Summary

In startSshPortForward, the port availability preflight calls ensurePortAvailable(localPort) without specifying a host. On dual-stack hosts this binds the IPv6 wildcard ::, which misses IPv4-only occupants and reports a busy port as free — the same address-family false-negative that was fixed for the Browser CDP path in #94394 and for isPortBusy in #94471.

The rest of ssh-tunnel.ts is consistently IPv4-loopback scoped:

• pickEphemeralPort binds 127.0.0.1
• canConnectLocal connects to 127.0.0.1
• The SSH -L forward targets 127.0.0.1

The fix is a single-line change: pass "127.0.0.1" as the host to ensurePortAvailable, matching the existing caller-scoped probe pattern from #94394.

Fixes #94596

Real behavior proof

Behavior addressed: On dual-stack hosts, startSshPortForward reports a busy IPv4-only port as free because ensurePortAvailable(localPort) without a host binds :: (IPv6 wildcard) and misses IPv4-only occupants.

Real environment tested: Linux 6.8.0-124-generic, Node.js v22.x, OpenClaw main @ 49f10a1

Exact steps or command run after this patch: cd ~/workspace/openclaw && npx vitest run src/infra/ssh-tunnel.test.ts src/infra/ports.test.ts

After-fix evidence: All 17 tests pass (12 ssh-tunnel + 5 ports). Source-level verification: ensurePortAvailable(localPort, "127.0.0.1") binds the same interface as the SSH forward target, pickEphemeralPort (line 68: listen(0, "127.0.0.1")), and canConnectLocal (line 83: connect({ host: "127.0.0.1" })), eliminating the dual-stack address-family mismatch.

Observed result after the fix: All 17 existing tests pass. The fix is source-verified: the same helper ensurePortAvailable(port, host?) that was extended with an optional host parameter in #94394 is now called with "127.0.0.1" in the SSH tunnel path, consistent with every other bind/connect call in the module (pickEphemeralPort → listen(0, "127.0.0.1"), canConnectLocal → connect({ host: "127.0.0.1" }), ssh -L ${localPort}:127.0.0.1:${remotePort}).

What was not tested: A live dual-stack reproduction was not performed — the fix is source-level verified. The false-negative requires an IPv4-only port occupant on a dual-stack host, which is the reporter's exact scenario but not reproducible in this CI/development environment.

Tests and validation

Unit tests

$ npx vitest run src/infra/ssh-tunnel.test.ts src/infra/ports.test.ts

✓ src/infra/ssh-tunnel.test.ts — 12 tests passed
  ✓ parseSshTarget accepts user@host:port
  ✓ parseSshTarget accepts host:port without user
  ✓ parseSshTarget accepts host-only (default port 22)
  ✓ parseSshTarget rejects missing host
  ✓ parseSshTarget rejects invalid port
  ✓ parseSshTarget rejects host starting with dash
  ✓ startSshPortForward throws on invalid target
  ✓ startSshPortForward falls back to ephemeral port on EADDRINUSE
  ✓ startSshPortForward throws on non-EADDRINUSE errors from ensurePortAvailable
  ✓ pickEphemeralPort returns a valid port number
  ✓ canConnectLocal returns false for a closed port
  ✓ waitForLocalListener times out when nothing is listening

✓ src/infra/ports.test.ts — 5 tests passed

Type check / Lint

• TypeScript compilation: clean (no errors in modified file)
• The change is a one-line argument addition to a function whose signature already accepts the optional second parameter

Risk checklist

• This change is backwards compatible — ensurePortAvailable already accepts an optional host parameter; passing "127.0.0.1" is a stricter, more correct probe that cannot introduce new false-positives
• This change has been tested with existing configurations — all 17 existing tests pass; the fix does not alter any configuration path
• I have updated relevant documentation — no documentation change needed; this is a bug fix that corrects internal behavior to match the documented SSH tunnel contract
• Breaking changes (if any) are documented in Summary — no breaking changes; the fix makes a preflight check stricter, which can only reduce (not increase) the chance of port conflicts

Risk assessment: Low. The fix is a one-line change that makes the port preflight consistent with every other network operation in the same module. ensurePortAvailable already supports the optional host parameter (added in #94394). Passing "127.0.0.1" means the probe binds the same interface the SSH forward will use, eliminating the dual-stack address-family mismatch. The existing EADDRINUSE fallback to pickEphemeralPort is preserved unchanged.

Current review state

• Self-review completed
• At least one maintainer review
• All CI checks passed