machine-bridge-mcp 1.2.2 → 1.2.6

package/src/local/relay-connection.mjs

@@ -6,6 +6,7 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
 const DEFAULT_HEARTBEAT_TIMEOUT_MS = 75_000;
 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;
@@ -43,6 +44,7 @@ export class RelayConnection {
     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);
     this.outageWarnAfterMs = boundedPositiveInteger(options.outageWarnAfterMs, DEFAULT_OUTAGE_WARN_AFTER_MS);
     this.outageWarnRepeatMs = boundedPositiveInteger(options.outageWarnRepeatMs, DEFAULT_OUTAGE_WARN_REPEAT_MS);
     this.outageWarnMaxRepeatMs = Math.max(
@@ -52,7 +54,9 @@ export class RelayConnection {
 
     this.closed = true;
     this.socket = null;
+    this.authenticated = false;
     this.ready = false;
+    this.readinessProbeDelivered = false;
     this.hasConnected = false;
     this.connectedAt = 0;
     this.lastInboundAt = 0;
@@ -61,6 +65,7 @@ export class RelayConnection {
     this.connectTimer = null;
     this.heartbeatTimer = null;
     this.handshakeTimer = null;
+    this.readinessTimer = null;
     this.outageWarnTimer = null;
     this.outageStartedAt = 0;
     this.outageAttempts = 0;
@@ -79,7 +84,9 @@ export class RelayConnection {
 
   status() {
     return {
+      authenticated: this.authenticated,
       ready: this.ready,
+      readiness_probe_delivered: this.readinessProbeDelivered,
       closed: this.closed,
       network_route: this.networkRoute,
       reconnect_attempt: this.reconnectAttempt,
@@ -89,7 +96,7 @@ export class RelayConnection {
   }
 
   currentSessionId() {
-    return this.ready ? this.activeSessionId : 0;
+    return this.authenticated ? this.activeSessionId : 0;
   }
 
   start() {
@@ -105,11 +112,14 @@ export class RelayConnection {
 
   stop() {
     this.closed = true;
+    this.authenticated = false;
     this.ready = false;
+    this.readinessProbeDelivered = false;
     this.activeSessionId = 0;
     this.clearTimer("heartbeatTimer", "clearInterval");
     this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("handshakeTimer", "clearTimeout");
+    this.clearTimer("readinessTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
     this.clearTimer("outageWarnTimer", "clearTimeout");
     const socket = this.socket;
@@ -129,10 +139,11 @@ export class RelayConnection {
   sendForSession(value, expectedSessionId) {
     const sessionId = Number(expectedSessionId) || 0;
     if (!sessionId || sessionId !== this.activeSessionId) return { ok: false, reason: "session_ended" };
-    if (!this.ready || !this.isSocketOpen(this.socket)) return { ok: false, reason: "transport_unavailable" };
-    return this.sendOnSocket(this.socket, value)
-      ? { ok: true, reason: "sent" }
-      : { ok: false, reason: "send_failed" };
+    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" };
+    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" };
   }
 
   interrupt(category = "relay_transport_error") {
@@ -144,7 +155,7 @@ export class RelayConnection {
 
   observeWelcome(message = {}) {
     const socket = this.socket;
-    if (this.closed || this.ready || !this.isSocketOpen(socket)) return false;
+    if (this.closed || this.authenticated || !this.isSocketOpen(socket)) return false;
     const mismatch = welcomeMismatch(message, this.expectedServer, this.expectedVersion);
     if (mismatch) {
       this.logger.debug?.("remote relay welcome rejected", { reason: mismatch });
@@ -157,26 +168,54 @@ export class RelayConnection {
 
   acknowledge(message = {}) {
     const socket = this.socket;
-    if (this.closed || this.ready || !this.isSocketOpen(socket)) return false;
+    if (this.closed || this.authenticated || !this.isSocketOpen(socket)) return false;
     const mismatch = acknowledgementMismatch(message, this.expectedServer, this.expectedVersion);
     if (mismatch) {
       this.logger.debug?.("remote relay acknowledgement rejected", { reason: mismatch });
       this.failPermanently("relay_protocol_mismatch");
       return false;
     }
-    this.ready = true;
+    this.authenticated = true;
+    this.readinessProbeDelivered = false;
     this.sessionGeneration += 1;
     this.activeSessionId = this.sessionGeneration;
     this.clearTimer("handshakeTimer", "clearTimeout");
     this.connectedAt = this.now();
     this.lastInboundAt = this.connectedAt;
-    this.reconnectAttempt = 0;
     this.startHeartbeat();
+    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";
+      terminateSocket(socket);
+    }, this.readinessTimeoutMs);
+    this.readinessTimer?.unref?.();
+    return true;
+  }
+
+  confirmReady(message = {}) {
+    const socket = this.socket;
+    if (this.closed || !this.authenticated || this.ready || !this.isSocketOpen(socket)) return false;
+    const mismatch = readinessMismatch(message, this.expectedServer, this.expectedVersion);
+    if (!mismatch && !this.readinessProbeDelivered) {
+      this.logger.debug?.("remote relay declared readiness before the end-to-end probe result was delivered");
+      this.failPermanently("relay_protocol_mismatch");
+      return false;
+    }
+    if (mismatch) {
+      this.logger.debug?.("remote relay readiness acknowledgement rejected", { reason: mismatch });
+      this.failPermanently("relay_protocol_mismatch");
+      return false;
+    }
+    this.ready = true;
+    this.clearTimer("readinessTimer", "clearTimeout");
+    this.reconnectAttempt = 0;
 
     if (!this.hasConnected) {
-      this.logger.info?.("remote relay connected");
+      this.logger.info?.("remote relay connected and end-to-end result delivery verified");
     } else if (this.outageStartedAt > 0) {
-      const outageMs = Math.max(0, this.connectedAt - this.outageStartedAt);
+      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", {
@@ -204,13 +243,20 @@ 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.ready) {
+    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 socket = this.socket;
+      if (this.closed || !socket) return true;
+      this.pendingCloseCategory = "relay_readiness_timeout";
+      terminateSocket(socket);
+      return true;
+    }
     this.failPermanently("relay_protocol_error");
     return true;
   }
@@ -272,8 +318,14 @@ export class RelayConnection {
     socket.on("message", (data) => {
       if (this.socket !== socket || this.closed) return;
       this.lastInboundAt = this.now();
+      // Bind results to the generation that received this message.
+      const relayContext = {
+        sessionId: this.activeSessionId,
+        authenticated: this.authenticated === true,
+        ready: this.ready === true,
+      };
       try {
-        const outcome = this.onMessage(data);
+        const outcome = this.onMessage(data, relayContext);
         if (outcome && typeof outcome.catch === "function") {
           outcome.catch((error) => this.logger.error?.("daemon message handler failed", { error_class: classifyOperationalError(error) }));
         }
@@ -285,16 +337,20 @@ export class RelayConnection {
     socket.on("close", (code, reason) => {
       if (this.socket !== socket) return;
       const wasReady = this.ready;
+      const wasAuthenticated = this.authenticated;
       this.socket = null;
+      this.authenticated = false;
       this.ready = false;
+      this.readinessProbeDelivered = false;
       this.activeSessionId = 0;
       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 = wasReady && this.connectedAt > 0 ? Math.max(0, this.now() - this.connectedAt) : 0;
+      const connectedForMs = wasAuthenticated && this.connectedAt > 0 ? Math.max(0, this.now() - this.connectedAt) : 0;
       this.logger.debug?.("remote relay transport closed", {
         close_code: Number(code) || 0,
         close_reason: reasonText || "<none>",
@@ -318,7 +374,7 @@ export class RelayConnection {
         this.closed = true;
         this.clearTimer("reconnectTimer", "clearTimeout");
         this.clearTimer("outageWarnTimer", "clearTimeout");
-        this.logger.warn?.("daemon connection was replaced by a newer authenticated instance");
+        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) });
@@ -348,12 +404,15 @@ export class RelayConnection {
     if (this.closed) return;
     const socket = this.socket;
     this.closed = true;
+    this.authenticated = false;
     this.ready = false;
+    this.readinessProbeDelivered = false;
     this.activeSessionId = 0;
     this.socket = null;
     this.clearTimer("connectTimer", "clearTimeout");
     this.clearTimer("heartbeatTimer", "clearInterval");
     this.clearTimer("handshakeTimer", "clearTimeout");
+    this.clearTimer("readinessTimer", "clearTimeout");
     this.clearTimer("reconnectTimer", "clearTimeout");
     this.clearTimer("outageWarnTimer", "clearTimeout");
     if (wasReady) {
@@ -413,7 +472,7 @@ export class RelayConnection {
     this.clearTimer("heartbeatTimer", "clearInterval");
     this.heartbeatTimer = this.scheduler.setInterval(() => {
       const socket = this.socket;
-      if (this.closed || !this.ready || !this.isSocketOpen(socket)) return;
+      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 });
@@ -505,6 +564,7 @@ export function relayCloseCategory(code, reason = "") {
   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";
@@ -541,6 +601,7 @@ function relayCloseUserCause(category) {
     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",
@@ -572,8 +633,23 @@ export function acknowledgementMismatch(message, expectedServer = "", expectedVe
   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 authenticated daemon";
+  return Number(code) === 1012 && String(reason || "") === "replaced by verified daemon";
 }
 
 export function reconnectDelay(attempt, random = Math.random) {

package/src/local/runtime.mjs

@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { lstat, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { RelayConnection } from "./relay-connection.mjs";
+import { isRelayReadyContext, RelayConnection } from "./relay-connection.mjs";
 import { ProcessSessionManager } from "./process-sessions.mjs";
 export { MAX_COMMAND_BYTES } from "./process-sessions.mjs";
 import { MCP_SUPPORTED_PROTOCOL_VERSIONS, normalizePolicy, PolicyGate, SERVER_NAME } from "./tools.mjs";
@@ -302,10 +302,13 @@ export class LocalRuntime {
       return;
     }
     if (this.handleRelayControlMessage(message)) return;
-    if (message.type !== "tool_call") {
-      this.handleRelayProtocolViolation("unexpected_server_message_type");
+    if (message.type === "relay_probe") {
+      if (isRelayReadyContext(relayContext, this.relay)) return this.handleRelayProtocolViolation("unexpected_relay_probe");
+      this.handleRelayProbe(message, relayContext);
       return;
     }
+    if (message.type !== "tool_call") return this.handleRelayProtocolViolation("unexpected_server_message_type");
+    if (!isRelayReadyContext(relayContext, this.relay)) return this.handleRelayProtocolViolation("tool_call_before_ready");
     await this.handleRelayToolCall(message, relayContext);
   }
 
@@ -318,6 +321,10 @@ export class LocalRuntime {
       this.relay?.acknowledge(message);
       return true;
     }
+    if (message.type === "ready_ack") {
+      this.relay?.confirmReady(message);
+      return true;
+    }
     if (message.type === "pong") return true;
     if (message.type === "error") {
       this.relay?.handleServerError(message);
@@ -338,6 +345,13 @@ export class LocalRuntime {
     this.logger.error?.("remote relay protocol error; upgrade and redeploy both components, then restart the daemon");
   }
 
+  handleRelayProbe(message, relayContext = {}) {
+    const id = typeof message?.id === "string" && /^probe_[A-Za-z0-9_-]{8,240}$/.test(message.id) ? message.id : "";
+    const relaySessionId = Number(relayContext.sessionId) || 0;
+    if (!id || !relaySessionId) return this.handleRelayProtocolViolation("invalid_relay_probe");
+    this.deliverRelayToolResult({ type: "relay_probe_result", id }, relaySessionId);
+  }
+
   async handleRelayToolCall(message, relayContext = {}) {
     const envelope = normalizeRelayToolCall(message);
     const relaySessionId = Number(relayContext.sessionId) || 0;
@@ -387,15 +401,21 @@ export class LocalRuntime {
   }
 
   deliverRelayToolResult(response, relaySessionId = 0) {
-    const outcome = this.relay?.sendForSession?.(response, relaySessionId)
-      || (this.send(response) ? { ok: true, reason: "sent" } : { ok: false, reason: "transport_unavailable" });
-    if (outcome.ok) return true;
-    const reason = String(outcome.reason || "transport_unavailable");
-    this.logger.event?.("debug", "relay.tool_result.discarded", {
-      call_id: shortCallId(response?.id), reason,
-    }, reason === "send_failed"
-      ? "Could not send a tool result because the relay transport failed"
-      : "Discarded a tool result because its relay session had ended");
+    const sessionId = Number(relaySessionId) || 0;
+    const outcome = this.relay?.sendForSession
+      ? this.relay.sendForSession(response, sessionId)
+      : (this.send(response) ? { ok: true, reason: "sent" } : { ok: false, reason: "transport_unavailable" });
+    if (outcome?.ok) return true;
+    const reason = String(outcome?.reason || "transport_unavailable");
+    const missingSession = reason === "session_ended" && sessionId <= 0;
+    this.logger.event?.(missingSession ? "error" : "debug", "relay.tool_result.discarded", {
+      call_id: shortCallId(response?.id), reason, relay_session_id: sessionId,
+      active_session_id: Number(this.relay?.currentSessionId?.() || 0),
+    }, missingSession
+      ? "Discarded a tool result because the relay session id was missing from the inbound tool_call context"
+      : reason === "send_failed"
+        ? "Could not send a tool result because the relay transport failed"
+        : "Discarded a tool result because its relay session had ended");
     if (reason === "send_failed") this.relay?.interrupt?.("relay_transport_error");
     return false;
   }
@@ -722,6 +742,7 @@ function createRelayConnection(runtime, { workerUrl, secret, expectedVersion, on
   });
 }
 
+
 function handleRelayData(runtime, data, relayContext = {}) {
   const raw = typeof data === "string" ? data : Buffer.from(data).toString("utf8");
   if (Buffer.byteLength(raw) > MAX_WS_MESSAGE_BYTES) {

package/src/worker/daemon-liveness.ts

@@ -0,0 +1,63 @@
+/**
+ * Worker-side authenticated daemon liveness.
+ *
+ * Local daemons heartbeat about every 25s and treat 75s of silence as half-open.
+ * The Worker must apply a symmetric bound: role=daemon + readyState=OPEN is not
+ * enough after Durable Object hibernation or a half-closed transport, because
+ * those sockets still look connected while tool_call never returns.
+ */
+export const DAEMON_LIVENESS_TIMEOUT_MS = 90_000;
+export const DAEMON_READY_TIMEOUT_MS = 15_000;
+
+export type DaemonRole = "candidate" | "probing" | "expired" | "daemon";
+
+export interface DaemonLivenessFields {
+  role?: DaemonRole | string;
+  connectedAt?: string;
+  lastSeenAt?: string;
+}
+
+export function daemonLastSeenMs(attachment: DaemonLivenessFields | undefined | null): number {
+  const raw = attachment?.lastSeenAt || attachment?.connectedAt || "";
+  return Date.parse(raw);
+}
+
+export function isLiveDaemonAttachment(
+  attachment: DaemonLivenessFields | undefined | null,
+  now = Date.now(),
+): boolean {
+  if (!attachment || attachment.role !== "daemon") return false;
+  const lastSeen = daemonLastSeenMs(attachment);
+  if (!Number.isFinite(lastSeen)) return false;
+  const age = now - lastSeen;
+  return age >= 0 && age <= DAEMON_LIVENESS_TIMEOUT_MS;
+}
+
+export function daemonLivenessDeadlineMs(attachment: DaemonLivenessFields | undefined | null): number {
+  const lastSeen = daemonLastSeenMs(attachment);
+  if (!Number.isFinite(lastSeen)) return Number.NaN;
+  return lastSeen + DAEMON_LIVENESS_TIMEOUT_MS;
+}
+
+export function daemonReadyDeadlineMs(attachment: DaemonLivenessFields | undefined | null): number {
+  if (!attachment || attachment.role !== "probing") return Number.NaN;
+  const connectedAt = Date.parse(attachment.connectedAt || "");
+  if (!Number.isFinite(connectedAt)) return Number.NaN;
+  return connectedAt + DAEMON_READY_TIMEOUT_MS;
+}
+
+export function withDaemonLastSeenAt<T extends DaemonLivenessFields>(
+  attachment: T,
+  lastSeenAt = new Date().toISOString(),
+): T & { lastSeenAt: string } {
+  return { ...attachment, lastSeenAt };
+}
+
+export const DAEMON_HELLO_TIMEOUT_MS = 10_000;
+
+export function isFreshDaemonCandidate(connectedAt: string, now = Date.now()): boolean {
+  const timestamp = Date.parse(connectedAt);
+  if (!Number.isFinite(timestamp)) return false;
+  const age = now - timestamp;
+  return age >= 0 && age <= DAEMON_HELLO_TIMEOUT_MS;
+}

package/src/worker/daemon-sockets.ts

@@ -0,0 +1,107 @@
+import { isLiveDaemonAttachment, withDaemonLastSeenAt, type DaemonRole } from "./daemon-liveness.ts";
+import { sanitizeMetadataText } from "./http.ts";
+import { sanitizeDaemonPolicy, sanitizeDaemonTools, type DaemonPolicy } from "./policy.ts";
+
+export interface DaemonAttachment {
+  role: DaemonRole;
+  connectedAt: string;
+  lastSeenAt?: string;
+  probeId?: string;
+  policy?: DaemonPolicy;
+  tools?: string[];
+}
+
+interface WebSocketContext {
+  getWebSockets(): WebSocket[];
+}
+
+export class DaemonSocketRegistry {
+  constructor(private readonly context: WebSocketContext) {}
+
+  attachment(socket: WebSocket): DaemonAttachment | undefined {
+    const raw = socket.deserializeAttachment();
+    if (!raw || typeof raw !== "object") return undefined;
+    const candidate = raw as Partial<DaemonAttachment>;
+    if (!["candidate", "probing", "expired", "daemon"].includes(String(candidate.role))) return undefined;
+    const policy = sanitizeDaemonPolicy(candidate.policy);
+    return {
+      role: candidate.role as DaemonRole,
+      connectedAt: sanitizeMetadataText(candidate.connectedAt, 64) ?? "",
+      lastSeenAt: sanitizeMetadataText(candidate.lastSeenAt, 64),
+      probeId: sanitizeProbeId(candidate.probeId),
+      policy,
+      tools: sanitizeDaemonTools(candidate.tools, policy),
+    };
+  }
+
+  readyAttachment(socket: WebSocket): DaemonAttachment | undefined {
+    const attachment = this.attachment(socket);
+    return attachment?.role === "daemon" ? attachment : undefined;
+  }
+
+  candidateSockets(): WebSocket[] { return this.openSockets("candidate"); }
+  probingSockets(): WebSocket[] { return this.openSockets("probing"); }
+  readyRoleSockets(): WebSocket[] { return this.openSockets("daemon").sort((left, right) => this.connectedAt(right) - this.connectedAt(left)); }
+  readySockets(now = Date.now()): WebSocket[] {
+    return this.readyRoleSockets().filter((socket) => isLiveDaemonAttachment(this.readyAttachment(socket), now));
+  }
+
+  nonReadySockets(): WebSocket[] {
+    return this.context.getWebSockets().filter((socket) => this.attachment(socket)?.role !== "daemon" && socket.readyState === WebSocket.OPEN);
+  }
+
+  beginCandidate(socket: WebSocket, connectedAt = new Date().toISOString()): void {
+    socket.serializeAttachment({ role: "candidate", connectedAt } satisfies DaemonAttachment);
+  }
+
+  beginProbe(socket: WebSocket, values: { connectedAt: string; probeId: string; policy: DaemonPolicy; tools: string[] }): void {
+    socket.serializeAttachment({
+      role: "probing",
+      connectedAt: values.connectedAt,
+      lastSeenAt: values.connectedAt,
+      probeId: values.probeId,
+      policy: values.policy,
+      tools: values.tools,
+    } satisfies DaemonAttachment);
+  }
+
+  promote(socket: WebSocket, lastSeenAt = new Date().toISOString()): DaemonAttachment | undefined {
+    const attachment = this.attachment(socket);
+    if (attachment?.role !== "probing") return undefined;
+    const ready = { ...attachment, role: "daemon" as const, lastSeenAt };
+    delete ready.probeId;
+    socket.serializeAttachment(ready satisfies DaemonAttachment);
+    return ready;
+  }
+
+  touch(socket: WebSocket, lastSeenAt = new Date().toISOString()): DaemonAttachment | undefined {
+    const attachment = this.attachment(socket);
+    if (!attachment || (attachment.role !== "probing" && attachment.role !== "daemon")) return undefined;
+    const touched = withDaemonLastSeenAt(attachment, lastSeenAt);
+    socket.serializeAttachment(touched satisfies DaemonAttachment);
+    return touched;
+  }
+
+  expire(socket: WebSocket): void {
+    const attachment = this.attachment(socket);
+    if (!attachment) return;
+    socket.serializeAttachment({
+      role: "expired",
+      connectedAt: attachment.connectedAt,
+      lastSeenAt: attachment.lastSeenAt,
+    } satisfies DaemonAttachment);
+  }
+
+  private openSockets(role: DaemonRole): WebSocket[] {
+    return this.context.getWebSockets().filter((socket) => this.attachment(socket)?.role === role && socket.readyState === WebSocket.OPEN);
+  }
+
+  private connectedAt(socket: WebSocket): number {
+    return Date.parse(this.attachment(socket)?.connectedAt ?? "") || 0;
+  }
+}
+
+function sanitizeProbeId(value: unknown): string | undefined {
+  if (typeof value !== "string" || !/^probe_[A-Za-z0-9_-]{8,240}$/.test(value)) return undefined;
+  return value;
+}