pi-browser-harness 0.10.2 → 0.11.0

package/src/cdp/discovery.ts

@@ -2,20 +2,24 @@ import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { connect as netConnect } from "node:net";
 import { request as httpRequest } from "node:http";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
 import { type Result, err, ok } from "../util/result";
 import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
+import { errnoCode } from "../util/guards";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
 
-/**
- * A live CDP endpoint plus, when discovery went through a DevToolsActivePort
- * file, the user-data-dir that file lives in. That directory is the browser's
- * profile registry (`Local State`) — Chromium writes DevToolsActivePort to
- * chrome::DIR_USER_DATA — so it is what profile selection enumerates.
- * Undefined when the endpoint came from BU_CDP_WS or a bare port probe.
- */
+const VersionResponse = Type.Object(
+  { webSocketDebuggerUrl: Type.Optional(Type.String()) },
+  { additionalProperties: true },
+);
+
+const versionValidator = Compile(VersionResponse);
+
 export type CdpEndpoint = {
   readonly wsUrl: string;
   readonly userDataDir?: string;
@@ -52,17 +56,9 @@ const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
   ));
 };
 
-// Fast, single-shot TCP check (no retry loop). Used to skip stale
-// DevToolsActivePort files left behind by a browser that has since quit —
-// unlike waitForPort, this returns immediately instead of blocking ~30s.
 const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
 
-// Ask the live browser for its canonical webSocketDebuggerUrl via
-// http://127.0.0.1:<port>/json/version. This is authoritative: it avoids
-// trusting a path from a stale DevToolsActivePort file that may belong to a
-// different browser which has since exited (e.g. Chrome's stale file pointing
-// at 9222 while Brave actually owns the port now). Returns null if the endpoint
-// is unreachable, non-200, or doesn't expose a WS URL.
+// /json/version is authoritative: a stale DevToolsActivePort file may name a browser that has since exited while another now owns the port.
 const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null> =>
   new Promise<string | null>((resolve) => {
     const req = httpRequest(
@@ -76,13 +72,8 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
         const chunks: Buffer[] = [];
         res.on("data", (c: Buffer) => chunks.push(c));
         res.on("end", () => {
-          try {
-            const json = JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
-            const ws = json["webSocketDebuggerUrl"];
-            resolve(typeof ws === "string" ? ws : null);
-          } catch {
-            resolve(null);
-          }
+          const parsed = parseJson(Buffer.concat(chunks).toString("utf8"), versionValidator);
+          resolve(parsed.success ? parsed.data.webSocketDebuggerUrl ?? null : null);
         });
       },
     );
@@ -91,10 +82,6 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
     req.end();
   });
 
-// Well-known CDP ports to probe when no DevToolsActivePort file is readable
-// (sandboxed harness, restricted filesystem permissions, or an unusual profile
-// location not on the profileDirs list). The default Chromium remote-debugging
-// port is 9222; users can extend via BU_CDP_PORTS="9222,9333".
 const fallbackPorts = (): ReadonlyArray<number> => {
   const ports = new Set<number>([9222]);
   const fromEnv = process.env["BU_CDP_PORTS"];
@@ -111,21 +98,21 @@ type Candidate = {
   readonly port: number;
   readonly path: string;
   readonly mtimeMs: number;
-  /** The user-data-dir whose DevToolsActivePort produced this candidate. */
   readonly userDataDir: string;
 };
 
-/**
- * Locate a live CDP endpoint, reporting the user-data-dir it belongs to when
- * that is knowable. `discoverWsUrl` is the URL-only view of the same walk.
- */
+// Read here rather than in the client: the daemon owns the only socket to Chrome, so an override the daemon cannot see has no effect.
+export const endpointFromEnv = (env: NodeJS.ProcessEnv = process.env): CdpEndpoint | undefined => {
+  const wsUrl = env["BU_CDP_WS"]?.trim();
+  return wsUrl ? { wsUrl } : undefined;
+};
+
 export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>> => {
+  const override = endpointFromEnv();
+  if (override) return ok(override);
+
   const dirs = userDataDirCandidates();
 
-  // Phase 1: collect every readable DevToolsActivePort candidate up front,
-  // rather than committing to the first one found. A single browser writes one
-  // such file, but stale files from quit browsers linger, so we must
-  // disambiguate below instead of trusting discovery order.
   const candidates: Candidate[] = [];
   const readErrors: string[] = [];
   for (const base of dirs) {
@@ -136,15 +123,10 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
       raw = await readFile(portFile, "utf8");
       try {
         mtimeMs = (await stat(portFile)).mtimeMs;
-      } catch {
-        // mtime is only a tiebreaker; a stat failure just leaves it at 0.
-      }
+      } catch {}
     } catch (e) {
-      // Node fs errors carry .code; see ErrnoException. ENOENT is normal — the
-      // dir is on our list but the user hasn't installed that browser. EPERM/
-      // EACCES is common under sandboxes; remember it and fall back to network
-      // probing rather than failing the whole discovery.
-      const code = (e as NodeJS.ErrnoException).code;
+      // EPERM/EACCES is common under sandboxes; remember it and fall back to network probing rather than failing the whole discovery.
+      const code = errnoCode(e);
       if (code === "ENOENT" || code === undefined) continue;
       if (code === "EPERM" || code === "EACCES") {
         readErrors.push(`${portFile}: ${code}`);
@@ -157,25 +139,16 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     const port = lines[0]?.trim();
     const path = lines[1]?.trim();
     if (!port || !path) continue;
-    // Guard against a truncated/corrupt port file (e.g. a non-numeric first
-    // line): an out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT
-    // synchronously, which would escape discoverWsUrl instead of surfacing as
-    // a Result error. Skip such entries.
+    // An out-of-range port makes net.connect throw ERR_SOCKET_BAD_PORT synchronously, escaping discoverWsUrl instead of surfacing as a Result error.
     const portNum = Number(port);
     if (!Number.isInteger(portNum) || portNum <= 0 || portNum >= 65536) continue;
     candidates.push({ port: portNum, path, mtimeMs, userDataDir: base });
   }
 
-  // Phase 2: no readable candidate — probe well-known ports directly. Covers
-  // sandboxed harnesses that can't read profile dirs and non-default install
-  // locations. Requires the browser to have been launched with
-  // --remote-debugging-port so /json/version is served.
   if (candidates.length === 0) {
     for (const port of fallbackPorts()) {
       if (!(await isPortLive(port))) continue;
       const live = await queryLiveWsUrl(port);
-      // No DevToolsActivePort file was involved, so the user-data-dir behind
-      // this endpoint is unknown — profile selection stays unavailable.
       if (live) return ok({ wsUrl: live });
     }
     const permHint = readErrors.length > 0
@@ -187,9 +160,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     ));
   }
 
-  // Phase 3: disambiguate candidates sharing a port (one browser running, and
-  // another's file left behind on the default 9222): keep the most-recently-
-  // written file — that's the currently-running browser.
   const byPort = new Map<number, Candidate>();
   for (const c of candidates) {
     const prev = byPort.get(c.port);
@@ -197,16 +167,11 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   }
   const unique = Array.from(byPort.values());
 
-  // Prefer candidates whose port is actually accepting connections; this skips
-  // stale files whose browser has quit (avoiding a ~30s waitForPort block).
   const liveChecks = await Promise.all(unique.map((c) => isPortLive(c.port)));
   const liveCandidates = unique.filter((_, i) => liveChecks[i]);
   const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
 
-  // Phase 4: for each candidate, prefer the browser's own canonical WS URL from
-  // /json/version. Some browsers disable that HTTP endpoint when remote
-  // debugging is toggled only via chrome://inspect (rather than a launch flag),
-  // so fall back to the WS path written in DevToolsActivePort.
+  // Some browsers disable the /json/version endpoint when remote debugging is toggled via chrome://inspect rather than a launch flag, hence the DevToolsActivePort fallback.
   let lastErr: Result<CdpEndpoint, CdpError> | null = null;
   for (const c of ordered) {
     const ready = await waitForPort(c.port);
@@ -218,10 +183,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
   }
 
-  // Every discovered candidate was stale/unreachable. Before giving up, try the
-  // well-known fallback ports — a user with a leftover DevToolsActivePort file
-  // may still have a live browser reachable via 9222 / BU_CDP_PORTS. (Skip ports
-  // already covered by a candidate above so we don't re-probe them.)
   for (const port of fallbackPorts()) {
     if (byPort.has(port) || !(await isPortLive(port))) continue;
     const liveUrl = await queryLiveWsUrl(port);
@@ -231,10 +192,6 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
 };
 
-/**
- * URL-only view of {@link discoverEndpoint}, kept as the stable entry point for
- * callers that don't care which user-data-dir answered.
- */
 export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
   const endpoint = await discoverEndpoint();
   return endpoint.success ? ok(endpoint.data.wsUrl) : endpoint;

package/src/cdp/errors.ts

@@ -12,6 +12,10 @@ export type CdpError = {
   readonly method?: string;
 };
 
+// Chrome reports a dead session as a generic protocol error, so the message text is the only signal that a reattach — not a retry — is what will fix it.
+export const classifyRemoteError = (message: string): CdpErrorKind =>
+  message.includes("Session with given id not found") ? "session_not_found" : "remote_error";
+
 export const cdpError = (
   kind: CdpErrorKind,
   message: string,

package/src/cdp/events.ts

@@ -0,0 +1,170 @@
+import { Type, type Static, type TSchema } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const ev = <P extends TSchema>(params: P) => ({ params, validate: Compile(params) });
+
+const open = { additionalProperties: true } as const;
+
+const Anything = Type.Object({}, open);
+
+const StackTrace = Type.Object(
+  {
+    callFrames: Type.Optional(
+      Type.Array(
+        Type.Object(
+          {
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            functionName: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      ),
+    ),
+  },
+  open,
+);
+
+const ConsoleArg = Type.Object(
+  {
+    type: Type.Optional(Type.String()),
+    value: Type.Optional(Type.Unknown()),
+    description: Type.Optional(Type.String()),
+    unserializableValue: Type.Optional(Type.String()),
+  },
+  open,
+);
+
+export const EVENTS = {
+  "Inspector.detached": ev(Anything),
+
+  "Page.javascriptDialogOpening": ev(
+    Type.Object(
+      {
+        type: Type.String(),
+        message: Type.String(),
+        defaultPrompt: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Page.loadEventFired": ev(Anything),
+  "Page.frameNavigated": ev(Anything),
+
+  "Runtime.consoleAPICalled": ev(
+    Type.Object(
+      {
+        type: Type.Optional(Type.String()),
+        args: Type.Optional(Type.Array(ConsoleArg)),
+        stackTrace: Type.Optional(StackTrace),
+      },
+      open,
+    ),
+  ),
+
+  "Log.entryAdded": ev(
+    Type.Object(
+      {
+        entry: Type.Object(
+          {
+            level: Type.Optional(Type.String()),
+            text: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String()),
+            lineNumber: Type.Optional(Type.Number()),
+            stackTrace: Type.Optional(StackTrace),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+
+  "Network.requestWillBeSent": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        request: Type.Object(
+          {
+            url: Type.String(),
+            method: Type.String(),
+            postData: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.responseReceived": ev(
+    Type.Object(
+      {
+        requestId: Type.String(),
+        response: Type.Optional(
+          Type.Object(
+            {
+              status: Type.Optional(Type.Number()),
+              statusText: Type.Optional(Type.String()),
+              mimeType: Type.Optional(Type.String()),
+            },
+            open,
+          ),
+        ),
+        type: Type.Optional(Type.String()),
+      },
+      open,
+    ),
+  ),
+  "Network.loadingFinished": ev(
+    Type.Object(
+      { requestId: Type.String(), encodedDataLength: Type.Optional(Type.Number()) },
+      open,
+    ),
+  ),
+  "Network.loadingFailed": ev(
+    Type.Object(
+      { requestId: Type.String(), errorText: Type.Optional(Type.String()) },
+      open,
+    ),
+  ),
+
+  "Target.targetCreated": ev(
+    Type.Object(
+      {
+        targetInfo: Type.Object(
+          {
+            targetId: Type.String(),
+            type: Type.String(),
+            openerId: Type.Optional(Type.String()),
+          },
+          open,
+        ),
+      },
+      open,
+    ),
+  ),
+  "Target.targetDestroyed": ev(Type.Object({ targetId: Type.String() }, open)),
+};
+
+export type CdpEventName = keyof typeof EVENTS;
+export type EventParamsOf<E extends CdpEventName> = Static<(typeof EVENTS)[E]["params"]>;
+
+export const isKnownEvent = (name: string): name is CdpEventName => Object.hasOwn(EVENTS, name);
+
+export const decodeEvent = <E extends CdpEventName>(
+  name: E,
+  raw: unknown,
+): Result<EventParamsOf<E>, CdpError> => {
+  const spec = EVENTS[name];
+  if (spec === undefined) {
+    return err(cdpError("invalid_response", "unknown CDP event", name));
+  }
+  if (!spec.validate.Check(raw)) {
+    const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
+    return err(cdpError("invalid_response", why, name));
+  }
+  return ok(raw as EventParamsOf<E>);
+};

package/src/cdp/network-buffer.ts

@@ -1,18 +1,5 @@
-/**
- * In-memory aggregator for CDP Network.* events.
- *
- * The CDP event stream is consumed by a single internal loop in session.ts.
- * That loop hands Network.* event params to this module, which joins them into
- * one record per requestId (request → response → finished/failed). Tools then
- * read records via drain(), filtered to what the caller asked for.
- *
- * Bounded by a fixed capacity (default 500): on overflow the oldest record is
- * evicted FIFO. The overflow flag is reported once per drain so tools can warn
- * the LLM that data may be missing.
- *
- * This module is pure (no CDP dependency) so the joining/filtering logic stays
- * trivially testable in isolation.
- */
+import { decodeEvent, type EventParamsOf } from "./events";
+import { createRecordStore } from "./record-store";
 
 export type NetworkRecord = {
   requestId: string;
@@ -22,34 +9,27 @@ export type NetworkRecord = {
   statusText?: string;
   type: string;
   mimeType?: string;
-  /** Wall-clock ms when requestWillBeSent fired, in Date.now() units. */
   requestStartedMs: number;
   durationMs?: number;
   requestBodySize: number;
   responseBodySize?: number;
   failed?: boolean;
   errorText?: string;
-  /** Populated by the tool layer via Network.getResponseBody, never by the aggregator. */
   body?: string | null;
 };
 
 export type NetworkFilter = {
-  /** Substring match by default. Wrap in slashes (`/foo/`) for regex. */
   urlPattern?: string;
   methodFilter?: string[];
   statusFilter?: { min?: number; max?: number };
   resourceTypes?: string[];
-  /** Only requests whose start is at most N ms ago. */
   sinceMs?: number;
-  /** Cap on the returned records. */
   limit?: number;
 };
 
 export type DrainResult = {
   readonly records: NetworkRecord[];
-  /** Total matches before `limit` was applied. */
   readonly total: number;
-  /** True if the ring buffer evicted at least one record since the last drain. */
   readonly bufferOverflowed: boolean;
 };
 
@@ -67,53 +47,41 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (url) => re.test(url);
-    } catch {
-      // Fall through to substring match if the pattern is not a valid regex.
-    }
+    } catch {}
   }
   return (url) => url.includes(pattern);
 };
 
+type UpdateEvent = "Network.responseReceived" | "Network.loadingFinished" | "Network.loadingFailed";
+
 export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
-  // Insertion-ordered map keyed by requestId. Map preserves insertion order in JS,
-  // so iteration gives us oldest-first eviction without a separate index.
-  const records = new Map<string, NetworkRecord>();
-  let overflowed = false;
-
-  const evictOldestIfFull = (): void => {
-    while (records.size >= capacity) {
-      const oldest = records.keys().next();
-      if (oldest.done) return;
-      records.delete(oldest.value);
-      overflowed = true;
-    }
+  const records = createRecordStore<string, NetworkRecord>(capacity);
+
+  // All three follow-up events say the same thing first: decode, find the request they belong to, give up quietly if it is gone.
+  const update = <E extends UpdateEvent>(
+    method: E,
+    p: unknown,
+    apply: (r: NetworkRecord, params: EventParamsOf<E>) => void,
+  ): void => {
+    const decoded = decodeEvent(method, p);
+    if (!decoded.success) return;
+    const id = decoded.data.requestId;
+    if (!id) return;
+    const r = records.get(id);
+    if (!r) return;
+    apply(r, decoded.data);
   };
 
   return {
     ingestRequestWillBeSent(p) {
-      // CDP boundary cast: Network.requestWillBeSent
-      const params = p as
-        | {
-            requestId?: string;
-            request?: {
-              url?: string;
-              method?: string;
-              postData?: string;
-              headers?: Record<string, string>;
-            };
-            type?: string;
-            timestamp?: number;
-            wallTime?: number;
-          }
-        | undefined;
+      const decoded = decodeEvent("Network.requestWillBeSent", p);
+      const params = decoded.success ? decoded.data : undefined;
       const id = params?.requestId;
-      const url = params?.request?.url;
-      const method = params?.request?.method;
+      const url = params?.request.url;
+      const method = params?.request.method;
       if (!id || !url || !method) return;
-      // Re-fired requestWillBeSent for the same id (e.g. redirect) — refresh in place.
       records.delete(id);
-      evictOldestIfFull();
-      const postData = params.request?.postData;
+      const postData = params.request.postData;
       records.set(id, {
         requestId: id,
         method,
@@ -125,54 +93,28 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
     },
 
     ingestResponseReceived(p) {
-      // CDP boundary cast: Network.responseReceived
-      const params = p as
-        | {
-            requestId?: string;
-            response?: {
-              status?: number;
-              statusText?: string;
-              mimeType?: string;
-            };
-            type?: string;
-          }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      if (params?.response?.status !== undefined) r.status = params.response.status;
-      if (params?.response?.statusText !== undefined && params.response.statusText !== "") r.statusText = params.response.statusText;
-      if (params?.response?.mimeType !== undefined) r.mimeType = params.response.mimeType;
-      // type is more accurate on responseReceived (CDP sometimes refines it)
-      if (params?.type !== undefined) r.type = params.type;
+      update("Network.responseReceived", p, (r, params) => {
+        if (params.response?.status !== undefined) r.status = params.response.status;
+        if (params.response?.statusText !== undefined && params.response.statusText !== "") r.statusText = params.response.statusText;
+        if (params.response?.mimeType !== undefined) r.mimeType = params.response.mimeType;
+        // type is more accurate on responseReceived (CDP sometimes refines it)
+        if (params.type !== undefined) r.type = params.type;
+      });
     },
 
     ingestLoadingFinished(p) {
-      // CDP boundary cast: Network.loadingFinished
-      const params = p as
-        | { requestId?: string; encodedDataLength?: number }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      if (params?.encodedDataLength !== undefined) r.responseBodySize = params.encodedDataLength;
-      r.durationMs = Date.now() - r.requestStartedMs;
+      update("Network.loadingFinished", p, (r, params) => {
+        if (params.encodedDataLength !== undefined) r.responseBodySize = params.encodedDataLength;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
     },
 
     ingestLoadingFailed(p) {
-      // CDP boundary cast: Network.loadingFailed
-      const params = p as
-        | { requestId?: string; errorText?: string; canceled?: boolean }
-        | undefined;
-      const id = params?.requestId;
-      if (!id) return;
-      const r = records.get(id);
-      if (!r) return;
-      r.failed = true;
-      if (params?.errorText !== undefined) r.errorText = params.errorText;
-      r.durationMs = Date.now() - r.requestStartedMs;
+      update("Network.loadingFailed", p, (r, params) => {
+        r.failed = true;
+        if (params.errorText !== undefined) r.errorText = params.errorText;
+        r.durationMs = Date.now() - r.requestStartedMs;
+      });
     },
 
     drain(filter) {
@@ -191,23 +133,14 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
         if (cutoff !== undefined && r.requestStartedMs < cutoff) continue;
         if (minStatus !== undefined && (r.status === undefined || r.status < minStatus)) continue;
         if (maxStatus !== undefined && (r.status === undefined || r.status > maxStatus)) continue;
-        // Clone so callers can mutate (e.g. attach body) without polluting the buffer.
         matched.push({ ...r });
       }
 
-      const total = matched.length;
-      const limit = Math.min(filter.limit ?? 50, 500);
-      const limited = matched.slice(-limit); // most recent N
-
-      const bufferOverflowed = overflowed;
-      overflowed = false;
-
-      return { records: limited, total, bufferOverflowed };
+      return records.page(matched, filter.limit);
     },
 
     clear() {
       records.clear();
-      overflowed = false;
     },
   };
 };

package/src/cdp/ownership.ts

@@ -1,28 +1,11 @@
-/**
- * Tracks which tab targetIds belong to this harness session.
- *
- * The harness attaches to the user's running Chrome, which is also full of
- * the user's own tabs. Without an ownership boundary the agent could attach
- * to (or close) personal tabs by accident. The registry is the single source
- * of truth for "did this session open that tab?".
- *
- * Mutations notify a single change listener so the orchestrator can persist
- * to disk via the existing BrowserState flow without the registry needing to
- * know about the pi storage API.
- */
-
 export type OwnershipRegistry = {
   add(targetId: string): void;
   remove(targetId: string): void;
   has(targetId: string): boolean;
   list(): ReadonlyArray<string>;
-  /** Replace the full set — used on restoreState to re-hydrate from disk. */
   replaceAll(ids: ReadonlyArray<string>): void;
   setHarnessWindow(targetId: string | undefined): void;
   harnessWindow(): string | undefined;
-  /** The real Chrome windowId of the dedicated harness window — the durable
-   *  identity of "the window this session initialized", surviving seed-tab
-   *  closure. Undefined until the window is created (or after teardown). */
   setHarnessWindowId(windowId: number | undefined): void;
   harnessWindowId(): number | undefined;
   onChange(cb: () => void): void;