@robota-sdk/agent-transport 3.0.0-beta.82 → 3.0.0-beta.83

package/src/__tests__/history-attached-budget.test.ts

@@ -0,0 +1,216 @@
+/**
+ * #3189: a history larger than an attached terminal's backpressure budget reaches that terminal
+ * whole, over a real socket, without the connection being cut.
+ *
+ * The carrier here is wired as the supervised attach carrier is: every reply goes through
+ * `createOutboundDelivery` measuring the socket's `writableLength` against
+ * `ATTACHED_SURFACE_MAX_PENDING_BYTES`, and a failure destroys the socket. The client sends what an
+ * attached terminal sends when it starts, all at once, and pages the history as it arrives.
+ */
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  createOutboundDelivery,
+} from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { Server, Socket } from 'node:net';
+
+type TListener = (...args: unknown[]) => void;
+
+const ENTRY_BYTES = 20_000;
+/** Half as much again as the budget, so one frame holding it all would trip it. */
+const HISTORY_BYTES = ATTACHED_SURFACE_MAX_PENDING_BYTES * 1.5;
+
+const STARTUP: readonly TClientMessage[] = [
+  { type: 'get-history' },
+  { type: 'get-context' },
+  { type: 'get-commands' },
+  { type: 'get-status' },
+  { type: 'get-executing' },
+  { type: 'get-pending' },
+  { type: 'get-execution-workspace' },
+];
+
+function longHistory(): IHistoryEntry[] {
+  return Array.from({ length: Math.ceil(HISTORY_BYTES / ENTRY_BYTES) }, (_, index) => ({
+    id: `e${index}`,
+    timestamp: new Date('2026-09-26T00:00:00.000Z'),
+    category: 'chat',
+    type: 'assistant',
+    data: { role: 'assistant', content: 'x'.repeat(ENTRY_BYTES) },
+  }));
+}
+
+function emittingSession(
+  history: IHistoryEntry[],
+): IInteractiveSession & { emit: (event: string, payload: unknown) => void } {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    getFullHistory: () => history,
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return Object.assign(session, {
+    emit: (event: string, payload: unknown) => {
+      for (const handler of listeners.get(event) ?? []) handler(payload);
+    },
+  });
+}
+
+/** One connection's carrier, as the supervised attach carrier builds it. */
+function serve(session: IInteractiveSession, socket: Socket, onCut: (error: Error) => void): void {
+  const deliver = createOutboundDelivery(
+    (message) => {
+      socket.write(`${JSON.stringify(message)}\n`);
+    },
+    (error) => {
+      onCut(error);
+      socket.destroy();
+    },
+    () => socket.writableLength,
+    ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  );
+  const { onMessage, cleanup } = createSessionMessageHandler({ session, deliver });
+  let buffered = '';
+  socket.setEncoding('utf8');
+  socket.on('data', (chunk: string) => {
+    buffered += chunk;
+    // Every complete line of a chunk is handled in one pass, as the carrier's drain loop does.
+    for (let end = buffered.indexOf('\n'); end !== -1; end = buffered.indexOf('\n')) {
+      const line = buffered.slice(0, end);
+      buffered = buffered.slice(end + 1);
+      onMessage(line);
+    }
+  });
+  socket.on('close', cleanup);
+}
+
+interface IClient {
+  readonly frames: TServerMessage[];
+  readonly closed: Promise<void>;
+  send(message: TClientMessage): void;
+  next(predicate: (frame: TServerMessage) => boolean): Promise<TServerMessage>;
+  end(): void;
+}
+
+function connect(path: string): Promise<IClient> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(path);
+    const frames: TServerMessage[] = [];
+    const waiters: {
+      predicate: (frame: TServerMessage) => boolean;
+      found: (f: TServerMessage) => void;
+      lost: (error: Error) => void;
+    }[] = [];
+    let buffered = '';
+    let markClosed: () => void = () => undefined;
+    const closed = new Promise<void>((done) => {
+      markClosed = done;
+    });
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk: string) => {
+      buffered += chunk;
+      for (let end = buffered.indexOf('\n'); end !== -1; end = buffered.indexOf('\n')) {
+        const frame = JSON.parse(buffered.slice(0, end)) as TServerMessage;
+        buffered = buffered.slice(end + 1);
+        frames.push(frame);
+        for (const waiter of waiters.splice(0)) {
+          if (waiter.predicate(frame)) waiter.found(frame);
+          else waiters.push(waiter);
+        }
+      }
+    });
+    socket.on('close', () => {
+      markClosed();
+      for (const waiter of waiters.splice(0))
+        waiter.lost(new Error('the host closed the connection'));
+    });
+    socket.on('error', reject);
+    socket.on('connect', () =>
+      resolve({
+        frames,
+        closed,
+        send: (message) => socket.write(`${JSON.stringify(message)}\n`),
+        next: (predicate) =>
+          new Promise((found, lost) => {
+            waiters.push({ predicate, found, lost });
+          }),
+        end: () => socket.end(),
+      }),
+    );
+  });
+}
+
+function isHistory(frame: TServerMessage): frame is Extract<TServerMessage, { type: 'history' }> {
+  return frame.type === 'history';
+}
+
+describe('a history larger than the attached-surface budget (#3189)', () => {
+  let server: Server | undefined;
+  let dir: string | undefined;
+
+  afterEach(async () => {
+    await new Promise<void>((done) => (server ? server.close(() => done()) : done()));
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('reaches an attached terminal whole, and the turn after it does not cut the terminal off', async () => {
+    const history = longHistory();
+    const session = emittingSession(history);
+    const cuts: Error[] = [];
+    dir = mkdtempSync(join(tmpdir(), 'rh-'));
+    const path = join(dir, 's.sock');
+    server = createServer((socket) => serve(session, socket, (error) => cuts.push(error)));
+    await new Promise<void>((done) => server!.listen(path, done));
+    const client = await connect(path);
+
+    // What an attached terminal sends when it starts, in one burst.
+    for (const message of STARTUP) client.send(message);
+    const received: string[] = [];
+    let page = (await client.next(isHistory)) as Extract<TServerMessage, { type: 'history' }>;
+    for (;;) {
+      received.push(...page.entries.map((entry) => entry.id));
+      const next = page.startIndex + page.entries.length;
+      if (next >= page.total) break;
+      const arriving = client.next(isHistory);
+      client.send({ type: 'get-history', fromIndex: next });
+      page = (await arriving) as Extract<TServerMessage, { type: 'history' }>;
+    }
+    expect(received).toEqual(history.map((entry) => entry.id));
+
+    // A turn ends: its result, then more frames at once, as the host sends them.
+    const thinking = client.next((frame) => frame.type === 'thinking');
+    session.emit('complete', {
+      response: 'done',
+      history,
+      toolSummaries: [],
+      contextState: { usedTokens: 1, maxTokens: 10, usedPercentage: 10 },
+    });
+    session.emit('thinking', false);
+    await thinking;
+
+    expect(cuts).toEqual([]);
+    expect(client.frames.map((frame) => frame.type)).toEqual(
+      expect.arrayContaining(['context', 'commands', 'session_status', 'pending', 'complete']),
+    );
+    client.end();
+    await client.closed;
+  }, 20_000);
+});

package/src/__tests__/message-decoders.test.ts

@@ -1,3 +1,4 @@
+import { SESSION_CHANGE_REFUSAL_CODES } from '@robota-sdk/agent-interface-session';
 import { describe, expect, it } from 'vitest';
 
 import {
@@ -18,11 +19,18 @@ import type { TClientMessage, TServerMessage } from '../wire-messages.js';
  */
 const CLIENT_SAMPLES: Readonly<Record<TClientMessage['type'], TClientMessage>> = {
   submit: { type: 'submit', prompt: 'hi' },
-  command: { type: 'command', name: 'help', args: 'x' },
+  command: { type: 'command', name: 'help', args: 'x', requestId: 'command-1' },
   abort: { type: 'abort' },
   'cancel-queue': { type: 'cancel-queue' },
   'get-messages': { type: 'get-messages' },
+  'get-history': { type: 'get-history', fromIndex: 40 },
+  'get-prompts': { type: 'get-prompts' },
   'get-context': { type: 'get-context' },
+  'get-commands': { type: 'get-commands' },
+  'get-status': { type: 'get-status' },
+  'list-sessions': { type: 'list-sessions', requestId: 'request-3' },
+  'new-session': { type: 'new-session', requestId: 'request-4' },
+  'switch-session': { type: 'switch-session', sessionId: 'session-2', requestId: 'request-5' },
   'get-usage-report': { type: 'get-usage-report' },
   'get-personal-usage-report': {
     type: 'get-personal-usage-report',
@@ -38,6 +46,13 @@ const CLIENT_SAMPLES: Readonly<Record<TClientMessage['type'], TClientMessage>> =
   'get-executing': { type: 'get-executing' },
   'get-pending': { type: 'get-pending' },
   'get-execution-workspace': { type: 'get-execution-workspace' },
+  'read-execution-detail': {
+    type: 'read-execution-detail',
+    requestId: 'detail-1',
+    entryId: 'main',
+    cursor: { offset: 20 },
+  },
+  'stop-waiting-loop': { type: 'stop-waiting-loop', requestId: 'loop-1' },
   'get-background-tasks': {
     type: 'get-background-tasks',
     filter: { kind: 'agent', includeClosed: true },
@@ -69,9 +84,47 @@ const SERVER_SAMPLES: Readonly<Record<TServerMessage['type'], TServerMessage>> =
   complete: { type: 'complete', result: {} as never },
   interrupted: { type: 'interrupted', result: {} as never },
   error: { type: 'error', message: 'm' },
-  command_result: { type: 'command_result', name: 'n', message: 'm', success: true },
+  command_result: {
+    type: 'command_result',
+    name: 'n',
+    message: 'm',
+    success: true,
+    requestId: 'command-1',
+  },
   messages: { type: 'messages', messages: [] },
+  history: {
+    type: 'history',
+    startIndex: 3,
+    total: 4,
+    entries: [
+      {
+        id: 'e1',
+        timestamp: '2026-09-26T01:02:03.004Z',
+        category: 'event',
+        type: 'skill-activation',
+        data: { name: 'review' },
+      },
+    ],
+  },
   context: { type: 'context', state: {} as never },
+  history_changed: { type: 'history_changed' },
+  turn_source: { type: 'turn_source', source: 'peer' },
+  commands: { type: 'commands', commands: [], skills: [] },
+  session_status: { type: 'session_status', status: {} as never },
+  sessions: { type: 'sessions', requestId: 'request-3', listing: {} as never },
+  sessions_error: {
+    type: 'sessions_error',
+    requestId: 'request-3',
+    code: 'list_failed',
+    message: 'unreadable store',
+  },
+  session_switched: { type: 'session_switched', event: { sessionId: 'session-2' } },
+  session_change_failed: {
+    type: 'session_change_failed',
+    code: 'prompt_pending',
+    message: 'Answer the pending prompt first.',
+    requestId: 'request-5',
+  },
   usage_report: { type: 'usage_report', report: {} as never },
   personal_usage_report: {
     type: 'personal_usage_report',
@@ -98,8 +151,23 @@ const SERVER_SAMPLES: Readonly<Record<TServerMessage['type'], TServerMessage>> =
     message: 'not found',
   },
   executing: { type: 'executing', executing: false },
-  pending: { type: 'pending', pending: null },
+  pending: { type: 'pending', pending: null, pendingCount: 0 },
   execution_workspace_event: { type: 'execution_workspace_event', snapshot: {} as never },
+  execution_detail: {
+    type: 'execution_detail',
+    requestId: 'detail-1',
+    page: { entryId: 'main', records: [], nextCursor: { offset: 20 } },
+  },
+  execution_detail_error: {
+    type: 'execution_detail_error',
+    requestId: 'detail-1',
+    message: 'Unknown entry: main',
+  },
+  waiting_loop_stop: {
+    type: 'waiting_loop_stop',
+    requestId: 'loop-1',
+    outcome: { kind: 'stopped', loopId: 'loop-a', message: 'Stopped loop-a.' },
+  },
   background_task_event: { type: 'background_task_event', event: {} as never },
   background_job_group_event: { type: 'background_job_group_event', event: {} as never },
   plan_event: { type: 'plan_event', event: {} as never },
@@ -122,7 +190,7 @@ const SERVER_SAMPLES: Readonly<Record<TServerMessage['type'], TServerMessage>> =
     taskId: 't',
     success: true,
   },
-  protocol_error: { type: 'protocol_error', message: 'm' },
+  protocol_error: { type: 'protocol_error', message: 'm', requestId: 'command-1' },
   resume_gap: { type: 'resume_gap' },
 };
 
@@ -170,6 +238,31 @@ const MALFORMED_CLIENT: ReadonlyArray<[string, unknown]> = [
   ['resume with a string lastSeq', { type: 'resume', lastSeq: '4' }],
   ['ack with NaN', { type: 'ack', seq: Number.NaN }],
   ['cancel-background-task with an empty taskId', { type: 'cancel-background-task', taskId: '' }],
+  ['list-sessions without requestId', { type: 'list-sessions' }],
+  ['get-history from a negative index', { type: 'get-history', fromIndex: -1 }],
+  ['get-history from a fractional index', { type: 'get-history', fromIndex: 1.5 }],
+  ['command with an empty requestId', { type: 'command', name: 'n', requestId: '' }],
+  ['switch-session with an empty sessionId', { type: 'switch-session', sessionId: '' }],
+  [
+    'switch-session with a numeric requestId',
+    { type: 'switch-session', sessionId: 's', requestId: 1 },
+  ],
+  ['new-session with an empty requestId', { type: 'new-session', requestId: '' }],
+  ['read-execution-detail without requestId', { type: 'read-execution-detail', entryId: 'main' }],
+  [
+    'read-execution-detail with an empty entryId',
+    { type: 'read-execution-detail', requestId: 'r', entryId: '' },
+  ],
+  [
+    'read-execution-detail with a negative offset',
+    { type: 'read-execution-detail', requestId: 'r', entryId: 'main', cursor: { offset: -1 } },
+  ],
+  [
+    'read-execution-detail with a string offset',
+    { type: 'read-execution-detail', requestId: 'r', entryId: 'main', cursor: { offset: '2' } },
+  ],
+  ['stop-waiting-loop without requestId', { type: 'stop-waiting-loop' }],
+  ['stop-waiting-loop with an empty requestId', { type: 'stop-waiting-loop', requestId: '' }],
 ];
 
 const MALFORMED_SERVER: ReadonlyArray<[string, unknown]> = [
@@ -182,13 +275,86 @@ const MALFORMED_SERVER: ReadonlyArray<[string, unknown]> = [
   ['thinking with a string flag', { type: 'thinking', isThinking: 'yes' }],
   ['messages with a non-array', { type: 'messages', messages: {} }],
   ['messages with a primitive entry', { type: 'messages', messages: ['x'] }],
-  ['pending with a number', { type: 'pending', pending: 1 }],
+  ['pending with a number', { type: 'pending', pending: 1, pendingCount: 1 }],
+  ['pending with a negative count', { type: 'pending', pending: null, pendingCount: -1 }],
+  ['pending with a fractional count', { type: 'pending', pending: 'p', pendingCount: 1.5 }],
   ['background_task with an array task', { type: 'background_task', taskId: 't', task: [] }],
   [
     'control result with an unknown action',
     { type: 'background_task_control_result', action: 'nuke', taskId: 't', success: true },
   ],
   ['command_result without success', { type: 'command_result', name: 'n', message: 'm' }],
+  [
+    'sessions_error with an unknown code',
+    { type: 'sessions_error', requestId: 'r', code: 'nope', message: 'm' },
+  ],
+  ['session_switched without event', { type: 'session_switched' }],
+  [
+    'session_change_failed with an unknown code',
+    { type: 'session_change_failed', code: 'nope', message: 'm' },
+  ],
+  ['session_change_failed without message', { type: 'session_change_failed', code: 'limit' }],
+  [
+    'session_change_failed with a numeric requestId',
+    { type: 'session_change_failed', code: 'limit', message: 'm', requestId: 1 },
+  ],
+  ['history without entries', { type: 'history', startIndex: 0, total: 0 }],
+  ['history without its place', { type: 'history', entries: [] }],
+  ['history with a negative total', { type: 'history', startIndex: 0, total: -1, entries: [] }],
+  ['history with a primitive entry', { type: 'history', startIndex: 0, total: 1, entries: ['x'] }],
+  [
+    'history with a numeric timestamp',
+    {
+      type: 'history',
+      startIndex: 0,
+      total: 1,
+      entries: [{ id: 'e', timestamp: 1, category: 'chat', type: 'user' }],
+    },
+  ],
+  [
+    'history with an entry missing its category',
+    {
+      type: 'history',
+      startIndex: 0,
+      total: 1,
+      entries: [{ id: 'e', timestamp: 't', type: 'user' }],
+    },
+  ],
+  [
+    'protocol_error with a numeric requestId',
+    { type: 'protocol_error', message: 'm', requestId: 1 },
+  ],
+  ['turn_source with an unknown source', { type: 'turn_source', source: 'robot' }],
+  ['turn_source without source', { type: 'turn_source' }],
+  ['execution_detail without page', { type: 'execution_detail', requestId: 'r' }],
+  ['execution_detail with an array page', { type: 'execution_detail', requestId: 'r', page: [] }],
+  ['execution_detail without requestId', { type: 'execution_detail', page: {} }],
+  ['execution_detail_error without message', { type: 'execution_detail_error', requestId: 'r' }],
+  ['waiting_loop_stop without outcome', { type: 'waiting_loop_stop', requestId: 'r' }],
+  [
+    'waiting_loop_stop with an unknown kind',
+    { type: 'waiting_loop_stop', requestId: 'r', outcome: { kind: 'paused' } },
+  ],
+  [
+    'waiting_loop_stop stopped without loopId',
+    { type: 'waiting_loop_stop', requestId: 'r', outcome: { kind: 'stopped' } },
+  ],
+  [
+    'waiting_loop_stop several without message',
+    { type: 'waiting_loop_stop', requestId: 'r', outcome: { kind: 'several' } },
+  ],
+  [
+    'waiting_loop_stop failed with a numeric loopId',
+    {
+      type: 'waiting_loop_stop',
+      requestId: 'r',
+      outcome: { kind: 'failed', loopId: 1, message: 'm' },
+    },
+  ],
+  [
+    'waiting_loop_stop with a prototype-only kind',
+    { type: 'waiting_loop_stop', requestId: 'r', outcome: { kind: 'toString' } },
+  ],
 ];
 
 describe('decodeClientMessage (issue #2045)', () => {
@@ -228,6 +394,36 @@ describe('decodeServerMessage (issue #2045)', () => {
   it.each(MALFORMED_SERVER)('refuses %s', (_label, value) => {
     expect(decodeServerMessage(value).ok).toBe(false);
   });
+
+  it('accepts every refusal code the session contracts declare, and a refusal without requestId', () => {
+    for (const code of SESSION_CHANGE_REFUSAL_CODES) {
+      expect(decodeServerMessage({ type: 'session_change_failed', code, message: 'm' }).ok).toBe(
+        true,
+      );
+    }
+  });
+
+  it('accepts every waiting-loop stop outcome', () => {
+    for (const outcome of [
+      { kind: 'none' },
+      { kind: 'several', message: 'Use /loop stop <id>.' },
+      { kind: 'stopped', loopId: 'loop-a' },
+      { kind: 'failed', message: 'store unavailable' },
+      { kind: 'failed', loopId: 'loop-a', message: 'store unavailable' },
+    ]) {
+      expect(decodeServerMessage({ type: 'waiting_loop_stop', requestId: 'r', outcome }).ok).toBe(
+        true,
+      );
+    }
+  });
+
+  it('accepts a pending frame without its count, as a host from before the count sends it', () => {
+    // Refusing it would cut a newer client off from an older daemon on every prompt it queues.
+    expect(decodeFrame('{"type":"pending","pending":null}', decodeServerMessage)).toEqual({
+      ok: true,
+      message: { type: 'pending', pending: null },
+    });
+  });
 });
 
 describe('decodeFrame — the one carrier path', () => {

package/src/__tests__/session-detail-loop-status.test.ts

@@ -0,0 +1,169 @@
+/**
+ * #3189 step 3b: an attached client reads a workspace entry's detail, stops a waiting self-paced
+ * loop, and follows status changes another client made.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { isObserverMessageType as isObserverMessageTypeFromClient } from '../client.js';
+import { isObserverMessageType } from '../index.js';
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IExecutionDetailPage } from '@robota-sdk/agent-interface-execution';
+import type {
+  IInteractiveSession,
+  ISessionStatusSnapshot,
+} from '@robota-sdk/agent-interface-session';
+
+type TListener = (...args: unknown[]) => void;
+
+const page: IExecutionDetailPage = {
+  entryId: 'main',
+  cursor: { offset: 20 },
+  nextCursor: { offset: 40 },
+  records: [{ id: 'main:20:0', kind: 'message', text: 'hello' }],
+};
+
+function createSession(overrides: Partial<IInteractiveSession> = {}): IInteractiveSession & {
+  emit: (event: string, ...args: unknown[]) => void;
+} {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    readExecutionWorkspaceDetail: vi.fn().mockResolvedValue(page),
+    stopWaitingSelfPacedLoop: vi.fn().mockResolvedValue({ kind: 'stopped', loopId: 'loop-a' }),
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+    ...overrides,
+  });
+  return Object.assign(session, {
+    emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((handler) => handler(...args));
+    },
+  });
+}
+
+function attach(
+  session: IInteractiveSession,
+  role: 'drive' | 'observe' = 'drive',
+): { sent: TServerMessage[]; send: (message: TClientMessage) => void } {
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session,
+    role,
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)) };
+}
+
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('read-execution-detail', () => {
+  it('answers with the page the session read, under the request id', async () => {
+    const session = createSession();
+    const client = attach(session);
+    client.send({
+      type: 'read-execution-detail',
+      requestId: 'detail-1',
+      entryId: 'main',
+      cursor: { offset: 20 },
+    });
+    await flush();
+    expect(session.readExecutionWorkspaceDetail).toHaveBeenCalledExactlyOnceWith('main', {
+      offset: 20,
+    });
+    expect(client.sent).toEqual([{ type: 'execution_detail', requestId: 'detail-1', page }]);
+  });
+
+  it('answers with an error reply when the session cannot read the entry', async () => {
+    const session = createSession({
+      readExecutionWorkspaceDetail: vi.fn().mockRejectedValue(new Error('Unknown entry: gone')),
+    });
+    const client = attach(session);
+    client.send({ type: 'read-execution-detail', requestId: 'detail-2', entryId: 'gone' });
+    await flush();
+    expect(client.sent).toEqual([
+      { type: 'execution_detail_error', requestId: 'detail-2', message: 'Unknown entry: gone' },
+    ]);
+  });
+});
+
+describe('stop-waiting-loop', () => {
+  it('answers with the outcome the session reports', async () => {
+    const session = createSession();
+    const client = attach(session);
+    client.send({ type: 'stop-waiting-loop', requestId: 'loop-1' });
+    await flush();
+    expect(session.stopWaitingSelfPacedLoop).toHaveBeenCalledOnce();
+    expect(client.sent).toEqual([
+      {
+        type: 'waiting_loop_stop',
+        requestId: 'loop-1',
+        outcome: { kind: 'stopped', loopId: 'loop-a' },
+      },
+    ]);
+  });
+
+  it('reports a session that throws as a failed stop', async () => {
+    const session = createSession({
+      stopWaitingSelfPacedLoop: vi.fn().mockRejectedValue(new Error('store unavailable')),
+    });
+    const client = attach(session);
+    client.send({ type: 'stop-waiting-loop', requestId: 'loop-2' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'waiting_loop_stop',
+        requestId: 'loop-2',
+        outcome: { kind: 'failed', message: 'store unavailable' },
+      },
+    ]);
+  });
+});
+
+describe('observers', () => {
+  it('may read an entry detail but may not stop a loop', async () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'read-execution-detail', requestId: 'detail-3', entryId: 'main' });
+    observer.send({ type: 'stop-waiting-loop', requestId: 'loop-3' });
+    await flush();
+    expect(session.stopWaitingSelfPacedLoop).not.toHaveBeenCalled();
+    expect(observer.sent).toEqual([
+      { type: 'protocol_error', message: 'Not permitted for an observer: stop-waiting-loop' },
+      { type: 'execution_detail', requestId: 'detail-3', page },
+    ]);
+  });
+
+  it('share one allowlist between the host and both package entries', () => {
+    expect(isObserverMessageTypeFromClient).toBe(isObserverMessageType);
+    expect(isObserverMessageType('read-execution-detail')).toBe(true);
+    expect(isObserverMessageType('get-status')).toBe(true);
+    expect(isObserverMessageType('stop-waiting-loop')).toBe(false);
+    expect(isObserverMessageType('get-prompts')).toBe(false);
+    expect(isObserverMessageType('submit')).toBe(false);
+    expect(isObserverMessageType('not-a-message')).toBe(false);
+  });
+});
+
+describe('status_changed', () => {
+  it('pushes the new status to every attached client as session_status', () => {
+    const session = createSession();
+    const drive = attach(session);
+    const observer = attach(session, 'observe');
+    const status: ISessionStatusSnapshot = {
+      ...session.getStatusSnapshot(),
+      permissionMode: 'plan',
+    };
+    session.emit('status_changed', status);
+    expect(drive.sent).toEqual([{ type: 'session_status', status }]);
+    expect(observer.sent).toEqual([{ type: 'session_status', status }]);
+  });
+});