ds-harness-remote 0.4.0 → 0.4.1

package/dist/index.js

@@ -4111,9 +4111,22 @@ function normalizeSdpMLineIndex(value) {
     return null;
   return value;
 }
+function selectCapabilities(offered, supported) {
+  const offeredCapabilities = new Set(offered);
+  return [...new Set(supported)].filter((capability) => offeredCapabilities.has(capability));
+}
+function acceptNegotiatedCapabilities(offered, negotiated) {
+  const accepted = negotiated ?? ["transport.relay"];
+  if (selectCapabilities(accepted, offered).length !== accepted.length) {
+    throw new Error("Server selected a capability that the peer did not offer.");
+  }
+  return [...accepted];
+}
 var rpcMethodSchema = external_exports.enum(rpcMethods);
 var messageTypeSchema = external_exports.enum(messageTypes);
 var controlFrameTypeSchema = external_exports.enum(controlFrameTypes);
+var uniqueStrings = (values) => new Set(values).size === values.length;
+var uniqueNumbers = (values) => new Set(values).size === values.length;
 var remoteMessageSchema = external_exports.object({
   v: external_exports.literal(PROTOCOL_VERSION),
   id: external_exports.string().min(1),
@@ -4134,8 +4147,8 @@ var helloPayloadSchema = external_exports.object({
   role: external_exports.enum(["host", "client"]),
   deviceId: external_exports.string().min(1),
   accessToken: external_exports.string().min(1),
-  protocols: external_exports.array(external_exports.number().int()).min(1),
-  capabilities: external_exports.array(external_exports.string()),
+  protocols: external_exports.array(external_exports.number().int().nonnegative().safe()).min(1).refine(uniqueNumbers),
+  capabilities: external_exports.array(external_exports.string().min(1)).refine(uniqueStrings),
   clientVersion: external_exports.string().optional(),
   harnessVersion: external_exports.string().optional()
 });
@@ -4146,6 +4159,7 @@ var helloAckPayloadSchema = external_exports.object({
   heartbeatIntervalMs: external_exports.number().int().positive(),
   maxControlFrameBytes: external_exports.number().int().positive(),
   maxRelayFrameBytes: external_exports.number().int().positive(),
+  capabilities: external_exports.array(external_exports.string().min(1)).refine(uniqueStrings).optional(),
   webrtcEnabled: external_exports.boolean().optional(),
   webrtcFallbackTimeoutMs: external_exports.number().int().positive().optional()
 });
@@ -4177,7 +4191,7 @@ var secureHandshakePayloadSchema = external_exports.object({
 var relayPayloadSchema = external_exports.object({
   connectionId: external_exports.string().min(1),
   targetDeviceId: external_exports.string().min(1),
-  counter: external_exports.number().int().nonnegative(),
+  counter: external_exports.number().int().nonnegative().safe(),
   ciphertext: external_exports.string().min(1)
 });
 var signalPayloadSchema = external_exports.object({
@@ -4384,6 +4398,9 @@ function cryptoRandomId() {
   return `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
 }
 
+// ../client-core/dist/remote-gateway.js
+var DIRECT_REMOTE_CALL_BYTES = 2 * 1024 * 1024;
+
 // ../client-core/dist/index.js
 var RemoteClientError = class extends Error {
   code;
@@ -4925,6 +4942,8 @@ function isChunk(frame) {
 
 // ../webrtc/dist/rtc-data-channel.js
 var DEFAULT_NEGOTIATE_TIMEOUT_MS = 8e3;
+var SELECTED_PATH_RETRY_COUNT = 5;
+var SELECTED_PATH_RETRY_DELAY_MS = 50;
 var RtcDataChannelTransport = class {
   pc;
   role;
@@ -5254,7 +5273,11 @@ var RtcDataChannelTransport = class {
   }
   async resolveSelectedTransport() {
     try {
-      const selected = await this.refreshStatsDiagnostics();
+      let selected = await this.refreshStatsDiagnostics();
+      for (let attempt = 0; attempt < SELECTED_PATH_RETRY_COUNT && !this.closed && (selected.transport === void 0 || selected.mode === void 0); attempt += 1) {
+        await sleep(SELECTED_PATH_RETRY_DELAY_MS);
+        selected = await this.refreshStatsDiagnostics();
+      }
       this.selected = selected?.transport;
       this.selectedMode = selected?.mode;
       this.selectedPathTelemetry = selectedPathTelemetry(selected);
@@ -5418,6 +5441,8 @@ function inspectSelectedPath(stats) {
     const remote = candidates.get(String(pair.remoteCandidateId));
     const localType = local?.candidateType;
     const remoteType = remote?.candidateType;
+    const localAddressScope = summarizeAddress(candidateAddressValue(local)).addressScope;
+    const remoteAddressScope = summarizeAddress(candidateAddressValue(remote)).addressScope;
     let selected;
     if (localType === "relay" || remoteType === "relay")
       selected = { transport: "turn", mode: "TURN" };
@@ -5425,13 +5450,15 @@ function inspectSelectedPath(stats) {
       continue;
     selected ??= {
       transport: "p2p",
-      mode: localType === "host" && remoteType === "host" ? "LAN" : "P2P"
+      mode: isLanCandidatePair(localType, remoteType, localAddressScope, remoteAddressScope) ? "LAN" : "P2P"
     };
     const currentRoundTripTime = numberStat(pair, "currentRoundTripTime");
     return {
       ...selected,
       localCandidateType: stringStat(local, "candidateType"),
       remoteCandidateType: stringStat(remote, "candidateType"),
+      localAddressScope,
+      remoteAddressScope,
       localAddress: candidateAddress(local),
       remoteAddress: candidateAddress(remote),
       protocol: stringStat(local, "protocol") ?? stringStat(remote, "protocol"),
@@ -5556,6 +5583,19 @@ function candidateTypeStat(candidate) {
 function candidateAddressValue(candidate) {
   return stringStat(candidate, "address") ?? stringStat(candidate, "ip");
 }
+function isLanCandidatePair(localType, remoteType, localScope, remoteScope) {
+  if (localType === "host" && remoteType === "host")
+    return true;
+  const directTypes = /* @__PURE__ */ new Set(["host", "prflx"]);
+  if (!directTypes.has(String(localType)) || !directTypes.has(String(remoteType)))
+    return false;
+  if (isLocalNetworkScope(localScope) && isLocalNetworkScope(remoteScope))
+    return true;
+  return localType === "host" && isLocalNetworkScope(localScope) && remoteType === "prflx" && remoteScope === "unknown" || remoteType === "host" && isLocalNetworkScope(remoteScope) && localType === "prflx" && localScope === "unknown";
+}
+function isLocalNetworkScope(scope) {
+  return scope === "private" || scope === "link-local";
+}
 function increment(map, key) {
   map[key] = (map[key] ?? 0) + 1;
 }
@@ -5565,6 +5605,8 @@ function selectedPathTelemetry(details) {
     ...details.mode === void 0 ? {} : { mode: details.mode },
     ...details.localCandidateType === void 0 ? {} : { localCandidateType: details.localCandidateType },
     ...details.remoteCandidateType === void 0 ? {} : { remoteCandidateType: details.remoteCandidateType },
+    ...details.localAddressScope === void 0 ? {} : { localAddressScope: details.localAddressScope },
+    ...details.remoteAddressScope === void 0 ? {} : { remoteAddressScope: details.remoteAddressScope },
     ...details.protocol === void 0 ? {} : { protocol: details.protocol },
     ...details.relayProtocol === void 0 ? {} : { relayProtocol: details.relayProtocol },
     ...details.currentRoundTripTimeMs === void 0 ? {} : { currentRoundTripTimeMs: details.currentRoundTripTimeMs },
@@ -5609,6 +5651,7 @@ var AdaptiveTransport = class extends BaseTransport {
   handshakeTimer;
   webrtcEnabled = true;
   serverNegotiateTimeoutMs;
+  negotiatedCapabilities = ["transport.relay"];
   connectedAt;
   lastRtcDiagnostics;
   constructor(url, options) {
@@ -5687,6 +5730,8 @@ var AdaptiveTransport = class extends BaseTransport {
       controlChannelUrl: this.url,
       controlChannelState: socketState(this.socket?.readyState),
       preferredTransports: this.options.forceRelay === true ? ["relay"] : [...this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS],
+      negotiatedCapabilities: [...this.negotiatedCapabilities],
+      webRtcEnabled: this.webrtcEnabled,
       ...this.rtc === void 0 ? {} : { webRtc: await this.rtc.connectionDetails() }
     };
   }
@@ -5733,6 +5778,12 @@ var AdaptiveTransport = class extends BaseTransport {
         const payload = frame.payload;
         if (payload.protocol !== PROTOCOL_VERSION)
           throw new Error("Server selected an unsupported protocol version");
+        const offered = this.options.capabilities ?? DEFAULT_CAPABILITIES;
+        this.negotiatedCapabilities = acceptNegotiatedCapabilities(offered, payload.capabilities);
+        const preferredTransports = this.negotiatedTransports();
+        if (preferredTransports.length === 0) {
+          throw new Error("Server did not negotiate a supported transport capability");
+        }
         if (payload.webrtcEnabled === false)
           this.webrtcEnabled = false;
         if (typeof payload.webrtcFallbackTimeoutMs === "number" && Number.isSafeInteger(payload.webrtcFallbackTimeoutMs) && payload.webrtcFallbackTimeoutMs > 0) {
@@ -5740,7 +5791,7 @@ var AdaptiveTransport = class extends BaseTransport {
         }
         this.sendControl("connect.request", {
           hostDeviceId: this.options.targetDeviceId,
-          preferredTransports: this.options.forceRelay === true ? ["relay"] : this.options.preferredTransports ?? [...DEFAULT_PREFERRED_TRANSPORTS]
+          preferredTransports
         });
         return;
       }
@@ -5750,7 +5801,9 @@ var AdaptiveTransport = class extends BaseTransport {
           throw new Error("connect.accepted did not include a connectionId");
         }
         this.connectionId = payload.connectionId;
-        void this.negotiate();
+        void this.negotiate().catch((error) => {
+          this.failConnection(error instanceof Error ? error : new Error("Adaptive transport negotiation failed"));
+        });
         return;
       }
       if (frame.type === "connect.rejected" || frame.type === "error") {
@@ -5807,15 +5860,25 @@ var AdaptiveTransport = class extends BaseTransport {
   async negotiate() {
     if (this.connectionId === void 0)
       return;
-    const preferred = this.options.preferredTransports ?? [...DEFAULT_PREFERRED_TRANSPORTS];
+    const preferred = this.negotiatedTransports();
     const wantWebRtc = !this.options.forceRelay && this.webrtcEnabled && (preferred.includes("lan") || preferred.includes("p2p") || preferred.includes("turn"));
     let selected = "relay";
     this.lastRtcDiagnostics = void 0;
     if (wantWebRtc) {
       try {
         const rtcSelected = await this.tryWebRtc();
-        this.dataMode = "webrtc";
-        selected = rtcSelected;
+        if (!preferred.includes(rtcSelected)) {
+          await this.rtc?.close();
+          this.rtc = void 0;
+          if (!preferred.includes("relay")) {
+            throw new Error(`WebRTC selected unnegotiated transport: ${rtcSelected}`);
+          }
+          this.dataMode = "relay";
+          selected = "relay";
+        } else {
+          this.dataMode = "webrtc";
+          selected = rtcSelected;
+        }
       } catch (error) {
         const reason = error instanceof Error ? error : new Error("WebRTC negotiation failed.");
         try {
@@ -5824,10 +5887,14 @@ var AdaptiveTransport = class extends BaseTransport {
         }
         await this.rtc?.close();
         this.rtc = void 0;
+        if (!preferred.includes("relay"))
+          throw reason;
         this.dataMode = "relay";
         selected = "relay";
       }
     } else {
+      if (!preferred.includes("relay"))
+        throw new Error("No negotiated transport is available");
       this.dataMode = "relay";
       selected = "relay";
     }
@@ -5839,6 +5906,14 @@ var AdaptiveTransport = class extends BaseTransport {
     });
     this.finishConnection();
   }
+  negotiatedTransports() {
+    const preferred = this.options.forceRelay === true ? ["relay"] : this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS;
+    return preferred.filter((transport) => {
+      if (transport === "lan" || transport === "p2p")
+        return this.negotiatedCapabilities.includes("transport.p2p");
+      return this.negotiatedCapabilities.includes(`transport.${transport}`);
+    });
+  }
   async tryWebRtc() {
     const connectionId = this.connectionId;
     if (connectionId === void 0)
@@ -13470,8 +13545,8 @@ function base64ToBytes(value) {
 }
 
 // src/remote-typert-gateway.ts
-var DIRECT_REMOTE_CALL_BYTES = 2 * 1024 * 1024;
-var RemoteTypertGateway = class {
+var DIRECT_REMOTE_CALL_BYTES2 = 2 * 1024 * 1024;
+var RemoteTypertGateway2 = class {
   constructor(client) {
     this.client = client;
   }
@@ -13488,7 +13563,7 @@ var RemoteTypertGateway = class {
     const request = { endpoint, payload };
     const encoded = new TextEncoder().encode(JSON.stringify(request));
     let response;
-    if (encoded.byteLength > DIRECT_REMOTE_CALL_BYTES) {
+    if (encoded.byteLength > DIRECT_REMOTE_CALL_BYTES2) {
       response = await this.callTransferred(encoded, signal);
     } else {
       try {
@@ -13770,7 +13845,7 @@ function normalizeServerUrl(value) {
 }
 
 // src/version.ts
-var PLUGIN_VERSION = "0.4.0";
+var PLUGIN_VERSION = "0.4.1";
 
 // src/server-api.ts
 var HostServerApi = class {
@@ -14169,6 +14244,7 @@ function requireRecord(value, name2) {
 
 // src/typert-gateway-switch.ts
 var REMOTE_COMMAND_METHODS = ["execute", "list"];
+var LOCAL_ONLY_NAMESPACES = /* @__PURE__ */ new Set(["dynamicCordisRunner"]);
 var ALL_REMOTE_COMMANDS = { execute: true, list: true };
 var TypertGatewaySwitch = class {
   runtime;
@@ -14229,13 +14305,13 @@ var TypertGatewaySwitch = class {
     if (this.installed) return;
     this.runtime.invoke = (request) => this.selectInvoke(request);
     if (this.originalStream !== void 0) {
-      this.runtime.stream = (request) => this.remoteTarget === void 0 ? this.localStream(request) : this.remoteTarget.open(endpointOf(request), { args: request.args }, request.signal ?? new AbortController().signal);
+      this.runtime.stream = (request) => this.remoteTarget === void 0 || isLocalOnlyEndpoint(endpointOf(request)) ? this.localStream(request) : this.remoteTarget.open(endpointOf(request), { args: request.args }, request.signal ?? new AbortController().signal);
     }
     if (this.originalDispatch !== void 0) {
-      this.runtime.dispatchRpc = (endpoint, payload, signal) => this.remoteTarget === void 0 ? this.localDispatch(endpoint, payload, signal) : this.remoteTarget.dispatch(endpoint, payload, signal);
+      this.runtime.dispatchRpc = (endpoint, payload, signal) => this.remoteTarget === void 0 || isLocalOnlyEndpoint(endpoint) ? this.localDispatch(endpoint, payload, signal) : this.remoteTarget.dispatch(endpoint, payload, signal);
     }
     if (this.originalOpen !== void 0) {
-      this.runtime.openWireStream = (endpoint, payload, signal) => this.remoteTarget === void 0 ? this.localOpen(endpoint, payload, signal) : this.remoteTarget.open(endpoint, payload, signal);
+      this.runtime.openWireStream = (endpoint, payload, signal) => this.remoteTarget === void 0 || isLocalOnlyEndpoint(endpoint) ? this.localOpen(endpoint, payload, signal) : this.remoteTarget.open(endpoint, payload, signal);
     }
     this.installed = true;
   }
@@ -14262,6 +14338,7 @@ var TypertGatewaySwitch = class {
     this.installed = false;
   }
   selectInvoke(request) {
+    if (isLocalOnlyEndpoint(endpointOf(request))) return this.localInvoke(request);
     if (this.remoteTarget !== void 0) return this.remoteTarget.invoke(request);
     if (request.namespace !== "commands" || !isRemoteCommandMethod(request.method) || this.remoteInvoke === void 0) {
       return this.localInvoke(request);
@@ -14292,6 +14369,10 @@ function requestFromCarrier(endpoint, payload, signal) {
 function endpointOf(request) {
   return `${request.namespace}/${request.method}`;
 }
+function isLocalOnlyEndpoint(endpoint) {
+  const separator = endpoint.indexOf("/");
+  return separator > 0 && LOCAL_ONLY_NAMESPACES.has(endpoint.slice(0, separator));
+}
 function isRemoteCommandMethod(method) {
   return REMOTE_COMMAND_METHODS.includes(method);
 }
@@ -14305,7 +14386,7 @@ import { networkInterfaces } from "node:os";
 
 // src/native-rtc-helper.ts
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 var cachedExternalFactory;
@@ -14321,17 +14402,25 @@ async function loadExternalNativeRtcFactory() {
   cachedExternalFactory = buildExternalNativeRtcFactory(nodeBinary);
   return cachedExternalFactory;
 }
-function buildExternalNativeRtcFactory(nodeBinary, requireFrom = fileURLToPath(import.meta.url)) {
+function buildExternalNativeRtcFactory(nodeBinary, requireFrom = resolveNativeRtcRequireFrom()) {
   return {
     create(configuration) {
       return new ExternalNativePeerConnection(nodeBinary, requireFrom, configuration);
     }
   };
 }
+function resolveNativeRtcRequireFrom(moduleUrl = import.meta.url) {
+  const modulePath = fileURLToPath(moduleUrl);
+  try {
+    return realpathSync(modulePath);
+  } catch {
+    return modulePath;
+  }
+}
 function resolveExternalNodeBinaryForRtc() {
   if (cachedNodeBinaryResolved) return cachedNodeBinary;
   cachedNodeBinaryResolved = true;
-  const requireFrom = fileURLToPath(import.meta.url);
+  const requireFrom = resolveNativeRtcRequireFrom();
   for (const candidate of nodeBinaryCandidates()) {
     if (isUsableExternalNode(candidate, requireFrom)) {
       cachedNodeBinary = candidate;
@@ -15520,7 +15609,7 @@ var ClientModeRuntime = class {
   async listRemoteDirectory(targetDeviceId, path, signal) {
     const remote = await this.ensureConnected(targetDeviceId, signal);
     if (remote.features.remoteGateway) {
-      const value = await new RemoteTypertGateway(remote.client).invoke({
+      const value = await new RemoteTypertGateway2(remote.client).invoke({
         namespace: "directoryPicker",
         method: "list",
         args: path === void 0 ? {} : { path },
@@ -15538,7 +15627,7 @@ var ClientModeRuntime = class {
   async listRemoteWorkspaces(targetDeviceId, signal) {
     const remote = await this.ensureConnected(targetDeviceId, signal);
     if (remote.features.remoteGateway) {
-      return readRemoteWorkspaceBaseline(new RemoteTypertGateway(remote.client), signal);
+      return readRemoteWorkspaceBaseline(new RemoteTypertGateway2(remote.client), signal);
     }
     const api = new RemoteHarnessApiProxy(remote.client).api;
     const response = await api.workspace.list({
@@ -15554,7 +15643,7 @@ var ClientModeRuntime = class {
     this.assertRemoteCompatible(remote);
     let workspace;
     if (remote.features.remoteGateway) {
-      workspace = await new RemoteTypertGateway(remote.client).invoke({
+      workspace = await new RemoteTypertGateway2(remote.client).invoke({
         namespace: "workspace",
         method: "create",
         args: { request: { path } },
@@ -15605,7 +15694,7 @@ var ClientModeRuntime = class {
   selectRemoteTarget(remote) {
     const target = { deviceId: remote.target.deviceId, name: remote.target.name };
     if (this.gatewaySwitch.supportsCarrier()) {
-      this.gatewaySwitch.selectRemote(new RemoteTypertGateway(remote.client), void 0, target);
+      this.gatewaySwitch.selectRemote(new RemoteTypertGateway2(remote.client), void 0, target);
       return;
     }
     this.proxySwitch.selectRemote(new RemoteHarnessApiProxy(remote.client).api, target);
@@ -15634,6 +15723,11 @@ var ClientModeRuntime = class {
     if (!presence.online) throw new ClientModeError("HOST_OFFLINE", "The selected Host is offline.", true);
     const credentials = await this.server.authenticate(identity);
     const rtcFactory = this.config.forceRelay ? void 0 : await this.rtcFactoryProvider({ routeTargets: [this.server.baseUrl] }).catch(() => void 0);
+    if (!this.config.forceRelay && rtcFactory === void 0) {
+      this.logger.warn("remote Harness WebRTC backend unavailable; using relay", {
+        targetDeviceId: shortId(target.deviceId)
+      });
+    }
     let webRtcFallback = false;
     const createTransport = (attempt) => new AdaptiveTransport(
       websocketUrl(this.server.baseUrl),
@@ -15698,6 +15792,11 @@ var ClientModeRuntime = class {
       this.logger.info("remote Harness transport ready", {
         targetDeviceId: shortId(target.deviceId),
         transport: connectedClient.getStats().mode,
+        ...connectionDetails === void 0 ? {} : {
+          preferredTransports: connectionDetails.preferredTransports,
+          negotiatedCapabilities: connectionDetails.negotiatedCapabilities,
+          webRtcEnabled: connectionDetails.webRtcEnabled
+        },
         ...webrtcDiagnosticsLogFields(connectionDetails?.webRtc?.diagnostics)
       });
       const features = await probeRemoteHostFeatures(connectedClient, serverDevice.clientVersion);
@@ -17026,6 +17125,7 @@ var HostServerConnection = class {
   reconnectRequested = false;
   resumeQueued = false;
   rtcFactory;
+  negotiatedCapabilities = ["transport.relay"];
   start() {
     if (this.running !== void 0) return;
     this.stopped = false;
@@ -17115,6 +17215,7 @@ var HostServerConnection = class {
   async connectOnce() {
     const credentials = await this.api.authenticate(this.identity);
     if (this.stopped) return;
+    const offeredCapabilities = this.rtcFactoryProvider === void 0 || this.config.forceRelay ? ["transport.relay", ...this.hostCapabilities()] : ["transport.p2p", "transport.turn", "transport.relay", ...this.hostCapabilities()];
     const socket = this.createWebSocket(websocketUrl2(this.api.baseUrl));
     this.socket = socket;
     let acknowledged = false;
@@ -17138,7 +17239,7 @@ var HostServerConnection = class {
           protocols: [PROTOCOL_VERSION],
           clientVersion: PLUGIN_VERSION,
           ...this.harnessVersion === void 0 ? {} : { harnessVersion: this.harnessVersion },
-          capabilities: this.rtcFactoryProvider === void 0 || this.config.forceRelay ? ["transport.relay", ...this.hostCapabilities()] : ["transport.p2p", "transport.turn", "transport.relay", ...this.hostCapabilities()]
+          capabilities: offeredCapabilities
         });
       };
       socket.onmessage = (event) => {
@@ -17147,6 +17248,10 @@ var HostServerConnection = class {
           this.lastActiveAt = Date.now();
           if (frame.type === "hello.ack") {
             const payload = requireHelloAck(frame.payload);
+            this.negotiatedCapabilities = acceptNegotiatedCapabilities(offeredCapabilities, payload.capabilities);
+            if (!this.negotiatedCapabilities.some((capability) => capability === "transport.relay" || capability === "transport.p2p" || capability === "transport.turn")) {
+              throw new ControlConnectionError("INVALID_MESSAGE", "Server did not negotiate a transport capability.");
+            }
             acknowledged = true;
             clearTimeout(helloTimer);
             this.online = true;
@@ -17222,7 +17327,10 @@ var HostServerConnection = class {
       this.handleSignalIce(requireSignalIce(frame.payload));
       return;
     }
-    if (frame.type === "transport.selected") return;
+    if (frame.type === "transport.selected") {
+      await this.handleTransportSelected(requireTransportSelected(frame.payload));
+      return;
+    }
     if (frame.type === "signal.answer") return;
     if (frame.type === "error") {
       const payload = requireControlError(frame.payload);
@@ -17309,6 +17417,17 @@ var HostServerConnection = class {
     if (tunnel === void 0 || payload.targetDeviceId !== this.identity.deviceId || payload.step !== 1) {
       throw new ControlConnectionError("SECURE_CHANNEL_FAILED", "Noise IK handshake is not valid for this connection.");
     }
+    if (tunnel.transport === "negotiating" && tunnel.rtc !== void 0) {
+      if (tunnel.pendingHandshake === void 0) tunnel.pendingHandshake = payload;
+      else this.logger.warn("duplicate pending secure handshake ignored", {
+        connectionId: shortId3(tunnel.connectionId),
+        peerDeviceId: shortId3(tunnel.peer.deviceId)
+      });
+      return;
+    }
+    await this.completeHandshake(tunnel, payload);
+  }
+  async completeHandshake(tunnel, payload) {
     tunnel.noise.readHandshake(fromBase64Url2(payload.data));
     const reply = tunnel.noise.writeHandshake();
     if (!tunnel.noise.complete) throw new ControlConnectionError("SECURE_CHANNEL_FAILED", "Noise IK handshake did not complete.");
@@ -17333,7 +17452,16 @@ var HostServerConnection = class {
       transport: mode
     });
   }
+  async resumePendingHandshake(tunnel) {
+    const payload = tunnel.pendingHandshake;
+    if (payload === void 0 || tunnel.channel !== void 0 || tunnel.transport === "negotiating") return;
+    tunnel.pendingHandshake = void 0;
+    await this.completeHandshake(tunnel, payload);
+  }
   async handleRelay(payload) {
+    if (!this.negotiatedCapabilities.includes("transport.relay")) {
+      throw new ControlConnectionError("INVALID_MESSAGE", "Server forwarded Relay without negotiating it.");
+    }
     if (payload.targetDeviceId !== this.identity.deviceId) {
       throw new ControlConnectionError("INVALID_MESSAGE", "Relay frame target does not match this Host.");
     }
@@ -17352,6 +17480,9 @@ var HostServerConnection = class {
     }
   }
   async handleSignalOffer(payload) {
+    if (!this.canUseWebRtc()) {
+      throw new ControlConnectionError("INVALID_MESSAGE", "Server forwarded WebRTC signaling without negotiating it.");
+    }
     const tunnel = this.tunnels.get(payload.connectionId);
     if (tunnel === void 0 || payload.targetDeviceId !== this.identity.deviceId) {
       this.logger.warn("stale webrtc offer ignored", { connectionId: shortId3(payload.connectionId) });
@@ -17413,10 +17544,54 @@ var HostServerConnection = class {
     rtc.handleSignal({ type: "offer", sdp: payload.sdp });
   }
   handleSignalIce(payload) {
+    if (!this.canUseWebRtc()) {
+      throw new ControlConnectionError("INVALID_MESSAGE", "Server forwarded WebRTC signaling without negotiating it.");
+    }
     const tunnel = this.tunnels.get(payload.connectionId);
     if (tunnel === void 0 || payload.targetDeviceId !== this.identity.deviceId) return;
     tunnel.rtc?.handleSignal({ type: "ice", candidate: payload.candidate });
   }
+  async handleTransportSelected(payload) {
+    const tunnel = this.tunnels.get(payload.connectionId);
+    if (tunnel === void 0 || payload.targetDeviceId !== this.identity.deviceId) {
+      this.logger.warn("stale transport selection ignored", { connectionId: shortId3(payload.connectionId) });
+      return;
+    }
+    if (tunnel.channel !== void 0) {
+      if (tunnel.transport !== payload.transport) {
+        this.logger.warn("late transport selection ignored", {
+          connectionId: shortId3(tunnel.connectionId),
+          selected: payload.transport
+        });
+      }
+      return;
+    }
+    const requiredCapability = `transport.${payload.transport}`;
+    if (!this.negotiatedCapabilities.includes(requiredCapability)) {
+      throw new ControlConnectionError(
+        "INVALID_MESSAGE",
+        `Client selected unnegotiated transport: ${payload.transport}`
+      );
+    }
+    if (payload.transport === "relay") {
+      const rtc = tunnel.rtc;
+      tunnel.rtc = void 0;
+      tunnel.transport = "relay";
+      tunnel.transportMode = void 0;
+      await rtc?.close();
+      await this.resumePendingHandshake(tunnel);
+      return;
+    }
+    if (tunnel.rtc === void 0) {
+      throw new ControlConnectionError("INVALID_MESSAGE", "Client selected WebRTC before creating a data channel.");
+    }
+    tunnel.transport = payload.transport;
+    tunnel.transportMode = tunnel.rtc.selectedPathMode();
+    await this.resumePendingHandshake(tunnel);
+  }
+  canUseWebRtc() {
+    return this.negotiatedCapabilities.includes("transport.p2p") || this.negotiatedCapabilities.includes("transport.turn");
+  }
   sendRtcSignal(tunnel, signal) {
     if (signal.type === "answer") {
       this.sendControl("signal.answer", {
@@ -17434,6 +17609,20 @@ var HostServerConnection = class {
   }
   handleRtcOpened(tunnel, selected) {
     if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc === void 0) return;
+    const requiredCapability = selected === "turn" ? "transport.turn" : "transport.p2p";
+    if (!this.negotiatedCapabilities.includes(requiredCapability)) {
+      const error = new Error(`WebRTC selected unnegotiated transport: ${selected}`);
+      if (!this.negotiatedCapabilities.includes("transport.relay")) {
+        void this.dropTunnel(tunnel.connectionId, "CONNECTION_FAILED");
+        return;
+      }
+      void this.handleRtcFailed(
+        tunnel,
+        tunnel.rtc,
+        error
+      );
+      return;
+    }
     tunnel.transport = selected;
     tunnel.transportMode = tunnel.rtc.selectedPathMode();
     this.sendTransportSelected(tunnel, selected);
@@ -17443,6 +17632,13 @@ var HostServerConnection = class {
       transport: tunnel.transportMode ?? selected,
       ...webrtcDiagnosticsLogFields2(rtcDiagnostics(tunnel.rtc))
     });
+    void this.resumePendingHandshake(tunnel).catch((error) => {
+      this.logger.warn("pending secure handshake failed", {
+        connectionId: shortId3(tunnel.connectionId),
+        reason: diagnosticReason3(error)
+      });
+      void this.dropTunnel(tunnel.connectionId, "SECURE_CHANNEL_FAILED");
+    });
   }
   async handleRtcFailed(tunnel, rtc, error) {
     if (this.tunnels.get(tunnel.connectionId) !== tunnel || tunnel.rtc !== rtc) return;
@@ -17463,6 +17659,7 @@ var HostServerConnection = class {
       reason: diagnosticReason3(error),
       ...webrtcDiagnosticsLogFields2(rtcDiagnostics(rtc))
     });
+    await this.resumePendingHandshake(tunnel);
   }
   sendTransportSelected(tunnel, transport) {
     this.sendControl("transport.selected", {
@@ -17662,6 +17859,13 @@ function requireSignalIce(value) {
   }
   return payload;
 }
+function requireTransportSelected(value) {
+  const payload = requireObject(value);
+  if (typeof payload.connectionId !== "string" || typeof payload.targetDeviceId !== "string" || payload.transport !== "p2p" && payload.transport !== "turn" && payload.transport !== "relay") {
+    throw new ControlConnectionError("INVALID_MESSAGE", "transport.selected payload is invalid.");
+  }
+  return payload;
+}
 function requireControlError(value) {
   const payload = requireObject(value);
   if (typeof payload.code !== "string" || typeof payload.message !== "string" || payload.connectionId !== void 0 && (typeof payload.connectionId !== "string" || payload.connectionId === "")) {
@@ -19249,7 +19453,7 @@ export {
   PluginControlRuntime,
   RemoteFileViewerBridge,
   RemoteHarnessApiProxy,
-  RemoteTypertGateway,
+  RemoteTypertGateway2 as RemoteTypertGateway,
   RpcError,
   RpcRouter,
   ServerApiError,