rechrome 1.28.0 → 1.28.2

package/README.md

@@ -285,7 +285,7 @@ directory. Pass `-s=<name>` for a named sub-session, or `--isolate` for a throwa
 ```bash
 git clone https://github.com/snomiao/rechrome.git
 cd rechrome
-bun install
+bun install       # `prepare` also builds vendor/ from vendor-src/, so the checkout has a working CLI
 bun link          # makes this checkout the global rechrome / rech
 bun test ./*.test.ts ./*.spec.ts ./scripts/*.test.ts   # rechrome's own tests (plain `bun test` also finds the vendored forks' suites)
 ```

package/daemon-manager.js

@@ -24,13 +24,14 @@ function oxmgrHasWinfix(version) {
 function pickDaemonManager(opts) {
   const override = opts.override?.toLowerCase();
   if (override === "oxmgr" && !opts.oxmgrBin) {
-    throw new Error("RECH_DAEMON_MANAGER=oxmgr, but oxmgr is not on PATH. Install oxmgr and add it to PATH, or install pm2 with `bun add -g pm2` and set RECH_DAEMON_MANAGER=pm2.");
+    throw new Error("RECH_DAEMON_MANAGER=oxmgr, but oxmgr is not on PATH. Install it with `bun i -g oxmgr` and ensure the global bin directory is on PATH.");
   }
   if (override === "pm2" && !opts.pm2Bin) {
     throw new Error("RECH_DAEMON_MANAGER=pm2, but pm2 is not on PATH. Install it with `bun add -g pm2` and ensure the global bin directory is on PATH.");
   }
   if (!opts.oxmgrBin && !opts.pm2Bin) {
-    throw new Error("No daemon process manager found on PATH (oxmgr or pm2). Install pm2 with `bun add -g pm2`, ensure the global bin directory is on PATH, then rerun `bunx rechrome setup`.");
+    const install = opts.isWindows ? "Install oxmgr with `bun i -g oxmgr` (on Windows, pm2 via `bun add -g pm2` is preferred unless oxmgr is the +winfix build)" : "Install oxmgr with `bun i -g oxmgr`";
+    throw new Error(`No daemon process manager found on PATH (oxmgr or pm2). ${install}, ensure the global bin directory is on PATH, then rerun \`bunx rechrome setup\`.`);
   }
   const oxmgr = { id: "oxmgr", bin: opts.oxmgrBin ?? "oxmgr" };
   const pm2 = { id: "pm2", bin: opts.pm2Bin ?? "pm2" };
@@ -62,9 +63,27 @@ function oxmgrInstallCommand(env) {
     return ["npm", "i", "-g", "oxmgr"];
   return ["bun", "i", "-g", "oxmgr"];
 }
+var PM2_DEPRECATION = "pm2 is deprecated as the rech daemon manager; install oxmgr (`bun i -g oxmgr`) and rerun `rech setup` to migrate.";
+function isDeprecatedPm2Fallback(mgr, opts) {
+  return mgr.id === "pm2" && !opts.isWindows && !opts.override;
+}
+function listsProcess(id, output, name) {
+  if (id === "pm2") {
+    try {
+      const list = JSON.parse(output);
+      return Array.isArray(list) && list.some((p) => p?.name === name);
+    } catch {
+      return false;
+    }
+  }
+  return output.split(/[\s\u2502|\u2503]+/).includes(name);
+}
 export {
   OXMGR_WINFIX_BASE,
+  PM2_DEPRECATION,
   compareVersion,
+  isDeprecatedPm2Fallback,
+  listsProcess,
   oxmgrHasWinfix,
   oxmgrInstallCommand,
   pickDaemonManager

package/daemon-manager.ts

@@ -58,13 +58,18 @@ export function pickDaemonManager(opts: {
 }): DaemonManager {
   const override = opts.override?.toLowerCase();
   if (override === "oxmgr" && !opts.oxmgrBin) {
-    throw new Error("RECH_DAEMON_MANAGER=oxmgr, but oxmgr is not on PATH. Install oxmgr and add it to PATH, or install pm2 with `bun add -g pm2` and set RECH_DAEMON_MANAGER=pm2.");
+    throw new Error("RECH_DAEMON_MANAGER=oxmgr, but oxmgr is not on PATH. Install it with `bun i -g oxmgr` and ensure the global bin directory is on PATH.");
   }
   if (override === "pm2" && !opts.pm2Bin) {
     throw new Error("RECH_DAEMON_MANAGER=pm2, but pm2 is not on PATH. Install it with `bun add -g pm2` and ensure the global bin directory is on PATH.");
   }
   if (!opts.oxmgrBin && !opts.pm2Bin) {
-    throw new Error("No daemon process manager found on PATH (oxmgr or pm2). Install pm2 with `bun add -g pm2`, ensure the global bin directory is on PATH, then rerun `bunx rechrome setup`.");
+    // oxmgr is the recommended manager. On Windows stock oxmgr is only used when pm2 is
+    // absent (see below), so pm2 stays a documented alternative there.
+    const install = opts.isWindows
+      ? "Install oxmgr with `bun i -g oxmgr` (on Windows, pm2 via `bun add -g pm2` is preferred unless oxmgr is the +winfix build)"
+      : "Install oxmgr with `bun i -g oxmgr`";
+    throw new Error(`No daemon process manager found on PATH (oxmgr or pm2). ${install}, ensure the global bin directory is on PATH, then rerun \`bunx rechrome setup\`.`);
   }
   const oxmgr: DaemonManager = { id: "oxmgr", bin: opts.oxmgrBin ?? "oxmgr" };
   const pm2: DaemonManager = { id: "pm2", bin: opts.pm2Bin ?? "pm2" };
@@ -97,3 +102,29 @@ export function oxmgrInstallCommand(env: { npm_config_user_agent?: string; npm_e
   if (/(^|\/)(npm|npx)(-cli\.js|\.cmd|\.exe)?$/i.test(execPath)) return ["npm", "i", "-g", "oxmgr"];
   return ["bun", "i", "-g", "oxmgr"];
 }
+
+export const PM2_DEPRECATION =
+  "pm2 is deprecated as the rech daemon manager; install oxmgr (`bun i -g oxmgr`) and rerun `rech setup` to migrate.";
+
+// Whether `mgr` is pm2 only as a stopgap because oxmgr is missing: the case where the user
+// should be nudged to oxmgr. Never on Windows, where pm2 is the deliberate choice over stock
+// (non-winfix) oxmgr and installing oxmgr would not change the pick, and never for an explicit
+// RECH_DAEMON_MANAGER=pm2.
+export function isDeprecatedPm2Fallback(mgr: DaemonManager, opts: { isWindows: boolean; override?: string | null }): boolean {
+  return mgr.id === "pm2" && !opts.isWindows && !opts.override;
+}
+
+// Whether a manager's process list (pm2 `jlist` JSON / oxmgr `list` table) registers exactly
+// `name`. A substring test false-positives on other processes whose names, paths or args
+// mention it (a pm2 app running from a `.../rechrome/...` checkout, or legacy `rechrome-serve`).
+export function listsProcess(id: DaemonManager["id"], output: string, name: string): boolean {
+  if (id === "pm2") {
+    try {
+      const list = JSON.parse(output);
+      return Array.isArray(list) && list.some((p: { name?: unknown } | null) => p?.name === name);
+    } catch {
+      return false;
+    }
+  }
+  return output.split(/[\s│|┃]+/).includes(name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rechrome",
-  "version": "1.28.0",
+  "version": "1.28.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/rechrome.git"
@@ -32,7 +32,9 @@
     "serve": "bun run rechrome.ts serve",
     "test": "bun test",
     "vendor-cli": "bash scripts/vendor-cli.sh",
-    "prepublishOnly": "bash scripts/vendor-cli.sh && sed 's/\\.ts/\\.js/g' rechrome.ts > rechrome.js && sed 's/\\.ts/\\.js/g' serve.ts > serve.js && bun build extension-token.ts --target=bun --outfile=extension-token.js && bun build daemon-manager.ts --target=bun --outfile=daemon-manager.js && bun build listeners.ts --target=bun --outfile=listeners.js"
+    "prepare": "bash scripts/vendor-cli.sh --prepare",
+    "check-pack": "bash scripts/check-pack.sh",
+    "prepublishOnly": "bash scripts/vendor-cli.sh && sed 's/\\.ts/\\.js/g' rechrome.ts > rechrome.js && sed 's/\\.ts/\\.js/g' serve.ts > serve.js && bun build extension-token.ts --target=bun --outfile=extension-token.js && bun build daemon-manager.ts --target=bun --outfile=daemon-manager.js && bun build listeners.ts --target=bun --outfile=listeners.js && bash scripts/check-pack.sh"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/rechrome.js

@@ -10,9 +10,10 @@ import { hostname, homedir, networkInterfaces } from "os";
 import { isIPv4 } from "net";
 import { join, basename, dirname } from "path";
 import { pathToFileURL } from "url";
+import { createRequire } from "node:module";
 import { spawn as cpSpawn } from "child_process";
 import { readFile, writeFile, rename, chmod, mkdir } from "node:fs/promises";
-import { oxmgrInstallCommand, pickDaemonManager, type DaemonManager } from "./daemon-manager.js";
+import { isDeprecatedPm2Fallback, listsProcess, oxmgrInstallCommand, pickDaemonManager, PM2_DEPRECATION, type DaemonManager } from "./daemon-manager.js";
 
 export const ENV_KEY = "RECHROME_URL";
 export const DEFAULT_PORT = 13775;
@@ -976,15 +977,45 @@ async function callServe(
     console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]`);
     process.exit(1);
   }
-  return res.json();
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Not the daemon answering, e.g. a reverse proxy's 404 because the URL's path prefix is wrong.
+    const detail = `HTTP ${res.status} from ${serviceUrl(url, "run")} is not a rechrome daemon response: ${text.slice(0, 200).trim()}`;
+    if (throwOnFailure) throw new Error(detail);
+    console.error(`[rech] rech-client -> ${serviceUrl(url, "run")}\n  -x: ${detail}`);
+    process.exit(1);
+  }
 }
 
+const BOOLEAN_OPEN_FLAGS = new Set(["--headed", "--persistent", "--in-memory", "--extension"]);
+
 export function normalizeCommandArgs(args: string[]): string[] {
   const normalized = [...args];
   if (normalized[0] === "tabs" || normalized[0] === "list") normalized[0] = "tab-list";
+  // `rech open hello.com`: profile-scoped listeners accept only HTTP(S)/about:blank targets, so
+  // give a bare host an https:// scheme the way a browser address bar would.
+  if (["open", "goto", "tab-new"].includes(normalized[0])) {
+    // The target is the first positional. A token after a `--flag` without `=` is that flag's
+    // value (`open --profile my-profile url`), unless the flag is a known boolean.
+    const takesValue = (flag: string) => flag.startsWith("-") && !flag.includes("=") && !BOOLEAN_OPEN_FLAGS.has(flag);
+    const i = normalized.findIndex((a, idx) => idx > 0 && !a.startsWith("-") && !takesValue(normalized[idx - 1]!));
+    if (i > 0) normalized[i] = withDefaultScheme(normalized[i]!);
+  }
   return normalized;
 }
 
+/** `hello.com` -> `https://hello.com`, `localhost:3000` -> `http://localhost:3000`; URLs with a scheme and paths are unchanged. */
+export function withDefaultScheme(target: string): string {
+  if (/^[./\\~]/.test(target) || /^[a-z]:[\\/]/i.test(target)) return target; // a file path, not a host
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target) && !/^[^/:]+:\d+(\/|$|[?#])/.test(target)) return target;
+  // Loopback by exact hostname: `localhost.example.com` / `127.example.com` are public hosts.
+  const host = (target.match(/^(\[[^\]]*\]|[^/:?#]*)/)?.[1] ?? "").toLowerCase();
+  const loopback = host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host);
+  return loopback ? `http://${target}` : `https://${target}`;
+}
+
 // Pull a global `--profile <val>` / `--profile=<val>` out of the leading flags of an argv.
 // Only flags before the first positional (the playwright subcommand) are rech globals — a
 // --profile at/after the subcommand belongs to the forwarded CLI (e.g. playwright-cli's own
@@ -1115,7 +1146,9 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
   }
   if (stderr) {
     if (stderr.includes('Extension connection timeout')) {
-      const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"];
+      // The daemon resolves registered profiles' bridge tokens itself and then asks for a reload;
+      // only blame a missing install when neither side had credentials.
+      const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] || /reload the .*extension/i.test(stderr);
       const last = hasToken
         ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
         : `  -> extension[not installed]  (run: rech setup)`;
@@ -1404,6 +1437,8 @@ function daemonManager(): DaemonManager {
     isWindows: IS_WINDOWS,
     override: process.env.RECH_DAEMON_MANAGER,
   });
+  if (isDeprecatedPm2Fallback(_daemonMgr, { isWindows: IS_WINDOWS, override: process.env.RECH_DAEMON_MANAGER }))
+    console.error(`[rech] warning: using pm2 because oxmgr is not on PATH. ${PM2_DEPRECATION}`);
   return _daemonMgr;
 }
 
@@ -1440,29 +1475,47 @@ async function oxmgrEnsureAutostart(mgr: DaemonManager): Promise<void> {
 }
 
 // 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.
+// Match a name in it with listsProcess, not a substring test.
 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();
 }
 
+// A candidate playwright-cli entry is usable only if the playwright-core it requires actually
+// resolves FROM that entry — the wrapper does `require('playwright-core/lib/tools/cli-client/program')`,
+// a deep subpath reachable only through the fork's patched `exports` map. existsSync on the .js is
+// not the same check: an uninitialised/half-built lib/playwright-cli submodule leaves the wrapper on
+// disk with no resolvable core, and the failure surfaces later as MODULE_NOT_FOUND inside the daemon.
+export function playwrightCliIsUsable(jsEntry: string): boolean {
+  try {
+    createRequire(jsEntry).resolve("playwright-core/lib/tools/cli-client/program");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Resolve which playwright-cli the daemon runs to drive Chrome. Priority:
 //   1. PLAYWRIGHT_CLI env override — explicit, already a full command string.
 //   2. Vendored fork in a git checkout (lib/playwright-cli/playwright-cli.js) — the patched
 //      multi-tab CLI + patched playwright-core (PLAYWRIGHT_MCP_PROFILE_DIRECTORY etc.).
 //   3. The fork bundled into the npm tarball (vendor/playwright-cli/playwright-cli.js, produced by
-//      scripts/vendor-cli.sh at prepublish). This is the batteries-included default for
-//      `bun i -g rechrome`: self-contained, no @playwright/cli dep, no browser-binary download.
+//      scripts/vendor-cli.sh at prepublish, and by `prepare` on `bun install` in a checkout). This
+//      is the batteries-included default for `bun i -g rechrome`: self-contained, no
+//      @playwright/cli dep, no browser-binary download.
 //   4. Bare `playwright-cli-multi-tab` on PATH — legacy fallback for a pre-existing global link.
+// Candidates 2–3 must also pass playwrightCliIsUsable(), so a present-but-broken one falls through.
+// lib/ stays ahead of vendor/ on purpose: a dev who built the fork wants their patched core, not
+// the (possibly older) vendor-src snapshot that `prepare` unpacks into vendor/.
 // A resolved .js entry is run through `node` on Windows (which can't exec a .js by shebang) and
 // bare on POSIX (its `#!/usr/bin/env node` shebang runs it under node, which the relay handshake
 // needs — see daemonInstall). serve splits the result on spaces into argv.
-export function resolvePlaywrightCli(): string {
+export function resolvePlaywrightCli(root: string = import.meta.dir): string {
   if (process.env.PLAYWRIGHT_CLI) return process.env.PLAYWRIGHT_CLI;
   const jsEntry = [
-    join(import.meta.dir, "lib/playwright-cli/playwright-cli.js"),
-    join(import.meta.dir, "vendor/playwright-cli/playwright-cli.js"),
-  ].find(existsSync);
+    join(root, "lib/playwright-cli/playwright-cli.js"),
+    join(root, "vendor/playwright-cli/playwright-cli.js"),
+  ].filter(existsSync).find(playwrightCliIsUsable);
   if (jsEntry) return IS_WINDOWS ? `node ${jsEntry}` : jsEntry;
   return "playwright-cli-multi-tab";
 }
@@ -1470,18 +1523,22 @@ export function resolvePlaywrightCli(): string {
 /**
  * Make sure a daemon process manager is available, offering to install oxmgr
  * (default No; --yes approves). An explicit RECH_DAEMON_MANAGER=pm2 is respected,
- * since installing oxmgr would not satisfy it.
+ * since installing oxmgr would not satisfy it. When only the deprecated pm2 fallback
+ * is available (POSIX without oxmgr), the offer is made too, but declining keeps pm2.
  */
 async function ensureDaemonManager(ask: (q: string, def?: string) => Promise<string>, yes = false): Promise<void> {
+  let fallback: DaemonManager | undefined;
   try {
-    daemonManager();
-    return;
+    fallback = daemonManager();
+    if (!isDeprecatedPm2Fallback(fallback, { isWindows: IS_WINDOWS, override: process.env.RECH_DAEMON_MANAGER })) return;
   } catch (error) {
     if (process.env.RECH_DAEMON_MANAGER?.toLowerCase() === "pm2") throw error;
   }
   const command = oxmgrInstallCommand(process.env);
-  const answer = yes ? "yes" : (await ask(`      oxmgr is missing. Install globally with \`${command.join(" ")}\`? [y/N]: `)).trim();
+  const reason = fallback ? "Only the deprecated pm2 is available" : "oxmgr is missing";
+  const answer = yes ? "yes" : (await ask(`      ${reason}. Install oxmgr globally with \`${command.join(" ")}\`? [y/N]: `)).trim();
   if (!/^(y|yes)$/i.test(answer)) {
+    if (fallback) return; // keep the working pm2 setup
     throw new Error(`Setup cancelled. To install oxmgr, run \`${command.join(" ")}\`, then rerun setup.`);
   }
   console.log(`      Installing oxmgr: ${command.join(" ")}`);
@@ -1536,6 +1593,22 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
 
   // Drop any prior registration (current + legacy names) before re-adding.
   for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
+  // Migrating from pm2 to oxmgr: a serve still registered in pm2 would hold the port and be
+  // resurrected at login, fighting the oxmgr-managed one. Remove it from pm2 too.
+  const pm2Bin = mgr.id === "oxmgr" ? Bun.which("pm2") : null;
+  if (pm2Bin) {
+    const pm2: DaemonManager = { id: "pm2", bin: pm2Bin };
+    const listed = await pmList(pm2).catch(() => "");
+    const stale = [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES].filter(name => listsProcess("pm2", listed, name));
+    if (stale.length) {
+      console.log(`      Migrating from pm2: removing ${stale.join(", ")}`);
+      for (const name of stale) await runPm(pm2, ["delete", name]);
+      // --force: pm2 won't save an empty list otherwise, keeping the old dump that `pm2 resurrect`
+      // would bring back at login to fight the oxmgr-managed serve over the port.
+      if (await runPm(pm2, ["save", "--force"]) !== 0)
+        console.warn("      pm2 save failed; run `pm2 save --force` so pm2 doesn't resurrect the old serve at login.");
+    }
+  }
 
   let startCode: number;
   if (mgr.id === "pm2") {
@@ -1574,7 +1647,7 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
 async function daemonUninstall(): Promise<void> {
   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"]);
+  if (mgr.id === "pm2") await runPm(mgr, ["save", "--force"]); // an emptied list must still overwrite the dump
   else await runPm(mgr, ["service", "uninstall"]);
   console.log(`Removed ${mgr.id} process: ${PM_PROCESS_NAME}`);
 }
@@ -2478,13 +2551,16 @@ async function status(): Promise<void> {
   // ReferenceError that took down the whole of `rech status`, so the one command
   // that reports "the relay is wedged" died exactly when the relay was wedged,
   // printing a stack trace instead of the restart hint.
-  if (pingBody?.degraded)
-    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; force it now with \`${daemonManager().id} restart ${PM_PROCESS_NAME}\``);
   // The daemon line is about this machine; a client of a remote host has no local daemon to report.
   const isHost = !!(await readListeners().catch(() => null));
+  // No oxmgr/pm2 on PATH must not take down `rech status`: report it instead of throwing.
+  let mgr: DaemonManager | undefined;
+  if (isHost) try { mgr = daemonManager(); } catch { /* reported below */ }
+  if (pingBody?.degraded)
+    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; ${isHost ? `force it now with \`${mgr?.id ?? "oxmgr"} restart ${PM_PROCESS_NAME}\`` : "the daemon host can restart it"}`);
   if (isHost) {
-    const daemonRegistered = (await pmList()).includes(PM_PROCESS_NAME);
-    console.log(`daemon:   ${daemonRegistered ? `${daemonManager().id} (${PM_PROCESS_NAME})` : "not installed"}`);
+    const daemonRegistered = mgr ? listsProcess(mgr.id, await pmList(mgr).catch(() => ""), PM_PROCESS_NAME) : false;
+    console.log(`daemon:   ${daemonRegistered ? `${mgr!.id} (${PM_PROCESS_NAME})` : mgr ? "not installed" : "not installed (no oxmgr or pm2 on PATH)"}`);
   }
   // Same resolution as a command: ?profile= in the URL, else PLAYWRIGHT_MCP_PROFILE_DIRECTORY.
   const effective = resolveEffectiveProfile(parsed.profileDirectory);
@@ -2586,7 +2662,8 @@ export function rechCli(argv: string[], handlers: RechHandlers) {
         ? handlers.urlList()
         : handlers.printProfileUri(a.profile, a.listener, { local: a.local, save: a.save }))
     .command("connect <url>", "Use a URL from another machine in this project (checks it first)", y => y
-      .positional("url", { type: "string", demandOption: true }),
+      .positional("url", { type: "string", demandOption: true, describe: "The URL printed by `rech url <profile>` on the machine with Chrome. Quote it: it contains #" })
+      .example("rech connect 'https://host.example.js.net/rechrome/?profile=you%40example.com#key=…'", ""),
       a => handlers.connect(a.url))
     .command(["listener", "listeners"], "Control who can connect: listeners, allowed profiles, keys, public URLs", y => y
       .command(["ls", "list", "$0"], "List listeners (keys hidden)", {}, () => handlers.listListeners())
@@ -2630,8 +2707,16 @@ export function rechCli(argv: string[], handlers: RechHandlers) {
     .demandCommand(1)
     .strict()
     .help()
+    .alias("help", "h")
     .version(false)
-    .fail((message, error) => { throw error ?? new Error(message); });
+    // A parse error (missing argument, unknown option…) shows that command's help above the
+    // error, so the fix is visible. Errors thrown by a command's own handler pass through.
+    .fail((message, error, y) => {
+      if (error) throw error;
+      // Straight to stderr: Bun's console.error would paint the whole help red.
+      y.showHelp((help: string) => process.stderr.write(`${help}\n\n`));
+      throw new Error(`rech: ${/^Not enough non-option arguments/.test(message) ? "missing a required argument; see the usage line above" : message}`);
+    });
 }
 
 if (import.meta.main) {

package/rechrome.ts

@@ -10,9 +10,10 @@ import { hostname, homedir, networkInterfaces } from "os";
 import { isIPv4 } from "net";
 import { join, basename, dirname } from "path";
 import { pathToFileURL } from "url";
+import { createRequire } from "node:module";
 import { spawn as cpSpawn } from "child_process";
 import { readFile, writeFile, rename, chmod, mkdir } from "node:fs/promises";
-import { oxmgrInstallCommand, pickDaemonManager, type DaemonManager } from "./daemon-manager.ts";
+import { isDeprecatedPm2Fallback, listsProcess, oxmgrInstallCommand, pickDaemonManager, PM2_DEPRECATION, type DaemonManager } from "./daemon-manager.ts";
 
 export const ENV_KEY = "RECHROME_URL";
 export const DEFAULT_PORT = 13775;
@@ -976,15 +977,45 @@ async function callServe(
     console.error(`[rech] rech-client -> rech-server[ok]\n  -x: bearer key rejected (used: ${key.slice(0, 4)}...) -> playwright[unknown]`);
     process.exit(1);
   }
-  return res.json();
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Not the daemon answering, e.g. a reverse proxy's 404 because the URL's path prefix is wrong.
+    const detail = `HTTP ${res.status} from ${serviceUrl(url, "run")} is not a rechrome daemon response: ${text.slice(0, 200).trim()}`;
+    if (throwOnFailure) throw new Error(detail);
+    console.error(`[rech] rech-client -> ${serviceUrl(url, "run")}\n  -x: ${detail}`);
+    process.exit(1);
+  }
 }
 
+const BOOLEAN_OPEN_FLAGS = new Set(["--headed", "--persistent", "--in-memory", "--extension"]);
+
 export function normalizeCommandArgs(args: string[]): string[] {
   const normalized = [...args];
   if (normalized[0] === "tabs" || normalized[0] === "list") normalized[0] = "tab-list";
+  // `rech open hello.com`: profile-scoped listeners accept only HTTP(S)/about:blank targets, so
+  // give a bare host an https:// scheme the way a browser address bar would.
+  if (["open", "goto", "tab-new"].includes(normalized[0])) {
+    // The target is the first positional. A token after a `--flag` without `=` is that flag's
+    // value (`open --profile my-profile url`), unless the flag is a known boolean.
+    const takesValue = (flag: string) => flag.startsWith("-") && !flag.includes("=") && !BOOLEAN_OPEN_FLAGS.has(flag);
+    const i = normalized.findIndex((a, idx) => idx > 0 && !a.startsWith("-") && !takesValue(normalized[idx - 1]!));
+    if (i > 0) normalized[i] = withDefaultScheme(normalized[i]!);
+  }
   return normalized;
 }
 
+/** `hello.com` -> `https://hello.com`, `localhost:3000` -> `http://localhost:3000`; URLs with a scheme and paths are unchanged. */
+export function withDefaultScheme(target: string): string {
+  if (/^[./\\~]/.test(target) || /^[a-z]:[\\/]/i.test(target)) return target; // a file path, not a host
+  if (/^[a-z][a-z0-9+.-]*:/i.test(target) && !/^[^/:]+:\d+(\/|$|[?#])/.test(target)) return target;
+  // Loopback by exact hostname: `localhost.example.com` / `127.example.com` are public hosts.
+  const host = (target.match(/^(\[[^\]]*\]|[^/:?#]*)/)?.[1] ?? "").toLowerCase();
+  const loopback = host === "localhost" || host === "[::1]" || /^127(\.\d{1,3}){3}$/.test(host);
+  return loopback ? `http://${target}` : `https://${target}`;
+}
+
 // Pull a global `--profile <val>` / `--profile=<val>` out of the leading flags of an argv.
 // Only flags before the first positional (the playwright subcommand) are rech globals — a
 // --profile at/after the subcommand belongs to the forwarded CLI (e.g. playwright-cli's own
@@ -1115,7 +1146,9 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
   }
   if (stderr) {
     if (stderr.includes('Extension connection timeout')) {
-      const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"];
+      // The daemon resolves registered profiles' bridge tokens itself and then asks for a reload;
+      // only blame a missing install when neither side had credentials.
+      const hasToken = !!effectiveEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] || /reload the .*extension/i.test(stderr);
       const last = hasToken
         ? `  -x: extension did not connect (reload it at chrome://extensions; then verify its token) -> extension[degraded]`
         : `  -> extension[not installed]  (run: rech setup)`;
@@ -1404,6 +1437,8 @@ function daemonManager(): DaemonManager {
     isWindows: IS_WINDOWS,
     override: process.env.RECH_DAEMON_MANAGER,
   });
+  if (isDeprecatedPm2Fallback(_daemonMgr, { isWindows: IS_WINDOWS, override: process.env.RECH_DAEMON_MANAGER }))
+    console.error(`[rech] warning: using pm2 because oxmgr is not on PATH. ${PM2_DEPRECATION}`);
   return _daemonMgr;
 }
 
@@ -1440,29 +1475,47 @@ async function oxmgrEnsureAutostart(mgr: DaemonManager): Promise<void> {
 }
 
 // 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.
+// Match a name in it with listsProcess, not a substring test.
 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();
 }
 
+// A candidate playwright-cli entry is usable only if the playwright-core it requires actually
+// resolves FROM that entry — the wrapper does `require('playwright-core/lib/tools/cli-client/program')`,
+// a deep subpath reachable only through the fork's patched `exports` map. existsSync on the .js is
+// not the same check: an uninitialised/half-built lib/playwright-cli submodule leaves the wrapper on
+// disk with no resolvable core, and the failure surfaces later as MODULE_NOT_FOUND inside the daemon.
+export function playwrightCliIsUsable(jsEntry: string): boolean {
+  try {
+    createRequire(jsEntry).resolve("playwright-core/lib/tools/cli-client/program");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // Resolve which playwright-cli the daemon runs to drive Chrome. Priority:
 //   1. PLAYWRIGHT_CLI env override — explicit, already a full command string.
 //   2. Vendored fork in a git checkout (lib/playwright-cli/playwright-cli.js) — the patched
 //      multi-tab CLI + patched playwright-core (PLAYWRIGHT_MCP_PROFILE_DIRECTORY etc.).
 //   3. The fork bundled into the npm tarball (vendor/playwright-cli/playwright-cli.js, produced by
-//      scripts/vendor-cli.sh at prepublish). This is the batteries-included default for
-//      `bun i -g rechrome`: self-contained, no @playwright/cli dep, no browser-binary download.
+//      scripts/vendor-cli.sh at prepublish, and by `prepare` on `bun install` in a checkout). This
+//      is the batteries-included default for `bun i -g rechrome`: self-contained, no
+//      @playwright/cli dep, no browser-binary download.
 //   4. Bare `playwright-cli-multi-tab` on PATH — legacy fallback for a pre-existing global link.
+// Candidates 2–3 must also pass playwrightCliIsUsable(), so a present-but-broken one falls through.
+// lib/ stays ahead of vendor/ on purpose: a dev who built the fork wants their patched core, not
+// the (possibly older) vendor-src snapshot that `prepare` unpacks into vendor/.
 // A resolved .js entry is run through `node` on Windows (which can't exec a .js by shebang) and
 // bare on POSIX (its `#!/usr/bin/env node` shebang runs it under node, which the relay handshake
 // needs — see daemonInstall). serve splits the result on spaces into argv.
-export function resolvePlaywrightCli(): string {
+export function resolvePlaywrightCli(root: string = import.meta.dir): string {
   if (process.env.PLAYWRIGHT_CLI) return process.env.PLAYWRIGHT_CLI;
   const jsEntry = [
-    join(import.meta.dir, "lib/playwright-cli/playwright-cli.js"),
-    join(import.meta.dir, "vendor/playwright-cli/playwright-cli.js"),
-  ].find(existsSync);
+    join(root, "lib/playwright-cli/playwright-cli.js"),
+    join(root, "vendor/playwright-cli/playwright-cli.js"),
+  ].filter(existsSync).find(playwrightCliIsUsable);
   if (jsEntry) return IS_WINDOWS ? `node ${jsEntry}` : jsEntry;
   return "playwright-cli-multi-tab";
 }
@@ -1470,18 +1523,22 @@ export function resolvePlaywrightCli(): string {
 /**
  * Make sure a daemon process manager is available, offering to install oxmgr
  * (default No; --yes approves). An explicit RECH_DAEMON_MANAGER=pm2 is respected,
- * since installing oxmgr would not satisfy it.
+ * since installing oxmgr would not satisfy it. When only the deprecated pm2 fallback
+ * is available (POSIX without oxmgr), the offer is made too, but declining keeps pm2.
  */
 async function ensureDaemonManager(ask: (q: string, def?: string) => Promise<string>, yes = false): Promise<void> {
+  let fallback: DaemonManager | undefined;
   try {
-    daemonManager();
-    return;
+    fallback = daemonManager();
+    if (!isDeprecatedPm2Fallback(fallback, { isWindows: IS_WINDOWS, override: process.env.RECH_DAEMON_MANAGER })) return;
   } catch (error) {
     if (process.env.RECH_DAEMON_MANAGER?.toLowerCase() === "pm2") throw error;
   }
   const command = oxmgrInstallCommand(process.env);
-  const answer = yes ? "yes" : (await ask(`      oxmgr is missing. Install globally with \`${command.join(" ")}\`? [y/N]: `)).trim();
+  const reason = fallback ? "Only the deprecated pm2 is available" : "oxmgr is missing";
+  const answer = yes ? "yes" : (await ask(`      ${reason}. Install oxmgr globally with \`${command.join(" ")}\`? [y/N]: `)).trim();
   if (!/^(y|yes)$/i.test(answer)) {
+    if (fallback) return; // keep the working pm2 setup
     throw new Error(`Setup cancelled. To install oxmgr, run \`${command.join(" ")}\`, then rerun setup.`);
   }
   console.log(`      Installing oxmgr: ${command.join(" ")}`);
@@ -1536,6 +1593,22 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
 
   // Drop any prior registration (current + legacy names) before re-adding.
   for (const name of [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES]) await runPm(mgr, ["delete", name]);
+  // Migrating from pm2 to oxmgr: a serve still registered in pm2 would hold the port and be
+  // resurrected at login, fighting the oxmgr-managed one. Remove it from pm2 too.
+  const pm2Bin = mgr.id === "oxmgr" ? Bun.which("pm2") : null;
+  if (pm2Bin) {
+    const pm2: DaemonManager = { id: "pm2", bin: pm2Bin };
+    const listed = await pmList(pm2).catch(() => "");
+    const stale = [PM_PROCESS_NAME, ...LEGACY_PROCESS_NAMES].filter(name => listsProcess("pm2", listed, name));
+    if (stale.length) {
+      console.log(`      Migrating from pm2: removing ${stale.join(", ")}`);
+      for (const name of stale) await runPm(pm2, ["delete", name]);
+      // --force: pm2 won't save an empty list otherwise, keeping the old dump that `pm2 resurrect`
+      // would bring back at login to fight the oxmgr-managed serve over the port.
+      if (await runPm(pm2, ["save", "--force"]) !== 0)
+        console.warn("      pm2 save failed; run `pm2 save --force` so pm2 doesn't resurrect the old serve at login.");
+    }
+  }
 
   let startCode: number;
   if (mgr.id === "pm2") {
@@ -1574,7 +1647,7 @@ export async function daemonInstall(serveUrl: string): Promise<void> {
 async function daemonUninstall(): Promise<void> {
   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"]);
+  if (mgr.id === "pm2") await runPm(mgr, ["save", "--force"]); // an emptied list must still overwrite the dump
   else await runPm(mgr, ["service", "uninstall"]);
   console.log(`Removed ${mgr.id} process: ${PM_PROCESS_NAME}`);
 }
@@ -2478,13 +2551,16 @@ async function status(): Promise<void> {
   // ReferenceError that took down the whole of `rech status`, so the one command
   // that reports "the relay is wedged" died exactly when the relay was wedged,
   // printing a stack trace instead of the restart hint.
-  if (pingBody?.degraded)
-    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; force it now with \`${daemonManager().id} restart ${PM_PROCESS_NAME}\``);
   // The daemon line is about this machine; a client of a remote host has no local daemon to report.
   const isHost = !!(await readListeners().catch(() => null));
+  // No oxmgr/pm2 on PATH must not take down `rech status`: report it instead of throwing.
+  let mgr: DaemonManager | undefined;
+  if (isHost) try { mgr = daemonManager(); } catch { /* reported below */ }
+  if (pingBody?.degraded)
+    console.log(`relay:    ⚠ degraded (${pingBody.consecutiveTimeouts} consecutive command timeouts) — if it persists, the daemon self-restarts; ${isHost ? `force it now with \`${mgr?.id ?? "oxmgr"} restart ${PM_PROCESS_NAME}\`` : "the daemon host can restart it"}`);
   if (isHost) {
-    const daemonRegistered = (await pmList()).includes(PM_PROCESS_NAME);
-    console.log(`daemon:   ${daemonRegistered ? `${daemonManager().id} (${PM_PROCESS_NAME})` : "not installed"}`);
+    const daemonRegistered = mgr ? listsProcess(mgr.id, await pmList(mgr).catch(() => ""), PM_PROCESS_NAME) : false;
+    console.log(`daemon:   ${daemonRegistered ? `${mgr!.id} (${PM_PROCESS_NAME})` : mgr ? "not installed" : "not installed (no oxmgr or pm2 on PATH)"}`);
   }
   // Same resolution as a command: ?profile= in the URL, else PLAYWRIGHT_MCP_PROFILE_DIRECTORY.
   const effective = resolveEffectiveProfile(parsed.profileDirectory);
@@ -2586,7 +2662,8 @@ export function rechCli(argv: string[], handlers: RechHandlers) {
         ? handlers.urlList()
         : handlers.printProfileUri(a.profile, a.listener, { local: a.local, save: a.save }))
     .command("connect <url>", "Use a URL from another machine in this project (checks it first)", y => y
-      .positional("url", { type: "string", demandOption: true }),
+      .positional("url", { type: "string", demandOption: true, describe: "The URL printed by `rech url <profile>` on the machine with Chrome. Quote it: it contains #" })
+      .example("rech connect 'https://host.example.ts.net/rechrome/?profile=you%40example.com#key=…'", ""),
       a => handlers.connect(a.url))
     .command(["listener", "listeners"], "Control who can connect: listeners, allowed profiles, keys, public URLs", y => y
       .command(["ls", "list", "$0"], "List listeners (keys hidden)", {}, () => handlers.listListeners())
@@ -2630,8 +2707,16 @@ export function rechCli(argv: string[], handlers: RechHandlers) {
     .demandCommand(1)
     .strict()
     .help()
+    .alias("help", "h")
     .version(false)
-    .fail((message, error) => { throw error ?? new Error(message); });
+    // A parse error (missing argument, unknown option…) shows that command's help above the
+    // error, so the fix is visible. Errors thrown by a command's own handler pass through.
+    .fail((message, error, y) => {
+      if (error) throw error;
+      // Straight to stderr: Bun's console.error would paint the whole help red.
+      y.showHelp((help: string) => process.stderr.write(`${help}\n\n`));
+      throw new Error(`rech: ${/^Not enough non-option arguments/.test(message) ? "missing a required argument; see the usage line above" : message}`);
+    });
 }
 
 if (import.meta.main) {