ds-harness-remote 0.3.31 → 0.3.33

package/dist/index.js

@@ -4574,7 +4574,7 @@ var RTC_DATA_CHANNEL_OPTIONS = { ordered: true };
 function browserRtcFactory() {
   return {
     create(configuration) {
-      const raw = new RTCPeerConnection(configuration);
+      const raw = new RTCPeerConnection({ iceServers: configuration.iceServers });
       return {
         get connectionState() {
           return raw.connectionState;
@@ -4646,6 +4646,97 @@ function browserRtcFactory() {
     }
   };
 }
+function summarizeIceCandidate(candidate) {
+  const value = candidate?.candidate?.trim();
+  if (value === void 0 || value.length === 0)
+    return emptyCandidateSummary();
+  const parts = value.replace(/^candidate:/, "").split(/\s+/);
+  const typeIndex = parts.indexOf("typ");
+  const relatedAddressIndex = parts.indexOf("raddr");
+  return {
+    candidateType: parseCandidateType(parts[typeIndex + 1]),
+    protocol: normalizeProtocol(parts[2]),
+    ...summarizeAddress(parts[4]),
+    ...relatedAddressIndex < 0 ? {} : relatedAddressSummary(parts[relatedAddressIndex + 1])
+  };
+}
+function summarizeAddress(address) {
+  if (address === void 0 || address.length === 0)
+    return { addressFamily: "unknown", addressScope: "unknown" };
+  if (address.includes(":"))
+    return { addressFamily: "ipv6", addressScope: summarizeIpv6Scope(address) };
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return { addressFamily: "unknown", addressScope: "unknown" };
+  }
+  return { addressFamily: "ipv4", addressScope: summarizeIpv4Scope(parts) };
+}
+function stunOnlyIceServers(iceServers) {
+  const direct = [];
+  for (const server of iceServers) {
+    const sourceUrls = Array.isArray(server.urls) ? server.urls : [server.urls];
+    const urls = sourceUrls.filter(isStunUrl);
+    if (urls.length === 0)
+      continue;
+    direct.push({ urls: Array.isArray(server.urls) ? urls : urls[0] });
+  }
+  return direct;
+}
+function isStunUrl(url) {
+  const value = url.trim().toLowerCase();
+  return value.startsWith("stun:") || value.startsWith("stuns:");
+}
+function emptyCandidateSummary() {
+  return { candidateType: "unknown", addressFamily: "unknown", addressScope: "unknown" };
+}
+function parseCandidateType(value) {
+  if (value === "host" || value === "srflx" || value === "prflx" || value === "relay")
+    return value;
+  return "unknown";
+}
+function normalizeProtocol(value) {
+  if (value === void 0 || value.length === 0)
+    return void 0;
+  return value.toLowerCase();
+}
+function relatedAddressSummary(address) {
+  const summary = summarizeAddress(address);
+  return {
+    relatedAddressFamily: summary.addressFamily,
+    relatedAddressScope: summary.addressScope
+  };
+}
+function summarizeIpv4Scope(parts) {
+  if (parts[0] === 0 || parts[0] >= 240)
+    return "reserved";
+  if (parts[0] === 127)
+    return "loopback";
+  if (parts[0] === 169 && parts[1] === 254)
+    return "link-local";
+  if (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127)
+    return "cgnat";
+  if (parts[0] >= 224)
+    return "reserved";
+  if (parts[0] === 10)
+    return "private";
+  if (parts[0] === 192 && parts[1] === 168)
+    return "private";
+  if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+    return "private";
+  return "public";
+}
+function summarizeIpv6Scope(address) {
+  const value = address.toLowerCase();
+  if (value === "::1")
+    return "loopback";
+  if (value.startsWith("fe80:"))
+    return "link-local";
+  if (value.startsWith("fc") || value.startsWith("fd"))
+    return "private";
+  if (value.startsWith("ff"))
+    return "reserved";
+  return "public";
+}
 function adaptDataChannel(raw) {
   return {
     get label() {
@@ -4823,6 +4914,8 @@ var RtcDataChannelTransport = class {
   negotiateTimeoutMs;
   channelLabel;
   sendTimeoutMs;
+  label;
+  onDiagnostic;
   channel;
   remoteCandidates = [];
   remoteDescriptionSet = false;
@@ -4843,6 +4936,12 @@ var RtcDataChannelTransport = class {
   bytesReceived = 0;
   selected;
   selectedMode;
+  selectedPathTelemetry;
+  localCandidateTelemetry = emptyCandidateTelemetry();
+  remoteCandidateTelemetry = emptyCandidateTelemetry();
+  candidatePairTelemetry = emptyCandidatePairTelemetry();
+  filteredLocalCandidateTelemetry = emptyCandidateTelemetry();
+  filteredCandidatePairTelemetry = emptyCandidateTelemetry();
   lastBufferedAmount = 0;
   constructor(options) {
     this.role = options.role;
@@ -4850,15 +4949,30 @@ var RtcDataChannelTransport = class {
     this.negotiateTimeoutMs = options.negotiateTimeoutMs ?? DEFAULT_NEGOTIATE_TIMEOUT_MS;
     this.channelLabel = options.channelLabel ?? RTC_DATA_CHANNEL_LABEL;
     this.sendTimeoutMs = options.sendTimeoutMs;
-    this.pc = options.factory.create({ iceServers: options.iceServers });
+    this.label = options.label;
+    this.onDiagnostic = options.onDiagnostic;
+    this.pc = options.factory.create({
+      iceServers: options.iceServers,
+      onDiagnostic: (event) => this.handlePeerDiagnostic(event)
+    });
     this.pc.ondatachannel = (event) => this.adoptChannel(event.channel);
     this.pc.onicecandidate = (event) => {
       if (event.candidate !== null && !this.closed) {
+        const candidate = summarizeIceCandidate(event.candidate);
+        recordCandidate(this.localCandidateTelemetry, candidate);
+        this.emitDiagnostic({ type: "local-candidate", candidate, diagnostics: this.diagnostics() });
         this.onSignal({ type: "ice", candidate: event.candidate });
       }
     };
-    this.pc.onconnectionstatechange = () => this.checkConnectionState();
-    this.pc.oniceconnectionstatechange = () => this.checkConnectionState();
+    this.pc.onconnectionstatechange = () => {
+      this.emitStateChange();
+      this.checkConnectionState();
+    };
+    this.pc.oniceconnectionstatechange = () => {
+      this.emitStateChange();
+      this.checkConnectionState();
+    };
+    this.pc.onicegatheringstatechange = () => this.emitStateChange();
   }
   /** Begin negotiation; resolves when the DataChannel is open. */
   connect(signal) {
@@ -4871,7 +4985,7 @@ var RtcDataChannelTransport = class {
       this.openResolve = resolve2;
       this.openReject = reject;
       this.negotiateTimer = setTimeout(() => {
-        this.failOpen(new RtcConnectError("RTC_CONNECT_TIMEOUT", `WebRTC negotiation timed out after ${this.negotiateTimeoutMs}ms.`));
+        void this.failOpenAfterStats(new RtcConnectError("RTC_CONNECT_TIMEOUT", `WebRTC negotiation timed out after ${this.negotiateTimeoutMs}ms.`));
       }, this.negotiateTimeoutMs);
       if (this.role === "initiator") {
         void this.startInitiator().catch((error) => this.failOpen(asError(error)));
@@ -4922,10 +5036,25 @@ var RtcDataChannelTransport = class {
   selectedPathMode() {
     return this.selectedMode;
   }
+  diagnostics() {
+    return {
+      role: this.role,
+      ...this.label === void 0 ? {} : { label: this.label },
+      connectionState: this.pc.connectionState,
+      iceConnectionState: this.pc.iceConnectionState,
+      iceGatheringState: this.pc.iceGatheringState,
+      localCandidates: cloneCandidateTelemetry(this.localCandidateTelemetry),
+      remoteCandidates: cloneCandidateTelemetry(this.remoteCandidateTelemetry),
+      candidatePairs: cloneCandidatePairTelemetry(this.candidatePairTelemetry),
+      filteredLocalCandidates: cloneCandidateTelemetry(this.filteredLocalCandidateTelemetry),
+      filteredCandidatePairs: cloneCandidateTelemetry(this.filteredCandidatePairTelemetry),
+      ...this.selectedPathTelemetry === void 0 ? {} : { selectedPath: { ...this.selectedPathTelemetry } }
+    };
+  }
   async connectionDetails() {
     let statsDetails = {};
     try {
-      statsDetails = inspectSelectedPath(await this.pc.getStats());
+      statsDetails = await this.refreshStatsDiagnostics();
     } catch {
     }
     return {
@@ -4933,7 +5062,8 @@ var RtcDataChannelTransport = class {
       mode: statsDetails.mode ?? this.selectedMode,
       connectionState: this.pc.connectionState,
       iceConnectionState: this.pc.iceConnectionState,
-      dataChannelState: this.channel?.readyState
+      dataChannelState: this.channel?.readyState,
+      diagnostics: this.diagnostics()
     };
   }
   getStats() {
@@ -5029,13 +5159,19 @@ var RtcDataChannelTransport = class {
     }
   }
   async handleIce(candidate) {
+    const summary = summarizeIceCandidate(candidate);
     if (!this.remoteDescriptionSet) {
+      recordCandidate(this.remoteCandidateTelemetry, summary);
+      this.emitDiagnostic({ type: "remote-candidate", candidate: summary, action: "buffered", diagnostics: this.diagnostics() });
       this.remoteCandidates.push(candidate);
       return;
     }
     try {
       await this.pc.addIceCandidate(candidate);
+      recordCandidate(this.remoteCandidateTelemetry, summary);
+      this.emitDiagnostic({ type: "remote-candidate", candidate: summary, action: "added", diagnostics: this.diagnostics() });
     } catch {
+      this.emitDiagnostic({ type: "remote-candidate", candidate: summary, action: "ignored", diagnostics: this.diagnostics() });
     }
   }
   async flushRemoteCandidates() {
@@ -5100,9 +5236,15 @@ var RtcDataChannelTransport = class {
   }
   async resolveSelectedTransport() {
     try {
-      const selected = inspectSelectedPath(await this.pc.getStats());
+      const selected = await this.refreshStatsDiagnostics();
       this.selected = selected?.transport;
       this.selectedMode = selected?.mode;
+      this.selectedPathTelemetry = selectedPathTelemetry(selected);
+      this.emitDiagnostic({
+        type: "selected-path",
+        selectedPath: this.selectedPathTelemetry,
+        diagnostics: this.diagnostics()
+      });
     } catch {
       this.selected = void 0;
       this.selectedMode = void 0;
@@ -5112,9 +5254,16 @@ var RtcDataChannelTransport = class {
     if (this.closed || this.opened)
       return;
     if (this.pc.connectionState === "failed" || this.pc.iceConnectionState === "failed" || this.pc.connectionState === "closed" || this.pc.iceConnectionState === "closed") {
-      this.failOpen(new RtcConnectError("RTC_FAILED", "WebRTC peer connection failed before the data channel opened."));
+      void this.failOpenAfterStats(new RtcConnectError("RTC_FAILED", "WebRTC peer connection failed before the data channel opened."));
     }
   }
+  async failOpenAfterStats(error) {
+    await Promise.race([
+      this.refreshStatsDiagnostics().catch(() => void 0),
+      sleep(250)
+    ]);
+    this.failOpen(error);
+  }
   failOpen(error) {
     if (this.closed || this.opened || this.openReject === void 0)
       return;
@@ -5176,6 +5325,46 @@ var RtcDataChannelTransport = class {
     this.watchdogTimer = void 0;
     this.lastBufferedAmount = 0;
   }
+  async refreshStatsDiagnostics() {
+    const stats = [...await this.pc.getStats()];
+    this.candidatePairTelemetry = inspectCandidatePairs(stats);
+    return inspectSelectedPath(stats);
+  }
+  handlePeerDiagnostic(event) {
+    if (event.type === "local-candidate-filtered") {
+      recordCandidate(this.filteredLocalCandidateTelemetry, event.candidate);
+      this.emitDiagnostic({
+        type: event.type,
+        candidate: event.candidate,
+        reason: event.reason,
+        diagnostics: this.diagnostics()
+      });
+      return;
+    }
+    if (event.localCandidate !== void 0)
+      recordCandidate(this.filteredCandidatePairTelemetry, event.localCandidate);
+    this.emitDiagnostic({
+      type: event.type,
+      localCandidate: event.localCandidate,
+      reason: event.reason,
+      diagnostics: this.diagnostics()
+    });
+  }
+  emitStateChange() {
+    this.emitDiagnostic({
+      type: "state-change",
+      connectionState: this.pc.connectionState,
+      iceConnectionState: this.pc.iceConnectionState,
+      iceGatheringState: this.pc.iceGatheringState,
+      diagnostics: this.diagnostics()
+    });
+  }
+  emitDiagnostic(event) {
+    try {
+      this.onDiagnostic?.(event);
+    } catch {
+    }
+  }
 };
 var RtcConnectError = class extends Error {
   code;
@@ -5237,6 +5426,33 @@ function inspectSelectedPath(stats) {
   }
   return {};
 }
+function inspectCandidatePairs(stats) {
+  const candidates = /* @__PURE__ */ new Map();
+  const telemetry = emptyCandidatePairTelemetry();
+  const pairs = [];
+  for (const [reportId, entry] of stats) {
+    if (entry.type === "local-candidate" || entry.type === "remote-candidate") {
+      if (typeof entry.candidateType === "string" && entry.id !== void 0) {
+        candidates.set(String(entry.id), entry);
+      }
+    } else if (entry.type === "candidate-pair") {
+      pairs.push({ ...entry, id: entry.id ?? reportId });
+    }
+  }
+  for (const pair of pairs) {
+    telemetry.total += 1;
+    if (pair.nominated === true)
+      telemetry.nominated += 1;
+    if (pair.selected === true)
+      telemetry.selected += 1;
+    increment(telemetry.byState, stringStat(pair, "state") ?? (pair.selected === true ? "selected" : "unknown"));
+    const local = candidates.get(String(pair.localCandidateId));
+    const remote = candidates.get(String(pair.remoteCandidateId));
+    recordCandidateStats(telemetry.byLocalType, telemetry.byLocalFamily, telemetry.byLocalScope, local);
+    recordCandidateStats(telemetry.byRemoteType, telemetry.byRemoteFamily, telemetry.byRemoteScope, remote);
+  }
+  return telemetry;
+}
 function candidateAddress(candidate) {
   const address = stringStat(candidate, "address") ?? stringStat(candidate, "ip");
   if (address === void 0)
@@ -5252,6 +5468,91 @@ function numberStat(entry, key) {
   const value = entry?.[key];
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function emptyCandidateTelemetry() {
+  return {
+    total: 0,
+    byType: {},
+    byFamily: {},
+    byScope: {},
+    byProtocol: {}
+  };
+}
+function cloneCandidateTelemetry(value) {
+  return {
+    total: value.total,
+    byType: { ...value.byType },
+    byFamily: { ...value.byFamily },
+    byScope: { ...value.byScope },
+    byProtocol: { ...value.byProtocol }
+  };
+}
+function emptyCandidatePairTelemetry() {
+  return {
+    total: 0,
+    nominated: 0,
+    selected: 0,
+    byState: {},
+    byLocalType: {},
+    byRemoteType: {},
+    byLocalFamily: {},
+    byRemoteFamily: {},
+    byLocalScope: {},
+    byRemoteScope: {}
+  };
+}
+function cloneCandidatePairTelemetry(value) {
+  return {
+    total: value.total,
+    nominated: value.nominated,
+    selected: value.selected,
+    byState: { ...value.byState },
+    byLocalType: { ...value.byLocalType },
+    byRemoteType: { ...value.byRemoteType },
+    byLocalFamily: { ...value.byLocalFamily },
+    byRemoteFamily: { ...value.byRemoteFamily },
+    byLocalScope: { ...value.byLocalScope },
+    byRemoteScope: { ...value.byRemoteScope }
+  };
+}
+function recordCandidate(telemetry, candidate) {
+  telemetry.total += 1;
+  increment(telemetry.byType, candidate.candidateType);
+  increment(telemetry.byFamily, candidate.addressFamily);
+  increment(telemetry.byScope, candidate.addressScope);
+  if (candidate.protocol !== void 0)
+    increment(telemetry.byProtocol, candidate.protocol);
+}
+function recordCandidateStats(byType, byFamily, byScope, candidate) {
+  const candidateType = candidateTypeStat(candidate);
+  const address = summarizeAddress(candidateAddressValue(candidate));
+  increment(byType, candidateType);
+  increment(byFamily, address.addressFamily);
+  increment(byScope, address.addressScope);
+}
+function candidateTypeStat(candidate) {
+  const value = stringStat(candidate, "candidateType");
+  if (value === "host" || value === "srflx" || value === "prflx" || value === "relay")
+    return value;
+  return "unknown";
+}
+function candidateAddressValue(candidate) {
+  return stringStat(candidate, "address") ?? stringStat(candidate, "ip");
+}
+function increment(map, key) {
+  map[key] = (map[key] ?? 0) + 1;
+}
+function selectedPathTelemetry(details) {
+  return {
+    ...details.transport === void 0 ? {} : { transport: details.transport },
+    ...details.mode === void 0 ? {} : { mode: details.mode },
+    ...details.localCandidateType === void 0 ? {} : { localCandidateType: details.localCandidateType },
+    ...details.remoteCandidateType === void 0 ? {} : { remoteCandidateType: details.remoteCandidateType },
+    ...details.protocol === void 0 ? {} : { protocol: details.protocol },
+    ...details.relayProtocol === void 0 ? {} : { relayProtocol: details.relayProtocol },
+    ...details.currentRoundTripTimeMs === void 0 ? {} : { currentRoundTripTimeMs: details.currentRoundTripTimeMs },
+    ...details.availableOutgoingBitrate === void 0 ? {} : { availableOutgoingBitrate: details.availableOutgoingBitrate }
+  };
+}
 function requireSdp(description) {
   if (typeof description.sdp !== "string" || description.sdp.length === 0) {
     throw new RtcConnectError("RTC_FAILED", "The RTC backend produced an empty session description.");
@@ -5266,6 +5567,9 @@ function toArrayBuffer(data) {
 function asError(error) {
   return error instanceof Error ? error : new RtcConnectError("RTC_FAILED", "WebRTC negotiation failed.");
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 
 // ../webrtc/dist/adaptive-transport.js
 var DEFAULT_CAPABILITIES = ["transport.p2p", "transport.turn", "transport.relay", "harness.api.v1"];
@@ -5288,6 +5592,7 @@ var AdaptiveTransport = class extends BaseTransport {
   webrtcEnabled = true;
   serverNegotiateTimeoutMs;
   connectedAt;
+  lastRtcDiagnostics;
   constructor(url, options) {
     super();
     this.url = url;
@@ -5487,6 +5792,7 @@ var AdaptiveTransport = class extends BaseTransport {
     const preferred = this.options.preferredTransports ?? [...DEFAULT_PREFERRED_TRANSPORTS];
     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();
@@ -5495,7 +5801,7 @@ var AdaptiveTransport = class extends BaseTransport {
       } catch (error) {
         const reason = error instanceof Error ? error : new Error("WebRTC negotiation failed.");
         try {
-          this.options.onWebRtcFallback?.(reason);
+          this.options.onWebRtcFallback?.(reason, this.lastRtcDiagnostics);
         } catch {
         }
         await this.rtc?.close();
@@ -5534,8 +5840,15 @@ var AdaptiveTransport = class extends BaseTransport {
       factory,
       iceServers,
       onSignal: (signal) => this.sendRtcSignal(signal),
-      negotiateTimeoutMs: this.serverNegotiateTimeoutMs ?? this.options.negotiateTimeoutMs,
-      label: `client->${this.options.targetDeviceId}`
+      negotiateTimeoutMs: negotiateTimeout(this.serverNegotiateTimeoutMs, this.options.negotiateTimeoutMs),
+      label: `client->${this.options.targetDeviceId}`,
+      onDiagnostic: (event) => {
+        this.lastRtcDiagnostics = event.diagnostics;
+        try {
+          this.options.onWebRtcDiagnostic?.(event);
+        } catch {
+        }
+      }
     });
     this.rtc = rtc;
     rtc.onMessage((data) => {
@@ -5549,10 +5862,12 @@ var AdaptiveTransport = class extends BaseTransport {
     try {
       await rtc.connect();
     } catch (error) {
+      this.lastRtcDiagnostics = rtc.diagnostics();
       await rtc.close();
       this.rtc = void 0;
       throw error;
     }
+    this.lastRtcDiagnostics = rtc.diagnostics();
     return rtc.selectedTransport() ?? "p2p";
   }
   sendRtcSignal(signal) {
@@ -5625,6 +5940,13 @@ function socketState(readyState) {
     return "closing";
   return "closed";
 }
+function negotiateTimeout(serverMs, localMs) {
+  if (serverMs === void 0)
+    return localMs;
+  if (localMs === void 0)
+    return serverMs;
+  return Math.max(serverMs, localMs);
+}
 
 // src/api-proxy-switch.ts
 var SWITCHED_DOMAINS = [
@@ -13212,7 +13534,7 @@ function normalizeServerUrl(value) {
 }
 
 // src/version.ts
-var PLUGIN_VERSION = "0.3.31";
+var PLUGIN_VERSION = "0.3.33";
 
 // src/server-api.ts
 var HostServerApi = class {
@@ -13226,9 +13548,13 @@ var HostServerApi = class {
   identity;
   credentials;
   credentialsPromise;
+  harnessVersion;
   bindIdentity(identity) {
     this.identity = identity;
   }
+  setHarnessVersion(version) {
+    this.harnessVersion = version;
+  }
   currentAuthorization() {
     if (this.credentials === void 0) return void 0;
     return {
@@ -13435,7 +13761,8 @@ var HostServerApi = class {
       role: this.role,
       platform: platform(),
       identityKey: identity.publicKey,
-      clientVersion: PLUGIN_VERSION
+      clientVersion: PLUGIN_VERSION,
+      ...this.role === "host" && this.harnessVersion !== void 0 ? { harnessVersion: this.harnessVersion } : {}
     };
   }
   saveTokens(identity, tokens, authorization) {
@@ -13646,33 +13973,662 @@ function isRemoteCommandMethod(method) {
 }
 
 // src/werift-rtc.ts
+import { createSocket } from "node:dgram";
 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 { delimiter, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var cachedExternalFactory;
+var cachedExternalFactoryResolved = false;
+var cachedNodeBinary;
+var cachedNodeBinaryResolved = false;
+async function loadExternalNativeRtcFactory() {
+  if (cachedExternalFactory !== void 0) return cachedExternalFactory;
+  if (cachedExternalFactoryResolved) return void 0;
+  cachedExternalFactoryResolved = true;
+  const nodeBinary = resolveExternalNodeBinaryForRtc();
+  if (nodeBinary === void 0) return void 0;
+  cachedExternalFactory = buildExternalNativeRtcFactory(nodeBinary);
+  return cachedExternalFactory;
+}
+function buildExternalNativeRtcFactory(nodeBinary, requireFrom = fileURLToPath(import.meta.url)) {
+  return {
+    create(configuration) {
+      return new ExternalNativePeerConnection(nodeBinary, requireFrom, configuration);
+    }
+  };
+}
+function resolveExternalNodeBinaryForRtc() {
+  if (cachedNodeBinaryResolved) return cachedNodeBinary;
+  cachedNodeBinaryResolved = true;
+  const requireFrom = fileURLToPath(import.meta.url);
+  for (const candidate of nodeBinaryCandidates()) {
+    if (isUsableExternalNode(candidate, requireFrom)) {
+      cachedNodeBinary = candidate;
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function nodeBinaryCandidates() {
+  const candidates = [];
+  const add3 = (value) => {
+    if (value === void 0 || value.trim() === "") return;
+    if (!candidates.includes(value)) candidates.push(value);
+  };
+  add3(process.env.DSH_REMOTE_NODE);
+  add3(process.env.NODE);
+  add3(process.execPath);
+  for (const part of (process.env.PATH ?? "").split(delimiter)) add3(join(part, process.platform === "win32" ? "node.exe" : "node"));
+  add3("/opt/homebrew/bin/node");
+  add3("/usr/local/bin/node");
+  add3("/usr/bin/node");
+  add3(join(process.env.HOME ?? "", ".volta", "bin", process.platform === "win32" ? "node.exe" : "node"));
+  add3(join(process.env.HOME ?? "", ".asdf", "shims", process.platform === "win32" ? "node.exe" : "node"));
+  add3(join(process.env.HOME ?? "", ".local", "bin", process.platform === "win32" ? "node.exe" : "node"));
+  for (const nvmNode of nvmNodeCandidates()) add3(nvmNode);
+  return candidates;
+}
+function nvmNodeCandidates() {
+  const root = join(process.env.HOME ?? "", ".nvm", "versions", "node");
+  if (root === "" || !existsSync(root)) return [];
+  try {
+    return readdirSync(root).map((version) => join(root, version, "bin", process.platform === "win32" ? "node.exe" : "node")).sort((left, right) => right.localeCompare(left, "en", { numeric: true }));
+  } catch {
+    return [];
+  }
+}
+function isUsableExternalNode(candidate, requireFrom) {
+  if (!isExecutableFile(candidate)) return false;
+  const env = { ...process.env, DSH_REMOTE_RTC_HELPER_REQUIRE_FROM: requireFrom };
+  delete env.ELECTRON_RUN_AS_NODE;
+  const probe = spawnSync(candidate, [
+    "--input-type=module",
+    "--eval",
+    [
+      "import { createRequire } from 'node:module';",
+      "const require = createRequire(process.env.DSH_REMOTE_RTC_HELPER_REQUIRE_FROM);",
+      "if (process.versions.electron) throw new Error('electron-node');",
+      "const wrtc = require('@roamhq/wrtc');",
+      "const RTCPeerConnection = wrtc.RTCPeerConnection ?? wrtc.default?.RTCPeerConnection;",
+      "if (typeof RTCPeerConnection !== 'function') throw new Error('missing-rtc');",
+      "console.log(`node:${process.versions.node}`);"
+    ].join("")
+  ], {
+    cwd: dirname(requireFrom),
+    env,
+    encoding: "utf8",
+    timeout: 3e3
+  });
+  return probe.status === 0 && probe.stdout.startsWith("node:");
+}
+function isExecutableFile(candidate) {
+  try {
+    const stat4 = statSync(candidate);
+    if (!stat4.isFile()) return false;
+    if (process.platform === "win32") return true;
+    return (stat4.mode & 73) !== 0;
+  } catch {
+    return false;
+  }
+}
+var ExternalNativePeerConnection = class {
+  constructor(nodeBinary, requireFrom, configuration) {
+    this.nodeBinary = nodeBinary;
+    this.requireFrom = requireFrom;
+    this.child = spawn(this.nodeBinary, ["--input-type=module", "--eval", HELPER_SOURCE], {
+      cwd: dirname(this.requireFrom),
+      env: { ...process.env, DSH_REMOTE_RTC_HELPER_REQUIRE_FROM: this.requireFrom },
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    this.child.stdout.setEncoding("utf8");
+    this.child.stdout.on("data", (chunk) => this.handleStdout(String(chunk)));
+    this.child.stderr.on("data", () => void 0);
+    this.child.on("exit", () => this.handleExit());
+    this.child.on("error", (error) => this.handleExit(error));
+    this.child.stdin.on("error", (error) => this.handleExit(error));
+    this.ready = this.request("init", { iceServers: configuration.iceServers ?? [] }).then(() => void 0);
+  }
+  connectionState = "new";
+  iceConnectionState = "new";
+  iceGatheringState = "new";
+  signalingState = "stable";
+  onconnectionstatechange = null;
+  oniceconnectionstatechange = null;
+  onicegatheringstatechange = null;
+  onicecandidate = null;
+  ondatachannel = null;
+  child;
+  pending = /* @__PURE__ */ new Map();
+  channels = /* @__PURE__ */ new Map();
+  nextRequestId = 1;
+  nextChannelId = 1;
+  stdout = "";
+  closed = false;
+  ready;
+  createDataChannel(label, options) {
+    const channelId = this.nextChannelId++;
+    const channel = new ExternalNativeDataChannel(this, channelId, label, options?.ordered ?? true);
+    this.channels.set(channelId, channel);
+    this.notify("createDataChannel", { channelId, label, options: { ordered: options?.ordered ?? true } });
+    return channel;
+  }
+  async createOffer() {
+    await this.ready;
+    return this.request("createOffer", {});
+  }
+  async createAnswer() {
+    await this.ready;
+    return this.request("createAnswer", {});
+  }
+  async setLocalDescription(description) {
+    await this.ready;
+    await this.request("setLocalDescription", { description });
+  }
+  async setRemoteDescription(description) {
+    await this.ready;
+    await this.request("setRemoteDescription", { description });
+  }
+  async addIceCandidate(candidate) {
+    await this.ready;
+    await this.request("addIceCandidate", { candidate: candidate ?? null });
+  }
+  async getStats() {
+    await this.ready;
+    return this.request("getStats", {});
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.notify("close", {});
+    const timer = setTimeout(() => {
+      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+    }, 1e3);
+    timer.unref?.();
+  }
+  sendChannelData(channelId, data) {
+    const payload = typeof data === "string" ? { channelId, text: data } : { channelId, base64: Buffer.from(data).toString("base64") };
+    this.notify("channelSend", payload);
+  }
+  closeChannel(channelId) {
+    this.notify("channelClose", { channelId });
+  }
+  request(method, payload) {
+    if (this.closed) return Promise.reject(new Error("native rtc helper is closed"));
+    const id = this.nextRequestId++;
+    const promise = new Promise((resolve2, reject) => {
+      this.pending.set(id, { resolve: resolve2, reject });
+    });
+    this.write({ id, method, payload });
+    return promise;
+  }
+  notify(method, payload) {
+    if (this.closed && method !== "close") return;
+    this.write({ method, payload });
+  }
+  write(message) {
+    try {
+      this.child.stdin.write(`${JSON.stringify(message)}
+`);
+    } catch {
+      this.handleExit(new Error("native rtc helper stdin is closed"));
+    }
+  }
+  handleStdout(chunk) {
+    this.stdout += chunk;
+    for (; ; ) {
+      const newline = this.stdout.indexOf("\n");
+      if (newline < 0) return;
+      const line = this.stdout.slice(0, newline);
+      this.stdout = this.stdout.slice(newline + 1);
+      if (line.trim() === "") continue;
+      try {
+        this.handleMessage(JSON.parse(line));
+      } catch {
+        this.handleExit(new Error("native rtc helper sent invalid JSON"));
+      }
+    }
+  }
+  handleMessage(message) {
+    if ("id" in message) {
+      const pending = this.pending.get(message.id);
+      if (pending === void 0) return;
+      this.pending.delete(message.id);
+      if (message.ok) pending.resolve(message.value);
+      else pending.reject(new Error(message.error ?? "native rtc helper command failed"));
+      return;
+    }
+    if (message.event === "state") {
+      this.connectionState = message.connectionState;
+      this.iceConnectionState = message.iceConnectionState;
+      this.iceGatheringState = message.iceGatheringState;
+      this.signalingState = message.signalingState;
+      this.onconnectionstatechange?.();
+      this.oniceconnectionstatechange?.();
+      this.onicegatheringstatechange?.();
+      return;
+    }
+    if (message.event === "icecandidate") {
+      this.onicecandidate?.({ candidate: message.candidate });
+      return;
+    }
+    if (message.event === "datachannel") {
+      const channel = this.channelFor(message.channelId, message.label, message.ordered);
+      this.ondatachannel?.({ channel });
+      channel.updateState(message.readyState, message.bufferedAmount);
+      return;
+    }
+    if (message.event === "channel-state") {
+      this.channels.get(message.channelId)?.updateState(message.readyState, message.bufferedAmount);
+      return;
+    }
+    if (message.event === "channel-message") {
+      const channel = this.channels.get(message.channelId);
+      if (channel === void 0) return;
+      if (message.text !== void 0) channel.emitMessage(message.text);
+      else if (message.base64 !== void 0) channel.emitMessage(bufferToArrayBuffer(Buffer.from(message.base64, "base64")));
+      return;
+    }
+    if (message.event === "channel-error") {
+      this.channels.get(message.channelId)?.emitError();
+    }
+  }
+  channelFor(channelId, label, ordered) {
+    const existing = this.channels.get(channelId);
+    if (existing !== void 0) return existing;
+    const channel = new ExternalNativeDataChannel(this, channelId, label, ordered);
+    this.channels.set(channelId, channel);
+    return channel;
+  }
+  handleExit(error) {
+    if (!this.closed) this.closed = true;
+    const reason = error ?? new Error("native rtc helper exited");
+    for (const pending of this.pending.values()) pending.reject(reason);
+    this.pending.clear();
+    for (const channel of this.channels.values()) channel.updateState("closed", 0);
+  }
+};
+var ExternalNativeDataChannel = class {
+  constructor(owner, channelId, label, ordered) {
+    this.owner = owner;
+    this.channelId = channelId;
+    this.label = label;
+    this.ordered = ordered;
+  }
+  readyState = "connecting";
+  bufferedAmount = 0;
+  binaryType = "arraybuffer";
+  onopen = null;
+  onmessage = null;
+  onclose = null;
+  onerror = null;
+  onbufferedamountlow = null;
+  send(data) {
+    this.owner.sendChannelData(this.channelId, data);
+  }
+  close() {
+    this.owner.closeChannel(this.channelId);
+  }
+  updateState(readyState, bufferedAmount) {
+    const previous = this.readyState;
+    this.readyState = readyState;
+    this.bufferedAmount = bufferedAmount;
+    if (previous !== "open" && readyState === "open") this.onopen?.();
+    if (previous !== "closed" && readyState === "closed") this.onclose?.();
+    if (bufferedAmount === 0) this.onbufferedamountlow?.();
+  }
+  emitMessage(data) {
+    this.onmessage?.({ data });
+  }
+  emitError() {
+    this.onerror?.();
+  }
+};
+function bufferToArrayBuffer(buffer) {
+  return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+}
+var HELPER_SOURCE = String.raw`
+import { createRequire } from 'node:module'
+import { createInterface } from 'node:readline'
+
+const require = createRequire(process.env.DSH_REMOTE_RTC_HELPER_REQUIRE_FROM || (process.cwd() + '/package.json'))
+const wrtc = require('@roamhq/wrtc')
+const RTCPeerConnection = wrtc.RTCPeerConnection ?? wrtc.default?.RTCPeerConnection
+if (typeof RTCPeerConnection !== 'function') throw new Error('missing RTCPeerConnection')
+
+let pc
+let nextRemoteChannelId = 100000
+const channels = new Map()
+let chain = Promise.resolve()
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n')
+}
+
+function respond(id, ok, value, error) {
+  if (id === undefined) return
+  send(ok ? { id, ok: true, value } : { id, ok: false, error: String(error?.message ?? error ?? 'command failed') })
+}
+
+function state() {
+  return {
+    event: 'state',
+    connectionState: pc?.connectionState ?? 'closed',
+    iceConnectionState: pc?.iceConnectionState ?? 'closed',
+    iceGatheringState: pc?.iceGatheringState ?? 'complete',
+    signalingState: pc?.signalingState ?? 'closed',
+  }
+}
+
+function emitState() {
+  send(state())
+}
+
+function normalizeCandidate(candidate) {
+  if (candidate === null || candidate === undefined) return null
+  if (typeof candidate.toJSON === 'function') return candidate.toJSON()
+  return {
+    candidate: candidate.candidate,
+    sdpMid: candidate.sdpMid,
+    sdpMLineIndex: candidate.sdpMLineIndex,
+    usernameFragment: candidate.usernameFragment,
+  }
+}
+
+function attachChannel(channelId, channel) {
+  channels.set(channelId, channel)
+  try { channel.binaryType = 'arraybuffer' } catch {}
+  const emitChannel = () => send({
+    event: 'channel-state',
+    channelId,
+    readyState: channel.readyState,
+    bufferedAmount: channel.bufferedAmount ?? 0,
+  })
+  channel.onopen = emitChannel
+  channel.onclose = emitChannel
+  channel.onerror = () => send({ event: 'channel-error', channelId })
+  channel.onmessage = event => {
+    const data = event.data
+    if (typeof data === 'string') {
+      send({ event: 'channel-message', channelId, text: data })
+      return
+    }
+    send({ event: 'channel-message', channelId, base64: Buffer.from(data).toString('base64') })
+  }
+  send({
+    event: 'datachannel',
+    channelId,
+    label: channel.label,
+    ordered: channel.ordered,
+    readyState: channel.readyState,
+    bufferedAmount: channel.bufferedAmount ?? 0,
+  })
+}
+
+function serializeStats(stats) {
+  const entries = []
+  const push = (key, value) => {
+    const copy = {}
+    for (const [entryKey, entryValue] of Object.entries(value ?? {})) {
+      if (typeof entryValue !== 'function') copy[entryKey] = entryValue
+    }
+    entries.push([String(key), copy])
+  }
+  if (typeof stats?.forEach === 'function') stats.forEach((value, key) => push(key, value))
+  else for (const [key, value] of stats ?? []) push(key, value)
+  return entries
+}
+
+async function handle(command) {
+  const { id, method, payload = {} } = command
+  try {
+    if (method === 'init') {
+      pc = new RTCPeerConnection({ iceServers: payload.iceServers ?? [] })
+      pc.onconnectionstatechange = emitState
+      pc.oniceconnectionstatechange = emitState
+      pc.onicegatheringstatechange = emitState
+      pc.onsignalingstatechange = emitState
+      pc.onicecandidate = event => send({ event: 'icecandidate', candidate: normalizeCandidate(event.candidate) })
+      pc.ondatachannel = event => attachChannel(nextRemoteChannelId++, event.channel)
+      emitState()
+      respond(id, true, {})
+      return
+    }
+    if (method === 'createDataChannel') {
+      const channel = pc.createDataChannel(payload.label, payload.options)
+      attachChannel(payload.channelId, channel)
+      respond(id, true, {})
+      return
+    }
+    if (method === 'createOffer') {
+      respond(id, true, await pc.createOffer())
+      return
+    }
+    if (method === 'createAnswer') {
+      respond(id, true, await pc.createAnswer())
+      return
+    }
+    if (method === 'setLocalDescription') {
+      await pc.setLocalDescription(payload.description)
+      emitState()
+      respond(id, true, {})
+      return
+    }
+    if (method === 'setRemoteDescription') {
+      await pc.setRemoteDescription(payload.description)
+      emitState()
+      respond(id, true, {})
+      return
+    }
+    if (method === 'addIceCandidate') {
+      await pc.addIceCandidate(payload.candidate)
+      respond(id, true, {})
+      return
+    }
+    if (method === 'getStats') {
+      respond(id, true, serializeStats(await pc.getStats()))
+      return
+    }
+    if (method === 'channelSend') {
+      const channel = channels.get(payload.channelId)
+      if (channel === undefined) throw new Error('unknown data channel')
+      channel.send(payload.text ?? Buffer.from(payload.base64, 'base64'))
+      respond(id, true, {})
+      return
+    }
+    if (method === 'channelClose') {
+      channels.get(payload.channelId)?.close()
+      respond(id, true, {})
+      return
+    }
+    if (method === 'close') {
+      for (const channel of channels.values()) {
+        try { channel.close() } catch {}
+      }
+      channels.clear()
+      try { pc?.close() } catch {}
+      respond(id, true, {})
+      setTimeout(() => process.exit(0), 0)
+      return
+    }
+    throw new Error('unknown method ' + method)
+  } catch (error) {
+    respond(id, false, undefined, error)
+  }
+}
+
+const rl = createInterface({ input: process.stdin })
+rl.on('line', line => {
+  chain = chain.then(() => handle(JSON.parse(line))).catch(error => {
+    send({ id: -1, ok: false, error: String(error?.message ?? error) })
+  })
+})
+process.stdin.on('end', () => {
+  try { pc?.close() } catch {}
+  process.exit(0)
+})
+`;
+
+// src/werift-rtc.ts
 var cachedFactory;
-async function loadWeriftFactory() {
-  if (cachedFactory !== void 0) return cachedFactory;
+var cachedWerift;
+var cachedNativeFactory;
+async function loadNodeRtcFactory(options = {}) {
+  const nativeFactory = isElectronRuntime() ? await loadExternalNativeRtcFactory().catch(() => void 0) : await loadNativeRtcFactory().catch(() => void 0);
+  return nativeFactory ?? await loadWeriftFactory(options);
+}
+async function loadWeriftFactory(options = {}) {
+  const cacheable = isCacheableFactoryOptions(options);
+  if (cacheable && cachedFactory !== void 0) return cachedFactory;
   try {
-    const werift = await import("werift");
-    cachedFactory = buildWeriftFactory(werift);
-    return cachedFactory;
+    const werift = cachedWerift ?? await import("werift");
+    cachedWerift = werift;
+    const routeCandidates = options.preferredHostIpv4Candidates ?? await detectRouteHostIpv4Candidates(options.routeTargets ?? [], options.routeProbeTimeoutMs);
+    const factory = buildWeriftFactory(werift, { ...options, preferredHostIpv4Candidates: routeCandidates });
+    if (cacheable) cachedFactory = factory;
+    return factory;
   } catch {
     return void 0;
   }
 }
-function buildWeriftFactory(werift) {
+async function loadNativeRtcFactory() {
+  if (cachedNativeFactory !== void 0) return cachedNativeFactory;
+  try {
+    const wrtc = await import("@roamhq/wrtc");
+    const RTCPeerConnection2 = wrtc.RTCPeerConnection ?? wrtc.default?.RTCPeerConnection;
+    if (RTCPeerConnection2 === void 0) return void 0;
+    cachedNativeFactory = buildNativeRtcFactory(RTCPeerConnection2);
+    return cachedNativeFactory;
+  } catch {
+    return void 0;
+  }
+}
+function isElectronRuntime() {
+  const versions = process.versions;
+  return typeof versions.electron === "string" || process.env.ELECTRON_RUN_AS_NODE === "1";
+}
+function buildNativeRtcFactory(RTCPeerConnection2) {
+  return {
+    create(configuration) {
+      const raw = new RTCPeerConnection2({ iceServers: configuration.iceServers });
+      return {
+        get connectionState() {
+          return raw.connectionState;
+        },
+        get iceConnectionState() {
+          return raw.iceConnectionState;
+        },
+        get iceGatheringState() {
+          return raw.iceGatheringState;
+        },
+        get signalingState() {
+          return raw.signalingState;
+        },
+        set onconnectionstatechange(value) {
+          raw.onconnectionstatechange = value;
+        },
+        get onconnectionstatechange() {
+          return raw.onconnectionstatechange;
+        },
+        set oniceconnectionstatechange(value) {
+          raw.oniceconnectionstatechange = value;
+        },
+        get oniceconnectionstatechange() {
+          return raw.oniceconnectionstatechange;
+        },
+        set onicegatheringstatechange(value) {
+          raw.onicegatheringstatechange = value;
+        },
+        get onicegatheringstatechange() {
+          return raw.onicegatheringstatechange;
+        },
+        set onicecandidate(value) {
+          raw.onicecandidate = value === null ? null : (event) => value({
+            candidate: event.candidate === null ? null : normalizeNativeCandidate(event.candidate)
+          });
+        },
+        get onicecandidate() {
+          return raw.onicecandidate;
+        },
+        set ondatachannel(value) {
+          raw.ondatachannel = value === null ? null : (event) => value({ channel: adaptNativeDataChannel(event.channel) });
+        },
+        get ondatachannel() {
+          return raw.ondatachannel;
+        },
+        createDataChannel(label, options) {
+          return adaptNativeDataChannel(raw.createDataChannel(label, options));
+        },
+        createOffer() {
+          return raw.createOffer();
+        },
+        createAnswer() {
+          return raw.createAnswer();
+        },
+        setLocalDescription(description) {
+          return raw.setLocalDescription(description);
+        },
+        setRemoteDescription(description) {
+          return raw.setRemoteDescription(description);
+        },
+        addIceCandidate(candidate) {
+          return raw.addIceCandidate(candidate);
+        },
+        getStats() {
+          return raw.getStats();
+        },
+        close() {
+          raw.close();
+        }
+      };
+    }
+  };
+}
+function buildWeriftFactory(werift, options = {}) {
   return {
     create(configuration) {
-      const hostIpv4 = detectHostIpv4();
+      const hostIpv4Candidates = detectHostIpv4Candidates(
+        options.interfaces ?? networkInterfaces(),
+        options.preferredHostIpv4Candidates
+      );
+      const allowedHostIpv4 = new Set(hostIpv4Candidates);
       const raw = new werift.RTCPeerConnection({
-        iceServers: configuration.iceServers ?? [],
+        iceServers: orderIceServersForWerift(configuration.iceServers ?? []),
+        iceUseIpv4: true,
         iceUseIpv6: false,
         iceUseLinkLocalAddress: false,
-        ...hostIpv4 === void 0 ? {} : { iceInterfaceAddresses: { udp4: hostIpv4 } }
+        ...hostIpv4Candidates.length === 0 ? {} : {
+          iceAdditionalHostAddresses: hostIpv4Candidates,
+          iceFilterCandidatePair: (pair) => {
+            const allowed = shouldUseCandidatePair(pair, allowedHostIpv4);
+            if (!allowed) {
+              configuration.onDiagnostic?.({
+                type: "candidate-pair-filtered",
+                localCandidate: summarizeWeriftCandidate(localCandidate(pair)),
+                reason: "local-host-not-allowed"
+              });
+            }
+            return allowed;
+          }
+        }
       });
       let onIceCandidate = null;
       let onDataChannel = null;
       raw.onicecandidate = (event) => {
         if (onIceCandidate === null) return;
-        onIceCandidate({ candidate: event.candidate === void 0 ? null : event.candidate.toJSON() });
+        const candidate = event.candidate === void 0 ? null : event.candidate.toJSON();
+        if (candidate !== null && !shouldAdvertiseCandidate(candidate, allowedHostIpv4)) {
+          configuration.onDiagnostic?.({
+            type: "local-candidate-filtered",
+            candidate: summarizeIceCandidate(candidate),
+            reason: "local-host-not-allowed"
+          });
+          return;
+        }
+        onIceCandidate({ candidate });
       };
       raw.ondatachannel = (event) => {
         if (onDataChannel === null) return;
@@ -13721,8 +14677,8 @@ function buildWeriftFactory(werift) {
         get ondatachannel() {
           return onDataChannel;
         },
-        createDataChannel(label, options) {
-          return adaptDataChannel2(raw.createDataChannel(label, { ordered: options?.ordered ?? true }));
+        createDataChannel(label, options2) {
+          return adaptDataChannel2(raw.createDataChannel(label, { ordered: options2?.ordered ?? true }));
         },
         createOffer() {
           return raw.createOffer();
@@ -13804,27 +14760,245 @@ function adaptDataChannel2(raw) {
     }
   };
 }
+function adaptNativeDataChannel(raw) {
+  let onmessage = null;
+  return {
+    get label() {
+      return raw.label;
+    },
+    get ordered() {
+      return raw.ordered;
+    },
+    get readyState() {
+      return raw.readyState;
+    },
+    get bufferedAmount() {
+      return raw.bufferedAmount;
+    },
+    get binaryType() {
+      return raw.binaryType;
+    },
+    set binaryType(value) {
+      raw.binaryType = value;
+    },
+    set onopen(value) {
+      raw.onopen = value;
+    },
+    get onopen() {
+      return raw.onopen;
+    },
+    set onmessage(value) {
+      onmessage = value;
+      raw.onmessage = value === null ? null : (event) => value({ data: normalizeNativeMessageData(event.data) });
+    },
+    get onmessage() {
+      return onmessage;
+    },
+    set onclose(value) {
+      raw.onclose = value;
+    },
+    get onclose() {
+      return raw.onclose;
+    },
+    set onerror(value) {
+      raw.onerror = value;
+    },
+    get onerror() {
+      return raw.onerror;
+    },
+    set onbufferedamountlow(value) {
+      raw.onbufferedamountlow = value;
+    },
+    get onbufferedamountlow() {
+      return raw.onbufferedamountlow;
+    },
+    send(data) {
+      raw.send(typeof data === "string" ? data : Buffer.from(data));
+    },
+    close() {
+      raw.close();
+    }
+  };
+}
 function toArrayBuffer2(data) {
   if (typeof data === "string") return data;
   return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
 }
-function detectHostIpv4() {
-  const preferred = [];
-  const fallback = [];
-  for (const [name2, addresses] of Object.entries(networkInterfaces())) {
-    if (isVirtualInterface(name2)) continue;
+function normalizeNativeCandidate(candidate) {
+  if (typeof candidate.toJSON === "function") return candidate.toJSON();
+  return {
+    candidate: candidate.candidate,
+    sdpMid: candidate.sdpMid,
+    sdpMLineIndex: candidate.sdpMLineIndex,
+    usernameFragment: candidate.usernameFragment
+  };
+}
+function normalizeNativeMessageData(data) {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return data;
+  if (ArrayBuffer.isView(data)) {
+    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+  }
+  return new Uint8Array().buffer;
+}
+function detectHostIpv4Candidates(interfaces, preferredHostIpv4Candidates = []) {
+  const candidates = [];
+  const routePreference = new Map(preferredHostIpv4Candidates.map((ip, index) => [ip, 1e4 - index]));
+  for (const [name2, addresses] of Object.entries(interfaces)) {
+    const interfaceScore = physicalInterfaceScore(name2);
+    if (interfaceScore === void 0) continue;
     for (const address of addresses ?? []) {
-      if (address.internal || address.family !== "IPv4") continue;
+      if (address.internal || !isIpv4Family(address.family)) continue;
       const ip = address.address;
-      if (ip.startsWith("127.") || ip.startsWith("169.254.") || isCgnat(ip)) continue;
-      if (isPrivate(ip)) preferred.push(ip);
-      else fallback.push(ip);
+      if (!isUsableIpv4(ip)) continue;
+      candidates.push({
+        name: name2,
+        ip,
+        score: interfaceScore + (isPrivate(ip) ? 1e3 : 0) + (routePreference.get(ip) ?? 0)
+      });
     }
   }
-  return preferred[0] ?? fallback[0];
+  candidates.sort((left, right) => {
+    const score = right.score - left.score;
+    if (score !== 0) return score;
+    const name2 = left.name.localeCompare(right.name, "en");
+    return name2 === 0 ? left.ip.localeCompare(right.ip, "en", { numeric: true }) : name2;
+  });
+  return [...new Set(candidates.map((candidate) => candidate.ip))];
+}
+async function detectRouteHostIpv4Candidates(targets, timeoutMs = 500) {
+  const detected = await Promise.all(targets.map(async (target) => {
+    const routeTarget = parseRouteTarget(target);
+    return routeTarget === void 0 ? void 0 : await detectRouteHostIpv4(routeTarget, timeoutMs).catch(() => void 0);
+  }));
+  return [...new Set(detected.filter((ip) => ip !== void 0 && isUsableIpv4(ip)))];
+}
+function shouldUseCandidatePair(pair, allowedHostIpv4) {
+  if (allowedHostIpv4.size === 0) return true;
+  const candidate = localCandidate(pair);
+  if (candidate === void 0) return true;
+  return shouldUseLocalCandidate(candidate, allowedHostIpv4);
+}
+function shouldAdvertiseCandidate(candidate, allowedHostIpv4) {
+  if (allowedHostIpv4.size === 0) return true;
+  const parsed = parseIceCandidate(candidate);
+  if (parsed === void 0) return true;
+  return shouldUseLocalCandidate(parsed, allowedHostIpv4);
+}
+function shouldUseLocalCandidate(candidate, allowedHostIpv4) {
+  if (candidate.type === "host") return candidate.host !== void 0 && allowedHostIpv4.has(candidate.host);
+  if (candidate.type === "srflx" && candidate.relatedAddress !== void 0) {
+    return allowedHostIpv4.has(candidate.relatedAddress);
+  }
+  return true;
+}
+function localCandidate(pair) {
+  try {
+    return pair.localCandidate;
+  } catch {
+    return void 0;
+  }
+}
+function summarizeWeriftCandidate(candidate) {
+  if (candidate === void 0) return void 0;
+  const address = summarizeAddress(candidate.host);
+  const related = summarizeAddress(candidate.relatedAddress);
+  return {
+    candidateType: candidate.type === "host" || candidate.type === "srflx" || candidate.type === "prflx" || candidate.type === "relay" ? candidate.type : "unknown",
+    ...address,
+    ...candidate.relatedAddress === void 0 ? {} : { relatedAddressFamily: related.addressFamily, relatedAddressScope: related.addressScope }
+  };
+}
+function orderIceServersForWerift(iceServers) {
+  return iceServers.map((server) => {
+    const urls = Array.isArray(server.urls) ? [...server.urls] : [server.urls];
+    urls.sort((left, right) => iceUrlScore(left) - iceUrlScore(right));
+    return { ...server, urls: Array.isArray(server.urls) ? urls : urls[0] ?? server.urls };
+  });
+}
+function iceUrlScore(url) {
+  const value = url.trim().toLowerCase();
+  if (value.startsWith("stun:") || value.startsWith("stuns:")) return 0;
+  if (value.startsWith("turn:") && value.includes("transport=tcp")) return 10;
+  if (value.startsWith("turns:") && value.includes("transport=tcp")) return 20;
+  if (value.startsWith("turn:") && value.includes("transport=udp")) return 30;
+  if (value.startsWith("turns:")) return 40;
+  if (value.startsWith("turn:")) return 50;
+  return 100;
+}
+function parseRouteTarget(value) {
+  try {
+    const url = new URL(value);
+    const port = Number(url.port || (url.protocol === "http:" ? "80" : "443"));
+    if (!Number.isSafeInteger(port) || port <= 0 || port > 65535 || url.hostname.length === 0) return void 0;
+    return { host: url.hostname, port };
+  } catch {
+    return void 0;
+  }
+}
+async function detectRouteHostIpv4(target, timeoutMs) {
+  const socket = createSocket("udp4");
+  try {
+    return await new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve2(void 0);
+      }, timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.off("error", onError);
+      };
+      const onError = (error) => {
+        cleanup();
+        reject(error);
+      };
+      socket.once("error", onError);
+      socket.connect(target.port, target.host, () => {
+        cleanup();
+        const address = socket.address();
+        resolve2(typeof address === "string" ? void 0 : address.address);
+      });
+    });
+  } finally {
+    socket.close();
+  }
+}
+function isCacheableFactoryOptions(options) {
+  return options.interfaces === void 0 && options.preferredHostIpv4Candidates === void 0 && options.routeTargets === void 0;
+}
+function parseIceCandidate(candidate) {
+  const value = candidate.candidate?.trim();
+  if (value === void 0 || value.length === 0) return void 0;
+  const parts = value.replace(/^candidate:/, "").split(/\s+/);
+  const typeIndex = parts.indexOf("typ");
+  if (typeIndex < 0) return void 0;
+  const host = parts[4];
+  const type = parts[typeIndex + 1];
+  const relatedAddressIndex = parts.indexOf("raddr");
+  return {
+    ...host === void 0 ? {} : { host },
+    ...type === void 0 ? {} : { type },
+    ...relatedAddressIndex < 0 || parts[relatedAddressIndex + 1] === void 0 ? {} : { relatedAddress: parts[relatedAddressIndex + 1] }
+  };
+}
+function physicalInterfaceScore(name2) {
+  const value = name2.toLowerCase();
+  if (/^(utun|tun|tap|ppp|bridge|awdl|llw|gif|stf|anpi|ap\d|vmnet|veth|docker|br-|vboxnet|lo)/.test(value)) {
+    return void 0;
+  }
+  if (/^(eth|eno|ens|enp)/.test(value)) return 500;
+  if (/^(en|wlan|wl|wifi|wi-fi)/.test(value)) return 450;
+  return 300;
+}
+function isIpv4Family(family) {
+  return family === "IPv4" || family === 4;
 }
-function isVirtualInterface(name2) {
-  return /^(utun|ppp|bridge|awdl|llw|gif|stf|anpi|ap\d|en[1-9]\d*$)/i.test(name2);
+function isUsableIpv4(ip) {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  if (parts[0] === 0 || parts[0] === 127 || parts[0] >= 224) return false;
+  if (parts[0] === 169 && parts[1] === 254) return false;
+  return !isCgnat(ip);
 }
 function isCgnat(ip) {
   const parts = ip.split(".").map(Number);
@@ -13841,8 +15015,9 @@ function isPrivate(ip) {
 // src/client-runtime.ts
 var REMOTE_COMMAND_LIST_MIN_VERSION = [0, 3, 16];
 var REMOTE_FILE_VIEWER_MIN_VERSION = [0, 3, 17];
+var DIRECT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 12e3;
 var ClientModeRuntime = class {
-  constructor(config, identities, server, apiProxy, typertGateway, logger, host, rtcFactoryProvider = loadWeriftFactory) {
+  constructor(config, identities, server, apiProxy, typertGateway, logger, host, rtcFactoryProvider = loadNodeRtcFactory) {
     this.config = config;
     this.identities = identities;
     this.server = server;
@@ -13879,6 +15054,7 @@ var ClientModeRuntime = class {
       available: this.config.serverUrl !== void 0,
       identityReady: this.identity !== void 0,
       deviceId: this.identity?.deviceId,
+      deviceName: this.identity?.name,
       serverUrl: this.config.serverUrl,
       ...this.proxySwitch.status(),
       connected: this.connected !== void 0,
@@ -14077,61 +15253,76 @@ var ClientModeRuntime = class {
     const presence = await this.server.presenceFor(targetDeviceId);
     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().catch(() => void 0);
+    const rtcFactory = this.config.forceRelay ? void 0 : await this.rtcFactoryProvider({ routeTargets: [this.server.baseUrl] }).catch(() => void 0);
     let webRtcFallback = false;
-    const createTransport = (relayOnly) => new AdaptiveTransport(
+    const createTransport = (attempt) => new AdaptiveTransport(
       websocketUrl(this.server.baseUrl),
       {
         role: "client",
         deviceId: identity.deviceId,
         accessToken: credentials.accessToken,
         targetDeviceId,
-        forceRelay: this.config.forceRelay || relayOnly,
-        preferredTransports: this.config.forceRelay || relayOnly ? ["relay"] : ["lan", "p2p", "turn", "relay"],
-        ...rtcFactory === void 0 || relayOnly ? {} : { rtcFactory },
-        fetchIceServers: async (connectionId) => this.server.turnCredentials(connectionId),
-        onWebRtcFallback: (error) => {
+        forceRelay: this.config.forceRelay || attempt === "relay",
+        preferredTransports: preferredTransportsForAttempt(attempt),
+        negotiateTimeoutMs: attempt === "direct" ? DIRECT_WEBRTC_NEGOTIATE_TIMEOUT_MS : void 0,
+        ...rtcFactory === void 0 || attempt === "relay" ? {} : { rtcFactory },
+        fetchIceServers: async (connectionId) => iceServersForAttempt(attempt, await this.server.turnCredentials(connectionId)),
+        onWebRtcFallback: (error, diagnostics) => {
           webRtcFallback = true;
-          this.logger.warn("remote Harness WebRTC failed; using relay", {
+          this.logger.warn(attempt === "direct" ? "remote Harness direct WebRTC failed; trying TURN" : "remote Harness TURN WebRTC failed; using relay", {
             targetDeviceId: shortId(target.deviceId),
-            reason: diagnosticReason(error)
+            attempt,
+            reason: diagnosticReason(error),
+            ...webrtcDiagnosticsLogFields(diagnostics)
           });
         }
       }
     );
-    let transport = createTransport(false);
-    let client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 6e4);
+    const attempts = this.config.forceRelay || rtcFactory === void 0 ? ["relay"] : ["direct", "turn", "relay"];
+    let transport;
+    let client;
     try {
-      await client.connect();
-      signal?.throwIfAborted();
-      if (webRtcFallback) {
-        await client.close();
-        transport = createTransport(true);
+      for (const attempt of attempts) {
+        webRtcFallback = false;
+        transport = createTransport(attempt);
         client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 6e4);
         await client.connect();
         signal?.throwIfAborted();
-        this.logger.info("remote Harness relay fallback re-established", {
-          targetDeviceId: shortId(target.deviceId)
-        });
+        if (attempt === "relay" || !webRtcFallback) break;
+        await client.close();
+        client = void 0;
+        transport = void 0;
+        if (attempt === "turn") {
+          this.logger.info("remote Harness relay fallback re-established", {
+            targetDeviceId: shortId(target.deviceId)
+          });
+        }
       }
-      client.onClose(() => {
-        if (this.connected?.client !== client) return;
+      if (client === void 0 || transport === void 0) {
+        throw new ClientModeError("CONNECTION_FAILED", "Unable to establish a remote transport.", true);
+      }
+      const connectedClient = client;
+      const connectedTransport = transport;
+      connectedClient.onClose(() => {
+        if (this.connected?.client !== connectedClient) return;
         this.connected = void 0;
         this.pendingWorkspaceSelection = void 0;
         this.proxySwitch.selectLocal();
         this.gatewaySwitch.selectLocal();
-        void client.close().catch(() => void 0);
+        void connectedClient.close().catch(() => void 0);
         this.logger.warn("remote Harness transport closed; falling back to local mode", {
           targetDeviceId: shortId(target.deviceId)
         });
       });
+      const connectionDetails = await connectedTransport.connectionDetails().catch(() => void 0);
       this.logger.info("remote Harness transport ready", {
         targetDeviceId: shortId(target.deviceId),
-        transport: client.getStats().mode
+        transport: connectedClient.getStats().mode,
+        ...webrtcDiagnosticsLogFields(connectionDetails?.webRtc?.diagnostics)
       });
-      return { client, target, transport, features: remoteHostFeatures(serverDevice.clientVersion) };
+      return { client: connectedClient, target, transport: connectedTransport, features: remoteHostFeatures(serverDevice.clientVersion) };
     } catch (error) {
-      await client.close().catch(() => void 0);
+      await client?.close().catch(() => void 0);
       throw error;
     }
   }
@@ -14278,6 +15469,20 @@ function websocketUrl(baseUrl) {
   url.pathname = `${url.pathname.replace(/\/$/, "")}/ws/v1/connect`;
   return url.toString();
 }
+function webrtcDiagnosticsLogFields(diagnostics) {
+  if (diagnostics === void 0) return {};
+  return {
+    rtcConnectionState: diagnostics.connectionState,
+    rtcIceConnectionState: diagnostics.iceConnectionState,
+    rtcIceGatheringState: diagnostics.iceGatheringState,
+    rtcLocalCandidates: diagnostics.localCandidates,
+    rtcRemoteCandidates: diagnostics.remoteCandidates,
+    rtcCandidatePairs: diagnostics.candidatePairs,
+    rtcFilteredLocalCandidates: diagnostics.filteredLocalCandidates,
+    rtcFilteredCandidatePairs: diagnostics.filteredCandidatePairs,
+    ...diagnostics.selectedPath === void 0 ? {} : { rtcSelectedPath: diagnostics.selectedPath }
+  };
+}
 function record(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new ClientModeError("INVALID_MESSAGE", "The control request payload is invalid.");
@@ -14355,6 +15560,14 @@ function diagnosticReason(error) {
   const message = error.message.replace(/[\r\n\t]+/g, " ").slice(0, 240);
   return code === void 0 ? message : `${code}: ${message}`;
 }
+function preferredTransportsForAttempt(attempt) {
+  if (attempt === "direct") return ["lan", "p2p", "relay"];
+  if (attempt === "turn") return ["turn", "relay"];
+  return ["relay"];
+}
+function iceServersForAttempt(attempt, iceServers) {
+  return attempt === "direct" ? stunOnlyIceServers(iceServers) : iceServers;
+}
 
 // src/control-runtime.ts
 import { hostname as hostname2 } from "node:os";
@@ -14363,7 +15576,7 @@ import { hostname as hostname2 } from "node:os";
 import { createHash } from "node:crypto";
 import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname as dirname2, join as join2 } from "node:path";
 var identitySchema = external_exports.object({
   schemaVersion: external_exports.literal(1),
   deviceId: external_exports.string().uuid(),
@@ -14392,14 +15605,14 @@ var IdentityStore = class {
   peers = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     const env = options.env ?? process.env;
-    const dshHome = env.DSH_HOME || join(options.homeDirectory ?? homedir(), ".dsh");
-    this.directory = options.directory ?? join(dshHome, "remote");
+    const dshHome = env.DSH_HOME || join2(options.homeDirectory ?? homedir(), ".dsh");
+    this.directory = options.directory ?? join2(dshHome, "remote");
   }
   async loadOrCreate(deviceName) {
     await mkdir(this.directory, { recursive: true, mode: 448 });
     await chmod(this.directory, 448);
-    const devicePath = join(this.directory, "device.json");
-    const keyPath = join(this.directory, "device.key");
+    const devicePath = join2(this.directory, "device.json");
+    const keyPath = join2(this.directory, "device.key");
     const [hasDevice, hasKey] = await Promise.all([exists(devicePath), exists(keyPath)]);
     if (hasDevice !== hasKey) {
       throw new IdentityInvalidError("device identity is incomplete; repair it explicitly before reconnecting");
@@ -14468,7 +15681,7 @@ var IdentityStore = class {
     return removed;
   }
   async loadPeers() {
-    const path = join(this.directory, "trusted-peers.json");
+    const path = join2(this.directory, "trusted-peers.json");
     if (!await exists(path)) {
       await atomicJsonWrite(path, { schemaVersion: 1, peers: [] }, 384);
     }
@@ -14484,7 +15697,7 @@ var IdentityStore = class {
     this.peers = peers;
   }
   async savePeers() {
-    await atomicJsonWrite(join(this.directory, "trusted-peers.json"), {
+    await atomicJsonWrite(join2(this.directory, "trusted-peers.json"), {
       schemaVersion: 1,
       peers: [...this.peers.values()]
     }, 384);
@@ -14493,7 +15706,7 @@ var IdentityStore = class {
 function serverStorageDirectory(root, serverUrl, role) {
   const origin = new URL(serverUrl).origin;
   const scope = createHash("sha256").update(origin).digest("hex").slice(0, 24);
-  return join(root, "servers", scope, role);
+  return join2(root, "servers", scope, role);
 }
 function fingerprint(publicKey) {
   const compact = createHash("sha256").update(fromBase64Url2(publicKey)).digest("hex").slice(0, 12).toUpperCase();
@@ -14511,7 +15724,7 @@ async function atomicJsonWrite(path, value, mode) {
 `, mode);
 }
 async function atomicTextWrite(path, value, mode) {
-  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await mkdir(dirname2(path), { recursive: true, mode: 448 });
   const temporary = `${path}.${process.pid}.${uuidV7()}.tmp`;
   await writeFile(temporary, value, { encoding: "utf8", mode, flag: "wx" });
   await chmod(temporary, mode);
@@ -14536,7 +15749,7 @@ function safeErrorMessage(error) {
 
 // src/server-credentials.ts
 import { chmod as chmod2, mkdir as mkdir2, readFile as readFile2, rename as rename2, rm as rm2, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname3, join as join3 } from "node:path";
 var credentialSchema = external_exports.object({
   schemaVersion: external_exports.literal(1),
   serverUrl: external_exports.string().url(),
@@ -14551,7 +15764,7 @@ var credentialSchema = external_exports.object({
 var ServerCredentialStore = class {
   path;
   constructor(directory) {
-    this.path = join2(directory, "server-credentials.json");
+    this.path = join3(directory, "server-credentials.json");
   }
   async load(serverUrl, deviceId) {
     if (!await exists2(this.path)) return void 0;
@@ -14578,7 +15791,7 @@ var ServerCredentialsInvalidError = class extends Error {
   code = "SERVER_CREDENTIALS_INVALID";
 };
 async function atomicWrite(path, contents) {
-  await mkdir2(dirname2(path), { recursive: true, mode: 448 });
+  await mkdir2(dirname3(path), { recursive: true, mode: 448 });
   const temporary = `${path}.${process.pid}.${uuidV7()}.tmp`;
   await writeFile2(temporary, contents, { encoding: "utf8", mode: 384, flag: "wx" });
   await chmod2(temporary, 384);
@@ -14788,6 +16001,7 @@ var PluginControlRuntime = class {
     return {
       mode: "local",
       available: false,
+      deviceName: hostname2(),
       hostAuthorizationAvailable: this.host !== void 0,
       ...this.host === void 0 ? {} : { host: this.host.hostStatus() }
     };
@@ -15037,7 +16251,7 @@ function shortId2(value) {
 
 // src/harness-version.ts
 import { readFile as readFile3 } from "node:fs/promises";
-import { dirname as dirname3, isAbsolute, join as join3 } from "node:path";
+import { dirname as dirname4, isAbsolute, join as join4 } from "node:path";
 var LEGACY_PLACEHOLDER_VERSION = "0.0.1";
 function normalizeHarnessVersion(value) {
   if (typeof value !== "string") return void 0;
@@ -15051,14 +16265,14 @@ function selectHarnessVersion(reportedVersion, distributionVersion) {
 }
 async function readHarnessDistributionVersion(entrypoint = process.argv[1]) {
   if (entrypoint === void 0 || !isAbsolute(entrypoint)) return void 0;
-  let directory = dirname3(entrypoint);
+  let directory = dirname4(entrypoint);
   for (let depth = 0; depth < 8; depth += 1) {
     try {
-      const manifest = JSON.parse(await readFile3(join3(directory, "package.json"), "utf8"));
+      const manifest = JSON.parse(await readFile3(join4(directory, "package.json"), "utf8"));
       if (manifest.name === "@deepseek-ai/dsh") return normalizeHarnessVersion(manifest.version);
     } catch {
     }
-    const parent = dirname3(directory);
+    const parent = dirname4(directory);
     if (parent === directory) break;
     directory = parent;
   }
@@ -15297,7 +16511,7 @@ function isOversizedListing(value) {
 }
 
 // src/server-connection.ts
-var DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 8e3;
+var DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS = 12e3;
 var HostServerConnection = class {
   constructor(config, identity, identities, api, connections, logger, createWebSocket = (url) => new WebSocket(url), rtcFactoryProvider, hostCapabilities = () => ["harness.api.v1"], harnessVersion) {
     this.config = config;
@@ -15587,6 +16801,7 @@ var HostServerConnection = class {
       connectionId: payload.connectionId,
       membershipId: descriptor.membershipId,
       peer,
+      preferredTransports: payload.preferredTransports,
       noise,
       transport: "negotiating"
     });
@@ -15676,13 +16891,24 @@ var HostServerConnection = class {
         code: errorCode(error)
       });
     }
+    if (!tunnel.preferredTransports.includes("turn")) iceServers = stunOnlyIceServers(iceServers);
     const rtc = new RtcDataChannelTransport({
       role: "responder",
       factory: this.rtcFactory,
       iceServers,
       onSignal: (signal) => this.sendRtcSignal(tunnel, signal),
       negotiateTimeoutMs: DEFAULT_WEBRTC_NEGOTIATE_TIMEOUT_MS,
-      label: `host<-${tunnel.peer.deviceId}`
+      label: `host<-${tunnel.peer.deviceId}`,
+      onDiagnostic: (event) => {
+        if (event.type !== "local-candidate-filtered" && event.type !== "candidate-pair-filtered") return;
+        this.logger.debug("webrtc candidate filtered", {
+          connectionId: shortId3(tunnel.connectionId),
+          peerDeviceId: shortId3(tunnel.peer.deviceId),
+          type: event.type,
+          reason: event.reason,
+          candidate: event.type === "local-candidate-filtered" ? event.candidate : event.localCandidate
+        });
+      }
     });
     tunnel.rtc = rtc;
     rtc.onMessage((data) => tunnel.channel?.receive(void 0, data));
@@ -15724,7 +16950,8 @@ var HostServerConnection = class {
     this.logger.info("webrtc data channel ready", {
       connectionId: shortId3(tunnel.connectionId),
       peerDeviceId: shortId3(tunnel.peer.deviceId),
-      transport: tunnel.transportMode ?? selected
+      transport: tunnel.transportMode ?? selected,
+      ...webrtcDiagnosticsLogFields2(rtcDiagnostics(tunnel.rtc))
     });
   }
   async handleRtcFailed(tunnel, rtc, error) {
@@ -15732,7 +16959,8 @@ var HostServerConnection = class {
     if (tunnel.transport === "p2p" || tunnel.transport === "turn") {
       this.logger.warn("webrtc data channel failed; disconnecting peer", {
         connectionId: shortId3(tunnel.connectionId),
-        reason: diagnosticReason4(error)
+        reason: diagnosticReason4(error),
+        ...webrtcDiagnosticsLogFields2(rtcDiagnostics(rtc))
       });
       await this.dropTunnel(tunnel.connectionId, "CONNECTION_FAILED");
       return;
@@ -15742,7 +16970,8 @@ var HostServerConnection = class {
     await rtc.close();
     this.logger.warn("webrtc negotiation failed; falling back to relay", {
       connectionId: shortId3(tunnel.connectionId),
-      reason: diagnosticReason4(error)
+      reason: diagnosticReason4(error),
+      ...webrtcDiagnosticsLogFields2(rtcDiagnostics(rtc))
     });
   }
   sendTransportSelected(tunnel, transport) {
@@ -15969,6 +17198,28 @@ function diagnosticReason4(error) {
   const message = asError2(error).message.replace(/[\r\n]+/g, " ").slice(0, 160);
   return message || "Unknown Server connection error.";
 }
+function webrtcDiagnosticsLogFields2(diagnostics) {
+  if (diagnostics === void 0) return {};
+  return {
+    rtcConnectionState: diagnostics.connectionState,
+    rtcIceConnectionState: diagnostics.iceConnectionState,
+    rtcIceGatheringState: diagnostics.iceGatheringState,
+    rtcLocalCandidates: diagnostics.localCandidates,
+    rtcRemoteCandidates: diagnostics.remoteCandidates,
+    rtcCandidatePairs: diagnostics.candidatePairs,
+    rtcFilteredLocalCandidates: diagnostics.filteredLocalCandidates,
+    rtcFilteredCandidatePairs: diagnostics.filteredCandidatePairs,
+    ...diagnostics.selectedPath === void 0 ? {} : { rtcSelectedPath: diagnostics.selectedPath }
+  };
+}
+function rtcDiagnostics(rtc) {
+  try {
+    const candidate = rtc;
+    return typeof candidate.diagnostics === "function" ? candidate.diagnostics() : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function errorCode(error) {
   return error instanceof ServerApiError || error instanceof ControlConnectionError ? error.code : "CONNECTION_FAILED";
 }
@@ -15986,7 +17237,7 @@ function closeCode(code) {
 // src/remote-directory-browser.ts
 import { readdir, stat as stat3 } from "node:fs/promises";
 import { homedir as homedir2, platform as platform2 } from "node:os";
-import { basename, dirname as dirname4, isAbsolute as isAbsolute2, parse, resolve } from "node:path";
+import { basename, dirname as dirname5, isAbsolute as isAbsolute2, parse, resolve } from "node:path";
 var MAX_ENTRIES = 500;
 async function listRemoteDirectory(path, signal) {
   signal?.throwIfAborted();
@@ -16019,7 +17270,7 @@ function crumbs(path) {
   let current = path;
   while (current !== root) {
     segments.unshift(basename(current));
-    current = dirname4(current);
+    current = dirname5(current);
   }
   for (const segment of segments) {
     current = resolve(current, segment);
@@ -16070,7 +17321,11 @@ var transferReadSchema = external_exports.object({ transferId: transferIdSchema,
 var transferCloseSchema = external_exports.object({ transferId: transferIdSchema }).strict();
 var commandExecuteSchema = external_exports.object({
   agentId: external_exports.string().min(1).max(128),
-  line: external_exports.string().min(1).max(2048)
+  line: external_exports.string().min(1).max(2048),
+  // The official Harness command endpoint requires the `images` wire field.
+  // Remote command execution keeps attachments out of scope, so only an empty
+  // list is accepted and legacy clients that omit it are normalized below.
+  images: external_exports.array(external_exports.never()).length(0).optional()
 }).strict();
 var commandListSchema = external_exports.object({
   agentId: external_exports.string().min(1).max(128)
@@ -16183,11 +17438,12 @@ var API_TRANSFER_IDLE_MS = 2 * 6e4;
 var INLINE_TRANSFER_RESPONSE_BYTES = 2 * 1024 * 1024;
 var SESSION_HISTORY_PAGE_SIZES = [50, 30, 20, 12, 6, 3, 1];
 var HarnessApiBridge = class {
-  constructor(api, publish, maxStreams = 8, logger, typertGateway) {
+  constructor(api, publish, maxStreams = 8, logger, typertGateway, harnessVersion) {
     this.api = api;
     this.publish = publish;
     this.maxStreams = maxStreams;
     this.logger = logger;
+    this.harnessVersion = harnessVersion;
     this.methods = createMethodMap(api, typertGateway);
     this.mux = api.events.mux.bind(api.events);
     this.host = api.events.host.bind(api.events);
@@ -16225,6 +17481,7 @@ var HarnessApiBridge = class {
         const value = await listRemoteDirectory(typeof payload.path === "string" ? payload.path : void 0, signal);
         response = { rpcId: params.rpcId, result: { ok: true, value } };
       }
+      if (params.method === "host.describe") response = normalizeHostDescribeVersion(response, this.harnessVersion);
       this.logger?.debug("harness api call ok", {
         method: params.method,
         durationMs: Math.round(performance.now() - startedAt)
@@ -16455,6 +17712,24 @@ function needsRemoteDirectoryFallback(response) {
   const result = response.result;
   return typeof result === "object" && result !== null && "ok" in result && result.ok === false && "error" in result && typeof result.error === "object" && result.error !== null && "code" in result.error && result.error.code === "directory-picker-unavailable";
 }
+function normalizeHostDescribeVersion(response, harnessVersion) {
+  if (!response.result.ok || harnessVersion === void 0) return response;
+  const value = response.result.value;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return response;
+  const description = value;
+  const selectedVersion = selectHarnessVersion(
+    normalizeHarnessVersion(description.version),
+    harnessVersion
+  );
+  if (selectedVersion === void 0 || description.version === selectedVersion) return response;
+  return {
+    ...response,
+    result: {
+      ...response.result,
+      value: { ...description, version: selectedVersion }
+    }
+  };
+}
 function createMethodMap(api, typertGateway) {
   const domains = api;
   const methods = /* @__PURE__ */ new Map();
@@ -16464,7 +17739,8 @@ function createMethodMap(api, typertGateway) {
       const [namespace, commandMethod] = method.split(".");
       const implementation2 = async (request, signal) => {
         if (commandMethod === "execute") {
-          const args2 = commandExecuteSchema.parse(request.payload);
+          const payload = commandExecuteSchema.parse(request.payload);
+          const args2 = { ...payload, images: payload.images ?? [] };
           const value2 = await typertGateway.invoke({
             namespace,
             method: "execute",
@@ -16775,7 +18051,8 @@ var HostPluginRuntime = class {
         (event, data) => send(createEvent(event, data)),
         void 0,
         this.logger,
-        typertGateway?.()
+        typertGateway?.(),
+        this.harnessVersion
       );
       const fileViewer = new RemoteFileViewerBridge(
         () => this.fileViewerHost?.(),
@@ -16803,6 +18080,7 @@ var HostPluginRuntime = class {
     });
     if (this.serverApi !== void 0) {
       this.harnessVersion = await this.readHarnessVersion();
+      this.serverApi.setHarnessVersion(this.harnessVersion);
       this.serverApi.bindIdentity(this.identity);
       this.serverConnection = this.createServerConnection(this.identity);
       this.serverConnection.start();
@@ -16920,7 +18198,7 @@ var HostPluginRuntime = class {
       this.connections,
       this.logger,
       void 0,
-      this.config.forceRelay ? void 0 : loadWeriftFactory,
+      this.config.forceRelay ? void 0 : () => loadNodeRtcFactory({ routeTargets: this.config.serverUrl === void 0 ? [] : [this.config.serverUrl] }),
       () => this.fileViewerHost?.() === void 0 ? ["harness.api.v1"] : ["harness.api.v1", "fileviewer.read.v1"],
       this.harnessVersion
     );
@@ -17018,13 +18296,13 @@ function decodeBase64(value) {
 }
 
 // src/index.ts
-var name = "dsh-remote";
+var name = "ds-harness-remote";
 function apply(ctx, input = {}) {
   ctx.inject(["settings", "apiProxy", "connection", "typertGateway"], (runtimeContext) => activate(runtimeContext, input));
 }
 async function activate(ctx, input) {
   const settings = ctx.get("settings");
-  const settingsScope = settings?.register(settingsNamespace("dsh-remote"), Config, {
+  const settingsScope = settings?.register(settingsNamespace("ds-harness-remote"), Config, {
     base: input,
     applies: "restart",
     validate: (value) => {