neko-harness 0.4.0 → 0.4.2

package/dist/gateway.js

@@ -16593,7 +16593,7 @@ function parseGatewayArgs(argv) {
 // packages/gateway/src/gateway.ts
 import { randomUUID as randomUUID5 } from "crypto";
 import { mkdir as mkdir6, readFile as readFile7, writeFile as writeFile5 } from "fs/promises";
-import { basename as basename4, dirname as dirname9, join as join12 } from "path";
+import { basename as basename4, dirname as dirname9, join as join13 } from "path";
 import { createHost as createHost3 } from "@earendil-works/chord";
 import { BACKGROUND_CONTEXT as BACKGROUND_CONTEXT4 } from "@earendil-works/chord/context";
 
@@ -21124,7 +21124,9 @@ var listenerStateSchema = Type5.Union([
   Type5.Object({
     status: Type5.Literal("listening"),
     address: Type5.String(),
-    port: Type5.Integer({ minimum: 1, maximum: 65535 })
+    port: Type5.Integer({ minimum: 1, maximum: 65535 }),
+    bindAddress: Type5.Optional(Type5.String()),
+    mode: Type5.Optional(Type5.Union([Type5.Literal("direct"), Type5.Literal("wsl-relay")]))
   }),
   Type5.Object({ status: Type5.Literal("error"), error: Type5.String() }),
   Type5.Object({ status: Type5.Literal("stopping") })
@@ -21153,7 +21155,11 @@ var NekoMobileAdmin = contract("neko.mobile-admin", {
               Type5.Null()
             ]),
             devices: Type5.Array(adminDeviceSchema),
-            lastConnectedAddress: Type5.Union([Type5.String(), Type5.Null()])
+            lastConnectedAddress: Type5.Union([Type5.String(), Type5.Null()]),
+            wsl: Type5.Optional(Type5.Union([
+              Type5.Object({ interop: Type5.Boolean(), error: Type5.Union([Type5.String(), Type5.Null()]) }),
+              Type5.Null()
+            ]))
           })
         ],
         enable: [
@@ -21164,7 +21170,9 @@ var NekoMobileAdmin = contract("neko.mobile-admin", {
           Type5.Object({
             status: Type5.Literal("listening"),
             address: Type5.String(),
-            port: Type5.Integer({ minimum: 1, maximum: 65535 })
+            port: Type5.Integer({ minimum: 1, maximum: 65535 }),
+            bindAddress: Type5.Optional(Type5.String()),
+            mode: Type5.Optional(Type5.Union([Type5.Literal("direct"), Type5.Literal("wsl-relay")]))
           })
         ],
         disable: [Type5.Null(), listenerStateSchema],
@@ -21250,7 +21258,7 @@ function createMobileAdminFactory(deps) {
 // packages/gateway/src/mobile/listener.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { createServer } from "https";
-import { hostname, networkInterfaces } from "os";
+import { hostname } from "os";
 import { createHost as createHost2, memoryLinkPair } from "@earendil-works/chord";
 import { WebSocketServer } from "ws";
 
@@ -21813,7 +21821,7 @@ import { Check as Check2 } from "typebox/value";
 import { createHost } from "@earendil-works/chord";
 
 // packages/core/src/application-version.ts
-var RUNNING_VERSION = "0.4.0";
+var RUNNING_VERSION = "0.4.2";
 var APPLICATION_PROTOCOL = 4;
 function stableVersion(value) {
   return typeof value === "string" && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(value) && value.split(".").every((n) => Number.isSafeInteger(Number(n)));
@@ -23749,6 +23757,70 @@ class MobileCertificate {
   }
 }
 
+// packages/gateway/src/mobile/network.ts
+import { networkInterfaces } from "os";
+var VIRTUAL_INTERFACE_PREFIXES = [
+  "anpi",
+  "awdl",
+  "bridge",
+  "docker",
+  "gif",
+  "ipsec",
+  "llw",
+  "ppp",
+  "stf",
+  "tap",
+  "tun",
+  "utun",
+  "vboxnet",
+  "veth",
+  "virbr",
+  "vmnet"
+];
+var VIRTUAL_INTERFACE_KEYWORDS = ["hyper-v", "virtual", "virtualbox", "vmware", "vpn", "wsl"];
+function isVirtualInterfaceName(name) {
+  const lower = name.toLowerCase();
+  if (VIRTUAL_INTERFACE_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+    return true;
+  return VIRTUAL_INTERFACE_KEYWORDS.some((keyword) => lower.includes(keyword));
+}
+function isBenchmarkAddress(address) {
+  return address.startsWith("198.18.") || address.startsWith("198.19.");
+}
+function collectListenCandidates(interfaces, skipVirtual) {
+  const candidates = [];
+  for (const [name, infos] of Object.entries(interfaces)) {
+    if (infos === undefined)
+      continue;
+    if (skipVirtual && isVirtualInterfaceName(name))
+      continue;
+    for (const info of infos) {
+      if (info.family !== "IPv4" || info.internal)
+        continue;
+      if (info.address.startsWith("169.254."))
+        continue;
+      if (skipVirtual && isBenchmarkAddress(info.address))
+        continue;
+      candidates.push(info.address);
+    }
+  }
+  return candidates.sort();
+}
+function mobileListenCandidates(interfaces) {
+  const source = interfaces ?? networkInterfaces();
+  const filtered = collectListenCandidates(source, true);
+  return filtered.length > 0 ? filtered : collectListenCandidates(source, false);
+}
+function prioritizeListenCandidate(candidates, lastConnectedAddress) {
+  if (lastConnectedAddress === null || !candidates.includes(lastConnectedAddress))
+    return [...candidates];
+  return [lastConnectedAddress, ...candidates.filter((candidate) => candidate !== lastConnectedAddress)];
+}
+function isIpv4Literal(address) {
+  const parts = address.split(".");
+  return parts.length === 4 && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+
 // packages/gateway/src/mobile/pairing.ts
 import { createHash as createHash5, randomBytes as randomBytes3 } from "crypto";
 var PAIRING_CODE_TTL_MS = 120000;
@@ -23942,71 +24014,376 @@ class MobilePairing {
   }
 }
 
-// packages/gateway/src/mobile/listener.ts
-function defaultServerName() {
-  const name = hostname().trim();
-  return (name === "" ? "neko-computer" : name).slice(0, 64);
+// packages/gateway/src/mobile/relay.ts
+import { spawn as nodeSpawn } from "child_process";
+class RelayError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "RelayError";
+    this.code = code;
+  }
 }
-var VIRTUAL_INTERFACE_PREFIXES = [
-  "anpi",
-  "awdl",
-  "bridge",
-  "docker",
-  "gif",
-  "ipsec",
-  "llw",
-  "ppp",
-  "stf",
-  "tap",
-  "tun",
-  "utun",
-  "vboxnet",
-  "veth",
-  "virbr",
-  "vmnet"
-];
-var VIRTUAL_INTERFACE_KEYWORDS = ["hyper-v", "virtual", "virtualbox", "vmware", "vpn"];
-function isVirtualInterfaceName(name) {
-  const lower = name.toLowerCase();
-  if (VIRTUAL_INTERFACE_PREFIXES.some((prefix) => lower.startsWith(prefix)))
-    return true;
-  return VIRTUAL_INTERFACE_KEYWORDS.some((keyword) => lower.includes(keyword));
+var RELAY_HEARTBEAT_INTERVAL_MS = 2000;
+var RELAY_WATCHDOG_MS = 8000;
+var START_TIMEOUT_MS = 20000;
+var STOP_GRACE_MS = 1000;
+var STDERR_TAIL_BYTES = 2000;
+var RELAY_SOURCE = `using System;
+using System.Diagnostics;
+using System.Net;
+using System.Net.Sockets;
+using System.Threading;
+
+public static class NekoRelay
+{
+    static readonly Stopwatch Clock = Stopwatch.StartNew();
+    static long lastBeatMs = 0;
+
+    static void Touch() { Interlocked.Exchange(ref lastBeatMs, Clock.ElapsedMilliseconds); }
+    static string Flat(string text) { return text.Replace("\\r", " ").Replace("\\n", " "); }
+    static void Close(TcpClient client) { if (client != null) { try { client.Close(); } catch (Exception) { } } }
+
+    static void Copy(TcpClient from, TcpClient to)
+    {
+        byte[] buffer = new byte[16384];
+        try
+        {
+            System.IO.Stream source = from.GetStream();
+            System.IO.Stream sink = to.GetStream();
+            int count;
+            while ((count = source.Read(buffer, 0, buffer.Length)) > 0) { sink.Write(buffer, 0, count); }
+        }
+        catch (Exception) { }
+        try { to.Client.Shutdown(SocketShutdown.Send); } catch (Exception) { }
+    }
+
+    static void Pump(object state)
+    {
+        object[] args = (object[])state;
+        TcpClient client = (TcpClient)args[0];
+        TcpClient target = null;
+        try
+        {
+            target = new TcpClient();
+            target.NoDelay = true;
+            client.NoDelay = true;
+            target.Connect((string)args[1], (int)args[2]);
+            Thread upstream = new Thread(delegate() { Copy(client, target); });
+            upstream.IsBackground = true;
+            upstream.Start();
+            Copy(target, client);
+        }
+        catch (Exception) { }
+        finally { Close(client); Close(target); }
+    }
+
+    public static void Run(string listenIp, int listenPort, string targetIp, int targetPort, int watchdogMs)
+    {
+        TcpListener listener = new TcpListener(IPAddress.Parse(listenIp), listenPort);
+        listener.ExclusiveAddressUse = true;
+        try { listener.Start(128); }
+        catch (SocketException e)
+        {
+            string code = (e.SocketErrorCode == SocketError.AddressAlreadyInUse || e.SocketErrorCode == SocketError.AccessDenied) ? "port_in_use" : "listen_failed";
+            Console.Out.WriteLine("ERROR " + code + " " + Flat(e.Message));
+            Console.Out.Flush();
+            Environment.Exit(2);
+        }
+        try
+        {
+            TcpClient probe = new TcpClient();
+            IAsyncResult pending = probe.BeginConnect(targetIp, targetPort, null, null);
+            if (!pending.AsyncWaitHandle.WaitOne(3000)) { throw new TimeoutException("connect timed out"); }
+            probe.EndConnect(pending);
+            probe.Close();
+        }
+        catch (Exception e)
+        {
+            Console.Out.WriteLine("ERROR target_unreachable " + Flat(e.Message));
+            Console.Out.Flush();
+            Environment.Exit(3);
+        }
+        Touch();
+        Thread input = new Thread(delegate()
+        {
+            try { while (Console.In.ReadLine() != null) { Touch(); } } catch (Exception) { }
+            Environment.Exit(0);
+        });
+        input.IsBackground = true;
+        input.Start();
+        Thread watchdog = new Thread(delegate()
+        {
+            while (true)
+            {
+                Thread.Sleep(1000);
+                if (Clock.ElapsedMilliseconds - Interlocked.Read(ref lastBeatMs) > watchdogMs) { Environment.Exit(0); }
+            }
+        });
+        watchdog.IsBackground = true;
+        watchdog.Start();
+        Console.Out.WriteLine("READY");
+        Console.Out.Flush();
+        while (true)
+        {
+            TcpClient accepted;
+            try { accepted = listener.AcceptTcpClient(); }
+            catch (Exception) { Environment.Exit(4); return; }
+            ThreadPool.QueueUserWorkItem(Pump, new object[] { accepted, targetIp, targetPort });
+        }
+    }
+}`;
+function assertPort2(port, label) {
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    throw new Error(`relay ${label} port is invalid`);
 }
-function isBenchmarkAddress(address) {
-  return address.startsWith("198.18.") || address.startsWith("198.19.");
+function buildRelayScript(endpoints, watchdogMs = RELAY_WATCHDOG_MS) {
+  if (!isIpv4Literal(endpoints.listenAddress) || !isIpv4Literal(endpoints.targetAddress)) {
+    throw new Error("relay addresses must be IPv4 literals");
+  }
+  assertPort2(endpoints.listenPort, "listen");
+  assertPort2(endpoints.targetPort, "target");
+  if (!Number.isInteger(watchdogMs) || watchdogMs < 1000)
+    throw new Error("relay watchdog is invalid");
+  return [
+    "$ErrorActionPreference='Stop'",
+    `$src=@'
+${RELAY_SOURCE}
+'@`,
+    "Add-Type -TypeDefinition $src -Language CSharp",
+    `[NekoRelay]::Run('${endpoints.listenAddress}',${endpoints.listenPort},'${endpoints.targetAddress}',${endpoints.targetPort},${watchdogMs})`
+  ].join(`
+`);
 }
-function collectListenCandidates(interfaces, skipVirtual) {
-  const candidates = [];
-  for (const [name, infos] of Object.entries(interfaces)) {
-    if (infos === undefined)
-      continue;
-    if (skipVirtual && isVirtualInterfaceName(name))
+function encodeRelayCommand(script) {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+function describeExit(child) {
+  return child.signalCode !== null ? `signal ${child.signalCode}` : `exit code ${child.exitCode}`;
+}
+async function startWindowsRelay(options) {
+  const watchdogMs = options.watchdogMs ?? RELAY_WATCHDOG_MS;
+  const script = buildRelayScript(options, watchdogMs);
+  const spawn = options.spawn ?? nodeSpawn;
+  const child = spawn(options.powershell, ["-NoProfile", "-NonInteractive", "-EncodedCommand", encodeRelayCommand(script)], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+  let stderrTail = "";
+  child.stderr?.on("data", (chunk) => {
+    stderrTail = (stderrTail + chunk.toString("utf8")).slice(-STDERR_TAIL_BYTES);
+  });
+  child.stdin?.on("error", () => {});
+  const exited = new Promise((resolve) => {
+    child.once("error", (error) => resolve(`spawn error: ${error.message}`));
+    child.once("exit", () => resolve(describeExit(child)));
+  });
+  let heartbeat;
+  let stopping;
+  const stop = () => {
+    stopping ??= (async () => {
+      clearInterval(heartbeat);
+      child.stdin?.end();
+      const grace = options.stopGraceMs ?? STOP_GRACE_MS;
+      const done = await Promise.race([exited.then(() => true), delay2(grace).then(() => false)]);
+      if (!done) {
+        child.kill("SIGKILL");
+        await Promise.race([exited, delay2(grace)]);
+      }
+    })();
+    return stopping;
+  };
+  const ready = new Promise((resolve, reject) => {
+    let buffer = "";
+    const timer = setTimeout(() => reject(new RelayError("timeout", "Windows relay did not become ready in time")), options.startTimeoutMs ?? START_TIMEOUT_MS);
+    const finish = (action) => {
+      clearTimeout(timer);
+      action();
+    };
+    child.stdout?.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      for (;; ) {
+        const newline = buffer.indexOf(`
+`);
+        if (newline < 0)
+          break;
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line === "READY")
+          finish(resolve);
+        else if (line.startsWith("ERROR ")) {
+          const [, code = "start_failed", ...rest] = line.split(" ");
+          const known = ["port_in_use", "listen_failed", "target_unreachable"];
+          const mapped = known.find((item) => item === code) ?? "start_failed";
+          finish(() => reject(new RelayError(mapped, rest.join(" ") || code)));
+        }
+      }
+    });
+    exited.then((reason) => {
+      const detail = stderrTail.trim();
+      finish(() => reject(new RelayError("start_failed", `Windows relay exited before it was ready (${reason})${detail === "" ? "" : `: ${detail}`}`)));
+    });
+  });
+  try {
+    await ready;
+  } catch (error) {
+    await stop();
+    throw error;
+  }
+  heartbeat = setInterval(() => {
+    child.stdin?.write(`
+`);
+  }, options.heartbeatMs ?? RELAY_HEARTBEAT_INTERVAL_MS);
+  heartbeat.unref?.();
+  return { exited, stop };
+}
+function delay2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// packages/gateway/src/mobile/wsl.ts
+import { execFile } from "child_process";
+import { accessSync as accessSync2, constants as constants2, readFileSync as readFileSync2 } from "fs";
+import { networkInterfaces as networkInterfaces2 } from "os";
+import { delimiter, join as join8 } from "path";
+var POWERSHELL_FALLBACK = "/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe";
+var defaultProbeDeps = {
+  platform: process.platform,
+  env: process.env,
+  readProcVersion() {
+    try {
+      return readFileSync2("/proc/version", "utf8");
+    } catch {
+      return;
+    }
+  },
+  isExecutable(path) {
+    try {
+      accessSync2(path, constants2.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+function detectWsl(overrides = {}) {
+  const deps = { ...defaultProbeDeps, ...overrides };
+  if (deps.platform !== "linux")
+    return;
+  const { env } = deps;
+  const version = deps.readProcVersion() ?? "";
+  const inWsl = (env.WSL_DISTRO_NAME ?? "") !== "" || (env.WSL_INTEROP ?? "") !== "" || /microsoft|wsl/i.test(version);
+  if (!inWsl)
+    return;
+  const candidates = [
+    ...(env.PATH ?? "").split(delimiter).filter((dir) => dir !== "").map((dir) => join8(dir, "powershell.exe")),
+    POWERSHELL_FALLBACK
+  ];
+  return { powershell: candidates.find((candidate) => deps.isExecutable(candidate)) };
+}
+var WINDOWS_ADDRESSES_SCRIPT = [
+  "$ErrorActionPreference='Stop'",
+  "$r=@()",
+  "foreach($n in [System.Net.NetworkInformation.NetworkInterface]::GetAllNetworkInterfaces()){",
+  "if($n.OperationalStatus -ne 'Up'){continue}",
+  "if($n.NetworkInterfaceType -eq 'Loopback' -or $n.NetworkInterfaceType -eq 'Tunnel'){continue}",
+  "foreach($a in $n.GetIPProperties().UnicastAddresses){",
+  "if($a.Address.AddressFamily -eq 'InterNetwork'){$r+=[pscustomobject]@{name=$n.Name;address=$a.Address.IPAddressToString}}",
+  "}}",
+  "ConvertTo-Json -InputObject @($r) -Compress"
+].join(`
+`);
+var WSL_ADAPTER_PATTERN = /wsl|hyper-v|vethernet/i;
+var runPowerShell = (powershell, script, timeoutMs) => new Promise((resolve, reject) => {
+  execFile(powershell, ["-NoProfile", "-NonInteractive", "-Command", script], { timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024, encoding: "utf8" }, (error, stdout) => error ? reject(error) : resolve(stdout));
+});
+function parseWindowsInterfaces(output) {
+  const text = output.replace(/^\uFEFF/, "").trim();
+  if (text === "")
+    return [];
+  const parsed = JSON.parse(text);
+  const items = Array.isArray(parsed) ? parsed : [parsed];
+  const result = [];
+  for (const item of items) {
+    if (typeof item !== "object" || item === null)
       continue;
-    for (const info of infos) {
-      if (info.family !== "IPv4" || info.internal)
-        continue;
-      if (info.address.startsWith("169.254."))
-        continue;
-      if (skipVirtual && isBenchmarkAddress(info.address))
-        continue;
-      candidates.push(info.address);
+    const { name, address } = item;
+    if (typeof name === "string" && typeof address === "string" && isIpv4Literal(address)) {
+      result.push({ name, address });
     }
   }
-  return candidates.sort();
+  return result;
 }
-function mobileListenCandidates(interfaces) {
-  const source = interfaces ?? networkInterfaces();
-  const filtered = collectListenCandidates(source, true);
-  return filtered.length > 0 ? filtered : collectListenCandidates(source, false);
+function toInterfaceDict(interfaces) {
+  const dict = {};
+  for (const { name, address } of interfaces) {
+    const list = dict[name] ?? [];
+    dict[name] = list;
+    list.push({
+      address,
+      netmask: "255.255.255.0",
+      family: "IPv4",
+      mac: "00:00:00:00:00:00",
+      internal: false,
+      cidr: `${address}/24`
+    });
+  }
+  return dict;
 }
-function prioritizeListenCandidate(candidates, lastConnectedAddress) {
-  if (lastConnectedAddress === null || !candidates.includes(lastConnectedAddress))
-    return [...candidates];
-  return [lastConnectedAddress, ...candidates.filter((candidate) => candidate !== lastConnectedAddress)];
+
+class WindowsAddressDiscovery {
+  powershell;
+  run;
+  cacheMs;
+  timeoutMs;
+  now;
+  cached;
+  pending;
+  constructor(options) {
+    this.powershell = options.powershell;
+    this.run = options.run ?? runPowerShell;
+    this.cacheMs = options.cacheMs ?? 15000;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+    this.now = options.now ?? Date.now;
+  }
+  invalidate() {
+    this.cached = undefined;
+  }
+  candidates() {
+    if (this.cached !== undefined && this.now() - this.cached.at < this.cacheMs) {
+      return Promise.resolve([...this.cached.addresses]);
+    }
+    this.pending ??= this.read().finally(() => {
+      this.pending = undefined;
+    });
+    return this.pending.then((addresses) => [...addresses]);
+  }
+  async read() {
+    const output = await this.run(this.powershell, WINDOWS_ADDRESSES_SCRIPT, this.timeoutMs);
+    const usable = parseWindowsInterfaces(output).filter((item) => !WSL_ADAPTER_PATTERN.test(item.name));
+    const addresses = mobileListenCandidates(toInterfaceDict(usable));
+    this.cached = { at: this.now(), addresses };
+    return addresses;
+  }
 }
-function isIpv4Literal(address) {
-  const parts = address.split(".");
-  return parts.length === 4 && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+function wslOwnAddresses(interfaces = networkInterfaces2()) {
+  const result = [];
+  for (const infos of Object.values(interfaces)) {
+    for (const info of infos ?? []) {
+      if (info.family === "IPv4" && !info.internal)
+        result.push(info.address);
+    }
+  }
+  return result;
+}
+function primaryWslAddress(interfaces = networkInterfaces2()) {
+  const eth0 = (interfaces.eth0 ?? []).find((info) => info.family === "IPv4" && !info.internal);
+  return eth0?.address ?? wslOwnAddresses(interfaces)[0];
+}
+
+// packages/gateway/src/mobile/listener.ts
+var RELAY_PORT_RETRY_MS = 1e4;
+var RELAY_PORT_RETRY_INTERVAL_MS = 1000;
+function defaultServerName() {
+  const name = hostname().trim();
+  return (name === "" ? "neko-computer" : name).slice(0, 64);
 }
 function assertListenAddress(address) {
   if (!isIpv4Literal(address))
@@ -24018,6 +24395,23 @@ function assertListenAddress(address) {
 function toError(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
+var WSL_INTEROP_UNAVAILABLE = "WSL \u7684 Windows \u4E92\u64CD\u4F5C\u4E0D\u53EF\u7528\uFF08\u627E\u4E0D\u5230 powershell.exe\uFF09\uFF0C\u65E0\u6CD5\u8BFB\u53D6 Windows \u5C40\u57DF\u7F51\u5730\u5740\u3002\u8BF7\u542F\u7528 WSL \u4E92\u64CD\u4F5C\uFF0C\u6216\u76F4\u63A5\u5728 Windows \u4E0A\u8FD0\u884C neko\u3002";
+function describeRelayError(error, address, port, bindAddress) {
+  if (!(error instanceof RelayError))
+    return `Windows \u4E2D\u7EE7\u542F\u52A8\u5931\u8D25\uFF1A${toMessage(error)}`;
+  switch (error.code) {
+    case "port_in_use":
+      return `Windows \u4E0A ${address}:${port} \u5DF2\u88AB\u5360\u7528\uFF0C\u8BF7\u66F4\u6362\u7AEF\u53E3\u6216\u91CA\u653E\u8BE5\u7AEF\u53E3\u540E\u91CD\u8BD5\u3002`;
+    case "target_unreachable":
+      return `Windows \u65E0\u6CD5\u8FDE\u63A5\u5230 WSL \u5185\u7684\u76D1\u542C\u5730\u5740 ${bindAddress}:${port}\uFF08${error.message}\uFF09\u3002`;
+    case "timeout":
+      return "Windows \u4E2D\u7EE7\u542F\u52A8\u8D85\u65F6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002";
+    case "listen_failed":
+      return `Windows \u4E2D\u7EE7\u65E0\u6CD5\u5728 ${address}:${port} \u4E0A\u76D1\u542C\uFF1A${error.message}`;
+    default:
+      return `Windows \u4E2D\u7EE7\u542F\u52A8\u5931\u8D25\uFF1A${error.message}`;
+  }
+}
 function isMobilePrincipal2(principal) {
   return typeof principal === "object" && principal !== null && principal.kind === "mobile";
 }
@@ -24047,7 +24441,26 @@ class MobileGateway {
   stateValue;
   queue = Promise.resolve();
   closing;
-  constructor(serverId, serverName, onError, chord, store, storeFailure, initial) {
+  relay;
+  wslEnvironment;
+  windowsAddresses;
+  startRelay;
+  localInterfaces;
+  relayPortRetryMs;
+  relayPortRetryIntervalMs;
+  constructor(serverId, serverName, onError, chord, store, storeFailure, initial, network = {}) {
+    this.wslEnvironment = network.wsl === null ? undefined : network.wsl ?? detectWsl();
+    const powershell = this.wslEnvironment?.powershell;
+    if (network.windowsCandidates !== undefined)
+      this.windowsAddresses = network.windowsCandidates;
+    else if (powershell !== undefined) {
+      const discovery = new WindowsAddressDiscovery({ powershell });
+      this.windowsAddresses = () => discovery.candidates();
+    }
+    this.startRelay = network.startRelay ?? startWindowsRelay;
+    this.localInterfaces = network.localInterfaces;
+    this.relayPortRetryMs = network.relayPortRetryMs ?? RELAY_PORT_RETRY_MS;
+    this.relayPortRetryIntervalMs = network.relayPortRetryIntervalMs ?? RELAY_PORT_RETRY_INTERVAL_MS;
     this.serverId = serverId;
     this.serverName = serverName;
     this.onError = onError;
@@ -24064,7 +24477,7 @@ class MobileGateway {
     } catch (error) {
       storeFailure = toMessage(error);
     }
-    const gateway = new MobileGateway(options.serverId, options.serverName ?? defaultServerName(), options.onError, options.chord, store, storeFailure, storeFailure === undefined ? { status: "disabled" } : { status: "error", error: `mobile store unavailable: ${storeFailure}` });
+    const gateway = new MobileGateway(options.serverId, options.serverName ?? defaultServerName(), options.onError, options.chord, store, storeFailure, storeFailure === undefined ? { status: "disabled" } : { status: "error", error: `mobile store unavailable: ${storeFailure}` }, options.network);
     gateway.runtime = options.runtime;
     if (store !== undefined) {
       const config = store.getState();
@@ -24136,12 +24549,30 @@ class MobileGateway {
     }
     return false;
   }
-  adminState() {
+  async adminState() {
     const store = this.requireStore();
     const config = store.getState();
+    let candidates;
+    let wsl = null;
+    if (this.wslEnvironment === undefined) {
+      candidates = mobileListenCandidates();
+    } else {
+      candidates = [];
+      let error = null;
+      if (this.windowsAddresses === undefined)
+        error = WSL_INTEROP_UNAVAILABLE;
+      else {
+        try {
+          candidates = await this.windowsAddresses();
+        } catch (caught) {
+          error = `\u8BFB\u53D6 Windows \u5C40\u57DF\u7F51\u5730\u5740\u5931\u8D25\uFF1A${toMessage(caught)}`;
+        }
+      }
+      wsl = { interop: this.windowsAddresses !== undefined, error };
+    }
     return {
       state: this.stateValue,
-      candidates: prioritizeListenCandidate(mobileListenCandidates(), config.lastConnectedAddress),
+      candidates: prioritizeListenCandidate(candidates, config.lastConnectedAddress),
       port: config.port,
       certificate: this.certificate === undefined ? null : { fingerprint: this.certificate.fingerprint, expiresAt: this.certificate.expiresAt },
       devices: config.devices.map((device) => ({
@@ -24151,7 +24582,8 @@ class MobileGateway {
         lastSeenAt: device.lastSeenAt,
         online: this.deviceOnline(device.deviceId)
       })),
-      lastConnectedAddress: config.lastConnectedAddress
+      lastConnectedAddress: config.lastConnectedAddress,
+      wsl
     };
   }
   async regenerateCertificate() {
@@ -24231,9 +24663,10 @@ class MobileGateway {
     if (store?.getState().devices.some((device) => device.deviceId === auth.deviceId)) {
       store.touchDevice(auth.deviceId, Date.now()).catch((error) => this.onError?.(toError(error)));
     }
-    if (store !== undefined && typeof localAddress === "string" && isIpv4Literal(localAddress)) {
-      if (store.getState().lastConnectedAddress !== localAddress) {
-        store.rememberConnectedAddress(localAddress).catch((error) => this.onError?.(toError(error)));
+    const learned = this.advertisedAddress(localAddress);
+    if (store !== undefined && typeof learned === "string" && isIpv4Literal(learned)) {
+      if (store.getState().lastConnectedAddress !== learned) {
+        store.rememberConnectedAddress(learned).catch((error) => this.onError?.(toError(error)));
       }
     }
     const clientHost = createHost2({
@@ -24317,6 +24750,13 @@ class MobileGateway {
     for (const connection of this.connections.values())
       connection.sendNotification(method, params);
   }
+  advertisedAddress(localAddress) {
+    const state = this.stateValue;
+    if (state.status === "listening" && state.mode === "wsl-relay" && localAddress === state.bindAddress) {
+      return state.address;
+    }
+    return localAddress;
+  }
   requireStore() {
     if (this.storeHandle === undefined)
       throw new Error(`mobile store is unavailable: ${this.storeFailure ?? "unknown error"}`);
@@ -24329,6 +24769,7 @@ class MobileGateway {
     await this.stopListening();
     this.stateValue = { status: "starting" };
     try {
+      const plan = await this.planListen(address);
       const certificate = await this.certificateValue();
       const server = createServer({ cert: certificate.certPem, key: certificate.keyPem }, (request, response) => {
         this.handleRequest(request, response);
@@ -24356,11 +24797,10 @@ class MobileGateway {
         };
         server.once("error", onFailure);
         server.once("listening", onListening);
-        server.listen(port, address);
+        server.listen(port, plan.bindAddress);
       });
       this.server = server;
       this.wss = wss;
-      this.stateValue = { status: "listening", address, port };
       server.on("error", (error) => {
         this.stateValue = { status: "error", error: toMessage(error) };
         this.onError?.(error);
@@ -24368,6 +24808,9 @@ class MobileGateway {
           return;
         });
       });
+      if (plan.mode === "wsl-relay")
+        await this.startRelayFor(address, port, plan.bindAddress);
+      this.stateValue = plan.mode === "wsl-relay" ? { status: "listening", address, port, mode: "wsl-relay", bindAddress: plan.bindAddress } : { status: "listening", address, port };
     } catch (error) {
       await this.stopListening().catch(() => {
         return;
@@ -24376,6 +24819,66 @@ class MobileGateway {
       throw error;
     }
   }
+  async planListen(address) {
+    if (this.wslEnvironment === undefined)
+      return { mode: "direct", bindAddress: address };
+    if (this.windowsAddresses === undefined)
+      throw new Error(WSL_INTEROP_UNAVAILABLE);
+    let candidates;
+    try {
+      candidates = await this.windowsAddresses();
+    } catch (error) {
+      throw new Error(`\u8BFB\u53D6 Windows \u5C40\u57DF\u7F51\u5730\u5740\u5931\u8D25\uFF1A${toMessage(error)}`);
+    }
+    if (!candidates.includes(address)) {
+      throw new Error(`${address} \u4E0D\u662F\u5F53\u524D\u53EF\u7528\u7684 Windows \u5C40\u57DF\u7F51\u5730\u5740\uFF0C\u8BF7\u91CD\u65B0\u9009\u62E9\u540E\u518D\u5F00\u542F\u3002`);
+    }
+    const interfaces = this.localInterfaces?.();
+    if (wslOwnAddresses(interfaces).includes(address))
+      return { mode: "direct", bindAddress: address };
+    const bindAddress = primaryWslAddress(interfaces);
+    if (bindAddress === undefined)
+      throw new Error("WSL \u5185\u6CA1\u6709\u53EF\u7528\u7684\u7F51\u7EDC\u5730\u5740\uFF0C\u65E0\u6CD5\u5EFA\u7ACB\u624B\u673A\u5165\u53E3\u3002");
+    return { mode: "wsl-relay", bindAddress };
+  }
+  async startRelayFor(address, port, bindAddress) {
+    const deadline = Date.now() + this.relayPortRetryMs;
+    let relay;
+    for (;; ) {
+      try {
+        relay = await this.startRelay({
+          powershell: this.wslEnvironment?.powershell ?? "powershell.exe",
+          listenAddress: address,
+          listenPort: port,
+          targetAddress: bindAddress,
+          targetPort: port
+        });
+        break;
+      } catch (error) {
+        if (error instanceof RelayError && error.code === "port_in_use" && Date.now() + this.relayPortRetryIntervalMs < deadline) {
+          await new Promise((resolve) => setTimeout(resolve, this.relayPortRetryIntervalMs));
+          continue;
+        }
+        throw new Error(describeRelayError(error, address, port, bindAddress));
+      }
+    }
+    this.relay = relay;
+    relay.exited.then((reason) => this.onRelayExited(relay, reason));
+  }
+  onRelayExited(relay, reason) {
+    this.enqueue(async () => {
+      if (this.relay !== relay)
+        return;
+      this.relay = undefined;
+      this.pairingValue?.invalidate();
+      await this.stopListening().catch(() => {
+        return;
+      });
+      const message = `Windows \u4E2D\u7EE7\u610F\u5916\u9000\u51FA\uFF08${reason}\uFF09\uFF0C\u8BF7\u91CD\u65B0\u5F00\u542F\u624B\u673A\u8BBF\u95EE\u3002`;
+      this.stateValue = { status: "error", error: message };
+      this.onError?.(new Error(message));
+    });
+  }
   async certificateValue() {
     if (this.certificate === undefined) {
       this.certificate = await MobileCertificate.load(this.requireStore(), this.serverId);
@@ -24383,6 +24886,12 @@ class MobileGateway {
     return this.certificate;
   }
   async stopListening() {
+    const relay = this.relay;
+    this.relay = undefined;
+    if (relay !== undefined)
+      await relay.stop().catch(() => {
+        return;
+      });
     for (const connection of [...this.connections.values()])
       connection.close(1001, "listener_stopped");
     const server = this.server;
@@ -24490,9 +24999,9 @@ ${JSON.stringify({ code, message })}`);
 
 // packages/gateway/src/port-file.ts
 import { readFile as readFile5, rm as rm2, writeFile as writeFile2 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 function gatewayPortFilePath(nekoDir, serverId) {
-  return join8(nekoDir, `${serverId}.port`);
+  return join9(nekoDir, `${serverId}.port`);
 }
 async function writeGatewayPortFile(nekoDir, serverId, wsUrl) {
   await writeFile2(gatewayPortFilePath(nekoDir, serverId), `${wsUrl}
@@ -24516,7 +25025,7 @@ import {
 // packages/core/src/application-updates.ts
 import { mkdir as mkdir3, readFile as readFile6, rename as rename3, rm as rm3, writeFile as writeFile3 } from "fs/promises";
 import { homedir as homedir5 } from "os";
-import { dirname as dirname5, join as join9 } from "path";
+import { dirname as dirname5, join as join10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 async function abortable(work, signal) {
   signal.throwIfAborted();
@@ -24580,7 +25089,7 @@ class UpdateChecker {
     return this.#work;
   }
   get #cachePath() {
-    return this.#options.cachePath ?? join9(homedir5(), ".neko", "update-check.json");
+    return this.#options.cachePath ?? join10(homedir5(), ".neko", "update-check.json");
   }
   async#check(force) {
     await this.local();
@@ -25360,7 +25869,7 @@ function serveSessions(host, runtime, context) {
 import { createHash as createHash6, randomUUID as randomUUID3 } from "crypto";
 import { mkdir as mkdir4, readdir as readdir2, rename as rename4, rm as rm4, stat as stat2, writeFile as writeFile4 } from "fs/promises";
 import { homedir as homedir6 } from "os";
-import { dirname as dirname6, join as join10 } from "path";
+import { dirname as dirname6, join as join11 } from "path";
 
 // node_modules/fflate/esm/index.mjs
 import { createRequire } from "module";
@@ -25783,8 +26292,8 @@ class SkillMarketError extends Error {
 var CATALOG_TTL_MS = 60000;
 var ZIP_CACHE_MAX = 16;
 var MAX_PACKAGE_BYTES = 32 * 1024 * 1024;
-var userSkillsDir2 = (home) => join10(home, ".agents", "skills");
-var projectSkillsDir = (workspaceRoot) => join10(workspaceRoot, ".agents", "skills");
+var userSkillsDir2 = (home) => join11(home, ".agents", "skills");
+var projectSkillsDir = (workspaceRoot) => join11(workspaceRoot, ".agents", "skills");
 var activeLevelOf = (state) => state.project ? "project" : state.user ? "user" : state.builtin ? "builtin" : null;
 var normalizeEntry = (raw) => {
   const row = raw ?? {};
@@ -25918,11 +26427,11 @@ function createSkillMarketClient(options) {
     } catch {
       return;
     }
-    await Promise.all(names.filter((n) => n.startsWith(".tmp-")).map((n) => rm4(join10(parent, n), { recursive: true, force: true }).catch(() => {})));
+    await Promise.all(names.filter((n) => n.startsWith(".tmp-")).map((n) => rm4(join11(parent, n), { recursive: true, force: true }).catch(() => {})));
   };
   const install = async ({ name, scope, workspaceRoot, overwrite }) => {
     const skillsDir = skillsDirFor(scope, workspaceRoot);
-    const target = join10(skillsDir, name);
+    const target = join11(skillsDir, name);
     const exists = await stat2(target).catch(() => {
       return;
     }) !== undefined;
@@ -25931,10 +26440,10 @@ function createSkillMarketClient(options) {
     const skill = await detail(name);
     const files = unpack(skill, await download(skill));
     await sweepTempDirs(skillsDir);
-    const temp = join10(dirname6(skillsDir), `.tmp-${randomUUID3()}`);
+    const temp = join11(dirname6(skillsDir), `.tmp-${randomUUID3()}`);
     try {
       for (const [relative, bytes] of files) {
-        const dest = join10(temp, ...relative.split("/"));
+        const dest = join11(temp, ...relative.split("/"));
         await mkdir4(dirname6(dest), { recursive: true });
         await writeFile4(dest, bytes);
       }
@@ -25947,7 +26456,7 @@ function createSkillMarketClient(options) {
     }
     let shadowedBy;
     if (scope === "user" && workspaceRoot !== undefined && workspaceRoot !== "") {
-      const projectDir = join10(projectSkillsDir(workspaceRoot), name);
+      const projectDir = join11(projectSkillsDir(workspaceRoot), name);
       if (await stat2(projectDir).catch(() => {
         return;
       }) !== undefined)
@@ -25957,7 +26466,7 @@ function createSkillMarketClient(options) {
   };
   const uninstall = async ({ name, scope, workspaceRoot }) => {
     const skillsDir = skillsDirFor(scope, workspaceRoot);
-    const target = join10(skillsDir, name);
+    const target = join11(skillsDir, name);
     if (await stat2(target).catch(() => {
       return;
     }) === undefined)
@@ -25991,9 +26500,9 @@ function createSkillMarketClient(options) {
 }
 
 // packages/gateway/src/workspaces.ts
-import { constants as constants2 } from "fs";
+import { constants as constants3 } from "fs";
 import { access, readdir as readdir3, stat as stat3 } from "fs/promises";
-import { dirname as dirname7, isAbsolute as isAbsolute3, join as join11 } from "path";
+import { dirname as dirname7, isAbsolute as isAbsolute3, join as join12 } from "path";
 async function browseWorkspaces(options) {
   const requested = options.path.replace(/^\/+([A-Za-z]:[\\/])/, "$1");
   if (process.platform === "win32" && (requested === "/" || requested === "\\")) {
@@ -26020,13 +26529,13 @@ async function browseWorkspaces(options) {
   let next = offset;
   for (;next < entries.length && directories.length < 100; next++) {
     const entry = entries[next];
-    const target = join11(path, entry.name);
+    const target = join12(path, entry.name);
     if (!entry.isDirectory() && !entry.isSymbolicLink())
       continue;
     try {
       if (!(await stat3(target)).isDirectory())
         continue;
-      await access(target, constants2.R_OK | constants2.X_OK);
+      await access(target, constants3.R_OK | constants3.X_OK);
       directories.push({ name: entry.name, path: target });
     } catch {
       directories.push({ name: entry.name, path: target, error: "\u76EE\u5F55\u4E0D\u53EF\u8BBF\u95EE" });
@@ -26505,7 +27014,7 @@ async function startGateway(options = {}) {
   const marketUrl = options.marketUrl ?? fileConfig.skills?.marketUrl ?? DEFAULT_SKILL_MARKET_URL;
   const nekoDir = dirname9(storagePath);
   const serverId = options.serverId ?? await loadOrCreateServerId(nekoDir);
-  const socketPath = options.socketPath !== undefined ? options.socketPath : fileConfig.gateway?.socketPath !== undefined ? fileConfig.gateway.socketPath : process.platform === "win32" ? null : join12(nekoDir, `${serverId}.sock`);
+  const socketPath = options.socketPath !== undefined ? options.socketPath : fileConfig.gateway?.socketPath !== undefined ? fileConfig.gateway.socketPath : process.platform === "win32" ? null : join13(nekoDir, `${serverId}.sock`);
   const runtime = await createNekoRuntime({
     context,
     onReport: (error) => options.onError?.(error instanceof Error ? error : new Error(String(error))),
@@ -26665,7 +27174,7 @@ function serverIdFromSocketPath(socketPath) {
   return isServerId(candidate) ? candidate : undefined;
 }
 async function loadOrCreateServerId(nekoDir) {
-  const file = join12(nekoDir, SERVER_ID_FILENAME);
+  const file = join13(nekoDir, SERVER_ID_FILENAME);
   try {
     const existing = (await readFile7(file, "utf8")).trim();
     if (existing !== "")
@@ -26678,12 +27187,79 @@ async function loadOrCreateServerId(nekoDir) {
   return created;
 }
 
+// packages/gateway/src/shutdown.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 5000;
+function shutdownSignals(platform) {
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  if (platform === "win32")
+    signals.push("SIGBREAK");
+  return signals;
+}
+function installShutdown(options = {}) {
+  const proc = options.process ?? process;
+  const exit = options.exit ?? ((code) => process.exit(code));
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  const controller = new AbortController;
+  let cleanup;
+  let cleaning = false;
+  let timer;
+  const runCleanup = () => {
+    if (cleaning || cleanup === undefined)
+      return;
+    cleaning = true;
+    cleanup().then(() => exit(0), (error) => {
+      options.log?.(error instanceof Error ? error.message : String(error));
+      exit(1);
+    });
+  };
+  const onSignal = () => {
+    if (controller.signal.aborted) {
+      options.log?.("\u518D\u6B21\u6536\u5230\u7EC8\u6B62\u4FE1\u53F7\uFF0C\u5F3A\u5236\u9000\u51FA\u3002");
+      exit(130);
+      return;
+    }
+    options.log?.(`
+\u6B63\u5728\u5173\u95ED\u2026`);
+    controller.abort();
+    timer = setTimeout(() => {
+      options.log?.("\u5173\u95ED\u8D85\u65F6\uFF0C\u5F3A\u5236\u9000\u51FA\u3002");
+      exit(1);
+    }, timeoutMs);
+    timer.unref?.();
+    runCleanup();
+  };
+  const installed = [];
+  for (const signal of shutdownSignals(proc.platform)) {
+    try {
+      proc.on(signal, onSignal);
+      installed.push(signal);
+    } catch {}
+  }
+  return {
+    signal: controller.signal,
+    setCleanup(next) {
+      cleanup = next;
+      if (controller.signal.aborted)
+        runCleanup();
+    },
+    dispose() {
+      clearTimeout(timer);
+      for (const signal of installed)
+        proc.off(signal, onSignal);
+    }
+  };
+}
+
 // packages/gateway/src/main.ts
 var argv = process.argv.slice(2);
 if (argv.includes("-h") || argv.includes("--help")) {
   console.log(GATEWAY_USAGE);
   process.exit(0);
 }
+var shutdown = installShutdown({
+  log: (message) => console.log(message),
+  exit: (code) => process.exit(code)
+});
 var options = parseGatewayArgs(argv);
 var gateway = await startGateway({
   ...options,
@@ -26695,15 +27271,4 @@ if (gateway.socketPath !== undefined)
 if (gateway.wsUrl !== undefined)
   console.log(`  WebSocket:   ${gateway.wsUrl}`);
 console.log("\u6309 Ctrl+C \u505C\u6B62\u3002");
-var stopping = false;
-var stop = () => {
-  if (stopping)
-    return;
-  stopping = true;
-  gateway.close().then(() => process.exit(0)).catch((error) => {
-    console.error("\u5173\u95ED\u5931\u8D25:", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  });
-};
-process.on("SIGINT", stop);
-process.on("SIGTERM", stop);
+shutdown.setCleanup(() => gateway.close());