fix(browser): clear stale Chrome singleton lock before launch

[RaviTharuma]

Problem

When an MCP client (or its host process) crashes or is killed without cleanly shutting down the browser, Chrome's singleton lock files (SingletonLock, SingletonSocket, SingletonCookie) persist in the user data directory. On the next startup, Chrome refuses to launch because it believes another instance is already running:

The browser is already running for /Users/<user>/.cache/chrome-devtools-mcp/chrome-profile.
Use --isolated to run multiple browser instances.

This is particularly disruptive for MCP clients that manage the browser lifecycle automatically. The only recovery options are manually deleting the lock files or using --isolated (which loses all session state, cookies, and logins). Users who rely on a persistent Chrome profile for authenticated workflows are stuck — they either lose their login state every time, or they have to manually intervene after every crash.

Reproduction

1. Start chrome-devtools-mcp with a persistent profile (the default)
2. Kill the parent process (e.g. the MCP client) without giving chrome-devtools-mcp a chance to shut down Chrome
3. Restart chrome-devtools-mcp → launch fails with the error above

Solution

This PR adds a clearStaleSingletonLock() helper that runs before puppeteer.launch() when a persistent user data directory is in use.

How it works:

1. Reads the SingletonLock symlink in the user data directory (Chrome writes it as hostname-PID)
2. Extracts the PID and checks whether the process is still alive via process.kill(pid, 0)
3. If the process is dead → removes SingletonLock, SingletonSocket, and SingletonCookie so Chrome can start cleanly
4. If the process is alive → leaves everything untouched; Chrome's own conflict detection handles it normally

This is a safe, minimal change:

• Only touches lock files when the owning process is confirmed dead
• No new dependencies
• No behavioral change when Chrome is running normally
• Existing --isolated behavior is unaffected

Test plan

• tsc --noEmit passes
• Stale lock (dead PID) → lock files removed, Chrome can start
• Live lock (own PID) → lock files preserved, no interference
• No lock file present → no-op, no errors
• Complex hostname format with multiple dashes (e.g. macbook-pro-16---m1-max.home-85428) → PID correctly extracted
• Garbage lock content (no parseable PID) → left alone, no errors

[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.

[RaviTharuma]

I have signed the CLA.

[OrKoN]

I believe Chrome is managing the lock files and we should not be clearing it for Chrome. I believe Chrome should already detect if the process is running. Do you have a test case or a screencast of this happening? Perhaps the fix needs to be done on the Chrome side.

[RaviTharuma]

@OrKoN Thanks for the review — fair question. Here's the concrete scenario:

Reproduction:

1. Start chrome-devtools-mcp with the default persistent profile (no --isolated)
2. The MCP client (e.g. Claude Code, OpenCode, Cursor) crashes, gets kill -9'd, or the terminal is force-closed
3. Chrome doesn't get a clean shutdown signal → SingletonLock persists in ~/.cache/chrome-devtools-mcp/chrome-profile/
4. Restart the MCP client → Chrome refuses to launch:

   The browser is already running for /Users/<user>/.cache/chrome-devtools-mcp/chrome-profile.
   Use --isolated to run multiple browser instances.
   

5. The only recovery is manually rm ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock*

You're right that Chrome itself handles lock detection when Chrome is the one managing its own lifecycle. But in the MCP context, Chrome is launched by puppeteer as a child process. When the parent (MCP client) crashes without triggering puppeteer's cleanup, Chrome exits too (orphaned child), but the lock files remain because nobody called browser.close().

Chrome's own "process alive" check works when Chrome crashes and restarts itself. But here, both Chrome and its parent are dead — Chrome just left its locks behind. On next startup, puppeteer.launch() asks Chrome to start with the same user data dir, and Chrome correctly sees the lock and refuses — it can't know the lock owner is dead because nobody told it to check.

The fix is minimal: read the PID from SingletonLock, check kill(pid, 0), remove only if the process is confirmed dead. If the process is alive, it's left untouched.

I don't have a screencast readily available but the reproduction steps above are deterministic — happens every time a persistent-profile MCP session is interrupted non-gracefully.

[OrKoN]

I am not able to reproduce that:

1. npx @modelcontextprotocol/inspector npx chrome-devtools-mcp@latest
2. Send a tool call to start the Chrome instance
3. Force close the terminal running npx @modelcontextprotocol/inspector npx chrome-devtools-mcp@latest or kill the client.

Observed: Chrome is automatically closed and can be started again. Could you please exact steps to reproduce? Could you confirm that the chrome-devtools-mcp server is actually killed/terminated? Related #1765 (comment)

[OrKoN]

So I think we should not handle the process checks for Chrome, let's find an exact scenario where this fails in an issue before revisiting this PR.