docs: WSL default port 49374 falls inside Windows reserved range, so pair links fail in a Windows browser #62532

Summary

On WSL2 with default NAT networking, the documented WSL default port 49374 is inside the Windows TCP port-exclusion range, so Windows browsers cannot reach the forwarded localhost port. opencode pair prints a link that fails with ERR_CONNECTION_REFUSED, with no hint from OpenCode. The docs note that "Windows reserves ports from 49152 up" but still list 49374 as the WSL default and show opencode service set port 49374 as the example.

Environment

• opencode version: 2.2.6
• OS: Debian GNU/Linux 13 (trixie) on Linux 6.18.33.2-microsoft-standard-WSL2, WSL networking mode nat
• Terminal: TERM=xterm-256color
• Shell: /bin/bash
• Install/channel: latest (curl installer, ~/.opencode/bin/opencode)
• Active plugins: none found in config

Reproduction

1. Run OpenCode inside WSL2 (default NAT networking) and start the service: opencode (service listens on 127.0.0.1:49374 inside WSL).
2. On Windows, confirm the current exclusion range: netsh int ipv4 show excludedportrange protocol=tcp → this boot contains 49370–49469, which covers 49374.
3. Run opencode pair and open the printed link in Chrome on Windows.
4. Chrome cannot connect. Inside WSL, curl http://127.0.0.1:49374/ returns 200. From Windows, curl.exe http://127.0.0.1:49374/ returns 000.
5. Control test: a test server bound to 127.0.0.1:59374 inside WSL is reachable from Windows via curl.exe http://localhost:59374/ (200), so localhost forwarding itself works and the failure is specific to reserved ports.

Expected Behavior

Either:

• the WSL default port is chosen outside the Windows host's protected range (below 49152, e.g. the existing Windows constant 28894), or
• the docs explicitly warn that in WSL, 49374 may be reserved by the Windows host and recommend opencode service set port <port below 49152>, and
• opencode pair / the web UI surfaces that the port is unreachable instead of printing a link that silently fails.

Actual Behavior

Pair link cannot be opened from the Windows browser. No OpenCode error is reported; the server log shows no /auth/connect request, so the connection never reaches WSL. Same port worked before a Windows reboot, then broke after Hyper-V chose a new dynamic reservation block.

Additional Context

The defaults are hardcoded channel constants extracted from the binary:

if (e === "latest" || e === "dev" || e === "beta" || e === "next") return 49374 // 0xC0DE
if (e === "local") return 49375 // 0xC0DF
return 1e4 + parseInt(hash(e).slice(0, 8), 16) ...

Windows' dynamic port range starts at 49152. winnat/HNS reserves blocks inside it at each boot, so the failing set changes across reboots:

Protocol tcp Port Exclusion Ranges
Start Port    End Port
     49370       49469   <- dynamic, no asterisk
     50000       50059   *
     55279       55378

Workaround verified: opencode service set port 28894 + opencode service restart (Windows default, below 49152) makes the pair link reachable from Chrome.

Related: #50672 (hardcoded 49374 collides on shared loopback), #55918 (WSL2 mirrored networking reserved range blocks binding).

Docs: https://opencode.ai/docs/cli/web/