fix: explain launch failures caused by running as root

[elcodabra]

Follow-up to #261. That issue was closed by #338, which added --chrome-arg so the sandbox can be disabled explicitly. The flag works, but the failure it fixes is still undiscoverable — you cannot find out that --chrome-arg=--no-sandbox is the answer.

Problem

launch() uses pipe: true. In pipe mode Puppeteer never calls waitForLineOutput(), which is the only place Chrome's stderr makes it into the thrown error. So when Chrome exits at startup with

Running as root without --no-sandbox is not supported. See https://crbug.com/638180.

that line is dropped, and what reaches the MCP client is:

Protocol error (Target.setDiscoverTargets): Target closed

Reproduced on main (v1.8.0) by pointing executablePath at a stub that prints Chrome's message to stderr and exits 1 — exactly the symptom reported in #261. The catch in launch() only recognised The browser is already running.

Fix

Detect the case and rethrow with an explanation. Deliberately not disabling the sandbox automatically, per #261 (comment):

Chrome failed to start: Protocol error (Target.setDiscoverTargets): Target closed

chrome-devtools-mcp is running as root and Chrome does not start as root unless its
sandbox is disabled (https://crbug.com/638180). Prefer running chrome-devtools-mcp as
a non-root user. If that is not possible, for example in a container, pass
--chrome-arg=--no-sandbox. That disables the Chrome sandbox, so only do it for content
you trust.

Notes on the shape of the check:

• It runs only on a failed launch, so root with a properly installed setuid sandbox is unaffected.
• The original error is kept in the message and as cause, so an unrelated failure under root is never masked or mislabelled.
• --no-sandbox present in the args short-circuits it: root is then not what stopped Chrome.
• --disable-setuid-sandbox and --no-sandbox-and-elevated do not count as opting out — Chrome's zygote check requires --no-sandbox specifically. Covered by a test.
• On Windows process.getuid is undefined, so the check is a no-op.

Also adds a "Running as root" section to docs/troubleshooting.md, next to the existing "Operating system sandboxes".

Testing

Five unit tests in tests/browser.test.ts covering root / non-root / no-uid platforms, the already-opted-out args, and the near-miss args above.

The pre-existing integration tests in that file cannot run in my environment — Chrome reports No usable sandbox! ... AppArmor userns restrictions there, on a clean checkout as well as with this change.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[elcodabra]

@googlebot I signed it!