rechrome 1.36.0 → 1.36.1

package/README.md

@@ -164,6 +164,11 @@ If no supported daemon manager is available, setup asks before installing `oxmgr
 when launched with npx. Pass `--yes` to approve this without prompting,
 for example `bunx rechrome setup --profile Default --yes`.
 
+On macOS, a daemon started by launchd or oxmgr cannot read Chrome's profile folder
+until its bun binary has Full Disk Access. `rech status` and the serve log report
+this and name the binary. See [Keeping rech serve running on macOS](docs/macos-daemon.md)
+for the grant, a LaunchAgent, and the terminal keep-alive alternative.
+
 Agents setting up Chrome on macOS can use the [rechrome setup skill](skills/rechrome-setup/SKILL.md),
 which covers native extension installation with Computer Use and CLI connection verification.
 `rech setup` detects Codex and Claude Code environment hints and prints agent-specific guidance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.36.0",
+  "version": "1.36.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"

package/rechrome.js

@@ -828,18 +828,53 @@ const CHROME_LOCAL_STATE_PATHS = () => {
 
 type ChromeProfileInfo = { user_name?: string; name?: string };
 
+/**
+ * macOS privacy (TCC) blocks a process launched by launchd/oxmgr from Chrome's data folder unless
+ * its binary has Full Disk Access; a Terminal or agent session inherits the grant. Turn that EPERM
+ * into the fix. Undefined for any other error (or platform).
+ */
+export function chromeDataAccessHint(error: unknown, execPath = process.execPath, platform = process.platform): string | undefined {
+  const code = (error as { code?: string } | null)?.code;
+  const message = error instanceof Error ? error.message : String(error);
+  if (platform !== "darwin" || !(code === "EPERM" || code === "EACCES" || /EPERM|operation not permitted/i.test(message))) return undefined;
+  return `macOS privacy settings (TCC) block ${execPath} from reading Chrome's profile folder. ` +
+    `Grant it Full Disk Access: System Settings → Privacy & Security → Full Disk Access → +, press ⌘⇧G, paste ${execPath}, ` +
+    `then restart rech serve. Or run rech serve from Terminal, which already has access (see docs/macos-daemon.md).`;
+}
+
+/** Why the last readChromeProfileCache() returned null (undefined when it succeeded). */
+let profileCacheProblem: string | undefined;
+
 export async function readChromeProfileCache(): Promise<Record<string, ChromeProfileInfo> | null> {
+  profileCacheProblem = undefined;
+  const problems: string[] = [];
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     const f = file(statePath);
     if (!(await f.exists())) continue;
     try {
       const data = JSON.parse(await f.text());
-      return data?.profile?.info_cache ?? null;
-    } catch {}
+      if (data?.profile?.info_cache) return data.profile.info_cache;
+      problems.push(`${statePath} has no profile list`);
+    } catch (error) {
+      const hint = chromeDataAccessHint(error);
+      problems.push(`${statePath} is unreadable (${error instanceof Error ? error.message : String(error)})${hint ? `. ${hint}` : ""}`);
+    }
   }
+  profileCacheProblem = problems.join("; ") || "Chrome's Local State file was not found";
   return null;
 }
 
+/**
+ * Say so (once per process) when profile emails/names are unavailable, so a bare folder name
+ * like "Profile 1" is never mistaken for the whole story.
+ */
+let warnedProfileCache = false;
+export function warnIfProfileNamesUnavailable(cache: Record<string, ChromeProfileInfo> | null): void {
+  if (cache || warnedProfileCache) return;
+  warnedProfileCache = true;
+  console.error(`[rech] Chrome profile emails and names are unavailable (${profileCacheProblem ?? "Local State not read"}); profiles are shown by folder name only.`);
+}
+
 export function resolveChromeProfileSelector(
   profiles: Array<[string, ChromeProfileInfo]>,
   selector: string,
@@ -1307,6 +1342,7 @@ async function listRemoteProfiles(url: string): Promise<void> {
 
 async function listProfiles(): Promise<void> {
   const [cache, registry, root] = await Promise.all([readChromeProfileCache(), readTokenRegistry(), findChromeUserDataDir()]);
+  warnIfProfileNamesUnavailable(cache);
   const profiles = buildProfileRows(cache, registry, root);
   const listeners = await readListeners();
   const url = process.env[ENV_KEY];
@@ -1406,7 +1442,7 @@ export function registeredProfileChoices(registry: Record<string, TokenEntry>, c
     const info = !userDataDir || defaultDirs.includes(userDataDir) ? cache?.[dir] : undefined;
     const names = [info?.name, info?.user_name, key].filter((n): n is string => !!n && n !== dir);
     const shown = [...new Set(names)];
-    return { label: shown.length ? `${shown.join(" · ")}  [${dir}]` : dir, value: key };
+    return { label: shown.length ? `${shown.join(" · ")}  [${dir}]` : `${dir}  (no email or name known)`, value: key };
   });
 }
 
@@ -1640,6 +1676,7 @@ async function printProfileUri(selector?: string, listener?: string, opts: { loc
   const interactive = isInteractive();
   const registry = await readTokenRegistry();
   const cache = await readChromeProfileCache();
+  warnIfProfileNamesUnavailable(cache);
   const cancelled = () => new Error("Cancelled; nothing shared.");
   let config = await readListeners();
   const current = resolveEffectiveProfile(url ? parseUrl(url).profileDirectory : undefined);
@@ -1999,7 +2036,16 @@ export function unknownCommandHint(output: string, rechCommands: Iterable<string
   ].join("\n");
 }
 
-async function run(url: string, args: string[], overrideEnv?: Record<string, string>, opts: { verbatim?: boolean } = {}) {
+/**
+ * An `open` whose extension bridge never connected. Typical right after Chrome restarts: the
+ * relay's connect page reaches no live worker, yet a fresh bridge moments later connects at once
+ * (seen 2026-10-17: a timeout, then `rech setup`'s probe connected in 0.1s). Worth one retry.
+ */
+export function isBridgeTimeout(args: string[], result: { status: number; stderr?: string }): boolean {
+  return args.find(a => !a.startsWith("-")) === "open" && result.status !== 0 && /Extension connection timeout/i.test(result.stderr ?? "");
+}
+
+async function run(url: string, args: string[], overrideEnv?: Record<string, string>, opts: { verbatim?: boolean; bridgeRetried?: boolean } = {}) {
   // Match the underlying CLI's command names while accepting the short forms humans
   // naturally try. Keep this client-side so old and new serve daemons behave alike.
   args = normalizeCommandArgs(args);
@@ -2020,6 +2066,13 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
     ({ args, upload } = await prepareStdinUpload(args, process.stdin));
   }
   const { status, stdout, stderr, files, existingSession } = await callServe(url, args, overrideEnv, identity, false, upload);
+  if (!opts.bridgeRetried && isBridgeTimeout(args, { status, stderr })) {
+    // Close the failed session so the retry gets a fresh cliDaemon and relay. callServe re-reads
+    // the extension's live token from the profile, so a re-minted token heals here too.
+    console.error(`[rech] the Chrome extension bridge did not answer (common right after Chrome restarts); retrying once with a fresh connection…`);
+    await callServe(url, [...args.filter(a => /^-s=/.test(a)), "close"], overrideEnv, identity).catch(() => {});
+    return run(url, args, overrideEnv, { ...opts, bridgeRetried: true });
+  }
 
   const isOpenWithUrl = args[0] === "open" && args.length > 1;
   if (existingSession && isOpenWithUrl) {
@@ -2039,9 +2092,12 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
       // The daemon resolves registered profiles' bridge tokens itself and then asks for a reload;
       // only blame a missing install when neither side had credentials.
       const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] || /reload the .*extension/i.test(stderr);
+      const profileArg = displayProfile ? ` --profile ${JSON.stringify(displayProfile)}` : "";
       const last = hasToken
-        ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
-        : `  -> extension[not installed]  (run: rech setup)`;
+        ? `  -x: extension did not connect${opts.bridgeRetried ? " (also after an automatic retry)" : ""} -> extension[degraded]\n` +
+          `[rech] reload "Playwright MCP Bridge" at chrome://extensions${displayProfile ? ` in ${displayProfile}'s window` : ""}, then retry; ` +
+          `or run \`rech setup${profileArg}\`, which re-detects the extension and token and verifies the connection.`
+        : `  -> extension[not installed]  (run: rech setup${profileArg})`;
       console.error(`[rech] rech-client -> rech-server[ok] -> playwright[ok]\n${last}`);
     }
     if (stderr.includes("Browser '") && stderr.includes("is not open")) {
@@ -2076,6 +2132,26 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
   process.exit(status);
 }
 
+/** The daemon's Playwright CLI predates `open --wait` (rechrome <= 1.35.1 bundled one). */
+export function cliRejectsWaitOption(output: string): boolean {
+  return /Unknown options?:?[^\n]*?['"`]?--wait\b/i.test(output);
+}
+
+/**
+ * setup's bridge probe: open about:blank without waiting for a load. The daemon owns the CLI and
+ * may be older than this client, so feature-check by behavior: if the CLI rejects `--wait`, probe
+ * again without it rather than reporting a broken bridge.
+ */
+export async function probeBridgeOpen<T extends { status: number; stdout: string; stderr: string }>(
+  call: (args: string[]) => Promise<T>,
+  note: (message: string) => void = () => {},
+): Promise<T> {
+  const probe = await call(["open", "about:blank", "--wait", "none"]);
+  if (probe.status === 0 || !cliRejectsWaitOption(`${probe.stderr}\n${probe.stdout}`)) return probe;
+  note("The daemon's Playwright CLI does not support `open --wait`; probing without it (update rechrome on the daemon host).");
+  return call(["open", "about:blank"]);
+}
+
 export type SetupPhase = "extension" | "token" | "bridge" | "error" | "save" | "ready";
 
 export function createSetupGuide(extDistDir: string, profileDisplay: string) {
@@ -2536,6 +2612,7 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
     [ENV_KEY]: serveUrl,
     PWMCP_TEST_CONNECTION_TIMEOUT: process.env.PWMCP_TEST_CONNECTION_TIMEOUT || "30000",
     PLAYWRIGHT_CLI: resolvedPlaywrightCli,
+    RECH_SERVE_MANAGED: "1", // the manager restarts it; never idle-self-exit (see serve.js)
   };
   if (process.env.RECH_HOST) daemonEnv.RECH_HOST = process.env.RECH_HOST;
   if (isReadable(process.env.RECH_TLS_CERT)) daemonEnv.RECH_TLS_CERT = process.env.RECH_TLS_CERT!;
@@ -3294,7 +3371,7 @@ async function setup(opts: SetupOptions = {}): Promise<void> {
   console.log(`✓ [1/5] Local management daemon verified; requested profile access: ${desiredBind}`);
 
   const cache = await readChromeProfileCache();
-  if (!cache) { console.error("      Chrome profiles not found"); rl?.close(); process.exit(1); }
+  if (!cache) { console.error(`      Chrome profiles not found: ${profileCacheProblem ?? "Local State not read"}`); rl?.close(); process.exit(1); }
   const userDataDir = await findChromeUserDataDir();
 
   async function pickProfile(exclude: Set<string>): Promise<[string, ChromeProfileInfo] | null> {
@@ -3420,12 +3497,9 @@ async function setup(opts: SetupOptions = {}): Promise<void> {
     guide?.takeRetry();
     guide?.update("bridge", "Extension and token detected. Testing the browser connection…");
     try {
-      const probe = await callServe(
-        rechUrl.toString(),
-        [`-s=${probeSession}`, "open", "about:blank", "--wait", "none"],
-        probeEnv,
-        probeIdentity,
-        true,
+      const probe = await probeBridgeOpen(
+        args => callServe(rechUrl.toString(), [`-s=${probeSession}`, ...args], probeEnv, probeIdentity, true),
+        note => console.log(`      ${note}`),
       );
       bridgeVerified = probe.status === 0;
       if (bridgeVerified) {
@@ -3581,7 +3655,7 @@ async function status(): Promise<void> {
     ? await fetch(serviceUrl(url, "ping"), { headers: { Authorization: `Bearer ${parsed.key}` }, signal: AbortSignal.timeout(2000) }).catch(() => null)
     : null;
   const pingBody = pingResponse?.ok
-    ? await pingResponse.json().catch(() => null) as { bind?: string; listener?: string; profiles?: string[] | "*"; degraded?: boolean; consecutiveTimeouts?: number } | null
+    ? await pingResponse.json().catch(() => null) as { bind?: string; listener?: string; profiles?: string[] | "*"; degraded?: boolean; consecutiveTimeouts?: number; chromeAccessProblem?: string } | null
     : null;
   // Show the URL this client connects to; through a proxy, the daemon's bind is on another port.
   const details = [pingBody?.listener && `listener ${pingBody.listener}`, pingBody?.bind && `bind ${pingBody.bind}`].filter(Boolean).join(", ");
@@ -3602,6 +3676,8 @@ async function status(): Promise<void> {
   // No oxmgr/pm2 on PATH must not take down `rech status`: report it instead of throwing.
   let mgr: DaemonManager | undefined;
   if (isHost) try { mgr = daemonManager(); } catch { /* reported below */ }
+  if (pingBody?.chromeAccessProblem)
+    console.log(`chrome:   ⚠ daemon ${pingBody.chromeAccessProblem}`);
   if (pingBody?.degraded)
     console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; ${isHost ? `force it now with \`${mgr?.id ?? "oxmgr"} restart ${PM_PROCESS_NAME}\`` : "the daemon host can restart it"}`);
   if (isHost) {

package/rechrome.ts

@@ -828,18 +828,53 @@ const CHROME_LOCAL_STATE_PATHS = () => {
 
 type ChromeProfileInfo = { user_name?: string; name?: string };
 
+/**
+ * macOS privacy (TCC) blocks a process launched by launchd/oxmgr from Chrome's data folder unless
+ * its binary has Full Disk Access; a Terminal or agent session inherits the grant. Turn that EPERM
+ * into the fix. Undefined for any other error (or platform).
+ */
+export function chromeDataAccessHint(error: unknown, execPath = process.execPath, platform = process.platform): string | undefined {
+  const code = (error as { code?: string } | null)?.code;
+  const message = error instanceof Error ? error.message : String(error);
+  if (platform !== "darwin" || !(code === "EPERM" || code === "EACCES" || /EPERM|operation not permitted/i.test(message))) return undefined;
+  return `macOS privacy settings (TCC) block ${execPath} from reading Chrome's profile folder. ` +
+    `Grant it Full Disk Access: System Settings → Privacy & Security → Full Disk Access → +, press ⌘⇧G, paste ${execPath}, ` +
+    `then restart rech serve. Or run rech serve from Terminal, which already has access (see docs/macos-daemon.md).`;
+}
+
+/** Why the last readChromeProfileCache() returned null (undefined when it succeeded). */
+let profileCacheProblem: string | undefined;
+
 export async function readChromeProfileCache(): Promise<Record<string, ChromeProfileInfo> | null> {
+  profileCacheProblem = undefined;
+  const problems: string[] = [];
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     const f = file(statePath);
     if (!(await f.exists())) continue;
     try {
       const data = JSON.parse(await f.text());
-      return data?.profile?.info_cache ?? null;
-    } catch {}
+      if (data?.profile?.info_cache) return data.profile.info_cache;
+      problems.push(`${statePath} has no profile list`);
+    } catch (error) {
+      const hint = chromeDataAccessHint(error);
+      problems.push(`${statePath} is unreadable (${error instanceof Error ? error.message : String(error)})${hint ? `. ${hint}` : ""}`);
+    }
   }
+  profileCacheProblem = problems.join("; ") || "Chrome's Local State file was not found";
   return null;
 }
 
+/**
+ * Say so (once per process) when profile emails/names are unavailable, so a bare folder name
+ * like "Profile 1" is never mistaken for the whole story.
+ */
+let warnedProfileCache = false;
+export function warnIfProfileNamesUnavailable(cache: Record<string, ChromeProfileInfo> | null): void {
+  if (cache || warnedProfileCache) return;
+  warnedProfileCache = true;
+  console.error(`[rech] Chrome profile emails and names are unavailable (${profileCacheProblem ?? "Local State not read"}); profiles are shown by folder name only.`);
+}
+
 export function resolveChromeProfileSelector(
   profiles: Array<[string, ChromeProfileInfo]>,
   selector: string,
@@ -1307,6 +1342,7 @@ async function listRemoteProfiles(url: string): Promise<void> {
 
 async function listProfiles(): Promise<void> {
   const [cache, registry, root] = await Promise.all([readChromeProfileCache(), readTokenRegistry(), findChromeUserDataDir()]);
+  warnIfProfileNamesUnavailable(cache);
   const profiles = buildProfileRows(cache, registry, root);
   const listeners = await readListeners();
   const url = process.env[ENV_KEY];
@@ -1406,7 +1442,7 @@ export function registeredProfileChoices(registry: Record<string, TokenEntry>, c
     const info = !userDataDir || defaultDirs.includes(userDataDir) ? cache?.[dir] : undefined;
     const names = [info?.name, info?.user_name, key].filter((n): n is string => !!n && n !== dir);
     const shown = [...new Set(names)];
-    return { label: shown.length ? `${shown.join(" · ")}  [${dir}]` : dir, value: key };
+    return { label: shown.length ? `${shown.join(" · ")}  [${dir}]` : `${dir}  (no email or name known)`, value: key };
   });
 }
 
@@ -1640,6 +1676,7 @@ async function printProfileUri(selector?: string, listener?: string, opts: { loc
   const interactive = isInteractive();
   const registry = await readTokenRegistry();
   const cache = await readChromeProfileCache();
+  warnIfProfileNamesUnavailable(cache);
   const cancelled = () => new Error("Cancelled; nothing shared.");
   let config = await readListeners();
   const current = resolveEffectiveProfile(url ? parseUrl(url).profileDirectory : undefined);
@@ -1999,7 +2036,16 @@ export function unknownCommandHint(output: string, rechCommands: Iterable<string
   ].join("\n");
 }
 
-async function run(url: string, args: string[], overrideEnv?: Record<string, string>, opts: { verbatim?: boolean } = {}) {
+/**
+ * An `open` whose extension bridge never connected. Typical right after Chrome restarts: the
+ * relay's connect page reaches no live worker, yet a fresh bridge moments later connects at once
+ * (seen 2026-10-17: a timeout, then `rech setup`'s probe connected in 0.1s). Worth one retry.
+ */
+export function isBridgeTimeout(args: string[], result: { status: number; stderr?: string }): boolean {
+  return args.find(a => !a.startsWith("-")) === "open" && result.status !== 0 && /Extension connection timeout/i.test(result.stderr ?? "");
+}
+
+async function run(url: string, args: string[], overrideEnv?: Record<string, string>, opts: { verbatim?: boolean; bridgeRetried?: boolean } = {}) {
   // Match the underlying CLI's command names while accepting the short forms humans
   // naturally try. Keep this client-side so old and new serve daemons behave alike.
   args = normalizeCommandArgs(args);
@@ -2020,6 +2066,13 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
     ({ args, upload } = await prepareStdinUpload(args, process.stdin));
   }
   const { status, stdout, stderr, files, existingSession } = await callServe(url, args, overrideEnv, identity, false, upload);
+  if (!opts.bridgeRetried && isBridgeTimeout(args, { status, stderr })) {
+    // Close the failed session so the retry gets a fresh cliDaemon and relay. callServe re-reads
+    // the extension's live token from the profile, so a re-minted token heals here too.
+    console.error(`[rech] the Chrome extension bridge did not answer (common right after Chrome restarts); retrying once with a fresh connection…`);
+    await callServe(url, [...args.filter(a => /^-s=/.test(a)), "close"], overrideEnv, identity).catch(() => {});
+    return run(url, args, overrideEnv, { ...opts, bridgeRetried: true });
+  }
 
   const isOpenWithUrl = args[0] === "open" && args.length > 1;
   if (existingSession && isOpenWithUrl) {
@@ -2039,9 +2092,12 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
       // The daemon resolves registered profiles' bridge tokens itself and then asks for a reload;
       // only blame a missing install when neither side had credentials.
       const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] || /reload the .*extension/i.test(stderr);
+      const profileArg = displayProfile ? ` --profile ${JSON.stringify(displayProfile)}` : "";
       const last = hasToken
-        ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
-        : `  -> extension[not installed]  (run: rech setup)`;
+        ? `  -x: extension did not connect${opts.bridgeRetried ? " (also after an automatic retry)" : ""} -> extension[degraded]\n` +
+          `[rech] reload "Playwright MCP Bridge" at chrome://extensions${displayProfile ? ` in ${displayProfile}'s window` : ""}, then retry; ` +
+          `or run \`rech setup${profileArg}\`, which re-detects the extension and token and verifies the connection.`
+        : `  -> extension[not installed]  (run: rech setup${profileArg})`;
       console.error(`[rech] rech-client -> rech-server[ok] -> playwright[ok]\n${last}`);
     }
     if (stderr.includes("Browser '") && stderr.includes("is not open")) {
@@ -2076,6 +2132,26 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
   process.exit(status);
 }
 
+/** The daemon's Playwright CLI predates `open --wait` (rechrome <= 1.35.1 bundled one). */
+export function cliRejectsWaitOption(output: string): boolean {
+  return /Unknown options?:?[^\n]*?['"`]?--wait\b/i.test(output);
+}
+
+/**
+ * setup's bridge probe: open about:blank without waiting for a load. The daemon owns the CLI and
+ * may be older than this client, so feature-check by behavior: if the CLI rejects `--wait`, probe
+ * again without it rather than reporting a broken bridge.
+ */
+export async function probeBridgeOpen<T extends { status: number; stdout: string; stderr: string }>(
+  call: (args: string[]) => Promise<T>,
+  note: (message: string) => void = () => {},
+): Promise<T> {
+  const probe = await call(["open", "about:blank", "--wait", "none"]);
+  if (probe.status === 0 || !cliRejectsWaitOption(`${probe.stderr}\n${probe.stdout}`)) return probe;
+  note("The daemon's Playwright CLI does not support `open --wait`; probing without it (update rechrome on the daemon host).");
+  return call(["open", "about:blank"]);
+}
+
 export type SetupPhase = "extension" | "token" | "bridge" | "error" | "save" | "ready";
 
 export function createSetupGuide(extDistDir: string, profileDisplay: string) {
@@ -2536,6 +2612,7 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
     [ENV_KEY]: serveUrl,
     PWMCP_TEST_CONNECTION_TIMEOUT: process.env.PWMCP_TEST_CONNECTION_TIMEOUT || "30000",
     PLAYWRIGHT_CLI: resolvedPlaywrightCli,
+    RECH_SERVE_MANAGED: "1", // the manager restarts it; never idle-self-exit (see serve.ts)
   };
   if (process.env.RECH_HOST) daemonEnv.RECH_HOST = process.env.RECH_HOST;
   if (isReadable(process.env.RECH_TLS_CERT)) daemonEnv.RECH_TLS_CERT = process.env.RECH_TLS_CERT!;
@@ -3294,7 +3371,7 @@ async function setup(opts: SetupOptions = {}): Promise<void> {
   console.log(`✓ [1/5] Local management daemon verified; requested profile access: ${desiredBind}`);
 
   const cache = await readChromeProfileCache();
-  if (!cache) { console.error("      Chrome profiles not found"); rl?.close(); process.exit(1); }
+  if (!cache) { console.error(`      Chrome profiles not found: ${profileCacheProblem ?? "Local State not read"}`); rl?.close(); process.exit(1); }
   const userDataDir = await findChromeUserDataDir();
 
   async function pickProfile(exclude: Set<string>): Promise<[string, ChromeProfileInfo] | null> {
@@ -3420,12 +3497,9 @@ async function setup(opts: SetupOptions = {}): Promise<void> {
     guide?.takeRetry();
     guide?.update("bridge", "Extension and token detected. Testing the browser connection…");
     try {
-      const probe = await callServe(
-        rechUrl.toString(),
-        [`-s=${probeSession}`, "open", "about:blank", "--wait", "none"],
-        probeEnv,
-        probeIdentity,
-        true,
+      const probe = await probeBridgeOpen(
+        args => callServe(rechUrl.toString(), [`-s=${probeSession}`, ...args], probeEnv, probeIdentity, true),
+        note => console.log(`      ${note}`),
       );
       bridgeVerified = probe.status === 0;
       if (bridgeVerified) {
@@ -3581,7 +3655,7 @@ async function status(): Promise<void> {
     ? await fetch(serviceUrl(url, "ping"), { headers: { Authorization: `Bearer ${parsed.key}` }, signal: AbortSignal.timeout(2000) }).catch(() => null)
     : null;
   const pingBody = pingResponse?.ok
-    ? await pingResponse.json().catch(() => null) as { bind?: string; listener?: string; profiles?: string[] | "*"; degraded?: boolean; consecutiveTimeouts?: number } | null
+    ? await pingResponse.json().catch(() => null) as { bind?: string; listener?: string; profiles?: string[] | "*"; degraded?: boolean; consecutiveTimeouts?: number; chromeAccessProblem?: string } | null
     : null;
   // Show the URL this client connects to; through a proxy, the daemon's bind is on another port.
   const details = [pingBody?.listener && `listener ${pingBody.listener}`, pingBody?.bind && `bind ${pingBody.bind}`].filter(Boolean).join(", ");
@@ -3602,6 +3676,8 @@ async function status(): Promise<void> {
   // No oxmgr/pm2 on PATH must not take down `rech status`: report it instead of throwing.
   let mgr: DaemonManager | undefined;
   if (isHost) try { mgr = daemonManager(); } catch { /* reported below */ }
+  if (pingBody?.chromeAccessProblem)
+    console.log(`chrome:   ⚠ daemon ${pingBody.chromeAccessProblem}`);
   if (pingBody?.degraded)
     console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; ${isHost ? `force it now with \`${mgr?.id ?? "oxmgr"} restart ${PM_PROCESS_NAME}\`` : "the daemon host can restart it"}`);
   if (isHost) {

package/serve.js

@@ -19,6 +19,7 @@ import {
   readTokenRegistry,
   readChromeProfileCache,
   checkTailscaleServe,
+  chromeDataAccessHint,
 } from "./rechrome.js";
 
 const TAILSCALE_BIN = process.env.TAILSCALE_BIN || "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
@@ -122,6 +123,16 @@ export function provesRelayAlive(o: { stdout: string; stderr: string }): boolean
   return true;
 }
 
+/**
+ * The relay checks Chrome's data folder for the installed extension before connecting. Under
+ * macOS TCC that read fails and it reports "Playwright Extension not found" although the
+ * extension is installed — name the real cause instead of sending the user to reinstall.
+ */
+export function explainExtensionNotFound(output: string, accessProblem: string | undefined): string | undefined {
+  if (!accessProblem || !/Playwright Extension not found in/i.test(output)) return undefined;
+  return `[rech] the extension is probably installed; this daemon ${accessProblem}\n`;
+}
+
 export function inferSilentExtensionFailure(options: {
   status: number;
   stdout: string;
@@ -256,24 +267,63 @@ export function splitCommand(cmd: string): string[] {
     t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t);
 }
 
-async function resolveProfileDirectory(nameOrEmail: string): Promise<string> {
+/** Why this daemon cannot read Chrome's data folder; reported by /ping so `rech status` shows it. */
+let chromeAccessProblem: string | undefined;
+/** Log (once) why Chrome's data folder is unreadable — under launchd/oxmgr on macOS this is TCC. */
+export function warnChromeDataAccess(path: string, error: unknown): void {
+  if (chromeAccessProblem) return;
+  const message = error instanceof Error ? error.message : String(error);
+  chromeAccessProblem = `cannot read ${path} (${message}). ${chromeDataAccessHint(error) ?? "Profile names and emails cannot be resolved here."}`;
+  log(chromeAccessProblem);
+}
+
+/** A profile name or email could not be mapped to its Chrome folder because Local State is unreadable. */
+export class ProfileResolutionError extends Error {
+  constructor(readonly profile: string, statePath: string, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const hint = chromeDataAccessHint(cause);
+    super(`[rech] cannot find the Chrome folder for profile "${profile}": ${statePath} is unreadable (${message}). Refusing, so Chrome does not create a new empty profile named "${profile}".\n`
+      + `  Register it once (records its folder in ~/.rechrome): rech setup --profile ${JSON.stringify(profile)}\n`
+      + `  Or select the folder directly, e.g. rech --profile "Profile 1" …\n`
+      + (hint ? `  ${hint}\n` : ""));
+    this.name = "ProfileResolutionError";
+  }
+}
+
+export async function resolveProfileDirectory(
+  nameOrEmail: string,
+  registry?: Record<string, { profileDir?: string }>,
+  statePaths: string[] = [
+    join(HOME || "~", "Library/Application Support/Google/Chrome/Local State"),
+    join(HOME || "~", ".config/google-chrome/Local State"),
+    join(HOME || "~", "AppData/Local/Google/Chrome/User Data/Local State"),
+  ],
+): Promise<string> {
   if (/^(Default|Profile \d+)$/i.test(nameOrEmail)) return nameOrEmail;
-  const home = HOME || "~";
-  const candidates = [
-    join(home, "Library/Application Support/Google/Chrome/Local State"),
-    join(home, ".config/google-chrome/Local State"),
-    join(home, "AppData/Local/Google/Chrome/User Data/Local State"),
-  ];
-  for (const statePath of candidates) {
-    const f = file(statePath);
-    if (!(await f.exists())) continue;
-    const data = JSON.parse(await f.text());
-    const cache: Record<string, any> = data?.profile?.info_cache ?? {};
-    for (const [dir, info] of Object.entries(cache)) {
-      if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
-        return dir;
+  // setup recorded each registered profile's folder in ~/.rechrome, which macOS privacy (TCC)
+  // never guards, so a launchd/oxmgr daemon resolves it without touching Chrome's data folder.
+  const entry = (registry ?? await readTokenRegistry().catch(() => ({})) as Record<string, { profileDir?: string }>)[nameOrEmail];
+  if (entry?.profileDir) return entry.profileDir;
+  let unreadable: { path: string; error: unknown } | undefined;
+  for (const statePath of statePaths) {
+    try {
+      // Read without an exists() probe: under TCC the stat fails too, and exists() would report
+      // "missing" and hide the denial.
+      const data = JSON.parse(await file(statePath).text());
+      const cache: Record<string, any> = data?.profile?.info_cache ?? {};
+      for (const [dir, info] of Object.entries(cache)) {
+        if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
+          return dir;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") continue;
+      warnChromeDataAccess(statePath, error);
+      unreadable ??= { path: statePath, error };
     }
   }
+  // Passing an email or display name through would make Chrome create a NEW empty profile folder
+  // literally named after it (--profile-directory=me@example.com) instead of opening the real one.
+  if (unreadable) throw new ProfileResolutionError(nameOrEmail, unreadable.path, unreadable.error);
   return nameOrEmail;
 }
 
@@ -397,15 +447,34 @@ async function freeStalePort(port: number, host: string): Promise<void> {
 // the leak self-heals. /ping is deliberately NOT activity (the tray polls it every 2s
 // and would otherwise keep an orphan alive forever).
 const ORPHAN_POLL_INTERVAL_MS = 15_000;
-const ORPHAN_IDLE_EXIT_MS = Number(process.env.RECH_SERVE_IDLE_TIMEOUT_MS) || 5 * 60_000;
+const ORPHAN_IDLE_EXIT_MS = parseIdleTimeout(process.env.RECH_SERVE_IDLE_TIMEOUT_MS);
+
+// `RECH_SERVE_IDLE_TIMEOUT_MS=0` must disable self-exit; `Number(v) || default` turned 0 back into 5 min.
+export function parseIdleTimeout(raw: string | undefined, fallback = 5 * 60_000): number {
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+// A supervisor owns this serve's lifetime, so it is never a leaked foreground serve:
+// RECH_SERVE_MANAGED=1 (set by `rech setup`'s oxmgr/pm2 install), or a LaunchAgent — launchd
+// starts it with ppid 1 and its job label in XPC_SERVICE_NAME. ppid 1 alone is not enough:
+// `setsid rech serve` or `(rech serve &)` also starts with ppid 1 and must still self-exit.
+// Terminal apps set XPC_SERVICE_NAME to "0" or "application.<bundle id>…".
+export function isManagedServe(startPpid: number, env: Record<string, string | undefined> = process.env): boolean {
+  if (env.RECH_SERVE_MANAGED === "1") return true;
+  const label = env.XPC_SERVICE_NAME;
+  return startPpid === 1 && !!label && label !== "0" && !label.startsWith("application.");
+}
 
 // Pure decision predicate (testable). idleTimeoutMs <= 0 disables orphan self-exit.
 export function shouldExitOrphanedServe(opts: {
   orphaned: boolean;
   idleMs: number;
   idleTimeoutMs: number;
+  managed?: boolean;
 }): boolean {
-  return opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
+  return !opts.managed && opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
 }
 
 export const LANDING_HEADERS = {
@@ -533,14 +602,24 @@ export async function serve() {
   let orphaned = false;
   let idleSince = Date.now();
   const markActivity = () => { idleSince = Date.now(); };
+  const managed = isManagedServe(process.ppid);
+  if (managed) log("serve is supervised (launchd, a process manager, or RECH_SERVE_MANAGED=1) — idle self-exit disabled");
   setInterval(() => {
     if (process.ppid === 1) orphaned = true;
-    if (shouldExitOrphanedServe({ orphaned, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
+    if (shouldExitOrphanedServe({ orphaned, managed, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
       log(`orphaned foreground serve idle ${Math.round((Date.now() - idleSince) / 1000)}s — exiting (spawning agent is gone)`);
       process.exit(0);
     }
   }, ORPHAN_POLL_INTERVAL_MS);
 
+  // Say at startup, not on the first failed open, when macOS privacy blocks Chrome's data folder.
+  if (process.platform === "darwin") {
+    const chromeDir = join(HOME, "Library/Application Support/Google/Chrome");
+    try { readdirSync(chromeDir); } catch (error) {
+      if ((error as { code?: string }).code !== "ENOENT") warnChromeDataAccess(chromeDir, error);
+    }
+  }
+
   // Reap idle --isolate sessions so single-shot OAuth/login drives don't leak browser contexts.
   adoptOrphanedIsoSessions();
   setInterval(() => {
@@ -615,12 +694,12 @@ export async function serve() {
         // clients / `rech status` can see trouble without an active probe.
         const degraded = consecutiveTimeouts > 0;
         if (scoped || !reqUrl.searchParams.get("deep"))
-          return Response.json({ ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded });
+          return Response.json({ ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded, chromeAccessProblem });
         // Deep probe: exercise the relay read-only via `tab-list` (opens nothing) against the
         // most-recently-used session — never a fresh one, which could spawn a browser window.
         const target = [...recentSessions.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
         if (!target)
-          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded });
+          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded, chromeAccessProblem });
         const [pbin, ...pbinArgs] = splitCommand(resolvePlaywrightCli());
         const probe = Bun.spawn([pbin, ...pbinArgs, "tab-list", `-s=${target}`], {
           cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
@@ -634,7 +713,7 @@ export async function serve() {
         const healthy = probeStatus !== -1;
         return Response.json({
           ok: healthy, bind: listenHost, relay: healthy ? "healthy" : "degraded",
-          consecutiveTimeouts, degraded: degraded || !healthy,
+          consecutiveTimeouts, degraded: degraded || !healthy, chromeAccessProblem,
         });
       }
       // A browser opening a shared URL gets copyable connect instructions. The key stays in the
@@ -765,7 +844,14 @@ export async function serve() {
 
       // Resolve profile name/email → directory name
       if (!scoped && passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY) {
-        const resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        let resolved: string;
+        try {
+          resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        } catch (error) {
+          if (!(error instanceof ProfileResolutionError)) throw error;
+          log(`refused unresolvable profile "${error.profile}" (session=${namespacedSession})`);
+          return Response.json({ status: 1, stdout: "", stderr: error.message, files: [] });
+        }
         if (resolved !== passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY)
           log(`profile resolved: "${passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY}" → "${resolved}"`);
         passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY = resolved;
@@ -907,7 +993,8 @@ export async function serve() {
       const handshakeTimeoutMs = Number.isFinite(configuredHandshakeTimeout) && configuredHandshakeTimeout > 0
         ? configuredHandshakeTimeout
         : 30_000;
-      const stderr = inferSilentExtensionFailure({
+      const tccNote = explainExtensionNotFound(`${stdout}\n${rawStderr}`, chromeAccessProblem);
+      const stderr = (tccNote ?? "") + inferSilentExtensionFailure({
         status,
         stdout,
         stderr: rawStderr,

package/serve.ts

@@ -19,6 +19,7 @@ import {
   readTokenRegistry,
   readChromeProfileCache,
   checkTailscaleServe,
+  chromeDataAccessHint,
 } from "./rechrome.ts";
 
 const TAILSCALE_BIN = process.env.TAILSCALE_BIN || "/Applications/Tailscale.app/Contents/MacOS/Tailscale";
@@ -122,6 +123,16 @@ export function provesRelayAlive(o: { stdout: string; stderr: string }): boolean
   return true;
 }
 
+/**
+ * The relay checks Chrome's data folder for the installed extension before connecting. Under
+ * macOS TCC that read fails and it reports "Playwright Extension not found" although the
+ * extension is installed — name the real cause instead of sending the user to reinstall.
+ */
+export function explainExtensionNotFound(output: string, accessProblem: string | undefined): string | undefined {
+  if (!accessProblem || !/Playwright Extension not found in/i.test(output)) return undefined;
+  return `[rech] the extension is probably installed; this daemon ${accessProblem}\n`;
+}
+
 export function inferSilentExtensionFailure(options: {
   status: number;
   stdout: string;
@@ -256,24 +267,63 @@ export function splitCommand(cmd: string): string[] {
     t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t);
 }
 
-async function resolveProfileDirectory(nameOrEmail: string): Promise<string> {
+/** Why this daemon cannot read Chrome's data folder; reported by /ping so `rech status` shows it. */
+let chromeAccessProblem: string | undefined;
+/** Log (once) why Chrome's data folder is unreadable — under launchd/oxmgr on macOS this is TCC. */
+export function warnChromeDataAccess(path: string, error: unknown): void {
+  if (chromeAccessProblem) return;
+  const message = error instanceof Error ? error.message : String(error);
+  chromeAccessProblem = `cannot read ${path} (${message}). ${chromeDataAccessHint(error) ?? "Profile names and emails cannot be resolved here."}`;
+  log(chromeAccessProblem);
+}
+
+/** A profile name or email could not be mapped to its Chrome folder because Local State is unreadable. */
+export class ProfileResolutionError extends Error {
+  constructor(readonly profile: string, statePath: string, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const hint = chromeDataAccessHint(cause);
+    super(`[rech] cannot find the Chrome folder for profile "${profile}": ${statePath} is unreadable (${message}). Refusing, so Chrome does not create a new empty profile named "${profile}".\n`
+      + `  Register it once (records its folder in ~/.rechrome): rech setup --profile ${JSON.stringify(profile)}\n`
+      + `  Or select the folder directly, e.g. rech --profile "Profile 1" …\n`
+      + (hint ? `  ${hint}\n` : ""));
+    this.name = "ProfileResolutionError";
+  }
+}
+
+export async function resolveProfileDirectory(
+  nameOrEmail: string,
+  registry?: Record<string, { profileDir?: string }>,
+  statePaths: string[] = [
+    join(HOME || "~", "Library/Application Support/Google/Chrome/Local State"),
+    join(HOME || "~", ".config/google-chrome/Local State"),
+    join(HOME || "~", "AppData/Local/Google/Chrome/User Data/Local State"),
+  ],
+): Promise<string> {
   if (/^(Default|Profile \d+)$/i.test(nameOrEmail)) return nameOrEmail;
-  const home = HOME || "~";
-  const candidates = [
-    join(home, "Library/Application Support/Google/Chrome/Local State"),
-    join(home, ".config/google-chrome/Local State"),
-    join(home, "AppData/Local/Google/Chrome/User Data/Local State"),
-  ];
-  for (const statePath of candidates) {
-    const f = file(statePath);
-    if (!(await f.exists())) continue;
-    const data = JSON.parse(await f.text());
-    const cache: Record<string, any> = data?.profile?.info_cache ?? {};
-    for (const [dir, info] of Object.entries(cache)) {
-      if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
-        return dir;
+  // setup recorded each registered profile's folder in ~/.rechrome, which macOS privacy (TCC)
+  // never guards, so a launchd/oxmgr daemon resolves it without touching Chrome's data folder.
+  const entry = (registry ?? await readTokenRegistry().catch(() => ({})) as Record<string, { profileDir?: string }>)[nameOrEmail];
+  if (entry?.profileDir) return entry.profileDir;
+  let unreadable: { path: string; error: unknown } | undefined;
+  for (const statePath of statePaths) {
+    try {
+      // Read without an exists() probe: under TCC the stat fails too, and exists() would report
+      // "missing" and hide the denial.
+      const data = JSON.parse(await file(statePath).text());
+      const cache: Record<string, any> = data?.profile?.info_cache ?? {};
+      for (const [dir, info] of Object.entries(cache)) {
+        if ([info.name, info.user_name, info.gaia_name].includes(nameOrEmail))
+          return dir;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === "ENOENT") continue;
+      warnChromeDataAccess(statePath, error);
+      unreadable ??= { path: statePath, error };
     }
   }
+  // Passing an email or display name through would make Chrome create a NEW empty profile folder
+  // literally named after it (--profile-directory=me@example.com) instead of opening the real one.
+  if (unreadable) throw new ProfileResolutionError(nameOrEmail, unreadable.path, unreadable.error);
   return nameOrEmail;
 }
 
@@ -397,15 +447,34 @@ async function freeStalePort(port: number, host: string): Promise<void> {
 // the leak self-heals. /ping is deliberately NOT activity (the tray polls it every 2s
 // and would otherwise keep an orphan alive forever).
 const ORPHAN_POLL_INTERVAL_MS = 15_000;
-const ORPHAN_IDLE_EXIT_MS = Number(process.env.RECH_SERVE_IDLE_TIMEOUT_MS) || 5 * 60_000;
+const ORPHAN_IDLE_EXIT_MS = parseIdleTimeout(process.env.RECH_SERVE_IDLE_TIMEOUT_MS);
+
+// `RECH_SERVE_IDLE_TIMEOUT_MS=0` must disable self-exit; `Number(v) || default` turned 0 back into 5 min.
+export function parseIdleTimeout(raw: string | undefined, fallback = 5 * 60_000): number {
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+// A supervisor owns this serve's lifetime, so it is never a leaked foreground serve:
+// RECH_SERVE_MANAGED=1 (set by `rech setup`'s oxmgr/pm2 install), or a LaunchAgent — launchd
+// starts it with ppid 1 and its job label in XPC_SERVICE_NAME. ppid 1 alone is not enough:
+// `setsid rech serve` or `(rech serve &)` also starts with ppid 1 and must still self-exit.
+// Terminal apps set XPC_SERVICE_NAME to "0" or "application.<bundle id>…".
+export function isManagedServe(startPpid: number, env: Record<string, string | undefined> = process.env): boolean {
+  if (env.RECH_SERVE_MANAGED === "1") return true;
+  const label = env.XPC_SERVICE_NAME;
+  return startPpid === 1 && !!label && label !== "0" && !label.startsWith("application.");
+}
 
 // Pure decision predicate (testable). idleTimeoutMs <= 0 disables orphan self-exit.
 export function shouldExitOrphanedServe(opts: {
   orphaned: boolean;
   idleMs: number;
   idleTimeoutMs: number;
+  managed?: boolean;
 }): boolean {
-  return opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
+  return !opts.managed && opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
 }
 
 export const LANDING_HEADERS = {
@@ -533,14 +602,24 @@ export async function serve() {
   let orphaned = false;
   let idleSince = Date.now();
   const markActivity = () => { idleSince = Date.now(); };
+  const managed = isManagedServe(process.ppid);
+  if (managed) log("serve is supervised (launchd, a process manager, or RECH_SERVE_MANAGED=1) — idle self-exit disabled");
   setInterval(() => {
     if (process.ppid === 1) orphaned = true;
-    if (shouldExitOrphanedServe({ orphaned, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
+    if (shouldExitOrphanedServe({ orphaned, managed, idleMs: Date.now() - idleSince, idleTimeoutMs: ORPHAN_IDLE_EXIT_MS })) {
       log(`orphaned foreground serve idle ${Math.round((Date.now() - idleSince) / 1000)}s — exiting (spawning agent is gone)`);
       process.exit(0);
     }
   }, ORPHAN_POLL_INTERVAL_MS);
 
+  // Say at startup, not on the first failed open, when macOS privacy blocks Chrome's data folder.
+  if (process.platform === "darwin") {
+    const chromeDir = join(HOME, "Library/Application Support/Google/Chrome");
+    try { readdirSync(chromeDir); } catch (error) {
+      if ((error as { code?: string }).code !== "ENOENT") warnChromeDataAccess(chromeDir, error);
+    }
+  }
+
   // Reap idle --isolate sessions so single-shot OAuth/login drives don't leak browser contexts.
   adoptOrphanedIsoSessions();
   setInterval(() => {
@@ -615,12 +694,12 @@ export async function serve() {
         // clients / `rech status` can see trouble without an active probe.
         const degraded = consecutiveTimeouts > 0;
         if (scoped || !reqUrl.searchParams.get("deep"))
-          return Response.json({ ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded });
+          return Response.json({ ok: true, bind: listenHost, listener: listener.name, profiles: listener.profiles, multiListener: true, consecutiveTimeouts, degraded, chromeAccessProblem });
         // Deep probe: exercise the relay read-only via `tab-list` (opens nothing) against the
         // most-recently-used session — never a fresh one, which could spawn a browser window.
         const target = [...recentSessions.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
         if (!target)
-          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded });
+          return Response.json({ ok: true, bind: listenHost, relay: "idle", consecutiveTimeouts, degraded, chromeAccessProblem });
         const [pbin, ...pbinArgs] = splitCommand(resolvePlaywrightCli());
         const probe = Bun.spawn([pbin, ...pbinArgs, "tab-list", `-s=${target}`], {
           cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
@@ -634,7 +713,7 @@ export async function serve() {
         const healthy = probeStatus !== -1;
         return Response.json({
           ok: healthy, bind: listenHost, relay: healthy ? "healthy" : "degraded",
-          consecutiveTimeouts, degraded: degraded || !healthy,
+          consecutiveTimeouts, degraded: degraded || !healthy, chromeAccessProblem,
         });
       }
       // A browser opening a shared URL gets copyable connect instructions. The key stays in the
@@ -765,7 +844,14 @@ export async function serve() {
 
       // Resolve profile name/email → directory name
       if (!scoped && passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY) {
-        const resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        let resolved: string;
+        try {
+          resolved = await resolveProfileDirectory(passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY);
+        } catch (error) {
+          if (!(error instanceof ProfileResolutionError)) throw error;
+          log(`refused unresolvable profile "${error.profile}" (session=${namespacedSession})`);
+          return Response.json({ status: 1, stdout: "", stderr: error.message, files: [] });
+        }
         if (resolved !== passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY)
           log(`profile resolved: "${passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY}" → "${resolved}"`);
         passthroughEnv.PLAYWRIGHT_MCP_PROFILE_DIRECTORY = resolved;
@@ -907,7 +993,8 @@ export async function serve() {
       const handshakeTimeoutMs = Number.isFinite(configuredHandshakeTimeout) && configuredHandshakeTimeout > 0
         ? configuredHandshakeTimeout
         : 30_000;
-      const stderr = inferSilentExtensionFailure({
+      const tccNote = explainExtensionNotFound(`${stdout}\n${rawStderr}`, chromeAccessProblem);
+      const stderr = (tccNote ?? "") + inferSilentExtensionFailure({
         status,
         stdout,
         stderr: rawStderr,