pi-browser-harness 0.12.0 → 0.14.0

package/src/daemon/connection.ts

@@ -0,0 +1,323 @@
+import WebSocket from "ws";
+import { discoverWsUrl } from "../cdp/discovery";
+import {
+  CDP_ATTEMPT_LIFETIME_MS,
+  CDP_CONNECT_TIMEOUT_MS,
+  CDP_RECONNECT_COOLDOWN_MAX_MS,
+  CDP_RECONNECT_COOLDOWN_MS,
+} from "./protocol";
+import type { CdpError } from "../cdp/errors";
+import { type Result, err, ok } from "../util/result";
+
+// Why an attempt ended. Only "dropped" means clients were relying on a live Chrome connection
+// that went away unannounced; "failed" never got that far, "stopped" is the daemon's own doing,
+// and "superseded" is a closing socket that a newer attempt had already replaced.
+export type ConnectionEndReason = "failed" | "dropped" | "stopped" | "superseded";
+
+export type ConnectionEvents = {
+  readonly onMessage: (raw: string) => void;
+  // Fires exactly once per attempt. `generation` identifies the attempt so the caller can
+  // fail only the requests it sent on that socket.
+  readonly onEnd: (generation: number, reason: ConnectionEndReason) => void;
+};
+
+export type ChromeConnectionDependencies = {
+  readonly discoverWsUrl?: () => Promise<Result<string, CdpError>>;
+  readonly createWebSocket?: (url: string) => ChromeSocket;
+  // How long connect() waits before answering false while the dial carries on.
+  readonly connectTimeoutMs?: number;
+  // How long a dial stays open before it is abandoned as failed.
+  readonly attemptLifetimeMs?: number;
+  readonly cooldownMs?: number;
+  readonly cooldownMaxMs?: number;
+  readonly onAttemptSettled?: () => void;
+  readonly now?: () => number;
+};
+
+// What a caller that could not get a connection is looking at.
+export type ConnectionStatus =
+  | { readonly state: "open" }
+  // A dial is in progress; `pendingForMs` says for how long. No new prompt will be opened.
+  | { readonly state: "connecting"; readonly pendingForMs: number }
+  // The last dial failed; automatic re-dials resume after `retryInMs`.
+  | { readonly state: "cooldown"; readonly retryInMs: number; readonly lastFailure: string }
+  | { readonly state: "disconnected"; readonly lastFailure: string | null }
+  | { readonly state: "stopped" };
+
+export type ChromeConnection = {
+  // Clears a previous stop() and dials Chrome. Resolves true once the socket is open.
+  readonly start: () => Promise<boolean>;
+  // Dials Chrome unless already open, stopped or cooling down. Concurrent callers share the
+  // attempt in flight. Resolves true when open, or false once the attempt fails or the caller
+  // wait passes; in the latter case the dial itself keeps going.
+  readonly connect: () => Promise<boolean>;
+  // Explicit human demand: clears the cooldown and backoff, then connect().
+  readonly reconnectNow: () => Promise<boolean>;
+  readonly status: () => ConnectionStatus;
+  readonly isOpen: () => boolean;
+  // The generation of the current attempt or open socket; tag requests with it.
+  readonly generation: () => number;
+  readonly send: (payload: string) => Result<void, string>;
+  readonly stop: () => void;
+};
+
+type Attempt = {
+  readonly generation: number;
+  readonly startedAt: number;
+  readonly settledPromise: Promise<boolean>;
+  socket: ChromeSocket | null;
+  opened: boolean;
+  ended: boolean;
+  superseded: boolean;
+  failure: string | null;
+  readonly settle: (opened: boolean) => void;
+  readonly end: (reason: ConnectionEndReason) => void;
+};
+
+// The slice of ws's WebSocket the connection drives. Expressed structurally so a test can hand in
+// an EventEmitter-based fake without claiming to be the whole ws class.
+export type ChromeSocket = {
+  readonly readyState: number;
+  on(event: "open" | "close", listener: () => void): unknown;
+  on(event: "message", listener: (data: WebSocket.Data) => void): unknown;
+  on(event: "error", listener: (error: Error) => void): unknown;
+  send(data: string): void;
+  close(): void;
+};
+
+// ws delivers frames as a string, a Buffer, an ArrayBuffer or a list of Buffers.
+const wsDataToString = (data: WebSocket.Data): string => {
+  if (typeof data === "string") return data;
+  if (Array.isArray(data)) return Buffer.concat(data).toString("utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  return data.toString("utf8");
+};
+
+const closeSocket = (socket: ChromeSocket): void => {
+  if (socket.readyState === WebSocket.CLOSED) return;
+  try {
+    socket.close();
+  } catch {
+    // Closing an already-closing socket throws; the socket is gone either way.
+  }
+};
+
+// Resolves with the attempt's outcome, or false once `waitMs` passes while it is still dialing.
+const waitAtMost = (settled: Promise<boolean>, waitMs: number): Promise<boolean> => {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const gaveUp = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => { resolve(false); }, waitMs);
+  });
+  return Promise.race([settled, gaveUp]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+};
+
+// On-demand Chrome connection. Attempts happen only from start(), reconnectNow() and from
+// connect() while disconnected; a failed or dropped connection stays disconnected until the
+// next explicit browser demand. No background retry loop.
+//
+// One dial is one "Allow remote debugging" prompt in Chrome, so the design keeps prompts rare:
+// a dial lives for attemptLifetimeMs however long callers are willing to wait, every caller
+// joins the dial in flight instead of opening another, and after an outright failure no
+// automatic dial happens until a doubling cooldown passes. A dropped connection (Chrome closed,
+// the machine slept) carries no cooldown: the first re-dial after that is legitimate.
+export const createChromeConnection = (
+  deps: ChromeConnectionDependencies,
+  events: ConnectionEvents,
+): ChromeConnection => {
+  const {
+    discoverWsUrl: discover = discoverWsUrl,
+    createWebSocket = (url: string): ChromeSocket => new WebSocket(url, { perMessageDeflate: false }),
+    connectTimeoutMs = CDP_CONNECT_TIMEOUT_MS,
+    attemptLifetimeMs = CDP_ATTEMPT_LIFETIME_MS,
+    cooldownMs = CDP_RECONNECT_COOLDOWN_MS,
+    cooldownMaxMs = CDP_RECONNECT_COOLDOWN_MAX_MS,
+    onAttemptSettled,
+    now = Date.now,
+  } = deps;
+
+  let current: Attempt | null = null;
+  let stopped = false;
+  let lastGeneration = 0;
+  let cooldownUntil = 0;
+  let nextCooldownMs = cooldownMs;
+  let lastFailure: string | null = null;
+
+  const inCooldown = (): boolean => now() < cooldownUntil;
+
+  const recordFailure = (attempt: Attempt): void => {
+    lastFailure = attempt.failure ?? "connection attempt failed";
+    cooldownUntil = now() + nextCooldownMs;
+    nextCooldownMs = Math.min(nextCooldownMs * 2, cooldownMaxMs);
+  };
+
+  const recordSuccess = (): void => {
+    lastFailure = null;
+    cooldownUntil = 0;
+    nextCooldownMs = cooldownMs;
+  };
+
+  const startAttempt = (): Attempt => {
+    const generation = ++lastGeneration;
+    let resolveSettled: (opened: boolean) => void = () => undefined;
+    const settledPromise = new Promise<boolean>((resolve) => { resolveSettled = resolve; });
+    let settled = false;
+    // The whole dial, discovery included, is bounded by one lifetime timer.
+    let timer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+      attempt.failure ??= `no answer from Chrome within ${Math.round(attemptLifetimeMs / 1000)}s (was its "Allow remote debugging" prompt answered?)`;
+      attempt.end("failed");
+    }, attemptLifetimeMs);
+
+    const attempt: Attempt = {
+      generation,
+      startedAt: now(),
+      settledPromise,
+      socket: null,
+      opened: false,
+      ended: false,
+      superseded: false,
+      failure: null,
+      settle: (opened) => {
+        if (settled) return;
+        settled = true;
+        if (timer) { clearTimeout(timer); timer = null; }
+        resolveSettled(opened);
+        onAttemptSettled?.();
+      },
+      end: (reason) => {
+        if (attempt.ended) return;
+        attempt.ended = true;
+        if (current === attempt) current = null;
+        if (attempt.socket) closeSocket(attempt.socket);
+        if (reason === "failed") recordFailure(attempt);
+        attempt.settle(false);
+        events.onEnd(generation, reason);
+      },
+    };
+    return attempt;
+  };
+
+  const run = async (attempt: Attempt): Promise<void> => {
+    const d = await discover();
+    if (attempt.ended) return;
+    if (!d.success) {
+      attempt.failure = d.error.message;
+      attempt.end("failed");
+      return;
+    }
+
+    let socket: ChromeSocket;
+    try {
+      socket = createWebSocket(d.data);
+    } catch (e) {
+      attempt.failure = e instanceof Error ? e.message : String(e);
+      attempt.end("failed");
+      return;
+    }
+    attempt.socket = socket;
+
+    const endFromSocket = (): void => {
+      attempt.end(!attempt.opened ? "failed" : attempt.superseded ? "superseded" : "dropped");
+    };
+
+    socket.on("open", () => {
+      if (attempt.ended) { closeSocket(socket); return; }
+      try {
+        socket.send(JSON.stringify({ id: 0, method: "Target.setDiscoverTargets", params: { discover: true } }));
+      } catch (e) {
+        attempt.failure = e instanceof Error ? e.message : String(e);
+        attempt.end("failed");
+        return;
+      }
+      attempt.opened = true;
+      recordSuccess();
+      console.log("[pi-browser-daemon] Connected to Chrome ✓");
+      attempt.settle(true);
+    });
+    socket.on("message", (data: WebSocket.Data) => {
+      if (attempt.ended || !attempt.opened) return;
+      events.onMessage(wsDataToString(data));
+    });
+    socket.on("error", (e: Error) => {
+      attempt.failure ??= e.message;
+      endFromSocket();
+    });
+    socket.on("close", () => {
+      attempt.failure ??= "Chrome closed the connection before it opened (was its \"Allow remote debugging\" prompt denied?)";
+      endFromSocket();
+    });
+  };
+
+  const isOpen = (): boolean =>
+    current !== null && current.opened && current.socket?.readyState === WebSocket.OPEN;
+
+  const connect = (): Promise<boolean> => {
+    if (stopped) return Promise.resolve(false);
+    if (current) {
+      // A dial in flight is shared: joining it is what keeps Chrome's prompt count at one.
+      if (!current.opened) return waitAtMost(current.settledPromise, connectTimeoutMs);
+      if (isOpen()) return Promise.resolve(true);
+      // Opened once but closing now: Chrome is going away and the close event has not arrived
+      // yet. Start a fresh attempt at once; the old socket's close still fails its own requests.
+      current.superseded = true;
+      current = null;
+    }
+    if (inCooldown()) return Promise.resolve(false);
+
+    const attempt = startAttempt();
+    current = attempt;
+    run(attempt).catch((e: unknown) => {
+      attempt.failure ??= e instanceof Error ? e.message : String(e);
+      attempt.end("failed");
+    });
+    return waitAtMost(attempt.settledPromise, connectTimeoutMs);
+  };
+
+  const start = (): Promise<boolean> => {
+    stopped = false;
+    return connect();
+  };
+
+  const reconnectNow = (): Promise<boolean> => {
+    recordSuccess();
+    return start();
+  };
+
+  const stop = (): void => {
+    stopped = true;
+    const attempt = current;
+    current = null;
+    attempt?.end("stopped");
+  };
+
+  const status = (): ConnectionStatus => {
+    if (stopped) return { state: "stopped" };
+    if (isOpen()) return { state: "open" };
+    if (current && !current.opened) return { state: "connecting", pendingForMs: now() - current.startedAt };
+    if (inCooldown() && lastFailure !== null) return { state: "cooldown", retryInMs: cooldownUntil - now(), lastFailure };
+    return { state: "disconnected", lastFailure };
+  };
+
+  const send = (payload: string): Result<void, string> => {
+    const socket = current?.socket ?? null;
+    if (!socket || !isOpen()) return err("Chrome not connected");
+    try {
+      socket.send(payload);
+      return ok(undefined);
+    } catch (e) {
+      return err(e instanceof Error ? e.message : String(e));
+    }
+  };
+
+  return {
+    start,
+    connect,
+    reconnectNow,
+    status,
+    isOpen,
+    generation: () => current?.generation ?? 0,
+    send,
+    stop,
+  };
+};

package/src/daemon/index.ts

@@ -1,21 +1,77 @@
-import { createIpcServer } from "./server";
-import { createCdpBridge, type SendToClient } from "./bridge";
+import { createIpcServer, type IpcServer } from "./server";
+import { createCdpBridge, type CdpBridge, type SendToClient } from "./bridge";
 import { DAEMON_IDLE_TIMEOUT_MS } from "./protocol";
 
-async function main() {
-  console.log("[pi-browser-daemon] Starting...");
+export type DaemonDeps = {
+  readonly ipcServer?: IpcServer;
+  readonly cdpBridge?: CdpBridge;
+  readonly idleTimeoutMs?: number;
+  // Ends the process once shutdown has released the socket and the Chrome connection.
+  readonly exit?: (code: number) => void;
+  // One line per lifecycle event; defaults to the process's stdout.
+  readonly log?: (line: string) => void;
+};
+
+export type Daemon = {
+  // Listens on the IPC socket, connects to Chrome and arms the idle timer. Resolves once both are up.
+  readonly start: () => Promise<void>;
+  // Releases Chrome and the socket, then calls `exit(0)`. Idempotent.
+  readonly stop: () => Promise<void>;
+  readonly idleTimerArmed: () => boolean;
+};
+
+export const LOG_PREFIX = "[pi-browser-daemon]";
+
+export const describeError = (e: unknown): string => (e instanceof Error ? (e.stack ?? e.message) : String(e));
+
+// The composition the daemon process runs: request routing, event fan-out, client removal, the
+// idle timer and shutdown. Every collaborator is injectable so the wiring can be driven in-process.
+// The process entry that starts it lives in ./main.ts, so importing this module never launches a daemon.
+export const createDaemon = (deps: DaemonDeps = {}): Daemon => {
+  const ipcServer = deps.ipcServer ?? createIpcServer();
+  const cdpBridge = deps.cdpBridge ?? createCdpBridge();
+  const idleTimeoutMs = deps.idleTimeoutMs ?? DAEMON_IDLE_TIMEOUT_MS;
+  const exit = deps.exit ?? ((code: number): void => { process.exit(code); });
+  const log = deps.log ?? ((line: string): void => { console.log(`${LOG_PREFIX} ${line}`); });
 
-  const ipcServer = createIpcServer();
-  const cdpBridge = createCdpBridge();
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopping: Promise<void> | null = null;
+
+  const cancelIdleTimer = (): void => {
+    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+
+  const stop = (): Promise<void> => {
+    stopping ??= (async () => {
+      log("Shutting down...");
+      cancelIdleTimer();
+      await cdpBridge.stop();
+      await ipcServer.stop();
+      exit(0);
+    })();
+    return stopping;
+  };
+
+  const resetIdleTimer = (): void => {
+    cancelIdleTimer();
+    if (ipcServer.clientCount() === 0) {
+      idleTimer = setTimeout(() => {
+        idleTimer = null;
+        log(`Idle timeout — no clients for ${idleTimeoutMs / 60000} minutes. Shutting down.`);
+        void stop();
+      }, idleTimeoutMs);
+    }
+  };
 
   ipcServer.onMessage((msg, client) => {
+    // Control messages (register/deregister) are consumed by the server itself.
     if (msg.type !== "request") return;
 
     const send: SendToClient = (cid, resp) => {
       ipcServer.send(cid, resp);
     };
 
-    cdpBridge.handleRequest(msg, client.id, send);
+    void cdpBridge.handleRequest(msg, client.id, send);
   });
 
   cdpBridge.onEvent((event, targetClientIds) => {
@@ -29,7 +85,7 @@ async function main() {
   });
 
   cdpBridge.onClose(() => {
-    console.log("[pi-browser-daemon] Chrome disconnected");
+    log("Chrome disconnected");
     ipcServer.broadcast({
       type: "control",
       action: "shutdown",
@@ -37,50 +93,23 @@ async function main() {
     });
   });
 
-  let idleTimer: ReturnType<typeof setTimeout> | null = null;
-
-  const resetIdleTimer = (): void => {
-    if (idleTimer) clearTimeout(idleTimer);
-    if (ipcServer.clientCount() === 0) {
-      idleTimer = setTimeout(() => {
-        console.log("[pi-browser-daemon] Idle timeout — no clients for " +
-          `${DAEMON_IDLE_TIMEOUT_MS / 60000} minutes. Shutting down.`);
-        shutdown();
-      }, DAEMON_IDLE_TIMEOUT_MS);
-    }
-  };
-
-  const cancelIdleTimer = (): void => {
-    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
-  };
-
   ipcServer.onConnect(() => { cancelIdleTimer(); });
   ipcServer.onDisconnect(() => { resetIdleTimer(); });
 
-  try {
-    await ipcServer.start();
-    console.log("[pi-browser-daemon] IPC server listening");
-  } catch (e) {
-    console.error("[pi-browser-daemon] Failed to start IPC server:", e);
-    process.exit(1);
-  }
-
-  await cdpBridge.start();
+  const start = async (): Promise<void> => {
+    try {
+      await ipcServer.start();
+      log("IPC server listening");
+    } catch (e) {
+      log(`Failed to start IPC server: ${describeError(e)}`);
+      exit(1);
+      return;
+    }
 
-  resetIdleTimer();
+    await cdpBridge.start();
 
-  const shutdown = async () => {
-    console.log("[pi-browser-daemon] Shutting down...");
-    await cdpBridge.stop();
-    await ipcServer.stop();
-    process.exit(0);
+    resetIdleTimer();
   };
 
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-}
-
-main().catch((e) => {
-  console.error("[pi-browser-daemon] Fatal:", e);
-  process.exit(1);
-});
+  return { start, stop, idleTimerArmed: () => idleTimer !== null };
+};

package/src/daemon/lines.ts

@@ -0,0 +1,40 @@
+import type { Socket } from "node:net";
+
+// Newline-framed reader for the wire protocol. node:readline was used before, but it re-emits the
+// input socket's errors on its own Interface, and an Interface without an "error" listener turns an
+// ECONNRESET into an uncaught exception (it took pi down when the daemon was killed mid-probe).
+// This splitter never emits anything but lines; socket errors stay on the socket, where every
+// caller already handles them. A trailing partial line is delivered when the socket ends.
+export const readLines = (socket: Socket, onLine: (line: string) => void): (() => void) => {
+  // Held in an object: a plain `let` closed over here is narrowed to `true` by the compiler.
+  const state = { rest: "", active: true };
+  // Read through a call: `onLine` may dispose the reader mid-loop, which flow narrowing cannot see.
+  const stopped = (): boolean => !state.active;
+
+  const onData = (chunk: Buffer | string): void => {
+    if (stopped()) return;
+    state.rest += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    let nl = state.rest.indexOf("\n");
+    while (nl !== -1 && !stopped()) {
+      const line = state.rest.slice(0, nl);
+      state.rest = state.rest.slice(nl + 1);
+      onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+      nl = state.rest.indexOf("\n");
+    }
+  };
+  const onEnd = (): void => {
+    if (stopped() || state.rest === "") return;
+    const line = state.rest;
+    state.rest = "";
+    onLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+  };
+
+  socket.setEncoding("utf8");
+  socket.on("data", onData);
+  socket.on("end", onEnd);
+  return () => {
+    state.active = false;
+    socket.off("data", onData);
+    socket.off("end", onEnd);
+  };
+};

package/src/daemon/main.ts

@@ -0,0 +1,12 @@
+// The daemon process entry. spawn.ts launches this file under tsx; it starts the daemon
+// unconditionally, so nothing but the spawned process should import it.
+import { createDaemon, describeError, LOG_PREFIX } from "./index";
+
+console.log(`${LOG_PREFIX} Starting...`);
+const daemon = createDaemon();
+process.on("SIGINT", () => { void daemon.stop(); });
+process.on("SIGTERM", () => { void daemon.stop(); });
+daemon.start().catch((e: unknown) => {
+  console.error(`${LOG_PREFIX} Fatal: ${describeError(e)}`);
+  process.exit(1);
+});

package/src/daemon/protocol.ts

@@ -26,15 +26,41 @@ export type WireEvent = {
   readonly sessionId?: string;
 };
 
-export type WireControl = {
-  readonly type: "control";
-  readonly action: "register" | "registered" | "deregister" | "shutdown";
-  readonly clientId?: string;
-  readonly reason?: string;
-};
+export const CONTROL_ACTIONS = ["register", "registered", "deregister", "shutdown"] as const;
+
+export type ControlAction = (typeof CONTROL_ACTIONS)[number];
+
+// Each action carries exactly the fields it needs, so a handler that has matched on `action`
+// never has to re-check what the guard already proved.
+export type WireRegister = { readonly type: "control"; readonly action: "register"; readonly clientId: string };
+export type WireRegistered = { readonly type: "control"; readonly action: "registered"; readonly clientId: string };
+export type WireDeregister = { readonly type: "control"; readonly action: "deregister"; readonly clientId: string };
+export type WireShutdown = { readonly type: "control"; readonly action: "shutdown"; readonly reason?: string };
+
+export type WireControl = WireRegister | WireRegistered | WireDeregister | WireShutdown;
 
 export type WireMessage = WireRequest | WireResponse | WireEvent | WireControl;
 
+const isControlAction = (v: unknown): v is ControlAction =>
+  typeof v === "string" && CONTROL_ACTIONS.some((a) => a === v);
+
+const isOptionalString = (v: unknown): v is string | undefined => v === undefined || typeof v === "string";
+
+const isOptionalRecord = (v: unknown): v is Record<string, unknown> | undefined => v === undefined || isRecord(v);
+
+const isWireControl = (v: Record<string, unknown>): v is WireControl => {
+  const action = v["action"];
+  if (!isControlAction(action)) return false;
+  switch (action) {
+    case "register":
+    case "registered":
+    case "deregister":
+      return typeof v["clientId"] === "string";
+    case "shutdown":
+      return isOptionalString(v["reason"]);
+  }
+};
+
 const isWireMessage = (v: unknown): v is WireMessage => {
   if (!isRecord(v)) return false;
   const t = v["type"];
@@ -44,9 +70,8 @@ const isWireMessage = (v: unknown): v is WireMessage => {
     case "request": {
       if (typeof v["id"] !== "number") return false;
       if (typeof v["method"] !== "string") return false;
-      const sid = v["sessionId"];
-      if (sid !== undefined && typeof sid !== "string") return false;
-      return true;
+      if (!isOptionalRecord(v["params"])) return false;
+      return isOptionalString(v["sessionId"]);
     }
     case "response": {
       if (typeof v["id"] !== "number") return false;
@@ -55,28 +80,17 @@ const isWireMessage = (v: unknown): v is WireMessage => {
         if (!isRecord(errVal)) return false;
         if (typeof errVal["message"] !== "string") return false;
         if (typeof errVal["code"] !== "number") return false;
+        if (!isOptionalString(errVal["data"])) return false;
       }
       return true;
     }
     case "event": {
       if (typeof v["method"] !== "string") return false;
-      const sid = v["sessionId"];
-      if (sid !== undefined && typeof sid !== "string") return false;
-      return true;
-    }
-    case "control": {
-      const action = v["action"];
-      if (typeof action !== "string") return false;
-      if (!["register", "registered", "deregister", "shutdown"].includes(action)) return false;
-      const cid = v["clientId"];
-      if (
-        (action === "register" || action === "registered" || action === "deregister") &&
-        typeof cid !== "string"
-      ) {
-        return false;
-      }
-      return true;
+      if (!isOptionalRecord(v["params"])) return false;
+      return isOptionalString(v["sessionId"]);
     }
+    case "control":
+      return isWireControl(v);
     default:
       return false;
   }
@@ -105,6 +119,22 @@ export const DAEMON_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
 export const DAEMON_MAX_CLIENTS = 16;
 
+// How long a caller waits for a Chrome connection before being told "not connected". The dial
+// itself keeps going (see CDP_ATTEMPT_LIFETIME_MS): a human answering Chrome's "Allow remote
+// debugging" prompt takes longer than any tool call should block.
 export const CDP_CONNECT_TIMEOUT_MS = 10_000;
 
+// How long one dial stays open waiting for Chrome. One dial is one "Allow" prompt, so the attempt
+// must outlive a user who is away from the keyboard rather than be replaced by a fresh prompt.
+export const CDP_ATTEMPT_LIFETIME_MS = 5 * 60 * 1000;
+
+// After a dial fails outright (discovery failed, refused, denied, lifetime passed), no automatic
+// re-dial happens until this cooldown passes; it doubles per consecutive failure up to the cap.
+// An explicit Daemon.reconnect request (/browser-setup, /browser-reload-daemon) bypasses it.
+export const CDP_RECONNECT_COOLDOWN_MS = 30_000;
+export const CDP_RECONNECT_COOLDOWN_MAX_MS = 5 * 60 * 1000;
+
+// The one request the daemon answers itself: clears the reconnect cooldown and dials Chrome now.
+export const DAEMON_RECONNECT_METHOD = "Daemon.reconnect";
+
 export const CDP_COMMAND_TIMEOUT_MS = 10_000;