switchroom 0.15.44 → 0.16.4

package/telegram-plugin/tests/subagent-watcher-clip-narrative.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { clipNarrative } from '../tool-activity-summary.js'
+
+// `clipNarrative` is the shared narrative-clip primitive used by both the
+// main-agent gateway path (showNarrativeStep) and the sub-agent watcher. It
+// collapses multi-line text to the first line, trims, and slices to 200 chars
+// (= STATUS_LINE_MAX). Fix 1 raised the cap from 120 → 200 to match the tool-
+// label cap so a narrative line reads as legibly as a tool step (no
+// mid-sentence truncation on typical agent narration lengths of 130–180 chars).
+
+describe('clipNarrative — shared subagent-watcher narrative clip', () => {
+  it('collapses a multi-line block to its first line', () => {
+    const text = 'On it. Let me find the repo…\nthen build it\nand run the tests'
+    expect(clipNarrative(text)).toBe('On it. Let me find the repo…')
+  })
+
+  it('trims surrounding whitespace on the first line', () => {
+    expect(clipNarrative('   Found both repos:   \nmore')).toBe('Found both repos:')
+  })
+
+  it('caps the first line at 200 characters (Fix 1: raised from 120 to match STATUS_LINE_MAX)', () => {
+    // 200-char cap: a 250-char first line is clipped at exactly 200.
+    const long = 'x'.repeat(250)
+    const out = clipNarrative(long)
+    expect(out.length).toBe(200)
+    expect(out).toBe('x'.repeat(200))
+  })
+
+  it('a first line under 200 chars is returned verbatim', () => {
+    expect(clipNarrative('short narrative line')).toBe('short narrative line')
+  })
+
+  it('a narrative between 120 and 200 chars is NOT truncated (the Fix 1 improvement)', () => {
+    // Before Fix 1 the 120-char clip truncated typical 130–180 char agent narration.
+    // After Fix 1 these are returned in full up to 200 chars.
+    const narrative = 'I will now analyse all 30 changed files in /src/auth to understand the scope before patching the vulnerable token-parsing code path'
+    expect(narrative.length).toBeGreaterThan(120)
+    expect(narrative.length).toBeLessThanOrEqual(200)
+    expect(clipNarrative(narrative)).toBe(narrative) // not truncated
+  })
+
+  it('matches the new 200-char cap expression (STATUS_LINE_MAX equivalence)', () => {
+    const STATUS_LINE_MAX = 200
+    const samples = [
+      'line one\nline two',
+      '   padded   \nrest',
+      'a'.repeat(150),
+      'b'.repeat(250),
+      'single',
+      '',
+      'tab\tand spaces  \nnext',
+    ]
+    for (const s of samples) {
+      const expected = s.split('\n')[0].trim().slice(0, STATUS_LINE_MAX)
+      expect(clipNarrative(s)).toBe(expected)
+    }
+  })
+})

package/telegram-plugin/tests/subagent-watcher-parent-turn-key.test.ts

@@ -90,6 +90,16 @@ function writeMeta(agentType: string, description: string): string {
   return jsonlPath
 }
 
+/**
+ * Write meta.json with a `toolUseId` field (Bug 1 fix — direct PK lookup).
+ * Modern Claude Code versions write this alongside `agentType` and `description`.
+ */
+function writeMetaWithToolUseId(toolUseId: string, agentType: string, description: string): string {
+  const jsonlPath = join(tempDir, 'worker.jsonl')
+  writeFileSync(join(tempDir, 'worker.meta.json'), JSON.stringify({ agentType, description, toolUseId }))
+  return jsonlPath
+}
+
 function readSub(id: string) {
   return db.prepare('SELECT jsonl_agent_id, parent_turn_key FROM subagents WHERE id = ?').get(id) as
     | { jsonl_agent_id: string | null; parent_turn_key: string | null }
@@ -154,6 +164,57 @@ describe('backfillJsonlAgentId — parent_turn_key resolution', () => {
   })
 })
 
+// ─── #2501: direct toolUseId PK lookup (Bug 1 fix) ───────────────────────────
+// Claude Code writes `toolUseId` to meta.json so backfillJsonlAgentId can
+// match the row by its primary key instead of the fuzzy (agentType, description)
+// match that fails when descriptions collide or are null.
+describe('backfillJsonlAgentId — toolUseId direct PK lookup (#2501)', () => {
+  it('uses toolUseId from meta.json to link the row directly by PK', () => {
+    insertTurn({ turnKey: '555:10', chatId: '555', startedAt: 1000, endedAt: 2000 })
+    insertSub({ id: 'toolu_direct', agentType: 'general-purpose', description: null as unknown as string, startedAt: 1500 })
+
+    const jsonlPath = writeMetaWithToolUseId('toolu_direct', 'general-purpose', '')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_direct')
+
+    const row = readSub('toolu_direct')
+    expect(row?.jsonl_agent_id).toBe('agentstem_direct')
+  })
+
+  it('direct PK lookup succeeds even when description is null (fuzzy match would fail)', () => {
+    // Two rows with the same agentType and NULL description — fuzzy match is ambiguous.
+    insertSub({ id: 'toolu_null_desc_1', agentType: 'general-purpose', description: null as unknown as string, startedAt: 1000 })
+    insertSub({ id: 'toolu_null_desc_2', agentType: 'general-purpose', description: null as unknown as string, startedAt: 2000 })
+
+    // meta.json carries the exact toolUseId for the first row.
+    const jsonlPath = writeMetaWithToolUseId('toolu_null_desc_1', 'general-purpose', '')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_null_desc')
+
+    // Must link to the first row, not the more-recent second one.
+    expect(readSub('toolu_null_desc_1')?.jsonl_agent_id).toBe('agentstem_null_desc')
+    expect(readSub('toolu_null_desc_2')?.jsonl_agent_id).toBeNull()
+  })
+
+  it('falls back to fuzzy match when toolUseId in meta.json does not match any row', () => {
+    insertSub({ id: 'toolu_fuzzy', agentType: 'researcher', description: 'Find stuff', startedAt: 1000 })
+
+    // toolUseId points at a non-existent row; fuzzy match should still work.
+    const jsonlPath = writeMetaWithToolUseId('toolu_NONEXISTENT', 'researcher', 'Find stuff')
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_fuzzy_fallback')
+
+    expect(readSub('toolu_fuzzy')?.jsonl_agent_id).toBe('agentstem_fuzzy_fallback')
+  })
+
+  it('meta.json with only toolUseId and no agentType/description still links the row', () => {
+    insertSub({ id: 'toolu_id_only', agentType: null as unknown as string, description: null as unknown as string, startedAt: 1000 })
+
+    const jsonlPath = join(tempDir, 'worker.jsonl')
+    writeFileSync(join(tempDir, 'worker.meta.json'), JSON.stringify({ toolUseId: 'toolu_id_only' }))
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_id_only')
+
+    expect(readSub('toolu_id_only')?.jsonl_agent_id).toBe('agentstem_id_only')
+  })
+})
+
 // ─── #2081: overlapping windows + hook-stamped value precedence ───────────────
 // The backfill is now only a FALLBACK — the PreToolUse hook stamps
 // parent_turn_key from the live turn-active marker at dispatch
@@ -203,3 +264,44 @@ describe('backfillJsonlAgentId — overlapping windows / hook precedence (#2081)
     expect(row?.parent_turn_key).toBe('-100:7:1400')
   })
 })
+
+// ─── #2506: null meta.json guard ─────────────────────────────────────────────
+// JSON.parse('null') succeeds and returns null. Before the fix, the enclosing
+// try/catch only covered the read+parse, so execution fell through to
+// `if (!meta.agentType …)` which threw TypeError: Cannot read properties of
+// null. The fix guards with `if (!meta || …)` so a literal-null meta.json
+// degrades to the same clean skip as any other "no usable fields" case.
+describe('backfillJsonlAgentId — null meta.json guard (#2506)', () => {
+  it('meta.json containing literal null → clean skip, no throw, row stays unlinked', () => {
+    insertSub({ id: 'toolu_null_meta', agentType: 'worker', description: 'task', startedAt: 1000 })
+
+    const jsonlPath = join(tempDir, 'null_meta_worker.jsonl')
+    writeFileSync(join(tempDir, 'null_meta_worker.meta.json'), 'null')
+
+    const logs: string[] = []
+    // Must not throw — before the fix this crashed with TypeError: Cannot read
+    // properties of null (reading 'agentType').
+    expect(() => backfillJsonlAgentId(db, jsonlPath, 'agentstem_null_meta', (m) => logs.push(m))).not.toThrow()
+
+    // Row must remain unlinked (the skip path, not the link path).
+    const row = readSub('toolu_null_meta')
+    expect(row?.jsonl_agent_id).toBeNull()
+
+    // A skip log must have been emitted (not a misleading 'backfill error').
+    expect(logs.some((l) => l.includes('backfill skip') && l.includes('agentstem_null_meta'))).toBe(true)
+  })
+
+  it('meta.json containing literal null → skip log does NOT contain "error"', () => {
+    // The outer try/catch in registerAgent would have surfaced this as a
+    // "backfill error" before the fix; now it should be a clean "backfill skip".
+    const jsonlPath = join(tempDir, 'null_meta_worker2.jsonl')
+    writeFileSync(join(tempDir, 'null_meta_worker2.meta.json'), 'null')
+
+    const logs: string[] = []
+    backfillJsonlAgentId(db, jsonlPath, 'agentstem_null_meta2', (m) => logs.push(m))
+
+    // Should have a skip log, not an error log.
+    expect(logs.some((l) => l.toLowerCase().includes('error'))).toBe(false)
+    expect(logs.some((l) => l.includes('backfill skip'))).toBe(true)
+  })
+})

package/telegram-plugin/tests/subagent-watcher-workflow-visibility.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Regression test for workflow sub-agent feed visibility.
+ *
+ * Root cause: rescanSubagentDirs() did a flat readdir on subagents/ and only
+ * matched entries whose names started with "agent-" and ended with ".jsonl".
+ * Workflow sub-agents (spawned by the Workflow tool) write to a nested path:
+ *   <session>/subagents/workflows/wf_<id>/agent-<id>.jsonl
+ * The "workflows" directory entry doesn't match the agent-*.jsonl filter, so
+ * it was silently skipped and no workflow agent was ever registered or tailed.
+ *
+ * Fix: descend one level into subagents/workflows/wf_NNN dirs using the same
+ * watchAndScan helper so all downstream tiers (registry, tailing, stall
+ * detection, historical suppression, terminatedAgentIds dedup) apply
+ * identically.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { rmSync } from 'fs'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+
+function minimalAgentJsonl(): string {
+  return buildJSONL(
+    { type: 'user', message: { content: [{ type: 'text', text: 'Implement the workflow step' }] } },
+  )
+}
+
+// ─── Test suite ───────────────────────────────────────────────────────────────
+
+describe('workflow sub-agent feed visibility', () => {
+  let tmpRoot = ''
+  const started: Array<ReturnType<typeof startSubagentWatcher>> = []
+
+  afterEach(() => {
+    while (started.length) {
+      try { started.pop()?.stop() } catch { /* ignore */ }
+    }
+    if (tmpRoot) {
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+      tmpRoot = ''
+    }
+  })
+
+  /**
+   * Start a minimal watcher against a real tmpdir and return a poll() helper.
+   * Timers are stubbed so no real setInterval fires; the caller drives polls
+   * manually to control the scan sequence.
+   */
+  function startWatcher(agentDir: string): {
+    poll: () => void
+    watcher: ReturnType<typeof startSubagentWatcher>
+    registered: string[]
+  } {
+    const registered: string[] = []
+    const intervals: Array<{ fn: () => void; ref: number }> = []
+    const timeouts: Array<{ fn: () => void; ref: number }> = []
+    let nextRef = 1
+
+    const watcher = startSubagentWatcher({
+      agentDir,
+      onFinish: (info) => { registered.push(`finish:${info.agentId}`) },
+      stallThresholdMs: 60_000,
+      silentSynthesisStallThresholdMs: 60_000,
+      rescanMs: 500,
+      now: () => Date.now(),
+      setInterval: (fn) => {
+        const ref = nextRef++
+        intervals.push({ fn, ref })
+        return { ref }
+      },
+      clearInterval: (handle) => {
+        const { ref } = handle as { ref: number }
+        const idx = intervals.findIndex((i) => i.ref === ref)
+        if (idx !== -1) intervals.splice(idx, 1)
+      },
+      setTimeout: (fn) => {
+        const ref = nextRef++
+        timeouts.push({ fn, ref })
+        return { ref }
+      },
+      clearTimeout: (handle) => {
+        const { ref } = handle as { ref: number }
+        const idx = timeouts.findIndex((t) => t.ref === ref)
+        if (idx !== -1) timeouts.splice(idx, 1)
+      },
+      log: () => {},
+    })
+    started.push(watcher)
+
+    return {
+      poll: () => intervals[0]?.fn(),
+      watcher,
+      registered,
+    }
+  }
+
+  it('registers a workflow agent at subagents/workflows/wf_<id>/agent-<id>.jsonl', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-workflow-test-'))
+    const agentDir = join(tmpRoot, 'agent')
+
+    // Lay out the nested workflow path that the Workflow tool produces
+    const wfDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'workflows', 'wf_test')
+    mkdirSync(wfDir, { recursive: true })
+    const agentId = 'abcdef1234567890'
+    const jsonlPath = join(wfDir, `agent-${agentId}.jsonl`)
+    writeFileSync(jsonlPath, minimalAgentJsonl())
+
+    const { poll, watcher } = startWatcher(agentDir)
+    poll()
+
+    const entry = watcher.getRegistry().get(agentId)
+    expect(entry, 'workflow agent should be registered').toBeDefined()
+    expect(entry?.state).toBe('running')
+    // The agent file was just written, so the boot-promotion path correctly
+    // marks it live (historical=false) — the user is still awaiting its output.
+  })
+
+  it('does NOT register a sibling journal.jsonl in the wf dir', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-workflow-journal-test-'))
+    const agentDir = join(tmpRoot, 'agent')
+
+    const wfDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'workflows', 'wf_test')
+    mkdirSync(wfDir, { recursive: true })
+
+    const agentId = 'deadbeefcafe0001'
+    writeFileSync(join(wfDir, `agent-${agentId}.jsonl`), minimalAgentJsonl())
+    // journal.jsonl is written by the Workflow tool alongside the agent transcript
+    writeFileSync(join(wfDir, 'journal.jsonl'), buildJSONL({ type: 'workflow_event', step: 1 }))
+
+    const { poll, watcher } = startWatcher(agentDir)
+    poll()
+
+    // The agent JSONL must be registered
+    expect(watcher.getRegistry().get(agentId), 'agent entry must exist').toBeDefined()
+    // journal.jsonl must NOT appear in the registry (no agent id derived from it)
+    const journalKey = 'journal' // would be the agentId if erroneously registered
+    expect(watcher.getRegistry().get(journalKey), 'journal.jsonl must not be registered').toBeUndefined()
+    // Registry should have exactly one entry (the real agent)
+    expect(watcher.getRegistry().size).toBe(1)
+  })
+
+  it('registers multiple workflow agents across different wf_* dirs', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-workflow-multi-test-'))
+    const agentDir = join(tmpRoot, 'agent')
+
+    const workflowsBase = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'workflows')
+
+    const wfIds = ['wf_step1', 'wf_step2', 'wf_step3']
+    const agentIds: string[] = []
+    for (const wfId of wfIds) {
+      const wfDir = join(workflowsBase, wfId)
+      mkdirSync(wfDir, { recursive: true })
+      const agentId = `agent${wfId.replace('wf_', '')}cafebabe`
+      agentIds.push(agentId)
+      writeFileSync(join(wfDir, `agent-${agentId}.jsonl`), minimalAgentJsonl())
+      // Each wf dir also gets a journal.jsonl — must be ignored
+      writeFileSync(join(wfDir, 'journal.jsonl'), buildJSONL({ step: wfId }))
+    }
+
+    const { poll, watcher } = startWatcher(agentDir)
+    poll()
+
+    for (const agentId of agentIds) {
+      expect(watcher.getRegistry().get(agentId), `${agentId} should be registered`).toBeDefined()
+    }
+    // Exactly the three agents, no journals
+    expect(watcher.getRegistry().size).toBe(3)
+  })
+
+  it('skips a stray non-directory file sitting directly in workflows/', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-workflow-stray-test-'))
+    const agentDir = join(tmpRoot, 'agent')
+
+    const workflowsBase = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'workflows')
+    mkdirSync(workflowsBase, { recursive: true })
+    // A stray regular file directly under workflows/ (e.g. an index/lock the
+    // Workflow tool might drop there). statSync succeeds on it, so without the
+    // isDirectory() guard it would be handed to watchAndScan and open a wasted
+    // fs.watch. It must be skipped — not registered — and not crash the scan.
+    writeFileSync(join(workflowsBase, 'index.json'), '{"runs":[]}')
+
+    // A real workflow agent alongside the stray file must still register
+    const wfDir = join(workflowsBase, 'wf_real')
+    mkdirSync(wfDir, { recursive: true })
+    const agentId = 'feedface00001111'
+    writeFileSync(join(wfDir, `agent-${agentId}.jsonl`), minimalAgentJsonl())
+
+    const { poll, watcher } = startWatcher(agentDir)
+    poll()
+
+    expect(watcher.getRegistry().get(agentId), 'real workflow agent should register').toBeDefined()
+    // Only the real agent — the stray file produced no entry
+    expect(watcher.getRegistry().size).toBe(1)
+  })
+
+  it('discovers a wf_* dir created AFTER the watcher starts (runtime poll)', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-workflow-late-test-'))
+    const agentDir = join(tmpRoot, 'agent')
+
+    // Session + subagents dir present at boot, but no workflows/ run yet
+    const subagents = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagents, { recursive: true })
+
+    const { poll, watcher } = startWatcher(agentDir)
+    poll() // boot scan: nothing to register
+    expect(watcher.getRegistry().size).toBe(0)
+
+    // A workflow run begins after the watcher is already live
+    const wfDir = join(subagents, 'workflows', 'wf_late')
+    mkdirSync(wfDir, { recursive: true })
+    const agentId = 'lateb00b1234abcd'
+    writeFileSync(join(wfDir, `agent-${agentId}.jsonl`), minimalAgentJsonl())
+
+    poll() // next poll tick re-descends workflows/ and picks it up
+    expect(watcher.getRegistry().get(agentId), 'late workflow agent should be discovered on poll').toBeDefined()
+  })
+})

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -519,6 +519,153 @@ describe('startSubagentWatcher', () => {
       expect(toolTick?.latestSummary).toBe('')
     })
 
+    it('narrative gate: a draft-then-reply sub_agent_text is SUPPRESSED (no progress cue)', () => {
+      // The worker composes its answer as a text block, then calls
+      // stream_reply with near-identical text. The narrative cue must be
+      // suppressed so the answer is not double-surfaced.
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary }) => {
+          // Narrative ticks carry NO progressLine (tool ticks do); record them.
+          if (progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo path')))
+      h.poll()
+      const answer = 'The repo is at /home/user/code/switchroom.'
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText(answer)))
+      h.poll()
+      // The draft is staged, not yet resolved — no cue yet.
+      // The very next event is a reply tool with matching text → SUPPRESS.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+      }))
+      h.poll()
+      expect(narrativeCues.length).toBe(0)
+    })
+
+    it('narrative gate: pure working narration is SHOWN (cue fires)', () => {
+      // "On it. Let me find the repo…" followed by a Bash tool — the next
+      // event is a non-reply tool, so the narration is SHOWN.
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary }) => {
+          if (progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('On it. Let me find the repo.')))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+      h.poll()
+      // The staged narration was resolved by the non-reply Bash → SHOWN.
+      expect(narrativeCues.length).toBe(1)
+      expect(narrativeCues[0]).toContain('find the repo')
+    })
+
+    it('narrative gate: trailing narration at turn_end is SHOWN', () => {
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary }) => {
+          if (progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+      h.poll()
+      // A trailing narration block, then turn_end (turn_duration). The
+      // trailing block has no reply after it → SHOWN at turn_end.
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('Done. All green.')))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentTurnDuration()))
+      h.poll()
+      expect(narrativeCues.length).toBe(1)
+      expect(narrativeCues[0]).toContain('All green')
+    })
+
+    it('NIT 3: trailing narration that DRAFTS a prior stream_reply is SUPPRESSED at turn_end', () => {
+      // A FOREGROUND sub-agent calls stream_reply as its final tool, THEN
+      // emits a trailing text block that is a draft of that delivered answer,
+      // then turn_end. Before the fix, turn_end SHOWed pending narration
+      // unconditionally (toolName === null skipped dedup), double-surfacing a
+      // draft of the answer. Now it suppresses a trailing draft symmetric with
+      // main-agent step 3.
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary }) => {
+          if (progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
+      h.poll()
+      const answer = 'The fix touches three files and adds a unit test for the double-Done case.'
+      // Final tool of the turn is stream_reply carrying the answer.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+      }))
+      h.poll()
+      // Trailing text block (separate message) that drafts the delivered answer.
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText(answer)))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentTurnDuration()))
+      h.poll()
+      // SUPPRESSED: the trailing draft of the reply is not surfaced.
+      expect(narrativeCues.length).toBe(0)
+    })
+
+    it('NIT 3: genuine trailing narration AFTER a stream_reply is still SHOWN', () => {
+      // Symmetric guard: after delivering its answer the sub-agent emits a
+      // DIFFERENT trailing line ("Done — cleaning up."). That is genuine
+      // liveness, not a draft of the answer, so it must still SHOW.
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary }) => {
+          if (progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
+      h.poll()
+      const answer = 'The fix touches three files and adds a unit test for the double-Done case.'
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+      }))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('Done — cleaning up the worktree now.')))
+      h.poll()
+      appendFileSync(jsonlPath, buildJSONL(subAgentTurnDuration()))
+      h.poll()
+      expect(narrativeCues.length).toBe(1)
+      expect(narrativeCues[0]).toContain('cleaning up')
+    })
+
     it('captures the full last narrative line into lastResultText (handback)', () => {
       // lastSummaryLine keeps only the first line, 120 chars — a progress
       // preview. lastResultText keeps the full last narrative emission: