switchroom 0.14.19 → 0.14.21

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -184,10 +184,16 @@ export function planBufferedRedelivery(
   return out
 }
 
+/** Meta keys that describe an attachment — the primary (image_path,
+ *  attachment_*) plus the A2 numbered siblings (image_path_2,
+ *  attachment_file_id_2, …) and attachment_count. */
+const ATTACHMENT_META_RE = /^(image_path|attachment_)/
+
 /** Collapse a >1 run into a single turn. The newest message anchors the
  *  turn (its messageId/ts/user/meta); texts join in arrival order; the
- *  single attachment (if any) rides along from whichever message carried
- *  it. Caller guarantees the run is mergeable + has at most one media. */
+ *  attachment(s) (if any) ride along from whichever message carried them.
+ *  Caller guarantees the run is mergeable + has at most one media-bearing
+ *  entry. */
 function mergeRun(run: InboundMessage[]): InboundMessage {
   const last = run[run.length - 1]!
   const mediaEntry = run.find(inboundHasMedia)
@@ -195,10 +201,21 @@ function mergeRun(run: InboundMessage[]): InboundMessage {
     ...last,
     text: run.map((m) => m.text).join('\n'),
   }
-  // Re-seat the single attachment/imagePath from the entry that owns it
-  // (which may not be `last`), or strip them if the run is text-only.
+  // Re-seat the attachment/imagePath from the entry that owns it (which may
+  // not be `last`), or strip them if the run is text-only.
   delete merged.imagePath
   delete merged.attachment
+  if (mediaEntry != null && mediaEntry !== last) {
+    // The media-bearing entry isn't the anchor, so `last.meta` lacks the
+    // attachment fields the agent reads (image_path / attachment_* and the
+    // A2 numbered siblings). Splice the owning entry's attachment meta keys
+    // into the merged meta so the agent still sees every attachment.
+    const splicedMeta: Record<string, string> = { ...merged.meta }
+    for (const [k, v] of Object.entries(mediaEntry.meta)) {
+      if (ATTACHMENT_META_RE.test(k)) splicedMeta[k] = v
+    }
+    merged.meta = splicedMeta
+  }
   if (mediaEntry?.imagePath != null) merged.imagePath = mediaEntry.imagePath
   if (mediaEntry?.attachment != null) merged.attachment = mediaEntry.attachment
   return merged

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

@@ -0,0 +1,170 @@
+/**
+ * Unit tests for the A2 multi-attachment helpers
+ * (telegram-plugin/gateway/coalesce-attachments.ts).
+ *
+ * These pin the pure pieces of the multi-attachment fold-in that live
+ * outside gateway.ts so they can be exercised without loadAccess()/IPC:
+ *   1. resolveCoalesceMaxAttachments — the runtime cap default (10).
+ *   2. splitCoalescedAttachments — primary + capped extras, arrival order.
+ *   3. buildExtraAttachmentMeta — numbered meta fields starting at _2.
+ *
+ * A cap of 1 reproduces the historical single-attachment shape: primary
+ * only, no extras, no numbered meta.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  splitCoalescedAttachments,
+  buildExtraAttachmentMeta,
+  resolveCoalesceMaxAttachments,
+  DEFAULT_MAX_ATTACHMENTS,
+  type ResolvedExtraAttachment,
+} from '../gateway/coalesce-attachments.js'
+
+describe('resolveCoalesceMaxAttachments (default 10 = full album)', () => {
+  it('defaults to 10 when unset', () => {
+    expect(resolveCoalesceMaxAttachments(undefined)).toBe(10)
+    expect(DEFAULT_MAX_ATTACHMENTS).toBe(10)
+  })
+  it('honours an explicit operator cap', () => {
+    expect(resolveCoalesceMaxAttachments(1)).toBe(1)
+    expect(resolveCoalesceMaxAttachments(25)).toBe(25)
+  })
+  it('floors a 0 / negative cap at 1 (never strips the only attachment)', () => {
+    expect(resolveCoalesceMaxAttachments(0)).toBe(1)
+    expect(resolveCoalesceMaxAttachments(-5)).toBe(1)
+  })
+})
+
+interface Entry {
+  text: string
+  att?: string
+}
+
+const has = (e: Entry): boolean => e.att != null
+
+describe('splitCoalescedAttachments', () => {
+  it('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,160 @@
+/**
+ * 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,
+  resolveSafeBoundaryEnabled,
+  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('resolveSafeBoundaryEnabled (default ON)', () => {
+  it('defaults to true when unset', () => {
+    expect(resolveSafeBoundaryEnabled(undefined)).toBe(true)
+  })
+  it('stays true when explicitly true', () => {
+    expect(resolveSafeBoundaryEnabled(true)).toBe(true)
+  })
+  it('only an explicit false opts out', () => {
+    expect(resolveSafeBoundaryEnabled(false)).toBe(false)
+  })
+})
+
+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/permission-verdict-resume-guard.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Structural pin for the permission-card resume beat.
+ *
+ * What broke (and the bug this guards against): when the operator
+ * answers a permission card, the suspended `claude` turn un-parks and
+ * resumes the SAME turn — the gateway must flip the awaiting glyph
+ * (🙏) back to a working glyph so the operator sees progress instead
+ * of a stuck card. That flip is `resumeReactionAfterVerdict()`.
+ *
+ * The verdict can arrive down several independent paths (button tap,
+ * always-allow, `/allow`·`/deny`, TTL auto-deny, free-text `y <id>`/
+ * `no <id>` reply, …). Every one of them calls
+ * `dispatchPermissionVerdict(...)` to un-park the turn — but the resume
+ * glyph flip is a *separate* call right next to it. The free-text-reply
+ * path shipped the dispatch WITHOUT the resume (fixed in v0.14.19), so
+ * answering via a text reply left the card frozen on 🙏 even though the
+ * turn was running. The controller-level behaviour is covered by
+ * `status-reactions.test.ts` ("setAwaiting" + watchdog re-arm); mtcute
+ * UAT cannot observe reactions at all, so this static pin is the only
+ * thing that catches a verdict path forgetting the resume.
+ *
+ * This guard fails loudly if any `dispatchPermissionVerdict(...)`
+ * callsite is not paired with a `resumeReactionAfterVerdict()` within a
+ * few lines — i.e. a new (or refactored) verdict path drops the resume.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_SRC = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf8',
+)
+
+const LINES = GATEWAY_SRC.split('\n')
+
+// A `dispatchPermissionVerdict(` occurrence is a CALLSITE unless it's the
+// function definition itself.
+const isDefinition = (line: string) =>
+  /\bfunction\s+dispatchPermissionVerdict\b/.test(line)
+
+const dispatchCallsites = LINES.flatMap((line, i) =>
+  /\bdispatchPermissionVerdict\s*\(/.test(line) && !isDefinition(line)
+    ? [i]
+    : [],
+)
+
+// How far below the dispatch the resume call is allowed to live. The
+// widest real gap today is ~9 lines (the slash-command path); 15 gives
+// refactor headroom without letting an unrelated resume "cover" a
+// dispatch from a different block.
+const RESUME_WINDOW = 15
+
+describe('permission verdict → resume reaction wiring', () => {
+  it('there is at least one verdict-dispatch path to guard', () => {
+    expect(dispatchCallsites.length).toBeGreaterThan(0)
+  })
+
+  it('every dispatchPermissionVerdict() callsite flips the awaiting glyph back via resumeReactionAfterVerdict()', () => {
+    const unpaired: number[] = []
+    for (const idx of dispatchCallsites) {
+      const window = LINES.slice(idx, idx + RESUME_WINDOW + 1).join('\n')
+      if (!/\bresumeReactionAfterVerdict\s*\(\s*\)/.test(window)) {
+        // 1-based line number for a human-readable failure.
+        unpaired.push(idx + 1)
+      }
+    }
+    expect(
+      unpaired,
+      `dispatchPermissionVerdict() at gateway.ts line(s) ` +
+        `${unpaired.join(', ')} has no resumeReactionAfterVerdict() within ` +
+        `${RESUME_WINDOW} lines — that verdict path leaves the permission ` +
+        `card stuck on 🙏 after the operator answers. Add the resume call ` +
+        `(see the sibling paths and v0.14.19 / the free-text-reply fix).`,
+    ).toEqual([])
+  })
+
+  it('the resume helper still exists (the pairing is meaningless if it was deleted)', () => {
+    expect(/function\s+resumeReactionAfterVerdict\s*\(/.test(GATEWAY_SRC)).toBe(
+      true,
+    )
+  })
+})

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

@@ -2,10 +2,24 @@ import { describe, it, expect } from 'vitest'
 import {
   renderWorkerActivity,
   createWorkerActivityFeed,
+  isWorkerActivityFeedEnabled,
   type WorkerActivityView,
   type BotApiForWorkerFeed,
 } from '../worker-activity-feed.js'
 
+describe('isWorkerActivityFeedEnabled (default ON)', () => {
+  it('defaults to true when the env var is unset', () => {
+    expect(isWorkerActivityFeedEnabled(undefined)).toBe(true)
+  })
+  it('stays on for any value other than "0"', () => {
+    expect(isWorkerActivityFeedEnabled('1')).toBe(true)
+    expect(isWorkerActivityFeedEnabled('')).toBe(true)
+  })
+  it('only "0" disables it', () => {
+    expect(isWorkerActivityFeedEnabled('0')).toBe(false)
+  })
+})
+
 function view(partial: Partial<WorkerActivityView> = {}): WorkerActivityView {
   return {
     description: 'research competitors',
@@ -92,6 +106,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 +296,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