rechrome 1.23.0 → 1.23.2

package/extension/lib/background.mjs

@@ -129,6 +129,7 @@ class RelayConnection {
     __publicField(this, "_hasEverAttached", false);
     __publicField(this, "_eventListeners", []);
     __publicField(this, "_closed", false);
+    __publicField(this, "_keepAliveInterval");
     __publicField(this, "onclose");
     __publicField(this, "ontabattached");
     __publicField(this, "ontabdetached");
@@ -143,6 +144,9 @@ class RelayConnection {
     this._installEventForwarders();
     this._ws.onmessage = this._onMessage.bind(this);
     this._ws.onclose = () => this._onClose();
+    this._keepAliveInterval = setInterval(() => {
+      this._sendMessage({ method: "extension.keepalive", params: [] });
+    }, 2e4);
   }
   get attachedTabs() {
     return this._attachedTabs;
@@ -203,6 +207,7 @@ class RelayConnection {
     if (this._closed)
       return;
     this._closed = true;
+    clearInterval(this._keepAliveInterval);
     for (const l of this._eventListeners)
       l.remove();
     this._eventListeners = [];
@@ -352,18 +357,23 @@ class PendingConnections {
   }
 }
 async function openRelayConnection(mcpRelayUrl, protocolVersion) {
+  let socket;
+  let timer;
   try {
-    const socket = new WebSocket(mcpRelayUrl);
+    socket = new WebSocket(mcpRelayUrl);
     await new Promise((resolve, reject) => {
       socket.onopen = () => resolve();
       socket.onerror = () => reject(new Error("WebSocket error"));
-      setTimeout(() => reject(new Error("Connection timeout")), 5e3);
+      timer = setTimeout(() => reject(new Error("Connection timeout")), 5e3);
     });
     return new RelayConnection(socket, protocolVersion);
   } catch (error) {
+    socket == null ? void 0 : socket.close();
     const message = `Failed to connect to MCP relay: ${error.message}`;
     debugLog(message);
     throw new Error(message);
+  } finally {
+    clearTimeout(timer);
   }
 }
 const PLAYWRIGHT_GROUP_TITLE = "pw";
@@ -595,7 +605,10 @@ class PlaywrightExtension {
   }
   async _connectTab(selectorTabId, tab, clientName) {
     try {
-      await this._cleanupPromise;
+      await Promise.race([
+        this._cleanupPromise,
+        new Promise((resolve) => setTimeout(resolve, 2e3))
+      ]);
       const connection = await this._pendingConnections.take(selectorTabId);
       if (!connection)
         throw new Error("Pending client connection closed");

package/extension/lib/ui/connect.js

@@ -1,5 +1,33 @@
 import { c as clientExports, j as jsxRuntimeExports, r as reactExports, A as AuthTokenSection, T as TabItem, B as Button, g as getOrCreateAuthToken } from "./authToken.js";
 const SUPPORTED_PROTOCOL_VERSION = 2;
+const BACKGROUND_RESPONSE_TIMEOUT_MS = 1e4;
+const SELF_RELOAD_GUARD_KEY = "connect-self-reload-at";
+const SELF_RELOAD_MIN_INTERVAL_MS = 6e4;
+function attemptExtensionSelfReload() {
+  if (new URLSearchParams(window.location.search).get("selfReload") !== "1")
+    return false;
+  const last = Number(localStorage.getItem(SELF_RELOAD_GUARD_KEY) || 0);
+  const now = Date.now();
+  if (now - last < SELF_RELOAD_MIN_INTERVAL_MS)
+    return false;
+  localStorage.setItem(SELF_RELOAD_GUARD_KEY, String(now));
+  chrome.runtime.reload();
+  return true;
+}
+async function sendMessageWithTimeout(message, simulateHang = false) {
+  let timer;
+  try {
+    return await Promise.race([
+      simulateHang ? new Promise(() => {
+      }) : chrome.runtime.sendMessage(message),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Extension service worker did not respond")), BACKGROUND_RESPONSE_TIMEOUT_MS);
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 const ConnectApp = () => {
   const [tabs, setTabs] = reactExports.useState([]);
   const [status, setStatus] = reactExports.useState(null);
@@ -13,6 +41,8 @@ const ConnectApp = () => {
     const runAsync = async () => {
       const params = new URLSearchParams(window.location.search);
       const relayUrl = params.get("mcpRelayUrl");
+      const recoveryAttempt = params.get("recoveryAttempt") === "1";
+      const hasAutomationToken = !!params.get("token");
       if (!relayUrl) {
         setError("Missing mcpRelayUrl parameter in URL.");
         return;
@@ -53,7 +83,21 @@ const ConnectApp = () => {
         });
         return;
       }
-      const response = await chrome.runtime.sendMessage({ type: "connectionRequested", mcpRelayUrl: relayUrl, protocolVersion: requestedVersion });
+      let response;
+      try {
+        response = await sendMessageWithTimeout(
+          { type: "connectionRequested", mcpRelayUrl: relayUrl, protocolVersion: requestedVersion },
+          params.get("testHangOnce") === "1" && !recoveryAttempt
+        );
+      } catch (error) {
+        if (hasAutomationToken && !recoveryAttempt) {
+          const reloading = attemptExtensionSelfReload();
+          setError(reloading ? "Extension service worker is not responding. Reloading extension and retrying…" : "Extension service worker is not responding. Retrying once…");
+          return;
+        }
+        setError(`Extension service worker did not recover: ${error.message}`);
+        return;
+      }
       if (!response.success) {
         setError(response.error);
         return;
@@ -90,7 +134,7 @@ const ConnectApp = () => {
   const handleConnectToTab = reactExports.useCallback(async (tab, clientName = clientInfo) => {
     setShowTabList(false);
     try {
-      const response = await chrome.runtime.sendMessage({
+      const response = await sendMessageWithTimeout({
         type: "connectToTab",
         tab,
         clientName
@@ -104,12 +148,19 @@ const ConnectApp = () => {
         });
       }
     } catch (e) {
+      const recoveryAttempt = new URLSearchParams(window.location.search).get("recoveryAttempt") === "1";
+      const hasAutomationToken = !!new URLSearchParams(window.location.search).get("token");
+      if (hasAutomationToken && !recoveryAttempt) {
+        const reloading = attemptExtensionSelfReload();
+        setError(reloading ? "Extension service worker stopped during connection. Reloading extension and retrying…" : "Extension service worker stopped during connection. Retrying once…");
+        return;
+      }
       setStatus({
         type: "error",
         message: `"${clientName}" failed to connect: ${e}`
       });
     }
-  }, [clientInfo]);
+  }, [clientInfo, setError]);
   reactExports.useEffect(() => {
     const listener = (message) => {
       if (message.type === "pendingConnectionClosed") {

package/extension/manifest.json

@@ -1,8 +1,9 @@
 {
   "manifest_version": 3,
   "name": "Playwright Extension",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Connect your browser to AI agents through Playwright MCP server and CLI. Enables AI-driven web testing, debugging, and automation.",
+  "minimum_chrome_version": "116",
   "permissions": [
     "debugger",
     "activeTab",

package/package.json

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

package/rech.js

@@ -351,7 +351,9 @@ const CHROME_LOCAL_STATE_PATHS = () => {
   ];
 };
 
-async function readChromeProfileCache(): Promise<Record<string, { user_name?: string; name?: string }> | null> {
+type ChromeProfileInfo = { user_name?: string; name?: string };
+
+async function readChromeProfileCache(): Promise<Record<string, ChromeProfileInfo> | null> {
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     const f = file(statePath);
     if (!(await f.exists())) continue;
@@ -363,6 +365,41 @@ async function readChromeProfileCache(): Promise<Record<string, { user_name?: st
   return null;
 }
 
+export function resolveChromeProfileSelector(
+  profiles: Array<[string, ChromeProfileInfo]>,
+  selector: string,
+): [string, ChromeProfileInfo] | null {
+  const value = selector.trim();
+  validateChromeProfileSelector(value);
+
+  const needle = value.toLowerCase();
+  const selectors: Array<{ label: string; value: (dir: string, info: ChromeProfileInfo) => string }> = [
+    { label: "email", value: (_dir, info) => info.user_name ?? "" },
+    { label: "Chrome profile name", value: (_dir, info) => info.name ?? "" },
+    { label: "profile folder name", value: (dir) => dir },
+  ];
+  for (const kind of selectors) {
+    const matches = profiles.filter(([dir, info]) => kind.value(dir, info).trim().toLowerCase() === needle);
+    if (matches.length > 1) {
+      throw new Error(
+        `--profile "${value}" matches multiple profiles by ${kind.label}. ` +
+        `Use a unique email or profile folder name from \`rech profiles\`.`,
+      );
+    }
+    if (matches.length === 1) return matches[0];
+  }
+  return null;
+}
+
+export function validateChromeProfileSelector(selector: string): void {
+  const value = selector.trim();
+  if (!/^\d+$/.test(value)) return;
+  throw new Error(
+    `--profile no longer accepts menu numbers (received "${value}"). ` +
+    `Use the profile email, Chrome profile name, or profile folder name from \`rech profiles\`.`,
+  );
+}
+
 async function findChromeUserDataDir(): Promise<string | null> {
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     if (!(await file(statePath).exists())) continue;
@@ -480,15 +517,14 @@ async function listProfiles(): Promise<void> {
     }
   }
 
-  // Header clarifies each column; email/nickname sit beside the profile dir so a bare
-  // "Profile N" is never shown alone. Only user_name (email) + name (nickname) are read
+  // Columns mirror selector precedence. Only user_name (email) + name (profile name) are read
   // from Local State — the gaia real name is deliberately never surfaced.
   const rows = [
-    ["PROFILE", "EMAIL", "NICKNAME", ""],
+    ["EMAIL", "PROFILE NAME", "FOLDER", ""],
     ...Object.entries(cache).map(([dir, info]) => [
-      dir,
       info.user_name || "",
       info.name || "",
+      dir,
       dir === currentDir ? "← current" : "",
     ]),
   ];
@@ -546,7 +582,16 @@ async function callServe(
   return res.json();
 }
 
+export function normalizeCommandArgs(args: string[]): string[] {
+  const normalized = [...args];
+  if (normalized[0] === "tabs" || normalized[0] === "list") normalized[0] = "tab-list";
+  return normalized;
+}
+
 async function run(url: string, args: string[]) {
+  // 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);
   const { host, port, protocol, extensionId, extensionToken, profileDirectory, userDataDir, loadExtension } = parseUrl(url);
   const effectiveProfile = resolveEffectiveProfile(profileDirectory);
   const displayProfile = effectiveProfile ? await resolveProfileEmail(effectiveProfile) : undefined;
@@ -570,10 +615,17 @@ async function run(url: string, args: string[]) {
     if (stderr.includes('Extension connection timeout')) {
       const hasToken = !!resolvedEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"];
       const last = hasToken
-        ? `  -x: extension token rejected -> extension[unknown]`
+        ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
         : `  -> extension[not installed]  (run: rech setup)`;
       console.error(`[rech] rech-client -> rech-server[ok] -> playwright[ok]\n${last}`);
     }
+    if (stderr.includes("Browser '") && stderr.includes("is not open")) {
+      console.error(
+        `[rech] the session id is derived from this worktree and profile; it is not a persisted stale id. ` +
+        `The preceding open did not finish. Retry \`rech open <url>\`; if it reports an extension timeout, ` +
+        `reload Playwright MCP Bridge at chrome://extensions and retry.`,
+      );
+    }
     process.stderr.write(stderr);
   }
   if (stdout) process.stdout.write(stdout);
@@ -1136,6 +1188,15 @@ async function provisionProfile(name: string, opts: { headed?: boolean } = {}):
 }
 
 async function setup(opts: { profile?: string; token?: string } = {}): Promise<void> {
+  if (opts.profile !== undefined) {
+    try {
+      validateChromeProfileSelector(opts.profile);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      envWatcher?.close();
+      process.exit(1);
+    }
+  }
   const { createInterface } = await import("readline");
   const isTTY = process.stdin.isTTY ?? false;
   let rl: ReturnType<typeof createInterface> | null = null;
@@ -1157,8 +1218,8 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     return new Promise<string>(r => rl!.question("", ans => r(ans || def)));
   };
 
-  // [1/4] Daemon
-  console.log("\n[1/4] Checking serve daemon...");
+  // [1/5] Daemon
+  console.log("\n[1/5] Checking serve daemon...");
 
   // Bind address (persists to ~/.env.local as RECH_HOST).
   // Read the persisted value from ~/.env.local directly — process.env may be shadowed by nearer .env files.
@@ -1262,40 +1323,20 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   if (!cache) { console.error("      Chrome profiles not found"); rl?.close(); process.exit(1); }
   const userDataDir = await findChromeUserDataDir();
 
-  async function pickProfile(exclude: Set<string>): Promise<[string, { user_name?: string; name?: string }] | null> {
+  async function pickProfile(exclude: Set<string>): Promise<[string, ChromeProfileInfo] | null> {
     const available = Object.entries(cache!).filter(([dir]) => !exclude.has(dir));
     if (!available.length) return null;
     available.forEach(([dir, info], i) =>
       console.log(`        ${String(i + 1).padStart(2)}.  ${(info.user_name || "(no email)").padEnd(32)}  ${(info.name || "").padEnd(20)}  [${dir}]`)
     );
     if (opts.profile !== undefined) {
-      const num = parseInt(opts.profile);
-      if (!isNaN(num) && String(num) === opts.profile.trim()) {
-        // A bare integer is a 1-based MENU INDEX, NOT the Chrome directory literally named
-        // "Profile <N>". The two collide in the user's head: `--profile 1` selects the first
-        // *listed* profile (usually Default), not the dir "Profile 1". When such a dir exists
-        // and differs from the indexed pick, warn so the mismatch is caught; echo the resolved
-        // selection either way. Email is the unambiguous selector — steer toward it.
-        const sel = available[num - 1] ?? null;
-        const dirNamed = available.find(([dir]) => dir.toLowerCase() === `profile ${num}`);
-        if (dirNamed && dirNamed[0] !== sel?.[0]) {
-          const hint = dirNamed[1].user_name || `"Profile ${num}"`;
-          console.error(
-            `      [warn] --profile ${num} = menu index ${num} → ` +
-            `${sel ? `${sel[1].user_name || sel[0]} [${sel[0]}]` : "(out of range)"}, ` +
-            `NOT the Chrome directory "Profile ${num}" (${dirNamed[1].user_name || dirNamed[0]}). ` +
-            `For an unambiguous match use the email or exact directory name, e.g. --profile ${hint}.`,
-          );
-        }
-        if (sel) console.log(`      selected: ${sel[1].user_name || "(no email)"} [${sel[0]}]`);
-        return sel;
+      let match: [string, ChromeProfileInfo] | null;
+      try {
+        match = resolveChromeProfileSelector(available, opts.profile);
+      } catch (error) {
+        console.error(`      ${error instanceof Error ? error.message : String(error)}`);
+        return null;
       }
-      const needle = opts.profile.toLowerCase();
-      const match = available.find(([dir, info]) =>
-        dir.toLowerCase() === needle
-        || (info.name ?? "").toLowerCase() === needle
-        || (info.user_name ?? "").toLowerCase().includes(needle)
-      ) ?? null;
       if (match) console.log(`      selected: ${match[1].user_name || "(no email)"} [${match[0]}]`);
       return match;
     }
@@ -1303,7 +1344,7 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
       console.log(`      Only one profile available — selecting: ${available[0][1].user_name || available[0][0]}`);
       return available[0];
     }
-    if (!isTTY) console.log("      [agent] Provide profile number on next stdin line, or rerun with --profile <num|email>");
+    if (!isTTY) console.log("      [agent] Provide profile number on next stdin line, or rerun with --profile <email|name|folder>");
     const answer = await ask("\n      Profile number: ");
     const idx = parseInt(answer.trim()) - 1;
     if (isNaN(idx) || idx < 0 || idx >= available.length) return null;
@@ -1334,7 +1375,7 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
         console.error(`\n      Non-TTY: load the extension once via chrome://extensions → "Load unpacked":`);
         console.error(`        ${EXTENSION_DIST_DIR}`);
         console.error(`      (open chrome://extensions in profile "${profileDisplay}" — see the guide just opened)`);
-        console.error(`      Then re-run:  rech setup --profile <num|email> [--token <tok>]`);
+        console.error(`      Then re-run:  rech setup --profile <email|name|folder> [--token <tok>]`);
         return null;
       }
       await ask("\n      Press Enter after loading the extension to retry...");
@@ -1420,21 +1461,22 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     return null;
   }
 
-  // [2/4] Primary profile
-  console.log("\n[2/4] Select Chrome profile:");
+  // [2/5] Primary profile
+  console.log("\n[2/5] Select Chrome profile:");
   const picked = await pickProfile(new Set());
   if (!picked) { console.error("      Invalid selection"); rl?.close(); process.exit(1); }
   const [profileDir, profileInfoSel] = picked;
   const profileDisplay = profileInfoSel.user_name || profileInfoSel.name || profileDir;
 
-  // [3+4/4] Extension + token for primary profile
-  console.log("\n[3/4] Checking extension...");
+  // [3/5] Extension + token for primary profile
+  console.log("\n[3/5] Checking extension...");
   const profileEmail = profileInfoSel.user_name || profileDir;
   const primary = await getExtAndToken(profileDir, profileDisplay, profileEmail, opts.token);
   if (!primary) { rl?.close(); process.exit(1); }
   const { extId, token } = primary;
 
-  // Build RECHROME_URL and show it before asking where to save
+  // Build RECHROME_URL, verify the selected profile can complete a real extension
+  // handshake, then show it before asking where to save.
   const rechUrl = new URL(url);
   if (!rechUrl.username) rechUrl.username = randomBytes(12).toString("base64url");
   rechUrl.searchParams.set("extension_id", extId);
@@ -1442,7 +1484,39 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   rechUrl.searchParams.set("profile", profileEmail);
   if (userDataDir) rechUrl.searchParams.set("user_data_dir", userDataDir);
   const newLine = `RECHROME_URL=${rechUrl.toString()}`;
-  console.log(`\n[4/4] Your RECHROME_URL:\n\n  ${newLine}\n`);
+  console.log(`\n[4/5] Verifying extension bridge for ${profileDisplay}...`);
+  const probeSession = `iso-setup-${randomBytes(4).toString("hex")}`;
+  const probeIdentity = await getClientIdentity();
+  probeIdentity.profile = profileEmail;
+  const probeEnv: Record<string, string> = {
+    PLAYWRIGHT_MCP_EXTENSION_ID: extId,
+    PLAYWRIGHT_MCP_EXTENSION_TOKEN: token,
+    PLAYWRIGHT_MCP_PROFILE_DIRECTORY: profileEmail,
+    ...(userDataDir ? { PLAYWRIGHT_MCP_USER_DATA_DIR: userDataDir } : {}),
+  };
+  let bridgeVerified = false;
+  try {
+    const probe = await callServe(
+      rechUrl.toString(),
+      [`-s=${probeSession}`, "open", "about:blank", "--wait", "none"],
+      probeEnv,
+      probeIdentity,
+    );
+    bridgeVerified = probe.status === 0;
+    if (bridgeVerified) {
+      console.log("      Extension bridge connected successfully");
+    } else {
+      const diagnostic = probe.stderr.trim() || probe.stdout.trim() || `bridge probe exited ${probe.status}`;
+      console.error(`      Extension bridge verification failed: ${diagnostic}`);
+    }
+  } catch (error) {
+    console.error(`      Extension bridge verification failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    // The isolated probe must never claim or close an existing worktree session.
+    await callServe(rechUrl.toString(), [`-s=${probeSession}`, "close"], probeEnv, probeIdentity).catch(() => {});
+  }
+
+  console.log(`\n[5/5] Your RECHROME_URL:\n\n  ${newLine}\n`);
   if (!isTTY) console.log(`  [agent] Provide save destination on next stdin line: 1=cwd, 2=cwd rechrome-only, 3=home, 4=skip\n`);
 
   const pwdEnvPath = join(process.cwd(), ".env.local");
@@ -1493,7 +1567,10 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   }
   rl?.close();
   envWatcher?.close();
-  console.log(`\nDone! Test with:\n  rech open github.com/snomiao`);
+  if (bridgeVerified)
+    console.log(`\nDone! Test with:\n  rech open github.com/snomiao`);
+  else
+    console.error(`\nSetup was saved, but the selected profile did not pass the bridge check. Reload the extension at chrome://extensions and run \`rech setup --profile ${profileEmail}\` again.`);
 }
 
 async function status(): Promise<void> {
@@ -1542,14 +1619,13 @@ function printHelp(): void {
   console.log(`rechrome (rech) — drive Chrome via Playwright over HTTP
 
 Usage:
-  rech setup [--profile <num|email>] [--token <tok>]
+  rech setup [--profile <email|name|folder>] [--token <tok>]
                                First-time setup: daemon + Chrome extension + config
                                --profile selects the Chrome profile non-interactively.
-                               A bare number is the 1-based MENU INDEX (position in the
-                               listed order), NOT the Chrome directory "Profile N". For
-                               scripts prefer the email (e.g. --profile you@gmail.com) —
-                               it is the only unambiguous selector; an exact directory
-                               name ("Profile 1") also matches.
+                               Menu numbers are not accepted. Resolution order is exact
+                               email (e.g. you@gmail.com), exact Chrome profile name,
+                               then exact profile folder name (e.g. "Profile 1"). See
+                               available values with \`rech profiles\`.
                                --token (or RECH_TOKEN) supplies the auth token for
                                non-TTY/agent runs, skipping the interactive paste
   rech provision-profile <name> --experimental [--headed]
@@ -1578,7 +1654,7 @@ Environment:
 
 Examples:
   rech setup
-  rech setup --profile 18 --token <PLAYWRIGHT_MCP_EXTENSION_TOKEN>
+  rech setup --profile you@gmail.com --token <PLAYWRIGHT_MCP_EXTENSION_TOKEN>
   rech eval "() => document.title"
   rech open https://example.com
   rech screenshot`);
@@ -1624,7 +1700,7 @@ if (import.meta.main) {
     if (!experimental) {
       console.error(`provision-profile is experimental and creates a Chrome-for-Testing profile (not your`);
       console.error(`real Chrome): branded Google Chrome 149+ rejects --load-extension, so a managed profile`);
-      console.error(`can't reuse your logged-in Chrome. For your real Chrome use:  rech setup --profile <N>`);
+      console.error(`can't reuse your logged-in Chrome. For your real Chrome use:  rech setup --profile <email|name|folder>`);
       console.error(`To proceed anyway, re-run with --experimental.`);
       process.exit(1);
     }

package/rech.ts

@@ -351,7 +351,9 @@ const CHROME_LOCAL_STATE_PATHS = () => {
   ];
 };
 
-async function readChromeProfileCache(): Promise<Record<string, { user_name?: string; name?: string }> | null> {
+type ChromeProfileInfo = { user_name?: string; name?: string };
+
+async function readChromeProfileCache(): Promise<Record<string, ChromeProfileInfo> | null> {
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     const f = file(statePath);
     if (!(await f.exists())) continue;
@@ -363,6 +365,41 @@ async function readChromeProfileCache(): Promise<Record<string, { user_name?: st
   return null;
 }
 
+export function resolveChromeProfileSelector(
+  profiles: Array<[string, ChromeProfileInfo]>,
+  selector: string,
+): [string, ChromeProfileInfo] | null {
+  const value = selector.trim();
+  validateChromeProfileSelector(value);
+
+  const needle = value.toLowerCase();
+  const selectors: Array<{ label: string; value: (dir: string, info: ChromeProfileInfo) => string }> = [
+    { label: "email", value: (_dir, info) => info.user_name ?? "" },
+    { label: "Chrome profile name", value: (_dir, info) => info.name ?? "" },
+    { label: "profile folder name", value: (dir) => dir },
+  ];
+  for (const kind of selectors) {
+    const matches = profiles.filter(([dir, info]) => kind.value(dir, info).trim().toLowerCase() === needle);
+    if (matches.length > 1) {
+      throw new Error(
+        `--profile "${value}" matches multiple profiles by ${kind.label}. ` +
+        `Use a unique email or profile folder name from \`rech profiles\`.`,
+      );
+    }
+    if (matches.length === 1) return matches[0];
+  }
+  return null;
+}
+
+export function validateChromeProfileSelector(selector: string): void {
+  const value = selector.trim();
+  if (!/^\d+$/.test(value)) return;
+  throw new Error(
+    `--profile no longer accepts menu numbers (received "${value}"). ` +
+    `Use the profile email, Chrome profile name, or profile folder name from \`rech profiles\`.`,
+  );
+}
+
 async function findChromeUserDataDir(): Promise<string | null> {
   for (const statePath of CHROME_LOCAL_STATE_PATHS()) {
     if (!(await file(statePath).exists())) continue;
@@ -480,15 +517,14 @@ async function listProfiles(): Promise<void> {
     }
   }
 
-  // Header clarifies each column; email/nickname sit beside the profile dir so a bare
-  // "Profile N" is never shown alone. Only user_name (email) + name (nickname) are read
+  // Columns mirror selector precedence. Only user_name (email) + name (profile name) are read
   // from Local State — the gaia real name is deliberately never surfaced.
   const rows = [
-    ["PROFILE", "EMAIL", "NICKNAME", ""],
+    ["EMAIL", "PROFILE NAME", "FOLDER", ""],
     ...Object.entries(cache).map(([dir, info]) => [
-      dir,
       info.user_name || "",
       info.name || "",
+      dir,
       dir === currentDir ? "← current" : "",
     ]),
   ];
@@ -546,7 +582,16 @@ async function callServe(
   return res.json();
 }
 
+export function normalizeCommandArgs(args: string[]): string[] {
+  const normalized = [...args];
+  if (normalized[0] === "tabs" || normalized[0] === "list") normalized[0] = "tab-list";
+  return normalized;
+}
+
 async function run(url: string, args: string[]) {
+  // 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);
   const { host, port, protocol, extensionId, extensionToken, profileDirectory, userDataDir, loadExtension } = parseUrl(url);
   const effectiveProfile = resolveEffectiveProfile(profileDirectory);
   const displayProfile = effectiveProfile ? await resolveProfileEmail(effectiveProfile) : undefined;
@@ -570,10 +615,17 @@ async function run(url: string, args: string[]) {
     if (stderr.includes('Extension connection timeout')) {
       const hasToken = !!resolvedEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"];
       const last = hasToken
-        ? `  -x: extension token rejected -> extension[unknown]`
+        ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
         : `  -> extension[not installed]  (run: rech setup)`;
       console.error(`[rech] rech-client -> rech-server[ok] -> playwright[ok]\n${last}`);
     }
+    if (stderr.includes("Browser '") && stderr.includes("is not open")) {
+      console.error(
+        `[rech] the session id is derived from this worktree and profile; it is not a persisted stale id. ` +
+        `The preceding open did not finish. Retry \`rech open <url>\`; if it reports an extension timeout, ` +
+        `reload Playwright MCP Bridge at chrome://extensions and retry.`,
+      );
+    }
     process.stderr.write(stderr);
   }
   if (stdout) process.stdout.write(stdout);
@@ -1136,6 +1188,15 @@ async function provisionProfile(name: string, opts: { headed?: boolean } = {}):
 }
 
 async function setup(opts: { profile?: string; token?: string } = {}): Promise<void> {
+  if (opts.profile !== undefined) {
+    try {
+      validateChromeProfileSelector(opts.profile);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      envWatcher?.close();
+      process.exit(1);
+    }
+  }
   const { createInterface } = await import("readline");
   const isTTY = process.stdin.isTTY ?? false;
   let rl: ReturnType<typeof createInterface> | null = null;
@@ -1157,8 +1218,8 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     return new Promise<string>(r => rl!.question("", ans => r(ans || def)));
   };
 
-  // [1/4] Daemon
-  console.log("\n[1/4] Checking serve daemon...");
+  // [1/5] Daemon
+  console.log("\n[1/5] Checking serve daemon...");
 
   // Bind address (persists to ~/.env.local as RECH_HOST).
   // Read the persisted value from ~/.env.local directly — process.env may be shadowed by nearer .env files.
@@ -1262,40 +1323,20 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   if (!cache) { console.error("      Chrome profiles not found"); rl?.close(); process.exit(1); }
   const userDataDir = await findChromeUserDataDir();
 
-  async function pickProfile(exclude: Set<string>): Promise<[string, { user_name?: string; name?: string }] | null> {
+  async function pickProfile(exclude: Set<string>): Promise<[string, ChromeProfileInfo] | null> {
     const available = Object.entries(cache!).filter(([dir]) => !exclude.has(dir));
     if (!available.length) return null;
     available.forEach(([dir, info], i) =>
       console.log(`        ${String(i + 1).padStart(2)}.  ${(info.user_name || "(no email)").padEnd(32)}  ${(info.name || "").padEnd(20)}  [${dir}]`)
     );
     if (opts.profile !== undefined) {
-      const num = parseInt(opts.profile);
-      if (!isNaN(num) && String(num) === opts.profile.trim()) {
-        // A bare integer is a 1-based MENU INDEX, NOT the Chrome directory literally named
-        // "Profile <N>". The two collide in the user's head: `--profile 1` selects the first
-        // *listed* profile (usually Default), not the dir "Profile 1". When such a dir exists
-        // and differs from the indexed pick, warn so the mismatch is caught; echo the resolved
-        // selection either way. Email is the unambiguous selector — steer toward it.
-        const sel = available[num - 1] ?? null;
-        const dirNamed = available.find(([dir]) => dir.toLowerCase() === `profile ${num}`);
-        if (dirNamed && dirNamed[0] !== sel?.[0]) {
-          const hint = dirNamed[1].user_name || `"Profile ${num}"`;
-          console.error(
-            `      [warn] --profile ${num} = menu index ${num} → ` +
-            `${sel ? `${sel[1].user_name || sel[0]} [${sel[0]}]` : "(out of range)"}, ` +
-            `NOT the Chrome directory "Profile ${num}" (${dirNamed[1].user_name || dirNamed[0]}). ` +
-            `For an unambiguous match use the email or exact directory name, e.g. --profile ${hint}.`,
-          );
-        }
-        if (sel) console.log(`      selected: ${sel[1].user_name || "(no email)"} [${sel[0]}]`);
-        return sel;
+      let match: [string, ChromeProfileInfo] | null;
+      try {
+        match = resolveChromeProfileSelector(available, opts.profile);
+      } catch (error) {
+        console.error(`      ${error instanceof Error ? error.message : String(error)}`);
+        return null;
       }
-      const needle = opts.profile.toLowerCase();
-      const match = available.find(([dir, info]) =>
-        dir.toLowerCase() === needle
-        || (info.name ?? "").toLowerCase() === needle
-        || (info.user_name ?? "").toLowerCase().includes(needle)
-      ) ?? null;
       if (match) console.log(`      selected: ${match[1].user_name || "(no email)"} [${match[0]}]`);
       return match;
     }
@@ -1303,7 +1344,7 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
       console.log(`      Only one profile available — selecting: ${available[0][1].user_name || available[0][0]}`);
       return available[0];
     }
-    if (!isTTY) console.log("      [agent] Provide profile number on next stdin line, or rerun with --profile <num|email>");
+    if (!isTTY) console.log("      [agent] Provide profile number on next stdin line, or rerun with --profile <email|name|folder>");
     const answer = await ask("\n      Profile number: ");
     const idx = parseInt(answer.trim()) - 1;
     if (isNaN(idx) || idx < 0 || idx >= available.length) return null;
@@ -1334,7 +1375,7 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
         console.error(`\n      Non-TTY: load the extension once via chrome://extensions → "Load unpacked":`);
         console.error(`        ${EXTENSION_DIST_DIR}`);
         console.error(`      (open chrome://extensions in profile "${profileDisplay}" — see the guide just opened)`);
-        console.error(`      Then re-run:  rech setup --profile <num|email> [--token <tok>]`);
+        console.error(`      Then re-run:  rech setup --profile <email|name|folder> [--token <tok>]`);
         return null;
       }
       await ask("\n      Press Enter after loading the extension to retry...");
@@ -1420,21 +1461,22 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     return null;
   }
 
-  // [2/4] Primary profile
-  console.log("\n[2/4] Select Chrome profile:");
+  // [2/5] Primary profile
+  console.log("\n[2/5] Select Chrome profile:");
   const picked = await pickProfile(new Set());
   if (!picked) { console.error("      Invalid selection"); rl?.close(); process.exit(1); }
   const [profileDir, profileInfoSel] = picked;
   const profileDisplay = profileInfoSel.user_name || profileInfoSel.name || profileDir;
 
-  // [3+4/4] Extension + token for primary profile
-  console.log("\n[3/4] Checking extension...");
+  // [3/5] Extension + token for primary profile
+  console.log("\n[3/5] Checking extension...");
   const profileEmail = profileInfoSel.user_name || profileDir;
   const primary = await getExtAndToken(profileDir, profileDisplay, profileEmail, opts.token);
   if (!primary) { rl?.close(); process.exit(1); }
   const { extId, token } = primary;
 
-  // Build RECHROME_URL and show it before asking where to save
+  // Build RECHROME_URL, verify the selected profile can complete a real extension
+  // handshake, then show it before asking where to save.
   const rechUrl = new URL(url);
   if (!rechUrl.username) rechUrl.username = randomBytes(12).toString("base64url");
   rechUrl.searchParams.set("extension_id", extId);
@@ -1442,7 +1484,39 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   rechUrl.searchParams.set("profile", profileEmail);
   if (userDataDir) rechUrl.searchParams.set("user_data_dir", userDataDir);
   const newLine = `RECHROME_URL=${rechUrl.toString()}`;
-  console.log(`\n[4/4] Your RECHROME_URL:\n\n  ${newLine}\n`);
+  console.log(`\n[4/5] Verifying extension bridge for ${profileDisplay}...`);
+  const probeSession = `iso-setup-${randomBytes(4).toString("hex")}`;
+  const probeIdentity = await getClientIdentity();
+  probeIdentity.profile = profileEmail;
+  const probeEnv: Record<string, string> = {
+    PLAYWRIGHT_MCP_EXTENSION_ID: extId,
+    PLAYWRIGHT_MCP_EXTENSION_TOKEN: token,
+    PLAYWRIGHT_MCP_PROFILE_DIRECTORY: profileEmail,
+    ...(userDataDir ? { PLAYWRIGHT_MCP_USER_DATA_DIR: userDataDir } : {}),
+  };
+  let bridgeVerified = false;
+  try {
+    const probe = await callServe(
+      rechUrl.toString(),
+      [`-s=${probeSession}`, "open", "about:blank", "--wait", "none"],
+      probeEnv,
+      probeIdentity,
+    );
+    bridgeVerified = probe.status === 0;
+    if (bridgeVerified) {
+      console.log("      Extension bridge connected successfully");
+    } else {
+      const diagnostic = probe.stderr.trim() || probe.stdout.trim() || `bridge probe exited ${probe.status}`;
+      console.error(`      Extension bridge verification failed: ${diagnostic}`);
+    }
+  } catch (error) {
+    console.error(`      Extension bridge verification failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    // The isolated probe must never claim or close an existing worktree session.
+    await callServe(rechUrl.toString(), [`-s=${probeSession}`, "close"], probeEnv, probeIdentity).catch(() => {});
+  }
+
+  console.log(`\n[5/5] Your RECHROME_URL:\n\n  ${newLine}\n`);
   if (!isTTY) console.log(`  [agent] Provide save destination on next stdin line: 1=cwd, 2=cwd rechrome-only, 3=home, 4=skip\n`);
 
   const pwdEnvPath = join(process.cwd(), ".env.local");
@@ -1493,7 +1567,10 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
   }
   rl?.close();
   envWatcher?.close();
-  console.log(`\nDone! Test with:\n  rech open github.com/snomiao`);
+  if (bridgeVerified)
+    console.log(`\nDone! Test with:\n  rech open github.com/snomiao`);
+  else
+    console.error(`\nSetup was saved, but the selected profile did not pass the bridge check. Reload the extension at chrome://extensions and run \`rech setup --profile ${profileEmail}\` again.`);
 }
 
 async function status(): Promise<void> {
@@ -1542,14 +1619,13 @@ function printHelp(): void {
   console.log(`rechrome (rech) — drive Chrome via Playwright over HTTP
 
 Usage:
-  rech setup [--profile <num|email>] [--token <tok>]
+  rech setup [--profile <email|name|folder>] [--token <tok>]
                                First-time setup: daemon + Chrome extension + config
                                --profile selects the Chrome profile non-interactively.
-                               A bare number is the 1-based MENU INDEX (position in the
-                               listed order), NOT the Chrome directory "Profile N". For
-                               scripts prefer the email (e.g. --profile you@gmail.com) —
-                               it is the only unambiguous selector; an exact directory
-                               name ("Profile 1") also matches.
+                               Menu numbers are not accepted. Resolution order is exact
+                               email (e.g. you@gmail.com), exact Chrome profile name,
+                               then exact profile folder name (e.g. "Profile 1"). See
+                               available values with \`rech profiles\`.
                                --token (or RECH_TOKEN) supplies the auth token for
                                non-TTY/agent runs, skipping the interactive paste
   rech provision-profile <name> --experimental [--headed]
@@ -1578,7 +1654,7 @@ Environment:
 
 Examples:
   rech setup
-  rech setup --profile 18 --token <PLAYWRIGHT_MCP_EXTENSION_TOKEN>
+  rech setup --profile you@gmail.com --token <PLAYWRIGHT_MCP_EXTENSION_TOKEN>
   rech eval "() => document.title"
   rech open https://example.com
   rech screenshot`);
@@ -1624,7 +1700,7 @@ if (import.meta.main) {
     if (!experimental) {
       console.error(`provision-profile is experimental and creates a Chrome-for-Testing profile (not your`);
       console.error(`real Chrome): branded Google Chrome 149+ rejects --load-extension, so a managed profile`);
-      console.error(`can't reuse your logged-in Chrome. For your real Chrome use:  rech setup --profile <N>`);
+      console.error(`can't reuse your logged-in Chrome. For your real Chrome use:  rech setup --profile <email|name|folder>`);
       console.error(`To proceed anyway, re-run with --experimental.`);
       process.exit(1);
     }

package/serve.js

@@ -84,6 +84,23 @@ function noteSession(sess: string, now: number): void {
   }
 }
 
+export function inferSilentExtensionFailure(options: {
+  status: number;
+  stdout: string;
+  stderr: string;
+  isOpenCommand: boolean;
+  hasExtensionCredentials: boolean;
+  elapsedMs: number;
+  handshakeTimeoutMs: number;
+}): string {
+  const { status, stdout, stderr, isOpenCommand, hasExtensionCredentials, elapsedMs, handshakeTimeoutMs } = options;
+  if (stderr || status === 0 || stdout.trim() || !isOpenCommand || !hasExtensionCredentials)
+    return stderr;
+  if (elapsedMs < Math.max(1_000, handshakeTimeoutMs - 1_000))
+    return stderr;
+  return `Extension connection timeout after ${handshakeTimeoutMs}ms. Automatic recovery retry failed; reload the Playwright MCP Bridge extension at chrome://extensions and retry.\n`;
+}
+
 function tmpSocketRoot(): string {
   return `${(process.env.TMPDIR || "/tmp").replace(/\/$/, "")}/playwright-cli`;
 }
@@ -478,6 +495,7 @@ export async function serve() {
         } catch {}
       }
 
+      const commandStartedAt = Date.now();
       const proc = Bun.spawn([bin, ...binArgs, ...filteredArgs, `-s=${namespacedSession}`], {
         cwd: workDir,
         stdin: "ignore",
@@ -497,7 +515,7 @@ export async function serve() {
           reject(new Error("timeout"));
         }, TIMEOUT);
       });
-      const [status, stdout, stderr] = await Promise.race([
+      const [status, stdout, rawStderr] = await Promise.race([
         Promise.all([
           proc.exited,
           new Response(proc.stdout).text(),
@@ -509,6 +527,20 @@ export async function serve() {
       ) as [number, string, string];
       clearTimeout(timer);
 
+      const configuredHandshakeTimeout = Number(childEnv.PWMCP_TEST_CONNECTION_TIMEOUT);
+      const handshakeTimeoutMs = Number.isFinite(configuredHandshakeTimeout) && configuredHandshakeTimeout > 0
+        ? configuredHandshakeTimeout
+        : 30_000;
+      const stderr = inferSilentExtensionFailure({
+        status,
+        stdout,
+        stderr: rawStderr,
+        isOpenCommand: isOpenCmd,
+        hasExtensionCredentials: !!(passthroughEnv.PLAYWRIGHT_MCP_EXTENSION_ID && passthroughEnv.PLAYWRIGHT_MCP_EXTENSION_TOKEN),
+        elapsedMs: Date.now() - commandStartedAt,
+        handshakeTimeoutMs,
+      });
+
       log(`exit: ${status}${stdout.trim() ? ` | ${stdout.trim().slice(0, 200)}` : ""}`);
 
       // Relay self-heal (see notes at SESSION_CLOSE_TIMEOUTS): a command that RETURNS — even

package/serve.ts

@@ -84,6 +84,23 @@ function noteSession(sess: string, now: number): void {
   }
 }
 
+export function inferSilentExtensionFailure(options: {
+  status: number;
+  stdout: string;
+  stderr: string;
+  isOpenCommand: boolean;
+  hasExtensionCredentials: boolean;
+  elapsedMs: number;
+  handshakeTimeoutMs: number;
+}): string {
+  const { status, stdout, stderr, isOpenCommand, hasExtensionCredentials, elapsedMs, handshakeTimeoutMs } = options;
+  if (stderr || status === 0 || stdout.trim() || !isOpenCommand || !hasExtensionCredentials)
+    return stderr;
+  if (elapsedMs < Math.max(1_000, handshakeTimeoutMs - 1_000))
+    return stderr;
+  return `Extension connection timeout after ${handshakeTimeoutMs}ms. Automatic recovery retry failed; reload the Playwright MCP Bridge extension at chrome://extensions and retry.\n`;
+}
+
 function tmpSocketRoot(): string {
   return `${(process.env.TMPDIR || "/tmp").replace(/\/$/, "")}/playwright-cli`;
 }
@@ -478,6 +495,7 @@ export async function serve() {
         } catch {}
       }
 
+      const commandStartedAt = Date.now();
       const proc = Bun.spawn([bin, ...binArgs, ...filteredArgs, `-s=${namespacedSession}`], {
         cwd: workDir,
         stdin: "ignore",
@@ -497,7 +515,7 @@ export async function serve() {
           reject(new Error("timeout"));
         }, TIMEOUT);
       });
-      const [status, stdout, stderr] = await Promise.race([
+      const [status, stdout, rawStderr] = await Promise.race([
         Promise.all([
           proc.exited,
           new Response(proc.stdout).text(),
@@ -509,6 +527,20 @@ export async function serve() {
       ) as [number, string, string];
       clearTimeout(timer);
 
+      const configuredHandshakeTimeout = Number(childEnv.PWMCP_TEST_CONNECTION_TIMEOUT);
+      const handshakeTimeoutMs = Number.isFinite(configuredHandshakeTimeout) && configuredHandshakeTimeout > 0
+        ? configuredHandshakeTimeout
+        : 30_000;
+      const stderr = inferSilentExtensionFailure({
+        status,
+        stdout,
+        stderr: rawStderr,
+        isOpenCommand: isOpenCmd,
+        hasExtensionCredentials: !!(passthroughEnv.PLAYWRIGHT_MCP_EXTENSION_ID && passthroughEnv.PLAYWRIGHT_MCP_EXTENSION_TOKEN),
+        elapsedMs: Date.now() - commandStartedAt,
+        handshakeTimeoutMs,
+      });
+
       log(`exit: ${status}${stdout.trim() ? ` | ${stdout.trim().slice(0, 200)}` : ""}`);
 
       // Relay self-heal (see notes at SESSION_CLOSE_TIMEOUTS): a command that RETURNS — even