hermes - 💡(How to fix) Fix Bug: /browser connect misses IPv6 loopback CDP when 127.0.0.1 is not DevTools [1 pull requests]

Bug Description

/browser connect can miss a valid local Chrome DevTools Protocol (CDP) endpoint on macOS when port 9222 is split across IPv4 and IPv6 loopback listeners.

Observed local state:

• http://127.0.0.1:9222 had a Chrome listener, but /json/version returned 404, so it was not the usable CDP discovery endpoint.
• http://[::1]:9222/json/version returned valid Chrome DevTools Protocol discovery JSON and exposed the live debug Chrome instance.

The TUI gateway's default-local browser connect path assumed/probed the local endpoint as 127.0.0.1:9222, so Hermes failed to attach even though the actual debug Chrome endpoint was available on IPv6 loopback.

Steps to Reproduce

On macOS with Chrome debug launched on the default port:

lsof -nP -iTCP:9222 -sTCP:LISTEN
# observed: one Chrome listener on 127.0.0.1:9222
# observed: another Chrome debug listener on [::1]:9222

curl -i http://127.0.0.1:9222/json/version
# observed: HTTP/1.1 404 Not Found

curl -i 'http://[::1]:9222/json/version'
# observed: HTTP/1.1 200 OK
# observed body includes Browser and webSocketDebuggerUrl, e.g.
# ws://[::1]:9222/devtools/browser/<id>

Then run default /browser connect from the TUI / browser manage path.

Expected Behavior

For the default local CDP endpoint (localhost / 127.0.0.1 / ::1 on port 9222), Hermes should validate the actual CDP discovery endpoint and pick the loopback spelling that serves /json/version or /json.

A TCP listener or a hard-coded loopback spelling is not sufficient.

Actual Behavior

The TUI browser connect path treats default-local CDP as effectively 127.0.0.1:9222. That is correct for some macOS cases, but it breaks the inverse case where 127.0.0.1:9222 is not CDP while [::1]:9222 is the real CDP endpoint.

Affected Component

• CLI / TUI browser connect flow
• Browser tools / live Chrome CDP connection

Messaging Platform

N/A, CLI/TUI only.

Debug Report

I did not attach hermes debug share output because the minimal reproducer is network endpoint behavior and the logs/config can include local session details. The relevant commands and outputs are included above.

Operating System

macOS 26.4.

Python Version

• System python3 --version: Python 3.14.4
• Hermes test runner venv shown by scripts/run_tests.sh: Python 3.11.13

Hermes Version

• Local installed hermes --version: Hermes Agent v0.13.0 (2026.5.7)
• Upstream base used for the PR: a91a57fa5a13d516c38b07a141a9ce8a3daabeb0 (chore: release v0.14.0 (2026.5.16) (#26862))

Additional Logs / Traceback

curl -i http://127.0.0.1:9222/json/version
# HTTP/1.1 404 Not Found

curl -i 'http://[::1]:9222/json/version'
# HTTP/1.1 200 OK
# Browser: Chrome/148.0.7778.168
# webSocketDebuggerUrl: ws://[::1]:9222/devtools/browser/...

Root Cause Analysis

Related prior work switched the default local CDP endpoint from localhost to 127.0.0.1 to avoid IPv6-first localhost failures. This bug is the inverse: 127.0.0.1 is the wrong loopback endpoint and [::1] is the working endpoint.

The TUI gateway's default-local CDP handling should not choose a local spelling by assumption. It should probe local candidates and persist the first one that actually responds to Chrome's CDP discovery API.

Related but non-duplicative upstream items found before opening this issue:

• #10231: switched default from localhost to 127.0.0.1 for a different IPv6-first failure mode.
• #12912 / #12968: broader validation for cases where a TCP listener exists but classic discovery endpoints are unusable.
• #17238: TUI /browser connect local CDP handling.

Proposed Fix

For default-local CDP inputs, probe these candidates in order while preserving the user's first choice:

• requested host
• 127.0.0.1
• ::1
• localhost

Choose the first candidate whose /json/version or /json endpoint responds successfully, then persist that normalized endpoint for browser tools.

Are you willing to submit a PR for this?

Yes. PR: #26865.