@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/http2-bridge-server.test.js

@@ -0,0 +1,2129 @@
+import { duplexPair } from "node:stream";
+import http2 from "node:http2";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { buildHttp2BridgeForwardUrl, classifyStreamAgainstGoaway, createBridgeBodyReservation, createBridgeRouteBodyLedger, createHttp2BridgeServer, getBridgeBodyReservedBytesForTest, parseCanonicalBridgeRequestPath, resetBridgeBodyReservationsForTest, wrapDuplexChannelAsNodeDuplex, BridgeProcessCapacityError, DEFAULT_HTTP2_BRIDGE_MAX_BUFFERED_READ_BYTES, DEFAULT_HTTP2_BRIDGE_PING_INTERVAL_MS, DEFAULT_HTTP2_BRIDGE_PING_STALL_MS, HTTP2_BRIDGE_ENABLE_PUSH, HTTP2_BRIDGE_HEADER_TABLE_SIZE, HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS, HTTP2_BRIDGE_MAX_DEFLATE_DYNAMIC_TABLE_SIZE, HTTP2_BRIDGE_MAX_HEADER_LIST_PAIRS, HTTP2_BRIDGE_MAX_HEADER_LIST_SIZE, HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES, HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES, HTTP2_BRIDGE_MAX_SESSION_INVALID_FRAMES, HTTP2_BRIDGE_MAX_SESSION_MEMORY, HTTP2_BRIDGE_MAX_SESSION_REJECTED_STREAMS, HTTP2_BRIDGE_SERVER_OPTIONS, HTTP2_BRIDGE_STREAM_RESET_BURST, HTTP2_BRIDGE_STREAM_RESET_RATE, } from "./http2-bridge-server.js";
+import { createSandboxHttp2BridgeGateway, DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES, HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST, } from "./sandbox-callback-bridge.js";
+/**
+ * Unit harness for the host HTTP/2 server and the sandbox HTTP/2 client
+ * gateway. Every test connects the pair over one paired in-memory `Duplex`
+ * (`node:stream`'s `duplexPair`) — no real TCP socket and no spawned sandbox
+ * process. This proves the two halves speak one wire-compatible HTTP/2
+ * session with no network in between.
+ */
+const BRIDGE_TOKEN = "test-bridge-token-fixed-length-32";
+/** Wrap one side of a paired `Duplex` as a minimal fake `CommandManagedDuplexChannel`. */
+function fakeChannelFromDuplex(duplex) {
+    const dataListeners = [];
+    const exitListeners = [];
+    duplex.on("data", (chunk) => {
+        for (const listener of dataListeners)
+            listener(chunk);
+    });
+    duplex.on("end", () => {
+        for (const listener of exitListeners)
+            listener({ exitCode: null, transportClosed: true });
+    });
+    return {
+        write: (data) => {
+            duplex.write(Buffer.from(data));
+        },
+        onData: (listener) => {
+            dataListeners.push(listener);
+        },
+        onExit: (listener) => {
+            exitListeners.push(listener);
+        },
+        stop: () => {
+            duplex.destroy();
+        },
+        close: async () => {
+            duplex.end();
+        },
+    };
+}
+/** Bind the host server to one side of a fresh paired in-memory `Duplex`.
+ * Returns the other side, unbound, for a caller to connect a client to. */
+function bindTestServer(options = {}) {
+    const bridgeToken = options.bridgeToken ?? BRIDGE_TOKEN;
+    const [serverSide, clientSide] = duplexPair();
+    const forwardRequest = options.forwardRequest ??
+        (async (request) => ({
+            status: 200,
+            headers: { "content-type": "application/json" },
+            body: Buffer.from(JSON.stringify({ echoedMethod: request.method, echoedPath: request.pathname }), "utf8"),
+        }));
+    const handle = createHttp2BridgeServer({
+        bridgeToken,
+        forwardRequest,
+        pingIntervalMs: options.pingIntervalMs,
+        pingStallMs: options.pingStallMs,
+        requestBodyTimeoutMs: options.requestBodyTimeoutMs,
+        requestBodyLifetimeCeilingMs: options.requestBodyLifetimeCeilingMs,
+        closeGraceMs: options.closeGraceMs,
+        capacityDenialSettleDeadlineMs: options.capacityDenialSettleDeadlineMs,
+        responseWriteSettleDeadlineMs: options.responseWriteSettleDeadlineMs,
+        maxBodyBytes: options.maxBodyBytes,
+        routes: options.routes,
+        onGoaway: options.onGoaway,
+        onSessionError: options.onSessionError,
+        onSession: options.onSession,
+    });
+    const channel = fakeChannelFromDuplex(serverSide);
+    handle.bindChannel(channel);
+    return { handle, bridgeToken, clientSide, serverSide };
+}
+/** Bind the server, then connect the sandbox HTTP/2 client gateway to the
+ * other side of the same paired in-memory `Duplex`. */
+function createTestPair(options = {}) {
+    const { handle, bridgeToken, clientSide, serverSide } = bindTestServer(options);
+    const gateway = createSandboxHttp2BridgeGateway({
+        bridgeToken,
+        createConnection: () => clientSide,
+    });
+    return { handle, gateway, bridgeToken, clientSide, serverSide };
+}
+/** Open a raw HTTP/2 client session directly against one side of the pair,
+ * bypassing the sandbox gateway. Some tests need direct stream control (an
+ * explicit RST_STREAM, an explicit GOAWAY) the gateway's `forwardRequest`
+ * abstraction does not expose. `settings`, when given, rides the client's
+ * own initial SETTINGS frame — for example `{ initialWindowSize: 0 }` to
+ * deny the server any flow-control credit to send response bytes with, a
+ * deterministic stall independent of the fake transport's own buffering. */
+function connectRawClient(clientSide, settings) {
+    return http2.connect("http://bridge.internal", { createConnection: () => clientSide, settings });
+}
+/** Track whether `forwardRequest` ran, so a test can prove a denied or
+ * destroyed stream never reached it. Call `markCalled()` from inside
+ * `forwardRequest`, then assert on `.called`. */
+function createForwarderCallTracker() {
+    const tracker = {
+        called: false,
+        markCalled() {
+            tracker.called = true;
+        },
+    };
+    return tracker;
+}
+/** Send one more request over `rawClient` and wait for it to complete, so a
+ * test can prove the session survived a prior faulted, stalled, or denied
+ * stream. */
+async function expectSessionStillServesARequest(rawClient, request) {
+    return new Promise((resolve, reject) => {
+        const req = rawClient.request({
+            ":method": request.method,
+            ":path": request.path,
+            authorization: `Bearer ${request.token}`,
+        });
+        let status = 0;
+        let body = "";
+        req.setEncoding("utf8");
+        req.on("response", (headers) => {
+            status = Number(headers[":status"]) || 0;
+        });
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => resolve({ status, body }));
+        req.on("error", reject);
+        req.end();
+    });
+}
+describe("createHttp2BridgeServer + createSandboxHttp2BridgeGateway", () => {
+    // Every test in this file shares the module-scope process reservation
+    // total. A reservation one test leaves unreleased would otherwise lower
+    // the ceiling every later test sees, so each test starts from zero.
+    beforeEach(() => {
+        resetBridgeBodyReservationsForTest();
+    });
+    it("test_one_session_over_a_fake_channel_forwards_a_request", async () => {
+        const { handle, gateway } = createTestPair();
+        try {
+            const response = await gateway.forwardRequest({
+                method: "GET",
+                path: "/api/agents/me",
+                query: "",
+                headers: {},
+                body: Buffer.alloc(0),
+                receivedToken: BRIDGE_TOKEN,
+            });
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body.toString("utf8"))).toEqual({
+                echoedMethod: "GET",
+                echoedPath: "/api/agents/me",
+            });
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("test_sixty_four_concurrent_streams_all_complete", async () => {
+        const seenPaths = new Set();
+        const { handle, gateway } = createTestPair({
+            forwardRequest: async (request) => {
+                // Force real overlap: every forward call waits one macrotask before it
+                // resolves, so 64 concurrent streams are genuinely in flight together.
+                await new Promise((resolve) => setTimeout(resolve, 5));
+                seenPaths.add(request.pathname);
+                return {
+                    status: 200,
+                    headers: {},
+                    body: Buffer.from(JSON.stringify({ echoedPath: request.pathname }), "utf8"),
+                };
+            },
+        });
+        try {
+            const requests = Array.from({ length: 64 }, (_, index) => gateway.forwardRequest({
+                method: "GET",
+                path: `/api/issues/${index}`,
+                query: "",
+                headers: {},
+                body: Buffer.alloc(0),
+                receivedToken: BRIDGE_TOKEN,
+            }));
+            const responses = await Promise.all(requests);
+            expect(responses).toHaveLength(64);
+            for (const [index, response] of responses.entries()) {
+                expect(response.status).toBe(200);
+                expect(JSON.parse(response.body.toString("utf8"))).toEqual({
+                    echoedPath: `/api/issues/${index}`,
+                });
+            }
+            expect(seenPaths.size).toBe(64);
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("test_ping_detects_a_silent_stall_within_twenty_seconds", async () => {
+        // The production defaults name the twenty-second bound this test name
+        // promises. The mechanism test below exercises the same code path with
+        // small overrides, so the suite stays fast.
+        expect(DEFAULT_HTTP2_BRIDGE_PING_STALL_MS).toBe(20_000);
+        expect(DEFAULT_HTTP2_BRIDGE_PING_INTERVAL_MS).toBeLessThan(DEFAULT_HTTP2_BRIDGE_PING_STALL_MS);
+        const [serverSide] = duplexPair();
+        // Nothing consumes the other side of the pair, so every PING frame the
+        // server sends goes unacknowledged: a silent stall.
+        const stallErrors = [];
+        const handle = createHttp2BridgeServer({
+            bridgeToken: BRIDGE_TOKEN,
+            forwardRequest: async () => ({ status: 200 }),
+            pingIntervalMs: 15,
+            pingStallMs: 40,
+            onSessionError: (error) => stallErrors.push(error),
+        });
+        handle.bindChannel(fakeChannelFromDuplex(serverSide));
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        expect(stallErrors).toHaveLength(1);
+        expect(stallErrors[0]?.message).toMatch(/stall/i);
+        await handle.close();
+    });
+    it("test_goaway_reports_the_last_processed_stream_identifier", async () => {
+        // GOAWAY's Last-Stream-ID names the highest stream the SENDER processed
+        // for the peer's own initiated streams. Every request stream in this
+        // transport originates from the sandbox, so the meaningful, valid
+        // direction is the host naming the last client stream it processed — not
+        // the reverse (a client-sent GOAWAY only ever carries 0 here, since
+        // server push is disabled). The sandbox gateway observes it and can
+        // classify its own dispatched stream IDs with `classifyStreamAgainstGoaway`.
+        let hostSession;
+        const goawayRecords = [];
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            onSession: (session) => {
+                hostSession = session;
+            },
+        });
+        const gateway = createSandboxHttp2BridgeGateway({
+            bridgeToken,
+            createConnection: () => clientSide,
+            onGoaway: (record) => goawayRecords.push(record),
+        });
+        try {
+            const response = await gateway.forwardRequest({
+                method: "GET",
+                path: "/api/agents/me",
+                query: "",
+                headers: {},
+                body: Buffer.alloc(0),
+                receivedToken: bridgeToken,
+            });
+            expect(response.status).toBe(200);
+            await new Promise((resolve) => {
+                hostSession?.goaway(http2.constants.NGHTTP2_NO_ERROR, 1);
+                setTimeout(resolve, 50);
+            });
+            expect(goawayRecords).toHaveLength(1);
+            expect(goawayRecords[0]?.lastStreamId).toBe(1);
+            expect(classifyStreamAgainstGoaway(1, goawayRecords[0].lastStreamId)).toBe("accepted");
+            expect(classifyStreamAgainstGoaway(3, goawayRecords[0].lastStreamId)).toBe("not_accepted");
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("test_rst_stream_fails_one_request_and_keeps_the_session", async () => {
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                if (request.pathname === "/api/agents/me") {
+                    // Hold this one open long enough for the test to RST it.
+                    await new Promise((resolve) => setTimeout(resolve, 200));
+                }
+                return { status: 200, headers: {}, body: Buffer.from(JSON.stringify({ path: request.pathname }), "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const abortedStream = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/me",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const abortedOutcome = new Promise((resolve) => {
+                abortedStream.on("error", () => resolve("aborted"));
+                abortedStream.on("close", () => resolve("closed"));
+            });
+            abortedStream.end();
+            // Give the request time to reach the server before the reset.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            abortedStream.close(http2.constants.NGHTTP2_CANCEL);
+            await abortedOutcome;
+            // The session survives: a second request completes normally.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/companies/co1",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+            expect(JSON.parse(survivingResponse.body)).toEqual({ path: "/api/companies/co1" });
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_the_server_aborts_the_forward_when_the_client_closes_the_stream", async () => {
+        let capturedRequest;
+        let releaseForward;
+        const forwardHeld = new Promise((resolve) => {
+            releaseForward = resolve;
+        });
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                capturedRequest = request;
+                // Hold the handler open, so the test controls exactly when the
+                // client-side stream close happens relative to the forward.
+                await forwardHeld;
+                return { status: 200, body: Buffer.from("{}", "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const stream = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/me",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const streamClosed = new Promise((resolve) => {
+                stream.on("error", () => resolve());
+                stream.on("close", () => resolve());
+            });
+            stream.end();
+            // Give the request time to reach the server and enter forwardRequest.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(capturedRequest).toBeDefined();
+            expect(capturedRequest.signal.aborted).toBe(false);
+            stream.close(http2.constants.NGHTTP2_CANCEL);
+            await streamClosed;
+            // Give the server's own stream `close` listener a turn to run.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(capturedRequest.signal.aborted).toBe(true);
+            releaseForward();
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_one_aborted_stream_leaves_the_session_and_the_other_streams_open", async () => {
+        const signalsByPath = new Map();
+        let releaseSurvivor;
+        const survivorHeld = new Promise((resolve) => {
+            releaseSurvivor = resolve;
+        });
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                signalsByPath.set(request.pathname, request.signal);
+                if (request.pathname === "/api/agents/aborted") {
+                    // The RST — not a manual release — is what must end this forward:
+                    // it settles only when the stream's own signal fires, so the test
+                    // proves the signal itself unblocks the handler.
+                    await new Promise((_resolve, reject) => {
+                        request.signal.addEventListener("abort", () => reject(new Error("aborted")), {
+                            once: true,
+                        });
+                    }).catch(() => undefined);
+                }
+                else if (request.pathname === "/api/agents/survivor") {
+                    await survivorHeld;
+                }
+                return { status: 200, body: Buffer.from(JSON.stringify({ path: request.pathname }), "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const abortedStream = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/aborted",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const survivorStream = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/survivor",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const abortedStreamClosed = new Promise((resolve) => {
+                abortedStream.on("error", () => resolve());
+                abortedStream.on("close", () => resolve());
+            });
+            // Capture the survivor stream's own response, so the test proves this
+            // exact stream — the sibling of the aborted one, on the same session —
+            // completes normally, not merely that the session admits a fresh one.
+            const survivorResponse = new Promise((resolve, reject) => {
+                let status = 0;
+                let body = "";
+                survivorStream.setEncoding("utf8");
+                survivorStream.on("response", (h) => {
+                    status = Number(h[":status"]) || 0;
+                });
+                survivorStream.on("data", (chunk) => (body += chunk));
+                survivorStream.on("end", () => resolve({ status, body }));
+                survivorStream.on("error", reject);
+            });
+            abortedStream.end();
+            survivorStream.end();
+            // Give both requests time to reach the server and enter forwardRequest.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            abortedStream.close(http2.constants.NGHTTP2_CANCEL);
+            await abortedStreamClosed;
+            // Give the server's own stream `close` listener a turn to run.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            // The one aborted stream's signal fires. The other, still-open stream's
+            // signal stays untouched: the abort is local to its own stream.
+            expect(signalsByPath.get("/api/agents/aborted")?.aborted).toBe(true);
+            expect(signalsByPath.get("/api/agents/survivor")?.aborted).toBe(false);
+            releaseSurvivor();
+            const response = await survivorResponse;
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body)).toEqual({ path: "/api/agents/survivor" });
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_live_forward_work_never_passes_the_stream_limit", async () => {
+        // A forward that is never aborted holds open until the caller aborts it
+        // — this stands in for a forward stuck at its own long timeout. Only the
+        // per-stream abort binding this file adds can free such a forward before
+        // that timeout, so this count proves the binding, not merely the HTTP/2
+        // session's own stream-slot accounting (a stream's protocol slot frees on
+        // RST regardless of whether its forward call ever settles).
+        let liveForwards = 0;
+        let maxLiveForwards = 0;
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                liveForwards += 1;
+                maxLiveForwards = Math.max(maxLiveForwards, liveForwards);
+                try {
+                    await new Promise((resolve, reject) => {
+                        if (request.signal.aborted) {
+                            reject(new Error("aborted"));
+                            return;
+                        }
+                        request.signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+                    });
+                    return { status: 200, body: Buffer.from(JSON.stringify({ path: request.pathname }), "utf8") };
+                }
+                finally {
+                    liveForwards -= 1;
+                }
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const openAndCancelOneBatch = async (label) => {
+                const streams = Array.from({ length: HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS }, (_, index) => rawClient.request({
+                    ":method": "GET",
+                    ":path": `/api/issues/${label}-${index}`,
+                    authorization: `Bearer ${bridgeToken}`,
+                }));
+                for (const stream of streams)
+                    stream.end();
+                await new Promise((resolve) => setTimeout(resolve, 30));
+                for (const stream of streams)
+                    stream.close(http2.constants.NGHTTP2_CANCEL);
+                await new Promise((resolve) => setTimeout(resolve, 30));
+            };
+            // One full batch of maximum-concurrency streams, closed while their
+            // forwards are still held open, then a second full batch opened right
+            // after. Without the abort binding, the first batch's forwards would
+            // still be alive when the second batch dispatches, doubling the live-
+            // forward count past the stream limit.
+            await openAndCancelOneBatch("first");
+            await openAndCancelOneBatch("second");
+            expect(maxLiveForwards).toBeLessThanOrEqual(HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS);
+            expect(liveForwards).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_stalled_request_body_settles_instead_of_hanging_forever", async () => {
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 30,
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const startMs = Date.now();
+            // A partial, never-ended body stalls the read. The timeout destroys the
+            // stream, so the request settles (through an `error` or a `close`, not
+            // a clean response) well inside the bound, instead of hanging forever.
+            await new Promise((resolve) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                req.on("error", () => resolve());
+                req.on("close", () => resolve());
+                req.write("partial-body");
+            });
+            expect(Date.now() - startMs).toBeLessThan(5_000);
+            expect(forwarderTracker.called).toBe(false);
+            // The session survives the timed-out stream: a second, complete request
+            // still succeeds.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "POST",
+                path: "/api/issues/abc/comments",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_slow_but_progressing_request_body_completes_instead_of_timing_out", async () => {
+        // The idle bound is well under the total time the whole body takes, so a
+        // one-shot bound over the full read would trip. Each chunk resets the
+        // bound, so the request still completes.
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 80,
+            forwardRequest: async (request) => ({
+                status: 200,
+                body: Buffer.from(JSON.stringify({ bodyLength: request.body.byteLength }), "utf8"),
+            }),
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                // Five chunks, each inside the idle bound, summing past it.
+                let sent = 0;
+                const sendNext = () => {
+                    if (sent >= 5) {
+                        req.end();
+                        return;
+                    }
+                    sent += 1;
+                    req.write("chunk");
+                    setTimeout(sendNext, 40);
+                };
+                sendNext();
+            });
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body)).toEqual({ bodyLength: "chunk".length * 5 });
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_slow_trickle_that_never_ends_stops_at_the_one_shot_ceiling", async () => {
+        // The idle bound is generous, so a chunk every 40ms never lets it
+        // expire. The ceiling (150ms) arms once, when the read starts, and
+        // never renews on a chunk: this proves a peer that keeps every chunk
+        // gap under the idle bound, but never finishes the body, still loses
+        // the stream once the read's total age passes the ceiling. This is the
+        // failure mode an authenticated sandbox could otherwise use to hold one
+        // of the concurrent-stream slots open indefinitely: keep sending just
+        // enough to dodge the idle bound, and never finish the body.
+        //
+        // Every write below lands well before the ceiling, and the test makes
+        // no further call on the stream after the last one: nothing races the
+        // server's own reset of it once the ceiling passes, so this proves the
+        // bound from the server's own, deterministic effect (the forward
+        // handler never runs) instead of from a raw client-stream event whose
+        // timing Node does not guarantee here.
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 5_000,
+            requestBodyLifetimeCeilingMs: 150,
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const req = rawClient.request({
+                ":method": "POST",
+                ":path": "/api/issues/abc/comments",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            req.on("error", () => undefined);
+            // Four chunks, 40ms apart, well inside the idle bound. The total send
+            // time, about 160ms, passes the 150ms ceiling. The body never ends:
+            // this request never calls `.end()`.
+            for (let chunkIndex = 0; chunkIndex < 4; chunkIndex += 1) {
+                req.write("chunk");
+                await new Promise((resolve) => setTimeout(resolve, 40));
+            }
+            // Wait past the ceiling with no further write, so the server has time
+            // to destroy the stalled stream on its own.
+            await new Promise((resolve) => setTimeout(resolve, 150));
+            expect(forwarderTracker.called).toBe(false);
+            // The session survives the stopped stream: a second, complete request
+            // still succeeds.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "POST",
+                path: "/api/issues/abc/comments",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_request_body_within_the_lifetime_bound_still_completes", async () => {
+        // A generous ceiling must not interfere with an ordinary request that
+        // finishes well inside it.
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 5_000,
+            requestBodyLifetimeCeilingMs: 5_000,
+            forwardRequest: async (request) => ({
+                status: 200,
+                body: Buffer.from(JSON.stringify({ bodyLength: request.body.byteLength }), "utf8"),
+            }),
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                req.write("chunk");
+                req.end();
+            });
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body)).toEqual({ bodyLength: "chunk".length });
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_slow_but_progressing_upload_completes_within_the_ceiling", async () => {
+        // The idle bound and the ceiling are both generous, so a slow but
+        // genuinely progressing upload completes normally, instead of losing
+        // its stream mid-upload.
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 5_000,
+            requestBodyLifetimeCeilingMs: 5_000,
+            forwardRequest: async (request) => {
+                forwarderTracker.markCalled();
+                return { status: 200, body: Buffer.from(JSON.stringify({ bodyLength: request.body.byteLength }), "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                void (async () => {
+                    // Six chunks, 40ms apart (well inside the idle bound), each real
+                    // progress.
+                    for (let sent = 0; sent < 6; sent += 1) {
+                        req.write("chunk");
+                        await new Promise((r) => setTimeout(r, 40));
+                    }
+                    req.end();
+                })();
+            });
+            expect(forwarderTracker.called).toBe(true);
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body)).toEqual({ bodyLength: "chunk".length * 6 });
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_close_force_destroys_a_session_with_a_stalled_stream_instead_of_waiting_forever", async () => {
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            // A body timeout far longer than the close grace, so `close()` is the
+            // only thing that bounds the wait in this test.
+            requestBodyTimeoutMs: 60_000,
+            closeGraceMs: 30,
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const req = rawClient.request({
+                ":method": "POST",
+                ":path": "/api/issues/abc/comments",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            req.write("partial-body");
+            // Give the request time to reach the server before close() runs.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            const closeStart = Date.now();
+            await handle.close();
+            const closeElapsedMs = Date.now() - closeStart;
+            // `close()` force-destroyed the stalled session at the grace bound,
+            // instead of waiting on `session.close()` forever.
+            expect(closeElapsedMs).toBeLessThan(5_000);
+        }
+        finally {
+            rawClient.close();
+        }
+    });
+    it("test_the_server_sets_every_bounded_option", async () => {
+        expect(HTTP2_BRIDGE_SERVER_OPTIONS).toEqual({
+            settings: {
+                enablePush: HTTP2_BRIDGE_ENABLE_PUSH,
+                maxConcurrentStreams: HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS,
+                maxHeaderListSize: HTTP2_BRIDGE_MAX_HEADER_LIST_SIZE,
+                headerTableSize: HTTP2_BRIDGE_HEADER_TABLE_SIZE,
+            },
+            maxSessionMemory: HTTP2_BRIDGE_MAX_SESSION_MEMORY,
+            maxHeaderListPairs: HTTP2_BRIDGE_MAX_HEADER_LIST_PAIRS,
+            maxDeflateDynamicTableSize: HTTP2_BRIDGE_MAX_DEFLATE_DYNAMIC_TABLE_SIZE,
+            maxSessionInvalidFrames: HTTP2_BRIDGE_MAX_SESSION_INVALID_FRAMES,
+            maxSessionRejectedStreams: HTTP2_BRIDGE_MAX_SESSION_REJECTED_STREAMS,
+            streamResetRate: HTTP2_BRIDGE_STREAM_RESET_RATE,
+            streamResetBurst: HTTP2_BRIDGE_STREAM_RESET_BURST,
+        });
+        expect(HTTP2_BRIDGE_ENABLE_PUSH).toBe(false);
+        expect(HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS).toBe(4);
+        expect(HTTP2_BRIDGE_MAX_HEADER_LIST_SIZE).toBe(16384);
+        expect(HTTP2_BRIDGE_HEADER_TABLE_SIZE).toBe(4096);
+        expect(HTTP2_BRIDGE_MAX_SESSION_MEMORY).toBe(16);
+        expect(HTTP2_BRIDGE_MAX_HEADER_LIST_PAIRS).toBe(128);
+        expect(HTTP2_BRIDGE_MAX_DEFLATE_DYNAMIC_TABLE_SIZE).toBe(4096);
+        expect(HTTP2_BRIDGE_MAX_SESSION_INVALID_FRAMES).toBe(100);
+        expect(HTTP2_BRIDGE_MAX_SESSION_REJECTED_STREAMS).toBe(100);
+        expect(HTTP2_BRIDGE_STREAM_RESET_RATE).toBe(10);
+        expect(HTTP2_BRIDGE_STREAM_RESET_BURST).toBe(100);
+        // The running server actually carries the bound, not only the constant:
+        // the four `settings` values ride the server's outbound SETTINGS frame,
+        // so the connected client's `remoteSettings` reflects them after the
+        // handshake completes.
+        const { handle, clientSide } = bindTestServer();
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const remoteSettings = await new Promise((resolve) => {
+                rawClient.once("remoteSettings", resolve);
+            });
+            expect(remoteSettings.enablePush).toBe(HTTP2_BRIDGE_ENABLE_PUSH);
+            expect(remoteSettings.maxConcurrentStreams).toBe(HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS);
+            expect(remoteSettings.maxHeaderListSize).toBe(HTTP2_BRIDGE_MAX_HEADER_LIST_SIZE);
+            expect(remoteSettings.headerTableSize).toBe(HTTP2_BRIDGE_HEADER_TABLE_SIZE);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_the_host_body_budget_matches_the_stream_limit", () => {
+        // The multiplier counts every retained `Buffer` copy of one live
+        // forward's request and response body: four exact `Buffer` rows. The
+        // forward path decodes no body to a string, so no row applies the
+        // two-bytes-per-UTF-16-code-unit string overhead any more.
+        // `test_live_forward_work_never_passes_the_stream_limit` proves the
+        // count of live forwards never passes `HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS`,
+        // so this multiplier bounds live forwards, not merely open streams.
+        // `HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES` uses this exact same formula to
+        // enforce it as a real per-route cap, not merely a derived figure.
+        const expectedRouteBudget = HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS * 4 * DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES;
+        expect(expectedRouteBudget).toBe(168_820_736);
+        expect(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES).toBe(expectedRouteBudget);
+    });
+    describe("createBridgeBodyReservation", () => {
+        it("test_a_reservation_denies_a_chunk_that_passes_the_process_ceiling", () => {
+            const owner = createBridgeBodyReservation();
+            try {
+                expect(owner.reserve(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES)).toBe(true);
+                expect(owner.heldBytes).toBe(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES);
+                expect(getBridgeBodyReservedBytesForTest()).toBe(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES);
+                // One more byte passes the ceiling: denied, and it holds no bytes.
+                expect(owner.reserve(1)).toBe(false);
+                expect(owner.heldBytes).toBe(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES);
+                expect(getBridgeBodyReservedBytesForTest()).toBe(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES);
+            }
+            finally {
+                owner.release();
+            }
+        });
+        it("test_a_reservation_denies_the_concatenated_copy_that_passes_the_process_ceiling", () => {
+            const owner = createBridgeBodyReservation();
+            try {
+                // The chunk-array reservation alone passes comfortably.
+                const chunkArrayBytes = Math.floor(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES * 0.6);
+                expect(owner.reserve(chunkArrayBytes)).toBe(true);
+                // The concatenated `Buffer.concat` copy is a second, separate live
+                // copy of the same bytes: reserving it on top of the chunk array
+                // this owner already holds passes the ceiling, even though the
+                // chunk-array reservation alone did not.
+                expect(owner.reserve(chunkArrayBytes)).toBe(false);
+                expect(owner.heldBytes).toBe(chunkArrayBytes);
+                expect(getBridgeBodyReservedBytesForTest()).toBe(chunkArrayBytes);
+            }
+            finally {
+                owner.release();
+            }
+        });
+        it("test_a_reservation_releases_every_held_byte_one_time_only", () => {
+            const owner = createBridgeBodyReservation();
+            expect(owner.reserve(1_000)).toBe(true);
+            expect(getBridgeBodyReservedBytesForTest()).toBe(1_000);
+            owner.release();
+            expect(owner.heldBytes).toBe(0);
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            // A second release must not double-subtract: the total must not go
+            // below zero.
+            owner.release();
+            expect(owner.heldBytes).toBe(0);
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        });
+    });
+    describe("route isolation", () => {
+        it("test_a_route_ledger_denies_a_reservation_that_passes_its_own_ceiling_with_the_process_ceiling_still_open", () => {
+            // The process-wide ceiling has ample room (1 GiB); only this one
+            // route's own share is tight. A route-scoped owner must still deny
+            // the second reservation, proving the route ceiling is a real,
+            // independent check, not merely a reflection of the process total.
+            const routeLedger = createBridgeRouteBodyLedger();
+            const owner = createBridgeBodyReservation(routeLedger);
+            try {
+                expect(owner.reserve(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES)).toBe(true);
+                expect(routeLedger.reservedBytes).toBe(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES);
+                expect(owner.reserve(1)).toBe(false);
+                expect(owner.heldBytes).toBe(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES);
+                expect(routeLedger.reservedBytes).toBe(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES);
+                // The process-wide total only ever grew by what this owner actually
+                // holds: the denied byte reserved against neither total.
+                expect(getBridgeBodyReservedBytesForTest()).toBe(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES);
+            }
+            finally {
+                owner.release();
+            }
+        });
+        it("test_one_route_at_its_own_ceiling_never_blocks_a_sibling_routes_reservation", () => {
+            // Two routes, two ledgers. Route A spends its own entire ceiling.
+            // Route B's reservation, against its own separate ledger, must still
+            // succeed: the process-wide total (1 GiB) has room for both routes'
+            // ceilings many times over, so only route isolation — not the shared
+            // total — could explain a denial here.
+            const routeLedgerA = createBridgeRouteBodyLedger();
+            const routeLedgerB = createBridgeRouteBodyLedger();
+            const ownerA = createBridgeBodyReservation(routeLedgerA);
+            const ownerB = createBridgeBodyReservation(routeLedgerB);
+            try {
+                expect(ownerA.reserve(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES)).toBe(true);
+                expect(ownerA.reserve(1)).toBe(false);
+                expect(ownerB.reserve(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES)).toBe(true);
+            }
+            finally {
+                ownerA.release();
+                ownerB.release();
+            }
+        });
+        it("test_two_bridge_server_routes_isolate_their_own_reservations_end_to_end", async () => {
+            // The end-to-end proof: while route A's own forward holds its own
+            // entire per-route ceiling in flight, a second, independent route's
+            // request must still succeed. Each `bindTestServer` call is its own
+            // route (its own `createHttp2BridgeServer` call, so its own route
+            // ledger). Route A's forward parks on `releaseRouteAHold` after it
+            // reserves, so its reservation stays live — not merely reserved and
+            // immediately released — for the whole time route B's request runs.
+            let markRouteAReserved;
+            const routeAReserved = new Promise((resolve) => {
+                markRouteAReserved = resolve;
+            });
+            let releaseRouteAHold;
+            const routeAHold = new Promise((resolve) => {
+                releaseRouteAHold = resolve;
+            });
+            const routeA = bindTestServer({
+                forwardRequest: async (request) => {
+                    // Reserve this route's own entire ceiling against its own ledger,
+                    // simulating route A at its own documented peak.
+                    if (!request.reservation.reserve(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES)) {
+                        throw new BridgeProcessCapacityError();
+                    }
+                    markRouteAReserved();
+                    await routeAHold;
+                    return { status: 200 };
+                },
+            });
+            const routeB = bindTestServer({
+                forwardRequest: async () => ({ status: 200 }),
+            });
+            const rawClientA = connectRawClient(routeA.clientSide);
+            const rawClientB = connectRawClient(routeB.clientSide);
+            try {
+                const pendingResponseA = expectSessionStillServesARequest(rawClientA, {
+                    method: "GET",
+                    path: "/api/agents/me",
+                    token: routeA.bridgeToken,
+                });
+                // Wait until route A's forward actually holds its own ceiling —
+                // not merely until the request was sent — before checking route B.
+                await routeAReserved;
+                expect(getBridgeBodyReservedBytesForTest()).toBeGreaterThanOrEqual(HTTP2_BRIDGE_MAX_ROUTE_BODY_BYTES);
+                // Route A now holds its own entire per-route ceiling, live. The
+                // process-wide total still has headroom (1 GiB minus one 161 MiB
+                // route), so route B's independent request succeeds only if its own
+                // ledger is genuinely separate from route A's.
+                const responseB = await expectSessionStillServesARequest(rawClientB, {
+                    method: "GET",
+                    path: "/api/agents/me",
+                    token: routeB.bridgeToken,
+                });
+                expect(responseB.status).toBe(200);
+                releaseRouteAHold();
+                const responseA = await pendingResponseA;
+                expect(responseA.status).toBe(200);
+            }
+            finally {
+                rawClientA.close();
+                rawClientB.close();
+                await routeA.handle.close();
+                await routeB.handle.close();
+            }
+        });
+    });
+    it("test_the_stream_handler_releases_its_reservation_on_completion_error_abort_timeout_and_close", async () => {
+        // Every stream, no matter how it ends, must leave the process-wide
+        // reservation total at zero: `handleStream`'s `finally` block releases
+        // exactly one owner exactly one time on every exit path.
+        async function runCompletionCase() {
+            const { handle, bridgeToken, clientSide } = bindTestServer({
+                forwardRequest: async (request) => {
+                    request.reservation.reserve(1_000);
+                    return { status: 200, body: Buffer.from("{}", "utf8") };
+                },
+            });
+            const rawClient = connectRawClient(clientSide);
+            try {
+                const response = await expectSessionStillServesARequest(rawClient, {
+                    method: "GET",
+                    path: "/api/agents/me",
+                    token: bridgeToken,
+                });
+                expect(response.status).toBe(200);
+                expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            }
+            finally {
+                rawClient.close();
+                await handle.close();
+            }
+        }
+        async function runErrorCase() {
+            const { handle, bridgeToken, clientSide } = bindTestServer({
+                forwardRequest: async (request) => {
+                    request.reservation.reserve(1_000);
+                    throw new Error("forward handler fault");
+                },
+            });
+            const rawClient = connectRawClient(clientSide);
+            try {
+                const response = await expectSessionStillServesARequest(rawClient, {
+                    method: "GET",
+                    path: "/api/agents/me",
+                    token: bridgeToken,
+                });
+                expect(response.status).toBe(502);
+                expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            }
+            finally {
+                rawClient.close();
+                await handle.close();
+            }
+        }
+        async function runAbortCase() {
+            const { handle, bridgeToken, clientSide } = bindTestServer({
+                forwardRequest: async (request) => {
+                    request.reservation.reserve(1_000);
+                    await new Promise((resolve) => {
+                        if (request.signal.aborted) {
+                            resolve();
+                            return;
+                        }
+                        request.signal.addEventListener("abort", () => resolve(), { once: true });
+                    });
+                    return { status: 200 };
+                },
+            });
+            const rawClient = connectRawClient(clientSide);
+            try {
+                const stream = rawClient.request({
+                    ":method": "GET",
+                    ":path": "/api/agents/me",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                const streamClosed = new Promise((resolve) => {
+                    stream.on("error", () => resolve());
+                    stream.on("close", () => resolve());
+                });
+                stream.end();
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                stream.close(http2.constants.NGHTTP2_CANCEL);
+                await streamClosed;
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            }
+            finally {
+                rawClient.close();
+                await handle.close();
+            }
+        }
+        async function runTimeoutCase() {
+            const { handle, bridgeToken, clientSide } = bindTestServer({
+                requestBodyTimeoutMs: 30,
+                forwardRequest: async () => ({ status: 200 }),
+            });
+            const rawClient = connectRawClient(clientSide);
+            try {
+                await new Promise((resolve) => {
+                    const req = rawClient.request({
+                        ":method": "POST",
+                        ":path": "/api/issues/abc/comments",
+                        authorization: `Bearer ${bridgeToken}`,
+                    });
+                    req.on("error", () => resolve());
+                    req.on("close", () => resolve());
+                    req.write("partial-body");
+                });
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            }
+            finally {
+                rawClient.close();
+                await handle.close();
+            }
+        }
+        async function runCloseCase() {
+            const { handle, bridgeToken, clientSide } = bindTestServer({
+                requestBodyTimeoutMs: 60_000,
+                closeGraceMs: 30,
+            });
+            const rawClient = connectRawClient(clientSide);
+            try {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                req.write("partial-body");
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                await handle.close();
+                await new Promise((resolve) => setTimeout(resolve, 20));
+                expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            }
+            finally {
+                rawClient.close();
+            }
+        }
+        await runCompletionCase();
+        await runErrorCase();
+        await runAbortCase();
+        await runTimeoutCase();
+        await runCloseCase();
+    }, 10_000);
+    it("test_a_backpressured_response_holds_its_reservation_until_the_write_settles", async () => {
+        // `stream.end(body)` only queues `body` for asynchronous transmission.
+        // A client that never reads its response leaves those bytes in process
+        // memory well after `end()` returns, so the reservation covering them
+        // must stay held until the write actually settles, not merely until the
+        // call to `end()` returns.
+        const responseBytes = 4 * 1024 * 1024;
+        const responseBody = Buffer.alloc(responseBytes, 0x61);
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                // Mirror the real forward path: the handler reserves the response
+                // body it read from the sandbox target before returning it.
+                if (!request.reservation.reserve(responseBytes)) {
+                    throw new BridgeProcessCapacityError();
+                }
+                return { status: 200, body: responseBody };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const req = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/me",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            // Deliberately paused: no `resume()` and no `data` listener yet, so
+            // the client never issues the flow-control credit the host needs to
+            // finish writing a response this size.
+            const headersReceived = new Promise((resolve) => {
+                req.once("response", () => resolve());
+            });
+            req.end();
+            await headersReceived;
+            // Give the host's `stream.end()` call, and its microtask queue, a
+            // turn to run — the write is now queued but the client still is not
+            // draining it.
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(getBridgeBodyReservedBytesForTest()).toBeGreaterThan(0);
+            const drained = new Promise((resolve) => {
+                req.on("data", () => {
+                    // Discard: this test only cares that the bytes left the host.
+                });
+                req.once("end", () => resolve());
+            });
+            req.resume();
+            await drained;
+            // Give the host's `finally` block a turn to run after the write
+            // settles.
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_peer_reset_holds_the_reservation_until_the_active_forward_settles", async () => {
+        let capturedRequest;
+        let releaseForward;
+        const forwardHeld = new Promise((resolve) => {
+            releaseForward = resolve;
+        });
+        let forwardSettled = false;
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                capturedRequest = request;
+                // Stand in for a live response-body copy `readBridgeForwardResponseBody`
+                // (`execution-target.ts`) would reserve against this same owner.
+                request.reservation.reserve(10_000);
+                // The forward stays active past the peer's own reset: it settles
+                // only when the test releases it below, not merely when the abort
+                // signal fires — the same shape a real outbound `fetch` bound to
+                // `request.signal` has, since an abort does not settle the fetch
+                // promise synchronously.
+                await new Promise((resolve) => {
+                    if (request.signal.aborted) {
+                        resolve();
+                        return;
+                    }
+                    request.signal.addEventListener("abort", () => resolve(), { once: true });
+                });
+                await forwardHeld;
+                forwardSettled = true;
+                return { status: 200, body: Buffer.from("{}", "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const stream = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/me",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const streamClosed = new Promise((resolve) => {
+                stream.on("error", () => resolve());
+                stream.on("close", () => resolve());
+            });
+            stream.end();
+            // Give the request time to reach the server, enter `forwardRequest`,
+            // and land its reservation.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(capturedRequest).toBeDefined();
+            expect(getBridgeBodyReservedBytesForTest()).toBe(10_000);
+            // The peer resets the stream. The forward call is still pending.
+            stream.close(http2.constants.NGHTTP2_CANCEL);
+            await streamClosed;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(capturedRequest.signal.aborted).toBe(true);
+            // The owner still holds its bytes: the active forward has not
+            // settled yet, so `handleStream`'s `finally` has not released it.
+            expect(forwardSettled).toBe(false);
+            expect(getBridgeBodyReservedBytesForTest()).toBe(10_000);
+            // Let the forward settle. The `finally` block releases the owner
+            // exactly one time, and the process total returns to zero.
+            releaseForward();
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(forwardSettled).toBe(true);
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_stalled_body_releases_its_reservation_while_other_streams_hold_theirs", async () => {
+        const releaseByPath = new Map();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 60,
+            forwardRequest: async (request) => {
+                // Stand in for a live response-body buffer: reserve, then hold the
+                // forward open until the test releases this exact path.
+                request.reservation.reserve(20_000);
+                await new Promise((resolve) => {
+                    releaseByPath.set(request.pathname, resolve);
+                });
+                return { status: 200, body: Buffer.from("{}", "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const streamA = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/a",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const streamB = rawClient.request({
+                ":method": "GET",
+                ":path": "/api/agents/b",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            // Drain each response as it arrives: `session.close()` later in this
+            // test's teardown waits for every stream to fully end on both sides,
+            // and an unread response can hold a stream open past that point.
+            streamA.resume();
+            streamB.resume();
+            streamA.end();
+            streamB.end();
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(40_000);
+            // The third stream's request body stalls past the idle bound. It
+            // never reaches `forwardRequest`, so it never reserves anything of
+            // its own; its owner still holds zero bytes at the moment it releases.
+            const streamC = rawClient.request({
+                ":method": "POST",
+                ":path": "/api/issues/abc/comments",
+                authorization: `Bearer ${bridgeToken}`,
+            });
+            const streamCClosed = new Promise((resolve) => {
+                streamC.on("error", () => resolve());
+                streamC.on("close", () => resolve());
+            });
+            streamC.write("partial-body");
+            await streamCClosed;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            // The stalled stream's release changed nothing: the other two streams
+            // keep their reservations.
+            expect(getBridgeBodyReservedBytesForTest()).toBe(40_000);
+            releaseByPath.get("/api/agents/a")?.();
+            releaseByPath.get("/api/agents/b")?.();
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_denied_stream_drains_its_body_and_holds_no_bytes", async () => {
+        const { handle, clientSide } = bindTestServer({
+            forwardRequest: async () => ({ status: 200 }),
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                // No `authorization` header: the token check denies this stream
+                // before its body is ever read.
+                const req = rawClient.request({ ":method": "POST", ":path": "/api/issues/abc/comments" });
+                let status = 0;
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", () => undefined);
+                req.on("end", () => resolve({ status }));
+                req.on("error", reject);
+                req.write(Buffer.alloc(50_000, "a"));
+                req.end();
+            });
+            expect(response.status).toBe(401);
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_request_body_reservation_denial_answers_503_on_the_wire", async () => {
+        // A denied request-body chunk must leave the stream alive long enough
+        // to answer 503 for real, on the wire — not merely destroy the stream
+        // and leave the caller with a bare reset. `respondJson` only queues the
+        // 503 write; the handler must wait for that write to settle before it
+        // destroys the stream, or the client can see a reset instead of the
+        // full response body asserted below.
+        const filler = createBridgeBodyReservation();
+        expect(filler.reserve(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES - 100)).toBe(true);
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                // Ten times the 100 bytes of headroom the filler above left.
+                req.end(Buffer.alloc(1_000, "a"));
+            });
+            expect(response.status).toBe(503);
+            expect(forwarderTracker.called).toBe(false);
+            // A raw reset delivers no body at all: parsing it here proves the
+            // full JSON response actually reached the client, not merely the
+            // status line.
+            expect(JSON.parse(response.body)).toEqual({
+                error: "The bridge host reached its reserved process body byte ceiling. Retry later.",
+            });
+            // The stream ended with a real response, not a raw reset: the session
+            // stays healthy, so a second, complete request still succeeds.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+            filler.release();
+        }
+    });
+    it("test_a_stalled_client_still_frees_the_capacity_denial_reservation_and_slot", async () => {
+        // The capacity-denial (503) path must not wait forever for its queued
+        // write to settle: a client that grants no flow-control credit for the
+        // response would otherwise hold this stream's reservation and
+        // concurrent-stream slot open indefinitely. A zero initial window
+        // denies the server any credit to send the 503 body with, at the
+        // protocol layer, regardless of the fake transport's own buffering —
+        // the same deterministic stall a real stalled peer produces.
+        const filler = createBridgeBodyReservation();
+        expect(filler.reserve(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES - 100)).toBe(true);
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            capacityDenialSettleDeadlineMs: 30,
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide, { initialWindowSize: 0 });
+        try {
+            const startMs = Date.now();
+            const closed = new Promise((resolve) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                req.on("error", () => undefined);
+                req.on("close", () => resolve());
+                // Ten times the 100 bytes of headroom the filler above left: the
+                // request body itself denies the reservation and enters the 503
+                // path.
+                req.end(Buffer.alloc(1_000, "a"));
+            });
+            await closed;
+            // The deadline bounded the wait: the stream closed near the deadline
+            // bound, not after some much longer natural settle that never comes.
+            expect(Date.now() - startMs).toBeLessThan(5_000);
+            expect(forwarderTracker.called).toBe(false);
+            // The stream's own reservation released even though the client never
+            // drained the 503 body — only the filler's own bytes remain held.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(filler.heldBytes);
+            // The stream's slot freed too. Restore a normal flow-control window
+            // first: only the denied stream above needs to stall.
+            await new Promise((resolve) => rawClient.settings({ initialWindowSize: 65_535 }, () => resolve()));
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+            filler.release();
+        }
+    });
+    it("test_a_stalled_normal_response_still_frees_its_reservation_and_slot", async () => {
+        // The completed-response (200) write path must not wait forever for its
+        // queued write to settle either: a client that grants no flow-control
+        // credit for the response would otherwise hold this stream's
+        // reservation and concurrent-stream slot open indefinitely, the same
+        // failure mode the capacity-denial path already guards against. A zero
+        // initial window denies the server any credit to send the response body
+        // with, at the protocol layer, regardless of the fake transport's own
+        // buffering.
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            responseWriteSettleDeadlineMs: 30,
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200, headers: {}, body: Buffer.alloc(1_000, "a") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide, { initialWindowSize: 0 });
+        try {
+            const startMs = Date.now();
+            const closed = new Promise((resolve) => {
+                const req = rawClient.request({
+                    ":method": "GET",
+                    ":path": "/api/agents/me",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                req.on("error", () => undefined);
+                req.on("close", () => resolve());
+                req.end();
+            });
+            await closed;
+            expect(forwarderTracker.called).toBe(true);
+            // The deadline bounded the wait: the stream closed near the deadline
+            // bound, not after some much longer natural settle that never comes.
+            expect(Date.now() - startMs).toBeLessThan(5_000);
+            // This stream's own reservation released even though the client never
+            // drained the response body.
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+            // The stream's slot freed too. Restore a normal flow-control window
+            // first: only the stalled stream above needs to stall.
+            await new Promise((resolve) => rawClient.settings({ initialWindowSize: 65_535 }, () => resolve()));
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_normal_response_that_settles_in_time_is_left_alone", async () => {
+        // A response that genuinely settles inside the deadline must not be
+        // force-destroyed: the bounded wait exists only for a stream that never
+        // settles on its own.
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            responseWriteSettleDeadlineMs: 5_000,
+            forwardRequest: async () => ({
+                status: 200,
+                headers: { "content-type": "application/json" },
+                body: Buffer.from(JSON.stringify({ ok: true }), "utf8"),
+            }),
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: bridgeToken,
+            });
+            expect(response.status).toBe(200);
+            expect(JSON.parse(response.body)).toEqual({ ok: true });
+            expect(getBridgeBodyReservedBytesForTest()).toBe(0);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_response_reservation_denial_answers_503_on_the_wire", async () => {
+        // The response reader on the sandbox target side
+        // (`readBridgeForwardResponseBody`) denies its own reservation and
+        // throws `BridgeProcessCapacityError` from inside `forwardRequest`,
+        // after the forward handler already ran — a different call site than
+        // the request-body denial above, but the same 503-before-destroy
+        // contract must hold: the stream must stay alive long enough to answer
+        // 503 for real, on the wire, not merely destroy and leave the caller
+        // with a bare reset.
+        const forwarderTracker = createForwarderCallTracker();
+        // Only the first call denies: the surviving-request check below reuses
+        // the same session for a second, independent request, which must
+        // succeed once this first stream's reservation released.
+        let forwardCalls = 0;
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                forwardCalls += 1;
+                if (forwardCalls === 1) {
+                    throw new BridgeProcessCapacityError();
+                }
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "GET",
+                    ":path": "/api/agents/me",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                req.end();
+            });
+            expect(response.status).toBe(503);
+            expect(forwarderTracker.called).toBe(true);
+            // A raw reset delivers no body at all: parsing it here proves the
+            // full JSON response actually reached the client, not merely the
+            // status line.
+            expect(JSON.parse(response.body)).toEqual({
+                error: "The bridge host reached its reserved process body byte ceiling. Retry later.",
+            });
+            // The stream ended with a real response, not a raw reset: the session
+            // stays healthy, so a second, complete request still succeeds.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: bridgeToken,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_denied_concatenated_request_body_never_allocates_the_copy", async () => {
+        // The chunk-array copy and the concatenated copy are two separate live
+        // buffers, so each must reserve on its own. Leave room for the first but
+        // not the second: a correct reader checks the reservation before
+        // `Buffer.concat` allocates the copy, so the denied concatenated copy
+        // must never call `Buffer.concat` at all.
+        const chunkBytes = 200_000;
+        const filler = createBridgeBodyReservation();
+        expect(filler.reserve(HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES - Math.floor(chunkBytes * 1.5))).toBe(true);
+        const concatSpy = vi.spyOn(Buffer, "concat");
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, bridgeToken, clientSide } = bindTestServer({
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    authorization: `Bearer ${bridgeToken}`,
+                });
+                let status = 0;
+                let body = "";
+                req.setEncoding("utf8");
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                req.write(Buffer.alloc(chunkBytes, "a"), () => {
+                    // Give the host a turn to receive the one chunk and reserve its
+                    // bytes before this test ends the stream and triggers the
+                    // concatenated-copy reservation attempt.
+                    setTimeout(() => {
+                        // The chunk-array reservation alone must already hold, on top of
+                        // the filler above, exactly the one chunk's bytes: the
+                        // concatenated-copy reservation has not run yet, because the
+                        // stream has not ended.
+                        expect(getBridgeBodyReservedBytesForTest()).toBe(filler.heldBytes + chunkBytes);
+                        req.end();
+                    }, 50);
+                });
+            });
+            expect(response.status).toBe(503);
+            expect(forwarderTracker.called).toBe(false);
+            expect(concatSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            concatSpy.mockRestore();
+            rawClient.close();
+            await handle.close();
+            filler.release();
+        }
+    });
+    describe("parseCanonicalBridgeRequestPath", () => {
+        it("parses an origin-form path with a query exactly one time", () => {
+            const result = parseCanonicalBridgeRequestPath({ ":path": "/api/issues/abc?foo=bar" });
+            expect(result).toEqual({ ok: true, value: { pathname: "/api/issues/abc", query: "?foo=bar" } });
+        });
+        it("test_a_non_origin_form_path_is_rejected", () => {
+            expect(parseCanonicalBridgeRequestPath({ ":path": "http://evil.example/api" })).toEqual({
+                ok: false,
+                reason: "non_origin_form",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "//evil.example/api" })).toEqual({
+                ok: false,
+                reason: "non_origin_form",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "*" })).toEqual({
+                ok: false,
+                reason: "non_origin_form",
+            });
+        });
+        it("test_an_encoded_separator_or_a_dot_segment_is_rejected", () => {
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api%2fissues/abc" })).toEqual({
+                ok: false,
+                reason: "encoded_slash",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api\\issues/abc" })).toEqual({
+                ok: false,
+                reason: "backslash",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api/issues\0/abc" })).toEqual({
+                ok: false,
+                reason: "nul_byte",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api/%00/abc" })).toEqual({
+                ok: false,
+                reason: "nul_byte",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api/../secrets" })).toEqual({
+                ok: false,
+                reason: "dot_segment",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api/%2e%2e/secrets" })).toEqual({
+                ok: false,
+                reason: "dot_segment",
+            });
+            expect(parseCanonicalBridgeRequestPath({ ":path": "/api/./issues" })).toEqual({
+                ok: false,
+                reason: "dot_segment",
+            });
+        });
+        it("rejects a duplicate pseudo-header", () => {
+            expect(parseCanonicalBridgeRequestPath({ ":path": ["/api/agents/me", "/api/agents/other"] })).toEqual({ ok: false, reason: "duplicate_pseudo_header" });
+        });
+        it("rejects a missing path", () => {
+            expect(parseCanonicalBridgeRequestPath({})).toEqual({ ok: false, reason: "missing_path" });
+        });
+    });
+    it("buildHttp2BridgeForwardUrl resolves the parsed pathname and query against the base URL", () => {
+        const url = buildHttp2BridgeForwardUrl("http://127.0.0.1:4000", {
+            pathname: "/api/issues/abc",
+            query: "?foo=bar",
+        });
+        expect(url.toString()).toBe("http://127.0.0.1:4000/api/issues/abc?foo=bar");
+    });
+    it("classifyStreamAgainstGoaway classifies by the last processed stream id", () => {
+        expect(classifyStreamAgainstGoaway(1, 3)).toBe("accepted");
+        expect(classifyStreamAgainstGoaway(3, 3)).toBe("accepted");
+        expect(classifyStreamAgainstGoaway(5, 3)).toBe("not_accepted");
+    });
+    it("test_a_stream_without_the_bridge_token_never_reaches_the_forwarder", async () => {
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, clientSide } = bindTestServer({
+            forwardRequest: async (request) => {
+                forwarderTracker.markCalled();
+                return { status: 200, body: Buffer.from(JSON.stringify({ path: request.pathname }), "utf8") };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const response = await new Promise((resolve, reject) => {
+                // No `authorization` header at all: the stream never carries a token.
+                const req = rawClient.request({ ":method": "GET", ":path": "/api/agents/me" });
+                let status = 0;
+                let body = "";
+                req.on("response", (headers) => {
+                    status = Number(headers[":status"]) || 0;
+                });
+                req.setEncoding("utf8");
+                req.on("data", (chunk) => (body += chunk));
+                req.on("end", () => resolve({ status, body }));
+                req.on("error", reject);
+                req.end();
+            });
+            expect(response.status).toBe(401);
+            expect(forwarderTracker.called).toBe(false);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("test_a_denied_stream_with_an_unfinished_body_still_frees_its_stream_slot", async () => {
+        // The server answers a denied stream (an invalid token, here) at once,
+        // before it ever reads the request body. A peer that leaves that body
+        // unfinished must not hold the stream open past the same idle bound an
+        // authenticated request gets — otherwise, up to
+        // `HTTP2_BRIDGE_MAX_CONCURRENT_STREAMS` denied streams could each retain
+        // a slot forever and block every legitimate callback.
+        const forwarderTracker = createForwarderCallTracker();
+        const { handle, clientSide } = bindTestServer({
+            requestBodyTimeoutMs: 30,
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        const rawClient = connectRawClient(clientSide);
+        try {
+            const startMs = Date.now();
+            const closed = new Promise((resolve) => {
+                const req = rawClient.request({
+                    ":method": "POST",
+                    ":path": "/api/issues/abc/comments",
+                    // No `authorization` header: the token check denies this stream
+                    // before the body is ever read.
+                });
+                req.on("error", () => undefined);
+                req.on("close", () => resolve());
+                // Drain the response so its readable side reaches `end`: nothing in
+                // this test reads the response body otherwise, and an unread
+                // response can itself hold the client stream open past `close`.
+                req.resume();
+                // A partial body the request never ends: without its own bound, the
+                // inbound half of this stream would stay open indefinitely.
+                req.write("partial-body");
+            });
+            await closed;
+            expect(Date.now() - startMs).toBeLessThan(5_000);
+            expect(forwarderTracker.called).toBe(false);
+            // The session survives the freed stream: a second, complete request
+            // still succeeds, proving the session itself stayed open and healthy.
+            const survivingResponse = await expectSessionStillServesARequest(rawClient, {
+                method: "GET",
+                path: "/api/agents/me",
+                token: BRIDGE_TOKEN,
+            });
+            expect(survivingResponse.status).toBe(200);
+        }
+        finally {
+            rawClient.close();
+            await handle.close();
+        }
+    });
+    it("serves only exact GET schema discovery through HTTP/2", async () => {
+        const schema = { openapi: "3.1.0", paths: {} };
+        const forwarded = [];
+        const { gateway, handle } = createTestPair({
+            forwardRequest: async (request) => {
+                forwarded.push(`${request.method} ${request.pathname}`);
+                return { status: 200, body: Buffer.from(JSON.stringify(schema)) };
+            },
+        });
+        try {
+            for (const [method, path, status] of [
+                ["GET", "/api/openapi.json", 200],
+                ["POST", "/api/openapi.json", 403],
+                ["PATCH", "/api/openapi.json", 403],
+                ["DELETE", "/api/openapi.json", 403],
+                ["GET", "/api/openapi.json/extra", 403],
+                ["GET", "/api/openapiXjson", 403],
+                ["GET", "/api/secrets", 403],
+            ]) {
+                const response = await gateway.forwardRequest({
+                    method, path, query: "", headers: {}, body: Buffer.alloc(0), receivedToken: BRIDGE_TOKEN,
+                });
+                expect(response.status).toBe(status);
+                if (status === 200)
+                    expect(JSON.parse(response.body.toString())).toEqual(schema);
+            }
+            expect(forwarded).toEqual(["GET /api/openapi.json"]);
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("rejects a route the allowlist does not carry, before the forwarder runs", async () => {
+        const forwarderTracker = createForwarderCallTracker();
+        const { gateway, handle } = createTestPair({
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        try {
+            const response = await gateway.forwardRequest({
+                method: "DELETE",
+                path: "/api/agents/me",
+                query: "",
+                headers: {},
+                body: Buffer.alloc(0),
+                receivedToken: BRIDGE_TOKEN,
+            });
+            expect(response.status).toBe(403);
+            expect(forwarderTracker.called).toBe(false);
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("test_a_maximum_size_multipart_attachment_upload_fits_through_the_bridge", async () => {
+        // A file at the exact attachment content ceiling (10 MiB — the same
+        // figure `MAX_ATTACHMENT_BYTES` in `server/src/attachment-types.ts`
+        // enforces) still crosses the bridge wrapped in a multipart body: the
+        // boundary line and the part's own headers add bytes on top of that file
+        // content. The bridge's own body limit needs headroom for that framing,
+        // or a valid maximum-size attachment fails here before the server ever
+        // sees it.
+        const maxAttachmentBytes = 10 * 1024 * 1024;
+        const boundary = "----PaperclipTestBoundary1234567890abcdef";
+        const preamble = Buffer.from(`--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="file"; filename="attachment.bin"\r\n` +
+            `Content-Type: application/octet-stream\r\n\r\n`, "utf8");
+        const fileContent = Buffer.alloc(maxAttachmentBytes, 0x61);
+        const epilogue = Buffer.from(`\r\n--${boundary}--\r\n`, "utf8");
+        const multipartBody = Buffer.concat([preamble, fileContent, epilogue]);
+        // The wrapper really does add bytes on top of the file content alone —
+        // otherwise this test would prove nothing about framing headroom.
+        expect(multipartBody.byteLength).toBeGreaterThan(maxAttachmentBytes);
+        expect(multipartBody.byteLength).toBeLessThanOrEqual(DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES);
+        let receivedBodyBytes = 0;
+        const { gateway, handle } = createTestPair({
+            routes: HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST,
+            forwardRequest: async (request) => {
+                receivedBodyBytes = request.body.byteLength;
+                return { status: 201, body: Buffer.from("{}", "utf8") };
+            },
+        });
+        try {
+            const response = await gateway.forwardRequest({
+                method: "POST",
+                path: "/api/companies/co-1/issues/issue-1/attachments",
+                query: "",
+                headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
+                body: multipartBody,
+                receivedToken: BRIDGE_TOKEN,
+            });
+            expect(response.status).toBe(201);
+            expect(receivedBodyBytes).toBe(multipartBody.byteLength);
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    }, 20_000);
+    it("the sandbox gateway keeps its own token check before it opens a stream", async () => {
+        const forwarderTracker = createForwarderCallTracker();
+        const { gateway, handle } = createTestPair({
+            forwardRequest: async () => {
+                forwarderTracker.markCalled();
+                return { status: 200 };
+            },
+        });
+        try {
+            await expect(gateway.forwardRequest({
+                method: "GET",
+                path: "/api/agents/me",
+                query: "",
+                headers: {},
+                body: Buffer.alloc(0),
+                receivedToken: "wrong-token",
+            })).rejects.toThrow(/invalid bridge token/i);
+            expect(forwarderTracker.called).toBe(false);
+        }
+        finally {
+            await gateway.close();
+            await handle.close();
+        }
+    });
+    it("wrapDuplexChannelAsNodeDuplex relays writes and pushes through onData", async () => {
+        const written = [];
+        let dataListener;
+        let exitListener;
+        const channel = {
+            write: (data) => {
+                written.push(Buffer.from(data));
+            },
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: (listener) => {
+                exitListener = listener;
+            },
+            stop: () => undefined,
+            close: async () => undefined,
+        };
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel);
+        const received = [];
+        duplex.on("data", (chunk) => received.push(chunk));
+        duplex.write(Buffer.from("outbound"));
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(Buffer.concat(written).toString("utf8")).toBe("outbound");
+        dataListener?.(Buffer.from("inbound"));
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(Buffer.concat(received).toString("utf8")).toBe("inbound");
+        const ended = new Promise((resolve) => duplex.on("end", resolve));
+        exitListener?.({ exitCode: 0 });
+        await ended;
+    });
+    it("wrapDuplexChannelAsNodeDuplex queues chunks past a full readable side and drains them once the consumer reads again", async () => {
+        let dataListener;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => undefined,
+            close: async () => undefined,
+        };
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel, { maxBufferedReadBytes: 1_000_000 });
+        const received = [];
+        // The first chunk alone passes the readable side's default 64 KiB
+        // high-water mark, so `push()` reports the readable side full. The two
+        // chunks that follow queue in the wrapper instead of pushing past that
+        // signal — this is the bounded flow-control path this fix adds.
+        dataListener?.(Buffer.alloc(70_000, "a"));
+        dataListener?.(Buffer.from("-second-"));
+        dataListener?.(Buffer.from("-third-"));
+        // Attaching a "data" listener now starts flowing mode, which drives the
+        // wrapper's own `read()` until every queued chunk drains, proving no
+        // queued chunk was dropped and the arrival order held.
+        const drainedAll = new Promise((resolve) => {
+            duplex.on("data", (chunk) => {
+                received.push(chunk);
+                if (Buffer.concat(received).includes("-third-"))
+                    resolve();
+            });
+        });
+        await drainedAll;
+        expect(Buffer.concat(received).toString("utf8").endsWith("-second--third-")).toBe(true);
+    });
+    it("wrapDuplexChannelAsNodeDuplex stops the channel and destroys the duplex once the bounded read backpressure buffer overflows", async () => {
+        let dataListener;
+        let stopped = false;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => {
+                stopped = true;
+            },
+            close: async () => undefined,
+        };
+        // The cap must clear the default 65,536-byte readable high-water mark,
+        // so the first chunk below still passes the direct-push check and
+        // forces `push()` to report the readable side full; the overflow this
+        // test proves comes from the queue that follows, not from that first
+        // chunk on its own.
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel, { maxBufferedReadBytes: 80_000 });
+        // No consumer ever attaches, so the readable side never drains: every
+        // chunk past the first, which alone passes the default high-water mark,
+        // fills the bounded queue instead of the unbounded internal buffer a
+        // caller ignoring `push()`'s return would grow.
+        const errored = new Promise((resolve) => duplex.on("error", resolve));
+        dataListener?.(Buffer.alloc(70_000, "a")); // passes the high-water mark and the cap; still pushed directly.
+        dataListener?.(Buffer.alloc(30_000, "b")); // queues: 30,000 of the 80,000-byte cap.
+        dataListener?.(Buffer.alloc(30_000, "b")); // queues: 60,000 of the 80,000-byte cap.
+        dataListener?.(Buffer.alloc(30_000, "b")); // 90,000 queued bytes passes the cap.
+        const error = await errored;
+        expect(error.message).toMatch(/backpressure/i);
+        expect(stopped).toBe(true);
+    });
+    it("stops the channel when the read queue passes the lowered byte bound", async () => {
+        let dataListener;
+        let stopped = false;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => {
+                stopped = true;
+            },
+            close: async () => undefined,
+        };
+        // No override: this test proves the default bound itself is the direct
+        // 524,288-byte value, no longer derived from `HTTP2_BRIDGE_MAX_SESSION_MEMORY`.
+        // No consumer ever attaches, so the readable side never drains.
+        expect(DEFAULT_HTTP2_BRIDGE_MAX_BUFFERED_READ_BYTES).toBe(524_288);
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel);
+        const errored = new Promise((resolve) => duplex.on("error", resolve));
+        dataListener?.(Buffer.alloc(70_000, "a")); // passes the default high-water mark; still pushed directly.
+        dataListener?.(Buffer.alloc(500_000, "b")); // queues most of the 524,288-byte default cap.
+        dataListener?.(Buffer.alloc(60_000, "b")); // passes the default cap.
+        const error = await errored;
+        expect(error.message).toMatch(/backpressure/i);
+        expect(stopped).toBe(true);
+    });
+    it("wrapDuplexChannelAsNodeDuplex fails closed on one inbound chunk larger than the bounded read backpressure buffer, before the queue holds anything to compare it against", async () => {
+        let dataListener;
+        let stopped = false;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => {
+                stopped = true;
+            },
+            close: async () => undefined,
+        };
+        // No consumer ever attaches, and the queue is empty when this chunk
+        // arrives, so a check that only bounds the queue's cumulative size (and
+        // not one chunk's own size) would let this chunk reach `push()` unbound.
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel, { maxBufferedReadBytes: 5_000 });
+        const errored = new Promise((resolve) => duplex.on("error", resolve));
+        dataListener?.(Buffer.alloc(10_000, "a")); // exceeds the 5,000-byte cap on its own, on the very first chunk.
+        const error = await errored;
+        expect(error.message).toMatch(/backpressure/i);
+        expect(stopped).toBe(true);
+    });
+    it("wrapDuplexChannelAsNodeDuplex fails closed once the read backpressure queue stalls with no drain, even though it stays under the byte cap", async () => {
+        let dataListener;
+        let stopped = false;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => {
+                stopped = true;
+            },
+            close: async () => undefined,
+        };
+        // A generous byte cap, so the byte-cap check above never fires: this
+        // test proves the independent time bound catches a stuck consumer the
+        // byte cap alone would miss.
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel, {
+            maxBufferedReadBytes: 10_000_000,
+            readBackpressureStallMs: 40,
+        });
+        const errored = new Promise((resolve) => duplex.on("error", resolve));
+        dataListener?.(Buffer.alloc(70_000, "a")); // passes the high-water mark; pushed directly, no consumer drains it.
+        dataListener?.(Buffer.from("queued-and-never-drained")); // queues; no "data" listener ever attaches to drain it.
+        const error = await errored;
+        expect(error.message).toMatch(/stall/i);
+        expect(stopped).toBe(true);
+    });
+    it("wrapDuplexChannelAsNodeDuplex clears the stall bound once the queue fully drains, instead of firing later on an idle channel", async () => {
+        let dataListener;
+        const channel = {
+            write: () => undefined,
+            onData: (listener) => {
+                dataListener = listener;
+            },
+            onExit: () => undefined,
+            stop: () => undefined,
+            close: async () => undefined,
+        };
+        // A short stall bound, so this test proves the drain below clears the
+        // timer instead of merely finishing before a long one would have fired.
+        const duplex = wrapDuplexChannelAsNodeDuplex(channel, {
+            maxBufferedReadBytes: 10_000_000,
+            readBackpressureStallMs: 20,
+        });
+        const received = [];
+        const drainedAll = new Promise((resolve) => {
+            duplex.on("data", (chunk) => {
+                received.push(chunk);
+                if (Buffer.concat(received).includes("-third-"))
+                    resolve();
+            });
+        });
+        dataListener?.(Buffer.alloc(70_000, "a")); // passes the high-water mark; queues the chunks that follow.
+        dataListener?.(Buffer.from("-second-"));
+        dataListener?.(Buffer.from("-third-"));
+        await drainedAll;
+        // Wait past the stall bound with the channel now idle and the queue
+        // empty. A timer the full drain above did not clear would fire here.
+        await new Promise((resolve) => setTimeout(resolve, 60));
+        expect(duplex.destroyed).toBe(false);
+    });
+});
+//# sourceMappingURL=http2-bridge-server.test.js.map