Two Playwright agents on one machine is not a Playwright workers problem.

A fresh UUID directory per run, before anything else happens

The cheapest piece, and the one that does the most work. Every call to the assrt_test MCP tool mints a fresh runId with crypto.randomUUID() at the very top of the handler, before the agent class is even constructed. The run directory is computed as join(tmpdir(), "assrt", runId). Screenshots, video, the line-by-line log, and the structured event stream all hang off that directory. Two parallel assrt_test calls produce two disjoint UUIDs and therefore two disjoint trees on disk. There is no shared mutable file in the run path. The shared path is the persistent browser profile, and that is what the next two layers protect.

// /Users/matthewdi/assrt-mcp/src/mcp/server.ts, lines 427-432
// Every assrt_test call mints a fresh runId at the very top of the
// handler, before the agent is constructed. Two parallel calls get
// two disjoint directories on disk. No shared mutable file.

const crypto = await import("crypto");
const runId = crypto.randomUUID();
const runDir = join(tmpdir(), "assrt", runId);
const screenshotDir = join(runDir, "screenshots");
mkdirSync(screenshotDir, { recursive: true });

// Later in the same handler:
//   const videoDir   = join(runDir, "video");        // line 498
//   const logFile    = join(runDir, "execution.log"); // line 601
//   const eventsFile = join(runDir, "events.json");   // line 605

Three Chromium files that have to die before --user-data-dir can be passed

Chromium writes three sibling files into a profile while it runs: SingletonLock, SingletonSocket, and SingletonCookie. They exist so that a second chrome --user-data-dir=X invocation can find an already-running instance and forward its arguments instead of starting fresh. If the previous Chrome exited cleanly, the files are removed for you. If it crashed, was SIGKILLed, or you Ctrl-C'd the agent mid-run, the symlink stays. SingletonLock is the load-bearing one: it is a symlink whose target is the literal string hostname-PID, and Playwright launching into a profile with a live-looking lock is how you end up with a 180-second hung navigate.

The fix is a few lines of fs work. The detail that catches everyone is that existsSync follows symlinks and returns false when the target PID does not exist, so it would silently skip the unlink. You have to use lstatSync and ignore the resolved target.

// /Users/matthewdi/assrt-mcp/src/core/browser.ts, lines 311-347
// Persistent path. Run AFTER killOrphanChromeProcesses, BEFORE the
// --user-data-dir flag is appended. lstatSync (not existsSync) is
// load-bearing here because SingletonLock is a symlink whose target
// is the literal string "hostname-PID".

const userDataDir = join(homedir(), ".assrt", "browser-profile");
mkdirSync(userDataDir, { recursive: true });

await McpBrowserManager.killOrphanChromeProcesses(userDataDir);

const singletonFiles = ["SingletonLock", "SingletonSocket", "SingletonCookie"];
for (const name of singletonFiles) {
  const lockPath = join(userDataDir, name);
  let hasLock = false;
  try { lstatSync(lockPath); hasLock = true; } catch { /* no lock */ }
  if (hasLock) {
    try {
      unlinkSync(lockPath);
      console.error(`[browser] removed stale ${name} from browser profile`);
    } catch {
      console.error(`[browser] could not remove ${name}, falling back to isolated mode`);
      args.push("--isolated");
      isolated = true;
      break;
    }
  }
}
if (!isolated) {
  args.push("--user-data-dir", userDataDir);
}

Note the fallback. If any of the three files cannot be unlinked (because Chrome is actually still alive and holding it, which is the two-agent collision case), Assrt does not fight. It pushes --isolated onto the args, sets a local isolated = true, and the persistent path drops out. The losing agent runs in an in-memory profile for that one call and reports it in the launch log line.

The ps walk that runs before the singleton scrub

This is the layer that surprised me when I first read the source. The SingletonLock files are not the only thing that survives a crashed run. The Chrome process itself, and sometimes the Playwright MCP wrapper that spawned it, can stick around as orphans. They keep the user-data-dir busy. Removing the lock files while one of those orphans is still alive does not help; the orphan re-creates them.

So before touching the singleton files, Assrt walks three sources of PIDs and SIGKILLs everything pinned to the profile path. The three sources are:

• ps aux | grep for every process whose command line contains the exact --user-data-dir=<path> string. Catches the main Chrome and most renderer/utility children.
• The integer parsed from the SingletonLock symlink target after the - character. Catches the case where the main Chrome PID was missed by the ps grep, which I have seen on macOS specifically.
• A one-level parent walk that runs ps -o ppid= -p <pid> on every PID found so far, and adds the parent if the parent's command contains the substring playwright. That is how the Playwright MCP wrapper gets caught when its child Chrome was the only thing on ps aux.

// /Users/matthewdi/assrt-mcp/src/core/browser.ts, lines 149-182
// Three sources of truth, unioned. Then a one-level parent walk to
// catch the Playwright MCP wrapper if it owns one of the discovered
// pids. Returns a deduped Set of integers, never a string.

private static async collectProfilePids(userDataDir: string): Promise<number[]> {
  const pids = new Set<number>();

  // Source 1: every process with --user-data-dir=<path> on its cmdline
  const psOutput = execSync(
    `ps aux | grep -E "user-data-dir.*${userDataDir.replace(/\//g, "\\/")}" | grep -v grep || true`,
    { encoding: "utf-8", timeout: 5000 }
  ).trim();
  for (const line of psOutput.split("\n").filter(Boolean)) {
    const pid = parseInt(line.trim().split(/\s+/)[1], 10);
    if (pid && !isNaN(pid)) pids.add(pid);
  }

  // Source 2: the SingletonLock symlink target (encoded as hostname-PID)
  try {
    const target = readlinkSync(join(userDataDir, "SingletonLock"));
    const lockPid = parseInt(target.split("-").pop() || "", 10);
    if (lockPid && !isNaN(lockPid)) pids.add(lockPid);
  } catch { /* no lock */ }

  // Source 3: parents of (1) and (2) that are Playwright MCP wrappers
  for (const pid of [...pids]) {
    const ppid = parseInt(execSync(`ps -o ppid= -p ${pid}`).trim(), 10);
    if (ppid && ppid > 1) {
      const parentCmd = execSync(`ps -o command= -p ${ppid}`).trim();
      if (parentCmd.includes("playwright")) pids.add(ppid);
    }
  }
  return [...pids];
}

The kill loop runs twice with a 750 ms gap between sweeps. The second sweep covers the race where a child respawned, or a process whose PID was missed by the first ps. If the second sweep still returns PIDs, the function logs a warning and continues; the singleton-scrub layer downstream will either succeed or fall back to --isolated.

What it looks like when two agents collide

Two Claude Code sessions, both with @m13v/assrt configured as an MCP server, both calling assrt_test on the same target URL within the same second. Agent A wins the race. Agent B does not error; it transparently demotes itself to isolated mode for that one run. Here is the message sequence.

The single most important line in this exchange is the one labeled EBUSY. That is the catch block at browser.ts:335 firing, which pushes --isolated and breaks out of the singleton loop. The losing agent runs in memory, the winning agent owns the persistent session, and neither throws.

What raw launchPersistentContext does, and what the agent path adds

Both code paths use real Chromium. The difference is what happens before and around the launch.

// What two raw @playwright/mcp agents typically do
// when both want a persistent profile on the same host.

import { chromium } from "playwright";

const userDataDir = "/Users/me/.cache/playwright-profile";

// Agent A
const ctxA = await chromium.launchPersistentContext(userDataDir, {
  headless: true,
});
// ... runs scenario, exits, but child process leaks.
// SingletonLock on disk now points at a dead PID.

// Agent B starts a few seconds later.
const ctxB = await chromium.launchPersistentContext(userDataDir, {
  headless: true,
});
// chromium sees SingletonLock, opens-in-existing-browser-session
// behavior kicks in, the new browser routes commands into the
// dead-but-not-cleaned-up session, navigate() hangs for 180s,
// MCP stdio drops, you get "MCP client not connected" on the
// agent log with no actionable signal.

The on-disk state, before and after a launch

Toggle the panel below to see what the relevant filesystem paths look like during a clean two-agent run. The persistent profile is one path, owned by one Chrome at a time. The two run directories are disjoint UUIDs, owned by their respective agents forever.

What this means for you, in practice

A few opinions from running this in earnest for the last few months.

• If you only ever run one agent at a time, the persistent default is fine and you can ignore everything above. It just works because the orphan walk and the singleton scrub are no-ops on a clean host.
• If two Claude Code sessions are both going to call assrt_test against your local app, accept that one of them will run in isolated mode. That session will start logged out. Either run the login #Case first in that session, or use --extension mode and have both agents attach to your real Chrome.
• On CI, set ASSRT_ISOLATED=1 unconditionally. There is no reason to share state across runs in a CI environment, and isolated mode skips all three layers above for a small startup-time win.
• If your runner crashes mid-test (Ctrl-C in a hot loop, an OOM, a forced container kill), the next launch will quietly clean up after itself. You do not need to rm -rf the profile or restart the box. The orphan walk is exactly the mechanism that absorbs that case.

Frequently asked questions