@tapflowio/relay 0.26.1 → 0.27.1

package/dist/RelayServer.js

@@ -10,7 +10,7 @@ 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_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 { isTunnelIngress, markTunnelIngress, proxiedWithoutForwardedFor, resolveClientAddress, resolveRequestClient } from './lib/clientAddress.js';
 import { BuildTicketStore } from './lib/buildTickets.js';
 import { resolveBuildFile } from './lib/buildFiles.js';
 import { resolveCorsHeaders } from './lib/cors.js';
@@ -22,7 +22,8 @@ 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 { acquireLoopStallWatch } from '@tapflowio/agent-core/utils';
 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 +172,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;
@@ -201,6 +215,15 @@ export class RelayServer {
     purgeBuildsTimer = null;
     flushResourcesTimer = null;
     heartbeatTimer = null;
+    /** When the last heartbeat sweep ran, by the same clock `isAlive` judges with. */
+    lastSweepAt = 0;
+    /** Names agents give at registration, kept apart from the session map so an agent with no sessions
+     *  can still be named when its socket goes. */
+    agentNames = new WeakMap();
+    releaseStallWatch = null;
+    /** Agent sockets whose close was already explained — ended by a sweep, or replaced by the same agent
+     *  registering again — so the close handler does not log them as a fresh drop. */
+    explainedCloses = new WeakMap();
     /**
      * When each socket last answered a ping. WeakMap → no manual cleanup on close (GC handles it).
      *
@@ -278,15 +301,52 @@ 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;
+    warnedTrustedProxyWithoutXff = false;
     /** Agent identities already warned about a missing `build-download`. See `warnLegacyInstaller`. */
     warnedLegacyInstaller = new Set();
     buildTickets = new BuildTicketStore();
     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 +371,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.
@@ -476,8 +537,17 @@ export class RelayServer {
         this.purgeBuildsTimer.unref();
         this.flushResourcesTimer = setInterval(() => this.flushResourceBuffers(), 60_000);
         this.flushResourcesTimer.unref();
-        this.heartbeatTimer = setInterval(() => this.runHeartbeat(), HEARTBEAT_MS);
+        this.lastSweepAt = Date.now();
+        this.heartbeatTimer = setInterval(() => { this.noteLateSweep(); this.runHeartbeat(); }, HEARTBEAT_MS);
         this.heartbeatTimer.unref();
+        this.releaseStallWatch ??= acquireLoopStallWatch();
+        // The rule a proxy has to follow, said once to whoever set the list: the case it covers (a proxy that
+        // sends no forwarding header at all) is one no request-time check can see.
+        const trustedProxies = this.options.trustedProxies ?? [];
+        if (trustedProxies.length > 0) {
+            logger.info(`Trusted proxies: ${trustedProxies.join(', ')}. A request from one of these without ` +
+                'X-Forwarded-For is treated as coming from that address itself, so the proxy must send X-Forwarded-For.');
+        }
         return new Promise((resolve, reject) => {
             this.httpServer.once('error', (err) => {
                 if (err.code === 'EADDRINUSE') {
@@ -536,6 +606,8 @@ export class RelayServer {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
+        this.releaseStallWatch?.();
+        this.releaseStallWatch = null;
         // `unref()` would not do: the test runner's process outlives the server, so an un-cleared hold
         // still fires — against a server that has already stopped.
         this.stopping = true;
@@ -550,6 +622,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)
@@ -607,14 +686,42 @@ export class RelayServer {
     // interval, whatever path the change took. `onAuthChanged` is the same check run early.
     runHeartbeat(clients = this.wss.clients) {
         this.revalidateSockets(clients);
+        // Agents one line each; everything else summed, because a relay waking from sleep finds every socket
+        // stale at once and one line per browser tab would push the agent lines out of the log buffer.
+        const others = new Map();
         for (const ws of clients) {
             if (!this.isAlive(ws)) {
+                const role = this.wsRoles.get(ws);
+                if (role === 'agent') {
+                    this.pushLog(`heartbeat terminated agent ${this.agentNames.get(ws) ?? 'unknown'} — last pong ${this.pongAgeSeconds(ws)}s ago`);
+                    this.explainedCloses.set(ws, 'terminated');
+                }
+                else {
+                    const key = role ?? 'unregistered';
+                    others.set(key, (others.get(key) ?? 0) + 1);
+                }
                 ws.terminate();
                 continue;
             }
             if (ws.readyState === WebSocket.OPEN)
                 ws.ping();
         }
+        if (others.size > 0) {
+            this.pushLog(`heartbeat terminated ${[...others].map(([role, n]) => `${n} ${role}`).join(', ')} socket(s)`);
+        }
+    }
+    /** A sweep that runs late means this process was held, or the machine slept: the pongs it judges were
+     *  never read, so its terminations say nothing about the clients. Same clock as `isAlive`. */
+    noteLateSweep(now = Date.now()) {
+        const late = now - this.lastSweepAt - HEARTBEAT_MS;
+        if (late > HEARTBEAT_MS / 2) {
+            this.pushLog(`heartbeat sweep ran ${Math.round(late / 1000)}s late — the relay was stalled or the system slept; this sweep may end sockets that were alive`);
+        }
+        this.lastSweepAt = now;
+    }
+    pongAgeSeconds(ws) {
+        const at = this.lastPongAt.get(ws);
+        return at === undefined ? '?' : Math.round((Date.now() - at) / 1000);
     }
     /**
      * Injected into the handlers whose write can take access away — member update and removal, token
@@ -757,6 +864,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
@@ -833,6 +947,24 @@ export class RelayServer {
     remoteAddressOf(request) {
         return request.socket.remoteAddress ?? '';
     }
+    /**
+     * Called on both doors — the WebSocket upgrade and every HTTP request — since `auth/init` and the logs
+     * route decide locality on the HTTP side. Not on the tunnel listener, where every request is remote
+     * whatever it carries.
+     */
+    warnTrustedProxyWithoutXffOnce(request) {
+        if (this.warnedTrustedProxyWithoutXff || isTunnelIngress(request))
+            return;
+        const header = proxiedWithoutForwardedFor(this.remoteAddressOf(request), request.headers, this.options.trustedProxies ?? []);
+        if (!header)
+            return;
+        logger.warn(`A request from a trusted proxy (TAPFLOW_TRUSTED_PROXIES) carried ${header} but no X-Forwarded-For. ` +
+            'Without that header the relay cannot see the real client, so it treats the request as coming from the ' +
+            'proxy itself: local, and so unauthenticated, when that address is loopback. Configure the proxy to ' +
+            'send X-Forwarded-For. A proxy on this host can instead use the tunnel port, which is open only when a ' +
+            'tunnel is configured or TAPFLOW_TUNNEL_PORT names a port.');
+        this.warnedTrustedProxyWithoutXff = true;
+    }
     warnProxyMisconfigOnce(socketAddr, forwardedFor) {
         if (this.warnedProxyMisconfig)
             return;
@@ -842,12 +974,19 @@ export class RelayServer {
         if (a === '::1' || a.startsWith('127.')) {
             logger.warn('Received X-Forwarded-For from a loopback connection but TAPFLOW_TRUSTED_PROXIES is unset. ' +
                 'If a same-host reverse proxy or `tailscale serve` forwards to this port, every client it forwards is ' +
-                'treated as localhost (unauthenticated). Point it at the tunnel port instead (TAPFLOW_TUNNEL_PORT, ' +
-                'default 4001), or set TAPFLOW_TRUSTED_PROXIES so the real client IP is used.');
+                'treated as localhost (unauthenticated). Point it at the tunnel port instead (open only when a tunnel ' +
+                'is configured or TAPFLOW_TUNNEL_PORT names a port), or set TAPFLOW_TRUSTED_PROXIES so the real ' +
+                'client IP is used.');
             this.warnedProxyMisconfig = true;
         }
     }
     handleConnection(ws, request) {
+        // **First, before anything can return.** A frame that breaks the protocol makes `ws` emit `'error'` on
+        // this socket (a reset it handles itself), and an EventEmitter with no `'error'` listener throws: from
+        // inside `ws`'s receiver, with nothing above it to catch. One client could end the relay for everyone,
+        // signed in or not. `ws` closes the socket itself after emitting, so the `'close'` handler below still runs.
+        // Debug, not warn: any client can produce this at will, and the close is already logged where it matters.
+        ws.on('error', (err) => logger.debug(`WebSocket error: ${err.message}`));
         const socketAddr = this.remoteAddressOf(request);
         const xff = request.headers['x-forwarded-for'];
         const forwardedFor = Array.isArray(xff) ? xff[0] : xff;
@@ -855,6 +994,7 @@ export class RelayServer {
         // A proxy in front of the tunnel port adds the header too, and there it changes nothing about auth.
         if (!viaTunnel)
             this.warnProxyMisconfigOnce(socketAddr, forwardedFor);
+        this.warnTrustedProxyWithoutXffOnce(request);
         const { addr, isLocal } = resolveClientAddress({
             socketAddr,
             forwardedFor,
@@ -1021,9 +1161,22 @@ export class RelayServer {
                 logger.error(`route failed for ${inbound.msg.type}:`, e);
             }
         });
-        ws.on('close', () => {
+        ws.on('close', (code, reason) => {
+            // Not while stopping: the relay ending every socket itself says nothing about the agents.
+            if (this.wsRoles.get(ws) === 'agent' && !this.stopping) {
+                const name = this.agentNames.get(ws) ?? 'unknown';
+                const explained = this.explainedCloses.get(ws);
+                if (explained === 'replaced') {
+                    this.pushLog(`agent socket replaced: ${name} registered again on a new connection`);
+                }
+                else if (!explained) {
+                    const why = reason.length > 0 ? ` ${reason.toString()}` : '';
+                    this.pushLog(`agent socket closed: ${name} (code ${code}${why}, last pong ${this.pongAgeSeconds(ws)}s ago)`);
+                }
+            }
             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))
@@ -1237,7 +1390,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);
                 }
@@ -1321,6 +1479,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));
@@ -1336,6 +1498,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': {
@@ -1344,6 +1519,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;
@@ -1397,7 +1574,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': {
@@ -1436,6 +1613,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;
@@ -1478,6 +1658,7 @@ export class RelayServer {
                     });
                     break;
                 }
+                this.rememberShutdownRequester(ws, target.session.id, msg.requestId);
                 target.session.agentSocket.send(JSON.stringify(msg));
                 break;
             }
@@ -1643,6 +1824,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;
@@ -1665,6 +1898,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
@@ -1739,6 +2043,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:
@@ -1755,7 +2063,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);
         }
@@ -1788,6 +2099,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)
@@ -1807,16 +2122,19 @@ 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.
                 // The rebound sessions have already moved off `old`, so this no longer covers them.
                 this.evictAgentSocket(old, 'replaced');
+                this.explainedCloses.set(old, 'replaced');
                 old.terminate();
             }
         }
         // 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
@@ -1833,6 +2151,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);
             }
@@ -1855,6 +2174,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
@@ -1862,7 +2186,9 @@ export class RelayServer {
         // transition, matching the disconnect line in evictAgentSocket.
         // `||`, 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)`);
+        this.agentNames.set(ws, msg.agentName || msg.agentId || 'unknown');
+        // Through `pushLog` too, so `tapflow logs` shows an agent coming back after the line about it leaving.
+        this.pushLog(`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.
      *
@@ -1882,8 +2208,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 &&
@@ -2002,7 +2329,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)();
         }
     }
@@ -2364,7 +2691,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 ` +
@@ -2555,6 +2882,7 @@ export class RelayServer {
         this.resourceBuffers.clear();
     }
     async handleRequest(req, res) {
+        this.warnTrustedProxyWithoutXffOnce(req);
         const corsHeaders = resolveCorsHeaders(req.headers.origin, this.corsAllowed);
         if (corsHeaders) {
             for (const [k, v] of Object.entries(corsHeaders))
@@ -2668,6 +2996,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');