@robota-sdk/agent-transport-webrtc 3.0.0-beta.81

package/src/__tests__/pairing-gate.test.ts

@@ -0,0 +1,276 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { PairingGate, type IPairingGateOptions } from '../pairing-gate.js';
+import { WebRtcDeliveryLifecycle } from '../webrtc-delivery-lifecycle.js';
+
+import type { startPairingHandshake, TPairingFrame } from '@robota-sdk/agent-remote-pairing';
+import type { createSessionMessageHandler } from '@robota-sdk/agent-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { RTCDataChannel } from 'werift';
+
+/**
+ * REMOTE-008 Step 1 (SECURITY milestone) — the pairing gate's fail-closed routing switch, driven with a stub
+ * channel + injected handshake + injected session-bridge (no real peer/crypto/session).
+ */
+
+/** A controllable stub of the pairing handshake: capture frames, resolve/reject on demand. */
+function makeHandshakeStub() {
+  const sent: TPairingFrame[] = [];
+  const received: TPairingFrame[] = [];
+  let resolveResult!: (value: { sessionKey: string }) => void;
+  let rejectResult!: (error: Error) => void;
+  const start: typeof startPairingHandshake = (options) => {
+    // Record what the gate asked us to send (it wraps this over the channel).
+    const controller = {
+      result: new Promise<{ sessionKey: string }>((res, rej) => {
+        resolveResult = res;
+        rejectResult = rej;
+      }),
+      onFrame: (frame: TPairingFrame) => received.push(frame),
+    };
+    // Expose the send seam so a test can assert the gate serialized a frame.
+    options.send({ t: 'pair-nonce', nonce: 'stub' });
+    return controller;
+  };
+  return {
+    start,
+    received,
+    sentByGate: sent,
+    accept: () => resolveResult({ sessionKey: 'k' }),
+    reject: () => rejectResult(new Error('pairing rejected')),
+  };
+}
+
+function makeGate(over: Partial<IPairingGateOptions> = {}) {
+  const channelSends: string[] = [];
+  const channel = { send: (d: string) => channelSends.push(d), close: vi.fn() };
+  const session = Object.assign(createTestInteractiveSession(), {});
+  const sessionOnMessage = vi.fn();
+  const handlerCleanup = vi.fn();
+  const createHandler: typeof createSessionMessageHandler = () => ({
+    onMessage: sessionOnMessage,
+    cleanup: handlerCleanup,
+  });
+  const hs = makeHandshakeStub();
+  const gate = new PairingGate({
+    channel,
+    session,
+    secret: 's',
+    role: 'initiator',
+    localFingerprint: 'AA',
+    remoteFingerprint: 'BB',
+    startHandshake: hs.start,
+    createHandler,
+    ...over,
+  });
+  return { gate, channel, channelSends, sessionOnMessage, handlerCleanup, hs };
+}
+
+describe('PairingGate (REMOTE-008 Step 1 — fail-closed routing switch)', () => {
+  it('does not expose the session before the handshake accepts (no session bridge built)', () => {
+    const { sessionOnMessage } = makeGate();
+    // The handshake sent its nonce, but no session handler exists yet.
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('serializes the handshake frames it sends over the channel', () => {
+    const { channelSends } = makeGate();
+    // The stub handshake emits a pair-nonce on start; the gate must have serialized it.
+    expect(channelSends).toContain(JSON.stringify({ t: 'pair-nonce', nonce: 'stub' }));
+  });
+
+  it('pre-accept: routes a pairing frame to the handshake and DROPS a non-pairing frame', () => {
+    const { gate, hs, sessionOnMessage } = makeGate();
+    gate.onInbound(JSON.stringify({ t: 'pair-confirm', mac: 'm' }));
+    expect(hs.received).toEqual([{ t: 'pair-confirm', mac: 'm' }]);
+    // A well-formed but non-pairing frame pre-accept must never reach the (nonexistent) session.
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'p' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+    // Undecodable garbage pre-accept is dropped without throwing.
+    expect(() => gate.onInbound('not json')).not.toThrow();
+  });
+
+  it.each([
+    ['an empty mac', { t: 'pair-confirm', mac: '' }],
+    ['a numeric nonce', { t: 'pair-nonce', nonce: 7 }],
+    ['a padded (non-base64url) mac', { t: 'pair-confirm', mac: 'bWFj==' }],
+    ['a mac over the ceiling', { t: 'pair-confirm', mac: 'A'.repeat(129) }],
+  ])(
+    'issue #2046: a pairing frame with the right discriminator but %s never reaches the handshake',
+    (_label, frame) => {
+      // Against the old discriminator-only predicate every one of these was handed to the controller.
+      const { gate, hs } = makeGate();
+      gate.onInbound(JSON.stringify(frame));
+      expect(hs.received).toEqual([]);
+    },
+  );
+
+  it('on ACCEPT: builds the session bridge and routes subsequent frames to it', async () => {
+    const { gate, hs, sessionOnMessage } = makeGate();
+    hs.accept();
+    await Promise.resolve(); // let the result.then microtask run
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'hi' }));
+    expect(sessionOnMessage).toHaveBeenCalledWith(JSON.stringify({ type: 'submit', prompt: 'hi' }));
+  });
+
+  it('on REJECT: closes the channel and NEVER exposes the session', async () => {
+    const { gate, channel, hs, sessionOnMessage } = makeGate();
+    hs.reject();
+    await Promise.resolve();
+    expect(channel.close).toHaveBeenCalledTimes(1);
+    // Any frame after a failed pairing is ignored — the session is never reachable.
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'hi' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('post-close (cleanup): ignores further inbound frames', async () => {
+    const { gate, hs, sessionOnMessage } = makeGate();
+    hs.accept();
+    await Promise.resolve();
+    gate.cleanup();
+    gate.onInbound(JSON.stringify({ type: 'submit', prompt: 'hi' }));
+    expect(sessionOnMessage).not.toHaveBeenCalled();
+  });
+
+  it('fires onAccept on accept (not onReject)', async () => {
+    const onAccept = vi.fn();
+    const onReject = vi.fn();
+    const { hs } = makeGate({ onAccept, onReject });
+    hs.accept();
+    await Promise.resolve();
+    expect(onAccept).toHaveBeenCalledTimes(1);
+    expect(onReject).not.toHaveBeenCalled();
+  });
+
+  it('fires onReject on reject (not onAccept)', async () => {
+    const onAccept = vi.fn();
+    const onReject = vi.fn();
+    const { hs } = makeGate({ onAccept, onReject });
+    hs.reject();
+    await Promise.resolve();
+    expect(onReject).toHaveBeenCalledTimes(1);
+    expect(onAccept).not.toHaveBeenCalled();
+  });
+
+  it('cleanup tears down the session bridge when one was built', async () => {
+    const { gate, hs, handlerCleanup } = makeGate();
+    hs.accept();
+    await Promise.resolve();
+    gate.cleanup();
+    expect(handlerCleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it('post-accept send failure closes the carrier and reports without escaping the session event', async () => {
+    const handlers = new Map<string, (value: unknown) => void>();
+    const session = createTestInteractiveSession({
+      on: ((event: string, handler: (value: unknown) => void) => {
+        handlers.set(event, handler);
+      }) as IInteractiveSession['on'],
+      off: ((event: string) => {
+        handlers.delete(event);
+      }) as IInteractiveSession['off'],
+    });
+    let failSend = false;
+    const channel = {
+      send: vi.fn(() => {
+        if (failSend) throw new Error('paired channel closed');
+      }),
+      close: vi.fn(),
+    };
+    const onDeliveryError = vi.fn();
+    const hs = makeHandshakeStub();
+    new PairingGate({
+      channel,
+      session,
+      secret: 's',
+      role: 'initiator',
+      localFingerprint: 'AA',
+      remoteFingerprint: 'BB',
+      startHandshake: hs.start,
+      onDeliveryError,
+    });
+    hs.accept();
+    await Promise.resolve();
+    failSend = true;
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(channel.close).toHaveBeenCalledTimes(1);
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'paired channel closed' }),
+      'branch_event',
+    );
+    expect(handlers.size).toBe(0);
+  });
+
+  it('reports a paired delivery failure before a synchronous closing transition drops the carrier', async () => {
+    const handlers = new Map<string, (value: unknown) => void>();
+    const session = createTestInteractiveSession({
+      on: ((event: string, handler: (value: unknown) => void) => {
+        handlers.set(event, handler);
+      }) as IInteractiveSession['on'],
+      off: ((event: string) => {
+        handlers.delete(event);
+      }) as IInteractiveSession['off'],
+    });
+    const cleanup = vi.fn();
+    const onDropped = vi.fn();
+    const onDeliveryError = vi.fn();
+    let gate!: PairingGate;
+    let lifecycle!: WebRtcDeliveryLifecycle;
+    let failSend = false;
+    const channel = {
+      send: vi.fn(() => {
+        if (failSend) throw new Error('paired channel closed synchronously');
+      }),
+      close: vi.fn(() => lifecycle.handleDrop(1)),
+    };
+    lifecycle = new WebRtcDeliveryLifecycle({
+      cleanup: () => {
+        cleanup();
+        gate.cleanup();
+      },
+      onDropped,
+      onDeliveryError,
+    });
+    lifecycle.reset(1);
+    const hs = makeHandshakeStub();
+    gate = new PairingGate({
+      channel,
+      session,
+      secret: 's',
+      role: 'initiator',
+      localFingerprint: 'AA',
+      remoteFingerprint: 'BB',
+      startHandshake: hs.start,
+      onAccept: () => lifecycle.accept(1),
+      onDeliveryError: (error, event) =>
+        lifecycle.handleFailure(channel as unknown as RTCDataChannel, 1, error, event),
+    });
+    hs.accept();
+    await Promise.resolve();
+    failSend = true;
+
+    expect(() =>
+      handlers.get('branch_event')?.({
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(onDeliveryError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'paired channel closed synchronously' }),
+      'branch_event',
+    );
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    expect(onDropped).toHaveBeenCalledTimes(1);
+    expect(handlers.size).toBe(0);
+  });
+});

package/src/__tests__/pairing-relay-in-the-middle.test.ts

@@ -0,0 +1,229 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { extractDtlsFingerprint, startPairingHandshake } from '@robota-sdk/agent-remote-pairing';
+import { describe, expect, it, vi } from 'vitest';
+import { RTCPeerConnection } from 'werift';
+
+import { WebRtcTransport } from '../webrtc-transport.js';
+import { createInMemorySignalingPair, type ISignalingClient } from '../signaling.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { TPairingFrame } from '@robota-sdk/agent-remote-pairing';
+import type { RTCDataChannel } from 'werift';
+
+/**
+ * The pairing confirmation must bind to the certificate the DTLS layer actually verified. A relay that
+ * terminates DTLS on both sides and forwards the data channel must not be able to make the two honest
+ * peers compute the same binding.
+ */
+
+function createStubSession(): IInteractiveSession {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    getActiveDriverId: () => null,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+/** Insert `a=fingerprint:sha-256 <value>` before the first existing fingerprint line. */
+function prependFingerprint(sdp: string, value: string): string {
+  return sdp.replace(/^a=fingerprint:/m, `a=fingerprint:sha-256 ${value}\r\na=fingerprint:`);
+}
+
+type TDescription = { type: 'offer' | 'answer'; sdp: string };
+
+/** Pairing responder on the far side. Resolves true only if its own handshake accepts. */
+function connectResponder(signaling: ISignalingClient, secret: string): Promise<boolean> {
+  return new Promise<boolean>((resolvePaired) => {
+    const peer = new RTCPeerConnection();
+    peer.onIceCandidate.subscribe((c) => {
+      if (c) signaling.send({ kind: 'ice', data: c.toJSON() });
+    });
+    let hostFingerprint: string | undefined;
+    let chain: Promise<void> = Promise.resolve();
+    signaling.onSignal((message) => {
+      chain = chain
+        .then(async () => {
+          if (message.kind === 'offer') {
+            const offer = message.data as TDescription;
+            hostFingerprint = extractDtlsFingerprint(offer.sdp);
+            await peer.setRemoteDescription(offer);
+            await peer.setLocalDescription(await peer.createAnswer());
+            signaling.send({ kind: 'answer', data: peer.localDescription });
+          } else if (message.kind === 'ice') {
+            await peer.addIceCandidate(message.data as Parameters<typeof peer.addIceCandidate>[0]);
+          }
+        })
+        .catch(() => resolvePaired(false));
+    });
+    peer.onDataChannel.subscribe((channel) => {
+      const controller = startPairingHandshake({
+        secret,
+        role: 'responder',
+        localFingerprint: extractDtlsFingerprint(peer.localDescription!.sdp),
+        remoteFingerprint: hostFingerprint!,
+        send: (frame: TPairingFrame) => {
+          try {
+            channel.send(JSON.stringify(frame));
+          } catch {
+            /* closing */
+          }
+        },
+        timeoutMs: 6000,
+      });
+      controller.result.then(
+        () => resolvePaired(true),
+        () => resolvePaired(false),
+      );
+      channel.onMessage.subscribe((data) => {
+        try {
+          controller.onFrame(JSON.parse(data.toString()) as TPairingFrame);
+        } catch {
+          /* ignore */
+        }
+      });
+    });
+  });
+}
+
+/**
+ * A signaling relay that terminates DTLS with each side using its own certificates, forwards the data
+ * channel between them, and advertises the honest peer's fingerprint FIRST next to its own.
+ */
+function startRelay(toHost: ISignalingClient, toRemote: ISignalingClient): void {
+  const facingHost = new RTCPeerConnection();
+  const facingRemote = new RTCPeerConnection();
+  let hostChannel: RTCDataChannel | undefined;
+  const remoteChannel = facingRemote.createDataChannel('robota-session');
+  const toRemoteQueue: string[] = [];
+  const toHostQueue: string[] = [];
+  let hostFingerprint = '';
+  let pendingHostOffer: TDescription | undefined;
+
+  facingHost.onIceCandidate.subscribe((c) => {
+    if (c) toHost.send({ kind: 'ice', data: c.toJSON() });
+  });
+  facingRemote.onIceCandidate.subscribe((c) => {
+    if (c) toRemote.send({ kind: 'ice', data: c.toJSON() });
+  });
+
+  facingHost.onDataChannel.subscribe((channel) => {
+    hostChannel = channel;
+    for (const m of toHostQueue.splice(0)) channel.send(m);
+    channel.onMessage.subscribe((data) => {
+      const text = data.toString();
+      if (remoteChannel.readyState === 'open') remoteChannel.send(text);
+      else toRemoteQueue.push(text);
+    });
+  });
+  remoteChannel.stateChanged.subscribe((state) => {
+    if (state === 'open') for (const m of toRemoteQueue.splice(0)) remoteChannel.send(m);
+  });
+  remoteChannel.onMessage.subscribe((data) => {
+    const text = data.toString();
+    if (hostChannel) hostChannel.send(text);
+    else toHostQueue.push(text);
+  });
+
+  let hostChain: Promise<void> = Promise.resolve();
+  toHost.onSignal((message) => {
+    hostChain = hostChain.then(async () => {
+      if (message.kind === 'offer') {
+        pendingHostOffer = message.data as TDescription;
+        hostFingerprint = extractDtlsFingerprint(pendingHostOffer.sdp);
+        await facingRemote.setLocalDescription(await facingRemote.createOffer());
+        const own = facingRemote.localDescription!;
+        toRemote.send({
+          kind: 'offer',
+          data: { type: 'offer', sdp: prependFingerprint(own.sdp, hostFingerprint) },
+        });
+      } else if (message.kind === 'ice') {
+        await facingHost.addIceCandidate(message.data as Parameters<typeof facingHost.addIceCandidate>[0]);
+      }
+    });
+  });
+
+  let remoteChain: Promise<void> = Promise.resolve();
+  toRemote.onSignal((message) => {
+    remoteChain = remoteChain.then(async () => {
+      if (message.kind === 'answer') {
+        const answer = message.data as TDescription;
+        const remoteFingerprint = extractDtlsFingerprint(answer.sdp);
+        await facingRemote.setRemoteDescription(answer);
+        await facingHost.setRemoteDescription(pendingHostOffer!);
+        await facingHost.setLocalDescription(await facingHost.createAnswer());
+        const own = facingHost.localDescription!;
+        toHost.send({
+          kind: 'answer',
+          data: { type: 'answer', sdp: prependFingerprint(own.sdp, remoteFingerprint) },
+        });
+      } else if (message.kind === 'ice') {
+        await facingRemote.addIceCandidate(
+          message.data as Parameters<typeof facingRemote.addIceCandidate>[0],
+        );
+      }
+    });
+  });
+}
+
+describe('WebRTC pairing with a relay in the middle', () => {
+  it('refuses to pair when the relay advertises the honest fingerprint next to its own', async () => {
+    const secret = 'shared-secret-256bit-base64url-relay';
+    const [hostSig, relayHostSide] = createInMemorySignalingPair();
+    const [relayRemoteSide, remoteSig] = createInMemorySignalingPair();
+    const session = createStubSession();
+    const onPaired = vi.fn();
+    const transport = new WebRtcTransport({ signaling: hostSig, secret, onPaired });
+    transport.attach(session);
+
+    startRelay(relayHostSide, relayRemoteSide);
+    const remotePaired = connectResponder(remoteSig, secret);
+    await transport.start();
+
+    await expect(remotePaired).resolves.toBe(false);
+    expect(onPaired).not.toHaveBeenCalled();
+    await transport.stop();
+  }, 20000);
+});
+
+describe('WebRTC transport answer handling', () => {
+  it('takes one answer per start and ignores any later one', async () => {
+    let remoteDescriptions = 0;
+    class CountingPeer extends RTCPeerConnection {
+      override async setRemoteDescription(
+        ...args: Parameters<RTCPeerConnection['setRemoteDescription']>
+      ): ReturnType<RTCPeerConnection['setRemoteDescription']> {
+        remoteDescriptions += 1;
+        return super.setRemoteDescription(...args);
+      }
+    }
+    const [hostSig, remoteSig] = createInMemorySignalingPair();
+    const transport = new WebRtcTransport({
+      signaling: hostSig,
+      secret: 'shared-secret-256bit-base64url-answers',
+      loadWerift: () => ({ RTCPeerConnection: CountingPeer }) as never,
+    });
+    transport.attach(createStubSession());
+
+    const remote = new RTCPeerConnection();
+    const answered = new Promise<void>((resolve) => {
+      remoteSig.onSignal((message) => {
+        if (message.kind !== 'offer') return;
+        void (async () => {
+          await remote.setRemoteDescription(message.data as TDescription);
+          await remote.setLocalDescription(await remote.createAnswer());
+          remoteSig.send({ kind: 'answer', data: remote.localDescription });
+          remoteSig.send({ kind: 'answer', data: remote.localDescription });
+          setTimeout(resolve, 200);
+        })();
+      });
+    });
+    await transport.start();
+    await answered;
+
+    expect(remoteDescriptions).toBe(1);
+    await transport.stop();
+    await remote.close();
+  }, 15000);
+});

package/src/__tests__/session-attachment-budget.test.ts

@@ -0,0 +1,136 @@
+/**
+ * ARCH-030 / issue #1734 — the replay path's backpressure budget REACHES production.
+ *
+ * `IAttachOptions.pendingBytes` existed with zero production callers: the bridge could take a
+ * carrier's backpressure reading and nothing gave it one, so the replay burst — the case the
+ * reopened scope names — ran unbudgeted while every other outbound path on the same connection was
+ * guarded.
+ *
+ * This case asserts the BEHAVIOUR, not the wiring. A test that checked the option reaches
+ * `bridge.attach` would have passed on the day the defect existed, because the option was reaching
+ * nothing on the way in. What can fail is a peer over budget going unclosed.
+ */
+import { DEFAULT_MAX_PENDING_BYTES, SessionResumeBridge } from '@robota-sdk/agent-transport';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { attachSession } from '../session-attachment.js';
+
+import type { IPairingChannel } from '../pairing-gate-options.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+function fakeSession(): {
+  session: IInteractiveSession;
+  fire: (event: string, arg: unknown) => void;
+} {
+  const handlers = new Map<string, (arg: unknown) => void>();
+  const session = createTestInteractiveSession({
+    on: ((event: string, handler: (arg: unknown) => void) =>
+      handlers.set(event, handler)) as IInteractiveSession['on'],
+    off: ((event: string) => {
+      handlers.delete(event);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, fire: (event, arg) => handlers.get(event)?.(arg) };
+}
+
+/** A channel whose backpressure the case controls, matching the optional structural slice. */
+function channelHolding(bytes: () => number): IPairingChannel & { sent: string[] } {
+  const sent: string[] = [];
+  return {
+    sent,
+    send: (data: string) => void sent.push(data),
+    close: () => undefined,
+    get bufferedAmount(): number {
+      return bytes();
+    },
+  };
+}
+
+describe('attachSession + the replay budget (ARCH-030)', () => {
+  it('attributes direct admitted WebRTC submissions to the remote surface', async () => {
+    const base = fakeSession().session;
+    const submit = vi.fn().mockResolvedValue(undefined);
+    const session = Object.assign(base, { submit });
+    const channel = channelHolding(() => 0);
+    const attached = attachSession({ channel, session, surface: 'remote' }, false, () => undefined);
+
+    attached.onSessionMessage(JSON.stringify({ type: 'submit', prompt: 'remote turn' }));
+    await vi.waitFor(() => expect(submit).toHaveBeenCalled());
+
+    expect(submit).toHaveBeenCalledWith('remote turn', undefined, undefined, {
+      surface: 'remote',
+    });
+    attached.cleanup();
+  });
+
+  it('exposes host usage reporting on the admitted direct handler path', async () => {
+    const { session } = fakeSession();
+    const channel = channelHolding(() => 0);
+    const report = { schemaVersion: 1 } as never;
+    const attached = attachSession(
+      { channel, session, personalUsageReporter: async () => report },
+      false,
+      () => undefined,
+    );
+
+    attached.onSessionMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'direct-usage',
+        period: '30d',
+        timezone: 'UTC',
+      }),
+    );
+    await expect.poll(() => channel.sent.length).toBeGreaterThan(0);
+
+    expect(channel.sent.map((frame) => JSON.parse(frame))).toContainEqual({
+      type: 'personal_usage_report',
+      requestId: 'direct-usage',
+      report,
+    });
+    attached.cleanup();
+  });
+
+  it('closes a peer that is over budget when the replay burst is attempted', () => {
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    for (const delta of ['a', 'b', 'c']) fire('text_delta', delta);
+
+    let pending = 0;
+    const channel = channelHolding(() => pending);
+    const failures: string[] = [];
+    const attached = attachSession({ channel, session, resumeBridge: bridge }, true, (error) =>
+      failures.push(error.message),
+    );
+
+    // The peer has accepted a backlog it is not reading.
+    pending = DEFAULT_MAX_PENDING_BYTES + 1;
+    attached.onSessionMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+    expect(channel.sent).toHaveLength(0);
+    expect(failures).toHaveLength(1);
+    expect(failures[0]).toContain('pending');
+    attached.cleanup();
+    bridge.dispose();
+  });
+
+  it('replays normally while the peer is reading', () => {
+    // The companion the case above needs: without it, a budget that refused everything would pass.
+    const { session, fire } = fakeSession();
+    const bridge = new SessionResumeBridge({ session });
+    for (const delta of ['a', 'b', 'c']) fire('text_delta', delta);
+
+    const channel = channelHolding(() => 0);
+    const failures: string[] = [];
+    const attached = attachSession({ channel, session, resumeBridge: bridge }, true, (error) =>
+      failures.push(error.message),
+    );
+    attached.onSessionMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+
+    expect(channel.sent).toHaveLength(3);
+    expect(failures).toHaveLength(0);
+    attached.cleanup();
+    bridge.dispose();
+  });
+});