@robota-sdk/agent-transport 3.0.0-beta.100

package/src/__tests__/peer-message-ledger.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  acknowledgePeerMessage,
+  admitPeerMessage,
+  createPeerMessageLedger,
+  forgetPeerOrigin,
+} from '../peer-message-ledger.js';
+
+import type { IPeerMessage } from '@robota-sdk/agent-interface-session-mobility';
+
+function message(over: Partial<IPeerMessage> = {}): IPeerMessage {
+  return {
+    id: 'msg_1',
+    sequence: 1,
+    origin: { sessionId: 'peer_a' },
+    text: 'hello',
+    sentAt: 1,
+    ...over,
+  };
+}
+
+describe('PEER-001 — a retry gets the ORIGINAL answer back (#1809)', () => {
+  it('delivers a first message and refuses to deliver its retry', () => {
+    const ledger = createPeerMessageLedger();
+
+    const first = admitPeerMessage(ledger, message());
+    const retry = admitPeerMessage(ledger, message({ sentAt: 2 }));
+
+    expect(first.deliver).toBe(true);
+    expect(first.ack.state).toBe('delivered');
+    expect(retry.deliver).toBe(false);
+    expect(retry.ack.state).toBe('duplicate');
+  });
+
+  it('a retry of a REFUSED message stays refused, not silently accepted', () => {
+    // The property that makes a retry safe: a message must not get two contradictory answers. If
+    // the second attempt were re-judged, an admission that failed once could pass on a retry.
+    const ledger = createPeerMessageLedger();
+    const refusal = { state: 'refused', reason: 'not admitted' } as const;
+
+    const first = admitPeerMessage(ledger, message(), refusal);
+    const retry = admitPeerMessage(ledger, message({ sentAt: 2 }));
+
+    expect(first.ack.state).toBe('refused');
+    expect(retry.ack.state).toBe('duplicate');
+    expect(retry.deliver).toBe(false);
+    // The original reason survives, so the sender can still tell WHY it never landed.
+    expect(retry.ack.reason).toBe('not admitted');
+  });
+
+  it('carries the original sequence on the duplicate ack', () => {
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ sequence: 7 }));
+
+    const retry = admitPeerMessage(ledger, message({ sequence: 7, sentAt: 9 }));
+
+    expect(retry.ack.sequence).toBe(7);
+  });
+});
+
+describe('PEER-001 — sequence is per origin (#1809)', () => {
+  it('does not let one peer create a gap in another peer’s stream', () => {
+    // Two peers are independent senders. A shared counter would make peer B's traffic look like a
+    // gap in peer A's, and the session would wait for a message that was never coming.
+    const ledger = createPeerMessageLedger();
+
+    const a = admitPeerMessage(ledger, message({ id: 'a1', sequence: 1 }));
+    const b = admitPeerMessage(
+      ledger,
+      message({ id: 'b1', sequence: 1, origin: { sessionId: 'peer_b' } }),
+    );
+
+    expect(a.deliver).toBe(true);
+    expect(b.deliver).toBe(true);
+    expect(a.gapBefore).toBeUndefined();
+    expect(b.gapBefore).toBeUndefined();
+  });
+
+  it('reports a gap rather than silently reordering', () => {
+    // Buffer-and-reorder is a policy the session layer may choose. Inventing it here would hide a
+    // lost message behind an apparent success — the failure this contract exists to prevent.
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'm1', sequence: 1 }));
+
+    const ahead = admitPeerMessage(ledger, message({ id: 'm3', sequence: 3 }));
+
+    expect(ahead.deliver).toBe(true);
+    expect(ahead.gapBefore).toBe(2);
+  });
+
+  it('delivers a gap when it arrives LATE, instead of refusing what it reported as missing', () => {
+    // Found in review. The high-water form refused this: deliver 1, receive 3 (gap at 2 reported),
+    // then 2 arrives and is rejected as "already used" — although it was never delivered. That
+    // contradicted this module's own rule that a gap is REPORTED so the session layer can decide,
+    // because the session never got the chance.
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'm1', sequence: 1 }));
+    const ahead = admitPeerMessage(ledger, message({ id: 'm3', sequence: 3 }));
+
+    const late = admitPeerMessage(ledger, message({ id: 'm2', sequence: 2 }));
+
+    expect(ahead.gapBefore).toBe(2);
+    expect(late.deliver).toBe(true);
+    expect(late.ack.state).toBe('delivered');
+  });
+
+  it('does not rewind the frontier when a gap is filled late', () => {
+    // The frontier only moves forward, so a LATER gap is still measured against the highest
+    // sequence seen — filling 2 after 3 must not make 4 look like it follows 2.
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'm1', sequence: 1 }));
+    admitPeerMessage(ledger, message({ id: 'm3', sequence: 3 }));
+    admitPeerMessage(ledger, message({ id: 'm2', sequence: 2 }));
+
+    const next = admitPeerMessage(ledger, message({ id: 'm5', sequence: 5 }));
+
+    expect(next.gapBefore).toBe(4);
+  });
+
+  it('refuses a NEW id reusing an old sequence — that is a protocol error, not a retry', () => {
+    // A retry repeats its id. A new id on an already-used sequence cannot be ordered against what
+    // was delivered, so it is refused with the reason rather than guessed at.
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'm1', sequence: 1 }));
+
+    const reused = admitPeerMessage(ledger, message({ id: 'm2', sequence: 1 }));
+
+    expect(reused.deliver).toBe(false);
+    expect(reused.ack.state).toBe('refused');
+    expect(reused.ack.reason).toMatch(/already delivered by this origin/);
+  });
+});
+
+describe('PEER-001 — delivery and acknowledgement are different questions (#1809)', () => {
+  it('promotes a delivered message to acknowledged', () => {
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message());
+
+    const acked = acknowledgePeerMessage(ledger, 'peer_a', 'msg_1');
+
+    expect(acked?.state).toBe('acknowledged');
+  });
+
+  it('will not acknowledge something that was never delivered', () => {
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message(), { state: 'refused', reason: 'no' });
+
+    expect(acknowledgePeerMessage(ledger, 'peer_a', 'msg_1')).toBeUndefined();
+    expect(acknowledgePeerMessage(ledger, 'peer_a', 'never_seen')).toBeUndefined();
+    expect(acknowledgePeerMessage(ledger, 'unknown_peer', 'msg_1')).toBeUndefined();
+  });
+
+  it('a duplicate after acknowledgement still reads as duplicate', () => {
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message());
+    acknowledgePeerMessage(ledger, 'peer_a', 'msg_1');
+
+    expect(admitPeerMessage(ledger, message({ sentAt: 5 })).ack.state).toBe('duplicate');
+  });
+});
+
+describe('PEER-001 — disconnect and shutdown (#1809)', () => {
+  it('forgetting an origin frees its sequence space for a reconnect', () => {
+    // A peer that reconnects gets a fresh sequence space. Without this, its first message after a
+    // restart would collide with the sequence it used before and be refused.
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'm1', sequence: 5 }));
+
+    forgetPeerOrigin(ledger, 'peer_a');
+    const afterReconnect = admitPeerMessage(ledger, message({ id: 'm2', sequence: 1 }));
+
+    expect(afterReconnect.deliver).toBe(true);
+    expect(afterReconnect.ack.state).toBe('delivered');
+  });
+
+  it('forgetting one origin leaves the others intact', () => {
+    const ledger = createPeerMessageLedger();
+    admitPeerMessage(ledger, message({ id: 'a1', sequence: 1 }));
+    admitPeerMessage(ledger, message({ id: 'b1', sequence: 1, origin: { sessionId: 'peer_b' } }));
+
+    forgetPeerOrigin(ledger, 'peer_a');
+
+    // peer_b's record survives, so its next message is still ordered against what it sent.
+    const b2 = admitPeerMessage(
+      ledger,
+      message({ id: 'b2', sequence: 1, origin: { sessionId: 'peer_b' } }),
+    );
+    expect(b2.ack.state).toBe('refused');
+  });
+
+  it('remembers nothing across a new ledger — state is per connection by construction', () => {
+    const first = createPeerMessageLedger();
+    admitPeerMessage(first, message());
+
+    const fresh = createPeerMessageLedger();
+
+    expect(admitPeerMessage(fresh, message()).ack.state).toBe('delivered');
+  });
+});

package/src/__tests__/permission-summary.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { permissionSummaryArgument } from '../permission-summary.js';
+
+describe('permissionSummaryArgument', () => {
+  it('names a call by the argument a person recognises, file tools included', () => {
+    expect(permissionSummaryArgument({ filePath: '/w/a.txt', content: 'x' })).toBe('/w/a.txt');
+    expect(permissionSummaryArgument({ command: 'make', filePath: '/w/a.txt' })).toBe('make');
+    expect(permissionSummaryArgument({ file_path: 'b.txt' })).toBe('b.txt');
+    expect(permissionSummaryArgument({ url: 'https://x.test' })).toBe('https://x.test');
+  });
+
+  it('has nothing to show for empty or non-text arguments', () => {
+    expect(permissionSummaryArgument({ command: '' })).toBeUndefined();
+    expect(permissionSummaryArgument({ path: 3 })).toBeUndefined();
+    expect(permissionSummaryArgument({})).toBeUndefined();
+  });
+});

package/src/__tests__/personal-usage-report.test.ts

@@ -0,0 +1,193 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type {
+  IPersonalUsageReport,
+  IUsageBySourceReport,
+} from '@robota-sdk/agent-interface-analytics';
+import type { TServerMessage } from '../wire-messages.js';
+
+const report: IPersonalUsageReport = {
+  schemaVersion: 1,
+  generatedAt: '2026-09-06T03:00:00.000Z',
+  period: '7d',
+  timezone: 'Asia/Seoul',
+  interval: { startDate: '2026-08-31', endDate: '2026-09-06' },
+  totals: {
+    sessions: 1,
+    turns: 2,
+    promptTokens: 10,
+    completionTokens: 5,
+    totalTokens: 15,
+    costUsd: 0.01,
+    costStatus: 'exact',
+  },
+  daily: [],
+  byModel: [],
+  byProvider: [],
+  bySurface: [],
+  bySource: [],
+  byActivity: [],
+  sessionIds: ['session-1'],
+  coverage: {
+    validSessions: 1,
+    corruptSessions: 0,
+    unsupportedSessions: 0,
+    duplicateObservations: 0,
+    legacyObservations: 0,
+    unknownModelObservations: 0,
+    unknownProviderObservations: 0,
+    unknownSurfaceObservations: 0,
+    corruptSessionIds: [],
+    unsupportedSessionIds: [],
+  },
+};
+
+const storedReport: IUsageBySourceReport = {
+  sessionId: 'session-1',
+  totalTokens: 15,
+  promptTokens: 10,
+  completionTokens: 5,
+  costUsd: 0.01,
+  costExact: true,
+  bySource: [],
+  timeline: [],
+};
+
+describe('personal usage report protocol', () => {
+  it('routes a correlated request to the host reporter', async () => {
+    const sent: TServerMessage[] = [];
+    const reporter = vi.fn().mockResolvedValue(report);
+    const { onMessage } = createSessionMessageHandler({
+      session: createTestInteractiveSession(),
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      personalUsageReporter: reporter,
+    });
+
+    onMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'request-1',
+        period: '7d',
+        timezone: 'Asia/Seoul',
+      }),
+    );
+    await Promise.resolve();
+
+    expect(reporter).toHaveBeenCalledWith({ period: '7d', timezone: 'Asia/Seoul' });
+    expect(sent).toContainEqual({
+      type: 'personal_usage_report',
+      requestId: 'request-1',
+      report,
+    });
+  });
+
+  it('returns an explicit correlated error when the host has no reporter', () => {
+    const sent: TServerMessage[] = [];
+    const { onMessage } = createSessionMessageHandler({
+      session: createTestInteractiveSession(),
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    });
+
+    onMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'request-2',
+        period: '30d',
+        timezone: 'UTC',
+      }),
+    );
+
+    expect(sent).toContainEqual({
+      type: 'personal_usage_report_error',
+      requestId: 'request-2',
+      code: 'not_available',
+      message: 'Personal usage reporting is not available on this host.',
+    });
+  });
+
+  it('correlates malformed report requests only when requestId itself is valid', () => {
+    const sent: TServerMessage[] = [];
+    const { onMessage } = createSessionMessageHandler({
+      session: createTestInteractiveSession(),
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      personalUsageReporter: vi.fn(),
+    });
+
+    onMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 'safe-id',
+        period: '14d',
+        timezone: 'UTC',
+      }),
+    );
+    onMessage(
+      JSON.stringify({
+        type: 'get-personal-usage-report',
+        requestId: 42,
+        period: '14d',
+        timezone: 'UTC',
+      }),
+    );
+
+    expect(sent[0]).toEqual({
+      type: 'personal_usage_report_error',
+      requestId: 'safe-id',
+      code: 'report_failed',
+      message: 'Invalid personal usage report request.',
+    });
+    expect(sent[1]?.type).toBe('protocol_error');
+    expect(JSON.stringify(sent[1])).not.toContain('42');
+  });
+
+  it('routes a correlated stored-session drill-down through the host producer', async () => {
+    const sent: TServerMessage[] = [];
+    const reporter = vi.fn().mockResolvedValue(storedReport);
+    const { onMessage } = createSessionMessageHandler({
+      session: createTestInteractiveSession(),
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      storedSessionUsageReporter: reporter,
+    });
+
+    onMessage(
+      JSON.stringify({
+        type: 'get-stored-session-usage-report',
+        requestId: 'drilldown-1',
+        sessionId: 'session-1',
+      }),
+    );
+    await Promise.resolve();
+
+    expect(reporter).toHaveBeenCalledWith('session-1');
+    expect(sent).toContainEqual({
+      type: 'stored_session_usage_report',
+      requestId: 'drilldown-1',
+      sessionId: 'session-1',
+      report: storedReport,
+    });
+  });
+
+  it('does not echo invalid stored-session correlation fields', () => {
+    const sent: TServerMessage[] = [];
+    const { onMessage } = createSessionMessageHandler({
+      session: createTestInteractiveSession(),
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      storedSessionUsageReporter: vi.fn(),
+    });
+
+    onMessage(
+      JSON.stringify({
+        type: 'get-stored-session-usage-report',
+        requestId: 'drilldown-safe',
+        sessionId: 42,
+      }),
+    );
+
+    expect(sent[0]?.type).toBe('protocol_error');
+    expect(JSON.stringify(sent[0])).not.toContain('42');
+  });
+});

package/src/__tests__/project-read-messages.test.ts

@@ -0,0 +1,118 @@
+/**
+ * #3282 §4c — the Project panel's reads dispatch: success answers the matching `project_*` message
+ * under the request's `requestId`; a rejected read becomes a `failed`/`unavailable` result (never an
+ * uncaught rejection — the exact class of bug the `/memory` red-toast fix addresses at the command
+ * layer, guarded again here at the wire boundary); a session that does not implement the capability
+ * (`Partial<ISessionProjectRead>` — see `protocol-session.ts`) answers `protocol_error`, never a throw.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { handleProjectReadMessage, isProjectReadMessage } from '../project-read-messages.js';
+
+import type { TOutboundDeliver } from '../outbound-delivery.js';
+import type { TProjectReadCapableSession } from '../protocol-session.js';
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+
+function collect(): { sent: TServerMessage[]; deliver: TOutboundDeliver } {
+  const sent: TServerMessage[] = [];
+  return { sent, deliver: createOutboundDelivery((m) => sent.push(m), vi.fn()) };
+}
+
+describe('isProjectReadMessage', () => {
+  it('recognizes exactly the three Project panel read types', () => {
+    expect(isProjectReadMessage({ type: 'project-status', requestId: 'r' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'project-diff', requestId: 'r', path: 'a.txt' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'project-memory', requestId: 'r' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'get-status' } as TClientMessage)).toBe(false);
+  });
+});
+
+describe('handleProjectReadMessage', () => {
+  it('answers project_status with the session result under the same requestId', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectStatus: vi.fn().mockResolvedValue({ kind: 'not-a-repository' }),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r1' });
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_status', requestId: 'r1', result: { kind: 'not-a-repository' } },
+    ]);
+  });
+
+  it('passes the path through to readProjectDiff and answers project_diff', async () => {
+    const { sent, deliver } = collect();
+    const readProjectDiff = vi.fn().mockResolvedValue({ kind: 'diff', diffLines: [], truncated: false });
+    const session = { readProjectDiff } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, {
+      type: 'project-diff',
+      requestId: 'r2',
+      path: 'src/a.ts',
+    });
+    await Promise.resolve();
+    expect(readProjectDiff).toHaveBeenCalledExactlyOnceWith('src/a.ts');
+    expect(sent).toEqual([
+      { type: 'project_diff', requestId: 'r2', result: { kind: 'diff', diffLines: [], truncated: false } },
+    ]);
+  });
+
+  it('answers project_memory with the session result', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectMemory: vi
+        .fn()
+        .mockResolvedValue({ kind: 'memory', content: 'x', path: 'MEMORY.md', truncated: false }),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-memory', requestId: 'r3' });
+    await Promise.resolve();
+    expect(sent).toEqual([
+      {
+        type: 'project_memory',
+        requestId: 'r3',
+        result: { kind: 'memory', content: 'x', path: 'MEMORY.md', truncated: false },
+      },
+    ]);
+  });
+
+  it('turns a rejected readProjectStatus into a failed result, never an uncaught rejection', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectStatus: vi.fn().mockRejectedValue(new Error('git not found')),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r4' });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_status', requestId: 'r4', result: { kind: 'failed', message: 'git not found' } },
+    ]);
+  });
+
+  it('turns a rejected readProjectMemory into an unavailable result', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectMemory: vi.fn().mockRejectedValue(new Error('no store')),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-memory', requestId: 'r5' });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_memory', requestId: 'r5', result: { kind: 'unavailable', message: 'no store' } },
+    ]);
+  });
+
+  it('answers protocol_error, never a throw, when the session has no project-read capability', () => {
+    const { sent, deliver } = collect();
+    const session = {} as unknown as TProjectReadCapableSession;
+    expect(() =>
+      handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r6' }),
+    ).not.toThrow();
+    expect(sent).toEqual([
+      {
+        type: 'protocol_error',
+        message: 'This host does not support the Project panel.',
+        requestId: 'r6',
+      },
+    ]);
+  });
+});

package/src/__tests__/resume-buffer.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+
+import { ResumeBuffer } from '../resume-buffer.js';
+import type { TServerMessage } from '../wire-messages.js';
+
+/**
+ * REMOTE-013 E4 TC-01 — the bounded un-acked resume buffer: monotonic seq, ack-drop, tail replay, overrun
+ * marker (never a silent gap), and drop-oldest bound enforcement.
+ */
+
+function msg(delta: string): TServerMessage {
+  return { type: 'text_delta', delta };
+}
+
+describe('ResumeBuffer (REMOTE-013 TC-01)', () => {
+  it('append assigns a monotonic seq starting at 1 and tracks lastSeq', () => {
+    const b = new ResumeBuffer();
+    expect(b.append(msg('a'))).toBe(1);
+    expect(b.append(msg('b'))).toBe(2);
+    expect(b.append(msg('c'))).toBe(3);
+    expect(b.lastSeq).toBe(3);
+  });
+
+  it('tailAfter returns the ordered frames after lastSeq', () => {
+    const b = new ResumeBuffer();
+    b.append(msg('a'));
+    b.append(msg('b'));
+    b.append(msg('c'));
+    const tail = b.tailAfter(1);
+    expect(tail.kind).toBe('tail');
+    if (tail.kind === 'tail') {
+      expect(tail.frames.map((f) => f.seq)).toEqual([2, 3]);
+      expect(tail.frames.map((f) => (f.message as { delta: string }).delta)).toEqual(['b', 'c']);
+    }
+  });
+
+  it('tailAfter at/after the newest seq is an empty tail (caught up, not overrun)', () => {
+    const b = new ResumeBuffer();
+    b.append(msg('a'));
+    b.append(msg('b'));
+    expect(b.tailAfter(2)).toEqual({ kind: 'tail', frames: [] });
+    expect(b.tailAfter(5)).toEqual({ kind: 'tail', frames: [] });
+  });
+
+  it('ackThrough drops frames <= seq; the tail then starts after the ack', () => {
+    const b = new ResumeBuffer();
+    b.append(msg('a')); // 1
+    b.append(msg('b')); // 2
+    b.append(msg('c')); // 3
+    b.ackThrough(2);
+    expect(b.size).toBe(1);
+    const tail = b.tailAfter(2);
+    expect(tail.kind === 'tail' && tail.frames.map((f) => f.seq)).toEqual([3]);
+  });
+
+  it('tailAfter returns overrun only when the client MISSED an evicted frame', () => {
+    const b = new ResumeBuffer({ maxFrames: 2 });
+    b.append(msg('a')); // 1 (evicted)
+    b.append(msg('b')); // 2
+    b.append(msg('c')); // 3 → buffer now holds [2,3]
+    expect(b.size).toBe(2);
+    // client saw NOTHING (lastSeq 0): it needs frame 1, which is evicted → overrun.
+    expect(b.tailAfter(0)).toEqual({ kind: 'overrun' });
+    // client already saw seq 1: it needs 2,3 — both retained → clean tail (no gap).
+    const t1 = b.tailAfter(1);
+    expect(t1.kind === 'tail' && t1.frames.map((f) => f.seq)).toEqual([2, 3]);
+    // client saw seq 2 → only 3 remains.
+    const t2 = b.tailAfter(2);
+    expect(t2.kind === 'tail' && t2.frames.map((f) => f.seq)).toEqual([3]);
+  });
+
+  it('enforces the frame bound (drop-oldest) — never exceeds maxFrames', () => {
+    const b = new ResumeBuffer({ maxFrames: 3 });
+    for (let i = 0; i < 100; i += 1) b.append(msg(`m${i}`));
+    expect(b.size).toBe(3);
+    expect(b.lastSeq).toBe(100); // seq keeps advancing even as old frames drop
+  });
+
+  it('enforces the byte bound (drop-oldest) with an injected sizeOf', () => {
+    const b = new ResumeBuffer({ maxBytes: 30, sizeOf: () => 10 }); // ~3 frames fit
+    for (let i = 0; i < 10; i += 1) b.append(msg(`m${i}`));
+    expect(b.size).toBeLessThanOrEqual(3);
+    // A fresh client can still resume the retained tail.
+    const tail = b.tailAfter(b.lastSeq - 1);
+    expect(tail.kind).toBe('tail');
+  });
+
+  it('overrun after eviction triggers the full-refresh path for a far-behind client', () => {
+    const b = new ResumeBuffer({ maxFrames: 2 });
+    for (let i = 0; i < 10; i += 1) b.append(msg(`m${i}`)); // seqs 1..10, retains [9,10]
+    expect(b.tailAfter(0)).toEqual({ kind: 'overrun' }); // brand-new / far-behind client
+  });
+});