@robota-sdk/agent-transport 3.0.0-beta.78 → 3.0.0-beta.81

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__/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__/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
+  });
+});

package/src/__tests__/session-event-delivery.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+import { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from '../session-events.js';
+
+import type { TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+type TEmittingSession = IInteractiveSession & {
+  emitForTest: (event: string, payload: unknown) => void;
+};
+
+function createSession(): TEmittingSession {
+  const listeners = new Map<string, Set<(payload: unknown) => void>>();
+  return {
+    getActiveDriverId: () => null,
+    on: vi.fn((event: string, handler: (payload: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }),
+    off: vi.fn((event: string, handler: (payload: unknown) => void) => {
+      listeners.get(event)?.delete(handler);
+    }),
+    emitForTest: (event: string, payload: unknown) => {
+      for (const handler of listeners.get(event) ?? []) handler(payload);
+    },
+  } as unknown as TEmittingSession;
+}
+
+describe('protocol session-event delivery policy (ARCH-020/ARCH-028)', () => {
+  it('mechanically matches every surface classification to an actual subscription', () => {
+    const session = createSession();
+    const { cleanup } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery(vi.fn(), vi.fn()),
+    });
+    const classifiedForSubscription = Object.entries(PROTOCOL_SESSION_EVENT_CLASSIFICATION)
+      .filter(([, classification]) => classification !== 'non-surface')
+      .map(([event]) => event)
+      .sort();
+    const onCalls = vi.mocked(session.on).mock.calls;
+    expect(onCalls.map(([event]) => event).sort()).toEqual(classifiedForSubscription);
+
+    cleanup();
+    const offCalls = vi.mocked(session.off).mock.calls;
+    expect(offCalls.map(([event]) => event).sort()).toEqual(classifiedForSubscription);
+    for (const [event, handler] of onCalls) {
+      expect(offCalls).toContainEqual([event, handler]);
+    }
+  });
+
+  it('forwards plan, context refresh, and branch events as typed protocol frames', () => {
+    const session = createSession();
+    const sent: TServerMessage[] = [];
+    createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    });
+
+    session.emitForTest('plan_event', { type: 'plan_created', plan: { id: 'plan-1' } });
+    session.emitForTest('context_file_refreshed', { filePath: '/repo/AGENTS.md' });
+    session.emitForTest('branch_event', {
+      kind: 'branch_switched',
+      checkpointId: 'turn-0002',
+      branchId: 'branch-2',
+    });
+
+    expect(sent.map((message) => message.type)).toEqual([
+      'plan_event',
+      'context_file_refreshed',
+      'branch_event',
+    ]);
+  });
+
+  it('isolates a carrier send failure and reports its owning session event', () => {
+    const session = createSession();
+    const failures: Array<{ message: string; event: string }> = [];
+    createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery(
+        () => {
+          throw new Error('socket closed');
+        },
+        (error, event) => {
+          failures.push({ message: error.message, event });
+          throw new Error('diagnostic callback failed');
+        },
+      ),
+    });
+
+    expect(() =>
+      session.emitForTest('branch_event', {
+        kind: 'checkpoint_created',
+        checkpointId: 'turn-0001',
+        branchId: 'main',
+      }),
+    ).not.toThrow();
+    expect(failures).toEqual([{ message: 'socket closed', event: 'branch_event' }]);
+  });
+});

package/src/__tests__/session-message-handler-e5.test.ts

@@ -0,0 +1,99 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+import type { TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { TBackgroundTaskEvent } from '@robota-sdk/agent-interface-execution';
+
+/**
+ * REMOTE-014 E5 TC-03/05 — the protocol layer: the SERVER-ASSIGNED driver id is injected into inbound
+ * submit/command/prompt-response (a client cannot send its own), and turn-authored events are SELECTIVELY
+ * stamped with the active turn's driver (background events are never stamped).
+ */
+
+function mockSession(activeDriverId: string | null) {
+  const listeners = new Map<string, Set<(...a: unknown[]) => void>>();
+  return Object.assign(createTestInteractiveSession(), {
+    submit: vi.fn().mockResolvedValue(undefined),
+    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
+    resolvePermission: vi.fn(),
+    resolveAsk: vi.fn(),
+    getActiveDriverId: vi.fn().mockReturnValue(activeDriverId),
+    on: (e: string, h: (...a: unknown[]) => void) => {
+      if (!listeners.has(e)) listeners.set(e, new Set());
+      listeners.get(e)!.add(h);
+    },
+    off: (e: string, h: (...a: unknown[]) => void) => listeners.get(e)?.delete(h),
+    _emit: (e: string, ...a: unknown[]) => listeners.get(e)?.forEach((h) => h(...a)),
+  });
+}
+
+describe('session-message-handler E5 driver attribution (REMOTE-014)', () => {
+  it('TC-05: injects the SERVER-ASSIGNED driver id into submit + prompt-response (client cannot forge it)', () => {
+    const session = mockSession(null);
+    const { onMessage } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery(() => {}, vi.fn()),
+      driverId: 'device-42',
+    });
+    // A client submit frame carries NO driverId field (structurally — TClientMessage has none); the handler
+    // injects the bound server id.
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hi', driverId: 'spoofed' }));
+    expect(session.submit as ReturnType<typeof vi.fn>).toHaveBeenCalledWith(
+      'hi',
+      undefined,
+      undefined,
+      {
+        driverId: 'device-42',
+      },
+    );
+    onMessage(JSON.stringify({ type: 'permission-response', id: 'p1', result: true }));
+    expect(session.resolvePermission).toHaveBeenCalledWith('p1', true, 'device-42');
+    onMessage(
+      JSON.stringify({
+        type: 'ask-response',
+        id: 'a1',
+        response: { type: 'answer', values: ['y'] },
+      }),
+    );
+    expect(session.resolveAsk).toHaveBeenCalledWith(
+      'a1',
+      { type: 'answer', values: ['y'] },
+      'device-42',
+    );
+  });
+
+  it('TC-03: SELECTIVELY stamps turn-authored events with the active driver; background events carry none', () => {
+    const session = mockSession('driver-A');
+    const sent: TServerMessage[] = [];
+    createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((m) => sent.push(m), vi.fn()),
+    });
+
+    session._emit('user_message', 'hello');
+    session._emit('text_delta', 'chunk');
+    session._emit('background_task_event', { type: 'noop' } as unknown as TBackgroundTaskEvent);
+
+    const userMsg = sent.find((m) => m.type === 'user_message') as { driverId?: string };
+    const textDelta = sent.find((m) => m.type === 'text_delta') as { driverId?: string };
+    const bgEvent = sent.find((m) => m.type === 'background_task_event') as { driverId?: string };
+    expect(userMsg.driverId).toBe('driver-A');
+    expect(textDelta.driverId).toBe('driver-A');
+    expect(bgEvent.driverId).toBeUndefined(); // background events are NOT turn-authored
+  });
+
+  it('TC-03: an unattributed (idle) turn stamps no driverId', () => {
+    const session = mockSession(null); // getActiveDriverId → null
+    const sent: TServerMessage[] = [];
+    createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((m) => sent.push(m), vi.fn()),
+    });
+    session._emit('user_message', 'hi');
+    expect((sent[0] as { driverId?: string }).driverId).toBeUndefined();
+  });
+});