switchroom 0.18.32 → 0.19.0

package/telegram-plugin/tests/subagent-watcher-boot-skip-dead.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Boot-reconcile perf regression: at boot the subagent-watcher must NOT do the
+ * full initial `readSubTail` (a whole-transcript parse + per-record sqlite
+ * liveness/backfill round-trips) for provably-dead prior-session workers.
+ *
+ * Production incident (2026-07-19): on a busy 24/7 agent ~1177 dead `running`
+ * JSONLs (last written days-to-weeks ago) each got the full register → whole-
+ * file read → liveness/backfill → staleness → FSWatcher-decision treatment on
+ * every boot. On a slow disk that O(filesize) work delayed the gateway
+ * answering Telegram by ~7 minutes after each restart, so the agent looked
+ * dead. The staleness verdict (`last write > inflightPromoteMaxAgeMs`) was
+ * already reached, but only AFTER the expensive read.
+ *
+ * The fix replaces the full read for a stale-by-mtime historical entry with a
+ * BOUNDED TAIL PROBE. Outcomes asserted here (not code paths):
+ *   1. running-at-boot-stale (no turn_end): registered historical, NO watcher,
+ *      NOT swept (nothing terminal to sweep), and the disk read is bounded to
+ *      the tail window even for a huge file (never a byte-0 whole-transcript
+ *      read).
+ *   2. done-at-boot-stale (turn_end present): still reaches terminal cleanup —
+ *      `onTerminalCleanup` fires after the grace window so the worker-feed row
+ *      is swept (the regression the coordinator caught: a done-at-boot orphan
+ *      must NOT be silently left as a ghost feed row).
+ *   3. fresh in-flight-at-boot: takes the full path — its JSONL IS read from
+ *      byte 0 and it DOES get a per-file FSWatcher (no over-pruning).
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type * as fs from 'fs'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+interface FakeWatcher { path: string; close: ReturnType<typeof vi.fn> }
+interface ReadCall { position: number; length: number }
+
+const AGENT_DIR = '/home/user/.switchroom/agents/myagent'
+const PROJECTS = `${AGENT_DIR}/.claude/projects`
+const PROJECT = `${PROJECTS}/proj`
+const SESSION = `${PROJECT}/sess`
+const SUBAGENTS = `${SESSION}/subagents`
+const NOW = 100_000_000
+
+const turnEndLine = () => JSON.stringify({ type: 'system', subtype: 'turn_duration', duration_ms: 100 })
+const toolUseLine = () =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 't1', name: 'Read', input: {} }] } })
+
+/**
+ * Harness with per-path read tracking (position + length of every readSync, the
+ * proxy for "how much of the transcript did boot read") and FSWatcher tracking.
+ * `reportedSize` can far exceed the synthetic tail content, so a test can assert
+ * that only the tail window — not the whole (huge) file — was read.
+ */
+function makeHarness(opts: {
+  fileName: string
+  ageMs: number
+  reportedSize: number
+  /** Synthetic bytes returned when the file is read (represents its tail). */
+  tail: Buffer
+}) {
+  const jsonl = `${SUBAGENTS}/${opts.fileName}`
+  const reads: ReadCall[] = []
+  const watchers: FakeWatcher[] = []
+  const timeouts: Array<{ fn: () => void; fireAt: number; ref: number }> = []
+  const terminalCleanups: string[] = []
+  let currentTime = NOW
+  let nextRef = 1
+
+  const mockFs = {
+    existsSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      return ps === PROJECTS || ps === PROJECT || ps === SESSION || ps === SUBAGENTS || ps === jsonl
+    }) as typeof fs.existsSync,
+    readdirSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === PROJECTS) return ['proj']
+      if (ps === PROJECT) return ['sess']
+      if (ps === SESSION) return ['subagents']
+      if (ps === SUBAGENTS) return [opts.fileName]
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) => {
+      if (String(p) !== jsonl) return { size: 0, mtimeMs: currentTime } as fs.Stats
+      return { size: opts.reportedSize, mtimeMs: currentTime - opts.ageMs } as fs.Stats
+    }) as typeof fs.statSync,
+    openSync: (() => 7) as unknown as typeof fs.openSync,
+    closeSync: (() => undefined) as typeof fs.closeSync,
+    readSync: ((
+      _fd: number, buf: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null,
+    ): number => {
+      reads.push({ position: position ?? 0, length })
+      const src = opts.tail.subarray(0, Math.min(length, opts.tail.length))
+      src.copy(buf as Buffer, offset)
+      return src.length
+    }) as unknown as typeof fs.readSync,
+    watch: ((p: fs.PathLike) => {
+      const w: FakeWatcher = { path: String(p), close: vi.fn() }
+      watchers.push(w)
+      return w as unknown as fs.FSWatcher
+    }) as unknown as typeof fs.watch,
+  }
+
+  const watcher = startSubagentWatcher({
+    agentDir: AGENT_DIR,
+    fs: mockFs,
+    now: () => currentTime,
+    setInterval: () => ({ ref: 0 }),
+    clearInterval: () => {},
+    setTimeout: (fn: () => void, ms: number) => {
+      const ref = nextRef++
+      timeouts.push({ fn, fireAt: currentTime + ms, 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)
+    },
+    onTerminalCleanup: (agentId: string) => { terminalCleanups.push(agentId) },
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      timeouts.sort((a, b) => a.fireAt - b.fireAt)
+      const next = timeouts[0]
+      if (!next || next.fireAt > currentTime) break
+      timeouts.shift()
+      next.fn()
+    }
+  }
+
+  return {
+    watcher,
+    reads,
+    advance,
+    terminalCleanups,
+    jsonl,
+    fileWatchers: () => watchers.filter((w) => w.path === jsonl),
+  }
+}
+
+describe('subagent-watcher boot reconcile: skip full read for dead prior-session workers', () => {
+  it('running-at-boot-stale: historical, no watcher, bounded tail read (not whole transcript), not swept', () => {
+    const agentId = 'deadrunning'
+    // A huge (50 MB) JSONL last written 3 days ago whose tail has NO turn_end.
+    const tail = Buffer.from(`${toolUseLine()}\n${toolUseLine()}\n${toolUseLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 3 * 24 * 3600_000,
+      reportedSize: 50_000_000,
+      tail,
+    })
+
+    const entry = h.watcher.getRegistry().get(agentId)
+    expect(entry?.historical).toBe(true)
+    expect(entry?.state).toBe('running')             // never promoted, never done
+    expect(h.fileWatchers()).toHaveLength(0)          // no FD leak for a dead worker
+    expect(h.terminalCleanups).not.toContain(agentId) // nothing terminal to sweep
+
+    // The disk read was BOUNDED to the tail window — the 50 MB file was NEVER
+    // read from byte 0 (that whole-transcript read is the ~7-min boot cost).
+    expect(h.reads.length).toBeGreaterThan(0)
+    for (const r of h.reads) {
+      expect(r.position).toBeGreaterThan(0)           // tail offset, not byte 0
+      expect(r.length).toBeLessThanOrEqual(512 * 1024)
+    }
+
+    h.watcher.stop()
+  })
+
+  it('done-at-boot-stale: still reaches terminal cleanup (onTerminalCleanup fires → feed row swept)', () => {
+    const agentId = 'deaddone'
+    // A stale JSONL whose tail ends in a turn_duration line → done at boot.
+    const tail = Buffer.from(`${toolUseLine()}\n${turnEndLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 3 * 24 * 3600_000,
+      reportedSize: 50_000_000,
+      tail,
+    })
+
+    const entry = h.watcher.getRegistry().get(agentId)
+    expect(entry?.historical).toBe(true)
+    expect(entry?.state).toBe('done')                 // detected terminal via the probe
+    expect(h.fileWatchers()).toHaveLength(0)           // no watcher for a done-at-boot worker
+    expect(h.terminalCleanups).toHaveLength(0)         // not yet — waits out the grace window
+
+    // Fire the scheduled terminal cleanup (30s grace) → onTerminalCleanup so the
+    // gateway sweeps the ghost feed row. THIS is the regression guard.
+    h.advance(30_000)
+    expect(h.terminalCleanups).toContain(agentId)
+
+    // Still bounded — the probe read only the tail, never the whole 50 MB file.
+    for (const r of h.reads) {
+      expect(r.position).toBeGreaterThan(0)
+      expect(r.length).toBeLessThanOrEqual(512 * 1024)
+    }
+
+    h.watcher.stop()
+  })
+
+  it('fresh in-flight-at-boot: full path — read from byte 0 and given an FSWatcher (no over-pruning)', () => {
+    const agentId = 'liveone'
+    const tail = Buffer.from(`${toolUseLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 30_000,                                  // 30s old — inside the freshness window
+      reportedSize: tail.length,
+      tail,
+    })
+
+    // Full path: the JSONL is read from byte 0 (the whole transcript) and a
+    // per-file FSWatcher is opened so live transitions are observed.
+    expect(h.reads.some((r) => r.position === 0)).toBe(true)
+    expect(h.fileWatchers()).toHaveLength(1)
+
+    h.watcher.stop()
+  })
+})

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

@@ -59,6 +59,7 @@ function makeHarness(opts: { agentId?: string } = {}) {
   const progressCalls: ProgressCall[] = []
   const finishCalls: Array<{ agentId: string; outcome: string }> = []
   const terminalCleanupCalls: string[] = []
+  const resumeCalls: Array<{ agentId: string; description: string }> = []
   const logs: string[] = []
 
   const agentDir = '/home/user/.switchroom/agents/myagent'
@@ -133,6 +134,7 @@ function makeHarness(opts: { agentId?: string } = {}) {
       progressCalls.push({ agentId: id, skeleton: skeleton === true, progressLine, toolCount }),
     onFinish: ({ agentId: id, outcome }) => finishCalls.push({ agentId: id, outcome }),
     onTerminalCleanup: (id) => terminalCleanupCalls.push(id),
+    onResume: (id, description) => resumeCalls.push({ agentId: id, description }),
     now: () => currentTime,
     setInterval: (fn, ms) => {
       const ref = nextRef++
@@ -191,6 +193,7 @@ function makeHarness(opts: { agentId?: string } = {}) {
     progressCalls,
     finishCalls,
     terminalCleanupCalls,
+    resumeCalls,
     logs,
     advance,
     watcher,
@@ -240,6 +243,13 @@ describe('subagent-watcher resume re-registration (issue #3315)', () => {
     expect(revived!.historical).toBe(false)
     expect(h.logs.some((l) => l.includes('resumed after terminal cleanup') && l.includes(agentId))).toBe(true)
 
+    // Issue #3373: onResume fired exactly once for the resumed worker, BEFORE
+    // registration re-fires onProgress — this is what clears the feed's terminal
+    // `finalized` latch so the resumed cues re-surface a card instead of being
+    // swallowed. (The feed-side re-surface behaviour is covered in
+    // worker-activity-feed.test.ts.)
+    expect(h.resumeCalls.filter((c) => c.agentId === agentId)).toHaveLength(1)
+
     // Progress cues resume (the card updates again) — the user-visible fix.
     expect(h.progressCalls.length).toBeGreaterThan(progressBeforeResume)
     expect(h.progressCalls.slice(progressBeforeResume).some((c) => c.agentId === agentId)).toBe(true)
@@ -285,6 +295,10 @@ describe('subagent-watcher resume re-registration (issue #3315)', () => {
     expect(h.progressCalls).toHaveLength(progressAfterCleanup) // no card churn
     // Cleanup fired exactly once — no leaked/duplicated terminal sweep.
     expect(h.terminalCleanupCalls.filter((id) => id === agentId)).toHaveLength(1)
+    // Issue #3373 anti-zombie: a genuinely-finished worker that never grew past
+    // its terminal boundary must NEVER fire onResume — otherwise the feed's
+    // finalized latch would be cleared and a dead worker could zombie-resurface.
+    expect(h.resumeCalls.filter((c) => c.agentId === agentId)).toHaveLength(0)
 
     h.watcher.stop()
   })

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

@@ -647,6 +647,36 @@ describe('startSubagentWatcher', () => {
       h.poll()
       // The draft is staged, not yet resolved — no cue yet.
       // The very next event is a reply tool with matching text → SUPPRESS.
+      // #3231: feed the PREFIXED prod wire shape (mcp__…__stream_reply), the
+      // form real jsonl actually carries. Before the isReplyTool fix a bare
+      // REPLY_TOOLS.has() missed this and the draft was WRONGLY surfaced.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
+      }))
+      h.poll()
+      expect(narrativeCues.length).toBe(0)
+    })
+
+    it('narrative gate: a draft-then-reply sub_agent_text is SUPPRESSED with a BARE reply tool name too (#3231)', () => {
+      // Symmetric with the prefixed case above: bare 'stream_reply' can still
+      // arrive from non-MCP sources, so isReplyTool must match it as well.
+      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, skeleton }) => {
+          if (!skeleton && 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()
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
         message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
@@ -786,10 +816,11 @@ describe('startSubagentWatcher', () => {
       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.
+      // Final tool of the turn is stream_reply carrying the answer. #3231: use
+      // the PREFIXED prod wire shape so lastReplyText capture (isReplyTool) fires.
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
-        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
       }))
       h.poll()
       // Trailing text block (separate message) that drafts the delivered answer.
@@ -819,9 +850,10 @@ describe('startSubagentWatcher', () => {
       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.'
+      // #3231: prefixed prod wire shape.
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
-        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
       }))
       h.poll()
       appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('Done — cleaning up the worktree now.')))

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -261,6 +261,19 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
     new URL('../gateway/gateway.ts', import.meta.url),
     'utf8',
   )
+  // #2996 P4-A: the turn_flush backstop (redact → normalize → scrub on
+  // `capturedText`) moved VERBATIM into stream-render.ts with
+  // handleSessionEvent. The reply path's identical `...(text))` wrapper lives
+  // in outbound-send-path.ts (`normalizeOutboundBody`, #2996 P2). Parity is
+  // pinned across the two extracted homes.
+  const streamSrc = readFileSync(
+    new URL('../gateway/stream-render.ts', import.meta.url),
+    'utf8',
+  )
+  const replyModuleSrc = readFileSync(
+    new URL('../gateway/outbound-send-path.ts', import.meta.url),
+    'utf8',
+  )
 
   it('reply path: normalizes AFTER redact and BEFORE the voice scrub', () => {
     // #2996: the reply-path entry pipeline moved into outbound-send-path.ts
@@ -290,13 +303,13 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   })
 
   it('turn-flush backstop: applies the SAME normalization in the SAME slot (REDS if the line is removed)', () => {
-    const redactIdx = gatewaySrc.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
+    const redactIdx = streamSrc.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
     // The normalization call the reply path uses, verbatim, on the turn_flush
     // variable. This indexOf is what returns -1 (→ assertion fails) if the
     // `stripExcessBold(normalizePunctuation(capturedText))` line is deleted
     // from the turn_flush branch.
-    const normIdx = gatewaySrc.indexOf('stripExcessBold(normalizePunctuation(capturedText))', redactIdx)
-    const scrubIdx = gatewaySrc.indexOf('scrubVoice(capturedText)', redactIdx)
+    const normIdx = streamSrc.indexOf('stripExcessBold(normalizePunctuation(capturedText))', redactIdx)
+    const scrubIdx = streamSrc.indexOf('scrubVoice(capturedText)', redactIdx)
     expect(redactIdx).toBeGreaterThan(0)
     expect(normIdx).toBeGreaterThan(redactIdx) // normalize AFTER the turn_flush redact
     expect(scrubIdx).toBeGreaterThan(normIdx) // ...and BEFORE the voice scrub — mirrors reply
@@ -305,8 +318,8 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   it('both send sites share the identical `stripExcessBold(normalizePunctuation(` wrapper', () => {
     // Parity, structurally: the exact normalization wrapper the reply path uses
     // is the one the turn_flush branch uses — same call, not a lookalike.
-    expect(gatewaySrc).toContain('stripExcessBold(normalizePunctuation(text))')
-    expect(gatewaySrc).toContain('stripExcessBold(normalizePunctuation(capturedText))')
+    expect(replyModuleSrc).toContain('stripExcessBold(normalizePunctuation(text))')
+    expect(streamSrc).toContain('stripExcessBold(normalizePunctuation(capturedText))')
   })
 
   // Behavioural coverage (kept from the original suite): reconstruct the
@@ -678,3 +691,168 @@ describe('selectFlushDeliveryText — deliver the terminal answer, strip only na
     }
   })
 })
+
+// ── #3237: STRUCTURAL block-provenance discriminator ───────────────────────
+// The opener heuristic cannot tell a narration preamble from a real answer
+// paragraph that merely opens with "Let me explain…". The structural flag
+// (`followedByToolUse`, = `!lastInMessage`) can: a narration preamble is
+// followed by a tool_use in its message; a terminal answer paragraph is not.
+describe('selectFlushDeliveryText — structural provenance (followedByToolUse) #3237', () => {
+  // The exact real-answer shape from #3237: a genuine two-paragraph answer
+  // whose FIRST block opens with a narration phrase, written as plain text with
+  // NO tool calls (the model forgot the reply tool → flush path). Structure
+  // says neither block was followed by a tool_use, so nothing is narration.
+  const p1 =
+    'Let me explain how the flush path works: it fires at turn_end when the ' +
+    'model never called the reply tool, joining the captured assistant text ' +
+    'blocks with a paragraph break so the answer renders with real separation.'
+  const p2 =
+    'The terminal block is always delivered, so the answer is never fully ' +
+    'lost — but the opening paragraph could be dropped by the opener-only strip.'
+
+  it('#3237 regression: a real 2-paragraph answer opening with "Let me explain…" is NOT truncated when structure says neither block was followed by a tool_use', () => {
+    // With NO structural signal (legacy string[]) the opener strip DROPS p1.
+    expect(selectFlushDeliveryText([p1, p2])).toBe(p2) // documents the bug
+    // With structure present ([false,false]) the full answer is delivered.
+    const out = selectFlushDeliveryText([p1, p2], [false, false])
+    expect(out).toBe(`${p1}\n\n${p2}`)
+    expect(out).toContain('Let me explain how the flush path works')
+  })
+
+  it('duplicate-reply fix preserved: a narration block FOLLOWED by a tool_use is stripped, terminal answer delivered', () => {
+    const narration = 'Let me pull the numbers together before I answer.'
+    const realAnswer = 'Revenue was 4.2M, up 12% year over year.'
+    // followedByToolUse[0]=true (the model drafted then acted), [1]=false (terminal).
+    const out = selectFlushDeliveryText([narration, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Let me pull the numbers')
+  })
+
+  it('structure alone drives the strip — a preamble the opener regex would MISS is still stripped when it was followed by a tool_use', () => {
+    // "Here are the figures" matches no NARRATION_OPENER, but a tool_use
+    // followed it → structural narration → stripped.
+    const preamble = 'Here are the figures you asked about.'
+    const realAnswer = 'The three services are all green.'
+    const out = selectFlushDeliveryText([preamble, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Here are the figures')
+  })
+
+  it('structure WINS over the opener heuristic — a "Let me…" opener NOT followed by a tool_use is kept (never truncated)', () => {
+    const first = 'Let me walk you through the three steps in order.'
+    const second = 'Step one is to branch off fresh main.'
+    // Opener-only would strip `first`; structure ([false,false]) keeps it.
+    expect(selectFlushDeliveryText([first, second], [false, false])).toBe(
+      `${first}\n\n${second}`,
+    )
+  })
+
+  it('per-block fallback: an UNDEFINED entry falls back to the opener heuristic for that block only', () => {
+    const narration = 'Let me check that.'
+    const realAnswer = 'Done — all green.'
+    // meta[0] undefined → fall back to isNarrationBlock("Let me check that.") = true → stripped.
+    const out = selectFlushDeliveryText([narration, realAnswer], [undefined, false])
+    expect(out).toBe(realAnswer)
+  })
+
+  it('flag-absent back-compat: omitting the meta array reproduces today\'s opener-strip EXACTLY', () => {
+    // Every legacy case behaves identically with no meta argument.
+    expect(selectFlushDeliveryText(['Let me check.', 'the answer'])).toBe('the answer')
+    expect(selectFlushDeliveryText(['Checking now…', 'The build is green.'])).toBe(
+      'The build is green.',
+    )
+    expect(selectFlushDeliveryText([p1, p2])).toBe(p2) // opener strip drops p1
+    const first = 'B'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS + 5)
+    const last = 'C'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS + 5)
+    expect(selectFlushDeliveryText([first, last])).toBe(`${first}\n\n${last}`)
+  })
+
+  it('meta stays ALIGNED across the empty-block filter (zip-before-filter)', () => {
+    // An empty block between narration and answer must not shift the meta index.
+    const narration = 'Let me look that up.'
+    const realAnswer = 'The value is 42.'
+    // blocks[1] is empty (dropped); meta must still map [narration→true, ''→_, answer→false].
+    const out = selectFlushDeliveryText([narration, '   ', realAnswer], [true, false, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Let me look that up')
+  })
+
+  it('cross-message shape: narration (msg1, tool_use after) + answer (msg2, terminal) → narration stripped', () => {
+    // lastInMessage semantics are per-message; a narration that is the last text
+    // of msg1 but has a tool_use after it in msg1 is followedByToolUse=true.
+    const narration = 'Let me search the codebase for the symbol.'
+    const realAnswer = 'It is defined in session-tail.ts.'
+    const out = selectFlushDeliveryText([narration, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+  })
+
+  it('decideTurnFlush plumbs capturedBlockMeta through to the strip (#3237 end-to-end)', () => {
+    // Real-answer case: structure keeps both paragraphs.
+    const keep = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: [p1, p2],
+      capturedBlockMeta: [false, false],
+    })
+    expect(keep.kind).toBe('flush')
+    if (keep.kind === 'flush') expect(keep.text).toBe(`${p1}\n\n${p2}`)
+
+    // Narration case: structure strips the preamble.
+    const strip = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: ['Let me pull the numbers.', 'Revenue was 4.2M.'],
+      capturedBlockMeta: [true, false],
+    })
+    expect(strip.kind).toBe('flush')
+    if (strip.kind === 'flush') expect(strip.text).toBe('Revenue was 4.2M.')
+  })
+
+  // Regression for the post-#3338 review finding: a SUBSTANTIAL real-content
+  // block (≥ FLUSH_SUBSTANTIVE_MIN_CHARS, NOT narration-shaped) that happens to
+  // be followed by a tool_use must be KEPT — the model can write a real answer
+  // paragraph, then call a memory/verify tool, then a short wrap-up. Trusting
+  // followedByToolUse ALONE (the pre-fix behaviour) dropped the real answer and
+  // delivered only the wrap-up. The structural strip is gated by the substantive
+  // floor, so the substantial block survives.
+  it('substantial real-content block followed by a tool_use is KEPT (structural flag gated by the substantive floor)', () => {
+    const realAnswer =
+      'The migration completed cleanly across all five shards: each shard was ' +
+      'drained, the schema applied under an advisory lock, and traffic cut back ' +
+      'over with zero dropped requests. The new index brought the p99 query time ' +
+      'down from 840ms to 60ms, and the old columns are now safe to remove in ' +
+      'the next release once the read path is confirmed off them entirely.'
+    expect(realAnswer.length).toBeGreaterThanOrEqual(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    // Not narration-shaped: no first-person "about to do X" opener, no
+    // trailing ellipsis/colon — so only the structural flag could strip it.
+    const wrapUp = 'Saved that to memory.'
+    // meta[0]=true (a memory tool_use followed the real answer), [1]=false.
+    const out = selectFlushDeliveryText([realAnswer, wrapUp], [true, false])
+    expect(out).toBe(`${realAnswer}\n\n${wrapUp}`)
+    expect(out).toContain('The migration completed cleanly')
+
+    // End-to-end through decideTurnFlush.
+    const decision = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: [realAnswer, wrapUp],
+      capturedBlockMeta: [true, false],
+    })
+    expect(decision.kind).toBe('flush')
+    if (decision.kind === 'flush') {
+      expect(decision.text).toBe(`${realAnswer}\n\n${wrapUp}`)
+    }
+  })
+
+  // A SHORT block followed by a tool_use is still stripped via the length floor
+  // (the pre-#3237 "short preamble the opener misses" behaviour is preserved):
+  // it is below FLUSH_SUBSTANTIVE_MIN_CHARS, so the gated strip still fires.
+  it('short block followed by a tool_use is still stripped (length-floor branch of the gate)', () => {
+    const shortPreamble = 'Here are the figures you asked about.'
+    expect(shortPreamble.length).toBeLessThan(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    const realAnswer = 'The three services are all green.'
+    const out = selectFlushDeliveryText([shortPreamble, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Here are the figures')
+  })
+})

package/telegram-plugin/tests/turn-flush-suppression-wiring.test.ts

@@ -22,6 +22,11 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+// #2996 P4-A: the turn-flush / turn_end / `thinking`-arm code moved VERBATIM
+// into stream-render.ts with handleSessionEvent. Windows that used to live in
+// the gateway switch are grepped from the extracted module now.
+const streamSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'stream-render.ts'), 'utf-8')
+const gatewayAndStreamSrc = gatewaySrc + '\n' + streamSrc
 
 function between(src: string, startMarker: string, endMarker: string): string {
   const after = src.split(startMarker)[1] ?? ''
@@ -42,7 +47,7 @@ describe('S1 wiring — turn-flush suppression call site', () => {
   // The whole suppression branch: predicate call through the end of the
   // `if (suppress)` early-return.
   const branch = between(
-    gatewaySrc,
+    streamSrc,
     'const { shouldSuppressTurnFlush }',
     '// #3276 guard 5',
   )
@@ -72,7 +77,7 @@ describe('S1 wiring — turn-flush suppression call site', () => {
   it('the old predicate is gone from the whole gateway turn-flush path', () => {
     // getRecentOutboundCount must not be consulted anywhere in gateway.ts —
     // any reintroduction re-opens the chat-wide suppression class.
-    expect(codeOnly(gatewaySrc)).not.toMatch(/getRecentOutboundCount/)
+    expect(codeOnly(gatewayAndStreamSrc)).not.toMatch(/getRecentOutboundCount/)
   })
 })
 
@@ -81,7 +86,7 @@ describe('S2 wiring — thinking events re-arm the answer-ready quiescence flush
     // Without this, "prose → >1s thinking pause → trailing NO_REPLY" lets the
     // quiescence timer fire mid-pause and deliver a turn the model intended
     // silent. Scope to the thinking case arm only.
-    const arm = between(gatewaySrc, "case 'thinking': {", "case 'tool_use': {")
+    const arm = between(streamSrc, "case 'thinking': {", "case 'tool_use': {")
     expect(arm.length).toBeGreaterThan(50)
     expect(codeOnly(arm)).toMatch(/resetAnswerReadyFlushTimeout\(\)/)
   })
@@ -107,6 +112,6 @@ describe('S4 wiring — flushed answers quote-anchor to the inbound they answer'
   it('the turn-flush call site passes the turn’s inbound id (bare for synthesized turns)', () => {
     // The anchor must be the message this TURN answers — turn.sourceMessageId
     // is null for cron/handback turns, which therefore still send bare.
-    expect(codeOnly(gatewaySrc)).toMatch(/replyToMessageId:\s*turn\.sourceMessageId/)
+    expect(codeOnly(gatewayAndStreamSrc)).toMatch(/replyToMessageId:\s*turn\.sourceMessageId/)
   })
 })

package/telegram-plugin/tests/vault-approval-posture.test.ts

@@ -48,7 +48,10 @@ import { resolveVaultApprovalPosture } from '../vault-approval-posture.js'
 const gatewaySrc =
   readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
   '\n' +
-  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8') +
+  '\n' +
+  // P7 PR-8 (#2996): vault pending-op intercept moved to inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, '..', 'gateway', 'inbound-interceptors.ts'), 'utf-8')
 
 function sliceAccessApproveBlock(): string {
   const fn =
@@ -102,7 +105,10 @@ describe('handleVaultRequestAccessCallback — posture branch', () => {
     expect(approveBlock).toMatch(/passphrase-for-access-approve/)
     // Pinned: the queued-drain path passes the typed passphrase via
     // the new attestation shape `{ kind: 'passphrase', passphrase }`.
-    expect(gatewaySrc).toMatch(/performVaultAccessApproval\(ctx, stagedAccess, item\.stageId, item\.senderId, \{ kind: ['"]passphrase['"], passphrase \}\)/)
+    // P7 PR-8: the queued-drain call site moved into interceptVault
+    // (inbound-interceptors.ts) — ctx is `p.ctx` and the handler resolves via
+    // the lazy deps accessor. Same attestation shape pinned.
+    expect(gatewaySrc).toMatch(/performVaultAccessApproval\((?:p\.)?ctx, stagedAccess, item\.stageId, item\.senderId, \{ kind: ['"]passphrase['"], passphrase \}\)/)
   })
 })
 

package/telegram-plugin/tests/vault-grant-union.test.ts

@@ -29,7 +29,10 @@ import { resolve } from "node:path";
 const gatewaySrc =
   readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
   "\n" +
-  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8") +
+  "\n" +
+  // P7 PR-8 (#2996): vault pending-op intercept moved to inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, "..", "gateway", "inbound-interceptors.ts"), "utf-8");
 
 function extractPerformBlock(): string {
   const start = gatewaySrc.indexOf("async function performVaultAccessApproval");