negotium 0.1.37 → 0.1.39

package/dist/runtime/src/platform/playwright/manager.ts

@@ -1,5 +1,5 @@
 import { type ChildProcess, execFileSync, spawn } from "node:child_process";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import {
   cpSync,
   existsSync,
@@ -14,6 +14,7 @@ import { dirname, join, resolve } from "node:path";
 import {
   BROWSER_PROFILES_DIR,
   BROWSER_RS_BIN,
+  type BrowserProxyConfig,
   PATCHRIGHT_MCP_BIN,
   PLAYWRIGHT_BASE_PORT,
   PLAYWRIGHT_MAX_PORT,
@@ -36,6 +37,7 @@ import {
   type HeadedPlaywrightSpawnSpec,
   resolveHeadedPlaywrightSpawn,
 } from "#platform/playwright/headed-launch";
+import { probePlaywrightMcpTransports } from "#platform/playwright/transport-probe";
 import { sanitizeTopicName } from "#security/sanitize";
 import {
   assignTopicBrowserProfile,
@@ -51,11 +53,48 @@ import {
   waitForChildProcessSpawnError,
 } from "./manager-utils";
 
+export interface PlaywrightProfileBinding {
+  readonly instanceKey: string;
+  readonly ownerId: string;
+  readonly profile: string;
+}
+
+export interface PlaywrightChildEnvironmentContext {
+  instanceKey: string;
+  ownerId: string;
+  capability: string;
+  proxy: BrowserProxyConfig | null;
+  browserRsBin?: string;
+  environment: NodeJS.ProcessEnv;
+}
+
+export interface PlaywrightManagerHost {
+  readonly portsDir: string;
+  readonly basePort: number;
+  readonly maxPort: number;
+  readonly browserBin: string;
+  readonly fallbackBrowserBin: string;
+  readonly browserRsBin?: string;
+  readonly resolveProxy: () => BrowserProxyConfig | null;
+  readonly resolveTopicBinding: (userId: string, topic?: string) => PlaywrightProfileBinding;
+  readonly resolveNamedBinding: (ownerId: string, rawProfile: string) => PlaywrightProfileBinding;
+  readonly resolveInstanceDataDir: (instanceKey: string) => string;
+  readonly createChildEnvironment: (
+    context: PlaywrightChildEnvironmentContext,
+  ) => NodeJS.ProcessEnv;
+  /** Reap an orphan that owns this exact host-managed data directory. */
+  readonly cleanupBrowserProcessesForDataDir: (userDataDir: string) => void;
+  /** Reap host-managed browsers that are not represented by the supplied live directories. */
+  readonly reapOrphanBrowsers: (liveUserDataDirs: Iterable<string>) => void;
+}
+
 export {
   cleanupZombiePlaywright,
   isBrowserJanitorOwner,
+  reapOrphanBrowsers,
   selectOrphanBrowserPids,
 } from "#platform/playwright/browser-processes";
+export { probePlaywrightMcpTransports } from "#platform/playwright/transport-probe";
 export {
   browserProcessMatchesExpectedProfile,
   extractUserDataDirArg,
@@ -68,14 +107,57 @@ export { PLAYWRIGHT_PORTS_DIR };
 
 /** Multiple topics assigned to one profile reuse one browser process. */
 export function makeInstanceKey(userId: string, topic: string | undefined): string {
-  if (!topic) return makeBrowserProfileInstanceKey(userId, "default");
+  return resolvePlaywrightTopicBinding(userId, topic).instanceKey;
+}
+
+export function resolvePlaywrightTopicBinding(
+  userId: string,
+  topic: string | undefined,
+): PlaywrightProfileBinding {
+  return validateProfileBinding(managerHost.resolveTopicBinding(userId, topic));
+}
+
+function defaultTopicBinding(userId: string, topic: string | undefined): PlaywrightProfileBinding {
+  if (!topic) return managerHost.resolveNamedBinding(userId, "default");
   const ownerId = getBrowserProfileOwner(topic, userId);
   const profile = migrateLegacyTopicProfile(ownerId, topic);
-  return makeBrowserProfileInstanceKey(ownerId, profile);
+  return managerHost.resolveNamedBinding(ownerId, profile);
 }
 
 export function makeBrowserProfileInstanceKey(ownerId: string, rawProfile: string): string {
-  return `profile:${encodeURIComponent(ownerId)}:${normalizeBrowserProfileName(rawProfile)}`;
+  return resolvePlaywrightProfileBinding(ownerId, rawProfile).instanceKey;
+}
+
+export function resolvePlaywrightProfileBinding(
+  ownerId: string,
+  rawProfile: string,
+): PlaywrightProfileBinding {
+  return validateProfileBinding(managerHost.resolveNamedBinding(ownerId, rawProfile));
+}
+
+function validateProfileBinding(binding: PlaywrightProfileBinding): PlaywrightProfileBinding {
+  if (
+    !binding ||
+    typeof binding.instanceKey !== "string" ||
+    !binding.instanceKey.trim() ||
+    typeof binding.ownerId !== "string" ||
+    !binding.ownerId.trim() ||
+    typeof binding.profile !== "string" ||
+    !binding.profile.trim()
+  ) {
+    throw new Error("invalid Playwright profile binding");
+  }
+  return Object.freeze({ ...binding });
+}
+
+function defaultNamedBinding(ownerId: string, rawProfile: string): PlaywrightProfileBinding {
+  const profile = normalizeBrowserProfileName(rawProfile);
+  const instanceKey = `profile:${encodeURIComponent(ownerId)}:${profile}`;
+  return {
+    instanceKey,
+    ownerId,
+    profile,
+  };
 }
 
 export function legacyBrowserProfileName(topic: string): string {
@@ -90,7 +172,7 @@ function migrateLegacyTopicProfile(ownerId: string, topic: string): string {
   if (!existsSync(legacyDir)) return current;
 
   const profile = legacyBrowserProfileName(topic);
-  const profileDir = resolveProfileDir(ownerId, profile);
+  const profileDir = defaultProfileDir(ownerId, profile);
   mkdirSync(dirname(profileDir), { recursive: true });
   if (!existsSync(profileDir)) renameSync(legacyDir, profileDir);
   assignTopicBrowserProfile({ topicId: topic, actorUserId: ownerId, profile });
@@ -98,6 +180,88 @@ function migrateLegacyTopicProfile(ownerId: string, topic: string): string {
   return profile;
 }
 
+function defaultChildEnvironment(context: PlaywrightChildEnvironmentContext): NodeJS.ProcessEnv {
+  const { capability, ownerId, proxy, browserRsBin, environment } = context;
+  return {
+    ...environment,
+    NEGOTIUM_BROWSER_CAPABILITY: capability,
+    NEGOTIUM_BROWSER_VAULT_USER_ID: ownerId,
+    ...(browserRsBin && !proxy ? { NEGOTIUM_BROWSER_RS_BIN: browserRsBin } : {}),
+    ...(proxy
+      ? {
+          NEGOTIUM_BROWSER_PROXY_SERVER: proxy.server,
+          ...(proxy.username ? { NEGOTIUM_BROWSER_PROXY_USERNAME: proxy.username } : {}),
+          ...(proxy.password ? { NEGOTIUM_BROWSER_PROXY_PASSWORD: proxy.password } : {}),
+          ...(proxy.bypass ? { NEGOTIUM_BROWSER_PROXY_BYPASS: proxy.bypass } : {}),
+        }
+      : {}),
+  };
+}
+
+const defaultManagerHost: Readonly<PlaywrightManagerHost> = Object.freeze({
+  portsDir: PLAYWRIGHT_PORTS_DIR,
+  basePort: PLAYWRIGHT_BASE_PORT,
+  maxPort: PLAYWRIGHT_MAX_PORT,
+  browserBin: PLAYWRIGHT_MCP_BIN,
+  fallbackBrowserBin: PATCHRIGHT_MCP_BIN,
+  browserRsBin: BROWSER_RS_BIN,
+  resolveProxy: resolveBrowserProxy,
+  resolveTopicBinding: defaultTopicBinding,
+  resolveNamedBinding: defaultNamedBinding,
+  resolveInstanceDataDir(instanceKey: string) {
+    const { ownerId, profile } = parseInstanceKey(instanceKey);
+    return defaultProfileDir(ownerId, profile);
+  },
+  createChildEnvironment: defaultChildEnvironment,
+  cleanupBrowserProcessesForDataDir: killBrowserProcsForUserDataDir,
+  reapOrphanBrowsers,
+});
+
+let managerHost: Readonly<PlaywrightManagerHost> = defaultManagerHost;
+
+/**
+ * Configure product-specific profile storage and browser launch glue.
+ * Call once during bootstrap, before any browser instance is started.
+ */
+export function configurePlaywrightManagerHost(
+  overrides: Partial<PlaywrightManagerHost>,
+): Readonly<PlaywrightManagerHost> {
+  if (instances.size > 0 || spawning.size > 0 || pinnedInstances.size > 0) {
+    throw new Error("cannot configure Playwright manager while browser instances are active");
+  }
+  const next = { ...managerHost, ...overrides };
+  if (!next.portsDir || !Number.isInteger(next.basePort) || !Number.isInteger(next.maxPort)) {
+    throw new Error("invalid Playwright manager paths or port range");
+  }
+  if (next.basePort < 1 || next.maxPort > 65_535 || next.basePort > next.maxPort) {
+    throw new Error("invalid Playwright manager port range");
+  }
+  if (!next.browserBin || !next.fallbackBrowserBin) {
+    throw new Error("Playwright manager browser binaries are required");
+  }
+  if (
+    next.resolveInstanceDataDir !== defaultManagerHost.resolveInstanceDataDir &&
+    (next.cleanupBrowserProcessesForDataDir ===
+      defaultManagerHost.cleanupBrowserProcessesForDataDir ||
+      next.reapOrphanBrowsers === defaultManagerHost.reapOrphanBrowsers)
+  ) {
+    throw new Error(
+      "custom Playwright profile paths require host crash cleanup and orphan sweep hooks",
+    );
+  }
+  managerHost = Object.freeze(next);
+  return managerHost;
+}
+
+export function getPlaywrightManagerHost(): Readonly<PlaywrightManagerHost> {
+  return managerHost;
+}
+
+/** Restore Negotium's built-in browser host after all instances are stopped. */
+export function resetPlaywrightManagerHost(): void {
+  configurePlaywrightManagerHost(defaultManagerHost);
+}
+
 interface InstanceKeyParts {
   ownerId: string;
   profile: string;
@@ -118,8 +282,8 @@ function portFileName(instanceKey: string): string {
 
 function writePortFile(instanceKey: string, port: number) {
   try {
-    mkdirSync(PLAYWRIGHT_PORTS_DIR, { recursive: true });
-    writeFileSync(join(PLAYWRIGHT_PORTS_DIR, portFileName(instanceKey)), String(port));
+    mkdirSync(managerHost.portsDir, { recursive: true });
+    writeFileSync(join(managerHost.portsDir, portFileName(instanceKey)), String(port));
   } catch (e) {
     logger.warn({ err: e, instanceKey, port }, "Failed to save playwright port file");
   }
@@ -127,7 +291,7 @@ function writePortFile(instanceKey: string, port: number) {
 
 function deletePortFile(instanceKey: string) {
   try {
-    unlinkSync(join(PLAYWRIGHT_PORTS_DIR, portFileName(instanceKey)));
+    unlinkSync(join(managerHost.portsDir, portFileName(instanceKey)));
   } catch (e) {
     logger.warn({ err: e, instanceKey }, "Failed to delete playwright port file");
   }
@@ -136,7 +300,7 @@ function deletePortFile(instanceKey: string) {
 function readPortFile(instanceKey: string): number | null {
   try {
     const port = Number.parseInt(
-      readFileSync(join(PLAYWRIGHT_PORTS_DIR, portFileName(instanceKey)), "utf8").trim(),
+      readFileSync(join(managerHost.portsDir, portFileName(instanceKey)), "utf8").trim(),
       10,
     );
     return Number.isInteger(port) ? port : null;
@@ -145,14 +309,12 @@ function readPortFile(instanceKey: string): number | null {
   }
 }
 
-const BASE_PORT = PLAYWRIGHT_BASE_PORT;
-const MAX_PORT = PLAYWRIGHT_MAX_PORT;
 const MAX_IDLE_MS = 2 * 60 * 60 * 1000; // 2 hours idle → eligible for eviction
 
 interface PlaywrightInstance {
   process: ChildProcess;
   port: number;
-  userId: string;
+  ownerId: string;
   startedAt: number;
   lastUsedAt: number;
   capability: string;
@@ -160,18 +322,33 @@ interface PlaywrightInstance {
 
 const instances = new Map<string, PlaywrightInstance>();
 
+function assertInstanceOwner(instanceKey: string, ownerId: string): void {
+  const existing = instances.get(instanceKey);
+  if (existing && existing.ownerId !== ownerId) {
+    throw new Error(
+      `Playwright profile binding owner changed for "${instanceKey}" (${existing.ownerId} -> ${ownerId})`,
+    );
+  }
+}
+
 // Track used ports to avoid collisions
 const usedPorts = new Set<number>();
 
 // Prevent concurrent spawns for the same key
 const spawning = new Map<string, Promise<number | null>>();
 
+export interface PlaywrightMaintenanceControl {
+  /** Stop one of the locked instances before mutating its profile directory. */
+  stopInstance(instanceKey: string): Promise<boolean>;
+}
+
 /** Serialize destructive profile maintenance with normal browser startup. */
 export async function withPlaywrightInstanceMaintenance<T>(
   rawKeys: string[],
-  operation: () => Promise<T>,
+  operation: (control: PlaywrightMaintenanceControl) => Promise<T>,
 ): Promise<T> {
   const keys = [...new Set(rawKeys)].sort();
+  const lockedKeys = new Set(keys);
   for (;;) {
     const pending = keys
       .map((key) => spawning.get(key))
@@ -190,7 +367,32 @@ export async function withPlaywrightInstanceMaintenance<T>(
     for (const key of keys) spawning.set(key, barrier);
 
     try {
-      return await operation();
+      return await operation({
+        async stopInstance(instanceKey) {
+          if (!lockedKeys.has(instanceKey)) {
+            throw new Error(`Playwright maintenance does not own instance "${instanceKey}"`);
+          }
+          const process = instances.get(instanceKey)?.process;
+          if (!process) return false;
+          killInstance(instanceKey);
+          if (!(await waitForChildProcessExit(process, 3000))) {
+            logger.warn(
+              { instanceKey, pid: process.pid },
+              "Playwright MCP ignored SIGTERM during profile maintenance",
+            );
+            try {
+              process.kill("SIGKILL");
+            } catch (error) {
+              logger.warn(
+                { err: error, instanceKey, pid: process.pid },
+                "Failed to SIGKILL Playwright MCP during profile maintenance",
+              );
+            }
+            await waitForChildProcessExit(process, 1000);
+          }
+          return true;
+        },
+      });
     } finally {
       for (const key of keys) {
         if (spawning.get(key) === barrier) spawning.delete(key);
@@ -200,6 +402,36 @@ export async function withPlaywrightInstanceMaintenance<T>(
   }
 }
 
+/** Stop one managed instance under the same serialization used by startup and profile mutation. */
+export function stopPlaywrightInstance(instanceKey: string): Promise<boolean> {
+  return withPlaywrightInstanceMaintenance([instanceKey], ({ stopInstance }) =>
+    stopInstance(instanceKey),
+  );
+}
+
+/** Run owner-aware named-profile maintenance under one lifecycle barrier. */
+export function withPlaywrightProfileMaintenance<T>(
+  ownerId: string,
+  rawProfile: string,
+  operation: (
+    binding: PlaywrightProfileBinding,
+    control: PlaywrightMaintenanceControl,
+  ) => Promise<T>,
+): Promise<T> {
+  const binding = resolvePlaywrightProfileBinding(ownerId, rawProfile);
+  return withPlaywrightInstanceMaintenance([binding.instanceKey], async (control) => {
+    assertInstanceOwner(binding.instanceKey, binding.ownerId);
+    return operation(binding, control);
+  });
+}
+
+/** Stop a named profile before deleting or replacing its host-managed data directory. */
+export function stopPlaywrightProfile(ownerId: string, rawProfile: string): Promise<boolean> {
+  return withPlaywrightProfileMaintenance(ownerId, rawProfile, (binding, { stopInstance }) =>
+    stopInstance(binding.instanceKey),
+  );
+}
+
 // A shared profile may have several concurrent turns. Reference counts keep an
 // idle sweep from evicting the process until every borrower has finished.
 const pinnedInstances = new Map<string, number>();
@@ -219,16 +451,48 @@ export function getPlaywrightCapability(instanceKey: string): string | undefined
   return instances.get(instanceKey)?.capability;
 }
 
-// --- Abnormal exit notification callback ---
-// Fired when a Playwright MCP child process exits with a non-zero / non-null
-// code that did NOT originate from our own killInstance() (those paths are
-// intentional cleanups, not crashes). Consumers use this to abort any
-// in-flight `handleAgentQuery` whose Claude SDK is waiting on a tool result
-// the dead MCP can never deliver — preventing 20+ minute typing-only stalls.
-type PlaywrightExitHandler = (instanceKey: string, code: number | null) => void;
-let _onPlaywrightExit: PlaywrightExitHandler | null = null;
-export function onPlaywrightExit(handler: PlaywrightExitHandler) {
-  _onPlaywrightExit = handler;
+/** Resolve a live browser capability back to its owning user. */
+export function resolvePlaywrightCapabilityOwner(capability: string): string | undefined {
+  if (!capability) return undefined;
+  const provided = Buffer.from(capability);
+  for (const instance of instances.values()) {
+    const expected = Buffer.from(instance.capability);
+    if (provided.length === expected.length && timingSafeEqual(provided, expected)) {
+      return instance.ownerId;
+    }
+  }
+  return undefined;
+}
+
+/** Run the configured host's path-bounded orphan sweep against current live instances. */
+export function reapPlaywrightOrphans(): void {
+  managerHost.reapOrphanBrowsers([...instances.keys()].map(resolveUserDataDir));
+}
+
+// --- Browser MCP failure notification callback ---
+// Fired when a managed process fails or its transport becomes unhealthy.
+// Intentional cleanup paths do not notify consumers.
+export interface PlaywrightFailure {
+  reason: "exit" | "process-error" | "unhealthy";
+  code?: number | null;
+  error?: string;
+}
+
+type PlaywrightFailureHandler = (instanceKey: string, failure: PlaywrightFailure) => void;
+const playwrightFailureHandlers = new Set<PlaywrightFailureHandler>();
+export function onPlaywrightFailure(handler: PlaywrightFailureHandler): () => void {
+  playwrightFailureHandlers.add(handler);
+  return () => playwrightFailureHandlers.delete(handler);
+}
+
+function notifyPlaywrightFailure(instanceKey: string, failure: PlaywrightFailure): void {
+  for (const handler of playwrightFailureHandlers) {
+    try {
+      handler(instanceKey, failure);
+    } catch (err) {
+      logger.warn({ err, instanceKey, failure }, "Playwright failure handler failed");
+    }
+  }
 }
 
 /**
@@ -265,7 +529,7 @@ function evictIdleInstance(): number | null {
  * mistake a live topic Playwright for an orphan and SIGKILL it.
  */
 async function allocatePort(expectedUserDataDir?: string): Promise<number> {
-  for (let port = BASE_PORT; port <= MAX_PORT; port++) {
+  for (let port = managerHost.basePort; port <= managerHost.maxPort; port++) {
     if (usedPorts.has(port)) continue;
     usedPorts.add(port); // Reserve immediately before any await to prevent concurrent allocation
 
@@ -289,7 +553,12 @@ async function allocatePort(expectedUserDataDir?: string): Promise<number> {
     // until the old listener is actually gone, and recheck every candidate in
     // case another allocator claimed a different port while we were waiting.
     await waitForPortRelease(evictedPort);
-    const reusablePort = selectReusablePort(BASE_PORT, MAX_PORT, usedPorts, isPortInUse);
+    const reusablePort = selectReusablePort(
+      managerHost.basePort,
+      managerHost.maxPort,
+      usedPorts,
+      isPortInUse,
+    );
     if (reusablePort !== null) {
       usedPorts.add(reusablePort);
       return reusablePort;
@@ -297,7 +566,7 @@ async function allocatePort(expectedUserDataDir?: string): Promise<number> {
   }
 
   throw new Error(
-    `No available ports for Playwright MCP (${instances.size} active instances, range ${BASE_PORT}-${MAX_PORT})`,
+    `No available ports for Playwright MCP (${instances.size} active instances, range ${managerHost.basePort}-${managerHost.maxPort})`,
   );
 }
 
@@ -310,14 +579,13 @@ function ownerDirectory(ownerId: string): string {
   return `${sanitizeTopicName(ownerId).slice(0, 24)}_${digest}`;
 }
 
-function resolveProfileDir(ownerId: string, profile: string): string {
+function defaultProfileDir(ownerId: string, profile: string): string {
   return resolve(BROWSER_PROFILES_DIR, "profiles", ownerDirectory(ownerId), profile);
 }
 
 /** Resolve the shared profile userDataDir for an instanceKey. */
 function resolveUserDataDir(instanceKey: string): string {
-  const { ownerId, profile } = parseInstanceKey(instanceKey);
-  return resolveProfileDir(ownerId, profile);
+  return managerHost.resolveInstanceDataDir(instanceKey);
 }
 
 /**
@@ -366,15 +634,15 @@ function killInstance(instanceKey: string, opts?: { keepPort?: boolean }) {
 /**
  * Spawn a Playwright MCP process for the given instanceKey.
  * @param instanceKey  Unique key identifying this instance.
- * @param userId       Owner user ID (stored in the instance record).
+ * @param ownerId      Canonical profile owner ID (stored in the instance record).
  * @param reservedPort When provided the process binds to this already-reserved
  *                     port (restart path). When omitted a fresh port is allocated.
  */
 async function spawnPlaywright(
   instanceKey: string,
-  userId: string,
+  ownerId: string,
   reservedPort?: number,
-  browserBin = PLAYWRIGHT_MCP_BIN,
+  browserBin = managerHost.browserBin,
   allowFallback = true,
 ): Promise<number> {
   const userDataDir = resolveUserDataDir(instanceKey);
@@ -412,22 +680,22 @@ async function spawnPlaywright(
   // argv so the credentials never surface in `ps`/`/proc` command lines. The
   // launcher (scripts/mcp-patchright-http.mjs) reads these NEGOTIUM_BROWSER_PROXY_*
   // vars and hands them to Playwright's per-context proxy option.
-  const proxy = resolveBrowserProxy();
+  const proxy = managerHost.resolveProxy();
   const capability = randomBytes(32).toString("hex");
   const childEnv = {
-    ...process.env,
+    ...managerHost.createChildEnvironment({
+      instanceKey,
+      ownerId,
+      capability,
+      proxy,
+      browserRsBin: managerHost.browserRsBin,
+      environment: process.env,
+    }),
     NEGOTIUM_BROWSER_CAPABILITY: capability,
-    NEGOTIUM_BROWSER_VAULT_USER_ID: userId,
-    ...(BROWSER_RS_BIN && !proxy ? { NEGOTIUM_BROWSER_RS_BIN: BROWSER_RS_BIN } : {}),
-    ...(proxy
-      ? {
-          NEGOTIUM_BROWSER_PROXY_SERVER: proxy.server,
-          ...(proxy.username ? { NEGOTIUM_BROWSER_PROXY_USERNAME: proxy.username } : {}),
-          ...(proxy.password ? { NEGOTIUM_BROWSER_PROXY_PASSWORD: proxy.password } : {}),
-          ...(proxy.bypass ? { NEGOTIUM_BROWSER_PROXY_BYPASS: proxy.bypass } : {}),
-        }
-      : {}),
   };
+  // Every supported wrapper authenticates owner-scoped transports with this
+  // capability. Product-specific environment hooks may add Vault callbacks,
+  // but cannot remove transport authentication.
   if (proxy) {
     logger.info({ instanceKey, proxyServer: proxy.server }, "Browser egress proxy enabled");
   }
@@ -461,7 +729,7 @@ async function spawnPlaywright(
   // removes these listeners before signalling, so this only runs on real deaths.
   const reapCrashedBrowser = () => {
     const userDataDir = resolveUserDataDir(instanceKey);
-    killBrowserProcsForUserDataDir(userDataDir);
+    managerHost.cleanupBrowserProcessesForDataDir(userDataDir);
     cleanSingletonFiles(userDataDir);
   };
 
@@ -471,6 +739,10 @@ async function spawnPlaywright(
       releasePort(port);
       instances.delete(instanceKey);
       reapCrashedBrowser();
+      notifyPlaywrightFailure(instanceKey, {
+        reason: "process-error",
+        error: err instanceof Error ? err.message : String(err),
+      });
     }
   });
 
@@ -486,7 +758,7 @@ async function spawnPlaywright(
       releasePort(port);
       instances.delete(instanceKey);
       reapCrashedBrowser();
-      _onPlaywrightExit?.(instanceKey, code);
+      notifyPlaywrightFailure(instanceKey, { reason: "exit", code });
     }
   });
 
@@ -494,7 +766,7 @@ async function spawnPlaywright(
   instances.set(instanceKey, {
     process: proc,
     port,
-    userId,
+    ownerId,
     startedAt: now,
     lastUsedAt: now,
     capability,
@@ -502,18 +774,26 @@ async function spawnPlaywright(
 
   const ready = await Promise.race([
     (async () =>
-      (await waitForServer(port, 10_000)) && (await supportsOwnerCleanup(port, capability)))(),
+      (await waitForServer(port, 10_000)) &&
+      (await supportsOwnerCleanup(port, capability)) &&
+      (await probePlaywrightMcpTransports(port, capability)))(),
     spawnError,
   ]);
   if (!ready) {
     const exitCode = proc.exitCode;
     killInstance(instanceKey);
-    if (allowFallback && browserBin !== PATCHRIGHT_MCP_BIN) {
+    if (allowFallback && browserBin !== managerHost.fallbackBrowserBin) {
       logger.warn(
-        { instanceKey, browserBin, fallback: PATCHRIGHT_MCP_BIN },
+        { instanceKey, browserBin, fallback: managerHost.fallbackBrowserBin },
         "Preferred browser MCP unavailable or lacks owner isolation; using Patchright fallback",
       );
-      return spawnPlaywright(instanceKey, userId, undefined, PATCHRIGHT_MCP_BIN, false);
+      return spawnPlaywright(
+        instanceKey,
+        ownerId,
+        undefined,
+        managerHost.fallbackBrowserBin,
+        false,
+      );
     }
     throw new Error(
       `Playwright MCP failed health check after spawn on port ${port}` +
@@ -553,12 +833,14 @@ async function supportsOwnerCleanup(port: number, capability: string): Promise<b
  * - If not running → spawn
  */
 export async function ensurePlaywright(userId: string, topic?: string): Promise<number> {
-  const instanceKey = makeInstanceKey(userId, topic);
+  const binding = resolvePlaywrightTopicBinding(userId, topic);
+  const { instanceKey, ownerId } = binding;
 
   // If a spawn/restart is already in progress for this key, wait for it
   const inProgress = spawning.get(instanceKey);
   if (inProgress) {
     const port = await inProgress;
+    assertInstanceOwner(instanceKey, ownerId);
     if (port !== null) return port;
     // Restart failed — re-enter: by now another caller may have registered a
     // newer attempt to join, otherwise we start one ourselves.
@@ -575,24 +857,30 @@ export async function ensurePlaywright(userId: string, topic?: string): Promise<
   // a single-threaded event loop.
   const promise = (async (): Promise<number> => {
     const existing = instances.get(instanceKey);
+    assertInstanceOwner(instanceKey, ownerId);
 
     if (existing && !existing.process.killed && existing.process.exitCode === null) {
-      if (await isHealthy(existing.port)) {
+      if (await probePlaywrightMcpTransports(existing.port, existing.capability)) {
         existing.lastUsedAt = Date.now();
         return existing.port;
       }
       logger.warn({ instanceKey }, "Playwright MCP unresponsive, restarting");
       const oldPort = existing.port;
       killInstance(instanceKey);
+      notifyPlaywrightFailure(instanceKey, { reason: "unhealthy" });
       await waitForPortRelease(oldPort);
       cleanSingletonFiles(resolveUserDataDir(instanceKey));
     } else if (existing) {
       releasePort(existing.port);
       instances.delete(instanceKey);
       cleanSingletonFiles(resolveUserDataDir(instanceKey));
+      notifyPlaywrightFailure(instanceKey, {
+        reason: "exit",
+        code: existing.process.exitCode,
+      });
     }
 
-    return spawnPlaywright(instanceKey, userId);
+    return spawnPlaywright(instanceKey, ownerId);
   })().finally(() => spawning.delete(instanceKey));
   spawning.set(instanceKey, promise);
   return promise;
@@ -608,11 +896,16 @@ async function waitForPortRelease(port: number, timeoutMs = 3000): Promise<void>
 
 /** Start or reuse a named shared profile before assigning more topics to it. */
 export async function ensureBrowserProfile(ownerId: string, rawProfile: string): Promise<number> {
-  const instanceKey = makeBrowserProfileInstanceKey(ownerId, rawProfile);
+  const binding = resolvePlaywrightProfileBinding(ownerId, rawProfile);
+  const instanceKey = binding.instanceKey;
   const inProgress = spawning.get(instanceKey);
   if (inProgress) {
     const port = await inProgress;
-    if (port !== null && (await isHealthy(port))) return port;
+    assertInstanceOwner(instanceKey, binding.ownerId);
+    const capability = instances.get(instanceKey)?.capability;
+    if (port !== null && capability && (await probePlaywrightMcpTransports(port, capability))) {
+      return port;
+    }
     if (port === null) return ensureBrowserProfile(ownerId, rawProfile);
     throw new Error(`Browser profile "${rawProfile}" failed to start.`);
   }
@@ -620,6 +913,7 @@ export async function ensureBrowserProfile(ownerId: string, rawProfile: string):
   const promise = (async (): Promise<number> => {
     const publishedPort = readPortFile(instanceKey);
     const existing = instances.get(instanceKey);
+    assertInstanceOwner(instanceKey, binding.ownerId);
     if (publishedPort !== null && !existing) {
       // A port file without an in-memory instance belongs to a previous runtime.
       // Its per-process capability and ChildProcess handle cannot be recovered,
@@ -635,17 +929,27 @@ export async function ensureBrowserProfile(ownerId: string, rawProfile: string):
     }
 
     if (existing && !existing.process.killed && existing.process.exitCode === null) {
-      if (await isHealthy(existing.port)) {
+      if (await probePlaywrightMcpTransports(existing.port, existing.capability)) {
         existing.lastUsedAt = Date.now();
         return existing.port;
       }
       const oldPort = existing.port;
       killInstance(instanceKey);
+      notifyPlaywrightFailure(instanceKey, { reason: "unhealthy" });
       await waitForPortRelease(oldPort);
       cleanSingletonFiles(resolveUserDataDir(instanceKey));
+    } else if (existing) {
+      releasePort(existing.port);
+      instances.delete(instanceKey);
+      cleanSingletonFiles(resolveUserDataDir(instanceKey));
+      notifyPlaywrightFailure(instanceKey, {
+        reason: "exit",
+        code: existing.process.exitCode,
+      });
     }
-    const port = await spawnPlaywright(instanceKey, ownerId);
-    if (!(await isHealthy(port))) {
+    const port = await spawnPlaywright(instanceKey, binding.ownerId);
+    const capability = instances.get(instanceKey)?.capability;
+    if (!capability || !(await probePlaywrightMcpTransports(port, capability))) {
       killInstance(instanceKey);
       throw new Error(`Browser profile "${rawProfile}" did not pass its health check.`);
     }
@@ -661,9 +965,11 @@ export async function closeBrowserOwnerTabs(
   rawProfile: string,
   owner: string,
 ): Promise<number> {
-  const instanceKey = makeBrowserProfileInstanceKey(ownerId, rawProfile);
+  const binding = resolvePlaywrightProfileBinding(ownerId, rawProfile);
+  const instanceKey = binding.instanceKey;
   const inProgress = spawning.get(instanceKey);
   if (inProgress) await inProgress;
+  assertInstanceOwner(instanceKey, binding.ownerId);
   const instance = instances.get(instanceKey);
   if (!instance) return 0;
   const port = instance.port;
@@ -751,18 +1057,26 @@ export async function cloneProfileForChild(opts: {
   const srcOwner = getBrowserProfileOwner(opts.srcTopic, opts.userId);
   const dstOwner = getBrowserProfileOwner(opts.dstTopic, opts.userId);
   if (srcOwner !== dstOwner) {
-    const dstDir = resolveProfileDir(dstOwner, getTopicBrowserProfile(opts.dstTopic));
+    const srcBinding = resolvePlaywrightProfileBinding(
+      srcOwner,
+      getTopicBrowserProfile(opts.srcTopic),
+    );
+    const dstBinding = resolvePlaywrightProfileBinding(
+      dstOwner,
+      getTopicBrowserProfile(opts.dstTopic),
+    );
     return {
       copied: false,
-      srcDir: resolveProfileDir(srcOwner, getTopicBrowserProfile(opts.srcTopic)),
-      dstDir,
+      srcDir: resolveUserDataDir(srcBinding.instanceKey),
+      dstDir: resolveUserDataDir(dstBinding.instanceKey),
       reason: "cross-owner-fresh-profile",
     };
   }
   if (srcOwner === dstOwner && hasBrowserProfileTopic(opts.dstTopic)) {
     const profile = getTopicBrowserProfile(opts.srcTopic);
     assignTopicBrowserProfile({ topicId: opts.dstTopic, actorUserId: dstOwner, profile });
-    const sharedDir = resolveProfileDir(srcOwner, profile);
+    const binding = resolvePlaywrightProfileBinding(srcOwner, profile);
+    const sharedDir = resolveUserDataDir(binding.instanceKey);
     return {
       copied: false,
       srcDir: sharedDir,
@@ -891,7 +1205,7 @@ setInterval(
   () => {
     while (evictIdleInstance() !== null) {}
     try {
-      reapOrphanBrowsers([...instances.keys()].map(resolveUserDataDir));
+      reapPlaywrightOrphans();
     } catch (e) {
       logger.debug({ err: e }, "reapOrphanBrowsers sweep failed");
     }