feat(cdp): report a BU_CDP_WS pin in status, /browser-target and the prompt

Upstream 0.11.0 made BU_CDP_WS reach the daemon, and discoverEndpoint()
returns it before the fork's target is consulted. resolveCdpTarget() did
not know about it, so /browser-status and the system prompt named the
BU_CDP_HTTP/stored/default target while the daemon dialled the pinned URL,
and /browser-target claimed to switch browsers when it could not.

resolveCdpTarget() now puts BU_CDP_WS first, as a remote target with
source "ws". /browser-target warns that it takes precedence, as it already
did for BU_CDP_HTTP. Only host:port is ever shown: the path carries the
browser id and a proxied URL may carry a token. /browser-status does not
probe a pinned URL, since /json/version answering says nothing about
whether the pinned browser id is still current.

2 files changed, 66 insertions, 12 deletions

diff --git a/src/cdp/endpoint.ts b/src/cdp/endpoint.ts
index 96cf2ea..9cb21c6 100644
--- a/src/cdp/endpoint.ts
+++ b/src/cdp/endpoint.ts
@@ -16,10 +16,11 @@ export const DEFAULT_REMOTE_CDP = "10.88.0.25:9223";
 const LOCAL_ALIASES = new Set(["local", "localhost", "off", "none", "0", "no"]);
 
 /**
- * Where a target came from. "env" is BU_CDP_HTTP, "stored" is /browser-target,
- * "default" is this fork's built-in. Only "default" is allowed to fall back.
+ * Where a target came from. "ws" is upstream's BU_CDP_WS, "env" is BU_CDP_HTTP,
+ * "stored" is /browser-target, "default" is this fork's built-in. Only
+ * "default" is allowed to fall back.
  */
-export type CdpTargetSource = "env" | "stored" | "default";
+export type CdpTargetSource = "ws" | "env" | "stored" | "default";
 
 export type CdpTarget =
   | {
@@ -28,12 +29,17 @@ export type CdpTarget =
       readonly port: number;
       readonly source: CdpTargetSource;
     }
-  | { readonly kind: "local"; readonly source: Exclude<CdpTargetSource, "default"> }
+  | { readonly kind: "local"; readonly source: Exclude<CdpTargetSource, "default" | "ws"> }
   | { readonly kind: "invalid"; readonly raw: string; readonly reason: string; readonly source: CdpTargetSource };
 
 /**
- * Precedence: BU_CDP_HTTP, then the /browser-target choice, then the built-in
- * default.
+ * Precedence: BU_CDP_WS, then BU_CDP_HTTP, then the /browser-target choice,
+ * then the built-in default.
+ *
+ *   BU_CDP_WS    -> upstream's pinned WebSocket URL; discoverEndpoint() returns
+ *                   it before any of the rest is consulted, so it is reported
+ *                   here only so status, /browser-target and the prompt agree
+ *                   with what the daemon actually dials
  *
  *   "host:port"  -> that remote, and a failure to reach it is fatal
  *   local|off|…  -> upstream behaviour, this machine's own browser
@@ -57,6 +63,16 @@ export const resolveCdpTarget = (
   env: NodeJS.ProcessEnv = process.env,
   stored: string | null = null,
 ): CdpTarget => {
+  // FORK: mirror upstream's endpointFromEnv() in discovery.ts, which wins.
+  const pinnedWs = env["BU_CDP_WS"]?.trim();
+  if (pinnedWs) {
+    const parsed = parseWsUrl(pinnedWs);
+    if (!parsed) {
+      return { kind: "invalid", raw: redactWsUrl(pinnedWs), source: "ws", reason: "expected a ws:// or wss:// URL" };
+    }
+    return { kind: "remote", host: parsed.host, port: parsed.port, source: "ws" };
+  }
+
   const fromEnv = env["BU_CDP_HTTP"]?.trim();
   const fromStore = stored?.trim();
 
@@ -104,8 +120,38 @@ const parseHostPort = (value: string): { host: string; port: number } | null =>
   return { host, port };
 };
 
+/**
+ * host:port of a BU_CDP_WS URL. Only that much is ever shown: the path carries
+ * the browser's id, and a proxied endpoint may carry a token or credentials.
+ */
+const parseWsUrl = (value: string): { host: string; port: number } | null => {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "ws:" && url.protocol !== "wss:") return null;
+  const host = url.hostname.replace(/^\[(.*)\]$/, "$1");
+  if (!host) return null;
+  const port = url.port === "" ? (url.protocol === "wss:" ? 443 : 80) : Number(url.port);
+  return { host, port };
+};
+
+/** A BU_CDP_WS value safe to print: host:port when parseable, otherwise a placeholder. */
+export const redactWsUrl = (value: string): string => {
+  const parsed = parseWsUrl(value.trim());
+  return parsed ? `${parsed.host}:${parsed.port}` : "<unparseable URL>";
+};
+
 const sourceLabel = (source: CdpTargetSource): string =>
-  source === "env" ? "BU_CDP_HTTP" : source === "stored" ? "/browser-target" : "built-in default";
+  source === "ws"
+    ? "BU_CDP_WS, pinned WebSocket"
+    : source === "env"
+      ? "BU_CDP_HTTP"
+      : source === "stored"
+        ? "/browser-target"
+        : "built-in default";
 
 /** One-line description for /browser-status and error messages. */
 export const describeCdpTarget = (target: CdpTarget): string => {
diff --git a/src/index.ts b/src/index.ts
index e4d23f8..f80c028 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,7 +11,7 @@ import { restoreDownloadBehavior } from "./domains/files";
 import { createDaemonTransport } from "./daemon/transport";
 import { setDebugClicks } from "./util/debug";
 import { asBoolean, asString } from "./util/guards";
-import { describeCdpTarget, isValidTargetValue, localAliases, resolveCdpTarget } from "./cdp/endpoint";
+import { describeCdpTarget, isValidTargetValue, localAliases, redactWsUrl, resolveCdpTarget } from "./cdp/endpoint";
 import { clearTarget, readTarget, writeTarget } from "./cdp/target-store";
 import { ensureDaemon, stopDaemon } from "./daemon/spawn";
 import { queryLiveWsUrl } from "./cdp/discovery";
@@ -50,8 +50,12 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
       // when it is really just "not needed yet", so say which it is, and show
       // what we would connect to.
       const target = resolveCdpTarget(process.env, await readTarget());
+      // FORK: a BU_CDP_WS pin is not probed: /json/version answering says nothing
+      // about whether the browser id pinned in that URL is still current.
       const reachable =
-        target.kind === "remote" ? (await queryLiveWsUrl(target.port, 2_000, target.host)) !== null : null;
+        target.kind === "remote" && target.source !== "ws"
+          ? (await queryLiveWsUrl(target.port, 2_000, target.host)) !== null
+          : null;
 
       const browserLine = s.alive
         ? "🟢 Connected"
@@ -61,7 +65,7 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
 
       const targetLine =
         target.kind === "remote"
-          ? `${describeCdpTarget(target)}${reachable ? " — reachable ✓" : " — unreachable ✗"}` +
+          ? `${describeCdpTarget(target)}${reachable === null ? "" : reachable ? " — reachable ✓" : " — unreachable ✗"}` +
             (reachable === false && target.source === "default"
               ? "\n         will fall back to this machine's browser"
               : "")
@@ -134,10 +138,14 @@ export default function browserHarnessExtension(pi: ExtensionAPI): void {
 
       // Warn rather than silently disobey: the environment deliberately wins,
       // so a stored choice made now would not take effect this session.
-      const envOverride = (process.env["BU_CDP_HTTP"] ?? "").trim();
+      // FORK: BU_CDP_WS outranks both (upstream reads it first); show only its host:port.
+      const wsOverride = (process.env["BU_CDP_WS"] ?? "").trim();
+      const httpOverride = (process.env["BU_CDP_HTTP"] ?? "").trim();
+      const envOverride =
+        wsOverride !== "" ? `BU_CDP_WS (${redactWsUrl(wsOverride)})` : httpOverride !== "" ? `BU_CDP_HTTP=${httpOverride}` : "";
       if (envOverride !== "") {
         ctx.ui.notify(
-          `Saved, but BU_CDP_HTTP=${envOverride} is set in this environment and takes precedence.\n` +
+          `Saved, but ${envOverride} is set in this environment and takes precedence.\n` +
             `Still using: ${describeCdpTarget(resolved)}`,
           "warning",
         );