mcp-accessibility-scanner 3.1.0 → 3.2.0

package/lib/browserContextFactory.js

@@ -22,7 +22,7 @@ import coreBundle from 'playwright-core/lib/coreBundle';
 const { registryDirectory } = coreBundle.registry;
 const { startTraceViewerServer } = coreBundle.server;
 import { logUnhandledError, testDebug } from './utils/log.js';
-import { createGuid, createHash } from './utils/guid.js';
+import { createGuid, createHash, createShortGuid } from './utils/guid.js';
 import { outputFile } from './config.js';
 import { ensureNetworkPolicyRoutes } from './networkPolicy.js';
 /**
@@ -443,39 +443,144 @@ class BaseContextFactory {
     config;
     _logName;
     _browserPromise;
+    // Counts live handouts per browser object, claimed BEFORE awaiting context
+    // creation — the same pattern as CdpContextFactory. A `browser.contexts()`
+    // census cannot see a sibling still inside _doCreateContext(): if session
+    // A's close ran while session B's first newContext() was in flight, A saw
+    // itself as the last context and closed the shared browser out from under
+    // B. Keyed per browser object (not per factory) because an external
+    // disconnect makes _obtainBrowser hand out a fresh browser while stale
+    // handouts still reference the old one.
+    _handoutCounts = new WeakMap();
+    // Acquisitions that have entered createContext() but not yet claimed their
+    // per-browser handout count: `await` yields to the microtask queue even on
+    // an already-resolved browser promise, so a sibling's close running inside
+    // that window used to see zero remaining handouts and shut the shared
+    // browser down under the resuming caller. Registered synchronously before
+    // the first await (see _acquireBrowser) and consulted by every "am I the
+    // last one?" check. Keyed per obtain promise, not per factory: a pending
+    // acquisition on a NEW promise (after an external disconnect evicted the
+    // old one) must not keep the old browser from closing.
+    _pendingAcquisitions = new Map();
     constructor(name, config) {
         this._logName = name;
         this.config = config;
     }
-    async _obtainBrowser(clientInfo) {
+    // Deliberately not async: the returned promise must be the cached
+    // `_browserPromise` itself so callers can register pending acquisitions
+    // against it and use it for the identity guards, and the body must run
+    // synchronously so obtaining and registering happen in one continuation.
+    _obtainBrowser(clientInfo) {
         if (this._browserPromise)
             return this._browserPromise;
         testDebug(`obtain browser (${this._logName})`);
-        this._browserPromise = this._doObtainBrowser(clientInfo);
-        void this._browserPromise.then(browser => {
+        const promise = this._doObtainBrowser(clientInfo);
+        this._browserPromise = promise;
+        // The eviction is bound to the promise this browser came from — the same
+        // identity guard the close paths use: a close evicts the cache eagerly,
+        // so by the time the closing browser's asynchronous 'disconnected' fires
+        // (or a failed obtain rejects), a successor connection may already be
+        // cached, and clearing it would churn yet another browser for the next
+        // session while the successor is alive.
+        void promise.then(browser => {
             browser.on('disconnected', () => {
-                this._browserPromise = undefined;
+                if (this._browserPromise === promise)
+                    this._browserPromise = undefined;
             });
         }).catch(() => {
-            this._browserPromise = undefined;
+            if (this._browserPromise === promise)
+                this._browserPromise = undefined;
         });
-        return this._browserPromise;
+        return promise;
+    }
+    /**
+     * Obtains the shared browser and claims the caller's per-browser count via
+     * `claim`, atomically with the browser's delivery: the acquisition is
+     * registered in a synchronous counter before the first await, and `claim`
+     * runs in the same continuation that resolves the browser, so at every
+     * point the caller is visible either as pending or as a live handout. The
+     * close paths consult _hasPendingAcquisition() and defer the browser
+     * shutdown to a pending acquisition instead of treating themselves as last.
+     */
+    async _acquireBrowser(clientInfo, claim) {
+        const obtainedPromise = this._obtainBrowser(clientInfo);
+        this._pendingAcquisitions.set(obtainedPromise, (this._pendingAcquisitions.get(obtainedPromise) ?? 0) + 1);
+        try {
+            const browser = await obtainedPromise;
+            claim(browser);
+            return { browser, obtainedPromise };
+        }
+        finally {
+            const pending = (this._pendingAcquisitions.get(obtainedPromise) ?? 1) - 1;
+            if (pending > 0)
+                this._pendingAcquisitions.set(obtainedPromise, pending);
+            else
+                this._pendingAcquisitions.delete(obtainedPromise);
+        }
+    }
+    /**
+     * True while a createContext() has started against `obtainedPromise` but
+     * not yet claimed its per-browser count. A release that would otherwise be
+     * the last defers the browser shutdown to that acquisition — which either
+     * claims the count in the same continuation the promise resolves in (its
+     * own release then closes the browser), or fails to obtain the browser
+     * altogether, in which case there is no browser left to close (a rejected
+     * obtain never launched one).
+     */
+    _hasPendingAcquisition(obtainedPromise) {
+        return !!this._pendingAcquisitions.get(obtainedPromise);
+    }
+    _releaseHandout(browser) {
+        const remaining = Math.max(0, (this._handoutCounts.get(browser) ?? 1) - 1);
+        this._handoutCounts.set(browser, remaining);
+        return remaining === 0;
     }
     async createContext(clientInfo) {
         testDebug(`create browser context (${this._logName})`);
-        const browser = await this._obtainBrowser(clientInfo);
-        const browserContext = await this._doCreateContext(browser);
-        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
-    }
-    async _closeBrowserContext(browserContext, browser) {
-        testDebug(`close browser context (${this._logName})`);
-        if (browser.contexts().length === 1)
-            this._browserPromise = undefined;
-        await browserContext.close().catch(logUnhandledError);
-        if (browser.contexts().length === 0) {
-            testDebug(`close browser (${this._logName})`);
-            await browser.close().catch(logUnhandledError);
+        // `obtainedPromise` is the promise this browser came from — it guards the
+        // eager `_browserPromise` resets below: after an external disconnect a
+        // NEW promise may be in place, and clearing it would orphan the fresh
+        // connection other sessions are about to use.
+        const { browser, obtainedPromise } = await this._acquireBrowser(clientInfo, acquired => {
+            this._handoutCounts.set(acquired, (this._handoutCounts.get(acquired) ?? 0) + 1);
+        });
+        let browserContext;
+        try {
+            browserContext = await this._doCreateContext(browser);
         }
+        catch (error) {
+            // The handout never materialized. When it was the last one, the browser
+            // must not stay behind ownerless — a sibling's close may have deferred
+            // the browser shutdown to this in-flight creation.
+            if (this._releaseHandout(browser) && !this._hasPendingAcquisition(obtainedPromise)) {
+                if (this._browserPromise === obtainedPromise)
+                    this._browserPromise = undefined;
+                testDebug(`close browser (${this._logName})`);
+                await browser.close().catch(logUnhandledError);
+            }
+            throw error;
+        }
+        let released = false;
+        return {
+            browserContext,
+            close: async () => {
+                if (released)
+                    return;
+                released = true;
+                testDebug(`close browser context (${this._logName})`);
+                const last = this._releaseHandout(browser) && !this._hasPendingAcquisition(obtainedPromise);
+                // Cleared before the awaits so a createContext() arriving while this
+                // close is still in flight obtains a fresh browser instead of the
+                // closing one.
+                if (last && this._browserPromise === obtainedPromise)
+                    this._browserPromise = undefined;
+                await browserContext.close().catch(logUnhandledError);
+                if (last) {
+                    testDebug(`close browser (${this._logName})`);
+                    await browser.close().catch(logUnhandledError);
+                }
+            },
+        };
     }
 }
 class IsolatedContextFactory extends BaseContextFactory {
@@ -484,18 +589,26 @@ class IsolatedContextFactory extends BaseContextFactory {
         super('isolated', config);
     }
     async _doObtainBrowser(clientInfo) {
-        await injectCdpPort(this.config.browser);
+        const { cdpPortOptions, releaseCdpPort } = await allocateCdpPort(this.config.browser);
         const browserType = playwright[this.config.browser.browserName];
-        return browserType.launch({
-            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
-            ...this.config.browser.launchOptions,
-            handleSIGINT: false,
-            handleSIGTERM: false,
-        }).catch(error => {
-            if (error.message.includes('Executable doesn\'t exist'))
-                throw browserNotInstalledError(error);
-            throw error;
-        });
+        try {
+            return await browserType.launch({
+                tracesDir: await startTraceServer(this.config),
+                ...this.config.browser.launchOptions,
+                ...cdpPortOptions,
+                handleSIGINT: false,
+                handleSIGTERM: false,
+            }).catch(error => {
+                if (error.message.includes('Executable doesn\'t exist'))
+                    throw browserNotInstalledError(error);
+                throw error;
+            });
+        }
+        finally {
+            // Bound by the launched browser on success, free for reuse on failure —
+            // either way the reservation has served its purpose.
+            releaseCdpPort();
+        }
     }
     async _doCreateContext(browser) {
         return browser.newContext(this.config.browser.contextOptions);
@@ -519,6 +632,14 @@ class CdpContextFactory extends BaseContextFactory {
     constructor(config) {
         super('cdp', config);
     }
+    // Without --isolated every session gets the attached browser's one existing
+    // context, so a "separate" browser session would share its tabs, cookies
+    // and storage with everything else.
+    get sessionsUnsupportedReason() {
+        if (this.config.browser.isolated)
+            return undefined;
+        return 'this connection attaches to the browser\'s existing context, which every session would share (same tabs, cookies and storage). Add --isolated to give each session its own browser context.';
+    }
     // The CDP connection (and with it every route and page proxy) is shared by
     // all live sessions of this factory, so nothing may close it while a
     // sibling session still audits through it — neither a session's own
@@ -539,8 +660,16 @@ class CdpContextFactory extends BaseContextFactory {
     }
     async createContext(clientInfo) {
         testDebug('create browser context (cdp)');
-        const browser = await this._obtainBrowser(clientInfo);
-        this._sessionCounts.set(browser, (this._sessionCounts.get(browser) ?? 0) + 1);
+        // `obtainedPromise` guards the eager `_browserPromise` evictions below —
+        // same pattern as the base class: after an external disconnect a NEW
+        // promise may be in place, and clearing it would orphan the fresh
+        // connection other sessions are about to use. The session count is
+        // claimed atomically with the browser's delivery (see _acquireBrowser),
+        // so a sibling's close inside createContext's own await window defers to
+        // this acquisition instead of disconnecting under it.
+        const { browser, obtainedPromise } = await this._acquireBrowser(clientInfo, acquired => {
+            this._sessionCounts.set(acquired, (this._sessionCounts.get(acquired) ?? 0) + 1);
+        });
         let browserContext;
         try {
             browserContext = await this._doCreateContext(browser);
@@ -549,8 +678,11 @@ class CdpContextFactory extends BaseContextFactory {
             // Without this the CDP connection stays open after e.g. an unreadable
             // storage-state file, even though no context was ever handed out — but
             // only when no sibling session is still using the shared connection.
-            if (this._releaseBrowser(browser))
+            if (this._releaseBrowser(browser) && !this._hasPendingAcquisition(obtainedPromise)) {
+                if (this._browserPromise === obtainedPromise)
+                    this._browserPromise = undefined;
                 await browser.close().catch(logUnhandledError);
+            }
             throw error;
         }
         let released = false;
@@ -567,7 +699,13 @@ class CdpContextFactory extends BaseContextFactory {
                 // it stays.
                 if (this.config.browser.isolated)
                     await browserContext.close().catch(logUnhandledError);
-                if (this._releaseBrowser(browser)) {
+                if (this._releaseBrowser(browser) && !this._hasPendingAcquisition(obtainedPromise)) {
+                    // Evicted before the await so a createContext() arriving while
+                    // this disconnect is still in flight obtains a fresh connection
+                    // instead of the closing one — the 'disconnected' event that also
+                    // clears the cache fires too late to catch that window.
+                    if (this._browserPromise === obtainedPromise)
+                        this._browserPromise = undefined;
                     testDebug('disconnect browser (cdp)');
                     await browser.close().catch(logUnhandledError);
                 }
@@ -640,26 +778,97 @@ class CdpLaunchContextFactory {
     config;
     // See CdpContextFactory: fresh context when isolated, setStorageState otherwise.
     appliesStorageState = true;
+    // The live child launched on a pinned --cdp-launch-port, tracked from spawn
+    // until the process exits. The sessionsUnsupportedReason veto below keeps
+    // registry sessions off this path, but DEFAULT contexts reach it too —
+    // parallel handshake-free HTTP requests each build a per-request backend
+    // whose default context launches here — and a second launch against the
+    // pinned port cannot work while the first child lives: its own child can
+    // never bind the busy port, so the connect loop attaches to the FIRST
+    // child's endpoint, the "separate" context lands in a sibling's
+    // application, and cleanup kills a child that owns nothing. Serializing
+    // the launches would not fix that — the port stays bound for the first
+    // context's whole lifetime, so a queued second launch could only time out
+    // or cross-attach after all — hence the second concurrent context is
+    // honestly rejected instead. `closing` marks a teardown in progress (kill
+    // sent), which a new arrival may briefly wait out rather than failing a
+    // plain sequential close-then-relaunch on the OS shutdown tail.
+    _pinnedPortLaunch;
     constructor(config) {
         this.config = config;
     }
+    // Without --isolated a session would reuse a launched application's single
+    // existing context. With --isolated each context is created fresh, at the
+    // documented cost of launching another application instance per context —
+    // unless the port is pinned: then every session's child is launched against
+    // the SAME endpoint, the second session's connect loop reaches the first
+    // session's instance (its own child never bound the busy port), its
+    // "separate" context lands in a sibling's application, and its cleanup
+    // kills a child that owns nothing while leaking that context.
+    get sessionsUnsupportedReason() {
+        if (!this.config.browser.isolated)
+            return 'without --isolated each session would attach to a launched application\'s single shared context (same tabs, cookies and storage). Add --isolated to give each session its own browser context.';
+        if (this.config.browser.cdpLaunch?.port !== undefined)
+            return 'the pinned --cdp-launch-port can serve only one launched application at a time, so a second session would attach to the first session\'s instance. Drop --cdp-launch-port (each session then launches on its own free port) or run one session at a time.';
+        return undefined;
+    }
     async createContext(clientInfo) {
         const cdpLaunch = this.config.browser.cdpLaunch;
-        const port = cdpLaunch.port ?? await findFreePort();
+        if (cdpLaunch.port !== undefined) {
+            await this._waitForClosingPinnedPortHolder(cdpLaunch);
+            // Checked synchronously with the spawn-and-track below (nothing awaits
+            // in between on the pinned path): a concurrent createContext() resuming
+            // from the same wait could otherwise interleave here and both would
+            // launch against the one port.
+            this._assertPinnedPortFree(cdpLaunch);
+        }
+        // Reserved until the child is known to have bound the port (or the launch
+        // failed): findFreePort()'s probe socket is closed before the child
+        // spawns, so a concurrent session's probe could otherwise be handed the
+        // same port — both connect loops would then attach to whichever child
+        // bound first, sharing its context and killing the wrong child on
+        // cleanup (exactly the confusion the pinned-port session veto exists to
+        // prevent). In-process reservation suffices: the realistic collision
+        // source is concurrent createContext() calls in this process racing one
+        // OS port pool.
+        const allocatedPort = cdpLaunch.port === undefined ? await findFreePort({ reserve: true }) : undefined;
+        const port = cdpLaunch.port ?? allocatedPort;
         const endpoint = `http://127.0.0.1:${port}`;
         const args = (cdpLaunch.args ?? []).map(arg => arg.replaceAll('{port}', String(port)));
-        const childProcess = spawn(cdpLaunch.command, args, {
-            cwd: cdpLaunch.cwd,
-            env: {
-                ...process.env,
-                ...cdpLaunch.env,
-            },
-            stdio: ['ignore', 'ignore', 'pipe'],
-        });
-        childProcess.stderr.on('data', data => {
-            testDebug(`cdp-launch stderr: ${String(data).trimEnd()}`);
-        });
-        const browser = await this._waitForBrowser(endpoint, clientInfo, childProcess, cdpLaunch.startupTimeoutMs ?? 30000);
+        let browser;
+        let childProcess;
+        let pinnedLaunch;
+        try {
+            childProcess = spawn(cdpLaunch.command, args, {
+                cwd: cdpLaunch.cwd,
+                env: {
+                    ...process.env,
+                    ...cdpLaunch.env,
+                },
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+            if (cdpLaunch.port !== undefined)
+                pinnedLaunch = this._trackPinnedPortChild(childProcess);
+            childProcess.stderr?.on('data', data => {
+                testDebug(`cdp-launch stderr: ${String(data).trimEnd()}`);
+            });
+            // A successful connect proves the child owns the port, so the OS can no
+            // longer hand it to a sibling's probe; on failure the child is already
+            // killed and the port free again.
+            browser = await this._waitForBrowser(endpoint, clientInfo, childProcess, cdpLaunch.startupTimeoutMs ?? 30000);
+        }
+        catch (error) {
+            // _waitForBrowser has already killed the child on failure; marking the
+            // tracked launch closing lets the next pinned-port context wait out the
+            // exit instead of rejecting against a corpse.
+            if (pinnedLaunch)
+                pinnedLaunch.closing = true;
+            throw error;
+        }
+        finally {
+            if (allocatedPort !== undefined)
+                reservedPorts.delete(allocatedPort);
+        }
         let browserContext;
         try {
             if (this.config.browser.isolated) {
@@ -682,6 +891,8 @@ class CdpLaunchContextFactory {
             // The desktop process is already running by now; failing to obtain a
             // context (say, an unreadable storage-state file) must not leave it and
             // the CDP connection behind with nobody holding a close() for them.
+            if (pinnedLaunch)
+                pinnedLaunch.closing = true;
             await browser.close().catch(logUnhandledError);
             childProcess.kill('SIGTERM');
             throw error;
@@ -689,11 +900,62 @@ class CdpLaunchContextFactory {
         return {
             browserContext,
             close: async () => {
+                if (pinnedLaunch)
+                    pinnedLaunch.closing = true;
                 await browser.close().catch(logUnhandledError);
                 childProcess.kill('SIGTERM');
             }
         };
     }
+    /**
+     * Waits out a pinned-port holder whose teardown has already begun (kill
+     * sent, exit pending), bounded by the configured startup timeout — the
+     * same budget a launch gets — so a plain sequential close-then-relaunch
+     * does not flake on the child's asynchronous exit. A holder that is NOT
+     * closing is genuine concurrency; _assertPinnedPortFree rejects it.
+     */
+    async _waitForClosingPinnedPortHolder(cdpLaunch) {
+        const previous = this._pinnedPortLaunch;
+        if (!previous?.closing)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                previous.exited,
+                new Promise(resolve => {
+                    timer = setTimeout(resolve, cdpLaunch.startupTimeoutMs ?? 30000);
+                    timer.unref?.();
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Rejects a pinned-port launch while another live context's child still
+     * holds the port (see _pinnedPortLaunch). Synchronous, so callers can bind
+     * the check to the spawn without an interleaving window. */
+    _assertPinnedPortFree(cdpLaunch) {
+        if (this._pinnedPortLaunch)
+            throw new Error(`The pinned --cdp-launch-port ${cdpLaunch.port} already serves a launched application from another live browser context, and a second launch on the same port would silently attach to that application instead of its own. Close the other context first, or drop --cdp-launch-port so each context launches on its own free port.`);
+    }
+    /** Tracks the pinned-port child until its process is gone; identity-guarded
+     * so a stale exit can never untrack a successor's launch. The 'error'
+     * listener covers a spawn that never produces an 'exit' (e.g. ENOENT). */
+    _trackPinnedPortChild(childProcess) {
+        const launch = { closing: false, exited: undefined };
+        launch.exited = new Promise(resolve => {
+            const done = () => {
+                if (this._pinnedPortLaunch === launch)
+                    this._pinnedPortLaunch = undefined;
+                resolve();
+            };
+            childProcess.once('exit', done);
+            childProcess.once('error', done);
+        });
+        this._pinnedPortLaunch = launch;
+        return launch;
+    }
     async _waitForBrowser(endpoint, clientInfo, childProcess, startupTimeoutMs) {
         const deadline = Date.now() + startupTimeoutMs;
         const connectOptions = {
@@ -731,11 +993,60 @@ export class PersistentContextFactory {
     name = 'persistent';
     description = 'Create a new persistent browser context';
     _userDataDirs = new Set();
+    // Set while a live context (or one still launching) holds the stable
+    // `mcp-<browser>-<workspace>` profile. The profile can back only one running browser at
+    // a time (Chromium's ProcessSingleton lock), and every stateful backend's
+    // default context resolves to it — one such context under stdio, but each
+    // concurrent Mcp-Session-Id HTTP client brings its own backend, and the
+    // second used to spin on the lock and fail with "Browser is already in
+    // use". The stable profile goes to the FIRST claimant; genuinely
+    // concurrent claimants fall back to a disposable profile (their audit
+    // runs, without the stable profile's sign-in state), and the claim is
+    // released when the holder's context closes so the next default context —
+    // and the profile's persisted state — line up again. Checked-and-set
+    // synchronously, so concurrent createContext() calls cannot both claim.
+    //
+    // A holder that has BEGUN closing (`closing`, set via the handle's
+    // closeStarting notice) is a release in progress, not genuine concurrency:
+    // its async shutdown — dominated by the Context's bounded pending-download
+    // drain — can outlast a --connect-tool/--vscode provider switch-away, and a
+    // claimant arriving in that window (the user switching back) used to be
+    // silently demoted to a disposable profile, losing the stable profile's
+    // sign-in state. Such a claimant now waits on `released` (bounded: the
+    // drain is capped at 30s and the browser shutdown bounds the rest) and
+    // then claims the stable profile itself.
+    _stableProfileClaim;
+    // Claims the stable profile for one context. Synchronous, so a concurrent
+    // createContext() cannot interleave between check and set.
+    _claimStableProfile() {
+        let resolveReleased;
+        const released = new Promise(resolve => { resolveReleased = resolve; });
+        const claim = {
+            closing: false,
+            released,
+            release: () => {
+                if (this._stableProfileClaim === claim)
+                    this._stableProfileClaim = undefined;
+                resolveReleased();
+            },
+        };
+        this._stableProfileClaim = claim;
+        return claim;
+    }
     constructor(config) {
         this.config = config;
     }
-    async createContext(clientInfo) {
-        await injectCdpPort(this.config.browser);
+    // A user-supplied profile directory can back only one running browser at a
+    // time (Chromium's ProcessSingleton lock), and minting disposable profiles
+    // behind the user's back would silently drop the sign-in state they asked
+    // for — so explicit sessions are refused in that configuration. Without
+    // --user-data-dir, sessions run in their own disposable profiles below.
+    get sessionsUnsupportedReason() {
+        if (this.config.browser.userDataDir)
+            return 'the configured --user-data-dir profile can back only one running browser at a time. Drop --user-data-dir (extra sessions run in their own disposable profiles) or use --isolated.';
+        return undefined;
+    }
+    async createContext(clientInfo, _abortSignal, _toolName, options) {
         testDebug('create browser context (persistent)');
         // launchPersistentContext() accepts a storageState option without applying
         // it (verified against 1.61.1) — the profile is normally the state — so it
@@ -757,22 +1068,103 @@ export class PersistentContextFactory {
         // unwritable output directory), and nothing after the directory is created
         // may throw outside the cleanup scope below, or failed starts would leave
         // stray profiles behind.
-        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
-        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath, storageState ? `-storage-state-${createGuid()}` : '');
-        this._userDataDirs.add(userDataDir);
-        testDebug('lock user data dir', userDataDir);
+        const tracesDir = await startTraceServer(this.config);
+        // Per-launch and reserved until this launch binds it: two explicit
+        // sessions launching concurrently interleave their awaits here, and a
+        // port written into the shared config would be overwritten by the
+        // sibling before launchPersistentContext() reads it — both browsers
+        // then race for one port and one fails to bind.
+        const { cdpPortOptions, releaseCdpPort } = await allocateCdpPort(this.config.browser);
+        // An explicitly opened browser session gets its own disposable profile for
+        // the same reason a storage-state context does: the stable profile can back
+        // only one running browser, so a second session sharing it would spin on
+        // the ProcessSingleton lock and fail with "Browser is already in use". The
+        // DEFAULT (no-handle) context keeps the stable `mcp-<browser>-<workspace>` profile, so
+        // its sign-in state still survives restarts.
+        let profileSuffix = storageState
+            ? `-storage-state-${createGuid()}`
+            : options?.browserSession
+                ? `-session-${createGuid()}`
+                : '';
+        let claim;
+        let userDataDir;
+        let disposableProfile = false;
         const browserType = playwright[this.config.browser.browserName];
+        // The cleanup scope opens right after the port reservation: the
+        // profile-directory mkdir below can reject too (e.g. a transient volume
+        // failure), and a failure between the claim and the launch loop used to
+        // escape the cleanup — the claim was never reset (every later default
+        // context misclassified as concurrent and demoted to a disposable
+        // profile) and the reserved CDP port was never released.
         try {
+            // A default (no-suffix) context claims the stable profile — unless a
+            // sibling already holds it (see _stableProfileClaim): then it runs in
+            // a disposable profile instead of failing the launch. A user-supplied
+            // --user-data-dir is exempt: silently substituting a disposable profile
+            // would drop the sign-in state the user explicitly asked for, so that
+            // configuration keeps the launch-time contention error.
+            if (!profileSuffix && !this.config.browser.userDataDir) {
+                // A holder that has begun closing is a release in progress, not
+                // genuine concurrency: wait for the release (bounded by the holder's
+                // capped download drain and browser shutdown) instead of silently
+                // demoting this context to a disposable profile. Re-checked after
+                // the wait — another claimant may have won the freed claim.
+                const holder = this._stableProfileClaim;
+                if (holder?.closing) {
+                    testDebug('stable persistent profile holder is closing; waiting for its release');
+                    await holder.released;
+                }
+                if (this._stableProfileClaim) {
+                    profileSuffix = `-concurrent-${createGuid()}`;
+                    testDebug('stable persistent profile is in use by a concurrent context; falling back to a disposable profile');
+                }
+                else {
+                    claim = this._claimStableProfile();
+                }
+            }
+            userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(profileSuffix);
+            // Guarded on the config profile too: sessionsUnsupportedReason keeps
+            // registry sessions out of a user-supplied --user-data-dir, so a suffix
+            // here always means the guid-fresh managed directory above — but a direct
+            // caller combining both must still never see the user's profile deleted.
+            disposableProfile = !!profileSuffix && !this.config.browser.userDataDir;
+            this._userDataDirs.add(userDataDir);
+            testDebug('lock user data dir', userDataDir);
             for (let i = 0; i < 5; i++) {
                 try {
                     const browserContext = await browserType.launchPersistentContext(userDataDir, {
                         tracesDir,
                         ...this.config.browser.launchOptions,
+                        ...cdpPortOptions,
                         ...contextOptions,
                         handleSIGINT: false,
                         handleSIGTERM: false,
                     });
-                    return await this._applyStorageState(browserContext, storageState, userDataDir);
+                    const result = await this._applyStorageState(browserContext, storageState, userDataDir, disposableProfile);
+                    if (!claim)
+                        return result;
+                    const heldClaim = claim;
+                    return {
+                        browserContext: result.browserContext,
+                        // The owning Context's advance notice that close() will follow
+                        // once its async cleanup (the bounded download drain) finishes:
+                        // from here on a new default claimant waits for the release
+                        // instead of treating this holder as genuine concurrency.
+                        closeStarting: () => { heldClaim.closing = true; },
+                        close: async () => {
+                            try {
+                                await result.close();
+                            }
+                            finally {
+                                // Released only after the browser has shut down, so the next
+                                // claimant's launch meets a freed ProcessSingleton lock (the
+                                // launch retry loop covers the OS-level shutdown tail).
+                                // release() is idempotent and identity-guarded, so a repeated
+                                // close() can never free a claim a successor context holds.
+                                heldClaim.release();
+                            }
+                        },
+                    };
                 }
                 catch (error) {
                     if (error instanceof StorageStateError)
@@ -790,20 +1182,29 @@ export class PersistentContextFactory {
             throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
         }
         catch (error) {
+            // A claim that never produced a context must not pin the stable profile
+            // forever — the next default context would needlessly fall back to a
+            // disposable profile with the stable one sitting free.
+            claim?.release();
             // The disposable profile belongs to this context alone, so a launch that
             // never produced a context must not leave it behind — repeated failed
             // starts would otherwise pile one stray directory into the registry each.
             // (Already removed on the StorageStateError path; rm is idempotent.)
-            if (storageState) {
+            if (disposableProfile && userDataDir !== undefined) {
                 await fs.promises.rm(userDataDir, { recursive: true, force: true }).catch(() => { });
                 this._userDataDirs.delete(userDataDir);
             }
             throw error;
         }
+        finally {
+            // Bound by the launched browser on success, free for reuse on failure —
+            // either way the reservation has served its purpose.
+            releaseCdpPort();
+        }
     }
     // Separate from the launch retry loop: its `catch` retries on messages a
     // malformed storage-state file could coincidentally match (`Invalid URL`).
-    async _applyStorageState(browserContext, storageState, userDataDir) {
+    async _applyStorageState(browserContext, storageState, userDataDir, disposableProfile) {
         if (storageState) {
             try {
                 // Startup pages can keep persisting their anonymous identity while the
@@ -817,41 +1218,61 @@ export class PersistentContextFactory {
             catch (error) {
                 // Nobody holds a close() for this context yet, so a bad storage-state
                 // file must not leave the launched browser running.
-                await this._closeBrowserContext(browserContext, userDataDir, true);
+                await this._closeBrowserContext(browserContext, userDataDir, disposableProfile);
                 throw new StorageStateError(error instanceof Error ? error.message : String(error));
             }
         }
-        const close = () => this._closeBrowserContext(browserContext, userDataDir, !!storageState);
+        const close = () => this._closeBrowserContext(browserContext, userDataDir, disposableProfile);
         return { browserContext, close };
     }
     async _closeBrowserContext(browserContext, userDataDir, disposeUserDataDir = false) {
         testDebug('close browser context (persistent)');
         testDebug('release user data dir', userDataDir);
         await browserContext.close().catch(() => { });
-        // A storage-state profile is unique to this context and holds nothing worth
-        // keeping — the state file is the durable copy — so it is removed rather
-        // than left to pile up next to the regular persistent profile.
+        // A storage-state or browser-session profile is unique to this context and
+        // holds nothing worth keeping — the state file (or the default profile) is
+        // the durable copy — so it is removed rather than left to pile up next to
+        // the regular persistent profile.
         if (disposeUserDataDir)
             await fs.promises.rm(userDataDir, { recursive: true, force: true }).catch(() => { });
         this._userDataDirs.delete(userDataDir);
         testDebug('close browser context complete (persistent)');
     }
-    // The suffix keeps disposable storage-state profiles apart from the regular
-    // persistent profile (and, carrying a per-context guid, from each other), so
-    // removing one can never destroy an interactive session or a sibling's.
-    async _createUserDataDir(rootPath, suffix) {
+    // The suffix keeps disposable storage-state and browser-session profiles
+    // apart from the regular persistent profile (and, carrying a per-context
+    // guid, from each other), so removing one can never destroy an interactive
+    // session or a sibling's.
+    //
+    // The workspace token keeps different servers' stable profiles apart. MCP
+    // clients typically launch one stdio server per workspace, cwd'd into it, so
+    // hashing process.cwd() gives each workspace its own deterministic profile:
+    // sign-in state survives restarts of the same server (same cwd, same hash),
+    // while servers for other workspaces neither contend for this profile's
+    // ProcessSingleton lock nor inherit its cookies and storage. (This restores
+    // the separation the deprecated MCP Roots hash used to provide — keyed on
+    // the server's own launch directory instead of a client-reported root, so it
+    // covers every client rather than only those that exposed roots.)
+    async _createUserDataDir(suffix) {
         const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
         const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
-        // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
-        const rootPathToken = rootPath ? `-${createHash(rootPath)}` : '';
-        const result = path.join(dir, `mcp-${browserToken}${rootPathToken}${suffix}`);
+        const workspaceToken = `-${createHash(process.cwd())}`;
+        const result = path.join(dir, `mcp-${browserToken}${workspaceToken}${suffix}`);
         await fs.promises.mkdir(result, { recursive: true });
         return result;
     }
 }
-async function injectCdpPort(browserConfig) {
-    if (browserConfig.browserName === 'chromium')
-        browserConfig.launchOptions.cdpPort = await findFreePort();
+/**
+ * Allocates the CDP port for a Chromium launch, reserved until that launch has
+ * bound it (or failed). The port travels in per-launch options instead of
+ * being written into the shared config: concurrent launches from one factory
+ * (e.g. two explicit persistent sessions) would otherwise overwrite each
+ * other's `cdpPort` between allocation and launch and race for a single port.
+ */
+async function allocateCdpPort(browserConfig) {
+    if (browserConfig.browserName !== 'chromium')
+        return { cdpPortOptions: {}, releaseCdpPort: () => { } };
+    const cdpPort = await findFreePort({ reserve: true });
+    return { cdpPortOptions: { cdpPort }, releaseCdpPort: () => reservedPorts.delete(cdpPort) };
 }
 /**
  * Builds the HTTP headers sent with a `connectOverCDP` request: the client
@@ -866,15 +1287,33 @@ function cdpConnectHeaders(clientInfo, browserConfig) {
     Object.assign(headers, browserConfig.cdpHeaders);
     return Object.keys(headers).length ? headers : undefined;
 }
-async function findFreePort() {
-    return new Promise((resolve, reject) => {
-        const server = net.createServer();
-        server.listen(0, () => {
-            const { port } = server.address();
-            server.close(() => resolve(port));
+/**
+ * Ports handed out by `findFreePort({ reserve: true })` whose intended owner
+ * has not bound them yet. The probe socket below is closed before the caller
+ * uses the port, so without this set two concurrent allocations in this
+ * process could be handed the same port. Module-level because every factory
+ * in the process draws from the one OS port pool.
+ */
+const reservedPorts = new Set();
+async function findFreePort(options) {
+    for (;;) {
+        const port = await new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.listen(0, () => {
+                const { port } = server.address();
+                server.close(() => resolve(port));
+            });
+            server.on('error', reject);
         });
-        server.on('error', reject);
-    });
+        // Reserved ports are skipped for every caller — nothing may be pointed at
+        // a port a launched child is still starting up on. The check-and-reserve
+        // is synchronous, so concurrent allocations cannot interleave inside it.
+        if (reservedPorts.has(port))
+            continue;
+        if (options?.reserve)
+            reservedPorts.add(port);
+        return port;
+    }
 }
 /**
  * Builds the user-facing "browser not installed" error from Playwright's raw
@@ -889,10 +1328,38 @@ function browserNotInstalledError(error) {
     const location = match ? `; expected executable at ${match[1].trim()}` : '';
     return new Error(`Browser specified in your config is not installed${location}. Either install it (likely) or change the config.`);
 }
-async function startTraceServer(config, rootPath) {
+// One trace-viewer server and traces directory per config — i.e. per server
+// run, the same WeakMap pattern as resolveOutputDir. startTraceViewerServer()
+// binds a listening HTTP socket that nothing ever closes, so starting one per
+// browser launch (the persistent factory launches per context, so every
+// explicit-session open/close cycle) leaked a listener for the life of the
+// process. Sharing one tracesDir across launches is safe for the trace files:
+// each Context records under its own `trace-<guid>` name (see acquireTrace in
+// context.ts), exactly as --isolated mode has always shared its per-browser
+// tracesDir.
+const traceServers = new WeakMap();
+async function startTraceServer(config) {
     if (!config.saveTrace)
         return undefined;
-    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
+    let started = traceServers.get(config);
+    if (!started) {
+        started = doStartTraceServer(config);
+        traceServers.set(config, started);
+        // A failed start (e.g. an unwritable output directory) is not memoized:
+        // the next launch retries instead of replaying the rejection for the
+        // process lifetime. Guarded by identity — a retry may already have
+        // stored a fresh in-flight promise by the time this handler runs.
+        started.catch(() => {
+            if (traceServers.get(config) === started)
+                traceServers.delete(config);
+        });
+    }
+    return started;
+}
+async function doStartTraceServer(config) {
+    // The random suffix keeps two configs resolving in the same millisecond
+    // from sharing a trace folder. Nothing parses the folder name back.
+    const tracesDir = await outputFile(config, `traces-${Date.now()}-${createShortGuid()}`);
     const server = await startTraceViewerServer();
     const urlPrefix = server.urlPrefix('human-readable');
     const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';