@narumitw/pi-chrome-devtools 0.53.4 → 0.54.1

package/dist/chunks/{chunk-LSJSDY2M.ts → chunk-WTMZID3G.ts}

@@ -23,6 +23,9 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 var NEW_SETTINGS_FILE_NAME = "pi-chrome-devtools.json";
 var LEGACY_SETTINGS_FILE_NAME = "pi-chrome-devtools-settings.json";
+function isChromeDevtoolsToolMode(value) {
+  return value === "codemode" || value === "lazy" || value === "direct";
+}
 var DEFAULT_BROWSER_HOST = "127.0.0.1";
 var DEFAULT_BROWSER_PORT = 9222;
 var DEFAULT_BROWSER_ENDPOINT = `http://${DEFAULT_BROWSER_HOST}:${DEFAULT_BROWSER_PORT}`;
@@ -77,7 +80,7 @@ async function loadSettings(options = {}) {
   const userBrowser = user.normalized?.browser ?? {};
   const effectiveBrowser = resolveEffectiveBrowser(userBrowser, project.normalized?.browser);
   const settings = resolveSettings(user.normalized, project.normalized, effectiveBrowser);
-  const recognized = settings.tools !== void 0 || user.normalized?.browser !== void 0 || project.normalized?.browser !== void 0 || user.normalized?.webmcp !== void 0;
+  const recognized = user.normalized?.toolMode !== void 0 || settings.tools !== void 0 || user.normalized?.browser !== void 0 || project.normalized?.browser !== void 0 || user.normalized?.webmcp !== void 0;
   const invalidReasons = [user, project].filter((result) => result.kind === "invalid").map((result) => result.reason).filter((reason) => Boolean(reason));
   const userFile = user.kind === "invalid" ? {
     kind: "invalid",
@@ -99,6 +102,7 @@ async function loadSettings(options = {}) {
 }
 function resolveSettings(user, _project, browser) {
   return {
+    toolMode: user?.toolMode ?? "codemode",
     ...user?.tools ? { tools: user.tools, updatedAt: user.updatedAt } : {},
     browser,
     webmcp: { enabled: user?.webmcp?.enabled ?? false }
@@ -190,6 +194,11 @@ function projectOwnedSettingsWarnings(document, scope, filePath) {
 }
 async function normalizeSettingsDocument(document, scope, filePath, cwd) {
   const normalized = {};
+  if (scope === "user" && document.toolMode !== void 0) {
+    if (!isChromeDevtoolsToolMode(document.toolMode))
+      throw new Error("expected toolMode to be codemode, lazy, or direct");
+    normalized.toolMode = document.toolMode;
+  }
   if (scope === "user" && (document.tools !== void 0 || document.updatedAt !== void 0)) {
     const toolSettings = normalizeChromeDevtoolsSettings(document);
     if (!toolSettings) {
@@ -332,16 +341,31 @@ function orderedUniqueChromeDevtoolsTools(tools) {
 function orderedUnique(values) {
   return [...new Set(values)];
 }
-function saveSettings(settings, operations = {}) {
+var ToolCatalogApplicationError = class extends Error {
+  constructor(error, rollbackError) {
+    super(
+      rollbackError ? `${formatError(error)}; saved catalog rollback failed: ${formatError(rollbackError)}` : `${formatError(error)}; previous catalog restored`,
+      { cause: error }
+    );
+    this.rollbackError = rollbackError;
+  }
+  rollbackError;
+};
+function saveSettings(settings, operations = {}, applyAfterSave) {
   return queueSettingsMutation(
     (current) => ({
       ...current,
       tools: [...settings.tools],
       updatedAt: settings.updatedAt
     }),
-    operations
+    operations,
+    applyAfterSave
   );
 }
+function saveToolMode(mode, operations = {}) {
+  if (!isChromeDevtoolsToolMode(mode)) return Promise.reject(new Error("Invalid tool mode"));
+  return queueSettingsMutation((current) => ({ ...current, toolMode: mode }), operations);
+}
 function saveWebMcpSettings(enabled, operations = {}) {
   return queueSettingsMutation(
     (current) => ({
@@ -367,12 +391,12 @@ function saveBrowserSettings(patch, operations = {}) {
     return { ...current, browser };
   }, operations);
 }
-function queueSettingsMutation(mutate, operations) {
-  const operation = settingsSaveQueue.then(() => saveSettingsMutationNow(mutate, operations));
+function queueSettingsMutation(mutate, operations, applyToolCatalog) {
+  const operation = settingsSaveQueue.then(() => saveSettingsMutationNow(mutate, operations, applyToolCatalog));
   settingsSaveQueue = operation.catch(() => void 0);
   return operation;
 }
-async function saveSettingsMutationNow(mutate, operations) {
+async function saveSettingsMutationNow(mutate, operations, applyToolCatalog) {
   const filePath = settingsFilePath();
   let current = await readSettingsDocument(filePath, "user");
   const replaceCanonical = current.kind !== "missing";
@@ -394,6 +418,27 @@ async function saveSettingsMutationNow(mutate, operations) {
     await rm(tempFile, { force: true }).catch(() => void 0);
     throw error;
   }
+  if (!applyToolCatalog) return;
+  try {
+    applyToolCatalog();
+  } catch (error) {
+    let rollbackError;
+    try {
+      await saveSettingsMutationNow((latest) => {
+        const restored = { ...latest };
+        for (const field of ["tools", "updatedAt"]) {
+          if (JSON.stringify(latest[field]) !== JSON.stringify(nextDocument[field]))
+            throw new Error("Tool catalog changed after save; refusing to overwrite newer settings");
+          delete restored[field];
+          if (current.document?.[field] !== void 0) restored[field] = current.document[field];
+        }
+        return restored;
+      }, operations);
+    } catch (caught) {
+      rollbackError = caught;
+    }
+    throw new ToolCatalogApplicationError(error, rollbackError);
+  }
 }
 function settingsFilePath() {
   return join(getAgentDir(), NEW_SETTINGS_FILE_NAME);
@@ -439,7 +484,6 @@ var DEFAULT_HTTP_TIMEOUT_MS = 1e3;
 var DEFAULT_ENDPOINT_WAIT_MS = 5e3;
 var DEFAULT_ENDPOINT_RETRY_MS = 250;
 var MANAGED_BROWSER_PROFILE_PREFIX = "pi-chrome-devtools-profile-";
-var DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
 var BROWSER_SHUTDOWN_WAIT_MS = 1500;
 var state = {
   host: DEFAULT_HOST,
@@ -544,15 +588,265 @@ function applyRuntimeBrowserSettings(browser, paths, projectTrusted) {
 
 // src/browser-manager.ts
 import { execFile, spawn } from "node:child_process";
-import { constants as constants2 } from "node:fs";
-import { access as access2, mkdtemp, readFile as readFile2, rm as rm2 } from "node:fs/promises";
+import { access as access2, mkdtemp, rm as rm2 } from "node:fs/promises";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
+import { join as join3 } from "node:path";
+
+// src/browser-candidates.ts
+import { constants as constants2 } from "node:fs";
 import { delimiter, isAbsolute as isAbsolute2, join as join2, resolve as resolve2 } from "node:path";
+function normalizePathForComparison(value) {
+  return process.platform === "win32" ? value.toLowerCase() : value;
+}
+function browserCandidateDefinitions(browser) {
+  const explicitCandidate = explicitBrowserCandidateDefinition(browser);
+  if (explicitCandidate.length > 0) return explicitCandidate;
+  return uniqueBrowserCandidates(platformBrowserCandidateDefinitions());
+}
+function explicitBrowserCandidateDefinition(browser) {
+  if (!browser.executablePath) return [];
+  return [
+    {
+      label: browser.executablePathSource === "environment" ? "PI_CHROME_DEVTOOLS_BROWSER" : "browser.executablePath",
+      executable: browser.executablePath,
+      source: "env"
+    }
+  ];
+}
+function platformBrowserCandidateDefinitions() {
+  if (process.platform === "darwin") {
+    return [
+      {
+        label: "Google Chrome",
+        executable: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        source: "wellKnownPath"
+      },
+      {
+        label: "Chromium",
+        executable: "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        source: "wellKnownPath"
+      },
+      {
+        label: "Brave Browser",
+        executable: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+        source: "wellKnownPath"
+      },
+      {
+        label: "Microsoft Edge",
+        executable: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+        source: "wellKnownPath"
+      }
+    ];
+  }
+  if (process.platform === "win32") {
+    return windowsBrowserCandidateDefinitions();
+  }
+  return [
+    { label: "Google Chrome", executable: "google-chrome", source: "path" },
+    { label: "Google Chrome Stable", executable: "google-chrome-stable", source: "path" },
+    { label: "Chromium", executable: "chromium", source: "path" },
+    { label: "Chromium Browser", executable: "chromium-browser", source: "path" },
+    { label: "Brave Browser", executable: "brave-browser", source: "path" },
+    { label: "Brave", executable: "brave", source: "path" },
+    { label: "Microsoft Edge", executable: "microsoft-edge", source: "path" },
+    { label: "Microsoft Edge Stable", executable: "microsoft-edge-stable", source: "path" }
+  ];
+}
+function windowsBrowserCandidateDefinitions() {
+  const programFiles = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(
+    (value) => typeof value === "string" && value.length > 0
+  );
+  const wellKnownPaths = programFiles.flatMap((root) => [
+    join2(root, "Google", "Chrome", "Application", "chrome.exe"),
+    join2(root, "Chromium", "Application", "chrome.exe"),
+    join2(root, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+    join2(root, "Microsoft", "Edge", "Application", "msedge.exe")
+  ]);
+  return [
+    ...wellKnownPaths.map((executable) => ({
+      label: browserLabelFromExecutable(executable),
+      executable,
+      source: "wellKnownPath"
+    })),
+    { label: "Google Chrome", executable: "chrome.exe", source: "path" },
+    { label: "Chromium", executable: "chromium.exe", source: "path" },
+    { label: "Brave Browser", executable: "brave.exe", source: "path" },
+    { label: "Microsoft Edge", executable: "msedge.exe", source: "path" }
+  ];
+}
+function browserLabelFromExecutable(executable) {
+  const normalizedExecutable = normalizePathForComparison(executable);
+  if (normalizedExecutable.includes("brave")) return "Brave Browser";
+  if (normalizedExecutable.includes("edge") || normalizedExecutable.includes("msedge")) {
+    return "Microsoft Edge";
+  }
+  if (normalizedExecutable.includes("chromium")) return "Chromium";
+  return "Google Chrome";
+}
+function uniqueBrowserCandidates(candidates) {
+  const seen = /* @__PURE__ */ new Set();
+  return candidates.filter((candidate) => {
+    const key = normalizePathForComparison(candidate.executable);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+async function resolveBrowserCandidates(definitions, access3, throwIfCancelled) {
+  const candidates = [];
+  for (const definition of definitions) {
+    const resolvedExecutable = await resolveBrowserExecutable(definition.executable, access3, throwIfCancelled);
+    throwIfCancelled();
+    if (!resolvedExecutable) continue;
+    candidates.push({ ...definition, resolvedExecutable });
+  }
+  return uniqueBrowserCandidatesByResolvedPath(candidates);
+}
+function uniqueBrowserCandidatesByResolvedPath(candidates) {
+  const seen = /* @__PURE__ */ new Set();
+  return candidates.filter((candidate) => {
+    const key = normalizePathForComparison(resolve2(candidate.resolvedExecutable));
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+async function resolveBrowserExecutable(executable, access3, throwIfCancelled) {
+  if (hasPathSeparator(executable) || isAbsolute2(executable)) {
+    const resolvedExecutable = isAbsolute2(executable) ? executable : resolve2(executable);
+    return await canAccessExecutable(resolvedExecutable, access3, throwIfCancelled) ? resolvedExecutable : void 0;
+  }
+  for (const directory of executableSearchPath()) {
+    for (const executableName of executableSearchNames(executable)) {
+      const candidate = join2(directory, executableName);
+      if (await canAccessExecutable(candidate, access3, throwIfCancelled)) return candidate;
+    }
+  }
+  return void 0;
+}
+function hasPathSeparator(path) {
+  return path.includes("/") || path.includes("\\");
+}
+function executableSearchPath() {
+  return (process.env.PATH ?? "").split(delimiter).filter((part) => part.length > 0);
+}
+function executableSearchNames(executable) {
+  if (process.platform !== "win32" || /\.[a-z0-9]+$/i.test(executable)) return [executable];
+  return [executable, `${executable}.exe`, `${executable}.cmd`, `${executable}.bat`];
+}
+async function canAccessExecutable(path, access3, throwIfCancelled) {
+  let accessible = false;
+  try {
+    await access3(path, process.platform === "win32" ? constants2.F_OK : constants2.X_OK);
+    accessible = true;
+  } catch {
+  }
+  throwIfCancelled();
+  return accessible;
+}
+
+// src/browser-startup.ts
+var MAX_STARTUP_STDERR_BYTES = 64 * 1024;
+function handleErrorsUntilClose(emitter) {
+  const ignoreError = () => void 0;
+  emitter.on("error", ignoreError);
+  emitter.once("close", () => emitter.off("error", ignoreError));
+}
+function browserWebSocketIdentity(value, port) {
+  if (typeof value !== "string") return void 0;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "ws:" || !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || Number(url.port || "80") !== port || url.username || url.password || url.search || url.hash || !/^\/devtools\/browser\/[^/]+$/.test(url.pathname)) {
+      return void 0;
+    }
+    return url.pathname;
+  } catch {
+    return void 0;
+  }
+}
+function waitForBrowserStartup(child, port, waitMs, signal) {
+  handleErrorsUntilClose(child);
+  const stderr = child.stderr;
+  if (stderr && !stderr.closed) handleErrorsUntilClose(stderr);
+  signal.throwIfAborted();
+  if (!stderr) return Promise.reject(new Error("Auto-launched browser has no startup stderr stream."));
+  return new Promise((resolve3, reject) => {
+    let spawned = false;
+    let identity;
+    let receivedBytes = 0;
+    let pendingLine = "";
+    let settled = false;
+    let timeout;
+    const settle = (error) => {
+      if (settled) return;
+      if (!error && (!spawned || !identity)) return;
+      settled = true;
+      clearTimeout(timeout);
+      child.off("spawn", onSpawn);
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.off("close", onExit);
+      stderr.off("data", onData);
+      stderr.off("end", onEnd);
+      stderr.off("error", onError);
+      signal.removeEventListener("abort", onAbort);
+      stderr.resume();
+      if (error) reject(error);
+      else resolve3(identity);
+    };
+    const onError = (error) => settle(error);
+    const onAbort = () => settle(new Error("Chrome DevTools browser startup cancelled.", { cause: signal.reason }));
+    const onExit = () => settle(new Error("Auto-launched browser exited before DevTools became available."));
+    const onSpawn = () => {
+      spawned = true;
+      timeout = setTimeout(
+        () => settle(new Error("Timed out waiting for auto-launched browser DevTools startup announcement.")),
+        waitMs
+      );
+      settle();
+    };
+    const inspectLine = (line) => {
+      const match = /^DevTools listening on (\S+)$/.exec(line.trim());
+      if (!match) return;
+      identity = browserWebSocketIdentity(match[1], port);
+      if (!identity) settle(new Error("Auto-launched browser announced an unexpected DevTools endpoint."));
+      else settle();
+    };
+    const onData = (data) => {
+      receivedBytes += Buffer.byteLength(data);
+      if (receivedBytes > MAX_STARTUP_STDERR_BYTES) {
+        settle(new Error("Auto-launched browser startup stderr exceeded 64 KB before readiness."));
+        return;
+      }
+      pendingLine += data.toString();
+      const lines = pendingLine.split("\n");
+      pendingLine = lines.pop() ?? "";
+      for (const line of lines) {
+        inspectLine(line);
+        if (settled) break;
+      }
+    };
+    const onEnd = () => {
+      inspectLine(pendingLine);
+      if (!identity) settle(new Error("Auto-launched browser closed stderr before its DevTools startup announcement."));
+    };
+    child.once("spawn", onSpawn);
+    child.once("error", onError);
+    child.once("exit", onExit);
+    child.once("close", onExit);
+    stderr.on("data", onData);
+    stderr.once("end", onEnd);
+    stderr.once("error", onError);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/browser-manager.ts
 var DEFAULT_BROWSER_MANAGER_OPERATIONS = {
   access: access2,
   mkdtemp,
-  readFile: readFile2,
+  allocatePort: allocateBrowserPort,
   rm: (path, options) => rm2(path, options),
   fetch: (input, init) => fetch(input, init),
   spawn,
@@ -625,9 +919,13 @@ function setManagedBrowser(owner, browser) {
 function launchPromiseForOwner(owner) {
   return owner ? managedBrowserScope(owner).launchPromise : state.launchPromise;
 }
+function latestLaunchPromiseForOwner(owner) {
+  return owner ? managedBrowserScope(owner).latestLaunchPromise : state.latestLaunchPromise;
+}
 function setLaunchPromise(owner, launchPromise) {
-  if (owner) managedBrowserScope(owner).launchPromise = launchPromise;
-  else state.launchPromise = launchPromise;
+  const scope = owner ? managedBrowserScope(owner) : state;
+  scope.launchPromise = launchPromise;
+  if (launchPromise) scope.latestLaunchPromise = launchPromise;
 }
 function managedBrowserPort(owner) {
   return owner ? managedBrowserScope(owner).port : state.port;
@@ -652,12 +950,6 @@ function setLastLaunchAttempt(owner, attempt) {
 function formatError2(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function isNodeError2(error) {
-  return error instanceof Error && "code" in error;
-}
-function normalizePathForComparison(value) {
-  return process.platform === "win32" ? value.toLowerCase() : value;
-}
 async function ensureDevToolsEndpoint(waitMs = DEFAULT_ENDPOINT_WAIT_MS, callerSignal, owner) {
   callerSignal?.throwIfAborted();
   if (extensionsConfigured(owner)) {
@@ -665,14 +957,19 @@ async function ensureDevToolsEndpoint(waitMs = DEFAULT_ENDPOINT_WAIT_MS, callerS
     await ensureManagedBrowserLaunched(waitMs, callerSignal, owner);
     return;
   }
+  const pendingLaunch = launchPromiseForOwner(owner);
+  if (pendingLaunch) {
+    await waitForCaller(pendingLaunch, callerSignal);
+    return;
+  }
   if (canAutoLaunchBrowser(owner)) {
+    const launchBeforeProbe = latestLaunchPromiseForOwner(owner);
     try {
       await withEndpointRetry(
         () => fetchDevToolsJson("/json/version", { signal: callerSignal }, owner),
         waitMs,
         callerSignal
       );
-      return;
     } catch (error) {
       if (shouldAutoLaunchAfterEndpointError(error, owner)) {
         await ensureManagedBrowserLaunched(waitMs, callerSignal, owner);
@@ -680,6 +977,14 @@ async function ensureDevToolsEndpoint(waitMs = DEFAULT_ENDPOINT_WAIT_MS, callerS
       }
       throw error;
     }
+    let observedLaunch = launchBeforeProbe;
+    while (true) {
+      const concurrentLaunch = latestLaunchPromiseForOwner(owner);
+      if (!concurrentLaunch || concurrentLaunch === observedLaunch) break;
+      observedLaunch = concurrentLaunch;
+      await waitForCaller(concurrentLaunch, callerSignal);
+    }
+    return;
   }
   try {
     await fetchDevToolsJson("/json/version", { signal: callerSignal }, owner);
@@ -757,7 +1062,7 @@ async function prepareManagedBrowserLaunch(waitMs, generation, signal, owner) {
     throwIfBrowserLaunchCancelled(generation, signal, owner);
     if (!available) {
       throw new DevToolsEndpointError(
-        `Cannot launch the extension-owned browser because explicit port ${managedBrowserPort(owner)} is already in use. Choose a free browser.endpoint port or reset the endpoint to use a dynamic managed port.`
+        `Cannot launch the extension-owned browser because explicit port ${managedBrowserPort(owner)} is already in use. Choose a free browser.endpoint port or reset the endpoint to use an automatically selected managed port.`
       );
     }
   }
@@ -765,12 +1070,16 @@ async function prepareManagedBrowserLaunch(waitMs, generation, signal, owner) {
 }
 async function launchManagedBrowser(waitMs, generation, signal, owner) {
   throwIfBrowserLaunchCancelled(generation, signal, owner);
-  const candidateDefinitions = browserCandidateDefinitions(owner);
-  const candidates = await resolveBrowserCandidates(candidateDefinitions, generation, signal, owner);
+  const candidateDefinitions = browserCandidateDefinitions(browserSettingsForOwner(owner));
+  const candidates = await resolveBrowserCandidates(
+    candidateDefinitions,
+    browserManagerOperations.access,
+    () => throwIfBrowserLaunchCancelled(generation, signal, owner)
+  );
   throwIfBrowserLaunchCancelled(generation, signal, owner);
   setLastLaunchAttempt(owner, {
     candidateLabels: candidateDefinitions.map(formatBrowserCandidateDefinition),
-    mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "dynamic-port"
+    mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "automatic-port"
   });
   if (candidates.length === 0) {
     throw new DevToolsEndpointError(noBrowserCandidateMessage(candidateDefinitions, owner));
@@ -785,7 +1094,7 @@ async function launchManagedBrowser(waitMs, generation, signal, owner) {
       setLastLaunchAttempt(owner, {
         ...lastLaunchAttempt(owner),
         candidateLabels: candidateDefinitions.map(formatBrowserCandidateDefinition),
-        mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "dynamic-port",
+        mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "automatic-port",
         selectedCandidate: formatBrowserCandidate(candidate),
         userDataDir: managedBrowserForOwner(owner)?.userDataDir
       });
@@ -797,7 +1106,7 @@ async function launchManagedBrowser(waitMs, generation, signal, owner) {
         setLastLaunchAttempt(owner, {
           ...lastLaunchAttempt(owner) ?? {
             candidateLabels: candidateDefinitions.map(formatBrowserCandidateDefinition),
-            mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "dynamic-port"
+            mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "automatic-port"
           },
           lastError: formatError2(cancellation)
         });
@@ -807,7 +1116,7 @@ async function launchManagedBrowser(waitMs, generation, signal, owner) {
       setLastLaunchAttempt(owner, {
         ...lastLaunchAttempt(owner) ?? {
           candidateLabels: candidateDefinitions.map(formatBrowserCandidateDefinition),
-          mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "dynamic-port"
+          mode: managedBrowserPortConfigured(owner) ? "explicit-port" : "automatic-port"
         },
         lastError: formatError2(error)
       });
@@ -852,19 +1161,24 @@ function classifyExtensionBrowserVersion(version) {
 }
 async function launchBrowserCandidate(candidate, waitMs, generation, signal, owner) {
   throwIfBrowserLaunchCancelled(generation, signal, owner);
-  const userDataDir = await browserManagerOperations.mkdtemp(join2(tmpdir(), MANAGED_BROWSER_PROFILE_PREFIX));
+  const userDataDir = await browserManagerOperations.mkdtemp(join3(tmpdir(), MANAGED_BROWSER_PROFILE_PREFIX));
   let managedBrowser;
   try {
     throwIfBrowserLaunchCancelled(generation, signal, owner);
-    const portArgument = managedBrowserPortConfigured(owner) ? String(managedBrowserPort(owner)) : "0";
-    const args = buildManagedBrowserLaunchArguments(userDataDir, portArgument, managedBrowserExtensionPaths(owner));
+    const port = managedBrowserPortConfigured(owner) ? managedBrowserPort(owner) : await browserManagerOperations.allocatePort(browserSettingsForOwner(owner).host);
+    throwIfBrowserLaunchCancelled(generation, signal, owner);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new DevToolsEndpointError("Cannot launch a browser without a valid nonzero DevTools port.");
+    }
+    const args = buildManagedBrowserLaunchArguments(userDataDir, String(port), managedBrowserExtensionPaths(owner));
     const child = browserManagerOperations.spawn(candidate.resolvedExecutable, args, {
       shell: false,
-      stdio: "ignore"
+      stdio: ["ignore", "ignore", "pipe"]
     });
     const launchedBrowser = {
       process: child,
       userDataDir,
+      port,
       exited: false,
       ready: false,
       ownerGeneration: generation,
@@ -882,24 +1196,12 @@ async function launchBrowserCandidate(candidate, waitMs, generation, signal, own
         setManagedBrowserPort(owner, managedBrowserConfiguredPort(owner));
       }
     });
-    await waitForBrowserSpawn(child);
+    const browserIdentity = await waitForBrowserStartup(child, port, waitMs, signal);
     throwIfBrowserLaunchCancelled(generation, signal, owner);
-    if (managedBrowserPortConfigured(owner)) {
-      launchedBrowser.port = managedBrowserPort(owner);
-    } else {
-      launchedBrowser.port = await readManagedBrowserPort(
-        userDataDir,
-        launchedBrowser,
-        waitMs,
-        generation,
-        signal,
-        owner
-      );
-      throwIfBrowserLaunchCancelled(generation, signal, owner);
-      setManagedBrowserPort(owner, launchedBrowser.port);
-    }
-    await waitForDevToolsEndpoint(waitMs, launchedBrowser, generation, signal, owner);
+    setManagedBrowserPort(owner, port);
+    await waitForDevToolsEndpoint(waitMs, launchedBrowser, browserIdentity, generation, signal, owner);
     throwIfBrowserLaunchCancelled(generation, signal, owner);
+    throwIfManagedBrowserExited(launchedBrowser);
     launchedBrowser.ready = true;
   } catch (error) {
     if (managedBrowser) await shutdownManagedBrowser(managedBrowser, { awaitLaunch: false, owner });
@@ -924,55 +1226,21 @@ function buildManagedBrowserLaunchArguments(userDataDir, portArgument, extension
     "about:blank"
   ];
 }
-function waitForBrowserSpawn(child) {
-  return new Promise((resolve3, reject) => {
-    let settled = false;
-    const settle = (callback) => {
-      if (settled) return;
-      settled = true;
-      child.off("error", onError);
-      child.off("spawn", onSpawn);
-      callback();
-    };
-    const onError = (error) => settle(() => reject(error));
-    const onSpawn = () => settle(resolve3);
-    child.once("error", onError);
-    child.once("spawn", onSpawn);
-  });
-}
-async function readManagedBrowserPort(userDataDir, managedBrowser, waitMs, generation, signal, owner) {
-  const activePortFile = join2(userDataDir, DEVTOOLS_ACTIVE_PORT_FILE);
-  const deadline = Date.now() + waitMs;
-  while (true) {
-    throwIfManagedBrowserExited(managedBrowser);
-    const text = await browserManagerOperations.readFile(activePortFile, "utf8").catch((error) => {
-      if (isNodeError2(error) && error.code === "ENOENT") return void 0;
-      throw error;
-    });
-    throwIfBrowserLaunchCancelled(generation, signal, owner);
-    const portText = text?.split(/\r?\n/, 1)[0]?.trim();
-    const port = Number(portText);
-    if (Number.isInteger(port) && port > 0) return port;
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) {
-      throw new DevToolsEndpointError(
-        [
-          "Timed out waiting for auto-launched browser DevToolsActivePort.",
-          `Expected file: ${activePortFile}`,
-          launchHint(owner)
-        ].join("\n")
-      );
-    }
-    await browserManagerOperations.sleep(Math.min(DEFAULT_ENDPOINT_RETRY_MS, remainingMs), signal);
-  }
-}
-async function waitForDevToolsEndpoint(waitMs, managedBrowser, generation, signal, owner) {
+async function waitForDevToolsEndpoint(waitMs, managedBrowser, browserIdentity, generation, signal, owner) {
   const deadline = Date.now() + waitMs;
   while (true) {
     throwIfManagedBrowserExited(managedBrowser);
     try {
-      await fetchDevToolsJson("/json/version", { signal }, owner);
+      const version = await fetchDevToolsJson(
+        "/json/version",
+        { signal },
+        owner
+      );
       throwIfBrowserLaunchCancelled(generation, signal, owner);
+      throwIfManagedBrowserExited(managedBrowser);
+      if (browserWebSocketIdentity(version?.webSocketDebuggerUrl, managedBrowser.port ?? 0) !== browserIdentity) {
+        throw new DevToolsEndpointError("DevTools endpoint does not match the auto-launched browser.");
+      }
       return;
     } catch (error) {
       if (!isRetryableEndpointError(error)) throw error;
@@ -1171,16 +1439,16 @@ function launchModeLabel(owner) {
     if (!isLocalDevToolsHost(browser.host)) return "invalid; extensions require a local endpoint";
     if (!browser.autoLaunchEnabled) return "invalid; extensions require auto-launch";
     if (managedBrowser && !managedBrowser.exited) {
-      return managedBrowserPortConfigured(owner) ? "extension-owned browser on explicit port" : "extension-owned browser on dynamic port";
+      return managedBrowserPortConfigured(owner) ? "extension-owned browser on explicit port" : "extension-owned browser on automatically selected port";
     }
-    return managedBrowserPortConfigured(owner) ? "force extension-owned launch on explicit port" : "force extension-owned launch on dynamic port";
+    return managedBrowserPortConfigured(owner) ? "force extension-owned launch on explicit port" : "force extension-owned launch on automatically selected port";
   }
   if (!isLocalDevToolsHost(browser.host)) return "manual remote endpoint";
   if (!browser.autoLaunchEnabled) return "manual; auto-launch disabled";
   if (managedBrowser && !managedBrowser.exited) {
-    return managedBrowserPortConfigured(owner) ? "auto-launched on explicit port" : "auto-launched on dynamic port";
+    return managedBrowserPortConfigured(owner) ? "auto-launched on explicit port" : "auto-launched on automatically selected port";
   }
-  return managedBrowserPortConfigured(owner) ? "attach first; auto-launch explicit port" : "attach first; auto-launch dynamic port";
+  return managedBrowserPortConfigured(owner) ? "attach first; auto-launch explicit port" : "attach first; auto-launch on an automatically selected port";
 }
 function launchAttemptLines(owner) {
   const attempt = lastLaunchAttempt(owner);
@@ -1206,14 +1474,14 @@ function launchHint(owner) {
   if (!browser.autoLaunchEnabled) {
     return `Auto-launch is disabled. Start a browser manually: ${chromeLaunchCommand(owner)}`;
   }
-  const managedMode = managedBrowserPortConfigured(owner) ? `port ${managedBrowserPort(owner)}` : "a dynamic DevTools port";
+  const managedMode = managedBrowserPortConfigured(owner) ? `port ${managedBrowserPort(owner)}` : "an automatically selected nonzero DevTools port";
   return `If no endpoint is available, Pi will auto-launch a Chromium-family browser with ${managedMode} and an isolated temp profile. Manual command: ${chromeLaunchCommand(owner)}`;
 }
 function browserCandidateHint(owner) {
   if (extensionsConfigured(owner)) {
     return "Extension browser requirement: configure Chrome for Testing or Chromium with browser.executablePath; branded Chrome is rejected because it may ignore unpacked-extension flags.";
   }
-  return `Browser candidates: ${browserCandidateDefinitions(owner).map((candidate) => candidate.label).join(", ")}`;
+  return `Browser candidates: ${browserCandidateDefinitions(browserSettingsForOwner(owner)).map((candidate) => candidate.label).join(", ")}`;
 }
 function chromeLaunchCommand(owner) {
   const executable = browserSettingsForOwner(owner).executablePath ?? defaultManualBrowserExecutable();
@@ -1233,151 +1501,6 @@ function isLocalDevToolsHost(host) {
   const normalizedHost = host.toLowerCase().replace(/^\[(.*)]$/, "$1");
   return ["localhost", "127.0.0.1", "::1", "0:0:0:0:0:0:0:1"].includes(normalizedHost);
 }
-function browserCandidateDefinitions(owner) {
-  const explicitCandidate = explicitBrowserCandidateDefinition(owner);
-  if (explicitCandidate.length > 0) return explicitCandidate;
-  return uniqueBrowserCandidates(platformBrowserCandidateDefinitions());
-}
-function explicitBrowserCandidateDefinition(owner) {
-  const browser = browserSettingsForOwner(owner);
-  if (!browser.executablePath) return [];
-  return [
-    {
-      label: browser.executablePathSource === "environment" ? "PI_CHROME_DEVTOOLS_BROWSER" : "browser.executablePath",
-      executable: browser.executablePath,
-      source: "env"
-    }
-  ];
-}
-function platformBrowserCandidateDefinitions() {
-  if (process.platform === "darwin") {
-    return [
-      {
-        label: "Google Chrome",
-        executable: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-        source: "wellKnownPath"
-      },
-      {
-        label: "Chromium",
-        executable: "/Applications/Chromium.app/Contents/MacOS/Chromium",
-        source: "wellKnownPath"
-      },
-      {
-        label: "Brave Browser",
-        executable: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-        source: "wellKnownPath"
-      },
-      {
-        label: "Microsoft Edge",
-        executable: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-        source: "wellKnownPath"
-      }
-    ];
-  }
-  if (process.platform === "win32") {
-    return windowsBrowserCandidateDefinitions();
-  }
-  return [
-    { label: "Google Chrome", executable: "google-chrome", source: "path" },
-    { label: "Google Chrome Stable", executable: "google-chrome-stable", source: "path" },
-    { label: "Chromium", executable: "chromium", source: "path" },
-    { label: "Chromium Browser", executable: "chromium-browser", source: "path" },
-    { label: "Brave Browser", executable: "brave-browser", source: "path" },
-    { label: "Brave", executable: "brave", source: "path" },
-    { label: "Microsoft Edge", executable: "microsoft-edge", source: "path" },
-    { label: "Microsoft Edge Stable", executable: "microsoft-edge-stable", source: "path" }
-  ];
-}
-function windowsBrowserCandidateDefinitions() {
-  const programFiles = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(
-    (value) => typeof value === "string" && value.length > 0
-  );
-  const wellKnownPaths = programFiles.flatMap((root) => [
-    join2(root, "Google", "Chrome", "Application", "chrome.exe"),
-    join2(root, "Chromium", "Application", "chrome.exe"),
-    join2(root, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
-    join2(root, "Microsoft", "Edge", "Application", "msedge.exe")
-  ]);
-  return [
-    ...wellKnownPaths.map((executable) => ({
-      label: browserLabelFromExecutable(executable),
-      executable,
-      source: "wellKnownPath"
-    })),
-    { label: "Google Chrome", executable: "chrome.exe", source: "path" },
-    { label: "Chromium", executable: "chromium.exe", source: "path" },
-    { label: "Brave Browser", executable: "brave.exe", source: "path" },
-    { label: "Microsoft Edge", executable: "msedge.exe", source: "path" }
-  ];
-}
-function browserLabelFromExecutable(executable) {
-  const normalizedExecutable = normalizePathForComparison(executable);
-  if (normalizedExecutable.includes("brave")) return "Brave Browser";
-  if (normalizedExecutable.includes("edge") || normalizedExecutable.includes("msedge")) {
-    return "Microsoft Edge";
-  }
-  if (normalizedExecutable.includes("chromium")) return "Chromium";
-  return "Google Chrome";
-}
-function uniqueBrowserCandidates(candidates) {
-  const seen = /* @__PURE__ */ new Set();
-  return candidates.filter((candidate) => {
-    const key = normalizePathForComparison(candidate.executable);
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-async function resolveBrowserCandidates(definitions, generation, signal, owner) {
-  const candidates = [];
-  for (const definition of definitions) {
-    const resolvedExecutable = await resolveBrowserExecutable(definition.executable);
-    throwIfBrowserLaunchCancelled(generation, signal, owner);
-    if (!resolvedExecutable) continue;
-    candidates.push({ ...definition, resolvedExecutable });
-  }
-  return uniqueBrowserCandidatesByResolvedPath(candidates);
-}
-function uniqueBrowserCandidatesByResolvedPath(candidates) {
-  const seen = /* @__PURE__ */ new Set();
-  return candidates.filter((candidate) => {
-    const key = normalizePathForComparison(resolve2(candidate.resolvedExecutable));
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-async function resolveBrowserExecutable(executable) {
-  if (hasPathSeparator(executable) || isAbsolute2(executable)) {
-    const resolvedExecutable = isAbsolute2(executable) ? executable : resolve2(executable);
-    return await canAccessExecutable(resolvedExecutable) ? resolvedExecutable : void 0;
-  }
-  for (const directory of executableSearchPath()) {
-    for (const executableName of executableSearchNames(executable)) {
-      const candidate = join2(directory, executableName);
-      if (await canAccessExecutable(candidate)) return candidate;
-    }
-  }
-  return void 0;
-}
-function hasPathSeparator(path) {
-  return path.includes("/") || path.includes("\\");
-}
-function executableSearchPath() {
-  return (process.env.PATH ?? "").split(delimiter).filter((part) => part.length > 0);
-}
-function executableSearchNames(executable) {
-  if (process.platform !== "win32" || /\.[a-z0-9]+$/i.test(executable)) return [executable];
-  return [executable, `${executable}.exe`, `${executable}.cmd`, `${executable}.bat`];
-}
-async function canAccessExecutable(path) {
-  try {
-    await browserManagerOperations.access(path, process.platform === "win32" ? constants2.F_OK : constants2.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function formatBrowserCandidate(candidate) {
   return `${candidate.label} (${candidate.resolvedExecutable})`;
 }
@@ -1435,19 +1558,29 @@ function inspectBrowserVersion(executable, signal) {
     });
   });
 }
-function isPortAvailable(host, port) {
-  return new Promise((resolveAvailability, reject) => {
+async function allocateBrowserPort(host) {
+  const port = await probeBrowserPort(host, 0);
+  if (port === void 0) throw new Error("Cannot allocate an available DevTools port.");
+  return port;
+}
+async function isPortAvailable(host, port) {
+  return await probeBrowserPort(host, port) !== void 0;
+}
+function probeBrowserPort(host, port) {
+  return new Promise((resolvePort, reject) => {
     const server = createServer();
     const normalizedHost = host.replace(/^\[(.*)]$/, "$1");
     server.unref();
     server.once("error", (error) => {
-      if (error.code === "EADDRINUSE") resolveAvailability(false);
+      if (error.code === "EADDRINUSE") resolvePort(void 0);
       else reject(error);
     });
     server.listen(port, normalizedHost, () => {
+      const address = server.address();
       server.close((error) => {
         if (error) reject(error);
-        else resolveAvailability(true);
+        else if (!address || typeof address === "string") reject(new Error("DevTools port probe has no address."));
+        else resolvePort(address.port);
       });
     });
   });
@@ -1468,10 +1601,13 @@ export {
   WEBMCP_TOOL_NAMES,
   CHROME_DEVTOOLS_TOOL_NAMES,
   isWebMcpToolName,
+  isChromeDevtoolsToolMode,
   waitForSettingsWrites,
   loadSettings,
   parseBrowserEndpoint,
+  ToolCatalogApplicationError,
   saveSettings,
+  saveToolMode,
   saveWebMcpSettings,
   saveBrowserSettings,
   settingsFilePath,
@@ -1505,4 +1641,4 @@ export {
   endpointConfigHint,
   formatPageListItem
 };
-//# sourceMappingURL=chunk-LSJSDY2M.ts.map
+//# sourceMappingURL=chunk-WTMZID3G.ts.map