GeezerVison

What is the current behavior?

Port in use: isPortAvailable checks localhost, but since #5788 the WebSocket server binds every interface. On macOS those don't conflict, so a taken port passes the check, the listen fails with EADDRINUSE, and the CLI crashes. Two ns debug sessions are enough to hit it.

Reconnects: the connection lock was released on the connection event, which never fires for a client that drops during the handshake. proper-lockfile keeps refreshing a lock while its process lives, so it never goes stale, and every later client fails after about 10 seconds with Timeout while waiting for lock and a 401 until the CLI exits. Separately, a late close from a replaced client could destroy the socket its successor had just received.

What is the new behavior?

• isPortAvailable tests 127.0.0.1, ::1, 0.0.0.0 and ::, and the proxy moves to the next port if the bind still fails. Android's debug port uses the same check.

• Connections go through an in-process queue instead of a file lock. Each session only cleans up after itself.

• The newest client takes over, and the previous one is closed with Replaced by a newer debugger client.

• Port service timers are now cleared. The typeof timer === "number" check never matched in Node, which produced false not able to get inspector socket port warnings.

• The proxy only listens on 127.0.0.1 and ::1, and rejects browser origins other than DevTools and localhost with a 403. It used to accept connections from the network and from any web page, and the debugger can run any code in the app. Clients without an origin, like VS Code's debug adapter, are still accepted.

Only one client at a time is supported, as before. The runtime serves a single frontend and ios-device-lib keeps one forwarded connection per device.

Testing

Stress test against a real app on an iOS 26.2 simulator, 5 rounds per scenario:

With another process on 41000, this PR came up on 41001. Unit tests are included.

On an iPad, every scenario passed until the app stopped responding 80–140 seconds into a run, then every connection got a 401. It happened in 3 of 4 runs, varied in timing, hit a plain connect/close loop too, and left no crash report. The iPad locking is the likely cause, but that isn't proven, and recovery after waking wasn't tested.

Security checks against the running proxy: 127.0.0.1, ::1 and localhost connect, a https://evil.example origin gets a 403, and the machine's LAN address is refused. Real Chrome DevTools sends devtools://devtools, captured from a headless Chrome, which is on the allowed list. A full DevTools session through the proxy and VS Code's debug adapter weren't run.

The Safari --inspector TCP proxy is a separate path and is unchanged.

Part of a stack

Base: #6176. Next: #6178.

Summary by CodeRabbit

• Bug Fixes
  • Improved iOS debugger connections during client reconnections and disconnects, helping keep the active session stable and recover from interrupted handshakes.
  • Improved handling of occupied ports so the debugger can retry on another port when available.
  • Improved port availability checks across common network addresses, reducing incorrect reports that a port is free.
  • Restricted debugger connections to supported origins and loopback addresses, while continuing to allow valid DevTools connections.
  • Improved handling of simultaneous clients and session replacements to prevent an old connection from disrupting the active session.