machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/relay-connection.mjs

@@ -1,18 +1,29 @@
 import WebSocket from "ws";
+import { performance } from "node:perf_hooks";
 import { classifyOperationalError } from "./log.mjs";
 import { proxyAgentForWebSocket } from "./network-proxy.mjs";
-
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
-const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75_000;
+import { RelayLiveness } from "./relay-liveness.mjs";
+import {
+  boundedPositiveInteger, classifyRelayTransportError, formatAttempts, formatDuration, normalizeWorkerUrl, redactUrl,
+  relayHttpStatusFromError, sanitizeCloseReason, terminateSocket, tracedTlsConnection,
+} from "./relay-connection-support.mjs";
+import {
+  APPLICATION_PROXY_ROUTE_SCOPE, preferredRelayCloseCategory, relayOutageFields, relayRecoveryFields, relayStatusSnapshot,
+} from "./relay-diagnostics.mjs";
+import {
+  acknowledgementMismatch, isSupersededClose, readinessMismatch, reconnectDelay, relayCloseCategory, relayCloseUserCause,
+  relayFatalMessage, relayOutageUserAction, relayServerErrorReconnectCategory, sanitizeProtocolErrorCode, welcomeMismatch,
+} from "./relay-connection-classification.mjs";
+export {
+  acknowledgementMismatch, isRelayReadyContext, isSupersededClose, readinessMismatch, reconnectDelay, relayCloseCategory,
+  relayOutageUserAction, relayServerErrorReconnectCategory, welcomeMismatch,
+} from "./relay-connection-classification.mjs";
 const DEFAULT_CONNECT_TIMEOUT_MS = 15_000;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10_000;
 const DEFAULT_READINESS_TIMEOUT_MS = 15_000;
 const DEFAULT_OUTAGE_WARN_AFTER_MS = 10_000;
 const DEFAULT_OUTAGE_WARN_REPEAT_MS = 60_000;
 const DEFAULT_OUTAGE_WARN_MAX_REPEAT_MS = 15 * 60_000;
-const MAX_CLOSE_REASON_CHARS = 128;
-const MAX_PROTOCOL_ERROR_CODE_CHARS = 64;
-
 const DEFAULT_SCHEDULER = Object.freeze({
   setTimeout: (callback, delay) => setTimeout(callback, delay),
   clearTimeout: (timer) => clearTimeout(timer),
@@ -35,13 +46,13 @@ export class RelayConnection {
     this.onFatal = typeof options.onFatal === "function" ? options.onFatal : () => {};
     this.WebSocketClass = options.WebSocketClass || WebSocket;
     this.scheduler = options.scheduler || DEFAULT_SCHEDULER;
-    this.now = typeof options.now === "function" ? options.now : Date.now;
+    this.now = typeof options.now === "function" ? options.now : () => performance.now();
+    this.wallNow = typeof options.wallNow === "function" ? options.wallNow : Date.now;
     this.reconnectDelay = typeof options.reconnectDelay === "function" ? options.reconnectDelay : reconnectDelay;
     this.proxyAgentForUrl = typeof options.proxyAgentForUrl === "function" ? options.proxyAgentForUrl : proxyAgentForWebSocket;
     this.networkRoute = "unresolved";
+    this.networkRouteScope = APPLICATION_PROXY_ROUTE_SCOPE;
     this.maxPayload = boundedPositiveInteger(options.maxPayload, 8 * 1024 * 1024);
-    this.heartbeatIntervalMs = boundedPositiveInteger(options.heartbeatIntervalMs, DEFAULT_HEARTBEAT_INTERVAL_MS);
-    this.heartbeatTimeoutMs = boundedPositiveInteger(options.heartbeatTimeoutMs, DEFAULT_HEARTBEAT_TIMEOUT_MS);
     this.connectTimeoutMs = boundedPositiveInteger(options.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
     this.handshakeTimeoutMs = boundedPositiveInteger(options.handshakeTimeoutMs, DEFAULT_HANDSHAKE_TIMEOUT_MS);
     this.readinessTimeoutMs = boundedPositiveInteger(options.readinessTimeoutMs, DEFAULT_READINESS_TIMEOUT_MS);
@@ -59,40 +70,71 @@ export class RelayConnection {
     this.readinessProbeDelivered = false;
     this.hasConnected = false;
     this.connectedAt = 0;
-    this.lastInboundAt = 0;
+    this.lastReadyInboundSilenceMs = 0;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
     this.connectTimer = null;
-    this.heartbeatTimer = null;
     this.handshakeTimer = null;
     this.readinessTimer = null;
     this.outageWarnTimer = null;
     this.outageStartedAt = 0;
+    this.outageStartedWallAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
     this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
+    this.outageCount = 0;
     this.lastCloseCategory = "connection_interrupted";
+    this.lastCloseCode = 0;
     this.lastTransportErrorClass = "";
+    this.lastDisconnectedAt = 0;
+    this.lastReadyAt = 0;
+    this.lastReadyWallAt = 0;
+    this.lastReadyDurationMs = 0;
+    this.lastReconnectDelayMs = 0;
+    this.nextReconnectAt = 0;
+    this.nextReconnectWallAt = 0;
+    this.connectAttemptStartedAt = null;
+    this.lastConnectDurationMs = 0;
+    this.lastConnectStage = "idle";
+    this.lastConnectHttpStatus = null;
     this.pendingCloseCategory = "";
     this.connectedOnce = null;
     this.connectedOnceResolve = null;
     this.connectedOnceReject = null;
     this.sessionGeneration = 0;
     this.activeSessionId = 0;
+    this.liveness = new RelayLiveness({
+      ...options,
+      scheduler: this.scheduler,
+      now: this.now,
+      logger: this.logger,
+      currentSocket: () => this.socket,
+      isActive: () => !this.closed && this.authenticated && this.isSocketOpen(this.socket),
+      sendApplicationHeartbeat: (_now, socket) => this.sendOnSocket(socket, { type: "heartbeat", ts: this.wallNow() }),
+      onTransportError: (error, socket) => {
+        this.lastTransportErrorClass = classifyRelayTransportError(error);
+        this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_transport_error");
+        this.logger.debug?.("remote relay transport ping failed", { error_class: this.lastTransportErrorClass });
+        terminateSocket(socket);
+      },
+      onTransportTimeout: ({ silentForMs, eventLoopLagMs }, socket) => {
+        if (!socket) return;
+        this.logger.debug?.("remote relay transport pong timed out", { silent_for_ms: silentForMs, event_loop_lag_ms: eventLoopLagMs });
+        this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_transport_timeout");
+        terminateSocket(socket);
+      },
+      onApplicationTimeout: ({ silentForMs, eventLoopLagMs }, socket) => {
+        if (!socket) return;
+        this.logger.debug?.("remote relay application heartbeat timed out", { silent_for_ms: silentForMs, event_loop_lag_ms: eventLoopLagMs });
+        this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_heartbeat_timeout");
+        terminateSocket(socket);
+      },
+    });
   }
 
   status() {
-    return {
-      authenticated: this.authenticated,
-      ready: this.ready,
-      readiness_probe_delivered: this.readinessProbeDelivered,
-      closed: this.closed,
-      network_route: this.networkRoute,
-      reconnect_attempt: this.reconnectAttempt,
-      outage_active: this.outageStartedAt > 0,
-      session_generation: this.sessionGeneration,
-    };
+    return relayStatusSnapshot(this, this.now());
   }
 
   currentSessionId() {
@@ -111,12 +153,15 @@ export class RelayConnection {
   }
 
   stop() {
+    const settlePendingStart = this.connectedOnceResolve;
+    this.connectedOnceResolve = null;
+    this.connectedOnceReject = null;
     this.closed = true;
     this.authenticated = false;
     this.ready = false;
     this.readinessProbeDelivered = false;
     this.activeSessionId = 0;
-    this.clearTimer("heartbeatTimer", "clearInterval");
+    this.liveness.stop();
     this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("readinessTimer", "clearTimeout");
@@ -125,10 +170,12 @@ export class RelayConnection {
     const socket = this.socket;
     this.socket = null;
     if (socket) {
-      try { socket.close(1000, "daemon shutdown"); } catch {}
+      try { socket.close(1000, "daemon shutdown"); }
+      catch { /* Relay shutdown state is already authoritative and the transport may have closed concurrently. */ }
     }
     this.resetOutage();
     this.reconnectAttempt = 0;
+    settlePendingStart?.(false);
   }
 
   send(value) {
@@ -140,7 +187,8 @@ export class RelayConnection {
     const sessionId = Number(expectedSessionId) || 0;
     if (!sessionId || sessionId !== this.activeSessionId) return { ok: false, reason: "session_ended" };
     if (!this.authenticated || !this.isSocketOpen(this.socket)) return { ok: false, reason: "transport_unavailable" };
-    if (!this.ready && value?.type !== "relay_probe_result") return { ok: false, reason: "transport_unavailable" };
+    const preReadyControl = ["relay_probe_result", "resume_calls_ack", "authority_revoke_ack"].includes(String(value?.type || ""));
+    if (!this.ready && !preReadyControl) return { ok: false, reason: "transport_unavailable" };
     if (!this.sendOnSocket(this.socket, value)) return { ok: false, reason: "send_failed" };
     if (value?.type === "relay_probe_result") this.readinessProbeDelivered = true;
     return { ok: true, reason: "sent" };
@@ -148,7 +196,7 @@ export class RelayConnection {
 
   interrupt(category = "relay_transport_error") {
     if (this.closed || !this.socket) return false;
-    this.pendingCloseCategory = String(category || "relay_transport_error");
+    this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, category);
     terminateSocket(this.socket);
     return true;
   }
@@ -163,16 +211,16 @@ export class RelayConnection {
       return false;
     }
     this.logger.debug?.("remote relay welcome received");
-    Promise.resolve(this.helloMessage(message)).then((hello) => {
+    Promise.resolve(this.helloMessage(message, this.status())).then((hello) => {
       if (this.socket !== socket || this.closed || this.authenticated) return;
-      if (!this.sendOnSocket(socket, hello)) this.failPermanently("relay_authentication_failed");
+      this.sendOnSocket(socket, hello);
     }).catch((error) => {
+      if (this.socket !== socket || this.closed || this.authenticated) return;
       this.logger.debug?.("could not create daemon authentication proof", { error_class: classifyOperationalError(error) });
       this.failPermanently("relay_authentication_failed");
     });
     return true;
   }
-
   acknowledge(message = {}) {
     const socket = this.socket;
     if (this.closed || this.authenticated || !this.isSocketOpen(socket)) return false;
@@ -188,13 +236,12 @@ export class RelayConnection {
     this.activeSessionId = this.sessionGeneration;
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.connectedAt = this.now();
-    this.lastInboundAt = this.connectedAt;
-    this.startHeartbeat();
+    this.liveness.start();
     this.clearTimer("readinessTimer", "clearTimeout");
     this.readinessTimer = this.scheduler.setTimeout(() => {
       if (this.socket !== socket || this.closed || this.ready) return;
       this.logger.debug?.("remote relay end-to-end readiness probe timed out", { timeout_ms: this.readinessTimeoutMs });
-      this.pendingCloseCategory = "relay_readiness_timeout";
+      this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_readiness_timeout");
       terminateSocket(socket);
     }, this.readinessTimeoutMs);
     this.readinessTimer?.unref?.();
@@ -218,17 +265,20 @@ export class RelayConnection {
     this.ready = true;
     this.clearTimer("readinessTimer", "clearTimeout");
     this.reconnectAttempt = 0;
+    this.lastReadyAt = this.now();
+    this.lastReadyWallAt = this.wallNow();
+    this.nextReconnectAt = 0;
+    this.nextReconnectWallAt = 0;
+    this.lastReconnectDelayMs = 0;
 
     if (!this.hasConnected) {
       this.logger.info?.("remote relay connected and end-to-end result delivery verified");
     } else if (this.outageStartedAt > 0) {
       const outageMs = Math.max(0, this.now() - this.outageStartedAt);
       if (this.outageNoticeEmitted) {
-        this.logger.info?.(`remote relay connection restored after ${formatDuration(outageMs)} (${formatAttempts(this.outageAttempts)})`);
-        this.logger.debug?.("remote relay outage recovery details", {
-          outage_seconds: roundSeconds(outageMs),
-          attempts: this.outageAttempts,
-        });
+        const recoveryFields = relayRecoveryFields(this, outageMs);
+        this.logger.warn?.(`remote relay connection restored after ${formatDuration(outageMs)} (${formatAttempts(this.outageAttempts)})`, recoveryFields);
+        this.logger.debug?.("remote relay outage recovery details", recoveryFields);
       } else {
         this.logger.debug?.("remote relay connection recovered after a brief interruption", {
           outage_ms: outageMs,
@@ -253,18 +303,18 @@ export class RelayConnection {
 
   handleServerError(message = {}) {
     const errorCode = sanitizeProtocolErrorCode(message?.error);
-    this.logger.debug?.("remote relay reported a protocol error", { error_code: errorCode });
-    if (errorCode === "daemon_hello_timeout" && !this.authenticated) {
-      const socket = this.socket;
-      if (this.closed || !socket) return true;
-      this.pendingCloseCategory = "relay_handshake_timeout";
-      terminateSocket(socket);
-      return true;
-    }
-    if (errorCode === "daemon_ready_timeout" && this.authenticated && !this.ready) {
+    const reconnectCategory = relayServerErrorReconnectCategory(errorCode, {
+      authenticated: this.authenticated,
+      ready: this.ready,
+    });
+    this.logger.debug?.(
+      reconnectCategory ? "remote relay requested connection recovery" : "remote relay reported a protocol error",
+      { error_code: errorCode, reconnect_category: reconnectCategory || "none" },
+    );
+    if (reconnectCategory) {
       const socket = this.socket;
       if (this.closed || !socket) return true;
-      this.pendingCloseCategory = "relay_readiness_timeout";
+      this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, reconnectCategory);
       terminateSocket(socket);
       return true;
     }
@@ -275,26 +325,36 @@ export class RelayConnection {
   connect() {
     if (this.closed || this.socket) return;
     const wsUrl = `${this.workerUrl.replace(/^http/i, "ws")}/daemon/ws`;
+    this.connectAttemptStartedAt = this.now();
+    this.lastConnectStage = "socket_constructing";
+    this.lastConnectHttpStatus = null;
     this.logger.debug?.("connecting to remote relay", { endpoint: redactUrl(wsUrl), attempt: this.reconnectAttempt + 1 });
     let socket;
     try {
       const proxy = this.proxyAgentForUrl(wsUrl);
       const headers = this.connectionHeaders();
       if (!headers || typeof headers !== "object" || Array.isArray(headers)) throw new Error("relay connection headers are invalid");
-      this.networkRoute = proxy?.agent ? "proxy" : "direct";
+      this.networkRoute = proxy?.agent ? "application-http-proxy" : "system-network-stack";
+      this.lastConnectStage = proxy?.agent ? "proxy_connecting" : "tcp_connecting";
       socket = new this.WebSocketClass(wsUrl, {
         headers,
         maxPayload: this.maxPayload,
         ...(proxy?.agent ? { agent: proxy.agent } : {}),
+        ...(!proxy?.agent && this.WebSocketClass === WebSocket ? {
+          createConnection: tracedTlsConnection((stage) => this.observeConnectStage(stage)),
+        } : {}),
       });
       this.logger.debug?.("remote relay network route selected", { route: this.networkRoute });
     } catch (error) {
       if (error?.code === "relay_proxy_configuration") {
-        this.networkRoute = "invalid-proxy-configuration";
+        this.networkRoute = "invalid-application-proxy-configuration";
         this.failPermanently("relay_proxy_configuration");
         return;
       }
       this.lastTransportErrorClass = classifyRelayTransportError(error);
+      this.lastCloseCode = 0;
+      this.lastDisconnectedAt = this.wallNow();
+      this.finishConnectAttempt();
       this.logger.debug?.("remote relay connection could not be created", { error_class: this.lastTransportErrorClass });
       this.scheduleReconnect("connection_interrupted");
       return;
@@ -304,7 +364,8 @@ export class RelayConnection {
     this.connectTimer = this.scheduler.setTimeout(() => {
       if (this.socket !== socket || this.closed || this.isSocketOpen(socket)) return;
       this.logger.debug?.("remote relay transport connection timed out", { timeout_ms: this.connectTimeoutMs });
-      this.pendingCloseCategory = "relay_connect_timeout";
+      this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_connect_timeout");
+      this.finishConnectAttempt();
       terminateSocket(socket);
     }, this.connectTimeoutMs);
     this.connectTimer?.unref?.();
@@ -312,16 +373,18 @@ export class RelayConnection {
     socket.on("open", () => {
       this.clearTimer("connectTimer", "clearTimeout");
       if (this.socket !== socket || this.closed) {
-        try { socket.close(1000, "stale daemon connection"); } catch {}
+        try { socket.close(1000, "stale daemon connection"); }
+        catch { /* Stale transport ownership has already been rejected; concurrent close is harmless. */ }
         return;
       }
-      this.lastInboundAt = this.now();
       this.logger.debug?.("remote relay transport opened; awaiting device challenge");
+      this.observeConnectStage("websocket_open");
+      this.finishConnectAttempt();
       this.clearTimer("handshakeTimer", "clearTimeout");
       this.handshakeTimer = this.scheduler.setTimeout(() => {
         if (this.socket !== socket || this.closed || this.ready) return;
         this.logger.debug?.("remote relay authentication acknowledgement timed out", { timeout_ms: this.handshakeTimeoutMs });
-        this.pendingCloseCategory = "relay_handshake_timeout";
+        this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_handshake_timeout");
         terminateSocket(socket);
       }, this.handshakeTimeoutMs);
       this.handshakeTimer?.unref?.();
@@ -329,12 +392,13 @@ export class RelayConnection {
 
     socket.on("message", (data) => {
       if (this.socket !== socket || this.closed) return;
-      this.lastInboundAt = this.now();
+      this.liveness.observeApplicationInbound();
       // Bind results to the generation that received this message.
       const relayContext = {
         sessionId: this.activeSessionId,
         authenticated: this.authenticated === true,
         ready: this.ready === true,
+        transport: "websocket",
       };
       try {
         const outcome = this.onMessage(data, relayContext);
@@ -346,25 +410,37 @@ export class RelayConnection {
       }
     });
 
+    socket.on("pong", () => {
+      if (this.socket !== socket || this.closed) return;
+      this.liveness.observeInbound();
+    });
+
     socket.on("close", (code, reason) => {
       if (this.socket !== socket) return;
       const wasReady = this.ready;
       const wasAuthenticated = this.authenticated;
+      const readyInboundSilenceMs = this.liveness.silenceMs(this.now());
       this.socket = null;
       this.authenticated = false;
       this.ready = false;
       this.readinessProbeDelivered = false;
       this.activeSessionId = 0;
+      this.liveness.stop();
       this.clearTimer("connectTimer", "clearTimeout");
-      this.clearTimer("heartbeatTimer", "clearInterval");
       this.clearTimer("handshakeTimer", "clearTimeout");
       this.clearTimer("readinessTimer", "clearTimeout");
       const reasonText = sanitizeCloseReason(reason);
       const category = this.pendingCloseCategory || relayCloseCategory(code, reasonText);
       this.pendingCloseCategory = "";
-      const connectedForMs = wasAuthenticated && this.connectedAt > 0 ? Math.max(0, this.now() - this.connectedAt) : 0;
+      if (category !== "relay_transport_error") this.lastTransportErrorClass = "";
+      const disconnectedAt = this.now();
+      const connectedForMs = wasAuthenticated && this.connectedAt > 0 ? Math.max(0, disconnectedAt - this.connectedAt) : 0;
+      if (wasReady) this.lastReadyInboundSilenceMs = readyInboundSilenceMs;
+      this.lastDisconnectedAt = this.wallNow();
+      if (wasReady && this.lastReadyAt > 0) this.lastReadyDurationMs = Math.max(0, disconnectedAt - this.lastReadyAt);
+      this.lastCloseCode = Number(code) || 0;
       this.logger.debug?.("remote relay transport closed", {
-        close_code: Number(code) || 0,
+        close_code: this.lastCloseCode,
         close_reason: reasonText || "<none>",
         category,
         ready: wasReady,
@@ -387,10 +463,10 @@ export class RelayConnection {
         this.clearTimer("reconnectTimer", "clearTimeout");
         this.clearTimer("outageWarnTimer", "clearTimeout");
         this.logger.warn?.("daemon connection was replaced by a newer verified instance");
-        queueMicrotask(() => {
-          try { this.onSuperseded(); } catch (error) {
-            this.logger.error?.("daemon superseded callback failed", { error_class: classifyOperationalError(error) });
-          }
+        queueMicrotask(async () => {
+          try {
+            await this.onSuperseded();
+          } catch (error) { this.logger.error?.("daemon superseded callback failed", { error_class: classifyOperationalError(error) }); }
         });
         return;
       }
@@ -402,12 +478,18 @@ export class RelayConnection {
     socket.on("error", (error) => {
       if (this.socket !== socket || this.closed) return;
       this.lastTransportErrorClass = classifyRelayTransportError(error);
+      const httpStatus = relayHttpStatusFromError(error);
+      if (httpStatus) {
+        this.lastConnectStage = "http_rejected";
+        this.lastConnectHttpStatus = httpStatus;
+      }
+      this.finishConnectAttempt();
       this.logger.debug?.("remote relay transport error", { error_class: this.lastTransportErrorClass });
       if (this.lastTransportErrorClass === "authentication_failed") {
         this.failPermanently("relay_authentication_failed");
         return;
       }
-      this.pendingCloseCategory = "relay_transport_error";
+      this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_transport_error");
       terminateSocket(socket);
     });
   }
@@ -420,9 +502,9 @@ export class RelayConnection {
     this.ready = false;
     this.readinessProbeDelivered = false;
     this.activeSessionId = 0;
+    this.liveness.stop();
     this.socket = null;
     this.clearTimer("connectTimer", "clearTimeout");
-    this.clearTimer("heartbeatTimer", "clearInterval");
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.clearTimer("readinessTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
@@ -446,21 +528,33 @@ export class RelayConnection {
     }
     this.logger.error?.(message);
     this.logger.debug?.("remote relay fatal details", { category, cause: relayCloseUserCause(category) });
-    queueMicrotask(() => {
-      try { this.onFatal(error); } catch (callbackError) {
-        this.logger.error?.("relay fatal callback failed", { error_class: classifyOperationalError(callbackError) });
-      }
+    queueMicrotask(async () => {
+      try {
+        await this.onFatal(error);
+      } catch (callbackError) { this.logger.error?.("relay fatal callback failed", { error_class: classifyOperationalError(callbackError) }); }
     });
   }
 
   scheduleReconnect(category) {
     if (this.closed || this.reconnectTimer) return;
     this.recordOutage(category);
-    const delay = this.reconnectDelay(this.reconnectAttempt++);
+    const delay = this.reconnectDelay(this.reconnectAttempt++, Math.random, this.lastConnectDurationMs, this.connectTimeoutMs);
+    this.lastReconnectDelayMs = delay;
+    this.nextReconnectAt = this.now() + delay;
+    this.nextReconnectWallAt = this.wallNow() + delay;
     this.scheduleOutageWarning();
-    this.logger.debug?.("scheduling daemon reconnect", { delay_ms: delay, attempt: this.outageAttempts });
+    this.logger.debug?.("scheduling daemon reconnect", {
+      delay_ms: delay,
+      next_reconnect_at: new Date(this.nextReconnectWallAt).toISOString(),
+      attempt: this.outageAttempts,
+      close_category: this.lastCloseCategory,
+      network_route: this.networkRoute,
+      network_route_scope: this.networkRouteScope,
+    });
     this.reconnectTimer = this.scheduler.setTimeout(() => {
       this.reconnectTimer = null;
+      this.nextReconnectAt = 0;
+      this.nextReconnectWallAt = 0;
       this.connect();
     }, delay);
     this.reconnectTimer?.unref?.();
@@ -473,34 +567,19 @@ export class RelayConnection {
       return true;
     } catch (error) {
       this.lastTransportErrorClass = classifyRelayTransportError(error);
-      this.pendingCloseCategory = "relay_transport_error";
+      this.pendingCloseCategory = preferredRelayCloseCategory(this.pendingCloseCategory, "relay_transport_error");
       this.logger.debug?.("remote relay send failed", { error_class: this.lastTransportErrorClass });
       terminateSocket(socket);
       return false;
     }
   }
 
-  startHeartbeat() {
-    this.clearTimer("heartbeatTimer", "clearInterval");
-    this.heartbeatTimer = this.scheduler.setInterval(() => {
-      const socket = this.socket;
-      if (this.closed || !this.authenticated || !this.isSocketOpen(socket)) return;
-      const silentForMs = Math.max(0, this.now() - this.lastInboundAt);
-      if (silentForMs >= this.heartbeatTimeoutMs) {
-        this.logger.debug?.("remote relay heartbeat timed out", { silent_for_ms: silentForMs });
-        this.pendingCloseCategory = "relay_heartbeat_timeout";
-        terminateSocket(socket);
-        return;
-      }
-      this.sendOnSocket(socket, { type: "heartbeat", ts: this.now() });
-    }, this.heartbeatIntervalMs);
-    this.heartbeatTimer?.unref?.();
-  }
-
   recordOutage(category) {
     const now = this.now();
     if (this.outageStartedAt === 0) {
       this.outageStartedAt = now;
+      this.outageStartedWallAt = this.wallNow();
+      this.outageCount += 1;
       this.outageAttempts = 0;
       this.outageNoticeEmitted = false;
       this.lastOutageWarnAt = 0;
@@ -535,27 +614,22 @@ export class RelayConnection {
     this.outageWarningCount += 1;
     this.lastOutageWarnAt = this.now();
     const cause = relayCloseUserCause(this.lastCloseCategory);
-    const action = outageMs >= 5 * 60_000
-      ? " If this persists, check internet access and the deployed Worker."
-      : "";
-    this.logger.warn?.(`remote relay unavailable for ${formatDuration(outageMs)}; reconnecting automatically (${formatAttempts(this.outageAttempts)}; ${cause}).${action}`);
-    this.logger.debug?.("remote relay outage details", {
-      outage_seconds: roundSeconds(outageMs),
-      attempts: this.outageAttempts,
-      cause,
-      ...(this.lastTransportErrorClass ? { error_class: this.lastTransportErrorClass } : {}),
-    });
+    const action = relayOutageUserAction(this.lastCloseCategory, outageMs);
+    const outageFields = relayOutageFields(this, this.now(), cause);
+    this.logger.warn?.(`remote relay unavailable for ${formatDuration(outageMs)}; reconnecting automatically (${formatAttempts(this.outageAttempts)}; ${cause}).${action}`, outageFields);
+    this.logger.debug?.("remote relay outage details", outageFields);
   }
 
   resetOutage() {
     this.clearTimer("outageWarnTimer", "clearTimeout");
     this.outageStartedAt = 0;
+    this.outageStartedWallAt = 0;
     this.outageAttempts = 0;
     this.outageNoticeEmitted = false;
     this.outageWarningCount = 0;
     this.lastOutageWarnAt = 0;
-    this.lastCloseCategory = "connection_interrupted";
-    this.lastTransportErrorClass = "";
+    this.nextReconnectAt = 0;
+    this.nextReconnectWallAt = 0;
     this.pendingCloseCategory = "";
   }
 
@@ -569,182 +643,15 @@ export class RelayConnection {
   isSocketOpen(socket) {
     return Boolean(socket && socket.readyState === this.WebSocketClass.OPEN);
   }
-}
-
-export function relayCloseCategory(code, reason = "") {
-  const numeric = Number(code);
-  const reasonText = String(reason || "");
-  if (isSupersededClose(numeric, reasonText)) return "superseded";
-  if (numeric === 1008 && reasonText === "daemon hello timeout") return "relay_handshake_timeout";
-  if (numeric === 1008 && reasonText === "daemon ready timeout") return "relay_readiness_timeout";
-  if (numeric === 1008 && ["stale daemon candidate", "expired daemon candidate"].includes(reasonText)) return "relay_restarting_or_unavailable";
-  if (numeric === 1008 && ["daemon hello required", "missing daemon attachment", "invalid daemon candidate timestamp"].includes(reasonText)) return "relay_protocol_error";
-  if (numeric === 1000) return "normal_close";
-  if (numeric === 1001 || numeric === 1012 || numeric === 1013) return "relay_restarting_or_unavailable";
-  if (numeric === 1006) return "connection_interrupted";
-  if (numeric === 1002) return "relay_protocol_error";
-  if (numeric === 1007) return "invalid_transport_payload";
-  if (numeric === 1008) return "relay_policy_rejected";
-  if (numeric === 1009) return "message_too_large";
-  if (numeric === 1011) return "relay_internal_error";
-  return "unexpected_close";
-}
-
-function relayFatalMessage(category) {
-  if (category === "relay_protocol_mismatch") {
-    return "remote relay identity or version does not match this daemon; upgrade and redeploy both components";
-  }
-  if (category === "relay_protocol_error") {
-    return "remote relay protocol error; upgrade and redeploy both components, then restart the daemon";
-  }
-  if (category === "relay_proxy_configuration") {
-    return "remote relay proxy configuration is invalid; check HTTP_PROXY, HTTPS_PROXY, and NO_PROXY";
-  }
-  return "remote relay rejected the daemon connection; verify credentials or redeploy the Worker";
-}
-
-function relayCloseUserCause(category) {
-  const causes = {
-    connection_interrupted: "connection interrupted",
-    relay_restarting_or_unavailable: "relay restarting or temporarily unavailable",
-    relay_policy_rejected: "relay rejected the connection",
-    relay_internal_error: "relay internal error",
-    relay_protocol_mismatch: "relay identity or version mismatch",
-    relay_authentication_failed: "relay authentication failed",
-    relay_connect_timeout: "relay connection attempt timed out",
-    relay_handshake_timeout: "relay authentication acknowledgement timed out",
-    relay_readiness_timeout: "end-to-end relay readiness verification timed out",
-    relay_heartbeat_timeout: "relay stopped responding",
-    relay_transport_error: "relay transport error",
-    relay_protocol_error: "relay protocol error",
-    relay_proxy_configuration: "relay proxy configuration invalid",
-    invalid_transport_payload: "invalid transport payload",
-    message_too_large: "message exceeded the relay limit",
-    normal_close: "connection closed",
-    unexpected_close: "unexpected connection close",
-    superseded: "connection superseded",
-  };
-  return causes[String(category || "")] || "connection interrupted";
-}
-
-export function welcomeMismatch(message, expectedServer = "", expectedVersion = "") {
-  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_welcome";
-  if (message.type !== "welcome") return "unexpected_welcome_type";
-  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
-  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
-  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_welcome";
-  return "";
-}
-
-export function acknowledgementMismatch(message, expectedServer = "", expectedVersion = "") {
-  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_acknowledgement";
-  if (message.type !== "hello_ack") return "unexpected_acknowledgement_type";
-  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
-  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
-  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_acknowledgement";
-  return "";
-}
-
-export function readinessMismatch(message, expectedServer = "", expectedVersion = "") {
-  if (!message || typeof message !== "object" || Array.isArray(message)) return "invalid_readiness_acknowledgement";
-  if (message.type !== "ready_ack") return "unexpected_readiness_acknowledgement_type";
-  if (expectedServer && message.server !== expectedServer) return "server_identity_mismatch";
-  if (expectedVersion && message.version !== expectedVersion) return "server_version_mismatch";
-  if (typeof message.server !== "string" || !message.server || typeof message.version !== "string" || !message.version) return "incomplete_readiness_acknowledgement";
-  return "";
-}
-
-export function isRelayReadyContext(relayContext = {}, relay = null) {
-  if (relayContext?.ready === true) return true;
-  if (relayContext?.ready === false) return false;
-  return Number(relayContext?.sessionId) > 0 && relay?.status?.()?.ready === true;
-}
-
-export function isSupersededClose(code, reason) {
-  return Number(code) === 1012 && String(reason || "") === "replaced by verified daemon";
-}
 
-export function reconnectDelay(attempt, random = Math.random) {
-  const safeAttempt = Math.max(0, Number.isFinite(Number(attempt)) ? Number(attempt) : 0);
-  const base = Math.min(3000 * (2 ** Math.min(safeAttempt, 5)), 60_000);
-  return base + Math.floor(random() * 1000);
-}
-
-function normalizeWorkerUrl(value) {
-  let url;
-  try { url = new URL(String(value || "")); } catch { throw new Error("invalid Worker URL"); }
-  if (url.protocol !== "https:") throw new Error("Worker URL must use HTTPS");
-  if (url.username || url.password) throw new Error("Worker URL must not contain credentials");
-  if (url.pathname !== "/" || url.search || url.hash) throw new Error("Worker URL must be an origin without a path, query, or fragment");
-  return url.origin;
-}
-
-function sanitizeCloseReason(value) {
-  let text;
-  try { text = Buffer.isBuffer(value) ? value.toString("utf8") : String(value || ""); } catch { text = ""; }
-  return text.replace(/[\r\n\t\u0000-\u001f\u007f]/g, " ").trim().slice(0, MAX_CLOSE_REASON_CHARS);
-}
-
-function terminateSocket(socket) {
-  try {
-    if (typeof socket?.terminate === "function") socket.terminate();
-    else socket?.close?.();
-  } catch {}
-}
-
-function redactUrl(value) {
-  try {
-    const url = new URL(String(value));
-    return `${url.protocol}//${url.host}${url.pathname}`;
-  } catch {
-    return "<relay-url>";
+  observeConnectStage(stage) {
+    if (!Number.isFinite(this.connectAttemptStartedAt)) return;
+    this.lastConnectStage = String(stage || "socket_constructing");
   }
-}
-
-function classifyRelayTransportError(error) {
-  const directStatus = Number(error?.statusCode ?? error?.response?.statusCode);
-  if (directStatus === 401 || directStatus === 403) return "authentication_failed";
-  const match = /^Unexpected server response: (\d{3})$/.exec(String(error?.message || ""));
-  if (match && [401, 403].includes(Number(match[1]))) return "authentication_failed";
-  return classifyOperationalError(error);
-}
-
-function boundedPositiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
-}
-
-function sanitizeProtocolErrorCode(value) {
-  const code = String(value || "unknown_error").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_PROTOCOL_ERROR_CODE_CHARS);
-  return code || "unknown_error";
-}
 
-function formatAttempts(value) {
-  const attempts = Math.max(1, Math.floor(Number(value) || 1));
-  return `${attempts} reconnect attempt${attempts === 1 ? "" : "s"}`;
-}
-
-function formatDuration(milliseconds) {
-  let seconds = Math.max(1, Math.round(Number(milliseconds) / 1000));
-  const units = [
-    ["day", 86_400],
-    ["hour", 3_600],
-    ["minute", 60],
-    ["second", 1],
-  ];
-  const parts = [];
-  for (const [label, size] of units) {
-    if (seconds < size && parts.length === 0) continue;
-    const amount = Math.floor(seconds / size);
-    if (amount > 0) {
-      parts.push(`${amount} ${label}${amount === 1 ? "" : "s"}`);
-      seconds -= amount * size;
-    }
-    if (parts.length === 2) break;
+  finishConnectAttempt() {
+    if (!Number.isFinite(this.connectAttemptStartedAt)) return;
+    this.lastConnectDurationMs = Math.max(0, this.now() - this.connectAttemptStartedAt);
+    this.connectAttemptStartedAt = null;
   }
-  return parts.join(" ") || "1 second";
-}
-
-function roundSeconds(milliseconds) {
-  return Math.max(1, Math.round(milliseconds / 1000));
 }