rechrome 1.21.0 → 1.23.0

package/package.json

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

package/rech.js

@@ -6,6 +6,7 @@ import { mkdirSync, appendFileSync, existsSync, realpathSync, accessSync, cpSync
 import { hostname, homedir } from "os";
 import { join, basename, dirname } from "path";
 import { spawn as cpSpawn } from "child_process";
+import { pickDaemonManager, type DaemonManager } from "./daemon-manager.js";
 
 export const ENV_KEY = "RECHROME_URL";
 export const DEFAULT_PORT = 13775;
@@ -104,7 +105,7 @@ function openInDefaultApp(target: string): void {
   const cmd = process.platform === "darwin" ? ["open", target]
     : process.platform === "win32" ? ["cmd", "/c", "start", "", target]
     : ["xdg-open", target];
-  try { Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" }); } catch {}
+  try { Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore", windowsHide: true }); } catch {}
 }
 
 // Best-effort path to the Chrome executable for the current platform (used to open a
@@ -137,7 +138,7 @@ function openInChromeProfile(profileDir: string, target: string): boolean {
   try {
     Bun.spawn(
       [chromeBin, `--profile-directory=${profileDir}`, target],
-      { stdout: "ignore", stderr: "ignore", detached: true },
+      { stdout: "ignore", stderr: "ignore", detached: true, windowsHide: true },
     );
     return true;
   } catch {
@@ -200,7 +201,8 @@ function realpathSafe(p: string): string {
 
 async function gitOutput(args: string[], cwd: string): Promise<string | null> {
   try {
-    const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+    // windowsHide: don't flash a console window on Windows (git.exe is a console app)
+    const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore", windowsHide: true });
     const out = (await new Response(proc.stdout).text()).trim();
     await proc.exited;
     return out || null;
@@ -478,12 +480,18 @@ async function listProfiles(): Promise<void> {
     }
   }
 
-  const rows = Object.entries(cache).map(([dir, info]) => [
-    dir,
-    info.user_name || "",
-    info.name || "",
-    dir === currentDir ? "← current" : "",
-  ]);
+  // 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
+  // from Local State — the gaia real name is deliberately never surfaced.
+  const rows = [
+    ["PROFILE", "EMAIL", "NICKNAME", ""],
+    ...Object.entries(cache).map(([dir, info]) => [
+      dir,
+      info.user_name || "",
+      info.name || "",
+      dir === currentDir ? "← current" : "",
+    ]),
+  ];
   const widths = rows.reduce((w, r) => r.map((c, i) => Math.max(w[i] ?? 0, c.length)), [] as number[]);
   for (const row of rows) {
     console.log(row.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd());
@@ -494,9 +502,13 @@ async function callServe(
   url: string,
   args: string[],
   overrideEnv?: Record<string, string>,
+  precomputedIdentity?: { key: string; label: string; profile?: string },
 ): Promise<{ status: number; stdout: string; stderr: string; files?: string[]; existingSession?: boolean }> {
   const { key, host, port, protocol, extensionId, extensionToken, profileDirectory, userDataDir, loadExtension } = parseUrl(url);
-  const identity = await getClientIdentity();
+  // Reuse the caller's identity when provided — computing it shells out to `git` several times,
+  // and run() has already done so for its log line. Recomputing here would double those git
+  // spawns (and, on Windows, the console-window flashes) on every `rech open`.
+  const identity = precomputedIdentity ?? await getClientIdentity();
   const effectiveProfile = resolveEffectiveProfile(profileDirectory);
   if (effectiveProfile) identity.profile = effectiveProfile;
   const env = { ...(await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir, loadExtension })), ...overrideEnv };
@@ -545,7 +557,7 @@ async function run(url: string, args: string[]) {
   );
 
   const resolvedEnv = await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir, loadExtension });
-  const { status, stdout, stderr, files, existingSession } = await callServe(url, args);
+  const { status, stdout, stderr, files, existingSession } = await callServe(url, args, undefined, identity);
 
   const isOpenWithUrl = args[0] === "open" && args.length > 1;
   if (existingSession && isOpenWithUrl) {
@@ -647,27 +659,80 @@ const PM_PROCESS_NAME = "rechrome";
 // Pre-rename names to evict on (re)install/uninstall so a single `rech setup`
 // migrates an existing checkout cleanly.
 const LEGACY_PROCESS_NAMES = ["rechrome-serve"];
-// oxmgr everywhere, but it's unstable on Windows — fall back to pm2 there.
 const IS_WINDOWS = process.platform === "win32";
-const PM_BIN = IS_WINDOWS ? "pm2" : "oxmgr";
 
-// Spawn the active process manager. `env` is merged over process.env for the
-// child: pm2 captures the CLI's environment for the managed process (it has no
-// per-var flag like oxmgr's --env), so install passes daemon env this way.
-async function runPm(args: string[], env?: Record<string, string>): Promise<number> {
-  const proc = Bun.spawn(["bunx", PM_BIN, ...args], {
+// Read the installed oxmgr's version (e.g. "0.4.0+winfix"), or null if oxmgr
+// isn't on PATH / doesn't answer. Cached — daemonManager() sits on the hot path
+// of several subcommands (status, setup, install). Synchronous by design so the
+// selection has no await threading through call sites.
+let _oxmgrVersion: string | null | undefined;
+function oxmgrVersion(bin: string): string | null {
+  if (_oxmgrVersion !== undefined) return _oxmgrVersion;
+  try {
+    const p = Bun.spawnSync([bin, "--version"], { stdout: "pipe", stderr: "ignore", windowsHide: true });
+    const m = /(\d+\.\d+\.\d+[^\s]*)/.exec(p.stdout?.toString() ?? "");
+    _oxmgrVersion = m ? m[1]! : null;
+  } catch {
+    _oxmgrVersion = null;
+  }
+  return _oxmgrVersion;
+}
+
+// Resolve (and cache) the process manager that daemonizes `rech serve`. The
+// selection policy — oxmgr default, pm2 fallback, winfix-guarded on Windows,
+// RECH_DAEMON_MANAGER override — lives in ./daemon-manager.js (pure + tested);
+// here we just supply the runtime inputs (what's on PATH, the oxmgr version).
+let _daemonMgr: DaemonManager | undefined;
+function daemonManager(): DaemonManager {
+  if (_daemonMgr) return _daemonMgr;
+  const oxmgrBin = Bun.which("oxmgr");
+  const pm2Bin = Bun.which("pm2");
+  _daemonMgr = pickDaemonManager({
+    oxmgrBin,
+    pm2Bin,
+    oxmgrVersion: oxmgrBin ? oxmgrVersion(oxmgrBin) : null,
+    isWindows: IS_WINDOWS,
+    override: process.env.RECH_DAEMON_MANAGER,
+  });
+  return _daemonMgr;
+}
+
+// Spawn the resolved process manager by its absolute path (Bun.which). `env` is
+// merged over process.env for the child: pm2 captures the CLI's environment for
+// the managed process (it has no per-var flag like oxmgr's --env), so install
+// passes daemon env this way.
+async function runPm(mgr: DaemonManager, args: string[], env?: Record<string, string>): Promise<number> {
+  const proc = Bun.spawn([mgr.bin, ...args], {
     stdout: "inherit",
     stderr: "inherit",
+    windowsHide: true, // no console-window flash for the manager child on Windows
     ...(env ? { env: { ...process.env, ...env } } : {}),
   });
   await proc.exited;
   return proc.exitCode ?? 1;
 }
 
+// oxmgr boot/login autostart. `service install` wires the platform init
+// integration (Windows Task Scheduler, macOS launchd, or a systemd --user unit)
+// so the daemon — and the managed serve with it — returns at login/boot, the way
+// the pm2 path relied on `pm2 resurrect`. Skipped when already installed:
+// re-running `service install` re-bootstraps the oxmgr daemon, which restarts
+// every managed process (including the live serve). Best-effort — a failure
+// leaves serve crash-managed but not login-persistent.
+async function oxmgrEnsureAutostart(mgr: DaemonManager): Promise<void> {
+  let alreadyInstalled = false;
+  try {
+    alreadyInstalled =
+      Bun.spawnSync([mgr.bin, "service", "status"], { stdout: "ignore", stderr: "ignore", windowsHide: true }).exitCode === 0;
+  } catch { /* treat a probe failure as not-installed and attempt install */ }
+  if (alreadyInstalled) return;
+  await runPm(mgr, ["service", "install"]);
+}
+
 // Capture the process-manager's process list as text (oxmgr `list` / pm2 `jlist`).
 // Both render the process name verbatim, so callers can substring-match it.
-async function pmList(): Promise<string> {
-  const proc = Bun.spawn(["bunx", PM_BIN, IS_WINDOWS ? "jlist" : "list"], { stdout: "pipe", stderr: "ignore" });
+async function pmList(mgr: DaemonManager = daemonManager()): Promise<string> {
+  const proc = Bun.spawn([mgr.bin, mgr.id === "pm2" ? "jlist" : "list"], { stdout: "pipe", stderr: "ignore", windowsHide: true });
   return await new Response(proc.stdout).text();
 }
 
@@ -729,25 +794,27 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
   if (isReadable(process.env.RECH_TLS_CERT)) daemonEnv.RECH_TLS_CERT = process.env.RECH_TLS_CERT!;
   if (isReadable(process.env.RECH_TLS_KEY)) daemonEnv.RECH_TLS_KEY = process.env.RECH_TLS_KEY!;
 
+  const mgr = daemonManager();
+
   // Drop any prior registration (current + legacy names) before re-adding.
-  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(["delete", name]);
+  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
 
   let startCode: number;
-  if (IS_WINDOWS) {
+  if (mgr.id === "pm2") {
     // pm2 captures the CLI env (passed via runPm's env) for the managed process,
     // autorestarts by default, and runs the bun binary directly with
     // `--interpreter none` (so it isn't fed to node).
-    startCode = await runPm([
+    startCode = await runPm(mgr, [
       "start", bunBin,
       "--name", PM_PROCESS_NAME,
       "--interpreter", "none",
       "--cwd", home,
       "--", rechScript, "serve",
     ], daemonEnv);
-    await runPm(["save"]); // persist process list for `pm2 resurrect` on reboot
+    await runPm(mgr, ["save"]); // persist process list for `pm2 resurrect` on reboot
   } else {
     const envArgs = Object.entries(daemonEnv).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
-    startCode = await runPm([
+    startCode = await runPm(mgr, [
       "start",
       "--name", PM_PROCESS_NAME,
       "--restart", "always",
@@ -755,18 +822,23 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
       ...envArgs,
       `${bunBin} ${rechScript} serve`,
     ]);
-    await runPm(["service", "install"]);
+    // Boot/login persistence: on Windows the winfix oxmgr wires Task Scheduler,
+    // on POSIX a systemd --user unit / launchd agent — the equivalent of the pm2
+    // path's `pm2 resurrect` at login. Guarded so a re-install doesn't bounce the
+    // live daemon.
+    await oxmgrEnsureAutostart(mgr);
   }
   // Surface a failed start instead of reporting a daemon that was never registered.
   if (startCode !== 0)
-    throw new Error(`${PM_BIN} failed to start "${PM_PROCESS_NAME}" (exit ${startCode}). Check that ${PM_BIN} is installed and on PATH.`);
+    throw new Error(`${mgr.id} failed to start "${PM_PROCESS_NAME}" (exit ${startCode}). Check that ${mgr.id} is installed and on PATH.`);
 }
 
 async function daemonUninstall(): Promise<void> {
-  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(["delete", name]);
-  if (IS_WINDOWS) await runPm(["save"]);
-  else await runPm(["service", "uninstall"]);
-  console.log(`Removed ${PM_BIN} process: ${PM_PROCESS_NAME}`);
+  const mgr = daemonManager();
+  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
+  if (mgr.id === "pm2") await runPm(mgr, ["save"]);
+  else await runPm(mgr, ["service", "uninstall"]);
+  console.log(`Removed ${mgr.id} process: ${PM_PROCESS_NAME}`);
 }
 
 // ── Native tray (menu-bar / system-tray) icon ───────────────────────────────
@@ -983,7 +1055,7 @@ async function provisionExtensionToken(opts: {
   if (!opts.headed) args.push("--headless=new");
   if (process.platform === "linux") args.push("--no-sandbox");
   args.push("about:blank");
-  const proc = Bun.spawn([chromeBin, ...args], { stdout: "ignore", stderr: "ignore" });
+  const proc = Bun.spawn([chromeBin, ...args], { stdout: "ignore", stderr: "ignore", windowsHide: true });
   let cdp: CDPClient | null = null;
   try {
     // Chrome writes the chosen port to DevToolsActivePort once the debug server is up.
@@ -1198,13 +1270,34 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     );
     if (opts.profile !== undefined) {
       const num = parseInt(opts.profile);
-      if (!isNaN(num) && String(num) === opts.profile.trim()) return available[num - 1] ?? null;
+      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;
+      }
       const needle = opts.profile.toLowerCase();
-      return available.find(([dir, info]) =>
+      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;
     }
     if (available.length === 1) {
       console.log(`      Only one profile available — selecting: ${available[0][1].user_name || available[0][0]}`);
@@ -1414,17 +1507,20 @@ async function status(): Promise<void> {
   const ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
   // Resolve the daemon's actual bind from its authenticated /ping (cross-platform; lsof is
   // POSIX-only and absent on Windows). bind is "0.0.0.0" (all interfaces) or the loopback IP.
-  const bind = ping
+  const pingBody = ping
     ? await fetch(`${protocol}://${host}:${port}/ping`, {
         headers: { Authorization: `Bearer ${parsed.key}` },
         signal: AbortSignal.timeout(2000),
-      }).then(r => (r.ok ? r.json() : null)).then((b: { bind?: string } | null) => b?.bind).catch(() => undefined)
-    : undefined;
+      }).then(r => (r.ok ? r.json() : null)).catch(() => null) as { bind?: string; degraded?: boolean; consecutiveTimeouts?: number } | null
+    : null;
+  const bind = pingBody?.bind;
   const listenAddr = bind ? `${bind}:${port}` : `${host}:${port}`;
   console.log(`serve:    ${ping ? `running  ${protocol}://${listenAddr}` : "not running"}`);
+  if (pingBody?.degraded)
+    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; force it now with \`${PM_BIN} restart ${PM_PROCESS_NAME}\``);
   const pmOut = await pmList();
   const daemonRegistered = pmOut.includes(PM_PROCESS_NAME);
-  console.log(`daemon:   ${daemonRegistered ? `${PM_BIN} (${PM_PROCESS_NAME})` : "not installed"}`);
+  console.log(`daemon:   ${daemonRegistered ? `${daemonManager().id} (${PM_PROCESS_NAME})` : "not installed"}`);
   const registry = await readTokenRegistry();
   const entries = Object.entries(registry);
   if (entries.length) {
@@ -1448,7 +1544,12 @@ function printHelp(): void {
 Usage:
   rech setup [--profile <num|email>] [--token <tok>]
                                First-time setup: daemon + Chrome extension + config
-                               --profile selects the Chrome profile non-interactively
+                               --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.
                                --token (or RECH_TOKEN) supplies the auth token for
                                non-TTY/agent runs, skipping the interactive paste
   rech provision-profile <name> --experimental [--headed]

package/rech.ts

@@ -6,6 +6,7 @@ import { mkdirSync, appendFileSync, existsSync, realpathSync, accessSync, cpSync
 import { hostname, homedir } from "os";
 import { join, basename, dirname } from "path";
 import { spawn as cpSpawn } from "child_process";
+import { pickDaemonManager, type DaemonManager } from "./daemon-manager.ts";
 
 export const ENV_KEY = "RECHROME_URL";
 export const DEFAULT_PORT = 13775;
@@ -104,7 +105,7 @@ function openInDefaultApp(target: string): void {
   const cmd = process.platform === "darwin" ? ["open", target]
     : process.platform === "win32" ? ["cmd", "/c", "start", "", target]
     : ["xdg-open", target];
-  try { Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" }); } catch {}
+  try { Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore", windowsHide: true }); } catch {}
 }
 
 // Best-effort path to the Chrome executable for the current platform (used to open a
@@ -137,7 +138,7 @@ function openInChromeProfile(profileDir: string, target: string): boolean {
   try {
     Bun.spawn(
       [chromeBin, `--profile-directory=${profileDir}`, target],
-      { stdout: "ignore", stderr: "ignore", detached: true },
+      { stdout: "ignore", stderr: "ignore", detached: true, windowsHide: true },
     );
     return true;
   } catch {
@@ -200,7 +201,8 @@ function realpathSafe(p: string): string {
 
 async function gitOutput(args: string[], cwd: string): Promise<string | null> {
   try {
-    const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
+    // windowsHide: don't flash a console window on Windows (git.exe is a console app)
+    const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore", windowsHide: true });
     const out = (await new Response(proc.stdout).text()).trim();
     await proc.exited;
     return out || null;
@@ -478,12 +480,18 @@ async function listProfiles(): Promise<void> {
     }
   }
 
-  const rows = Object.entries(cache).map(([dir, info]) => [
-    dir,
-    info.user_name || "",
-    info.name || "",
-    dir === currentDir ? "← current" : "",
-  ]);
+  // 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
+  // from Local State — the gaia real name is deliberately never surfaced.
+  const rows = [
+    ["PROFILE", "EMAIL", "NICKNAME", ""],
+    ...Object.entries(cache).map(([dir, info]) => [
+      dir,
+      info.user_name || "",
+      info.name || "",
+      dir === currentDir ? "← current" : "",
+    ]),
+  ];
   const widths = rows.reduce((w, r) => r.map((c, i) => Math.max(w[i] ?? 0, c.length)), [] as number[]);
   for (const row of rows) {
     console.log(row.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd());
@@ -494,9 +502,13 @@ async function callServe(
   url: string,
   args: string[],
   overrideEnv?: Record<string, string>,
+  precomputedIdentity?: { key: string; label: string; profile?: string },
 ): Promise<{ status: number; stdout: string; stderr: string; files?: string[]; existingSession?: boolean }> {
   const { key, host, port, protocol, extensionId, extensionToken, profileDirectory, userDataDir, loadExtension } = parseUrl(url);
-  const identity = await getClientIdentity();
+  // Reuse the caller's identity when provided — computing it shells out to `git` several times,
+  // and run() has already done so for its log line. Recomputing here would double those git
+  // spawns (and, on Windows, the console-window flashes) on every `rech open`.
+  const identity = precomputedIdentity ?? await getClientIdentity();
   const effectiveProfile = resolveEffectiveProfile(profileDirectory);
   if (effectiveProfile) identity.profile = effectiveProfile;
   const env = { ...(await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir, loadExtension })), ...overrideEnv };
@@ -545,7 +557,7 @@ async function run(url: string, args: string[]) {
   );
 
   const resolvedEnv = await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir, loadExtension });
-  const { status, stdout, stderr, files, existingSession } = await callServe(url, args);
+  const { status, stdout, stderr, files, existingSession } = await callServe(url, args, undefined, identity);
 
   const isOpenWithUrl = args[0] === "open" && args.length > 1;
   if (existingSession && isOpenWithUrl) {
@@ -647,27 +659,80 @@ const PM_PROCESS_NAME = "rechrome";
 // Pre-rename names to evict on (re)install/uninstall so a single `rech setup`
 // migrates an existing checkout cleanly.
 const LEGACY_PROCESS_NAMES = ["rechrome-serve"];
-// oxmgr everywhere, but it's unstable on Windows — fall back to pm2 there.
 const IS_WINDOWS = process.platform === "win32";
-const PM_BIN = IS_WINDOWS ? "pm2" : "oxmgr";
 
-// Spawn the active process manager. `env` is merged over process.env for the
-// child: pm2 captures the CLI's environment for the managed process (it has no
-// per-var flag like oxmgr's --env), so install passes daemon env this way.
-async function runPm(args: string[], env?: Record<string, string>): Promise<number> {
-  const proc = Bun.spawn(["bunx", PM_BIN, ...args], {
+// Read the installed oxmgr's version (e.g. "0.4.0+winfix"), or null if oxmgr
+// isn't on PATH / doesn't answer. Cached — daemonManager() sits on the hot path
+// of several subcommands (status, setup, install). Synchronous by design so the
+// selection has no await threading through call sites.
+let _oxmgrVersion: string | null | undefined;
+function oxmgrVersion(bin: string): string | null {
+  if (_oxmgrVersion !== undefined) return _oxmgrVersion;
+  try {
+    const p = Bun.spawnSync([bin, "--version"], { stdout: "pipe", stderr: "ignore", windowsHide: true });
+    const m = /(\d+\.\d+\.\d+[^\s]*)/.exec(p.stdout?.toString() ?? "");
+    _oxmgrVersion = m ? m[1]! : null;
+  } catch {
+    _oxmgrVersion = null;
+  }
+  return _oxmgrVersion;
+}
+
+// Resolve (and cache) the process manager that daemonizes `rech serve`. The
+// selection policy — oxmgr default, pm2 fallback, winfix-guarded on Windows,
+// RECH_DAEMON_MANAGER override — lives in ./daemon-manager.ts (pure + tested);
+// here we just supply the runtime inputs (what's on PATH, the oxmgr version).
+let _daemonMgr: DaemonManager | undefined;
+function daemonManager(): DaemonManager {
+  if (_daemonMgr) return _daemonMgr;
+  const oxmgrBin = Bun.which("oxmgr");
+  const pm2Bin = Bun.which("pm2");
+  _daemonMgr = pickDaemonManager({
+    oxmgrBin,
+    pm2Bin,
+    oxmgrVersion: oxmgrBin ? oxmgrVersion(oxmgrBin) : null,
+    isWindows: IS_WINDOWS,
+    override: process.env.RECH_DAEMON_MANAGER,
+  });
+  return _daemonMgr;
+}
+
+// Spawn the resolved process manager by its absolute path (Bun.which). `env` is
+// merged over process.env for the child: pm2 captures the CLI's environment for
+// the managed process (it has no per-var flag like oxmgr's --env), so install
+// passes daemon env this way.
+async function runPm(mgr: DaemonManager, args: string[], env?: Record<string, string>): Promise<number> {
+  const proc = Bun.spawn([mgr.bin, ...args], {
     stdout: "inherit",
     stderr: "inherit",
+    windowsHide: true, // no console-window flash for the manager child on Windows
     ...(env ? { env: { ...process.env, ...env } } : {}),
   });
   await proc.exited;
   return proc.exitCode ?? 1;
 }
 
+// oxmgr boot/login autostart. `service install` wires the platform init
+// integration (Windows Task Scheduler, macOS launchd, or a systemd --user unit)
+// so the daemon — and the managed serve with it — returns at login/boot, the way
+// the pm2 path relied on `pm2 resurrect`. Skipped when already installed:
+// re-running `service install` re-bootstraps the oxmgr daemon, which restarts
+// every managed process (including the live serve). Best-effort — a failure
+// leaves serve crash-managed but not login-persistent.
+async function oxmgrEnsureAutostart(mgr: DaemonManager): Promise<void> {
+  let alreadyInstalled = false;
+  try {
+    alreadyInstalled =
+      Bun.spawnSync([mgr.bin, "service", "status"], { stdout: "ignore", stderr: "ignore", windowsHide: true }).exitCode === 0;
+  } catch { /* treat a probe failure as not-installed and attempt install */ }
+  if (alreadyInstalled) return;
+  await runPm(mgr, ["service", "install"]);
+}
+
 // Capture the process-manager's process list as text (oxmgr `list` / pm2 `jlist`).
 // Both render the process name verbatim, so callers can substring-match it.
-async function pmList(): Promise<string> {
-  const proc = Bun.spawn(["bunx", PM_BIN, IS_WINDOWS ? "jlist" : "list"], { stdout: "pipe", stderr: "ignore" });
+async function pmList(mgr: DaemonManager = daemonManager()): Promise<string> {
+  const proc = Bun.spawn([mgr.bin, mgr.id === "pm2" ? "jlist" : "list"], { stdout: "pipe", stderr: "ignore", windowsHide: true });
   return await new Response(proc.stdout).text();
 }
 
@@ -729,25 +794,27 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
   if (isReadable(process.env.RECH_TLS_CERT)) daemonEnv.RECH_TLS_CERT = process.env.RECH_TLS_CERT!;
   if (isReadable(process.env.RECH_TLS_KEY)) daemonEnv.RECH_TLS_KEY = process.env.RECH_TLS_KEY!;
 
+  const mgr = daemonManager();
+
   // Drop any prior registration (current + legacy names) before re-adding.
-  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(["delete", name]);
+  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
 
   let startCode: number;
-  if (IS_WINDOWS) {
+  if (mgr.id === "pm2") {
     // pm2 captures the CLI env (passed via runPm's env) for the managed process,
     // autorestarts by default, and runs the bun binary directly with
     // `--interpreter none` (so it isn't fed to node).
-    startCode = await runPm([
+    startCode = await runPm(mgr, [
       "start", bunBin,
       "--name", PM_PROCESS_NAME,
       "--interpreter", "none",
       "--cwd", home,
       "--", rechScript, "serve",
     ], daemonEnv);
-    await runPm(["save"]); // persist process list for `pm2 resurrect` on reboot
+    await runPm(mgr, ["save"]); // persist process list for `pm2 resurrect` on reboot
   } else {
     const envArgs = Object.entries(daemonEnv).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
-    startCode = await runPm([
+    startCode = await runPm(mgr, [
       "start",
       "--name", PM_PROCESS_NAME,
       "--restart", "always",
@@ -755,18 +822,23 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
       ...envArgs,
       `${bunBin} ${rechScript} serve`,
     ]);
-    await runPm(["service", "install"]);
+    // Boot/login persistence: on Windows the winfix oxmgr wires Task Scheduler,
+    // on POSIX a systemd --user unit / launchd agent — the equivalent of the pm2
+    // path's `pm2 resurrect` at login. Guarded so a re-install doesn't bounce the
+    // live daemon.
+    await oxmgrEnsureAutostart(mgr);
   }
   // Surface a failed start instead of reporting a daemon that was never registered.
   if (startCode !== 0)
-    throw new Error(`${PM_BIN} failed to start "${PM_PROCESS_NAME}" (exit ${startCode}). Check that ${PM_BIN} is installed and on PATH.`);
+    throw new Error(`${mgr.id} failed to start "${PM_PROCESS_NAME}" (exit ${startCode}). Check that ${mgr.id} is installed and on PATH.`);
 }
 
 async function daemonUninstall(): Promise<void> {
-  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(["delete", name]);
-  if (IS_WINDOWS) await runPm(["save"]);
-  else await runPm(["service", "uninstall"]);
-  console.log(`Removed ${PM_BIN} process: ${PM_PROCESS_NAME}`);
+  const mgr = daemonManager();
+  for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
+  if (mgr.id === "pm2") await runPm(mgr, ["save"]);
+  else await runPm(mgr, ["service", "uninstall"]);
+  console.log(`Removed ${mgr.id} process: ${PM_PROCESS_NAME}`);
 }
 
 // ── Native tray (menu-bar / system-tray) icon ───────────────────────────────
@@ -983,7 +1055,7 @@ async function provisionExtensionToken(opts: {
   if (!opts.headed) args.push("--headless=new");
   if (process.platform === "linux") args.push("--no-sandbox");
   args.push("about:blank");
-  const proc = Bun.spawn([chromeBin, ...args], { stdout: "ignore", stderr: "ignore" });
+  const proc = Bun.spawn([chromeBin, ...args], { stdout: "ignore", stderr: "ignore", windowsHide: true });
   let cdp: CDPClient | null = null;
   try {
     // Chrome writes the chosen port to DevToolsActivePort once the debug server is up.
@@ -1198,13 +1270,34 @@ async function setup(opts: { profile?: string; token?: string } = {}): Promise<v
     );
     if (opts.profile !== undefined) {
       const num = parseInt(opts.profile);
-      if (!isNaN(num) && String(num) === opts.profile.trim()) return available[num - 1] ?? null;
+      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;
+      }
       const needle = opts.profile.toLowerCase();
-      return available.find(([dir, info]) =>
+      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;
     }
     if (available.length === 1) {
       console.log(`      Only one profile available — selecting: ${available[0][1].user_name || available[0][0]}`);
@@ -1414,17 +1507,20 @@ async function status(): Promise<void> {
   const ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
   // Resolve the daemon's actual bind from its authenticated /ping (cross-platform; lsof is
   // POSIX-only and absent on Windows). bind is "0.0.0.0" (all interfaces) or the loopback IP.
-  const bind = ping
+  const pingBody = ping
     ? await fetch(`${protocol}://${host}:${port}/ping`, {
         headers: { Authorization: `Bearer ${parsed.key}` },
         signal: AbortSignal.timeout(2000),
-      }).then(r => (r.ok ? r.json() : null)).then((b: { bind?: string } | null) => b?.bind).catch(() => undefined)
-    : undefined;
+      }).then(r => (r.ok ? r.json() : null)).catch(() => null) as { bind?: string; degraded?: boolean; consecutiveTimeouts?: number } | null
+    : null;
+  const bind = pingBody?.bind;
   const listenAddr = bind ? `${bind}:${port}` : `${host}:${port}`;
   console.log(`serve:    ${ping ? `running  ${protocol}://${listenAddr}` : "not running"}`);
+  if (pingBody?.degraded)
+    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; force it now with \`${PM_BIN} restart ${PM_PROCESS_NAME}\``);
   const pmOut = await pmList();
   const daemonRegistered = pmOut.includes(PM_PROCESS_NAME);
-  console.log(`daemon:   ${daemonRegistered ? `${PM_BIN} (${PM_PROCESS_NAME})` : "not installed"}`);
+  console.log(`daemon:   ${daemonRegistered ? `${daemonManager().id} (${PM_PROCESS_NAME})` : "not installed"}`);
   const registry = await readTokenRegistry();
   const entries = Object.entries(registry);
   if (entries.length) {
@@ -1448,7 +1544,12 @@ function printHelp(): void {
 Usage:
   rech setup [--profile <num|email>] [--token <tok>]
                                First-time setup: daemon + Chrome extension + config
-                               --profile selects the Chrome profile non-interactively
+                               --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.
                                --token (or RECH_TOKEN) supplies the auth token for
                                non-TTY/agent runs, skipping the interactive paste
   rech provision-profile <name> --experimental [--headed]

package/serve.js

@@ -55,6 +55,35 @@ export function isIsoSession(namespacedSession: string): boolean {
   return /(?:^|-)iso-[0-9a-f]+$/.test(namespacedSession);
 }
 
+// --- Relay health / self-heal ---------------------------------------------------------
+// The daemon spawns a short-lived CLI child per command, but all commands share a long-lived
+// per-session cliDaemon and a single extension↔relay path. Under sustained multi-session load
+// the relay can wedge: navigations (`open`) hang to the 60s cap while cheap calls still return,
+// and — critically — the wedge PERSISTS (every later command reuses the same broken cliDaemon),
+// so historically only a manual `oxmgr restart rechrome` cleared it. We heal automatically on
+// two layers, driven by real command timeouts (no synthetic probe → Chrome is never touched):
+//   - per-session: after SESSION_CLOSE_TIMEOUTS consecutive timeouts on ONE session, run the
+//     CLI `close` for it so the next command respawns a clean cliDaemon.
+//   - global: after WATCHDOG_TIMEOUTS consecutive timeouts across ALL sessions with no success
+//     in between (= the shared relay is dead), exit(1); oxmgr's `--restart always` respawns us
+//     clean and the extension WS reconnects. Each timeout burns 60s of wall time, so this can't
+//     spin faster than ~once/minute even under concurrent load.
+const SESSION_CLOSE_TIMEOUTS = Number(process.env.RECH_SESSION_CLOSE_TIMEOUTS) || 2;
+const WATCHDOG_TIMEOUTS = Number(process.env.RECH_WATCHDOG_TIMEOUTS) || 3;
+let consecutiveTimeouts = 0;                       // global; reset on any non-timeout /run
+const sessionTimeouts = new Map<string, number>(); // per-session consecutive-timeout streak
+// Most-recently-used non-iso sessions, so the deep health probe can target something real
+// instead of spawning a fresh session (which could open a browser window).
+const recentSessions = new Map<string, number>();
+function noteSession(sess: string, now: number): void {
+  recentSessions.set(sess, now);
+  if (recentSessions.size > 64) {
+    let oldestKey: string | undefined, oldestAt = Infinity;
+    for (const [k, t] of recentSessions) if (t < oldestAt) { oldestAt = t; oldestKey = k; }
+    if (oldestKey) recentSessions.delete(oldestKey);
+  }
+}
+
 function tmpSocketRoot(): string {
   return `${(process.env.TMPDIR || "/tmp").replace(/\/$/, "")}/playwright-cli`;
 }
@@ -92,6 +121,7 @@ function reapIdleIsoSessions(bin: string, binArgs: string[], workDir: string): v
         stdin: "ignore",
         stdout: "ignore",
         stderr: "ignore",
+        windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
         env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
       });
       log(`reaped idle isolated session (idle ${Math.round((now - last) / 1000)}s): ${sess}`);
@@ -112,7 +142,7 @@ async function renewCertIfNeeded(certPath: string, keyPath: string): Promise<boo
     if (!domain) { log("TLS cert renewal: could not determine domain"); return false; }
     log(`TLS cert expires in ${Math.floor(daysLeft)} days, renewing ${domain}...`);
     const proc = Bun.spawn([TAILSCALE_BIN, "cert", "--cert-file", certPath, "--key-file", keyPath, domain], {
-      stdout: "pipe", stderr: "pipe",
+      stdout: "pipe", stderr: "pipe", windowsHide: true,
     });
     const [status, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
     if (status !== 0) { log(`TLS cert renewal failed: ${stderr.trim()}`); return false; }
@@ -189,7 +219,7 @@ async function freeStalePort(port: number): Promise<void> {
         "  $h | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
         "}",
       ].join(" ");
-      const r = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps]);
+      const r = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true });
       const out = r.stdout?.toString().trim();
       if (out) log(out);
     } else {
@@ -228,9 +258,13 @@ export async function serve() {
     }, 86_400_000);
   }
   const tls = certPath && keyPath ? { cert: Bun.file(certPath), key: Bun.file(keyPath) } : undefined;
-  const startServer = () => Bun.serve({
+  const startServer = (reusePort = false) => Bun.serve({
     hostname: listenHost,
     port,
+    // reusePort is used only as a last-resort fallback (see the bind loop below): if an orphaned
+    // holder can't be killed, binding with SO_REUSEADDR keeps serve up (degraded, port-shared)
+    // instead of crash-looping on EADDRINUSE. The normal path binds a clean, exclusive socket.
+    reusePort,
     tls,
     error(err) {
       log(`unhandled error: ${err.message}`);
@@ -254,7 +288,32 @@ export async function serve() {
       if (reqUrl.pathname === "/ping") {
         const denied = authCheck(req, key);
         if (denied) return denied;
-        return Response.json({ ok: true, bind: listenHost });
+        // Shallow ping proves only that the HTTP listener is up (it stayed up through past
+        // relay wedges). `degraded` surfaces the passive timeout streak from real traffic so
+        // clients / `rech status` can see trouble without an active probe.
+        const degraded = consecutiveTimeouts > 0;
+        if (!reqUrl.searchParams.get("deep"))
+          return Response.json({ ok: true, bind: listenHost, consecutiveTimeouts, degraded });
+        // 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 });
+        const [pbin, ...pbinArgs] = splitCommand(resolvePlaywrightCli());
+        const probe = Bun.spawn([pbin, ...pbinArgs, "tab-list", `-s=${target}`], {
+          cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
+          windowsHide: true,
+          env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
+        });
+        const probeStatus = await Promise.race([
+          probe.exited,
+          new Promise<number>((r) => setTimeout(() => { probe.kill(); r(-1); }, 5000)),
+        ]);
+        const healthy = probeStatus !== -1;
+        return Response.json({
+          ok: healthy, bind: listenHost, relay: healthy ? "healthy" : "degraded",
+          consecutiveTimeouts, degraded: degraded || !healthy,
+        });
       }
       if (reqUrl.pathname !== "/run") return new Response("rech server\n");
       const denied = authCheck(req, key);
@@ -312,7 +371,9 @@ export async function serve() {
       });
       const namespacedSession = clientSession ? `${sessionId}-${clientSession}` : sessionId;
       // Track --isolate sessions so the idle-TTL reaper can close them later.
-      if (isIsoSession(namespacedSession)) isoLastUsed.set(namespacedSession, Date.now());
+      const nowMs = Date.now();
+      if (isIsoSession(namespacedSession)) isoLastUsed.set(namespacedSession, nowMs);
+      else noteSession(namespacedSession, nowMs); // for the deep health probe to target
 
       // daemonInstall bakes PLAYWRIGHT_CLI into the daemon env; resolvePlaywrightCli() is the
       // fallback for a standalone `serve` (it re-runs the same env > fork > @playwright/cli > legacy chain).
@@ -339,6 +400,7 @@ export async function serve() {
             stdin: "ignore",
             stdout: "pipe",
             stderr: "pipe",
+            windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
             env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
           });
           const [listStatus, listOut] = await Promise.race([
@@ -421,16 +483,20 @@ export async function serve() {
         stdin: "ignore",
         stdout: "pipe",
         stderr: "pipe",
+        windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
         env: childEnv,
       });
 
       const TIMEOUT = 60_000;
-      const timeout = new Promise<never>((_, reject) =>
-        setTimeout(() => {
+      let timedOut = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          timedOut = true;
           proc.kill();
           reject(new Error("timeout"));
-        }, TIMEOUT),
-      );
+        }, TIMEOUT);
+      });
       const [status, stdout, stderr] = await Promise.race([
         Promise.all([
           proc.exited,
@@ -441,9 +507,37 @@ export async function serve() {
       ]).catch(
         () => [1, "", `Command timed out after ${TIMEOUT / 1000}s\n`] as [number, string, string],
       ) as [number, string, string];
+      clearTimeout(timer);
 
       log(`exit: ${status}${stdout.trim() ? ` | ${stdout.trim().slice(0, 200)}` : ""}`);
 
+      // Relay self-heal (see notes at SESSION_CLOSE_TIMEOUTS): a command that RETURNS — even
+      // non-zero — proves the relay answered, so clear the streaks; a TIMEOUT means it didn't.
+      if (timedOut) {
+        consecutiveTimeouts++;
+        const streak = (sessionTimeouts.get(namespacedSession) ?? 0) + 1;
+        sessionTimeouts.set(namespacedSession, streak);
+        log(`timeout: session=${namespacedSession} sessionStreak=${streak} globalStreak=${consecutiveTimeouts}`);
+        if (streak >= SESSION_CLOSE_TIMEOUTS) {
+          log(`session ${namespacedSession} wedged (${streak} consecutive timeouts) — closing so the next command respawns a clean cliDaemon`);
+          try {
+            Bun.spawn([bin, ...binArgs, "close", `-s=${namespacedSession}`], {
+              cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
+              windowsHide: true,
+              env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
+            });
+          } catch {}
+          sessionTimeouts.delete(namespacedSession);
+        }
+        if (consecutiveTimeouts >= WATCHDOG_TIMEOUTS) {
+          log(`relay wedged: ${consecutiveTimeouts} consecutive timeouts, no success between — exiting for oxmgr (--restart always) to respawn clean; extension WS will reconnect (Chrome untouched)`);
+          setTimeout(() => process.exit(1), 100); // brief delay to flush this response
+        }
+      } else {
+        consecutiveTimeouts = 0;
+        sessionTimeouts.delete(namespacedSession);
+      }
+
       // Detect files mentioned in output
       const filePattern = /[\w./-]+\.(?:png|jpe?g|pdf|json|yml)\b/gi;
       const mentionedFiles = [
@@ -482,17 +576,34 @@ export async function serve() {
     },
   });
 
-  // A leaked listening-socket handle in an orphaned cliDaemon can keep the port held after a
-  // prior serve exits; on EADDRINUSE, clear stale holders once and retry rather than crash-loop.
-  let server: ReturnType<typeof startServer>;
-  try {
-    server = startServer();
-  } catch (e: any) {
-    if (!String(e?.code ?? e?.message ?? "").includes("EADDRINUSE")) throw e;
-    log(`port ${port} in use — clearing stale daemon holders and retrying`);
-    await freeStalePort(port);
-    server = startServer();
+  // A leaked listening-socket handle in an orphaned cliDaemon can keep the port in LISTEN after a
+  // prior serve exits: Bun.serve creates the socket inheritable and Bun.spawn sweeps it into the
+  // detached daemon grandchild via bInheritHandles, so the socket outlives its creating serve.
+  // netstat then attributes the port to the now-dead *creator*, not the live holder, so we can't
+  // map port -> killable PID — freeStalePort kills the orphan by its cliDaemon signature instead.
+  // Retry a bounded number of times: the old single retry crash-looped whenever the OS hadn't yet
+  // released the socket after the kill (pm2 then restarts serve into the same race). As an absolute
+  // last resort, bind with reusePort so a holder we genuinely can't kill degrades to "up but sharing
+  // the port" rather than a permanent EADDRINUSE crash-loop.
+  const isEaddrInUse = (e: any) => String(e?.code ?? e?.message ?? "").includes("EADDRINUSE");
+  const MAX_BIND_ATTEMPTS = 4;
+  let server: ReturnType<typeof startServer> | undefined;
+  for (let attempt = 1; attempt <= MAX_BIND_ATTEMPTS; attempt++) {
+    try {
+      server = startServer();
+      break;
+    } catch (e: any) {
+      if (!isEaddrInUse(e)) throw e;
+      if (attempt === MAX_BIND_ATTEMPTS) {
+        log(`port ${port} still held after ${attempt - 1} cleanup attempts — binding with reusePort (last resort)`);
+        server = startServer(true);
+        break;
+      }
+      log(`port ${port} in use — clearing stale daemon holders and retrying (attempt ${attempt}/${MAX_BIND_ATTEMPTS - 1})`);
+      await freeStalePort(port);
+    }
   }
+  if (!server) throw new Error(`failed to bind port ${port}`);
 
   log(`serving on ${tls ? "https" : "http"}://${server.hostname}:${server.port}`);
   log(`Connection URL set (use .env.local to view)`);

package/serve.ts

@@ -55,6 +55,35 @@ export function isIsoSession(namespacedSession: string): boolean {
   return /(?:^|-)iso-[0-9a-f]+$/.test(namespacedSession);
 }
 
+// --- Relay health / self-heal ---------------------------------------------------------
+// The daemon spawns a short-lived CLI child per command, but all commands share a long-lived
+// per-session cliDaemon and a single extension↔relay path. Under sustained multi-session load
+// the relay can wedge: navigations (`open`) hang to the 60s cap while cheap calls still return,
+// and — critically — the wedge PERSISTS (every later command reuses the same broken cliDaemon),
+// so historically only a manual `oxmgr restart rechrome` cleared it. We heal automatically on
+// two layers, driven by real command timeouts (no synthetic probe → Chrome is never touched):
+//   - per-session: after SESSION_CLOSE_TIMEOUTS consecutive timeouts on ONE session, run the
+//     CLI `close` for it so the next command respawns a clean cliDaemon.
+//   - global: after WATCHDOG_TIMEOUTS consecutive timeouts across ALL sessions with no success
+//     in between (= the shared relay is dead), exit(1); oxmgr's `--restart always` respawns us
+//     clean and the extension WS reconnects. Each timeout burns 60s of wall time, so this can't
+//     spin faster than ~once/minute even under concurrent load.
+const SESSION_CLOSE_TIMEOUTS = Number(process.env.RECH_SESSION_CLOSE_TIMEOUTS) || 2;
+const WATCHDOG_TIMEOUTS = Number(process.env.RECH_WATCHDOG_TIMEOUTS) || 3;
+let consecutiveTimeouts = 0;                       // global; reset on any non-timeout /run
+const sessionTimeouts = new Map<string, number>(); // per-session consecutive-timeout streak
+// Most-recently-used non-iso sessions, so the deep health probe can target something real
+// instead of spawning a fresh session (which could open a browser window).
+const recentSessions = new Map<string, number>();
+function noteSession(sess: string, now: number): void {
+  recentSessions.set(sess, now);
+  if (recentSessions.size > 64) {
+    let oldestKey: string | undefined, oldestAt = Infinity;
+    for (const [k, t] of recentSessions) if (t < oldestAt) { oldestAt = t; oldestKey = k; }
+    if (oldestKey) recentSessions.delete(oldestKey);
+  }
+}
+
 function tmpSocketRoot(): string {
   return `${(process.env.TMPDIR || "/tmp").replace(/\/$/, "")}/playwright-cli`;
 }
@@ -92,6 +121,7 @@ function reapIdleIsoSessions(bin: string, binArgs: string[], workDir: string): v
         stdin: "ignore",
         stdout: "ignore",
         stderr: "ignore",
+        windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
         env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
       });
       log(`reaped idle isolated session (idle ${Math.round((now - last) / 1000)}s): ${sess}`);
@@ -112,7 +142,7 @@ async function renewCertIfNeeded(certPath: string, keyPath: string): Promise<boo
     if (!domain) { log("TLS cert renewal: could not determine domain"); return false; }
     log(`TLS cert expires in ${Math.floor(daysLeft)} days, renewing ${domain}...`);
     const proc = Bun.spawn([TAILSCALE_BIN, "cert", "--cert-file", certPath, "--key-file", keyPath, domain], {
-      stdout: "pipe", stderr: "pipe",
+      stdout: "pipe", stderr: "pipe", windowsHide: true,
     });
     const [status, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
     if (status !== 0) { log(`TLS cert renewal failed: ${stderr.trim()}`); return false; }
@@ -189,7 +219,7 @@ async function freeStalePort(port: number): Promise<void> {
         "  $h | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
         "}",
       ].join(" ");
-      const r = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps]);
+      const r = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true });
       const out = r.stdout?.toString().trim();
       if (out) log(out);
     } else {
@@ -228,9 +258,13 @@ export async function serve() {
     }, 86_400_000);
   }
   const tls = certPath && keyPath ? { cert: Bun.file(certPath), key: Bun.file(keyPath) } : undefined;
-  const startServer = () => Bun.serve({
+  const startServer = (reusePort = false) => Bun.serve({
     hostname: listenHost,
     port,
+    // reusePort is used only as a last-resort fallback (see the bind loop below): if an orphaned
+    // holder can't be killed, binding with SO_REUSEADDR keeps serve up (degraded, port-shared)
+    // instead of crash-looping on EADDRINUSE. The normal path binds a clean, exclusive socket.
+    reusePort,
     tls,
     error(err) {
       log(`unhandled error: ${err.message}`);
@@ -254,7 +288,32 @@ export async function serve() {
       if (reqUrl.pathname === "/ping") {
         const denied = authCheck(req, key);
         if (denied) return denied;
-        return Response.json({ ok: true, bind: listenHost });
+        // Shallow ping proves only that the HTTP listener is up (it stayed up through past
+        // relay wedges). `degraded` surfaces the passive timeout streak from real traffic so
+        // clients / `rech status` can see trouble without an active probe.
+        const degraded = consecutiveTimeouts > 0;
+        if (!reqUrl.searchParams.get("deep"))
+          return Response.json({ ok: true, bind: listenHost, consecutiveTimeouts, degraded });
+        // 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 });
+        const [pbin, ...pbinArgs] = splitCommand(resolvePlaywrightCli());
+        const probe = Bun.spawn([pbin, ...pbinArgs, "tab-list", `-s=${target}`], {
+          cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
+          windowsHide: true,
+          env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
+        });
+        const probeStatus = await Promise.race([
+          probe.exited,
+          new Promise<number>((r) => setTimeout(() => { probe.kill(); r(-1); }, 5000)),
+        ]);
+        const healthy = probeStatus !== -1;
+        return Response.json({
+          ok: healthy, bind: listenHost, relay: healthy ? "healthy" : "degraded",
+          consecutiveTimeouts, degraded: degraded || !healthy,
+        });
       }
       if (reqUrl.pathname !== "/run") return new Response("rech server\n");
       const denied = authCheck(req, key);
@@ -312,7 +371,9 @@ export async function serve() {
       });
       const namespacedSession = clientSession ? `${sessionId}-${clientSession}` : sessionId;
       // Track --isolate sessions so the idle-TTL reaper can close them later.
-      if (isIsoSession(namespacedSession)) isoLastUsed.set(namespacedSession, Date.now());
+      const nowMs = Date.now();
+      if (isIsoSession(namespacedSession)) isoLastUsed.set(namespacedSession, nowMs);
+      else noteSession(namespacedSession, nowMs); // for the deep health probe to target
 
       // daemonInstall bakes PLAYWRIGHT_CLI into the daemon env; resolvePlaywrightCli() is the
       // fallback for a standalone `serve` (it re-runs the same env > fork > @playwright/cli > legacy chain).
@@ -339,6 +400,7 @@ export async function serve() {
             stdin: "ignore",
             stdout: "pipe",
             stderr: "pipe",
+            windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
             env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
           });
           const [listStatus, listOut] = await Promise.race([
@@ -421,16 +483,20 @@ export async function serve() {
         stdin: "ignore",
         stdout: "pipe",
         stderr: "pipe",
+        windowsHide: true, // hide the CLI child's console; the user's Chrome (a GUI grandchild) stays visible
         env: childEnv,
       });
 
       const TIMEOUT = 60_000;
-      const timeout = new Promise<never>((_, reject) =>
-        setTimeout(() => {
+      let timedOut = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          timedOut = true;
           proc.kill();
           reject(new Error("timeout"));
-        }, TIMEOUT),
-      );
+        }, TIMEOUT);
+      });
       const [status, stdout, stderr] = await Promise.race([
         Promise.all([
           proc.exited,
@@ -441,9 +507,37 @@ export async function serve() {
       ]).catch(
         () => [1, "", `Command timed out after ${TIMEOUT / 1000}s\n`] as [number, string, string],
       ) as [number, string, string];
+      clearTimeout(timer);
 
       log(`exit: ${status}${stdout.trim() ? ` | ${stdout.trim().slice(0, 200)}` : ""}`);
 
+      // Relay self-heal (see notes at SESSION_CLOSE_TIMEOUTS): a command that RETURNS — even
+      // non-zero — proves the relay answered, so clear the streaks; a TIMEOUT means it didn't.
+      if (timedOut) {
+        consecutiveTimeouts++;
+        const streak = (sessionTimeouts.get(namespacedSession) ?? 0) + 1;
+        sessionTimeouts.set(namespacedSession, streak);
+        log(`timeout: session=${namespacedSession} sessionStreak=${streak} globalStreak=${consecutiveTimeouts}`);
+        if (streak >= SESSION_CLOSE_TIMEOUTS) {
+          log(`session ${namespacedSession} wedged (${streak} consecutive timeouts) — closing so the next command respawns a clean cliDaemon`);
+          try {
+            Bun.spawn([bin, ...binArgs, "close", `-s=${namespacedSession}`], {
+              cwd: workDir, stdin: "ignore", stdout: "ignore", stderr: "ignore",
+              windowsHide: true,
+              env: { PATH: process.env.PATH, HOME: HOME, USERPROFILE: process.env.USERPROFILE },
+            });
+          } catch {}
+          sessionTimeouts.delete(namespacedSession);
+        }
+        if (consecutiveTimeouts >= WATCHDOG_TIMEOUTS) {
+          log(`relay wedged: ${consecutiveTimeouts} consecutive timeouts, no success between — exiting for oxmgr (--restart always) to respawn clean; extension WS will reconnect (Chrome untouched)`);
+          setTimeout(() => process.exit(1), 100); // brief delay to flush this response
+        }
+      } else {
+        consecutiveTimeouts = 0;
+        sessionTimeouts.delete(namespacedSession);
+      }
+
       // Detect files mentioned in output
       const filePattern = /[\w./-]+\.(?:png|jpe?g|pdf|json|yml)\b/gi;
       const mentionedFiles = [
@@ -482,17 +576,34 @@ export async function serve() {
     },
   });
 
-  // A leaked listening-socket handle in an orphaned cliDaemon can keep the port held after a
-  // prior serve exits; on EADDRINUSE, clear stale holders once and retry rather than crash-loop.
-  let server: ReturnType<typeof startServer>;
-  try {
-    server = startServer();
-  } catch (e: any) {
-    if (!String(e?.code ?? e?.message ?? "").includes("EADDRINUSE")) throw e;
-    log(`port ${port} in use — clearing stale daemon holders and retrying`);
-    await freeStalePort(port);
-    server = startServer();
+  // A leaked listening-socket handle in an orphaned cliDaemon can keep the port in LISTEN after a
+  // prior serve exits: Bun.serve creates the socket inheritable and Bun.spawn sweeps it into the
+  // detached daemon grandchild via bInheritHandles, so the socket outlives its creating serve.
+  // netstat then attributes the port to the now-dead *creator*, not the live holder, so we can't
+  // map port -> killable PID — freeStalePort kills the orphan by its cliDaemon signature instead.
+  // Retry a bounded number of times: the old single retry crash-looped whenever the OS hadn't yet
+  // released the socket after the kill (pm2 then restarts serve into the same race). As an absolute
+  // last resort, bind with reusePort so a holder we genuinely can't kill degrades to "up but sharing
+  // the port" rather than a permanent EADDRINUSE crash-loop.
+  const isEaddrInUse = (e: any) => String(e?.code ?? e?.message ?? "").includes("EADDRINUSE");
+  const MAX_BIND_ATTEMPTS = 4;
+  let server: ReturnType<typeof startServer> | undefined;
+  for (let attempt = 1; attempt <= MAX_BIND_ATTEMPTS; attempt++) {
+    try {
+      server = startServer();
+      break;
+    } catch (e: any) {
+      if (!isEaddrInUse(e)) throw e;
+      if (attempt === MAX_BIND_ATTEMPTS) {
+        log(`port ${port} still held after ${attempt - 1} cleanup attempts — binding with reusePort (last resort)`);
+        server = startServer(true);
+        break;
+      }
+      log(`port ${port} in use — clearing stale daemon holders and retrying (attempt ${attempt}/${MAX_BIND_ATTEMPTS - 1})`);
+      await freeStalePort(port);
+    }
   }
+  if (!server) throw new Error(`failed to bind port ${port}`);
 
   log(`serving on ${tls ? "https" : "http"}://${server.hostname}:${server.port}`);
   log(`Connection URL set (use .env.local to view)`);