@tapflowio/relay 0.26.1 → 0.27.0

package/dist/RelayServer.d.ts

@@ -128,6 +128,9 @@ export declare class RelayServer {
     private readonly backpressureBytes;
     private readonly screenshotTimeoutMs;
     private readonly agentGraceMs;
+    /** How long a tracked boot lives without an answer. An option so tests can shrink the
+     *  180s horizon; production always takes the default. */
+    private readonly pendingBootTtlMs;
     private readonly corsAllowed;
     private warnedProxyMisconfig;
     /** Agent identities already warned about a missing `build-download`. See `warnLegacyInstaller`. */
@@ -136,6 +139,39 @@ export declare class RelayServer {
     private pendingScreenshots;
     private readonly uiTreeTimeoutMs;
     private pendingUITrees;
+    /**
+     * 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.
+     */
+    private readonly shutdownRequesters;
+    /**
+     * 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.
+     */
+    private readonly pendingBoots;
     constructor(options: {
         port: number;
         publicDir?: string;
@@ -151,6 +187,7 @@ export declare class RelayServer {
             key: string;
         };
         agentGraceMs?: number;
+        pendingBootTtlMs?: number;
         tunnel?: TunnelRuntime;
         tunnelPort?: number;
     });
@@ -324,6 +361,15 @@ export declare 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.
      */
+    private rememberShutdownRequester;
+    /** Hands the agent's answer to whoever asked for it, when that is not the holder — who already has it. */
+    private answerShutdownRequester;
+    /**
+     * 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.
+     */
+    private settleShutdownRequesters;
+    private forgetShutdownRequesters;
     private sendTo;
     /**
      * Settle every in-flight screenshot / UI-tree request belonging to these sessions. Both callers
@@ -332,6 +378,32 @@ export declare class RelayServer {
      * timeout, minutes later, having told the caller nothing in between.
      */
     private rejectPending;
+    private bootKey;
+    /** Record a boot against the agent socket it was dispatched to. The door guarantees both ids. */
+    private rememberBoot;
+    /** The one way an entry leaves: every removal path funnels through here so no timer survives it. */
+    private forgetBoot;
+    /**
+     * 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.
+     */
+    private settleBoot;
+    /**
+     * 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.
+     */
+    private invalidateBootsFor;
+    /**
+     * 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.
+     */
+    private forgetEvictedBoots;
     /**
      * 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

package/dist/RelayServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RelayServer.d.ts","sourceRoot":"","sources":["../src/RelayServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RelayServer.d.ts","sourceRoot":"","sources":["../src/RelayServer.ts"],"names":[],"mappings":"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"}

package/dist/RelayServer.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)
@@ -757,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
@@ -1024,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))
@@ -1237,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);
                 }
@@ -1321,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));
@@ -1336,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': {
@@ -1344,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;
@@ -1397,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': {
@@ -1436,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;
@@ -1478,6 +1570,7 @@ export class RelayServer {
                     });
                     break;
                 }
+                this.rememberShutdownRequester(ws, target.session.id, msg.requestId);
                 target.session.agentSocket.send(JSON.stringify(msg));
                 break;
             }
@@ -1643,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;
@@ -1665,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
@@ -1739,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:
@@ -1755,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);
         }
@@ -1788,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)
@@ -1807,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.
@@ -1817,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
@@ -1833,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);
             }
@@ -1855,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
@@ -1882,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 &&
@@ -2002,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)();
         }
     }
@@ -2364,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 ` +
@@ -2668,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');