Headless chrome test parallelism flakiness is a symlink problem

Two reasons. The boring one is resource contention: 20 headless Chromes contending for CPU and GPU time will blow through assertion timeouts long before they blow through memory, and that looks like 'random' flakes in logs. The interesting one, the one almost nobody writes about, is the Chromium singleton lock. A user-data-dir can only be opened by one Chrome process at a time; the lock is a symlink named `SingletonLock` whose target is `hostname-PID`. When a worker process dies without cleaning up (SIGKILL, OOM, CI runner timeout), the symlink survives. The next parallel worker that tries to open that profile gets 'Opening in existing browser session' and hangs. In CI this looks like intermittent startup flakiness because the failure depends on whether the previous run finished cleanly. Assrt's MCP layer evicts the lock before every launch, which is why its parallel runs do not inherit the crash state of the run before.

They are three different coordination points inside one user-data-dir. `SingletonLock` is a symlink whose presence means 'some Chrome owns this profile'; it is the one most people know about. `SingletonSocket` is the abstract Unix socket Chrome's launcher uses to send a 'focus your window / open a new tab' request to a running instance. `SingletonCookie` is a short random cookie the launcher checks to confirm it is talking to the same profile. If any of the three survive a crash, a subsequent launch can either hang, silently reuse an invisible process, or print 'Opening in existing browser session' and exit without a useful stack trace. The code in `assrt-mcp/src/core/browser.ts` at lines 326-342 iterates all three by name, uses `lstatSync` rather than `existsSync` (because the broken symlink target makes `existsSync` lie), and unlinks each. If an unlink fails, it falls back to Chrome's `--isolated` in-memory profile so the run still proceeds.

`existsSync` follows symlinks. `SingletonLock` is a dangling symlink whose target is the PID of the dead Chrome process. When the target PID no longer resolves, `existsSync` returns false and you silently skip the cleanup, so the next launch still sees the leftover link and fails. `lstatSync` stats the symlink itself, not what it points to, so it correctly reports that the link exists and needs to be removed. This is a load-bearing two-character difference. If you copy-paste naive code from Stack Overflow answers on this problem, it almost always uses `existsSync` and it almost always fails on exactly the Chromes that crashed hardest.

Playwright's test runner gives each test a fresh `BrowserContext` inside a shared browser process; it does not give each test a fresh user-data-dir unless you launch persistent mode with different paths per worker. If you are running in persistent mode and a worker crashes, the next run on that worker inherits the exact singleton-lock problem described above, and Playwright will not clean it for you. The fix is either: stop using persistent mode (isolated contexts are cleaner for most parallel suites), or actively evict the three singleton files between launches. Assrt's MCP runner does both, depending on how it is invoked. When `--isolated` is passed it runs with an in-memory profile (no disk state, no lock to leak); otherwise it uses `~/.assrt/browser-profile` and cleans the singletons before every spawn.

Because the MCP server is the thing that boots Chromium for every scenario an agent runs against a target URL. If you drive Assrt from a harness that spawns multiple scenarios at once (e.g. one MCP client per CI job, fanned out across a matrix), you are implicitly doing parallel headless Chrome, and you hit the same singleton-lock failure mode as a traditional Playwright test matrix. The difference is that the code that launches Chrome is one TypeScript file you can read in ten minutes — `assrt-mcp/src/core/browser.ts` — so you can see exactly why your parallel runs stabilize. Closed cloud vendors hide this layer. You pay for it when CI flakes and there is nothing to grep.

It is the per-call MCP tool timeout defined at `browser.ts:381` as `TOOL_TIMEOUT_MS = 120_000`. The MCP SDK defaults to 60 seconds, which is not enough for slow navigations on real sites, especially under parallel load. Raising it to 120 seconds does not mask flakiness, it exposes it. A navigation that takes 90 seconds is information: either the site is actually that slow under load, or you have a retry loop disguised as a wait. Either way, the log line `[mcp] browser_navigate url=... (92000ms)` is worth more than a raw 'timed out after 60s' error, because it tells you the page eventually responded and by how much. If you then see the same 90-second navigation drop to 800ms when you run the scenario in isolation, you have diagnosed a CPU-contention flake rather than a real bug.

For rendering fidelity, yes. For parallelism and the singleton-lock problem specifically, it changes nothing. The lock is held by the Chromium process on its user-data-dir, and the user-data-dir is shared between old and new headless modes. If you switched to `--headless=new` and your parallel runs got more stable, the likely reason is that `--headless=new` exposes bugs in your own code — requestAnimationFrame callbacks, Intersection Observer, reduced-motion detection — that the legacy `--headless` mode silently worked around. Fixing those makes you faster, but it does not address the specific CI failure where 'Chrome is already running' kills 1 in 20 jobs after a prior crash. That one is a filesystem problem.

If the code at `browser.ts:336-338` catches an error unlinking a singleton file (permissions, read-only filesystem, weirdness on Windows subsystems, etc), it pushes `--isolated` onto the Playwright MCP args and sets `isolated = true`. That tells Chromium to use an in-memory user-data-dir that lives only for the process lifetime. Nothing persists, nothing to lock. The trade-off: logged-in state does not carry across scenarios, so you have to re-authenticate in every run. That is a real cost for integration testing, which is why the default is persistent mode with singleton cleanup. The fallback exists so that an unluckily permissioned filesystem never brings the whole run down; it degrades to ephemeral instead of failing.

Before your next CI run, `ls -la ~/.cache/google-chrome` (or whatever user-data-dir Playwright is using on that runner) and look for `SingletonLock`, `SingletonSocket`, `SingletonCookie`. If the run before yours crashed, at least one of them will be there. Then launch Chrome against that profile and watch it either hang or print 'Opening in existing browser session'. To reproduce deliberately: launch chromium with `--user-data-dir=/tmp/demo`, send it SIGKILL mid-session, then launch again with the same `--user-data-dir`. The second launch will stall. Remove `/tmp/demo/SingletonLock` with `unlink` and try again; it succeeds. This is the loop Assrt automates.

Less, but still yes. Ephemeral runners start clean, so the 'leftover from the previous run' path does not apply. What does still apply: within a single job, if you run scenarios in parallel (several `npx playwright test` shards in one container, or several worker processes against a shared persistent profile), the same singleton-lock symptoms emerge between workers rather than between runs. If your CI uses a shared cache to persist browser state between runs for speed — some teams do this to avoid re-logging-in — you inherit the cross-run failure mode as well. The cleanest fix on GHA is to keep the profile in-memory per job via `--isolated` or equivalent; the second-cleanest is to evict the three singletons on job start.