cdp-toolkit 1.10.0 → 1.11.0

package/src/bidi/driver.ts

@@ -40,11 +40,16 @@ import {
   type ScreenshotOptions, type ScreenshotResult, type ScrollOptions, type SnapshotNode, type UidStability,
   type BandConsumer, type CaptureDelivery,
 } from "../driver.ts";
-import { assertLeaseOk } from "../leases.ts";
+import { assertLeaseOk, defaultLabel } from "../leases.ts";
 import { resolveLiveLabel } from "../origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
 import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
 import { BidiConnection, BidiError, connectBidiSessionUrl } from "./client.ts";
+import {
+  acquireSessionSlot, releaseSessionSlot, SessionSlotBusyError,
+  type AcquireResult, type SessionSlotHandle,
+} from "./session-lease.ts";
+import { defaultMarionettePort, forceClearOrphanSession } from "./marionette.ts";
 import { takeStampedSnapshot } from "./snapshot.ts";
 import { selectRule, buildFulfillParams, effectiveAction } from "../tools/network_mock.ts";
 import type {
@@ -320,39 +325,174 @@ const BIDI_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
 // the only identity both modes share. getConnection retains a holder on every call (fresh or
 // reused); callers release() it.
 const connections = new Map<string, BidiConnection>();
+// This process's OWN Firefox BiDi session-slot ownership, keyed by endpoint (see session-lease.ts).
+// The slot LOCK is a file on disk — that is the cross-process source of truth — and this map is our
+// in-process record of which endpoints WE currently hold a live claim on, so dispose() releases
+// exactly the slots we took, and a re-dial after a dead socket reuses our own claim instead of
+// contending with our own pid. Populated in getConnection's create body; cleared on dispose() and
+// on a terminal dial failure that never established a session.
+const slotHandles = new Map<string, SessionSlotHandle>();
+// In-flight create dedup, keyed by endpoint. Two page() acquisitions can both cache-miss and call
+// getConnection concurrently; without this both would run the acquire+dial body, and the second
+// would either contend for the slot we just took (same pid → wait then SessionSlotBusyError against
+// ourselves) or open a second BiDi session. The first caller stores its create-promise here and
+// every other awaits it; cleared in a finally once the create settles.
+const connecting = new Map<string, Promise<BidiConnection>>();
+
+/**
+ * Release a slot claim we took in THIS getConnection call after a dial that never established a
+ * live session, so a later attempt re-acquires cleanly. When `owned` is true we did NOT acquire in
+ * this call (we reused a pre-existing claim — our previous socket died without dispose), so the
+ * handle predates this call and must be left intact: we still own Firefox's slot, only the socket
+ * failed to re-establish.
+ */
+async function releaseSlotOnDialFailure(endpoint: string, owned: boolean): Promise<void> {
+  if (owned) return;
+  const h = slotHandles.get(endpoint);
+  if (h) {
+    await releaseSessionSlot(h).catch(() => undefined);
+    slotHandles.delete(endpoint);
+  }
+}
+
+/**
+ * The actionable error for issue #4: Firefox is holding an orphaned BiDi session on this endpoint
+ * that Marionette recovery could NOT auto-clear (Firefox launched without --marionette, or the
+ * Marionette channel timed out / could not confirm). Distinguished from the live-busy case (issue
+ * #5, a LIVE lease holder) because here NO live process holds our lease — a session Firefox itself
+ * stranded is wedging the slot, and the fix is to enable Marionette or restart Firefox.
+ */
+function orphanNotClearedError(endpoint: string): DriverError {
+  return driverError("disconnected",
+    `Firefox holds an orphaned WebDriver BiDi session on ${endpoint} that could not be auto-cleared. ` +
+    `Marionette recovery needs Firefox launched with --marionette (default port 2828, or set ` +
+    `CDP_FIREFOX_MARIONETTE_PORT); otherwise restart Firefox to free the slot. (A client killed without ` +
+    `session.end can leave a session Firefox does not reap.)`);
+}
+
+// getConnection: the ONE Firefox-session choke point. Beyond memoizing a BidiConnection per endpoint
+// it now runs the cross-process SESSION-slot coordination (session-lease.ts) plus Marionette orphan
+// recovery (marionette.ts). Firefox serves exactly ONE WebDriver-BiDi session per browser, and it
+// never reaps an abandoned one (verified: still held 10s after an abrupt socket death). Two ills
+// follow that this closes: (#5) two LIVE processes attaching to one user-launched Firefox used to
+// hard-wedge on the raw "Maximum number of active sessions" with no way to tell a live holder from a
+// crash; the lease now names the LIVE holder and says wait-and-retry. (#4) a process killed without
+// session.end used to leave the slot occupied until Firefox restarted; when the lease shows the
+// prior holder's PID is DEAD, or Firefox itself still refuses on a re-dial, a blind Marionette
+// WebDriver:DeleteSession (which shares Firefox's one session slot) force-clears the orphan WITHOUT
+// killing the user's browser, and we retry. Marionette recovery is best-effort and degrades to a
+// clear, actionable error when Firefox has no --marionette port (the launch-mode norm).
 async function getConnection(endpoint: string, timeoutMs?: number): Promise<BidiConnection> {
   const existing = connections.get(endpoint);
   if (existing && existing.isOpen) { existing.retain(); return existing; }
   // A cached connection whose socket has died (ws.onclose fired) can only reject every
   // send() with "connection not open" — reusing it would strand the endpoint permanently.
-  // Evict it so the code below re-dials and creates a fresh BiDi session. No cleanup is
-  // needed: a dead connection already had `closed` set and rejectAll() cleared its per-call
-  // timers, and BidiConnection holds no heartbeat/keepalive resource to leak (see client.ts).
+  // Evict it so the code below re-dials and creates a fresh BiDi session. We deliberately do NOT
+  // release the session slot here: a dead socket is transient and WE still own Firefox's slot, so
+  // the create body below re-dials WITHOUT re-acquiring (its `owned` branch), avoiding a needless
+  // contention against our own pid. No other cleanup is needed: a dead connection already had
+  // `closed` set and rejectAll() cleared its per-call timers, and BidiConnection holds no
+  // heartbeat/keepalive resource to leak (see client.ts).
   if (existing) connections.delete(endpoint);
-  // Firefox 153's default unhandledPromptBehavior is "dismiss": a page-blocking alert()/confirm()
-  // gets auto-dismissed before handleDialog() ever runs, and Firefox's own userPromptOpened event
-  // reports handler:"dismiss" on it (verified: a bare session.new left "no such alert" on the very
-  // next handleUserPrompt call). Setting "ignore" here is what makes handleDialog() able to see
-  // and answer a live prompt at all.
-  const conn = await connectBidiSessionUrl(endpoint, {
-    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-    capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } },
-  }).catch((e: unknown) => {
-    // Firefox allows exactly ONE active BiDi session and never reaps an abandoned one (verified:
-    // still held 10s after an abrupt socket death). A client killed without session.end therefore
-    // leaves the slot occupied until Firefox restarts, and the raw wire message ("Maximum number of
-    // active sessions") tells the user nothing about how to get unstuck. Force-ending a session we
-    // do not own is not an option (there is no id to end), so this maps the error to instructions.
-    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
-      throw driverError("disconnected",
-        `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` +
-        `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` +
-        `session that Firefox does not reap.)`);
+
+  // Concurrency: dedup in-flight creates on this endpoint. An awaiter shares the create's outcome
+  // but needs its OWN holder — the create's connectBidiSessionUrl retains exactly once, for the
+  // caller that started it, so every other caller retains again for itself (callers all release()).
+  const inflight = connecting.get(endpoint);
+  if (inflight) {
+    const conn = await inflight;
+    conn.retain();
+    return conn;
+  }
+
+  const create = (async (): Promise<BidiConnection> => {
+    const mport = defaultMarionettePort();
+    // Do we ALREADY hold this endpoint's slot? (e.g. our previous socket died without dispose, so
+    // the eviction above kept the claim.) If so, re-dial WITHOUT re-acquiring: acquireSessionSlot
+    // against our own live pid would just poll to its wait ceiling and then throw
+    // SessionSlotBusyError against ourselves. We already own Firefox's slot; only the socket needs
+    // re-establishing (and if Firefox stranded our old session, the re-dial's retry path clears it).
+    const owned = slotHandles.has(endpoint);
+    if (!owned) {
+      // Cross-process coordination (session-lease.ts): take the endpoint's single BiDi session slot,
+      // classifying any current holder. A LIVE holder (another agent legitimately driving this
+      // Firefox) throws SessionSlotBusyError; a DEAD holder's orphan is stolen and surfaced as
+      // staleHolder so we can force-clear Firefox's stranded session before we call session.new.
+      let acq: AcquireResult;
+      try {
+        acq = await acquireSessionSlot(endpoint, { label: defaultLabel(), marionettePort: mport });
+      } catch (e) {
+        if (e instanceof SessionSlotBusyError) {
+          // Issue #5: a distinguishable LIVE holder, NOT a wedge. Map to an actionable disconnected
+          // error that names who holds the one session and why Firefox can serve only one per browser.
+          const who = e.holderLabel ? `'${e.holderLabel}' (pid ${e.holderPid})` : "another live process";
+          throw driverError("disconnected",
+            `Firefox's single WebDriver BiDi session on ${endpoint} is held by a LIVE process ${who}. ` +
+            `Firefox serves exactly ONE BiDi session per browser instance, so this server cannot take it ` +
+            `while that process is running. Wait for it to release the session and retry, or point this ` +
+            `server at a different endpoint/browser.`);
+        }
+        throw e;
+      }
+      slotHandles.set(endpoint, acq.handle);
+      if (acq.staleHolder) {
+        // Issue #4 auto-recovery: we stole a DEAD holder's lease, but Firefox itself may still hold
+        // that holder's orphaned BiDi session. Force-clear it over Marionette BEFORE dialing, or
+        // session.new below will still hit "Maximum number of active sessions". Best-effort: a false
+        // result means Firefox has no --marionette (launch mode, or the user never enabled it); we
+        // still dial, and the re-dial retry path below surfaces a clear error if the orphan persists.
+        await forceClearOrphanSession(acq.staleHolder.marionettePort ?? mport);
+      }
     }
-    throw e;
-  }); // already retained once
-  connections.set(endpoint, conn);
-  return conn;
+
+    // Firefox 153's default unhandledPromptBehavior is "dismiss": a page-blocking alert()/confirm()
+    // gets auto-dismissed before handleDialog() ever runs, and Firefox's own userPromptOpened event
+    // reports handler:"dismiss" on it (verified: a bare session.new left "no such alert" on the very
+    // next handleUserPrompt call). Setting "ignore" here is what makes handleDialog() able to see
+    // and answer a live prompt at all.
+    const dialOpts = {
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+      capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" as const } } },
+    };
+    let conn: BidiConnection;
+    try {
+      conn = await connectBidiSessionUrl(endpoint, dialOpts); // already retained once
+    } catch (e) {
+      if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+        // Firefox still holds a BiDi session our lease didn't account for: a FOREIGN client we don't
+        // coordinate with, OUR OWN orphan from a dead socket (the `owned` re-dial), or a pre-lease
+        // orphan. Recovery: blind Marionette force-clear, then retry the dial EXACTLY once.
+        const cleared = await forceClearOrphanSession(mport);
+        if (!cleared) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          throw orphanNotClearedError(endpoint);
+        }
+        try {
+          conn = await connectBidiSessionUrl(endpoint, dialOpts); // already retained once
+        } catch (e2) {
+          await releaseSlotOnDialFailure(endpoint, owned);
+          if (e2 instanceof BidiError && /maximum number of active sessions/i.test(e2.message)) {
+            throw orphanNotClearedError(endpoint); // cleared, yet still refused: treat as unrecoverable
+          }
+          throw e2;
+        }
+      } else {
+        // Any other dial failure never established a session: release a slot we took THIS call and
+        // rethrow unchanged (the `owned` re-dial never acquired, so its claim is left intact).
+        await releaseSlotOnDialFailure(endpoint, owned);
+        throw e;
+      }
+    }
+    connections.set(endpoint, conn);
+    return conn;
+  })();
+
+  connecting.set(endpoint, create);
+  try {
+    return await create;
+  } finally {
+    connecting.delete(endpoint);
+  }
 }
 
 /**
@@ -1333,8 +1473,17 @@ class BidiBrowserDriver implements BrowserDriver {
     for (const key of [...bidiBeaconScripts.keys()]) {
       if (key.startsWith(`${this.endpoint}:`)) bidiBeaconScripts.delete(key);
     }
+    // Drop any in-flight create record defensively: dispose() ends this endpoint's life, so a
+    // pending create must not leave a stale promise that a later getConnection would await.
+    connecting.delete(this.endpoint);
     const conn = connections.get(this.endpoint);
-    if (!conn) return;
+    if (!conn) {
+      // No live connection, but we may still hold the session slot lock (e.g. a create acquired the
+      // slot then failed to establish a session on an `owned` re-dial, which leaves the claim). A
+      // clean dispose must free it cross-process so the next process is not falsely told we're LIVE.
+      await this.releaseSessionSlotIfHeld();
+      return;
+    }
     connections.delete(this.endpoint);
     // Cleanly END the BiDi session so Firefox frees its single session slot for the next
     // attach (a launch-mode Firefox is killed anyway; this matters for attach mode where the
@@ -1343,6 +1492,19 @@ class BidiBrowserDriver implements BrowserDriver {
     // Best-effort: harmless if the socket is already gone.
     await conn.send("session.end", {}).catch(() => undefined);
     conn.dispose();
+    // Release OUR cross-process session-slot lock so the next process (this or another) can take the
+    // slot cleanly. releaseSessionSlot only unlinks a record still stamped with our (pid, createdAt),
+    // so it never clobbers a claim a later process made after stealing ours. (session-lease.ts)
+    await this.releaseSessionSlotIfHeld();
+  }
+
+  /** Free this endpoint's session-slot lock if this process holds it, and forget the handle.
+   *  Best-effort and idempotent — safe to call whether or not a live connection existed. */
+  private async releaseSessionSlotIfHeld(): Promise<void> {
+    const h = slotHandles.get(this.endpoint);
+    if (!h) return;
+    await releaseSessionSlot(h).catch(() => undefined);
+    slotHandles.delete(this.endpoint);
   }
 }
 

package/src/bidi/marionette.ts

@@ -0,0 +1,276 @@
+/**
+ * Minimal Firefox Marionette client — orphan BiDi-session recovery, issue #4.
+ *
+ * WHAT THIS IS FOR, AND NOTHING ELSE. Firefox serves exactly ONE
+ * WebDriver-BiDi session per browser instance, and Marionette and BiDi SHARE
+ * that one global session slot. When a cdp-toolkit process dies mid-drive it can
+ * leave Firefox believing a BiDi session is still active; the next `session.new`
+ * then fails with "Maximum number of active sessions" even though no live
+ * process holds it. `session-lease.ts` detects that a dead process left the slot
+ * occupied (its `staleHolder`); THIS module is the mechanism that then frees the
+ * slot inside Firefox itself, WITHOUT killing the browser — so a user's real,
+ * logged-in Firefox keeps running and only the orphaned session is cleared.
+ *
+ * WHY MARIONETTE AND NOT BIDI. The BiDi endpoint is what's wedged: it refuses a
+ * new session while the orphan is "active", and it exposes no cross-session
+ * teardown. Marionette is Firefox's OTHER, older remote-control channel (a raw
+ * TCP port, `--marionette`, default 2828). Because the two dialects share the
+ * one session slot, a single Marionette `WebDriver:DeleteSession` tears down
+ * whatever occupies that slot — the orphaned BiDi session included — as a blind
+ * cross-dialect teardown. No `WebDriver:NewSession` is needed first: DeleteSession
+ * against an empty slot is a harmless no-op ("invalid session id").
+ *
+ * THE WIRE PROTOCOL ("packet" dialect, marionetteProtocol 3), proven against
+ * Firefox 153.0.3:
+ *   - Framing, both directions: `<utf8-byte-length>:<json>` — the ASCII decimal
+ *     byte count of the JSON body, a literal ':', then exactly that many bytes of
+ *     UTF-8 JSON. Frames coalesce and split across TCP reads; the decoder handles
+ *     both (see FrameDecoder).
+ *   - On connect, Firefox immediately PUSHES a handshake frame (a bare object,
+ *     e.g. `50:{"applicationType":"gecko","marionetteProtocol":3}`) that a client
+ *     must consume before anything else.
+ *   - Command frame:  `[0, msgId, "Command:Name", params]`.
+ *   - Response frame: `[1, msgId, error_or_null, result_or_null]`.
+ *
+ * ZERO RUNTIME DEPENDENCIES: only `node:net`.
+ */
+import { Socket } from "node:net";
+
+/** Firefox's default Marionette control port. */
+const DEFAULT_MARIONETTE_PORT = 2828;
+/** Whole-exchange budget: connect + handshake + command + reply. */
+const DEFAULT_TIMEOUT_MS = 4000;
+/** Marionette listens on loopback only; never dial anything else. */
+const HOST = "127.0.0.1";
+/** ASCII ':' — the length/body delimiter in the packet framing. */
+const COLON = 0x3a;
+
+/**
+ * The one command we ever send. Marionette + BiDi share the single session slot,
+ * so this blindly tears down whatever occupies it (the orphaned BiDi session)
+ * with no NewSession first. Precomputed once: `34:[0,1,"WebDriver:DeleteSession",{}]`.
+ */
+const DELETE_SESSION_FRAME = encodeFrame([0, 1, "WebDriver:DeleteSession", {}]);
+
+/**
+ * The Marionette control port to target. Reads `CDP_FIREFOX_MARIONETTE_PORT`
+ * per call (like session-lease.ts's env getters, so a test can redirect it); a
+ * value that is not a finite number > 0 falls back to Firefox's 2828 default.
+ */
+export function defaultMarionettePort(): number {
+  const raw = Number(process.env.CDP_FIREFOX_MARIONETTE_PORT);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MARIONETTE_PORT;
+}
+
+/**
+ * Encode one value as a Marionette wire frame: `<utf8-byte-length>:<utf8-json>`.
+ * The length prefix is the BYTE count of the JSON body (not its character
+ * count), so multi-byte UTF-8 payloads frame correctly. Pure; exported for tests.
+ */
+export function encodeFrame(json: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(json), "utf8");
+  const prefix = Buffer.from(`${body.length}:`, "ascii");
+  return Buffer.concat([prefix, body]);
+}
+
+/**
+ * Raised when the byte stream is not valid Marionette framing — a non-digit in
+ * the length prefix, or a frame body that is complete but not parseable JSON.
+ * FrameDecoder.next() throws this; forceClearOrphanSession catches it and
+ * degrades to `false` (a wedged/unparseable channel cannot confirm a free slot).
+ */
+export class MarionetteProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MarionetteProtocolError";
+  }
+}
+
+/**
+ * Incremental decoder for the `<byte-length>:<json>` framing. Feed raw TCP
+ * chunks with push(); pull one complete, parsed frame per next() call.
+ *
+ * Handles the two things naive framing gets wrong on a real socket: a single
+ * frame SPLIT across several reads (next() returns undefined until the whole
+ * body has arrived) and several frames COALESCED into one read (repeated next()
+ * calls drain them one at a time). Exported for unit testing against known
+ * byte vectors.
+ */
+export class FrameDecoder {
+  private buf: Buffer = Buffer.alloc(0);
+
+  /** Append a chunk of bytes. Cheap: no scan happens here. */
+  push(chunk: Buffer): void {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+  }
+
+  /**
+   * Return the next complete frame as its parsed value, or undefined when more
+   * bytes are still needed to complete the frame currently at the front of the
+   * buffer. Throws MarionetteProtocolError on malformed framing/JSON.
+   */
+  next(): unknown | undefined {
+    const colon = this.buf.indexOf(COLON);
+    if (colon === -1) {
+      // No delimiter yet. Everything buffered so far must be ASCII digits, or
+      // this is not Marionette framing and never will be — fail fast instead of
+      // buffering garbage until the caller's timeout.
+      this.assertDigitsPrefix(this.buf.length);
+      return undefined;
+    }
+    if (colon === 0) throw new MarionetteProtocolError("empty frame length prefix");
+    this.assertDigitsPrefix(colon);
+
+    const len = Number.parseInt(this.buf.toString("ascii", 0, colon), 10);
+    const start = colon + 1;
+    const end = start + len;
+    if (this.buf.length < end) return undefined; // body not fully arrived yet
+
+    const payload = this.buf.toString("utf8", start, end);
+    this.buf = this.buf.subarray(end); // keep any trailing bytes for the next frame
+    try {
+      return JSON.parse(payload);
+    } catch {
+      throw new MarionetteProtocolError(
+        `frame body was not valid JSON (${len} bytes): ${payload.slice(0, 80)}`,
+      );
+    }
+  }
+
+  /** Every byte in buf[0, upTo) must be an ASCII digit, or the framing is bad. */
+  private assertDigitsPrefix(upTo: number): void {
+    for (let i = 0; i < upTo; i++) {
+      const b = this.buf[i]!;
+      if (b < 0x30 || b > 0x39) {
+        throw new MarionetteProtocolError(
+          `non-digit byte 0x${b.toString(16)} in frame length prefix`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Interpret a `WebDriver:DeleteSession` reply frame `[1, msgId, error, result]`.
+ * The slot is FREE (return true) in exactly two shapes:
+ *   - error === null (result `{"value":null}`): an active session existed and
+ *     was cleared.
+ *   - error is an object with error === "invalid session id": the slot was
+ *     already empty — DeleteSession was a no-op.
+ * Any other shape (a different error, a non-response, a malformed frame) cannot
+ * confirm the slot is free, so it returns false.
+ */
+function isSlotFreedReply(frame: unknown): boolean {
+  if (!Array.isArray(frame)) return false;
+  const err: unknown = frame[2];
+  if (err === null) return true; // session existed and was cleared
+  if (typeof err === "object" && err !== null && (err as { error?: unknown }).error === "invalid session id") {
+    return true; // slot was already empty
+  }
+  return false; // any other error: cannot confirm
+}
+
+/**
+ * Force-clear an orphaned WebDriver-BiDi session so a subsequent BiDi
+ * `session.new` succeeds, WITHOUT killing Firefox.
+ *
+ * Connects to Marionette on `127.0.0.1:<marionettePort>`, drains the pushed
+ * handshake frame, sends exactly one `WebDriver:DeleteSession`, reads exactly one
+ * reply, and returns whether the session slot is now free.
+ *
+ * NEVER THROWS and NEVER LEAKS THE SOCKET. Every terminal path — success, a
+ * refused connection (Marionette not running because Firefox was not launched
+ * with --marionette; the NORMAL degrade case, not a loud error), a connect/read
+ * timeout, any socket error, a premature close, or an unexpected/unparseable
+ * reply — routes through a single settle() that destroys the socket exactly once
+ * and resolves the promise. Returns true only when the slot is confirmed free.
+ *
+ * @param marionettePort  TCP port Firefox's Marionette server listens on.
+ * @param opts.timeoutMs  Whole-exchange budget (connect+handshake+command+reply).
+ *                        Default 4000ms. On timeout the socket is destroyed and
+ *                        the result is false.
+ */
+export function forceClearOrphanSession(
+  marionettePort: number,
+  opts: { timeoutMs?: number } = {},
+): Promise<boolean> {
+  const timeoutMs =
+    opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+      ? opts.timeoutMs
+      : DEFAULT_TIMEOUT_MS;
+
+  return new Promise<boolean>((resolve) => {
+    // Guard a nonsense port up front: net.Socket.connect throws synchronously on
+    // an out-of-range/NaN port, and that throw must not escape as a rejection.
+    if (!Number.isFinite(marionettePort) || marionettePort <= 0 || marionettePort > 65535) {
+      resolve(false);
+      return;
+    }
+
+    const sock = new Socket();
+    const decoder = new FrameDecoder();
+    let settled = false;
+    let handshakeSeen = false;
+    let commandSent = false;
+
+    // One-shot terminal path. Idempotent (settled guard), removes listeners so a
+    // close/error triggered by our own destroy() can't re-enter, and ALWAYS
+    // destroys the socket — this is the single place the socket is torn down, so
+    // no code path can return without freeing it.
+    const settle = (value: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(value);
+    };
+
+    // The timeout covers the WHOLE exchange, including connect. unref() so a
+    // hosting process is never held open by this timer alone.
+    const timer = setTimeout(() => settle(false), timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+
+    // ECONNREFUSED (no Marionette on the port) and every other socket error are
+    // the normal degrade to false — quiet, not logged.
+    sock.on("error", () => settle(false));
+    // Peer closed before we got a reply: can't confirm, degrade to false.
+    sock.on("close", () => settle(false));
+
+    sock.on("data", (chunk: Buffer) => {
+      if (settled) return;
+      try {
+        decoder.push(chunk);
+        for (;;) {
+          const frame = decoder.next();
+          if (frame === undefined) break; // need more bytes for the front frame
+          if (!handshakeSeen) {
+            // First frame is Firefox's handshake (a bare object). Consume and
+            // discard it, then keep draining in case a later frame coalesced.
+            handshakeSeen = true;
+            continue;
+          }
+          // First post-handshake frame is our DeleteSession reply. Done.
+          settle(isSlotFreedReply(frame));
+          return;
+        }
+        // Handshake in hand and command not yet on the wire → send it once.
+        if (handshakeSeen && !commandSent) {
+          commandSent = true;
+          sock.write(DELETE_SESSION_FRAME);
+        }
+      } catch {
+        // Malformed framing/JSON: the channel can't confirm a free slot.
+        settle(false);
+      }
+    });
+
+    // connect() can still throw synchronously (e.g. a mid-range but invalid
+    // arg); route that through settle so nothing escapes as a rejection.
+    try {
+      sock.connect(marionettePort, HOST);
+    } catch {
+      settle(false);
+    }
+  });
+}