rechrome 1.28.2 → 1.29.1

package/serve.js

@@ -243,6 +243,116 @@ async function resolveProfileDirectory(nameOrEmail: string): Promise<string> {
   return nameOrEmail;
 }
 
+// Free the listening port from stale daemon holders before retrying a failed bind.
+// On Windows the listening socket (created inheritable by Bun.serve) is swept into the
+// detached cliDaemon grandchild via bInheritHandles, so an orphaned cliDaemon from a
+// previous `serve` keeps the port in LISTEN after the old serve dies — the fresh serve
+// then crash-loops on EADDRINUSE. A clean restart releases the port, so a failed bind
+// only happens when such a stale holder exists; killing orphaned daemon holders here is
+// safe because a freshly-starting serve owns no live sessions of its own yet (the user's
+// Chrome tabs persist regardless — the cliDaemon only drives them).
+// Command lines freeStalePort may kill: a previous rech serve, or a cliDaemon started from
+// THIS install's playwright (lib/ or vendor/ under this directory) — never another app's
+// Playwright daemon, which runs from its own node_modules.
+const escapeRegex = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const OWN_CLI_DAEMON = import.meta.dir.split(/[\\/]/).map(escapeRegex).join(String.raw`[\\/]`) + String.raw`[\\/].*cliDaemon\.js`;
+const RECH_SERVE = String.raw`rech(rome)?(\.js)?"?\s+serve`;
+const STALE_HOLDER_PATTERN = `${OWN_CLI_DAEMON}|${RECH_SERVE}`;
+// A leaked socket (or a wedged serve) accepts connections but never answers. Anything that
+// responds at an address is a live server there — possibly a healthy rech serve — so it is
+// never killed. Both schemes: the holder's TLS setting may differ from this serve's.
+async function answersAt(address: string, port: number): Promise<boolean> {
+  const host = address === "0.0.0.0" || address === "*" ? "127.0.0.1"
+    : address === "::" ? "[::1]"
+    : address.includes(":") ? `[${address}]` : address;
+  const probe = (scheme: string) => fetch(`${scheme}://${host}:${port}/`, {
+    signal: AbortSignal.timeout(1500), tls: { rejectUnauthorized: false },
+  } as RequestInit).then(() => true, () => false);
+  return (await Promise.all([probe("http"), probe("https")])).includes(true);
+}
+
+type PortHolder = { address: string; pid: number; alive: boolean; command: string };
+
+// Listeners on `port` that conflict with binding `host`: the same address, or a wildcard of
+// its family (a wildcard bind conflicts with every address of the family). Never this serve's
+// own sockets, which may already hold other addresses on the same port from this startup.
+function conflictingHolders(port: number, host: string): PortHolder[] {
+  let holders: PortHolder[] = [];
+  if (process.platform === "win32") {
+    const ps = [
+      "$ErrorActionPreference='SilentlyContinue';",
+      `$r=@(Get-NetTCPConnection -LocalPort ${port} -State Listen | ForEach-Object {`,
+      "  $p=Get-CimInstance Win32_Process -Filter \"ProcessId=$($_.OwningProcess)\";",
+      "  [pscustomobject]@{ address=[string]$_.LocalAddress; pid=[int]$_.OwningProcess; alive=[bool]$p; command=[string]$p.CommandLine } });",
+      "ConvertTo-Json -Compress -InputObject $r",
+    ].join(" ");
+    const out = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true }).stdout?.toString().trim();
+    try { holders = out ? [JSON.parse(out)].flat() : []; } catch { holders = []; }
+  } else {
+    const out = Bun.spawnSync(["sh", "-c", `lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpn 2>/dev/null`]).stdout?.toString() ?? "";
+    let pid = 0;
+    for (const line of out.split("\n")) {
+      if (line.startsWith("p")) pid = Number(line.slice(1));
+      else if (line.startsWith("n") && pid) {
+        const address = line.slice(1).replace(/:\d+$/, "").replace(/^\[(.*)\]$/, "$1");
+        const command = Bun.spawnSync(["ps", "-o", "command=", "-p", String(pid)]).stdout?.toString().trim() ?? "";
+        holders.push({ address, pid, alive: true, command });
+      }
+    }
+  }
+  const v6 = (a: string) => a.includes(":");
+  const wildcard = (a: string) => a === "0.0.0.0" || a === "::" || a === "*";
+  // A `::` listener is dual-stack on Windows and most Linux setups: it conflicts with IPv4 binds too.
+  return holders.filter(h => h.pid !== process.pid && (
+    wildcard(host) ? (h.address === "*" || h.address === "::" || host === "::" || !v6(h.address))
+      : h.address === host || h.address === "*" || h.address === "::" || (h.address === "0.0.0.0" && !v6(host))));
+}
+
+// Free the conflicting address from stale rech holders before retrying a failed bind.
+// Narrow-first: (1) kill each conflicting owner that is a live rech serve / this install's
+// cliDaemon AND doesn't answer at its own address — never an unrelated app, never a healthy
+// server; (2) only if the address is STILL held by owners that are all dead — the
+// inherited-handle case, where the socket lives in a child while netstat attributes it to a
+// now-dead owner — sweep orphaned cliDaemons (Windows). That sweep is the only recovery for
+// the case (the live holder can't be mapped from the port), so it is a logged last resort.
+async function freeStalePort(port: number, host: string): Promise<void> {
+  try {
+    const stale = new RegExp(STALE_HOLDER_PATTERN, process.platform === "win32" ? "i" : "");
+    for (const h of conflictingHolders(port, host)) {
+      if (!h.alive) continue;
+      if (!stale.test(h.command)) { log(`freeStalePort: port ${port} is held by an unrelated process (${h.pid}); not killing it`); continue; }
+      if (await answersAt(h.address, port)) { log(`freeStalePort: ${h.address}:${port} is served by a live process (${h.pid}); not killing it`); continue; }
+      log(`freeStalePort: killing stale rech holder ${h.pid} of ${h.address}:${port}`);
+      try { process.kill(h.pid, "SIGKILL"); } catch {}
+    }
+    await new Promise(r => setTimeout(r, 400));
+    const remaining = conflictingHolders(port, host);
+    if (process.platform === "win32" && remaining.length && remaining.every(h => !h.alive)) {
+      const q = (text: string) => text.replaceAll("'", "''");
+      const ps = [
+        "$ErrorActionPreference='SilentlyContinue';",
+        // A cliDaemon's parent (playwright-cli) exits right after spawning it, so a live one
+        // can't be told from an orphan by ancestry. They are only provably orphaned when no
+        // other rech serve is running: exclude this serve and its own wrappers (oxmgr, cmd).
+        `$self=@(); $x=${process.pid}; while($x){ $self+=$x; $x=(Get-CimInstance Win32_Process -Filter \"ProcessId=$x\").ParentProcessId; if($self -contains $x){ break } };`,
+        `$live=@(Get-CimInstance Win32_Process | Where-Object { $self -notcontains $_.ProcessId -and $_.ProcessId -ne $PID -and $_.CommandLine -match '${q(RECH_SERVE)}' });`,
+        "if($live.Count){ Write-Output (\"freeStalePort: port still held, but another rech serve is running (\" + ($live.ProcessId -join ',') + \"); not sweeping cliDaemons\") }",
+        "else {",
+        // Exclude this PowerShell itself: its own command line contains the pattern.
+        `  $d=Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -ne $PID -and $_.CommandLine -match '${q(OWN_CLI_DAEMON)}' };`,
+        "  Write-Output (\"freeStalePort: port still held; killing orphaned cliDaemon holders: \" + ($d.ProcessId -join ','));",
+        "  $d | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
+        "}",
+      ].join(" ");
+      const out = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true }).stdout?.toString().trim();
+      if (out) log(out);
+    }
+  } catch {
+    // best effort — the retry will surface a clear error if the port is still held
+  }
+  await new Promise(r => setTimeout(r, 800)); // let the OS release the socket before retry
+}
+
 // --- Foreground/orphan self-exit ---------------------------------------------------
 // A foreground `rech serve` (run directly by an agent, NOT under oxmgr/pm2) has no
 // process-manager safety net: when the agent that spawned it exits, the OS re-parents
@@ -264,6 +374,88 @@ export function shouldExitOrphanedServe(opts: {
   return opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
 }
 
+export const LANDING_HEADERS = {
+  "Content-Type": "text/html; charset=utf-8",
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+  "X-Content-Type-Options": "nosniff",
+  "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+};
+
+/**
+ * The page a shared connection URL shows in a browser: install-and-connect commands to copy,
+ * one per shell. It is static; the script reads the full URL (with its #key) from the address
+ * bar, shows it with the key masked, and copies it whole.
+ */
+export function landingPage(): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to a shared Chrome · rechrome</title>
+<style>
+:root { --bg:#fff; --fg:#1d1d1f; --muted:#6e6e73; --card:#f5f5f7; --line:#d2d2d7; --accent:#0a66c2; --warn:#b25000; }
+@media (prefers-color-scheme: dark) { :root { --bg:#161617; --fg:#f5f5f7; --muted:#a1a1a6; --card:#232325; --line:#3a3a3c; --accent:#4c9bff; --warn:#ffb86b; } }
+* { box-sizing: border-box; }
+body { margin:0; background:var(--bg); color:var(--fg); font:16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 760px; margin: 0 auto; padding: 40px 16px 56px; }
+h1 { font-size: 1.6rem; margin: 0 0 8px; }
+p { margin: 0 0 16px; color: var(--muted); }
+.row { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; margin: 0 0 12px; }
+.label { font-size: .8rem; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); margin-bottom: 6px; }
+.cmd { display: flex; gap: 10px; align-items: flex-start; }
+code { flex: 1; font: 13px/1.5 ui-monospace, "SF Mono", Menlo, Consolas, monospace; word-break: break-all; white-space: pre-wrap; }
+button { flex: none; font: inherit; font-size: .9rem; padding: 4px 12px; border-radius: 6px; border: 1px solid var(--line); background: var(--bg); color: var(--fg); cursor: pointer; }
+button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.warn { color: var(--warn); font-weight: 600; }
+.small { font-size: .85rem; }
+a { color: var(--accent); }
+</style></head>
+<body><main>
+<h1>Connect to a shared Chrome</h1>
+<p>Someone shared a Chrome profile with you through <a href="https://github.com/snomiao/rechrome">rechrome</a>.
+On your computer, inside the project folder that should use it, run:</p>
+<p id="nokey" class="warn" hidden>This link is missing its key (the part after #key=). Ask for the full link from <code>rech share</code>.</p>
+<div id="cmds"></div>
+<p class="small">Needs <a href="https://bun.sh">Bun</a>. Then try <code>rechrome open https://example.com</code>.
+This link contains a secret key: anyone with it can use this browser profile, so share it privately.</p>
+</main>
+<script>
+(() => {
+  const url = location.href;
+  if (!/[#&?]key=/.test(location.hash)) document.getElementById("nokey").hidden = false;
+  const posix = s => "'" + s.replace(/'/g, "'\\\\''") + "'";
+  const pwsh = s => '"' + s.replace(/[\`"$]/g, c => "\`" + c) + '"';
+  const cmd = s => '"' + s.replace(/"/g, "%22") + '"';
+  const shells = [
+    ["macOS / Linux", "bun i -g rechrome && rechrome connect " + posix(url)],
+    ["Windows PowerShell", "bun i -g rechrome; rechrome connect " + pwsh(url)],
+    ["Windows cmd", "bun i -g rechrome && rechrome connect " + cmd(url)],
+  ];
+  const mask = s => s.replace(/(key=)[^&"'\`]+/, "$1…");
+  const root = document.getElementById("cmds");
+  for (const [label, text] of shells) {
+    const row = document.createElement("div"); row.className = "row";
+    const name = document.createElement("div"); name.className = "label"; name.textContent = label;
+    const line = document.createElement("div"); line.className = "cmd";
+    const code = document.createElement("code"); code.textContent = mask(text);
+    const button = document.createElement("button"); button.type = "button"; button.textContent = "Copy";
+    button.setAttribute("aria-label", "Copy the " + label + " command");
+    button.addEventListener("click", async () => {
+      try { await navigator.clipboard.writeText(text); }
+      catch {
+        // Plain-HTTP pages (e.g. a LAN address) have no clipboard API: copy via a hidden textarea.
+        const area = document.createElement("textarea"); area.value = text; document.body.append(area);
+        area.select(); document.execCommand("copy"); area.remove();
+      }
+      button.textContent = "Copied"; setTimeout(() => { button.textContent = "Copy"; }, 1500);
+    });
+    line.append(code, button); row.append(name, line); root.append(row);
+  }
+})();
+</script>
+</body></html>
+`;
+}
+
 export async function serve() {
   // The daemon owns logs/ and output/, so it migrates them before writing anything.
   const migrated = migrateLegacyDataDir();
@@ -312,9 +504,13 @@ export async function serve() {
   const legacy: Listener = { name: "legacy", host: listenHost, port, key, profiles: "*" };
   const policies = new Map<string, Listener>();
   const servers = new Map<string, ReturnType<typeof Bun.serve>>();
-  const startServer = (initial: Listener) => Bun.serve({
+  const startServer = (initial: Listener, reusePort = false) => Bun.serve({
     hostname: initial.host,
     port: initial.port,
+    // reusePort is used only as a last-resort fallback (see bindAtStartup 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}`);
@@ -381,6 +577,10 @@ export async function serve() {
           consecutiveTimeouts, degraded: degraded || !healthy,
         });
       }
+      // A browser opening a shared URL gets copyable connect instructions. The key stays in the
+      // #fragment, which browsers never send, so the page is static and the key never reaches here.
+      if (reqUrl.pathname === "/" && req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html"))
+        return new Response(landingPage(), { headers: LANDING_HEADERS });
       if (reqUrl.pathname !== "/run") return new Response("rech server\n");
       const denied = authCheck(req, key);
       if (denied) return denied;
@@ -687,14 +887,47 @@ export async function serve() {
     },
   });
 
+  // A leaked listening-socket handle in an orphaned cliDaemon can keep a 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.
+  // Startup only: a freshly-starting serve owns no live sessions, so clearing stale holders is
+  // safe. Hot reloads never kill anything (see reconcile). 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;
+  const bindAtStartup = async (listener: Listener) => {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return startServer(listener);
+      } catch (e: any) {
+        if (!isEaddrInUse(e)) throw e;
+        // Something answers at this exact address: a live server (never killed, never port-shared).
+        if (await answersAt(listener.host, listener.port)) {
+          log(`port ${listener.port} is held by a live server that answers requests — not touching it`);
+          throw e;
+        }
+        if (attempt === MAX_BIND_ATTEMPTS) {
+          log(`port ${listener.port} still held after ${attempt - 1} cleanup attempts — binding with reusePort (last resort)`);
+          return startServer(listener, true);
+        }
+        log(`port ${listener.port} in use — clearing stale daemon holders and retrying (attempt ${attempt}/${MAX_BIND_ATTEMPTS - 1})`);
+        await freeStalePort(listener.port, listener.host);
+      }
+    }
+  };
+
   // Stage all new sockets before changing policy. Bind failure leaves existing
-  // listeners and browser sessions intact; never kill a process holding another port.
-  const reconcile = async (listeners: Listener[]) => {
+  // listeners and browser sessions intact; never kill a process holding another port
+  // once serving (stale-holder recovery runs only at startup).
+  const reconcile = async (listeners: Listener[], startup = false) => {
     const staged = new Map<string, ReturnType<typeof Bun.serve>>();
     try {
       for (const listener of listeners) {
         const address = listenerAddress(listener);
-        if (!servers.has(address)) staged.set(address, startServer(listener));
+        if (!servers.has(address)) staged.set(address, startup ? await bindAtStartup(listener) : startServer(listener));
       }
     } catch (error) {
       for (const server of staged.values()) server.stop(true);
@@ -709,17 +942,17 @@ export async function serve() {
   };
   let applied = "";
   let configured = false;
-  const reload = async () => {
+  const reload = async (startup = false) => {
     const config = await readListeners();
     if (!config && configured) throw new Error("listeners.json disappeared; refusing to restore unrestricted legacy access");
     const listeners = config?.listeners ?? [legacy];
     const fingerprint = JSON.stringify(listeners);
     if (applied === fingerprint) return;
-    await reconcile(listeners);
+    await reconcile(listeners, startup);
     configured ||= !!config;
     applied = fingerprint;
   };
-  await reload();
+  await reload(true);
   let reloading = false;
   let lastError = "";
   setInterval(async () => {

package/serve.ts

@@ -243,6 +243,116 @@ async function resolveProfileDirectory(nameOrEmail: string): Promise<string> {
   return nameOrEmail;
 }
 
+// Free the listening port from stale daemon holders before retrying a failed bind.
+// On Windows the listening socket (created inheritable by Bun.serve) is swept into the
+// detached cliDaemon grandchild via bInheritHandles, so an orphaned cliDaemon from a
+// previous `serve` keeps the port in LISTEN after the old serve dies — the fresh serve
+// then crash-loops on EADDRINUSE. A clean restart releases the port, so a failed bind
+// only happens when such a stale holder exists; killing orphaned daemon holders here is
+// safe because a freshly-starting serve owns no live sessions of its own yet (the user's
+// Chrome tabs persist regardless — the cliDaemon only drives them).
+// Command lines freeStalePort may kill: a previous rech serve, or a cliDaemon started from
+// THIS install's playwright (lib/ or vendor/ under this directory) — never another app's
+// Playwright daemon, which runs from its own node_modules.
+const escapeRegex = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const OWN_CLI_DAEMON = import.meta.dir.split(/[\\/]/).map(escapeRegex).join(String.raw`[\\/]`) + String.raw`[\\/].*cliDaemon\.js`;
+const RECH_SERVE = String.raw`rech(rome)?(\.ts)?"?\s+serve`;
+const STALE_HOLDER_PATTERN = `${OWN_CLI_DAEMON}|${RECH_SERVE}`;
+// A leaked socket (or a wedged serve) accepts connections but never answers. Anything that
+// responds at an address is a live server there — possibly a healthy rech serve — so it is
+// never killed. Both schemes: the holder's TLS setting may differ from this serve's.
+async function answersAt(address: string, port: number): Promise<boolean> {
+  const host = address === "0.0.0.0" || address === "*" ? "127.0.0.1"
+    : address === "::" ? "[::1]"
+    : address.includes(":") ? `[${address}]` : address;
+  const probe = (scheme: string) => fetch(`${scheme}://${host}:${port}/`, {
+    signal: AbortSignal.timeout(1500), tls: { rejectUnauthorized: false },
+  } as RequestInit).then(() => true, () => false);
+  return (await Promise.all([probe("http"), probe("https")])).includes(true);
+}
+
+type PortHolder = { address: string; pid: number; alive: boolean; command: string };
+
+// Listeners on `port` that conflict with binding `host`: the same address, or a wildcard of
+// its family (a wildcard bind conflicts with every address of the family). Never this serve's
+// own sockets, which may already hold other addresses on the same port from this startup.
+function conflictingHolders(port: number, host: string): PortHolder[] {
+  let holders: PortHolder[] = [];
+  if (process.platform === "win32") {
+    const ps = [
+      "$ErrorActionPreference='SilentlyContinue';",
+      `$r=@(Get-NetTCPConnection -LocalPort ${port} -State Listen | ForEach-Object {`,
+      "  $p=Get-CimInstance Win32_Process -Filter \"ProcessId=$($_.OwningProcess)\";",
+      "  [pscustomobject]@{ address=[string]$_.LocalAddress; pid=[int]$_.OwningProcess; alive=[bool]$p; command=[string]$p.CommandLine } });",
+      "ConvertTo-Json -Compress -InputObject $r",
+    ].join(" ");
+    const out = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true }).stdout?.toString().trim();
+    try { holders = out ? [JSON.parse(out)].flat() : []; } catch { holders = []; }
+  } else {
+    const out = Bun.spawnSync(["sh", "-c", `lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpn 2>/dev/null`]).stdout?.toString() ?? "";
+    let pid = 0;
+    for (const line of out.split("\n")) {
+      if (line.startsWith("p")) pid = Number(line.slice(1));
+      else if (line.startsWith("n") && pid) {
+        const address = line.slice(1).replace(/:\d+$/, "").replace(/^\[(.*)\]$/, "$1");
+        const command = Bun.spawnSync(["ps", "-o", "command=", "-p", String(pid)]).stdout?.toString().trim() ?? "";
+        holders.push({ address, pid, alive: true, command });
+      }
+    }
+  }
+  const v6 = (a: string) => a.includes(":");
+  const wildcard = (a: string) => a === "0.0.0.0" || a === "::" || a === "*";
+  // A `::` listener is dual-stack on Windows and most Linux setups: it conflicts with IPv4 binds too.
+  return holders.filter(h => h.pid !== process.pid && (
+    wildcard(host) ? (h.address === "*" || h.address === "::" || host === "::" || !v6(h.address))
+      : h.address === host || h.address === "*" || h.address === "::" || (h.address === "0.0.0.0" && !v6(host))));
+}
+
+// Free the conflicting address from stale rech holders before retrying a failed bind.
+// Narrow-first: (1) kill each conflicting owner that is a live rech serve / this install's
+// cliDaemon AND doesn't answer at its own address — never an unrelated app, never a healthy
+// server; (2) only if the address is STILL held by owners that are all dead — the
+// inherited-handle case, where the socket lives in a child while netstat attributes it to a
+// now-dead owner — sweep orphaned cliDaemons (Windows). That sweep is the only recovery for
+// the case (the live holder can't be mapped from the port), so it is a logged last resort.
+async function freeStalePort(port: number, host: string): Promise<void> {
+  try {
+    const stale = new RegExp(STALE_HOLDER_PATTERN, process.platform === "win32" ? "i" : "");
+    for (const h of conflictingHolders(port, host)) {
+      if (!h.alive) continue;
+      if (!stale.test(h.command)) { log(`freeStalePort: port ${port} is held by an unrelated process (${h.pid}); not killing it`); continue; }
+      if (await answersAt(h.address, port)) { log(`freeStalePort: ${h.address}:${port} is served by a live process (${h.pid}); not killing it`); continue; }
+      log(`freeStalePort: killing stale rech holder ${h.pid} of ${h.address}:${port}`);
+      try { process.kill(h.pid, "SIGKILL"); } catch {}
+    }
+    await new Promise(r => setTimeout(r, 400));
+    const remaining = conflictingHolders(port, host);
+    if (process.platform === "win32" && remaining.length && remaining.every(h => !h.alive)) {
+      const q = (text: string) => text.replaceAll("'", "''");
+      const ps = [
+        "$ErrorActionPreference='SilentlyContinue';",
+        // A cliDaemon's parent (playwright-cli) exits right after spawning it, so a live one
+        // can't be told from an orphan by ancestry. They are only provably orphaned when no
+        // other rech serve is running: exclude this serve and its own wrappers (oxmgr, cmd).
+        `$self=@(); $x=${process.pid}; while($x){ $self+=$x; $x=(Get-CimInstance Win32_Process -Filter \"ProcessId=$x\").ParentProcessId; if($self -contains $x){ break } };`,
+        `$live=@(Get-CimInstance Win32_Process | Where-Object { $self -notcontains $_.ProcessId -and $_.ProcessId -ne $PID -and $_.CommandLine -match '${q(RECH_SERVE)}' });`,
+        "if($live.Count){ Write-Output (\"freeStalePort: port still held, but another rech serve is running (\" + ($live.ProcessId -join ',') + \"); not sweeping cliDaemons\") }",
+        "else {",
+        // Exclude this PowerShell itself: its own command line contains the pattern.
+        `  $d=Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -ne $PID -and $_.CommandLine -match '${q(OWN_CLI_DAEMON)}' };`,
+        "  Write-Output (\"freeStalePort: port still held; killing orphaned cliDaemon holders: \" + ($d.ProcessId -join ','));",
+        "  $d | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }",
+        "}",
+      ].join(" ");
+      const out = Bun.spawnSync(["powershell", "-NoProfile", "-NonInteractive", "-Command", ps], { windowsHide: true }).stdout?.toString().trim();
+      if (out) log(out);
+    }
+  } catch {
+    // best effort — the retry will surface a clear error if the port is still held
+  }
+  await new Promise(r => setTimeout(r, 800)); // let the OS release the socket before retry
+}
+
 // --- Foreground/orphan self-exit ---------------------------------------------------
 // A foreground `rech serve` (run directly by an agent, NOT under oxmgr/pm2) has no
 // process-manager safety net: when the agent that spawned it exits, the OS re-parents
@@ -264,6 +374,88 @@ export function shouldExitOrphanedServe(opts: {
   return opts.idleTimeoutMs > 0 && opts.orphaned && opts.idleMs >= opts.idleTimeoutMs;
 }
 
+export const LANDING_HEADERS = {
+  "Content-Type": "text/html; charset=utf-8",
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+  "X-Content-Type-Options": "nosniff",
+  "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+};
+
+/**
+ * The page a shared connection URL shows in a browser: install-and-connect commands to copy,
+ * one per shell. It is static; the script reads the full URL (with its #key) from the address
+ * bar, shows it with the key masked, and copies it whole.
+ */
+export function landingPage(): string {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Connect to a shared Chrome · rechrome</title>
+<style>
+:root { --bg:#fff; --fg:#1d1d1f; --muted:#6e6e73; --card:#f5f5f7; --line:#d2d2d7; --accent:#0a66c2; --warn:#b25000; }
+@media (prefers-color-scheme: dark) { :root { --bg:#161617; --fg:#f5f5f7; --muted:#a1a1a6; --card:#232325; --line:#3a3a3c; --accent:#4c9bff; --warn:#ffb86b; } }
+* { box-sizing: border-box; }
+body { margin:0; background:var(--bg); color:var(--fg); font:16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 760px; margin: 0 auto; padding: 40px 16px 56px; }
+h1 { font-size: 1.6rem; margin: 0 0 8px; }
+p { margin: 0 0 16px; color: var(--muted); }
+.row { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; margin: 0 0 12px; }
+.label { font-size: .8rem; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); margin-bottom: 6px; }
+.cmd { display: flex; gap: 10px; align-items: flex-start; }
+code { flex: 1; font: 13px/1.5 ui-monospace, "SF Mono", Menlo, Consolas, monospace; word-break: break-all; white-space: pre-wrap; }
+button { flex: none; font: inherit; font-size: .9rem; padding: 4px 12px; border-radius: 6px; border: 1px solid var(--line); background: var(--bg); color: var(--fg); cursor: pointer; }
+button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.warn { color: var(--warn); font-weight: 600; }
+.small { font-size: .85rem; }
+a { color: var(--accent); }
+</style></head>
+<body><main>
+<h1>Connect to a shared Chrome</h1>
+<p>Someone shared a Chrome profile with you through <a href="https://github.com/snomiao/rechrome">rechrome</a>.
+On your computer, inside the project folder that should use it, run:</p>
+<p id="nokey" class="warn" hidden>This link is missing its key (the part after #key=). Ask for the full link from <code>rech share</code>.</p>
+<div id="cmds"></div>
+<p class="small">Needs <a href="https://bun.sh">Bun</a>. Then try <code>rechrome open https://example.com</code>.
+This link contains a secret key: anyone with it can use this browser profile, so share it privately.</p>
+</main>
+<script>
+(() => {
+  const url = location.href;
+  if (!/[#&?]key=/.test(location.hash)) document.getElementById("nokey").hidden = false;
+  const posix = s => "'" + s.replace(/'/g, "'\\\\''") + "'";
+  const pwsh = s => '"' + s.replace(/[\`"$]/g, c => "\`" + c) + '"';
+  const cmd = s => '"' + s.replace(/"/g, "%22") + '"';
+  const shells = [
+    ["macOS / Linux", "bun i -g rechrome && rechrome connect " + posix(url)],
+    ["Windows PowerShell", "bun i -g rechrome; rechrome connect " + pwsh(url)],
+    ["Windows cmd", "bun i -g rechrome && rechrome connect " + cmd(url)],
+  ];
+  const mask = s => s.replace(/(key=)[^&"'\`]+/, "$1…");
+  const root = document.getElementById("cmds");
+  for (const [label, text] of shells) {
+    const row = document.createElement("div"); row.className = "row";
+    const name = document.createElement("div"); name.className = "label"; name.textContent = label;
+    const line = document.createElement("div"); line.className = "cmd";
+    const code = document.createElement("code"); code.textContent = mask(text);
+    const button = document.createElement("button"); button.type = "button"; button.textContent = "Copy";
+    button.setAttribute("aria-label", "Copy the " + label + " command");
+    button.addEventListener("click", async () => {
+      try { await navigator.clipboard.writeText(text); }
+      catch {
+        // Plain-HTTP pages (e.g. a LAN address) have no clipboard API: copy via a hidden textarea.
+        const area = document.createElement("textarea"); area.value = text; document.body.append(area);
+        area.select(); document.execCommand("copy"); area.remove();
+      }
+      button.textContent = "Copied"; setTimeout(() => { button.textContent = "Copy"; }, 1500);
+    });
+    line.append(code, button); row.append(name, line); root.append(row);
+  }
+})();
+</script>
+</body></html>
+`;
+}
+
 export async function serve() {
   // The daemon owns logs/ and output/, so it migrates them before writing anything.
   const migrated = migrateLegacyDataDir();
@@ -312,9 +504,13 @@ export async function serve() {
   const legacy: Listener = { name: "legacy", host: listenHost, port, key, profiles: "*" };
   const policies = new Map<string, Listener>();
   const servers = new Map<string, ReturnType<typeof Bun.serve>>();
-  const startServer = (initial: Listener) => Bun.serve({
+  const startServer = (initial: Listener, reusePort = false) => Bun.serve({
     hostname: initial.host,
     port: initial.port,
+    // reusePort is used only as a last-resort fallback (see bindAtStartup 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}`);
@@ -381,6 +577,10 @@ export async function serve() {
           consecutiveTimeouts, degraded: degraded || !healthy,
         });
       }
+      // A browser opening a shared URL gets copyable connect instructions. The key stays in the
+      // #fragment, which browsers never send, so the page is static and the key never reaches here.
+      if (reqUrl.pathname === "/" && req.method === "GET" && (req.headers.get("accept") ?? "").includes("text/html"))
+        return new Response(landingPage(), { headers: LANDING_HEADERS });
       if (reqUrl.pathname !== "/run") return new Response("rech server\n");
       const denied = authCheck(req, key);
       if (denied) return denied;
@@ -687,14 +887,47 @@ export async function serve() {
     },
   });
 
+  // A leaked listening-socket handle in an orphaned cliDaemon can keep a 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.
+  // Startup only: a freshly-starting serve owns no live sessions, so clearing stale holders is
+  // safe. Hot reloads never kill anything (see reconcile). 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;
+  const bindAtStartup = async (listener: Listener) => {
+    for (let attempt = 1; ; attempt++) {
+      try {
+        return startServer(listener);
+      } catch (e: any) {
+        if (!isEaddrInUse(e)) throw e;
+        // Something answers at this exact address: a live server (never killed, never port-shared).
+        if (await answersAt(listener.host, listener.port)) {
+          log(`port ${listener.port} is held by a live server that answers requests — not touching it`);
+          throw e;
+        }
+        if (attempt === MAX_BIND_ATTEMPTS) {
+          log(`port ${listener.port} still held after ${attempt - 1} cleanup attempts — binding with reusePort (last resort)`);
+          return startServer(listener, true);
+        }
+        log(`port ${listener.port} in use — clearing stale daemon holders and retrying (attempt ${attempt}/${MAX_BIND_ATTEMPTS - 1})`);
+        await freeStalePort(listener.port, listener.host);
+      }
+    }
+  };
+
   // Stage all new sockets before changing policy. Bind failure leaves existing
-  // listeners and browser sessions intact; never kill a process holding another port.
-  const reconcile = async (listeners: Listener[]) => {
+  // listeners and browser sessions intact; never kill a process holding another port
+  // once serving (stale-holder recovery runs only at startup).
+  const reconcile = async (listeners: Listener[], startup = false) => {
     const staged = new Map<string, ReturnType<typeof Bun.serve>>();
     try {
       for (const listener of listeners) {
         const address = listenerAddress(listener);
-        if (!servers.has(address)) staged.set(address, startServer(listener));
+        if (!servers.has(address)) staged.set(address, startup ? await bindAtStartup(listener) : startServer(listener));
       }
     } catch (error) {
       for (const server of staged.values()) server.stop(true);
@@ -709,17 +942,17 @@ export async function serve() {
   };
   let applied = "";
   let configured = false;
-  const reload = async () => {
+  const reload = async (startup = false) => {
     const config = await readListeners();
     if (!config && configured) throw new Error("listeners.json disappeared; refusing to restore unrestricted legacy access");
     const listeners = config?.listeners ?? [legacy];
     const fingerprint = JSON.stringify(listeners);
     if (applied === fingerprint) return;
-    await reconcile(listeners);
+    await reconcile(listeners, startup);
     configured ||= !!config;
     applied = fingerprint;
   };
-  await reload();
+  await reload(true);
   let reloading = false;
   let lastError = "";
   setInterval(async () => {