mcp-accessibility-scanner 3.0.1 → 3.2.0

package/lib/browserContextFactory.js

@@ -22,9 +22,413 @@ import coreBundle from 'playwright-core/lib/coreBundle';
 const { registryDirectory } = coreBundle.registry;
 const { startTraceViewerServer } = coreBundle.server;
 import { logUnhandledError, testDebug } from './utils/log.js';
-import { createHash } from './utils/guid.js';
+import { createGuid, createHash, createShortGuid } from './utils/guid.js';
 import { outputFile } from './config.js';
+import { ensureNetworkPolicyRoutes } from './networkPolicy.js';
+/**
+ * Throws when a storage state is configured but `factory` will not apply it. A
+ * factory that neither creates a fresh context with the state nor applies it to
+ * the context it reuses would drop it without a word and audit the site as an
+ * anonymous user, which looks exactly like a successful run. Every factory in
+ * this file applies it one way or the other; the extension factory cannot — it
+ * works through the user's own running browser, where clearing every origin's
+ * cookies to install the recorded state is not an acceptable side effect.
+ * Callers pass the remedy that fits the mode they selected — the factory that
+ * creates the context is not always the one `contextFactory()` built.
+ */
+export function assertStorageStateSupported(config, factory, remedy) {
+    if (config.browser.contextOptions?.storageState && !factory.appliesStorageState)
+        throw new Error(`Storage state cannot be applied in this mode. ${remedy}`);
+}
+/**
+ * Throws when the configured storage state would be installed inside a profile
+ * directory the user supplied. The profile carries its own session data — it is
+ * data this server does not own — and resetting it to the recorded state would
+ * destroy it. Every factory that lands the state in a context backed by
+ * `--user-data-dir` calls this before touching the browser; callers pass the
+ * remedy that fits their mode.
+ */
+export function assertStorageStateDoesNotResetUserProfile(config, remedy) {
+    if (config.browser.contextOptions?.storageState && config.browser.userDataDir)
+        throw new Error(`--storage-state and --user-data-dir contradict each other: the profile carries its own session data, and resetting a user-supplied profile to match the recorded state would destroy it. ${remedy}`);
+}
 export function contextFactory(config) {
+    const factory = createContextFactory(config);
+    // Every built-in factory now applies a storage state; the guard stays so a
+    // future factory that forgets to declare support rejects the option instead
+    // of silently dropping it.
+    assertStorageStateSupported(config, factory, 'Drop the storage state and sign in interactively before auditing.');
+    return factory;
+}
+// The rules addCookies enforces client-side (verified against Playwright
+// 1.61.1: empty or missing domain/path without a url, a url combined with a
+// domain or a path, about:blank/data:/unparseable urls, an expires other
+// than -1 or a positive number up to Playwright's ceiling, and sameSite
+// outside Strict/Lax/None are all rejected there — non-http(s) url schemes
+// and malformed origin strings fail browser-side during the apply). Failing
+// them here keeps the failure ahead of the cache clear; anything these
+// checks miss still fails inside setStorageState.
+const cookieUrlProblem = (url) => {
+    if (typeof url !== 'string')
+        return 'is not a string';
+    if (url === 'about:blank')
+        return 'cannot be about:blank';
+    if (url.startsWith('data:'))
+        return 'cannot be a data: URL';
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return `must be an http(s) URL, not ${parsed.protocol}`;
+    }
+    catch {
+        return 'is not a valid absolute URL';
+    }
+    return null;
+};
+const isValidIndexedDBKey = (value) => typeof value === 'string'
+    || (typeof value === 'number' && Number.isFinite(value))
+    || (value instanceof Date && Number.isFinite(value.getTime()))
+    || value instanceof ArrayBuffer
+    || ArrayBuffer.isView(value)
+    || (Array.isArray(value) && value.every(isValidIndexedDBKey));
+const indexedDBIdentifier = /^[$_\p{ID_Start}][$\u200C\u200D\p{ID_Continue}]*$/u;
+const isValidIndexedDBKeyPath = (value) => typeof value === 'string' && (value === '' || value.split('.').every(part => indexedDBIdentifier.test(part)));
+const isValidIndexedDBKeyPathArray = (value) => Array.isArray(value) && !!value.length && value.every(isValidIndexedDBKeyPath);
+function assertValidStorageState(state) {
+    for (const value of state.cookies ?? []) {
+        const cookie = value;
+        const problem = !cookie || typeof cookie !== 'object'
+            ? 'a cookie entry is not an object'
+            : !cookie.url && (!cookie.domain || !cookie.path)
+                ? `cookie "${String(cookie.name ?? '')}" should have a url or a domain/path pair`
+                : cookie.url && cookie.domain
+                    ? `cookie "${String(cookie.name ?? '')}" should have either a url or a domain, not both`
+                    : cookie.url && cookie.path
+                        ? `cookie "${String(cookie.name ?? '')}" should have either a url or a path, not both`
+                        : cookie.url !== undefined && cookieUrlProblem(cookie.url)
+                            ? `cookie "${String(cookie.name ?? '')}" has a url that ${cookieUrlProblem(cookie.url)}`
+                            : cookie.expires !== undefined && (typeof cookie.expires !== 'number' || Number.isNaN(cookie.expires) || (cookie.expires !== -1 && (cookie.expires <= 0 || cookie.expires > 253402300799)))
+                                ? `cookie "${String(cookie.name ?? '')}" should have a valid expires — only -1 or a positive unix timestamp in seconds up to 253402300799 (9999-12-31T23:59:59Z, Playwright's own ceiling) is allowed`
+                                : cookie.sameSite !== undefined && !['Strict', 'Lax', 'None'].includes(cookie.sameSite)
+                                    ? `cookie "${String(cookie.name ?? '')}" has sameSite "${String(cookie.sameSite)}", expected one of Strict|Lax|None`
+                                    : null;
+        if (problem)
+            throw new Error(`Invalid storage state: ${problem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
+    }
+    for (const value of state.origins ?? []) {
+        const entry = value;
+        // Restoring an origin's storage navigates Playwright's temporary page to
+        // it — a malformed or non-http(s) origin fails that navigation after the
+        // clear.
+        const problem = !entry || typeof entry !== 'object'
+            ? 'an origins entry is not an object'
+            : typeof entry.origin !== 'string' || cookieUrlProblem(entry.origin)
+                ? `origins entry "${String(entry?.origin ?? '')}" is not an absolute http(s) URL`
+                : null;
+        if (problem)
+            throw new Error(`Invalid storage state: ${problem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
+        const databaseNames = new Set();
+        for (const value of Array.isArray(entry?.indexedDB) ? entry.indexedDB : []) {
+            const database = value;
+            const stores = Array.isArray(database.stores) ? database.stores : [];
+            let indexedDBProblem = !Number.isSafeInteger(database.version) || database.version <= 0
+                ? `IndexedDB database "${String(database.name ?? '')}" should have a positive integer version`
+                : databaseNames.has(String(database.name))
+                    ? `IndexedDB database name "${String(database.name)}" is duplicated`
+                    : null;
+            databaseNames.add(String(database.name));
+            const storeNames = new Set();
+            for (const store of stores) {
+                const storeName = String(store.name);
+                indexedDBProblem ??= storeNames.has(storeName)
+                    ? `IndexedDB object store name "${storeName}" is duplicated in database "${String(database.name)}"`
+                    : store.keyPath !== undefined && !isValidIndexedDBKeyPath(store.keyPath)
+                        ? `IndexedDB object store "${storeName}" has an invalid key path`
+                        : store.keyPathArray !== undefined && !isValidIndexedDBKeyPathArray(store.keyPathArray)
+                            ? `IndexedDB object store "${storeName}" has an invalid array key path`
+                            : store.autoIncrement && (store.keyPath === '' || Array.isArray(store.keyPathArray))
+                                ? `IndexedDB object store "${storeName}" cannot combine autoIncrement with an empty or array key path`
+                                : null;
+                storeNames.add(storeName);
+                const recordKeys = new Set();
+                const hasInlineKey = store.keyPath !== undefined || store.keyPathArray !== undefined;
+                for (const value of Array.isArray(store.records) ? store.records : []) {
+                    const record = value;
+                    const hasExternalKey = (record.key !== undefined && record.key !== null)
+                        || (record.keyEncoded !== undefined && record.keyEncoded !== null);
+                    const key = record.key ?? record.keyEncoded;
+                    const serializedKey = hasExternalKey ? JSON.stringify(key) ?? String(key) : '';
+                    indexedDBProblem ??= record.key !== undefined && record.key !== null && !isValidIndexedDBKey(record.key)
+                        ? `IndexedDB object store "${storeName}" has an invalid external record key`
+                        : hasInlineKey && hasExternalKey
+                            ? `IndexedDB object store "${storeName}" has an inline key path but record also supplies an external key`
+                            : !hasInlineKey && !store.autoIncrement && !hasExternalKey
+                                ? `IndexedDB object store "${storeName}" requires an external key for every record`
+                                : hasExternalKey && recordKeys.has(serializedKey)
+                                    ? `IndexedDB object store "${storeName}" has duplicate record key ${serializedKey}`
+                                    : null;
+                    if (hasExternalKey)
+                        recordKeys.add(serializedKey);
+                }
+                const indexNames = new Set();
+                for (const index of Array.isArray(store.indexes) ? store.indexes : []) {
+                    const indexName = String(index.name);
+                    indexedDBProblem ??= indexNames.has(indexName)
+                        ? `IndexedDB index name "${indexName}" is duplicated in object store "${storeName}"`
+                        : index.keyPath !== undefined && !isValidIndexedDBKeyPath(index.keyPath)
+                            ? `IndexedDB index "${indexName}" has an invalid key path`
+                            : index.keyPathArray !== undefined && !isValidIndexedDBKeyPathArray(index.keyPathArray)
+                                ? `IndexedDB index "${indexName}" has an invalid array key path`
+                                : index.multiEntry && Array.isArray(index.keyPathArray)
+                                    ? `IndexedDB index "${indexName}" cannot combine multiEntry with an array key path`
+                                    : null;
+                    indexNames.add(indexName);
+                }
+            }
+            if (indexedDBProblem)
+                throw new Error(`Invalid storage state: ${indexedDBProblem}. Nothing was changed — the state is validated before the apply, because setStorageState() clears the attached context's HTTP cache and cookie jar before it validates, and the cache cannot be restored.`);
+        }
+    }
+}
+/**
+ * Replaces every open page of `browserContext` with a blank fresh tab and
+ * returns the fresh tabs paired with the URL each replaced page showed.
+ * Replacement, not an in-page sessionStorage clear plus reload: the old
+ * document's scripts keep running between an evaluated clear and the
+ * navigation that would follow it, and a timer persisting the previous
+ * identity can write it back into that window — sessionStorage survives the
+ * reload, and the audit reads the old user again. A fresh tab starts with
+ * empty sessionStorage for every origin (only window.open clones the
+ * opener's copy, verified against Playwright 1.61.1 Chromium). The
+ * replacement tab is created before the old page closes — closing a
+ * browser's last tab can take the whole (attached, user-owned) browser down
+ * with it.
+ */
+async function replaceOpenPagesWithBlankTabs(browserContext) {
+    const seen = new Set();
+    const arrivals = [];
+    const onPage = (page) => arrivals.push(page);
+    const replaced = [];
+    const replacePage = async (page) => {
+        const url = page.url();
+        let fresh;
+        try {
+            fresh = await browserContext.newPage();
+        }
+        catch {
+            // Without a replacement tab (Electron targets cannot create pages),
+            // closing is the only way to keep the previous identity's DOM and
+            // sessionStorage out of the audit.
+            await page.close();
+            return;
+        }
+        // The replacement never needs replacing itself — it must not be swept up
+        // by the loop below when it surfaces through pages() or the listener.
+        seen.add(fresh);
+        try {
+            await page.close();
+        }
+        catch (error) {
+            await fresh.close().catch(() => { });
+            throw error;
+        }
+        replaced.push({ page: fresh, url });
+    };
+    // A still-old document can open a page while the ones above are being
+    // replaced — a popup from a timer, say — and a same-origin popup clones
+    // its opener's previous-identity sessionStorage at creation. A single
+    // pages() snapshot would hand such a page to Context unreset, so the sweep
+    // repeats until no unseen page remains; the temporary 'page' listener
+    // catches pages whose creation the next pages() call cannot see yet. The
+    // Set dedupes a page that arrives through both — two concurrent
+    // replacements of one page would race each other's close.
+    browserContext.on('page', onPage);
+    try {
+        while (true) {
+            const pending = [...new Set([...browserContext.pages(), ...arrivals.splice(0)])].filter(page => !seen.has(page));
+            if (!pending.length)
+                break;
+            for (const page of pending)
+                seen.add(page);
+            await Promise.all(pending.map(replacePage));
+        }
+    }
+    finally {
+        browserContext.off('page', onPage);
+    }
+    return replaced;
+}
+/**
+ * Navigates each replacement tab to the URL its replaced page showed, bringing
+ * what a scan sees onto the state the context now holds. A tab that cannot
+ * load its page — the origin may be blocked by the just-installed policy, or
+ * the load simply failed — is blanked instead (the fresh tab carries no old
+ * identity, so a blank one is safe to hand to Context), and closed only when
+ * even blanking fails.
+ */
+async function navigateReplacementPages(replaced) {
+    await Promise.all(replaced.map(async ({ page, url }) => {
+        if (!url || url === 'about:blank')
+            return;
+        try {
+            await page.goto(url);
+        }
+        catch {
+            try {
+                await page.goto('about:blank');
+            }
+            catch {
+                await page.close().catch(() => { });
+            }
+        }
+    }));
+}
+/**
+ * Lands the configured storage state in a context the browser already had.
+ * `setStorageState()` clears the context's cookies, local storage and IndexedDB
+ * and installs the recorded state — the documented semantics of the option the
+ * caller asked for, applied to a context `newContext()` never sees: the CDP
+ * modes without --isolated reuse the browser's existing context, and
+ * launchPersistentContext() silently ignores a storageState option (verified
+ * against Playwright 1.61.1).
+ */
+export async function applyStorageStateToReusedContext(config, browserContext) {
+    const storageState = config.browser.contextOptions?.storageState;
+    if (!storageState)
+        return;
+    const parsedState = await (async () => {
+        try {
+            return typeof storageState === 'string'
+                ? JSON.parse(await fs.promises.readFile(storageState, 'utf-8'))
+                : storageState;
+        }
+        catch (error) {
+            // Letting setStorageState() discover the bad file would fail inside
+            // the apply block, whose catch answers every failure with a rollback —
+            // and the rollback's own setStorageState() clears the attached
+            // context's HTTP cache. A config error that changed nothing must not
+            // cost the running application its cache.
+            throw new Error(`The storage state file could not be read or parsed: ${error instanceof Error ? error.message : String(error)}. Nothing was changed.`);
+        }
+    })();
+    // Playwright validates cookies only while installing them — after the
+    // attached context's HTTP cache and cookie jar are already cleared — so a
+    // semantically invalid cookie (bad expires, missing domain/path) would
+    // fail the apply with the cache unrestorably gone. Checked up front, with
+    // the same rules addCookies enforces (verified against 1.61.1).
+    assertValidStorageState(parsedState);
+    // setStorageState needs a temporary page whenever the state carries origins
+    // or the context has visited any — and by the time that page creation fails
+    // on a target without Target.createTarget, the HTTP cache is already cleared
+    // and cannot be put back. Probe the page creation first, so such targets are
+    // rejected before anything is mutated. When neither signal indicates a page
+    // will be needed (cookie-only state, no pages open), the probe is skipped so
+    // that case keeps working on those targets.
+    const stateHasOrigins = (parsedState.origins?.length ?? 0) > 0;
+    const hasLoadedPages = browserContext.pages().some(page => page.url() && page.url() !== 'about:blank');
+    if (stateHasOrigins || hasLoadedPages) {
+        try {
+            const probe = await browserContext.newPage();
+            await probe.close();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('Target.createTarget'))
+                throw new Error(`The attached browser cannot open the temporary page Playwright needs to apply the storage state's origin data (Electron targets do not support Target.createTarget). Nothing was changed. Drop the storage state and sign in inside the app instead. Original error: ${message}`);
+            throw error;
+        }
+    }
+    // setStorageState replaces the cookie jar and then rewrites origin storage
+    // one origin at a time, so a failure partway would otherwise leave the
+    // attached browser holding a mixture of old and recorded state while the
+    // operation reports failure. Both layers are snapshotted first: the cookie
+    // jar through pure protocol calls that work everywhere (kept as the
+    // fallback for a restore whose own origin phase fails), and origin storage
+    // through storageState() below.
+    const originalCookies = await browserContext.cookies();
+    // The snapshot doubles as a probe for origins this connection has already
+    // visited while its pages have since closed or gone blank: for those,
+    // storageState() opens the same temporary page the forward apply will need
+    // — the newPage probe above cannot see them — but unlike setStorageState()
+    // it mutates nothing, so a target that cannot create pages (Electron) is
+    // rejected here with everything intact, not after the forward apply has
+    // cleared the HTTP cache. Any other snapshot failure also aborts: without
+    // the full snapshot, a partial forward apply could only be rolled back to
+    // cookies, leaving the attached browser's origin storage part old, part
+    // recorded.
+    const originalState = await browserContext.storageState({ indexedDB: true }).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('Target.createTarget'))
+            throw new Error(`The attached browser cannot open the temporary page Playwright needs to reset origin storage for origins this connection has already visited (Electron targets do not support Target.createTarget). Nothing was changed. Drop the storage state and sign in inside the app instead. Original error: ${message}`);
+        throw new Error(`Snapshotting the context's current storage for rollback failed, so the storage state was not applied — a partial apply could not have been undone. Nothing was changed. Retry, or use --isolated for a fresh context. Original error: ${message}`);
+    });
+    // Pages that were already open still render the previous identity — and
+    // their scripts keep running: a page that periodically persists
+    // authentication into cookies or localStorage would overwrite the state
+    // being installed if it were still alive during setStorageState(), and
+    // replacing its tab afterwards cannot undo writes already made into
+    // context-wide storage. Every open page is therefore replaced with a blank
+    // fresh tab FIRST — the old document closes before the state lands, and
+    // only blank replacements (which run no scripts) survive the apply — and
+    // the replacements are navigated to the pages they replaced only once the
+    // recorded state is in place.
+    const replaced = await replaceOpenPagesWithBlankTabs(browserContext);
+    const policyRequired = !!(config.network?.allowedOrigins?.length || config.network?.blockedOrigins?.length);
+    let replacementNavigationSafe = !policyRequired;
+    try {
+        // The state validated above is the state applied: handing the path back
+        // to Playwright would re-read the file here, and a file replaced since
+        // that read would skip the cookie/origin validation and the page-creation
+        // probe only to fail after the cache clear those exist to prevent.
+        await browserContext.setStorageState(parsedState);
+        // The replacement navigations run inside the factory, before Context
+        // ensures the configured origin allowlist/blocklist — and the recorded
+        // credentials are already in place by now. The policy is installed here
+        // (permanently — page scripts can queue requests that fire after the
+        // navigation settles, so removing the handlers before Context re-ensures
+        // the same policy would open a window to a blocked origin;
+        // ensureNetworkPolicyRoutes installs once per context, so Context's later
+        // call is a no-op). Installed after setStorageState() so an abort-all
+        // route cannot interfere with the temporary page Playwright drives to
+        // restore origin storage.
+        await ensureNetworkPolicyRoutes(config, browserContext);
+        replacementNavigationSafe = true;
+        await navigateReplacementPages(replaced);
+    }
+    catch (error) {
+        // Prefer the full-state rollback; fall back to cookies-only when its
+        // reapplication is itself impossible on this target.
+        const restoredFully = await browserContext.setStorageState(originalState).then(() => true, () => false);
+        const restoredCookies = restoredFully || await browserContext.clearCookies()
+            .then(() => originalCookies.length ? browserContext.addCookies(originalCookies) : undefined)
+            .then(() => true, () => false);
+        // The old pages were closed before the apply and cannot be handed back.
+        // Navigate their replacements only when no policy was required or its
+        // installation succeeded; otherwise restored credentials stay offline.
+        if (replacementNavigationSafe)
+            await navigateReplacementPages(replaced);
+        else
+            await Promise.all(replaced.map(({ page }) => page.close().catch(() => { })));
+        // Restoring origin storage (localStorage/IndexedDB) makes Playwright open a
+        // temporary page; a CDP target that cannot create one — Electron has no
+        // Target.createTarget — fails here. Cookie-only states need no page and
+        // still work on such targets, so name that remedy instead of surfacing the
+        // raw protocol error.
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('Target.createTarget')) {
+            const rollbackNote = restoredFully
+                ? 'The context\'s original storage state was restored.'
+                : restoredCookies
+                    ? 'The context\'s original cookies were restored.'
+                    : 'Restoring the context\'s original cookies also failed; its cookie jar may now hold the recorded state.';
+            throw new Error(`The attached browser cannot open the temporary page Playwright needs to reset origin storage (Electron targets do not support Target.createTarget). Drop the storage state and sign in inside the app instead — a cookies-only state helps only while the attached target has no pages open and the connection has visited no origin, because clearing storage for an already-visited origin needs the same temporary page. ${rollbackNote} Original error: ${message}`);
+        }
+        if (!restoredFully && restoredCookies)
+            throw new Error(`${message} The context's original cookies were restored, but origin storage may retain partially applied state.`);
+        throw error;
+    }
+}
+function createContextFactory(config) {
     if (config.browser.remoteEndpoint)
         return new RemoteContextFactory(config);
     if (config.browser.cdpLaunch)
@@ -39,76 +443,272 @@ 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 {
+    appliesStorageState = true;
     constructor(config) {
         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);
     }
 }
 class CdpContextFactory extends BaseContextFactory {
+    // The isolated path creates a fresh context with the state; the attach path
+    // applies it to the browser's existing context via setStorageState().
+    appliesStorageState = true;
+    // One attached browser — and its default context — serves every session
+    // this factory creates. Re-running the global setStorageState() for a
+    // second session would wipe the first session's live cookies and origin
+    // storage mid-audit and reload its pages, so the state is applied once per
+    // context object: later sessions join the live shared state. Keyed weakly —
+    // a reconnect yields a fresh context object, so the slate resets with the
+    // connection — and a failed apply is forgotten so the next session retries.
+    _storageStateApplied = new WeakMap();
+    // Serializes the no-context fallback the same way: two sessions arriving at
+    // a contextless target must share one created context, not race two.
+    _fallbackContext = new WeakMap();
     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
+    // close() nor the cleanup after another session's failed setup. The
+    // handout count is kept per browser object, not per factory: an external
+    // disconnect makes _obtainBrowser hand out a fresh browser while stale
+    // sessions still hold references to the old one, and a shared counter
+    // would let a stale release keep the new connection open forever (its last
+    // real user would only ever bring the count down to the stale remainder).
+    // The reference is claimed before context creation, so a sibling still
+    // inside _doCreateContext() counts and a concurrent failure cannot close
+    // the connection out from under it.
+    _sessionCounts = new WeakMap();
+    _releaseBrowser(browser) {
+        const remaining = Math.max(0, (this._sessionCounts.get(browser) ?? 1) - 1);
+        this._sessionCounts.set(browser, remaining);
+        return remaining === 0;
+    }
     async createContext(clientInfo) {
         testDebug('create browser context (cdp)');
-        const browser = await this._obtainBrowser(clientInfo);
-        const browserContext = await this._doCreateContext(browser);
+        // `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);
+        }
+        catch (error) {
+            // 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) && !this._hasPendingAcquisition(obtainedPromise)) {
+                if (this._browserPromise === obtainedPromise)
+                    this._browserPromise = undefined;
+                await browser.close().catch(logUnhandledError);
+            }
+            throw error;
+        }
+        let released = false;
         return {
             browserContext,
             close: async () => {
-                testDebug('disconnect browser (cdp)');
-                await browser.close().catch(logUnhandledError);
+                if (released)
+                    return;
+                released = true;
+                // An isolated session's context belongs to it alone — close it now,
+                // or abandoned contexts (with their pages, routes and listeners)
+                // pile up on a long-lived shared connection until the last session
+                // exits. The non-isolated context is the browser's own and shared;
+                // it stays.
+                if (this.config.browser.isolated)
+                    await browserContext.close().catch(logUnhandledError);
+                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);
+                }
             }
         };
     }
@@ -120,10 +720,46 @@ class CdpContextFactory extends BaseContextFactory {
         });
     }
     async _doCreateContext(browser) {
-        return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
+        if (this.config.browser.isolated)
+            return await browser.newContext(this.config.browser.contextOptions);
+        const existing = browser.contexts()[0];
+        // An attached browser can expose no context at all; a fresh one created
+        // with the configured options (storage state included) beats handing an
+        // undefined context to the caller. The created context immediately seeds
+        // the applied-state memo — a later session will find it as the browser's
+        // existing context, and must join it rather than reset it — and the
+        // creation itself is memoized so concurrent arrivals share one context.
+        if (!existing) {
+            let creating = this._fallbackContext.get(browser);
+            if (!creating) {
+                creating = browser.newContext(this.config.browser.contextOptions).then(created => {
+                    this._storageStateApplied.set(created, Promise.resolve());
+                    // Evict on close, or a context closed externally (while the
+                    // connection lives on) would keep being handed out of this memo to
+                    // every later session — contexts() no longer lists it, so only the
+                    // memo would remember it, forever.
+                    created.on('close', () => this._fallbackContext.delete(browser));
+                    return created;
+                });
+                this._fallbackContext.set(browser, creating);
+                creating.catch(() => this._fallbackContext.delete(browser));
+            }
+            return await creating;
+        }
+        // The shared promise also serializes two sessions arriving at once: both
+        // await the same application instead of racing two global resets.
+        let applied = this._storageStateApplied.get(existing);
+        if (!applied) {
+            applied = applyStorageStateToReusedContext(this.config, existing);
+            this._storageStateApplied.set(existing, applied);
+            applied.catch(() => this._storageStateApplied.delete(existing));
+        }
+        await applied;
+        return existing;
     }
 }
 class RemoteContextFactory extends BaseContextFactory {
+    appliesStorageState = true;
     constructor(config) {
         super('remote', config);
     }
@@ -135,40 +771,191 @@ class RemoteContextFactory extends BaseContextFactory {
         return playwright[this.config.browser.browserName].connect(String(url));
     }
     async _doCreateContext(browser) {
-        return browser.newContext();
+        return browser.newContext(this.config.browser.contextOptions);
     }
 }
 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);
-        const browserContext = this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
+        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) {
+                browserContext = await browser.newContext(this.config.browser.contextOptions);
+            }
+            else {
+                const existing = browser.contexts()[0];
+                if (existing) {
+                    await applyStorageStateToReusedContext(this.config, existing);
+                    browserContext = existing;
+                }
+                else {
+                    // See CdpContextFactory: a launched app can expose no context yet;
+                    // a fresh one with the configured options beats an undefined one.
+                    browserContext = await browser.newContext(this.config.browser.contextOptions);
+                }
+            }
+        }
+        catch (error) {
+            // 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;
+        }
         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 = {
@@ -191,67 +978,301 @@ class CdpLaunchContextFactory {
         }
     }
 }
-class PersistentContextFactory {
+// Distinguishes a storage-state failure from a launch failure, so the launch
+// retry loop never retries on one (a bad state file fails the same way 5 times).
+class StorageStateError extends Error {
+}
+// Shared with the --connect-tool startup validation in program.ts, so the
+// lazy rejection here and the eager one there never drift apart.
+export const persistentProfileConflictRemedy = 'Drop --user-data-dir (a managed, disposable profile is used for storage-state sessions), or drop the storage state and sign in in that profile instead.';
+export class PersistentContextFactory {
     config;
+    // launchPersistentContext() silently ignores a storageState option, so the
+    // state is applied to the launched context with setStorageState() instead.
+    appliesStorageState = true;
     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)');
-        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
-        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
-        this._userDataDirs.add(userDataDir);
-        testDebug('lock user data dir', userDataDir);
+        // launchPersistentContext() accepts a storageState option without applying
+        // it (verified against 1.61.1) — the profile is normally the state — so it
+        // is stripped here and applied explicitly after launch.
+        const { storageState, ...contextOptions } = this.config.browser.contextOptions ?? {};
+        // setStorageState() resets cookies globally but origin storage only for
+        // origins in the state or known to the fresh context object, so stale
+        // localStorage/IndexedDB in a previously used profile would survive and
+        // could sign the audit in as the wrong identity. A storage-state session
+        // therefore runs in its own fresh disposable profile — unique per context,
+        // because one server can hold several live sessions and a shared
+        // deterministic directory would let one session's setup destroy another's
+        // running profile — removed again when the context closes. A user-supplied
+        // profile cannot be treated this way — it is data we do not own — and
+        // keeping it contradicts "start from the recorded state", so that
+        // combination errors.
+        assertStorageStateDoesNotResetUserProfile(this.config, persistentProfileConflictRemedy);
+        // Trace setup runs before the disposable profile exists: it can fail (an
+        // 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);
+        // 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];
-        for (let i = 0; i < 5; i++) {
+        // 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,
+                    });
+                    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)
+                        throw error;
+                    if (error.message.includes('Executable doesn\'t exist'))
+                        throw browserNotInstalledError(error);
+                    if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
+                        // User data directory is already in use, try again.
+                        await new Promise(resolve => setTimeout(resolve, 1000));
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            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 (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, disposableProfile) {
+        if (storageState) {
             try {
-                const browserContext = await browserType.launchPersistentContext(userDataDir, {
-                    tracesDir,
-                    ...this.config.browser.launchOptions,
-                    ...this.config.browser.contextOptions,
-                    handleSIGINT: false,
-                    handleSIGTERM: false,
-                });
-                const close = () => this._closeBrowserContext(browserContext, userDataDir);
-                return { browserContext, close };
+                // Startup pages can keep persisting their anonymous identity while the
+                // state lands. Park them on blank replacements before the apply, then
+                // navigate the replacements only after the recorded state is installed.
+                const replaced = await replaceOpenPagesWithBlankTabs(browserContext);
+                await browserContext.setStorageState(storageState);
+                await ensureNetworkPolicyRoutes(this.config, browserContext);
+                await navigateReplacementPages(replaced);
             }
             catch (error) {
-                if (error.message.includes('Executable doesn\'t exist'))
-                    throw browserNotInstalledError(error);
-                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
-                    // User data directory is already in use, try again.
-                    await new Promise(resolve => setTimeout(resolve, 1000));
-                    continue;
-                }
-                throw 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, disposableProfile);
+                throw new StorageStateError(error instanceof Error ? error.message : String(error));
             }
         }
-        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+        const close = () => this._closeBrowserContext(browserContext, userDataDir, disposableProfile);
+        return { browserContext, close };
     }
-    async _closeBrowserContext(browserContext, userDataDir) {
+    async _closeBrowserContext(browserContext, userDataDir, disposeUserDataDir = false) {
         testDebug('close browser context (persistent)');
         testDebug('release user data dir', userDataDir);
         await browserContext.close().catch(() => { });
+        // 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)');
     }
-    async _createUserDataDir(rootPath) {
+    // 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}`);
+        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
@@ -266,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
@@ -289,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';