Document the existing-profile CDP route: --remote-debugging-port is blocked on the default user-data-dir

[f-trycua]

Summary

Callers reasonably assume that if browser_prepare cannot attach to an existing profile, they can relaunch the browser with --remote-debugging-port instead. On Chrome ≥136 that is false for the case they care about, and nothing in the driver says so.

The behaviour

Chrome ignores --remote-debugging-port when running on the default user-data-dir. Verified on Chrome 151, same build, same session:

# real profile, default user-data-dir
$ google-chrome --remote-debugging-port=9222 --profile-directory="Profile 2"
$ ss -lnt | grep 9222        → nothing
$ ls ~/.config/google-chrome/DevToolsActivePort → No such file

# same flag, non-default user-data-dir
$ google-chrome --user-data-dir=/tmp/probe --remote-debugging-port=9222
$ curl -s http://127.0.0.1:9222/json/version → Chrome/151.0.7922.75

So on a user's real profile the chrome://inspect toggle is the only sanctioned route to CDP — which is exactly what browser_prepare's existing-profile setup path automates.

Second surprise: HTTP discovery is disabled on that route

A browser whose debugging was enabled by the toggle (rather than the flag) publishes a WebSocket endpoint but 404s the JSON discovery API:

$ cat ~/.config/google-chrome/DevToolsActivePort
9222
/devtools/browser/19b78f4d-32f5-482a-ac2c-85f5d0e6e7a7

$ curl -o /dev/null -w "%{http_code}" http://127.0.0.1:9222/json/version   → 404
$ curl -o /dev/null -w "%{http_code}" http://localhost:9222/json/version   → 404

The driver survives this because it has a second ownership proof — devtools_active_ports_file ("exact /proc argv profile port file plus loopback socket inode owner") rather than the /json/version path used for flag-launched browsers. Worth stating that this proof is load-bearing for the toggle route, so nobody "simplifies" it away.

Suggested work

• Document the two routes and when each applies: --remote-debugging-port + non-default --user-data-dir for throwaway automation profiles, chrome://inspect toggle for a user's real profile
• Say plainly that the port flag is inert on the default profile dir on Chrome ≥136 — otherwise every debugging session rediscovers it
• Note in the code that devtools_active_ports_file is the proof for toggle-enabled browsers, since /json/* is unavailable there
• Cross-reference the --force-renderer-accessibility precondition (a11y.rs: the Chromium ScreenReaderEnabled premise no longer holds on current Chrome #2915), which the setup route also needs on Linux

Related

The restart semantics of that toggle are handled in #2911; the navigation reliability in #2895. This issue is the user-facing documentation those two imply.