switchroom 0.14.19 → 0.14.20

package/telegram-plugin/tests/coalesce-attachments.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Unit tests for the A2 multi-attachment helpers
+ * (telegram-plugin/gateway/coalesce-attachments.ts).
+ *
+ * These pin the two pure pieces of the multi-attachment fold-in that live
+ * outside gateway.ts so they can be exercised without loadAccess()/IPC:
+ *   1. splitCoalescedAttachments — primary + capped extras, arrival order.
+ *   2. buildExtraAttachmentMeta — numbered meta fields starting at _2.
+ *
+ * The default cap (1) MUST reproduce the historical single-attachment shape:
+ * primary only, no extras, no numbered meta.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  splitCoalescedAttachments,
+  buildExtraAttachmentMeta,
+  type ResolvedExtraAttachment,
+} from '../gateway/coalesce-attachments.js'
+
+interface Entry {
+  text: string
+  att?: string
+}
+
+const has = (e: Entry): boolean => e.att != null
+
+describe('splitCoalescedAttachments', () => {
+  it('default cap 1: keeps only the first attachment as primary, no extras', () => {
+    const entries: Entry[] = [
+      { text: 'a', att: 'photo-1' },
+      { text: 'b', att: 'photo-2' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 1)
+    expect(primary).toEqual({ text: 'a', att: 'photo-1' })
+    expect(extras).toEqual([])
+  })
+
+  it('picks the FIRST attachment-bearing entry as primary even when text-only entries precede it', () => {
+    const entries: Entry[] = [
+      { text: 'look' },
+      { text: 'at this', att: 'photo-1' },
+      { text: 'and this', att: 'photo-2' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 3)
+    expect(primary?.att).toBe('photo-1')
+    expect(extras.map((e) => e.att)).toEqual(['photo-2'])
+  })
+
+  it('preserves arrival order of extras', () => {
+    const entries: Entry[] = [
+      { text: '1', att: 'a' },
+      { text: '2', att: 'b' },
+      { text: '3', att: 'c' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 5)
+    expect(primary?.att).toBe('a')
+    expect(extras.map((e) => e.att)).toEqual(['b', 'c'])
+  })
+
+  it('caps extras at maxAttachments (overflow dropped here; bypassed upstream)', () => {
+    const entries: Entry[] = [
+      { text: '1', att: 'a' },
+      { text: '2', att: 'b' },
+      { text: '3', att: 'c' },
+      { text: '4', att: 'd' },
+    ]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 2)
+    expect(primary?.att).toBe('a')
+    expect(extras.map((e) => e.att)).toEqual(['b']) // total = cap of 2
+  })
+
+  it('returns undefined primary when no entry carries an attachment', () => {
+    const entries: Entry[] = [{ text: 'just' }, { text: 'text' }]
+    const { primary, extras } = splitCoalescedAttachments(entries, has, 3)
+    expect(primary).toBeUndefined()
+    expect(extras).toEqual([])
+  })
+
+  it('floors a cap of 0 / negative at 1 so the only attachment is never stripped', () => {
+    const entries: Entry[] = [{ text: '1', att: 'a' }, { text: '2', att: 'b' }]
+    expect(splitCoalescedAttachments(entries, has, 0).primary?.att).toBe('a')
+    expect(splitCoalescedAttachments(entries, has, -5).primary?.att).toBe('a')
+    expect(splitCoalescedAttachments(entries, has, 0).extras).toEqual([])
+  })
+})
+
+describe('buildExtraAttachmentMeta', () => {
+  it('returns an empty object for no extras (default single-attachment turn)', () => {
+    expect(buildExtraAttachmentMeta([])).toEqual({})
+  })
+
+  it('numbers a single photo extra as _2', () => {
+    const resolved: ResolvedExtraAttachment[] = [{ imagePath: '/inbox/p2.jpg' }]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({ image_path_2: '/inbox/p2.jpg' })
+  })
+
+  it('numbers multiple extras incrementally from _2', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { imagePath: '/inbox/p2.jpg' },
+      { imagePath: '/inbox/p3.jpg' },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      image_path_2: '/inbox/p2.jpg',
+      image_path_3: '/inbox/p3.jpg',
+    })
+  })
+
+  it('emits full attachment metadata fields for a document extra', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      {
+        attachment: {
+          kind: 'document',
+          file_id: 'FID2',
+          size: 1234,
+          mime: 'application/pdf',
+          name: 'spec.pdf',
+        },
+      },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      attachment_kind_2: 'document',
+      attachment_file_id_2: 'FID2',
+      attachment_size_2: '1234',
+      attachment_mime_2: 'application/pdf',
+      attachment_name_2: 'spec.pdf',
+    })
+  })
+
+  it('omits optional metadata fields that are absent', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { attachment: { kind: 'voice', file_id: 'FID2' } },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      attachment_kind_2: 'voice',
+      attachment_file_id_2: 'FID2',
+    })
+  })
+
+  it('handles a mix of photo and document extras with correct numbering', () => {
+    const resolved: ResolvedExtraAttachment[] = [
+      { imagePath: '/inbox/p2.jpg' },
+      { attachment: { kind: 'document', file_id: 'FID3', mime: 'text/plain' } },
+    ]
+    expect(buildExtraAttachmentMeta(resolved)).toEqual({
+      image_path_2: '/inbox/p2.jpg',
+      attachment_kind_3: 'document',
+      attachment_file_id_3: 'FID3',
+      attachment_mime_3: 'text/plain',
+    })
+  })
+})

package/telegram-plugin/tests/interrupt-defer.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the deferred safe-boundary interrupt core (Problem B).
+ *
+ * The gateway-side wiring (timer, SIGINT-via-tmux, sendToAgent resume,
+ * coalescing) is exercised by integration; these pin the pure decision:
+ *   - ToolFlightTracker correctly tracks open tool calls by toolUseId and
+ *     clears on turn_end / a fresh enqueue.
+ *   - decideInterruptTiming returns fire-now unless the flag is on AND a tool
+ *     is in flight.
+ *   - resolveInterruptMaxWaitMs never yields a non-positive / forever wait.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  ToolFlightTracker,
+  decideInterruptTiming,
+  resolveInterruptMaxWaitMs,
+  DEFAULT_INTERRUPT_MAX_WAIT_MS,
+} from '../gateway/interrupt-defer.js'
+
+describe('ToolFlightTracker', () => {
+  it('starts at a safe boundary (no tools in flight)', () => {
+    const t = new ToolFlightTracker()
+    expect(t.isMidToolCall()).toBe(false)
+    expect(t.inFlightCount()).toBe(0)
+  })
+
+  it('a tool_use opens an unsafe boundary; its tool_result closes it', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    expect(t.isMidToolCall()).toBe(true)
+    t.onEvent({ kind: 'tool_result', toolUseId: 'tu_1' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('stays unsafe while ANY of several parallel tools is open', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'a' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'b' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'c' })
+    expect(t.inFlightCount()).toBe(3)
+    t.onEvent({ kind: 'tool_result', toolUseId: 'b' })
+    t.onEvent({ kind: 'tool_result', toolUseId: 'a' })
+    expect(t.isMidToolCall()).toBe(true) // c still open
+    t.onEvent({ kind: 'tool_result', toolUseId: 'c' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('turn_end clears any residual in-flight tools', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_2' })
+    t.onEvent({ kind: 'turn_end' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('a fresh enqueue clears the slate (new turn starts clean)', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.onEvent({ kind: 'enqueue' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('ignores sub-agent and non-tool events', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'sub_agent_tool_use', toolUseId: 'sub_1' })
+    t.onEvent({ kind: 'thinking' })
+    t.onEvent({ kind: 'text' })
+    t.onEvent({ kind: 'tool_label', toolUseId: 'tu_x' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('ignores tool_use with a missing / empty toolUseId', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use' })
+    t.onEvent({ kind: 'tool_use', toolUseId: null })
+    t.onEvent({ kind: 'tool_use', toolUseId: '' })
+    expect(t.isMidToolCall()).toBe(false)
+  })
+
+  it('tool_result for an unknown id is a harmless no-op', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'real' })
+    t.onEvent({ kind: 'tool_result', toolUseId: 'never-opened' })
+    expect(t.isMidToolCall()).toBe(true) // 'real' still open
+  })
+
+  it('clear() resets the tracker', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'tu_1' })
+    t.clear()
+    expect(t.isMidToolCall()).toBe(false)
+  })
+})
+
+describe('decideInterruptTiming', () => {
+  it('fires now when the flag is off, even mid-tool-call', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: false, midToolCall: true }),
+    ).toBe('fire-now')
+  })
+
+  it('fires now when the flag is on but no tool is in flight', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: false }),
+    ).toBe('fire-now')
+  })
+
+  it('defers only when the flag is on AND a tool is in flight', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: true }),
+    ).toBe('defer')
+  })
+
+  it('fires now in the fully-off case', () => {
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: false, midToolCall: false }),
+    ).toBe('fire-now')
+  })
+})
+
+describe('resolveInterruptMaxWaitMs', () => {
+  it('uses the configured value when positive', () => {
+    expect(resolveInterruptMaxWaitMs(3000)).toBe(3000)
+  })
+
+  it('falls back to the default when undefined', () => {
+    expect(resolveInterruptMaxWaitMs(undefined)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+  })
+
+  it('never returns a non-positive wait (no forever-wait)', () => {
+    expect(resolveInterruptMaxWaitMs(0)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+    expect(resolveInterruptMaxWaitMs(-1)).toBe(DEFAULT_INTERRUPT_MAX_WAIT_MS)
+  })
+
+  it('models the lifecycle: open tool → defer; tool_result → safe → fire', () => {
+    const t = new ToolFlightTracker()
+    t.onEvent({ kind: 'tool_use', toolUseId: 'w1' })
+    // `!` lands here, flag on:
+    expect(
+      decideInterruptTiming({ safeBoundaryEnabled: true, midToolCall: t.isMidToolCall() }),
+    ).toBe('defer')
+    // tool completes:
+    t.onEvent({ kind: 'tool_result', toolUseId: 'w1' })
+    expect(t.isMidToolCall()).toBe(false) // gateway fires the parked interrupt here
+  })
+})

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -450,6 +450,42 @@ describe('planBufferedRedelivery — merge-on-drain (forwarded-burst across a tu
     expect(plan[0]!.merged.imagePath).toBe('/tmp/p.jpg')
   })
 
+  it('splices attachment meta from the media entry when it is NOT the anchor (A2 numbered fields survive)', () => {
+    // A coalesced multi-attachment message buffered, then a text-only
+    // follow-up. mergeRun anchors on `last` (the text), whose meta has no
+    // attachment fields — so the owning entry's image_path + numbered
+    // siblings + attachment_count must be spliced into the merged meta or
+    // the agent would never see the photos.
+    const photo = userMsg({ text: 'look', ts: 1, imagePath: '/tmp/a.jpg' })
+    photo.meta = {
+      image_path: '/tmp/a.jpg',
+      image_path_2: '/tmp/b.jpg',
+      attachment_count: '2',
+      user: 'alice',
+    }
+    const txt = userMsg({ text: 'at these', ts: 2 })
+    txt.meta = { user: 'alice' }
+    const plan = planBufferedRedelivery([photo, txt])
+    expect(plan).toHaveLength(1)
+    const meta = plan[0]!.merged.meta
+    expect(meta.image_path).toBe('/tmp/a.jpg')
+    expect(meta.image_path_2).toBe('/tmp/b.jpg')
+    expect(meta.attachment_count).toBe('2')
+    // Top-level primary still re-seated for inboundHasMedia detection.
+    expect(plan[0]!.merged.imagePath).toBe('/tmp/a.jpg')
+  })
+
+  it('does not need a meta splice when the media entry IS the anchor', () => {
+    const txt = userMsg({ text: 'intro', ts: 1 })
+    txt.meta = { user: 'alice' }
+    const photo = userMsg({ text: 'pic', ts: 2, imagePath: '/tmp/p.jpg' })
+    photo.meta = { image_path: '/tmp/p.jpg', user: 'alice' }
+    const plan = planBufferedRedelivery([txt, photo])
+    expect(plan).toHaveLength(1)
+    // Anchor is the photo, so its meta is inherited verbatim.
+    expect(plan[0]!.merged.meta.image_path).toBe('/tmp/p.jpg')
+  })
+
   it('preserves the run total — sum of originals equals input length (lossless)', () => {
     const msgs = [
       userMsg({ text: 'a', ts: 1 }),

package/telegram-plugin/tests/worker-activity-feed.test.ts

@@ -92,6 +92,42 @@ describe('renderWorkerActivity', () => {
     expect(out).toContain('⚠️ <b>Worker failed</b>')
   })
 
+  it('grows a narrative block when narrativeLines is present', () => {
+    const out = renderWorkerActivity(
+      view({
+        latestSummary: 'newest only — should be ignored',
+        narrativeLines: ['read the brief', 'scanned vendor A', 'scanned vendor B'],
+      }),
+    )
+    expect(out).toContain('↳ <i>read the brief</i>')
+    expect(out).toContain('↳ <i>scanned vendor A</i>')
+    expect(out).toContain('↳ <i>scanned vendor B</i>')
+    // The single-line latestSummary fallback is NOT used when a block is present.
+    expect(out).not.toContain('newest only')
+    // Three narrative lines → three ↳ lines.
+    expect(out.match(/↳/g) ?? []).toHaveLength(3)
+  })
+
+  it('falls back to latestSummary when narrativeLines is empty', () => {
+    const out = renderWorkerActivity(view({ narrativeLines: [], latestSummary: 'one line' }))
+    expect(out).toContain('↳ <i>one line</i>')
+    expect(out.match(/↳/g) ?? []).toHaveLength(1)
+  })
+
+  it('drops blank narrative lines from the block', () => {
+    const out = renderWorkerActivity(
+      view({ narrativeLines: ['kept', '   ', 'also kept'] }),
+    )
+    expect(out).toContain('↳ <i>kept</i>')
+    expect(out).toContain('↳ <i>also kept</i>')
+    expect(out.match(/↳/g) ?? []).toHaveLength(2)
+  })
+
+  it('escapes HTML inside narrative lines', () => {
+    const out = renderWorkerActivity(view({ narrativeLines: ['a <b>x</b> & y'] }))
+    expect(out).toContain('a &lt;b&gt;x&lt;/b&gt; &amp; y')
+  })
+
   it('escapes HTML in description, tool, arg, and summary', () => {
     const out = renderWorkerActivity(
       view({
@@ -246,6 +282,83 @@ describe('createWorkerActivityFeed', () => {
     expect(feed.size).toBe(0)
   })
 
+  it('accumulates distinct narrative lines into a growing block across ticks', async () => {
+    const bot = makeFakeBot()
+    let clock = 10_000
+    const feed = createWorkerActivityFeed({ bot, now: () => clock, minEditIntervalMs: 0 })
+
+    await feed.update('w1', 'chat', view({ toolCount: 1, latestSummary: 'read the brief' }))
+    expect(bot.sent).toHaveLength(1)
+    expect(bot.sent[0].text).toContain('↳ <i>read the brief</i>')
+
+    clock = 11_000
+    await feed.update('w1', 'chat', view({ toolCount: 2, latestSummary: 'scanned vendor A' }))
+    clock = 12_000
+    await feed.update('w1', 'chat', view({ toolCount: 3, latestSummary: 'scanned vendor B' }))
+
+    const last = bot.edits.at(-1)!
+    expect(last.text).toContain('↳ <i>read the brief</i>')
+    expect(last.text).toContain('↳ <i>scanned vendor A</i>')
+    expect(last.text).toContain('↳ <i>scanned vendor B</i>')
+    expect(last.text.match(/↳/g) ?? []).toHaveLength(3)
+  })
+
+  it('dedups a repeated narrative line so the block does not duplicate', async () => {
+    const bot = makeFakeBot()
+    let clock = 10_000
+    const feed = createWorkerActivityFeed({ bot, now: () => clock, minEditIntervalMs: 0 })
+
+    await feed.update('w1', 'chat', view({ toolCount: 1, latestSummary: 'same line' }))
+    // Repeated narrative but a changed tool count → body differs, edit fires,
+    // but the narrative block must not gain a duplicate line.
+    clock = 11_000
+    await feed.update('w1', 'chat', view({ toolCount: 2, latestSummary: 'same line' }))
+
+    const last = bot.edits.at(-1)!
+    expect(last.text.match(/↳/g) ?? []).toHaveLength(1)
+  })
+
+  it('caps the narrative block to the last 6 lines', async () => {
+    const bot = makeFakeBot()
+    let clock = 10_000
+    const feed = createWorkerActivityFeed({ bot, now: () => clock, minEditIntervalMs: 0 })
+
+    for (let i = 1; i <= 9; i++) {
+      clock += 1000
+      await feed.update('w1', 'chat', view({ toolCount: i, latestSummary: `line ${i}` }))
+    }
+
+    const last = bot.edits.at(-1)!
+    expect(last.text.match(/↳/g) ?? []).toHaveLength(6)
+    // Oldest lines evicted; newest retained.
+    expect(last.text).not.toContain('line 1')
+    expect(last.text).not.toContain('line 3')
+    expect(last.text).toContain('line 4')
+    expect(last.text).toContain('line 9')
+  })
+
+  it('grows the narrative even while throttled (line surfaces on next edit)', async () => {
+    const bot = makeFakeBot()
+    let clock = 10_000
+    const feed = createWorkerActivityFeed({ bot, now: () => clock, minEditIntervalMs: 2500 })
+
+    await feed.update('w1', 'chat', view({ toolCount: 1, latestSummary: 'line A' }))
+    expect(bot.sent).toHaveLength(1)
+
+    // Throttled tick — no edit, but the line must still be accumulated.
+    clock = 11_000
+    await feed.update('w1', 'chat', view({ toolCount: 2, latestSummary: 'line B' }))
+    expect(bot.edits).toHaveLength(0)
+
+    // Past the throttle — the edit now carries BOTH lines.
+    clock = 13_000
+    await feed.update('w1', 'chat', view({ toolCount: 3, latestSummary: 'line C' }))
+    const last = bot.edits.at(-1)!
+    expect(last.text).toContain('↳ <i>line A</i>')
+    expect(last.text).toContain('↳ <i>line B</i>')
+    expect(last.text).toContain('↳ <i>line C</i>')
+  })
+
   it('forwards threadId as message_thread_id on send', async () => {
     const bot = makeFakeBot()
     let clock = 10_000

package/telegram-plugin/uat/scenarios/jtbd-forwarded-burst-dm.test.ts

@@ -0,0 +1,158 @@
+/**
+ * JTBD scenario — forwarded burst / split paste coalesces into ONE turn.
+ *
+ * Serves: `reference/steer-or-queue-mid-flight.md` — the "Forwarded
+ * burst / split paste" UAT prompt. When several messages land in quick
+ * succession from the same sender (a forward of 3-4 messages, or a long
+ * paste Telegram split into chunks), inbound coalescing must merge them
+ * into a SINGLE Claude turn with shared context — not reply to each
+ * fragment in isolation.
+ *
+ * This is the end-to-end gate for the A1 coalescing work shipped in
+ * v0.14.18 (#2007). The merge logic itself is covered by unit + fuzz
+ * tests (`inbound-coalesce.test.ts`, `pending-inbound-buffer.test.ts`),
+ * but only this scenario exercises the real inbound → gateway coalescer
+ * → claude → outbound path over a live Telegram chat.
+ *
+ * ## How the signal is constructed
+ *
+ * Naively asking the agent to "combine facts from several messages"
+ * does NOT distinguish coalesced from fanned-out: even when each
+ * message becomes its own turn, every later turn carries the PRIOR
+ * turns in its conversation history, so the model could still answer
+ * from history. History bleed makes a content-combination assertion
+ * useless as a coalescing probe.
+ *
+ * The distinguishing fact is whether a SINGLE turn saw all the parts in
+ * ONE incoming message. So we anchor the instruction on "this single
+ * message": three messages are fired near-simultaneously (so they land
+ * inside the default 500ms coalesce window), each carrying a distinct
+ * code token, and the instruction (in the last part) asks the agent to
+ * echo every token it received *in this one incoming message*.
+ *
+ *   - Coalesced  → the merged turn's single message contains ALPHA,
+ *     BRAVO and CHARLIE → the reply names all three.
+ *   - Fanned out → the message carrying the instruction contains only
+ *     its own token → the reply names just that one. (And the other
+ *     two tokens arrive as their own separate turns.)
+ *
+ * Tokens are deliberately odd uppercase strings so a substring match is
+ * unambiguous and won't collide with incidental words in the reply.
+ *
+ * Order-independence: the three sends are dispatched concurrently to
+ * guarantee they share a coalesce window, which means Telegram may
+ * deliver them in any order. We assert SET membership (all three
+ * present), never order.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+import { pollUntil } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+
+// Distinctive code tokens — unlikely to appear incidentally in a reply.
+const TOKENS = ["ALPHA", "BRAVO", "CHARLIE"] as const;
+
+const BURST: string[] = [
+  `BURST-PROBE part 1 of 3. Code token: ${TOKENS[0]}.`,
+  `BURST-PROBE part 2 of 3. Code token: ${TOKENS[1]}.`,
+  `BURST-PROBE part 3 of 3. Code token: ${TOKENS[2]}. ` +
+    `Reply with ONLY the BURST-PROBE code tokens contained in THIS SINGLE ` +
+    `incoming message, slash-separated. If this message contains just one ` +
+    `token, reply with only that token.`,
+];
+
+// Generous budget: TTFO on the test-harness is ~7s warm; coalescing
+// adds the (sub-second) window plus normal model latency.
+const ANSWER_TIMEOUT_MS = 40_000;
+
+function tokensIn(text: string): string[] {
+  const upper = text.toUpperCase();
+  return TOKENS.filter((t) => upper.includes(t));
+}
+
+describe("uat: forwarded burst / split paste coalesces into one turn", () => {
+  it(
+    "a 3-message burst is answered as ONE shared-context turn",
+    async () => {
+      const sc = await spinUp({ agent: AGENT });
+      try {
+        // Start observing BEFORE the burst — observeMessages only sees
+        // live updates, not history. Drain into a per-message-id map so
+        // streamed edits collapse to the message's latest text.
+        const latestById = new Map<number, ObservedMessage>();
+        const stream = sc.driver.observeMessages(sc.botUserId);
+        const consume = (async () => {
+          for await (const m of stream) {
+            if (m.senderUserId === sc.driverUserId) continue; // skip our own sends
+            latestById.set(m.messageId, m);
+          }
+        })();
+
+        // Fire all three concurrently so they share one coalesce window.
+        // Concurrency (not serial awaits) is what keeps inter-arrival
+        // under the 500ms default — three serial round-trips could blow
+        // the window on a slow link.
+        await Promise.all(BURST.map((t) => sc.sendDM(t)));
+
+        // Wait until a single bot message names all three tokens — the
+        // proof that one turn saw the whole burst in one incoming
+        // message.
+        const allThree = await pollUntil(
+          () => {
+            for (const m of latestById.values()) {
+              if (tokensIn(m.text).length === TOKENS.length) return m;
+            }
+            return undefined;
+          },
+          { timeout: ANSWER_TIMEOUT_MS, interval: 500 },
+        ).catch(() => undefined);
+
+        // Close the observer stream.
+        await stream[Symbol.asyncIterator]().return?.(undefined as never);
+        await consume;
+
+        const botMsgs = [...latestById.values()];
+        const tokenBearing = botMsgs.filter((m) => tokensIn(m.text).length > 0);
+
+        if (!allThree) {
+          const seen = tokenBearing
+            .map((m) => `#${m.messageId}=[${tokensIn(m.text).join(",")}]`)
+            .join(" ");
+          throw new Error(
+            `[forwarded-burst] No single bot reply named all of ` +
+              `${TOKENS.join("/")}. This is the coalescing regression: the ` +
+              `burst fanned out into separate turns so no turn saw the full ` +
+              `message. Token-bearing replies: ${seen || "(none)"}.`,
+          );
+        }
+
+        expect(tokensIn(allThree.text).sort()).toEqual([...TOKENS].sort());
+
+        // Forensic: a coalesced burst should produce ONE answer that
+        // names the tokens. Several token-bearing replies hint at a
+        // partial fan-out even though one of them happened to be
+        // complete — worth a warning before it becomes a hard failure.
+        if (tokenBearing.length > 1) {
+          console.warn(
+            `[forwarded-burst] ${tokenBearing.length} token-bearing replies ` +
+              `observed (expected 1). Possible partial fan-out: ` +
+              tokenBearing
+                .map((m) => `#${m.messageId}=[${tokensIn(m.text).join(",")}]`)
+                .join(" "),
+          );
+        } else {
+          console.log(
+            `[forwarded-burst] One shared-context reply named all tokens ` +
+              `(#${allThree.messageId}). Coalescing healthy.`,
+          );
+        }
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    ANSWER_TIMEOUT_MS + 20_000,
+  );
+});