@vellumai/assistant 0.3.0

package/src/__tests__/session-queue.test.ts

@@ -0,0 +1,1535 @@
+import { describe, expect, mock, test, beforeEach, afterAll } from 'bun:test';
+import { rmSync, writeFileSync } from 'node:fs';
+import type { Message, ProviderResponse } from '../providers/types.js';
+import type { AgentEvent, CheckpointInfo, CheckpointDecision } from '../agent/loop.js';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+
+// ---------------------------------------------------------------------------
+// Mocks — must precede the Session import so Bun applies them at load time.
+// ---------------------------------------------------------------------------
+
+function makeLoggerStub(): Record<string, unknown> {
+  const stub: Record<string, unknown> = {};
+  for (const m of ['info', 'warn', 'error', 'debug', 'trace', 'fatal', 'silent', 'child']) {
+    stub[m] = m === 'child' ? () => makeLoggerStub() : () => {};
+  }
+  return stub;
+}
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => makeLoggerStub(),
+}));
+
+mock.module('../util/platform.js', () => ({
+  getSocketPath: () => '/tmp/test.sock',
+  getDataDir: () => '/tmp',
+}));
+
+mock.module('../providers/registry.js', () => ({
+  getProvider: () => ({ name: 'mock-provider' }),
+  initializeProviders: () => {},
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({
+    provider: 'mock-provider',
+    maxTokens: 4096,
+    thinking: false,
+    contextWindow: {
+      maxInputTokens: 100000,
+      thresholdTokens: 80000,
+      preserveRecentMessages: 6,
+      summaryModel: 'mock-model',
+      maxSummaryTokens: 512,
+    },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+    timeouts: { permissionTimeoutSec: 1 },
+    apiKeys: {},
+    skills: { entries: {}, allowBundled: true },
+    memory: { retrieval: { injectionStrategy: 'inline' } },
+    permissions: { mode: 'legacy' },
+  }),
+  loadRawConfig: () => ({}),
+  saveRawConfig: () => {},
+  invalidateConfigCache: () => {},
+}));
+
+mock.module('../config/system-prompt.js', () => ({
+  buildSystemPrompt: () => 'system prompt',
+}));
+
+mock.module('../config/skills.js', () => ({
+  loadSkillCatalog: () => [],
+  loadSkillBySelector: () => ({ skill: null }),
+  ensureSkillIcon: async () => null,
+}));
+
+mock.module('../config/skill-state.js', () => ({
+  resolveSkillStates: () => [],
+}));
+
+mock.module('../skills/slash-commands.js', () => ({
+  buildInvocableSlashCatalog: () => new Map(),
+  resolveSlashSkillCommand: () => ({ kind: 'not_slash' }),
+  rewriteKnownSlashCommandPrompt: () => '',
+  parseSlashCandidate: () => ({ kind: 'not_slash' }),
+}));
+
+mock.module('../permissions/trust-store.js', () => ({
+  addRule: () => {},
+  findHighestPriorityRule: () => null,
+  clearCache: () => {},
+}));
+
+mock.module('../security/secret-allowlist.js', () => ({
+  resetAllowlist: () => {},
+}));
+
+mock.module('../memory/admin.js', () => ({
+  getMemoryConflictAndCleanupStats: () => ({
+    conflicts: { pending: 0, resolved: 0, oldestPendingAgeMs: null },
+    cleanup: { resolvedBacklog: 0, supersededBacklog: 0, resolvedCompleted24h: 0, supersededCompleted24h: 0 },
+  }),
+}));
+
+mock.module('../memory/conversation-store.js', () => ({
+  getMessages: () => [],
+  getConversation: () => ({
+    id: 'conv-1',
+    contextSummary: null,
+    contextCompactedMessageCount: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalEstimatedCost: 0,
+  }),
+  createConversation: () => ({ id: 'conv-1' }),
+  listConversations: () => [],
+  addMessage: (_convId: string, _role: string, _content: string) => {
+    return { id: `msg-${Date.now()}` };
+  },
+  updateConversationUsage: () => {},
+  updateConversationTitle: () => {},
+}));
+
+let linkAttachmentShouldThrow = false;
+
+mock.module('../memory/attachments-store.js', () => ({
+  uploadAttachment: () => ({ id: `att-${Date.now()}` }),
+  linkAttachmentToMessage: () => {
+    if (linkAttachmentShouldThrow) {
+      throw new Error('Simulated linkAttachmentToMessage failure');
+    }
+  },
+}));
+
+mock.module('../memory/retriever.js', () => ({
+  buildMemoryRecall: async () => ({
+    enabled: false,
+    degraded: false,
+    injectedText: '',
+    lexicalHits: 0,
+    semanticHits: 0,
+    recencyHits: 0,
+    injectedTokens: 0,
+    latencyMs: 0,
+  }),
+  injectMemoryRecallIntoUserMessage: (msg: Message) => msg,
+  stripMemoryRecallMessages: (msgs: Message[]) => msgs,
+}));
+
+mock.module('../context/window-manager.js', () => ({
+  ContextWindowManager: class {
+    constructor() {}
+    async maybeCompact() { return { compacted: false }; }
+  },
+  createContextSummaryMessage: () => ({ role: 'user', content: [{ type: 'text', text: 'summary' }] }),
+  getSummaryFromContextMessage: () => null,
+}));
+
+// ---------------------------------------------------------------------------
+// Workspace/git turn-commit test hooks.
+// ---------------------------------------------------------------------------
+
+const turnCommitCalls: Array<{ workspaceDir: string; sessionId: string; turnNumber: number }> = [];
+let turnCommitHangForever = false;
+
+// ---------------------------------------------------------------------------
+// Usage event capture for request-ID correlation tests.
+// ---------------------------------------------------------------------------
+
+interface CapturedUsageEvent {
+  requestId: string | null;
+  actor: string;
+}
+
+let capturedUsageEvents: CapturedUsageEvent[] = [];
+
+mock.module('../memory/llm-usage-store.js', () => ({
+  recordUsageEvent: (input: { requestId: string | null; actor: string }) => {
+    capturedUsageEvents.push({ requestId: input.requestId, actor: input.actor });
+    return { id: 'mock-id', createdAt: Date.now(), ...input };
+  },
+  listUsageEvents: () => [],
+}));
+
+// ---------------------------------------------------------------------------
+// Controllable AgentLoop mock.
+//
+// Each `run()` call returns a promise that does NOT resolve until the test
+// explicitly calls the stored `resolve` callback. This lets us simulate a
+// long-running agent loop so we can enqueue messages while the first one is
+// still "processing".
+// ---------------------------------------------------------------------------
+
+interface PendingRun {
+  resolve: (history: Message[]) => void;
+  reject: (err: Error) => void;
+  messages: Message[];
+  onEvent: (event: AgentEvent) => void;
+  onCheckpoint?: (checkpoint: CheckpointInfo) => CheckpointDecision;
+}
+
+let pendingRuns: PendingRun[] = [];
+
+mock.module('../agent/loop.js', () => ({
+  AgentLoop: class {
+    constructor() {}
+    async run(
+      messages: Message[],
+      onEvent: (event: AgentEvent) => void,
+      _signal?: AbortSignal,
+      _requestId?: string,
+      onCheckpoint?: (checkpoint: CheckpointInfo) => CheckpointDecision,
+    ): Promise<Message[]> {
+      return new Promise<Message[]>((resolve, reject) => {
+        pendingRuns.push({ resolve, reject, messages, onEvent, onCheckpoint });
+      });
+    }
+  },
+}));
+
+// ---------------------------------------------------------------------------
+// Import Session AFTER mocks are registered.
+// ---------------------------------------------------------------------------
+
+import { Session, MAX_QUEUE_DEPTH } from '../daemon/session.js';
+import type { QueueDrainReason, QueuePolicy } from '../daemon/session.js';
+
+type SessionWithWorkspaceDeps = Session & {
+  getWorkspaceGitService?: (_workspaceDir: string) => { ensureInitialized: () => Promise<void> };
+  commitTurnChanges?: (
+    workspaceDir: string,
+    sessionId: string,
+    turnNumber: number,
+    provider?: unknown,
+    deadlineMs?: number,
+  ) => Promise<void>;
+};
+
+function makeSession(sendToClient?: (msg: ServerMessage) => void): Session {
+  const provider = {
+    name: 'mock',
+    async sendMessage(): Promise<ProviderResponse> {
+      return {
+        content: [],
+        model: 'mock',
+        usage: { inputTokens: 0, outputTokens: 0 },
+        stopReason: 'end_turn',
+      };
+    },
+  };
+  const session = new Session('conv-1', provider, 'system prompt', 4096, sendToClient ?? (() => {}), '/tmp');
+  const sessionWithWorkspaceDeps = session as SessionWithWorkspaceDeps;
+  sessionWithWorkspaceDeps.getWorkspaceGitService = () => ({
+    ensureInitialized: async () => {},
+  });
+  sessionWithWorkspaceDeps.commitTurnChanges = async (workspaceDir: string, sessionId: string, turnNumber: number) => {
+    turnCommitCalls.push({ workspaceDir, sessionId, turnNumber });
+    if (turnCommitHangForever) {
+      // Simulate a commit that never resolves within the timeout budget
+      await new Promise<void>(() => {});
+    }
+  };
+  return session;
+}
+
+/**
+ * Wait until the pending runs array has at least `count` entries.
+ * This is needed because `processMessage` is async and goes through
+ * several awaited steps (context compaction, memory recall) before
+ * reaching `agentLoop.run()`.
+ */
+async function waitForPendingRun(count: number, timeoutMs = 2000): Promise<void> {
+  const start = Date.now();
+  while (pendingRuns.length < count) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`Timed out waiting for ${count} pending runs (have ${pendingRuns.length})`);
+    }
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+async function waitForCondition(predicate: () => boolean, timeoutMs = 2000): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error('Timed out waiting for condition');
+    }
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+/**
+ * Resolve the Nth pending AgentLoop.run() call. Fires the minimal events
+ * that `runAgentLoop` expects (usage + message_complete) so the session
+ * cleanly transitions out of its processing state.
+ */
+function resolveRun(index: number) {
+  const run = pendingRuns[index];
+  if (!run) throw new Error(`No pending run at index ${index}`);
+  // Emit the events runAgentLoop expects
+  const assistantMsg: Message = {
+    role: 'assistant',
+    content: [{ type: 'text', text: `reply-${index}` }],
+  };
+  run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+  run.onEvent({ type: 'message_complete', message: assistantMsg });
+  // Return updated history with the assistant message appended
+  run.resolve([...run.messages, assistantMsg]);
+}
+
+beforeEach(() => {
+  turnCommitCalls.length = 0;
+  turnCommitHangForever = false;
+  linkAttachmentShouldThrow = false;
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Session message queue', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('second message is queued when session is busy (does not throw)', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events1: ServerMessage[] = [];
+    const events2: ServerMessage[] = [];
+
+    // Start first message — this will block on AgentLoop.run
+    const p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+
+    // Wait for the first AgentLoop.run to be registered
+    await waitForPendingRun(1);
+
+    // Session should now be processing
+    expect(session.isProcessing()).toBe(true);
+
+    // Enqueue second message — should NOT throw
+    const result = session.enqueueMessage('msg-2', [], (e) => events2.push(e), 'req-2');
+    expect(result.queued).toBe(true);
+    expect(result.requestId).toBe('req-2');
+    expect(session.getQueueDepth()).toBe(1);
+
+    // Complete the first message
+    resolveRun(0);
+    await p1;
+
+    // After the first run resolves, the queue drains and triggers a second run.
+    await waitForPendingRun(2);
+
+    // The dequeued event should have been sent to events2
+    expect(events2.some((e) => e.type === 'message_dequeued')).toBe(true);
+
+    // A second AgentLoop.run should now be pending
+    expect(pendingRuns.length).toBe(2);
+
+    // Complete the second run
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('[experimental] queued messages are processed in FIFO order', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const processedOrder: string[] = [];
+
+    const makeHandler = (label: string) => (e: ServerMessage) => {
+      if (e.type === 'message_complete') processedOrder.push(label);
+    };
+
+    // Start first message
+    const p1 = session.processMessage('msg-1', [], makeHandler('msg-1'), 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue two more
+    session.enqueueMessage('msg-2', [], makeHandler('msg-2'), 'req-2');
+    session.enqueueMessage('msg-3', [], makeHandler('msg-3'), 'req-3');
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Complete first → triggers second
+    resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    // Complete second → triggers third
+    resolveRun(1);
+    await waitForPendingRun(3);
+
+    // Complete third
+    resolveRun(2);
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(processedOrder).toEqual(['msg-1', 'msg-2', 'msg-3']);
+  });
+
+  test('message_queued and message_dequeued events are emitted', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events2: ServerMessage[] = [];
+
+    // Start first message
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue second — simulating what handleUserMessage does
+    const result = session.enqueueMessage('msg-2', [], (e) => events2.push(e), 'req-2');
+    expect(result.queued).toBe(true);
+
+    // Complete first
+    resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    // Check for message_dequeued with correct fields
+    const dequeued = events2.find((e) => e.type === 'message_dequeued');
+    expect(dequeued).toBeDefined();
+    expect(dequeued).toEqual({
+      type: 'message_dequeued',
+      sessionId: 'conv-1',
+      requestId: 'req-2',
+    });
+
+    // Complete second run so the session finishes cleanly
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('abort() clears the queue and sends generation_cancelled for each queued message', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events2: ServerMessage[] = [];
+    const events3: ServerMessage[] = [];
+
+    // Start first message
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue two more
+    session.enqueueMessage('msg-2', [], (e) => events2.push(e), 'req-2');
+    session.enqueueMessage('msg-3', [], (e) => events3.push(e), 'req-3');
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Abort
+    session.abort();
+
+    // Queue should be empty
+    expect(session.getQueueDepth()).toBe(0);
+
+    // Both queued messages should receive session-scoped cancellation events.
+    const cancel2 = events2.find((e) => e.type === 'generation_cancelled');
+    expect(cancel2).toEqual({ type: 'generation_cancelled', sessionId: 'conv-1' });
+
+    const cancel3 = events3.find((e) => e.type === 'generation_cancelled');
+    expect(cancel3).toEqual({ type: 'generation_cancelled', sessionId: 'conv-1' });
+
+    // abort() must NOT emit session_error or generic error for queued discards.
+    const err2 = events2.find((e) => e.type === 'error');
+    expect(err2).toBeUndefined();
+    const err3 = events3.find((e) => e.type === 'error');
+    expect(err3).toBeUndefined();
+
+    const sessionErr2 = events2.find((e) => e.type === 'session_error');
+    expect(sessionErr2).toBeUndefined();
+
+    const sessionErr3 = events3.find((e) => e.type === 'session_error');
+    expect(sessionErr3).toBeUndefined();
+  });
+
+  test('session-scoped errors emit both session_error and generic error', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events: ServerMessage[] = [];
+
+    // Start a message — blocks on AgentLoop.run
+    const p1 = session.processMessage('msg-1', [], (e) => events.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Reject the AgentLoop.run() with a provider error to trigger the
+    // runAgentLoop catch block
+    pendingRuns[0].reject(new Error('Provider returned 500'));
+    await p1;
+
+    // Should emit session_error (typed, structured)
+    const sessionErr = events.find((e) => e.type === 'session_error');
+    expect(sessionErr).toBeDefined();
+
+    // Should also emit generic error for backward compatibility
+    // (RunOrchestrator relies on error events to detect failures)
+    const genericErr = events.find((e) => e.type === 'error');
+    expect(genericErr).toBeDefined();
+  });
+
+  test('queue depth is reported correctly as messages are added and drained', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start first message
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    expect(session.getQueueDepth()).toBe(0);
+
+    session.enqueueMessage('msg-2', [], () => {}, 'req-2');
+    expect(session.getQueueDepth()).toBe(1);
+
+    session.enqueueMessage('msg-3', [], () => {}, 'req-3');
+    expect(session.getQueueDepth()).toBe(2);
+
+    session.enqueueMessage('msg-4', [], () => {}, 'req-4');
+    expect(session.getQueueDepth()).toBe(3);
+
+    // Complete first → drains one from queue
+    resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Complete second → drains another
+    resolveRun(1);
+    await waitForPendingRun(3);
+
+    expect(session.getQueueDepth()).toBe(1);
+
+    // Complete third → drains last
+    resolveRun(2);
+    await waitForPendingRun(4);
+
+    expect(session.getQueueDepth()).toBe(0);
+
+    // Complete fourth (final queued message)
+    resolveRun(3);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('[experimental] drain continues after a queued message fails to persist', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events1: ServerMessage[] = [];
+    const events2: ServerMessage[] = [];
+    const events3: ServerMessage[] = [];
+
+    // Start first message — blocks on AgentLoop.run
+    const p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue a message with empty content (will fail persistUserMessage)
+    session.enqueueMessage('', [], (e) => events2.push(e), 'req-2');
+    // Enqueue a valid message after the bad one
+    session.enqueueMessage('msg-3', [], (e) => events3.push(e), 'req-3');
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Complete first message — triggers drain. The empty message should fail
+    // to persist, but the drain should continue to msg-3.
+    resolveRun(0);
+    await p1;
+
+    // msg-3 should have been dequeued and started a new AgentLoop.run
+    await waitForPendingRun(2);
+
+    // The empty message should have received an error event
+    const err2 = events2.find((e) => e.type === 'error');
+    expect(err2).toBeDefined();
+    if (err2 && err2.type === 'error') {
+      expect(err2.message).toContain('required');
+    }
+
+    // msg-3 should have received a dequeued event
+    expect(events3.some((e) => e.type === 'message_dequeued')).toBe(true);
+
+    // Complete the third message's run
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+
+    // msg-3 should have completed successfully
+    expect(events3.some((e) => e.type === 'message_complete')).toBe(true);
+  });
+
+  test('queue rejects when at max depth', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start first message to make session busy
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Fill the queue to MAX_QUEUE_DEPTH
+    for (let i = 0; i < MAX_QUEUE_DEPTH; i++) {
+      const result = session.enqueueMessage(`msg-${i + 2}`, [], () => {}, `req-${i + 2}`);
+      expect(result.queued).toBe(true);
+      expect(result.rejected).toBeUndefined();
+    }
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+
+    // Next enqueue should be rejected
+    const rejected = session.enqueueMessage('overflow', [], () => {}, 'req-overflow');
+    expect(rejected.queued).toBe(false);
+    expect(rejected.rejected).toBe(true);
+
+    // Queue depth should not have increased
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Queue policy primitives
+// ---------------------------------------------------------------------------
+
+describe('Session queue policy helpers', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('hasQueuedMessages() returns false on a fresh session', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+    expect(session.hasQueuedMessages()).toBe(false);
+  });
+
+  test('hasQueuedMessages() returns true after enqueuing while processing', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing to make the session busy
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue a message while processing
+    session.enqueueMessage('msg-2', [], () => {}, 'req-2');
+    expect(session.hasQueuedMessages()).toBe(true);
+
+    // Cleanup: resolve the pending run
+    resolveRun(0);
+    await waitForPendingRun(2);
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('canHandoffAtCheckpoint() returns false when not processing', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Not processing, no queued messages
+    expect(session.canHandoffAtCheckpoint()).toBe(false);
+  });
+
+  test('canHandoffAtCheckpoint() returns false when processing but no queued messages', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing — but don't enqueue anything
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    expect(session.isProcessing()).toBe(true);
+    expect(session.hasQueuedMessages()).toBe(false);
+    expect(session.canHandoffAtCheckpoint()).toBe(false);
+
+    // Cleanup
+    resolveRun(0);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('canHandoffAtCheckpoint() returns true when processing and queue has messages', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue a message
+    session.enqueueMessage('msg-2', [], () => {}, 'req-2');
+
+    expect(session.isProcessing()).toBe(true);
+    expect(session.hasQueuedMessages()).toBe(true);
+    expect(session.canHandoffAtCheckpoint()).toBe(true);
+
+    // Cleanup
+    resolveRun(0);
+    await waitForPendingRun(2);
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('QueueDrainReason type accepts expected values', () => {
+    // Compile-time verification that these are valid QueueDrainReason values
+    const reason1: QueueDrainReason = 'loop_complete';
+    const reason2: QueueDrainReason = 'checkpoint_handoff';
+    expect(reason1).toBe('loop_complete');
+    expect(reason2).toBe('checkpoint_handoff');
+  });
+
+  test('QueuePolicy type accepts expected shape', () => {
+    // Compile-time verification that the QueuePolicy interface works
+    const policy: QueuePolicy = { checkpointHandoffEnabled: true };
+    expect(policy.checkpointHandoffEnabled).toBe(true);
+
+    const disabledPolicy: QueuePolicy = { checkpointHandoffEnabled: false };
+    expect(disabledPolicy.checkpointHandoffEnabled).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checkpoint handoff tests
+// ---------------------------------------------------------------------------
+
+describe('Session checkpoint handoff', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('[experimental] onCheckpoint yields when there is a queued message', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events1: ServerMessage[] = [];
+
+    // Start processing first message
+    const p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue a second message while the first is processing
+    session.enqueueMessage('msg-2', [], () => {}, 'req-2');
+    expect(session.hasQueuedMessages()).toBe(true);
+
+    // The pending run should have received an onCheckpoint callback.
+    // Simulate the agent loop calling it at a turn boundary.
+    const run = pendingRuns[0];
+    expect(run.onCheckpoint).toBeDefined();
+    const decision = run.onCheckpoint!({
+      turnIndex: 0,
+      toolCount: 1,
+      hasToolUse: true,
+    });
+
+    // Because there is a queued message, the callback should return 'yield'
+    expect(decision).toBe('yield');
+
+    // Complete the run so the session finishes cleanly
+    resolveRun(0);
+    await p1;
+
+    // After yield, the first message should emit generation_handoff
+    const handoff = events1.find((e) => e.type === 'generation_handoff');
+    expect(handoff).toBeDefined();
+    expect(handoff).toMatchObject({
+      type: 'generation_handoff',
+      sessionId: 'conv-1',
+      requestId: 'req-1',
+      queuedCount: 1,
+    });
+
+    // The queued message should now be draining (second run started)
+    await waitForPendingRun(2);
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('onCheckpoint returns continue when queue is empty', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing — no enqueued messages
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    expect(session.hasQueuedMessages()).toBe(false);
+
+    // The pending run should have an onCheckpoint callback
+    const run = pendingRuns[0];
+    expect(run.onCheckpoint).toBeDefined();
+    const decision = run.onCheckpoint!({
+      turnIndex: 0,
+      toolCount: 1,
+      hasToolUse: true,
+    });
+
+    // No queued messages → continue
+    expect(decision).toBe('continue');
+
+    // Cleanup
+    resolveRun(0);
+    await p1;
+  });
+
+  test('[experimental] FIFO ordering is preserved through checkpoint handoff', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const processedOrder: string[] = [];
+
+    const makeHandler = (label: string) => (e: ServerMessage) => {
+      if (e.type === 'message_complete' || e.type === 'generation_handoff') processedOrder.push(label);
+    };
+
+    // Start first message
+    const p1 = session.processMessage('msg-1', [], makeHandler('msg-1'), 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue two messages
+    session.enqueueMessage('msg-2', [], makeHandler('msg-2'), 'req-2');
+    session.enqueueMessage('msg-3', [], makeHandler('msg-3'), 'req-3');
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Simulate the agent loop yielding at the checkpoint (first run)
+    const run0 = pendingRuns[0];
+    expect(run0.onCheckpoint).toBeDefined();
+    const decision = run0.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true });
+    expect(decision).toBe('yield');
+
+    // Complete first run
+    resolveRun(0);
+    await p1;
+
+    // msg-2 should be draining next
+    await waitForPendingRun(2);
+
+    // Complete second run (msg-2)
+    resolveRun(1);
+    await waitForPendingRun(3);
+
+    // Complete third run (msg-3)
+    resolveRun(2);
+    await new Promise((r) => setTimeout(r, 50));
+
+    // FIFO order: msg-1 completes first, then msg-2, then msg-3
+    expect(processedOrder).toEqual(['msg-1', 'msg-2', 'msg-3']);
+  });
+
+  test('queue-full rejection still works during checkpoint handoff', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Fill the queue to MAX_QUEUE_DEPTH
+    for (let i = 0; i < MAX_QUEUE_DEPTH; i++) {
+      const result = session.enqueueMessage(`queued-${i}`, [], () => {}, `req-q-${i}`);
+      expect(result.queued).toBe(true);
+    }
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+
+    // Verify checkpoint would yield (there are queued messages)
+    const run = pendingRuns[0];
+    expect(run.onCheckpoint).toBeDefined();
+    expect(run.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('yield');
+
+    // Next enqueue should still be rejected
+    const rejected = session.enqueueMessage('overflow', [], () => {}, 'req-overflow');
+    expect(rejected.queued).toBe(false);
+    expect(rejected.rejected).toBe(true);
+
+    // Queue depth unchanged
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+  });
+
+  test('[experimental] active run with repeated tool turns + queued message triggers checkpoint handoff', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const events1: ServerMessage[] = [];
+    const events2: ServerMessage[] = [];
+
+    // Start processing first message
+    const p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue a second message while the first is processing
+    session.enqueueMessage('msg-2', [], (e) => events2.push(e), 'req-2');
+    expect(session.hasQueuedMessages()).toBe(true);
+
+    // Simulate tool-use turns: the agent loop calls onCheckpoint at each turn boundary.
+    // Because there is a queued message, the callback should return 'yield'.
+    const run = pendingRuns[0];
+    expect(run.onCheckpoint).toBeDefined();
+
+    // Simulate multiple tool-use turns before the checkpoint fires
+    // Turn 0 — checkpoint yields because msg-2 is waiting
+    const decision = run.onCheckpoint!({
+      turnIndex: 0,
+      toolCount: 1,
+      hasToolUse: true,
+    });
+    expect(decision).toBe('yield');
+
+    // Complete the run (AgentLoop resolves after yielding)
+    resolveRun(0);
+    await p1;
+
+    // Verify generation_handoff was emitted (not plain message_complete)
+    const handoff = events1.find((e) => e.type === 'generation_handoff');
+    expect(handoff).toBeDefined();
+    expect(handoff).toMatchObject({
+      type: 'generation_handoff',
+      sessionId: 'conv-1',
+      requestId: 'req-1',
+      queuedCount: 1,
+    });
+    // message_complete should NOT be in events1 (handoff replaces it)
+    const messageComplete = events1.find((e) => e.type === 'message_complete' && 'sessionId' in e);
+    expect(messageComplete).toBeUndefined();
+
+    // The queued message should subsequently drain
+    await waitForPendingRun(2);
+    expect(events2.some((e) => e.type === 'message_dequeued')).toBe(true);
+
+    // Complete the second run
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  test('queued messages still drain FIFO under multiple handoffs', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const dequeueOrder: string[] = [];
+
+    const eventsA: ServerMessage[] = [];
+    const makeHandler = (label: string) => (e: ServerMessage) => {
+      if (e.type === 'message_dequeued') dequeueOrder.push(label);
+    };
+
+    // Start processing message A
+    const pA = session.processMessage('msg-A', [], (e) => eventsA.push(e), 'req-A');
+    await waitForPendingRun(1);
+
+    // Enqueue messages B, C, D
+    session.enqueueMessage('msg-B', [], makeHandler('B'), 'req-B');
+    session.enqueueMessage('msg-C', [], makeHandler('C'), 'req-C');
+    session.enqueueMessage('msg-D', [], makeHandler('D'), 'req-D');
+    expect(session.getQueueDepth()).toBe(3);
+
+    // Handoff from A -> B
+    const runA = pendingRuns[0];
+    expect(runA.onCheckpoint).toBeDefined();
+    expect(runA.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('yield');
+    resolveRun(0);
+    await pA;
+
+    // B should be draining
+    await waitForPendingRun(2);
+
+    // Handoff from B -> C
+    const runB = pendingRuns[1];
+    expect(runB.onCheckpoint).toBeDefined();
+    expect(runB.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('yield');
+    resolveRun(1);
+    await waitForPendingRun(3);
+
+    // Handoff from C -> D
+    const runC = pendingRuns[2];
+    expect(runC.onCheckpoint).toBeDefined();
+    // Only D remains, still should yield
+    expect(runC.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('yield');
+    resolveRun(2);
+    await waitForPendingRun(4);
+
+    // D has no more queued -> checkpoint should return 'continue'
+    const runD = pendingRuns[3];
+    expect(runD.onCheckpoint).toBeDefined();
+    expect(runD.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('continue');
+
+    resolveRun(3);
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Verify FIFO dequeue order
+    expect(dequeueOrder).toEqual(['B', 'C', 'D']);
+  });
+
+  test('[experimental] queued persistence failure does not strand later messages', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const eventsA: ServerMessage[] = [];
+    const eventsB: ServerMessage[] = [];
+    const eventsC: ServerMessage[] = [];
+
+    // Start processing message A
+    const pA = session.processMessage('msg-A', [], (e) => eventsA.push(e), 'req-A');
+    await waitForPendingRun(1);
+
+    // Enqueue B (empty content — will fail to persist) and C (valid)
+    session.enqueueMessage('', [], (e) => eventsB.push(e), 'req-B');
+    session.enqueueMessage('msg-C', [], (e) => eventsC.push(e), 'req-C');
+    expect(session.getQueueDepth()).toBe(2);
+
+    // Complete message A — triggers drain. B should fail, C should proceed.
+    resolveRun(0);
+    await pA;
+
+    // C should have been dequeued and started a new AgentLoop.run
+    await waitForPendingRun(2);
+
+    // B should have received an error event
+    const errB = eventsB.find((e) => e.type === 'error');
+    expect(errB).toBeDefined();
+    if (errB && errB.type === 'error') {
+      expect(errB.message).toContain('required');
+    }
+
+    // C should have received a dequeued event
+    expect(eventsC.some((e) => e.type === 'message_dequeued')).toBe(true);
+
+    // Complete C's run
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+
+    // C should have completed successfully
+    expect(eventsC.some((e) => e.type === 'message_complete')).toBe(true);
+  });
+
+  test('onCheckpoint callback is passed to both initial and retry runs', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // The first run should have onCheckpoint
+    expect(pendingRuns[0].onCheckpoint).toBeDefined();
+
+    // Simulate an ordering error: emit error + resolve with same length
+    // to trigger the retry path
+    const run0 = pendingRuns[0];
+    run0.onEvent({
+      type: 'error',
+      error: new Error('tool_result block not immediately after tool_use block'),
+    });
+    // Resolve with the same messages (no new messages appended = ordering error)
+    run0.resolve([...run0.messages]);
+
+    // Wait for the retry run
+    await waitForPendingRun(2);
+
+    // The retry run should also have onCheckpoint
+    expect(pendingRuns[1].onCheckpoint).toBeDefined();
+
+    // Complete retry cleanly
+    resolveRun(1);
+    await p1;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Usage requestId correlation
+// ---------------------------------------------------------------------------
+
+describe('Session usage requestId correlation', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+    capturedUsageEvents = [];
+  });
+
+  test('usage events recorded during a request carry that request ID', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-42');
+    await waitForPendingRun(1);
+
+    // Complete the run — this triggers recordUsage with the request's ID
+    resolveRun(0);
+    await p1;
+
+    // The usage event should carry the request ID, not null
+    const mainAgentUsage = capturedUsageEvents.find((e) => e.actor === 'main_agent');
+    expect(mainAgentUsage).toBeDefined();
+    expect(mainAgentUsage!.requestId).toBe('req-42');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Terminal trace events on rejection/failure paths
+// ---------------------------------------------------------------------------
+
+describe('Terminal trace events on rejection/failure', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('queued persist failure emits request_error trace', async () => {
+    const traceEvents: ServerMessage[] = [];
+    const session = makeSession((msg) => {
+      if ('type' in msg && msg.type === 'trace_event') traceEvents.push(msg);
+    });
+    await session.loadFromDb();
+
+    // Start first message
+    const p1 = session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Enqueue empty content (will fail persistUserMessage)
+    session.enqueueMessage('', [], () => {}, 'req-bad');
+    // Enqueue valid message so drain continues
+    session.enqueueMessage('msg-3', [], () => {}, 'req-3');
+
+    // Complete first — triggers drain, empty msg fails persist
+    resolveRun(0);
+    await p1;
+    await waitForPendingRun(2);
+
+    // Should have a request_error trace for the failed persist
+    const errorTrace = traceEvents.find(
+      (e) => 'kind' in e && e.kind === 'request_error' && 'requestId' in e && e.requestId === 'req-bad',
+    );
+    expect(errorTrace).toBeDefined();
+
+    // Cleanup
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Surface-action queue-full trace emission
+// ---------------------------------------------------------------------------
+
+describe('Surface-action queue-full trace', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('surface-action queue-full rejection emits request_error trace', async () => {
+    const traceEvents: ServerMessage[] = [];
+    const session = makeSession((msg) => {
+      if ('type' in msg && msg.type === 'trace_event') traceEvents.push(msg);
+    });
+    await session.loadFromDb();
+
+    // Start processing to make the session busy
+    session.processMessage('msg-1', [], () => {}, 'req-1');
+    await waitForPendingRun(1);
+
+    // Fill the queue to MAX_QUEUE_DEPTH
+    for (let i = 0; i < MAX_QUEUE_DEPTH; i++) {
+      const result = session.enqueueMessage(`queued-${i}`, [], () => {}, `req-q-${i}`);
+      expect(result.queued).toBe(true);
+    }
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+
+    // Register a pending surface action so handleSurfaceAction doesn't bail early
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- access private property for testing
+    (session as any).pendingSurfaceActions.set('surf-1', { surfaceType: 'confirmation' });
+
+    // Trigger the surface action — queue is full, should be rejected
+    session.handleSurfaceAction('surf-1', 'confirm');
+
+    // Should have a request_received trace followed by a request_error trace
+    const receivedTrace = traceEvents.find(
+      (e) => 'kind' in e && e.kind === 'request_received',
+    );
+    expect(receivedTrace).toBeDefined();
+
+    const errorTrace = traceEvents.find(
+      (e) => 'kind' in e && e.kind === 'request_error',
+    );
+    expect(errorTrace).toBeDefined();
+    expect(errorTrace).toHaveProperty('attributes');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- access trace attributes
+    const attrs = (errorTrace as any).attributes;
+    expect(attrs.reason).toBe('queue_full');
+    expect(attrs.source).toBe('surface_action');
+
+    // Queue depth should not have increased
+    expect(session.getQueueDepth()).toBe(MAX_QUEUE_DEPTH);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Host attachment approval tests
+// ---------------------------------------------------------------------------
+
+describe('Session host attachment directives', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('host attachment prompts and resolves when user allows', async () => {
+    const hostPath = '/tmp/vellum-host-attachment-allow.txt';
+    writeFileSync(hostPath, 'host attachment content');
+
+    try {
+      const clientEvents: ServerMessage[] = [];
+      const events: ServerMessage[] = [];
+      const session = makeSession((msg) => clientEvents.push(msg));
+      await session.loadFromDb();
+
+      const p1 = session.processMessage('msg-1', [], (e) => events.push(e), 'req-1');
+      await waitForPendingRun(1);
+
+      const run = pendingRuns[0];
+      const assistantMsg: Message = {
+        role: 'assistant',
+        content: [
+          {
+            type: 'text',
+            text: `Here is your file.\n<vellum-attachment source="host" path="${hostPath}" />`,
+          },
+        ],
+      };
+      run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+      run.onEvent({ type: 'message_complete', message: assistantMsg });
+      run.resolve([...run.messages, assistantMsg]);
+
+      await waitForCondition(() => clientEvents.some((e) => e.type === 'confirmation_request'));
+      const confirmation = clientEvents.find((e) => e.type === 'confirmation_request');
+      expect(confirmation).toBeDefined();
+      session.handleConfirmationResponse((confirmation as { requestId: string }).requestId, 'allow');
+
+      await p1;
+
+      expect(session.lastAssistantAttachments).toHaveLength(1);
+      expect(session.lastAssistantAttachments[0].sourceType).toBe('host_file');
+      expect(session.lastAttachmentWarnings).toHaveLength(0);
+
+      const completion = events.find((e) => e.type === 'message_complete');
+      expect(completion).toBeDefined();
+    } finally {
+      rmSync(hostPath, { force: true });
+    }
+  });
+
+  test('host attachment denial is non-fatal and emits warning text', async () => {
+    const hostPath = '/tmp/vellum-host-attachment-deny.txt';
+    writeFileSync(hostPath, 'host attachment content');
+
+    try {
+      const clientEvents: ServerMessage[] = [];
+      const events: ServerMessage[] = [];
+      const session = makeSession((msg) => clientEvents.push(msg));
+      await session.loadFromDb();
+
+      const p1 = session.processMessage('msg-1', [], (e) => events.push(e), 'req-1');
+      await waitForPendingRun(1);
+
+      const run = pendingRuns[0];
+      const assistantMsg: Message = {
+        role: 'assistant',
+        content: [
+          {
+            type: 'text',
+            text: `Here is your file.\n<vellum-attachment source="host" path="${hostPath}" />`,
+          },
+        ],
+      };
+      run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+      run.onEvent({ type: 'message_complete', message: assistantMsg });
+      run.resolve([...run.messages, assistantMsg]);
+
+      await waitForCondition(() => clientEvents.some((e) => e.type === 'confirmation_request'));
+      const confirmation = clientEvents.find((e) => e.type === 'confirmation_request');
+      expect(confirmation).toBeDefined();
+      session.handleConfirmationResponse((confirmation as { requestId: string }).requestId, 'deny');
+
+      await p1;
+
+      expect(session.lastAssistantAttachments).toHaveLength(0);
+      expect(session.lastAttachmentWarnings.some((w) => w.includes('access denied by user'))).toBe(true);
+
+      const warningDelta = events.find(
+        (e) => e.type === 'assistant_text_delta' && e.text.includes('Attachment warning:'),
+      );
+      expect(warningDelta).toBeDefined();
+      const completion = events.find((e) => e.type === 'message_complete');
+      expect(completion).toBeDefined();
+    } finally {
+      rmSync(hostPath, { force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attachment payload emission tests
+// ---------------------------------------------------------------------------
+
+describe('Session attachment event payloads', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('message_complete includes assistant attachments', async () => {
+    const events: ServerMessage[] = [];
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const p1 = session.processMessage('msg-1', [], (e) => events.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    const run = pendingRuns[0];
+    const assistantMsg: Message = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'Here is your chart.' }],
+    };
+    run.onEvent({
+      type: 'tool_result',
+      toolUseId: 'tool-1',
+      content: 'ok',
+      isError: false,
+      contentBlocks: [
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mock content block
+        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'iVBORw0K' } } as any,
+      ],
+    });
+    run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+    run.onEvent({ type: 'message_complete', message: assistantMsg });
+    run.resolve([...run.messages, assistantMsg]);
+
+    await p1;
+
+    const completion = events.find((e) => e.type === 'message_complete' && Array.isArray(e.attachments));
+    expect(completion).toBeDefined();
+    const attachments = (completion as { attachments: Array<{ mimeType: string; data: string; id?: string }> }).attachments;
+    expect(attachments).toHaveLength(1);
+    expect(attachments[0].mimeType).toBe('image/png');
+    expect(attachments[0].data).toBe('iVBORw0K');
+    expect(attachments[0].id).toBeDefined();
+  });
+
+  test('generation_handoff includes assistant attachments', async () => {
+    const events1: ServerMessage[] = [];
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Queue a second message so the first run yields via checkpoint handoff.
+    session.enqueueMessage('msg-2', [], () => {}, 'req-2');
+
+    const run = pendingRuns[0];
+    expect(run.onCheckpoint).toBeDefined();
+    expect(run.onCheckpoint!({ turnIndex: 0, toolCount: 1, hasToolUse: true })).toBe('yield');
+
+    const assistantMsg: Message = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'Handing off with attachment.' }],
+    };
+    run.onEvent({
+      type: 'tool_result',
+      toolUseId: 'tool-1',
+      content: 'ok',
+      isError: false,
+      contentBlocks: [
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mock content block
+        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'iVBORw0K' } } as any,
+      ],
+    });
+    run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+    run.onEvent({ type: 'message_complete', message: assistantMsg });
+    run.resolve([...run.messages, assistantMsg]);
+
+    await p1;
+
+    const handoff = events1.find((e) => e.type === 'generation_handoff' && Array.isArray(e.attachments));
+    expect(handoff).toBeDefined();
+    const attachments = (handoff as { attachments: Array<{ mimeType: string; data: string; id?: string }> }).attachments;
+    expect(attachments).toHaveLength(1);
+    expect(attachments[0].mimeType).toBe('image/png');
+    expect(attachments[0].data).toBe('iVBORw0K');
+
+    await waitForPendingRun(2);
+    resolveRun(1);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Regression: cancel semantics + session/global error channel split
+// ---------------------------------------------------------------------------
+
+describe('Regression: cancel semantics and error channel split', () => {
+  beforeEach(() => {
+    pendingRuns = [];
+  });
+
+  test('user cancellation emits generation_cancelled, never session_error', async () => {
+    const msgEvents: ServerMessage[] = [];
+    const session = makeSession();
+    await session.loadFromDb();
+
+    // Start processing a message — collect events from the per-message callback
+    const p1 = session.processMessage('msg-1', [], (e) => msgEvents.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // User cancels — sets the abort signal
+    session.abort();
+
+    // Resolve the pending run so the abort-check path fires
+    resolveRun(0);
+    await p1;
+
+    // generation_cancelled should be emitted via the per-message callback
+    const cancelEvent = msgEvents.find((e) => e.type === 'generation_cancelled');
+    expect(cancelEvent).toBeDefined();
+
+    // session_error must never appear on cancel
+    const sessionErr = msgEvents.find((e) => e.type === 'session_error');
+    expect(sessionErr).toBeUndefined();
+  });
+
+  test('post-processing failure still attempts turn-boundary commit', async () => {
+    const events: ServerMessage[] = [];
+    const session = makeSession();
+    await session.loadFromDb();
+    linkAttachmentShouldThrow = true;
+
+    const p1 = session.processMessage('msg-1', [], (e) => events.push(e), 'req-1');
+    await waitForPendingRun(1);
+    const run = pendingRuns[0];
+    const assistantMsg: Message = {
+      role: 'assistant',
+      content: [{ type: 'text', text: 'attachment-trigger' }],
+    };
+    run.onEvent({
+      type: 'tool_result',
+      toolUseId: 'tool-1',
+      content: 'ok',
+      isError: false,
+      contentBlocks: [
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mock content block
+        { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'iVBORw0K' } } as any,
+      ],
+    });
+    run.onEvent({ type: 'usage', inputTokens: 10, outputTokens: 5, model: 'mock', providerDurationMs: 100 });
+    run.onEvent({ type: 'message_complete', message: assistantMsg });
+    run.resolve([...run.messages, assistantMsg]);
+    await p1;
+
+    expect(turnCommitCalls).toHaveLength(1);
+    expect(turnCommitCalls[0]).toEqual({
+      workspaceDir: '/tmp',
+      sessionId: 'conv-1',
+      turnNumber: 1,
+    });
+    const err = events.find((e) => e.type === 'error');
+    expect(err).toBeDefined();
+  });
+
+  test('provider failure during processing emits both session_error and generic error', async () => {
+    const allEvents: ServerMessage[] = [];
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const p1 = session.processMessage('msg-1', [], (e) => allEvents.push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    // Simulate a provider failure
+    pendingRuns[0].reject(new Error('Connection refused'));
+    await p1;
+
+    // Should get session_error (structured)
+    const sessionErr = allEvents.find((e) => e.type === 'session_error');
+    expect(sessionErr).toBeDefined();
+
+    // Should also get generic error for backward compatibility
+    const genericErr = allEvents.find((e) => e.type === 'error');
+    expect(genericErr).toBeDefined();
+  });
+
+  test('cancel after queued messages produces no session_error for any queued entry', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    const eventsPerMsg: ServerMessage[][] = [[], [], []];
+
+    session.processMessage('msg-1', [], (e) => eventsPerMsg[0].push(e), 'req-1');
+    await waitForPendingRun(1);
+
+    session.enqueueMessage('msg-2', [], (e) => eventsPerMsg[1].push(e), 'req-2');
+    session.enqueueMessage('msg-3', [], (e) => eventsPerMsg[2].push(e), 'req-3');
+
+    session.abort();
+
+    // No queued message should have received session_error
+    for (const events of eventsPerMsg) {
+      const sessionErr = events.find((e) => e.type === 'session_error');
+      expect(sessionErr).toBeUndefined();
+    }
+  });
+
+  test('commitTurnChanges never resolving within budget -> turn still completes and drains queue', async () => {
+    const session = makeSession();
+    await session.loadFromDb();
+
+    turnCommitHangForever = true;
+
+    try {
+      const events1: ServerMessage[] = [];
+      const events2: ServerMessage[] = [];
+
+      // Start first message (promise intentionally not awaited — we test queue drain behavior)
+      const _p1 = session.processMessage('msg-1', [], (e) => events1.push(e), 'req-1');
+      await waitForPendingRun(1);
+
+      // Enqueue a second message while the first is processing
+      session.enqueueMessage('msg-2', [], (e) => events2.push(e), 'req-2');
+
+      // Complete the first agent loop run
+      resolveRun(0);
+
+      // The turn should still complete (timeout fires) and drain the queue
+      // even though commitTurnChanges never resolves.
+      // The default turnCommitMaxWaitMs is 4000ms in the config mock,
+      // but the mock config doesn't set it, so it defaults to 4000ms.
+      // We wait for the second run to be registered, which proves the
+      // turn completed and the queue drained despite the hanging commit.
+      await waitForPendingRun(2, 10_000);
+
+      // First message should have completed
+      const completion1 = events1.find((e) => e.type === 'message_complete');
+      expect(completion1).toBeDefined();
+
+      // Second message should have been dequeued
+      const dequeued = events2.find((e) => e.type === 'message_dequeued');
+      expect(dequeued).toBeDefined();
+
+      // The turn commit should have been called
+      expect(turnCommitCalls).toHaveLength(1);
+
+      // Complete the second run so the test can clean up
+      turnCommitHangForever = false;
+      resolveRun(1);
+      await new Promise((r) => setTimeout(r, 50));
+    } finally {
+      turnCommitHangForever = false;
+    }
+  }, 15_000);
+});