sliccy 6.137.0 → 6.138.0

package/dist/node-server/cdp-proxy/chrome-reconnect.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Chrome-leg reconnect supervisor for the node-server `/cdp` proxy.
+ *
+ * Chrome's browser-level debugger socket drops on its own (`messageTooLarge`,
+ * an inbound-queue overflow, a devtools window stealing the single slot). When
+ * it does, Chrome discards EVERY CDP session behind it. Until now node-server
+ * just cleared `chromeWs` and dropped client frames on the floor until a NEW
+ * `/cdp` client connected — i.e. until the SLICC tab was reloaded by hand
+ * (issue #2417, `DIAGNOSIS.md` §2.6). swift-server already reconnects
+ * (`CDPProxy.scheduleChromeReconnect` / `runChromeReconnectLoop`); this brings
+ * node-server to parity and adds the missing half both floats needed: the
+ * active client is closed with `CDP_UPSTREAM_RESET_CLOSE_CODE` so the page
+ * re-dials and resets its session state instead of issuing commands against
+ * sessions Chrome has forgotten.
+ *
+ * ## Reconnect policy (identical in node-server and swift-server)
+ *
+ * Retry indefinitely with a 1 s delay between attempts, until shutdown — there
+ * is no attempt cap. Close the active client with 4002 `upstream-reset` after
+ * the 3rd consecutive failure, so it does not hang on a proxy whose Chrome leg
+ * is gone. After a successful reconnect, reset the active client ONLY if it is
+ * the same client that held the slot when the Chrome leg went down — it is the
+ * one whose sessions Chrome discarded. A client that connected during the
+ * outage never had sessions on the dead leg and its buffered frames were just
+ * flushed onto the replacement connection, so closing it with 4002 would make
+ * the page retry commands that already ran (a sessionless `Target.createTarget`
+ * opens a duplicate tab). Never leave a clientless buffer around: buffered
+ * frames are dropped whenever the client that wrote them loses the slot.
+ */
+import { type ClientFrameBuffer } from './client-frame-buffer.js';
+/** Delay before each reconnect attempt. Mirrors swift `defaultReconnectDelayNanoseconds`. */
+export declare const CHROME_RECONNECT_DELAY_MS = 1000;
+/**
+ * Consecutive failed attempts after which the active client is cut loose with
+ * 4002 rather than left hanging on a proxy whose Chrome leg is gone. The loop
+ * keeps retrying afterwards. Mirrors swift `upstreamResetFailureThreshold`.
+ */
+export declare const CHROME_RECONNECT_FAILURE_THRESHOLD = 3;
+export interface ChromeReconnectDeps {
+    /** Re-discover Chrome's browser-level ws URL (via `/json/version`). */
+    discoverChromeWsUrl: () => Promise<string>;
+    /** Connect the Chrome leg to `url`; rejects when the socket never opens. */
+    connectChrome: (url: string) => Promise<void>;
+    /** Close the active `/cdp` client with the upstream-reset code, if any. */
+    resetClient: (reason: string) => void;
+    /**
+     * Id of the client holding the single `/cdp` slot right now, or null when it
+     * is empty. Sampled on every leg drop and compared again after a successful
+     * reconnect: only the holder that saw the dead leg carries stale sessions.
+     */
+    activeClientId: () => number | null;
+    /** True once graceful shutdown started — no reconnect, no client reset. */
+    isShuttingDown: () => boolean;
+    /**
+     * True when the Chrome leg is already open again — e.g. a NEW `/cdp` client
+     * connected during the delay and `handleCdpClient` rebuilt it. That client
+     * has no stale sessions, so the loop must exit WITHOUT evicting it.
+     */
+    isChromeLegHealthy?: () => boolean;
+    /** Log one `[cdp-proxy]`-prefixed line (caller applies `CliLogDedup`). */
+    log: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    delayMs?: number;
+    failureThreshold?: number;
+}
+/** The proxy state a Chrome-leg drop mutates (a slice of `ServerState`). */
+export interface ChromeLegState<Socket = unknown> {
+    chromeWs: Socket | null;
+    /** Id of the Chrome connection `chromeWs` refers to (0 = never connected). */
+    chromeConnectionId: number;
+    /** Id of the client holding the single `/cdp` slot, or null for none. */
+    activeClientId: number | null;
+    /** Non-null = buffering Client→Chrome frames instead of forwarding them. */
+    messageBuffer: ClientFrameBuffer | null;
+    shuttingDown: boolean;
+}
+/**
+ * Record that the Chrome leg went away: clear the socket and start buffering
+ * client frames so they survive the gap (node-server used to drop them until a
+ * NEW `/cdp` client connected). Returns false — meaning "do not schedule a
+ * reconnect" — when the event came from a socket a newer connect already
+ * replaced, or when the server is shutting down.
+ *
+ * The buffer opened here is tagged with the connection that just died, so the
+ * flush onto the REPLACEMENT connection discards it: those frames name sessions
+ * Chrome dropped with the old socket, and the client is being reset anyway.
+ */
+export declare function markChromeLegDown<Socket>(state: ChromeLegState<Socket>, droppedWs: Socket): boolean;
+/** Minimal `ws` surface needed to evict the active `/cdp` client. */
+export interface ResettableClientSocket {
+    readyState: number;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Close the active `/cdp` client with the upstream-reset code so the page
+ * re-dials and rebuilds its (now dead) CDP sessions. Returns true when a close
+ * was actually issued.
+ */
+export declare function closeClientForUpstreamReset(client: ResettableClientSocket | null | undefined, reason: string, log: (line: string) => void): boolean;
+/**
+ * Owns at most one in-flight reconnect loop. `schedule()` is idempotent — a
+ * Chrome socket that fires both `error` and `close` schedules once.
+ */
+export declare class ChromeReconnectController {
+    private readonly deps;
+    private task;
+    private cancelled;
+    /** Slot holder at the most recent Chrome-leg drop — the one with stale sessions. */
+    private slotHolderAtDrop;
+    constructor(deps: ChromeReconnectDeps);
+    /** True while a reconnect loop is running. */
+    get reconnecting(): boolean;
+    /** Start the reconnect loop unless one is already running or we're shutting down. */
+    schedule(reason: string): void;
+    /** Stop the loop (graceful shutdown). Sticky — the controller is not reused. */
+    cancel(): void;
+    /** Resolves when the current reconnect loop (if any) has finished. For tests. */
+    settled(): Promise<void>;
+    /**
+     * Retry until the leg is back or shutdown stops us — no attempt cap, so a
+     * Chrome that comes back after a long outage is picked up without needing a
+     * fresh client to drive discovery (swift parity).
+     */
+    private run;
+    /** One discover + connect round. Returns true when the leg is back. */
+    private attempt;
+    /**
+     * Close the client that held the slot when the leg dropped: Chrome discarded
+     * every session with the old socket, so that page's cached sessionIds are
+     * dead and it must re-dial with a clean slate.
+     *
+     * A client that connected DURING the outage is left alone. It never had
+     * sessions on the dead leg, and the frames it buffered were just flushed onto
+     * the replacement connection — closing it with 4002 would make the page retry
+     * commands that already ran, and a sessionless `Target.createTarget` among
+     * them opens a duplicate tab (issue #2417). The third-failure reset clears
+     * the slot, so the comparison below naturally fails for any replacement.
+     */
+    private resetStaleSlotHolder;
+    private stopped;
+}

package/dist/node-server/cdp-proxy/chrome-reconnect.js

@@ -0,0 +1,206 @@
+/**
+ * Chrome-leg reconnect supervisor for the node-server `/cdp` proxy.
+ *
+ * Chrome's browser-level debugger socket drops on its own (`messageTooLarge`,
+ * an inbound-queue overflow, a devtools window stealing the single slot). When
+ * it does, Chrome discards EVERY CDP session behind it. Until now node-server
+ * just cleared `chromeWs` and dropped client frames on the floor until a NEW
+ * `/cdp` client connected — i.e. until the SLICC tab was reloaded by hand
+ * (issue #2417, `DIAGNOSIS.md` §2.6). swift-server already reconnects
+ * (`CDPProxy.scheduleChromeReconnect` / `runChromeReconnectLoop`); this brings
+ * node-server to parity and adds the missing half both floats needed: the
+ * active client is closed with `CDP_UPSTREAM_RESET_CLOSE_CODE` so the page
+ * re-dials and resets its session state instead of issuing commands against
+ * sessions Chrome has forgotten.
+ *
+ * ## Reconnect policy (identical in node-server and swift-server)
+ *
+ * Retry indefinitely with a 1 s delay between attempts, until shutdown — there
+ * is no attempt cap. Close the active client with 4002 `upstream-reset` after
+ * the 3rd consecutive failure, so it does not hang on a proxy whose Chrome leg
+ * is gone. After a successful reconnect, reset the active client ONLY if it is
+ * the same client that held the slot when the Chrome leg went down — it is the
+ * one whose sessions Chrome discarded. A client that connected during the
+ * outage never had sessions on the dead leg and its buffered frames were just
+ * flushed onto the replacement connection, so closing it with 4002 would make
+ * the page retry commands that already ran (a sessionless `Target.createTarget`
+ * opens a duplicate tab). Never leave a clientless buffer around: buffered
+ * frames are dropped whenever the client that wrote them loses the slot.
+ */
+import { createClientFrameBuffer } from './client-frame-buffer.js';
+import { CDP_UPSTREAM_RESET_CLOSE_CODE, CDP_UPSTREAM_RESET_CLOSE_REASON } from './close-codes.js';
+/** Delay before each reconnect attempt. Mirrors swift `defaultReconnectDelayNanoseconds`. */
+export const CHROME_RECONNECT_DELAY_MS = 1000;
+/**
+ * Consecutive failed attempts after which the active client is cut loose with
+ * 4002 rather than left hanging on a proxy whose Chrome leg is gone. The loop
+ * keeps retrying afterwards. Mirrors swift `upstreamResetFailureThreshold`.
+ */
+export const CHROME_RECONNECT_FAILURE_THRESHOLD = 3;
+/**
+ * Record that the Chrome leg went away: clear the socket and start buffering
+ * client frames so they survive the gap (node-server used to drop them until a
+ * NEW `/cdp` client connected). Returns false — meaning "do not schedule a
+ * reconnect" — when the event came from a socket a newer connect already
+ * replaced, or when the server is shutting down.
+ *
+ * The buffer opened here is tagged with the connection that just died, so the
+ * flush onto the REPLACEMENT connection discards it: those frames name sessions
+ * Chrome dropped with the old socket, and the client is being reset anyway.
+ */
+export function markChromeLegDown(state, droppedWs) {
+    // swift-server guards the same way with `chromeConnectionID`: a late close
+    // from the previous socket must not tear down the live one.
+    if (state.chromeWs !== null && state.chromeWs !== droppedWs)
+        return false;
+    state.chromeWs = null;
+    if (state.shuttingDown)
+        return false;
+    state.messageBuffer ??= createClientFrameBuffer({
+        chromeConnectionId: state.chromeConnectionId,
+        clientId: state.activeClientId,
+    });
+    return true;
+}
+/** `WebSocket.OPEN` — kept local so this module stays free of the `ws` import. */
+const WS_READY_STATE_OPEN = 1;
+/**
+ * Close the active `/cdp` client with the upstream-reset code so the page
+ * re-dials and rebuilds its (now dead) CDP sessions. Returns true when a close
+ * was actually issued.
+ */
+export function closeClientForUpstreamReset(client, reason, log) {
+    if (!client || client.readyState !== WS_READY_STATE_OPEN)
+        return false;
+    log(`[cdp-proxy] Closing client after Chrome-leg reset (${reason})`);
+    client.close(CDP_UPSTREAM_RESET_CLOSE_CODE, CDP_UPSTREAM_RESET_CLOSE_REASON);
+    return true;
+}
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Owns at most one in-flight reconnect loop. `schedule()` is idempotent — a
+ * Chrome socket that fires both `error` and `close` schedules once.
+ */
+export class ChromeReconnectController {
+    deps;
+    task = null;
+    cancelled = false;
+    /** Slot holder at the most recent Chrome-leg drop — the one with stale sessions. */
+    slotHolderAtDrop = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** True while a reconnect loop is running. */
+    get reconnecting() {
+        return this.task !== null;
+    }
+    /** Start the reconnect loop unless one is already running or we're shutting down. */
+    schedule(reason) {
+        if (this.cancelled || this.deps.isShuttingDown()) {
+            this.deps.log(`[cdp-proxy] Chrome WS dropped during shutdown — not reconnecting (${reason})`);
+            return;
+        }
+        // Sampled on EVERY drop, including one that lands while a loop is already
+        // running (a client that connected during the outage rebuilt the leg and
+        // then lost it too): the stale-session client is whoever held the slot at
+        // the most recent drop.
+        this.slotHolderAtDrop = this.deps.activeClientId();
+        if (this.task !== null)
+            return;
+        const delayMs = this.deps.delayMs ?? CHROME_RECONNECT_DELAY_MS;
+        this.deps.log(`[cdp-proxy] Scheduling Chrome WS reconnect in ${delayMs}ms (${reason})`);
+        const task = this.run(delayMs);
+        this.task = task;
+        void task.then(() => {
+            if (this.task === task)
+                this.task = null;
+        });
+    }
+    /** Stop the loop (graceful shutdown). Sticky — the controller is not reused. */
+    cancel() {
+        this.cancelled = true;
+    }
+    /** Resolves when the current reconnect loop (if any) has finished. For tests. */
+    async settled() {
+        await this.task;
+    }
+    /**
+     * Retry until the leg is back or shutdown stops us — no attempt cap, so a
+     * Chrome that comes back after a long outage is picked up without needing a
+     * fresh client to drive discovery (swift parity).
+     */
+    async run(delayMs) {
+        const threshold = this.deps.failureThreshold ?? CHROME_RECONNECT_FAILURE_THRESHOLD;
+        const sleep = this.deps.sleep ?? defaultSleep;
+        let consecutiveFailures = 0;
+        let didSignalFailure = false;
+        for (;;) {
+            await sleep(delayMs);
+            if (this.stopped())
+                return;
+            if (await this.attempt(consecutiveFailures + 1))
+                return;
+            consecutiveFailures++;
+            if (didSignalFailure || consecutiveFailures < threshold)
+                continue;
+            // Cut the client loose ONCE so it stops waiting on a dead proxy; the loop
+            // keeps going and resets whoever holds the slot when Chrome returns.
+            didSignalFailure = true;
+            this.deps.log(`[cdp-proxy] Chrome WS reconnect failed ${consecutiveFailures}x — resetting client (still retrying)`);
+            this.deps.resetClient('reconnect-failed');
+        }
+    }
+    /** One discover + connect round. Returns true when the leg is back. */
+    async attempt(attempt) {
+        if (this.deps.isChromeLegHealthy?.() === true) {
+            this.deps.log('[cdp-proxy] Chrome WS already re-established — no client reset needed');
+            return true;
+        }
+        try {
+            const url = await this.deps.discoverChromeWsUrl();
+            if (this.stopped())
+                return true;
+            await this.deps.connectChrome(url);
+            if (this.stopped())
+                return true;
+            this.deps.log('[cdp-proxy] Chrome WS auto-reconnected');
+            this.resetStaleSlotHolder();
+            return true;
+        }
+        catch (err) {
+            this.deps.log(`[cdp-proxy] Auto-reconnect attempt ${attempt} failed: ${String(err)}`);
+            return false;
+        }
+    }
+    /**
+     * Close the client that held the slot when the leg dropped: Chrome discarded
+     * every session with the old socket, so that page's cached sessionIds are
+     * dead and it must re-dial with a clean slate.
+     *
+     * A client that connected DURING the outage is left alone. It never had
+     * sessions on the dead leg, and the frames it buffered were just flushed onto
+     * the replacement connection — closing it with 4002 would make the page retry
+     * commands that already ran, and a sessionless `Target.createTarget` among
+     * them opens a duplicate tab (issue #2417). The third-failure reset clears
+     * the slot, so the comparison below naturally fails for any replacement.
+     */
+    resetStaleSlotHolder() {
+        const holder = this.slotHolderAtDrop;
+        const current = this.deps.activeClientId();
+        if (holder !== null && current === holder) {
+            this.deps.resetClient('reconnected');
+            return;
+        }
+        if (current !== null) {
+            this.deps.log('[cdp-proxy] Client connected during the outage — no stale sessions, not resetting it');
+        }
+    }
+    stopped() {
+        if (!this.cancelled && !this.deps.isShuttingDown())
+            return false;
+        this.deps.log('[cdp-proxy] Chrome WS reconnect cancelled (shutting down)');
+        return true;
+    }
+}

package/dist/node-server/cdp-proxy/client-frame-buffer.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Bounded, generation-tagged Client→Chrome frame buffer for the `/cdp` proxy.
+ *
+ * Frames a client sends while the Chrome leg is unavailable are held here. The
+ * buffer is bounded and drops the OLDEST frame on overflow — same policy and
+ * limit as swift-server's `CDPProxy.appendBufferedMessage` (`maxBufferSize =
+ * 1_000`). Unbounded growth would turn a Chrome leg that never comes back into
+ * a heap leak.
+ *
+ * The generation tag decides whether the buffer may be flushed at all. A
+ * buffered frame is only meaningful on the exact `{chromeConnection, client}`
+ * pair it was written for:
+ *
+ *   - Chrome discards EVERY CDP session when its browser-level socket closes,
+ *     so frames buffered after a leg drop name sessions the replacement
+ *     connection has never heard of. Worse, a browser-level `Target.createTarget`
+ *     would still execute — after its caller was already rejected with 4002 —
+ *     and the caller's retry opens a duplicate tab.
+ *   - Frames buffered by a client that has since been superseded or closed must
+ *     not run under whoever holds the slot now.
+ *
+ * So a buffer is flushed only when both halves of its generation still match at
+ * flush time, and dropped (the caller logs the count and the reason) otherwise.
+ * The one case that still flushes is the original initial-connect buffering — a
+ * client that connected before Chrome was ready lost no sessions, so its
+ * `chromeConnectionId` is `null` and any connection will do.
+ *
+ * The state transitions live here rather than in `index.ts` so the whole policy
+ * is unit-testable without booting a server. Mirrors `CDPProxy`'s
+ * `clientFrameBufferDropReason` / `discardBufferedMessages` in swift-server.
+ */
+/** Max frames held while the Chrome leg is down. Mirrors swift `maxBufferSize`. */
+export declare const CDP_CLIENT_FRAME_BUFFER_LIMIT = 1000;
+/** The `{chromeConnection, client}` pair a buffer's frames were written for. */
+export interface CdpBufferGeneration {
+    /**
+     * Id of the Chrome connection that was live when buffering started, or
+     * `null` when no leg was live at all (initial connect / a leg that never
+     * opened). `null` flushes onto any connection; a concrete id only flushes
+     * onto that same connection, which a post-drop replacement never is.
+     */
+    chromeConnectionId: number | null;
+    /** Id of the client that held the single `/cdp` slot, or `null` for none. */
+    clientId: number | null;
+}
+/** Buffered Client→Chrome frames plus the generation they belong to. */
+export interface ClientFrameBuffer {
+    readonly generation: CdpBufferGeneration;
+    readonly frames: unknown[];
+}
+/** Why a buffer was dropped rather than flushed. Used verbatim in log lines. */
+export type ClientFrameBufferDropReason = 'chrome-leg-reset' | 'client-superseded' | 'client-disconnected' | 'upstream-reset' | 'no-client';
+/** How many frames were thrown away, and why. `null` when nothing was lost. */
+export interface DroppedClientFrames {
+    count: number;
+    reason: ClientFrameBufferDropReason;
+}
+export interface ClientFrameBufferHost {
+    /**
+     * The Chrome leg, or null while it is down. A socket that is still
+     * CONNECTING (a reconnect attempt in flight) counts as "no live leg": a
+     * client joining then has lost nothing and its frames must stay flushable.
+     */
+    chromeWs: {
+        readyState: number;
+    } | null;
+    /** Monotonic id of `chromeWs`, assigned when the socket is created. */
+    chromeConnectionId: number;
+    /** Monotonic id of the client holding the single slot; null when empty. */
+    activeClientId: number | null;
+    messageBuffer: ClientFrameBuffer | null;
+}
+export declare function createClientFrameBuffer(generation: CdpBufferGeneration): ClientFrameBuffer;
+/**
+ * Append `frame` to `frames`, dropping the oldest entry when the limit is
+ * reached. Returns true when a frame was dropped, so the caller can log it.
+ */
+export declare function appendBufferedClientFrame(frames: unknown[], frame: unknown, limit?: number): boolean;
+/** The generation a buffer opened right now belongs to. */
+export declare function currentBufferGeneration(state: ClientFrameBufferHost): CdpBufferGeneration;
+/**
+ * Decide whether `buffer` may be flushed onto the connection identified by
+ * `current`. Returns `null` when the flush is safe, otherwise the drop reason.
+ */
+export declare function clientFrameBufferDropReason(buffer: ClientFrameBuffer, current: CdpBufferGeneration): ClientFrameBufferDropReason | null;
+/** Frames to send now, plus what was thrown away instead of being sent. */
+export interface ClientFrameFlush {
+    frames: unknown[];
+    dropped: DroppedClientFrames | null;
+}
+/**
+ * Clear the buffer and report what may be delivered onto `targetConnectionId`.
+ * Always leaves `state.messageBuffer` null: either the frames go out now, or
+ * they are gone.
+ */
+export declare function takeClientFrameBuffer(state: ClientFrameBufferHost, targetConnectionId: number): ClientFrameFlush;
+/**
+ * Whether `clientId` still holds the single `/cdp` slot. A frame from a
+ * client that was superseded, closed, or reset with 4002 must not reach
+ * Chrome even if it arrives before that client's socket has finished
+ * closing — swift-server's `receive` guard, mirrored here.
+ */
+export declare function clientHoldsSlot(state: ClientFrameBufferHost, clientId: number): boolean;
+/**
+ * Give the single `/cdp` slot to `clientId`. Anything the previous holder
+ * buffered belongs to IT — running those frames under the new client is the
+ * duplicate-tab bug from issue #2417 — so it is dropped, and a fresh buffer is
+ * opened so frames arriving during the Chrome handshake are still captured.
+ */
+export declare function adoptClientSlot(state: ClientFrameBufferHost, clientId: number): DroppedClientFrames | null;
+/**
+ * Empty the slot. Whatever the departing client buffered dies with it — a
+ * clientless buffer must never reach a Chrome leg, and after a 4002 reset the
+ * page re-issues whatever it still needs.
+ */
+export declare function releaseClientSlot(state: ClientFrameBufferHost, reason: Extract<ClientFrameBufferDropReason, 'client-disconnected' | 'upstream-reset'>): DroppedClientFrames | null;
+/** The `[cdp-proxy]` line emitted whenever buffered frames are thrown away. */
+export declare function describeDroppedClientFrames(dropped: DroppedClientFrames): string;

package/dist/node-server/cdp-proxy/client-frame-buffer.js

@@ -0,0 +1,141 @@
+/**
+ * Bounded, generation-tagged Client→Chrome frame buffer for the `/cdp` proxy.
+ *
+ * Frames a client sends while the Chrome leg is unavailable are held here. The
+ * buffer is bounded and drops the OLDEST frame on overflow — same policy and
+ * limit as swift-server's `CDPProxy.appendBufferedMessage` (`maxBufferSize =
+ * 1_000`). Unbounded growth would turn a Chrome leg that never comes back into
+ * a heap leak.
+ *
+ * The generation tag decides whether the buffer may be flushed at all. A
+ * buffered frame is only meaningful on the exact `{chromeConnection, client}`
+ * pair it was written for:
+ *
+ *   - Chrome discards EVERY CDP session when its browser-level socket closes,
+ *     so frames buffered after a leg drop name sessions the replacement
+ *     connection has never heard of. Worse, a browser-level `Target.createTarget`
+ *     would still execute — after its caller was already rejected with 4002 —
+ *     and the caller's retry opens a duplicate tab.
+ *   - Frames buffered by a client that has since been superseded or closed must
+ *     not run under whoever holds the slot now.
+ *
+ * So a buffer is flushed only when both halves of its generation still match at
+ * flush time, and dropped (the caller logs the count and the reason) otherwise.
+ * The one case that still flushes is the original initial-connect buffering — a
+ * client that connected before Chrome was ready lost no sessions, so its
+ * `chromeConnectionId` is `null` and any connection will do.
+ *
+ * The state transitions live here rather than in `index.ts` so the whole policy
+ * is unit-testable without booting a server. Mirrors `CDPProxy`'s
+ * `clientFrameBufferDropReason` / `discardBufferedMessages` in swift-server.
+ */
+/** Max frames held while the Chrome leg is down. Mirrors swift `maxBufferSize`. */
+export const CDP_CLIENT_FRAME_BUFFER_LIMIT = 1000;
+/** The slice of `ServerState` the buffer lifecycle reads and mutates. */
+/** ws `WebSocket.OPEN`; the only readyState under which frames can actually be delivered. */
+const SOCKET_OPEN = 1;
+export function createClientFrameBuffer(generation) {
+    return { generation, frames: [] };
+}
+/**
+ * Append `frame` to `frames`, dropping the oldest entry when the limit is
+ * reached. Returns true when a frame was dropped, so the caller can log it.
+ */
+export function appendBufferedClientFrame(frames, frame, limit = CDP_CLIENT_FRAME_BUFFER_LIMIT) {
+    let dropped = false;
+    while (frames.length >= limit) {
+        frames.shift();
+        dropped = true;
+    }
+    frames.push(frame);
+    return dropped;
+}
+/** The generation a buffer opened right now belongs to. */
+export function currentBufferGeneration(state) {
+    return {
+        // No live leg = nothing was lost, so the frames may flush onto whatever
+        // connection comes up next (the original initial-connect buffering).
+        chromeConnectionId: state.chromeWs?.readyState === SOCKET_OPEN ? state.chromeConnectionId : null,
+        clientId: state.activeClientId,
+    };
+}
+/**
+ * Decide whether `buffer` may be flushed onto the connection identified by
+ * `current`. Returns `null` when the flush is safe, otherwise the drop reason.
+ */
+export function clientFrameBufferDropReason(buffer, current) {
+    const { chromeConnectionId, clientId } = buffer.generation;
+    if (chromeConnectionId !== null && chromeConnectionId !== current.chromeConnectionId) {
+        return 'chrome-leg-reset';
+    }
+    if (current.clientId === null)
+        return 'no-client';
+    if (clientId !== current.clientId)
+        return 'client-superseded';
+    return null;
+}
+/**
+ * Clear the buffer and report what may be delivered onto `targetConnectionId`.
+ * Always leaves `state.messageBuffer` null: either the frames go out now, or
+ * they are gone.
+ */
+export function takeClientFrameBuffer(state, targetConnectionId) {
+    const buffer = state.messageBuffer;
+    state.messageBuffer = null;
+    if (!buffer)
+        return { frames: [], dropped: null };
+    const reason = clientFrameBufferDropReason(buffer, {
+        chromeConnectionId: targetConnectionId,
+        clientId: state.activeClientId,
+    });
+    if (!reason)
+        return { frames: buffer.frames, dropped: null };
+    return {
+        frames: [],
+        dropped: buffer.frames.length > 0 ? { count: buffer.frames.length, reason } : null,
+    };
+}
+/**
+ * Whether `clientId` still holds the single `/cdp` slot. A frame from a
+ * client that was superseded, closed, or reset with 4002 must not reach
+ * Chrome even if it arrives before that client's socket has finished
+ * closing — swift-server's `receive` guard, mirrored here.
+ */
+export function clientHoldsSlot(state, clientId) {
+    return state.activeClientId === clientId;
+}
+/**
+ * Give the single `/cdp` slot to `clientId`. Anything the previous holder
+ * buffered belongs to IT — running those frames under the new client is the
+ * duplicate-tab bug from issue #2417 — so it is dropped, and a fresh buffer is
+ * opened so frames arriving during the Chrome handshake are still captured.
+ */
+export function adoptClientSlot(state, clientId) {
+    state.activeClientId = clientId;
+    let dropped = null;
+    if (state.messageBuffer && state.messageBuffer.generation.clientId !== clientId) {
+        dropped = releaseClientFrameBuffer(state, 'client-superseded');
+    }
+    state.messageBuffer ??= createClientFrameBuffer(currentBufferGeneration(state));
+    return dropped;
+}
+/**
+ * Empty the slot. Whatever the departing client buffered dies with it — a
+ * clientless buffer must never reach a Chrome leg, and after a 4002 reset the
+ * page re-issues whatever it still needs.
+ */
+export function releaseClientSlot(state, reason) {
+    state.activeClientId = null;
+    return releaseClientFrameBuffer(state, reason);
+}
+function releaseClientFrameBuffer(state, reason) {
+    const buffer = state.messageBuffer;
+    state.messageBuffer = null;
+    if (!buffer || buffer.frames.length === 0)
+        return null;
+    return { count: buffer.frames.length, reason };
+}
+/** The `[cdp-proxy]` line emitted whenever buffered frames are thrown away. */
+export function describeDroppedClientFrames(dropped) {
+    return `[cdp-proxy] Dropped ${dropped.count} buffered client frame(s) — ${dropped.reason}`;
+}

package/dist/node-server/cdp-proxy/close-codes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Application-range (4000–4999) WebSocket close codes the `/cdp` proxy sends
+ * to its single client. Both MUST stay in sync with the same-named constants
+ * in `packages/webapp/src/cdp/cdp-client.ts` (and their Swift twins in
+ * `packages/swift-server/Sources/WebSocket/CDPProxy.swift`), because the
+ * page-side `CDPClient` branches on the exact numeric code.
+ */
+/**
+ * Sent to a CDP client that is evicted because a newer client took the single
+ * proxy slot. The page-side `CDPClient` recognises it and stops
+ * auto-reconnecting (otherwise two webapp tabs on one instance evict each
+ * other forever). MUST stay in sync with `CDP_SUPERSEDED_CLOSE_CODE` in
+ * `packages/webapp/src/cdp/cdp-client.ts`.
+ */
+export declare const CDP_SUPERSEDED_CLOSE_CODE = 4001;
+/**
+ * Sent to the active CDP client after the proxy's Chrome-leg WebSocket dropped
+ * and was re-established (or definitively failed to come back). Chrome
+ * discards every CDP session when that socket closes, so the page's cached
+ * `sessionId`s are dead — but nothing else tells it. The page-side `CDPClient`
+ * treats this code as "reconnect and reset session state" (unlike
+ * {@link CDP_SUPERSEDED_CLOSE_CODE}, it does NOT latch superseded). MUST stay
+ * in sync with `CDP_UPSTREAM_RESET_CLOSE_CODE` in
+ * `packages/webapp/src/cdp/cdp-client.ts`.
+ */
+export declare const CDP_UPSTREAM_RESET_CLOSE_CODE = 4002;
+/** Close reason paired with {@link CDP_UPSTREAM_RESET_CLOSE_CODE}. */
+export declare const CDP_UPSTREAM_RESET_CLOSE_REASON = "upstream-reset";

package/dist/node-server/cdp-proxy/close-codes.js

@@ -0,0 +1,28 @@
+/**
+ * Application-range (4000–4999) WebSocket close codes the `/cdp` proxy sends
+ * to its single client. Both MUST stay in sync with the same-named constants
+ * in `packages/webapp/src/cdp/cdp-client.ts` (and their Swift twins in
+ * `packages/swift-server/Sources/WebSocket/CDPProxy.swift`), because the
+ * page-side `CDPClient` branches on the exact numeric code.
+ */
+/**
+ * Sent to a CDP client that is evicted because a newer client took the single
+ * proxy slot. The page-side `CDPClient` recognises it and stops
+ * auto-reconnecting (otherwise two webapp tabs on one instance evict each
+ * other forever). MUST stay in sync with `CDP_SUPERSEDED_CLOSE_CODE` in
+ * `packages/webapp/src/cdp/cdp-client.ts`.
+ */
+export const CDP_SUPERSEDED_CLOSE_CODE = 4001;
+/**
+ * Sent to the active CDP client after the proxy's Chrome-leg WebSocket dropped
+ * and was re-established (or definitively failed to come back). Chrome
+ * discards every CDP session when that socket closes, so the page's cached
+ * `sessionId`s are dead — but nothing else tells it. The page-side `CDPClient`
+ * treats this code as "reconnect and reset session state" (unlike
+ * {@link CDP_SUPERSEDED_CLOSE_CODE}, it does NOT latch superseded). MUST stay
+ * in sync with `CDP_UPSTREAM_RESET_CLOSE_CODE` in
+ * `packages/webapp/src/cdp/cdp-client.ts`.
+ */
+export const CDP_UPSTREAM_RESET_CLOSE_CODE = 4002;
+/** Close reason paired with {@link CDP_UPSTREAM_RESET_CLOSE_CODE}. */
+export const CDP_UPSTREAM_RESET_CLOSE_REASON = 'upstream-reset';