switchroom 0.18.20 → 0.18.22

package/telegram-plugin/tests/flushed-turn-supersede.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Unit coverage for the turnId-keyed flushed-turn supersede registry
+ * (2026-07 duplicate-reply fix).
+ *
+ * The regression these tests pin: the answer-ready quiescence flush (or the
+ * turn-end backstop) posts a turn's terminal text as a Telegram message, then
+ * the model's REAL `reply` tool call for the SAME turn lands ~10 s later and
+ * ships a SECOND message. The pre-existing `OutboundDedupCache` misses this
+ * because it matches on EXACT text equality — a `narration\n\nanswer` flush
+ * never equals the clean `answer`-only reply.
+ *
+ * Identity-only supersede (adversarial-review HIGH fix): supersede fires ONLY
+ * when the landing reply is positively attributable to the flushed turn by
+ * turnId. A reply with an UNRESOLVED turn (`liveTurnId == null`) never deletes a
+ * turnId-bearing record — we never delete a message we can't attribute to the
+ * reply's own turn. The lane holds a per-turnId map, so two concurrent turns can
+ * each flush a message and each turn's reply supersedes ONLY its own.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  decideSupersede,
+  FlushedTurnSupersedeRegistry,
+  DEFAULT_SUPERSEDE_TTL_MS,
+  type FlushedTurnRecord,
+} from '../flushed-turn-supersede.js'
+
+const rec = (over: Partial<FlushedTurnRecord> = {}): FlushedTurnRecord => ({
+  turnId: 'turn-A',
+  messageIds: [101, 102],
+  text: 'narration\n\nthe real answer',
+  ts: 1_000_000,
+  ...over,
+})
+
+describe('decideSupersede — the duplicate-reply decision core', () => {
+  it('supersedes when the reply is attributed to the SAME turn as the flush', () => {
+    // The common late-replay dup: the gateway resolves the reply's turnId (from
+    // origin_turn_id) even after currentTurn cleared, so it matches by identity.
+    const d = decideSupersede(rec({ turnId: 'turn-A' }), {
+      liveTurnId: 'turn-A',
+      now: 1_000_000 + 10_000,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.deleteMessageIds).toEqual([101, 102])
+    expect(d.reason).toBe('supersede')
+  })
+
+  it('does NOT supersede a reply belonging to a DIFFERENT turn', () => {
+    // A different turn is the resolved owner — it must never delete this turn's
+    // message. This is the guard that keeps the fix from eating a legit answer.
+    const d = decideSupersede(rec({ turnId: 'turn-A' }), {
+      liveTurnId: 'turn-B',
+      now: 1_000_000 + 500,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.deleteMessageIds).toEqual([])
+    expect(d.reason).toBe('different-turn')
+  })
+
+  it('does NOT supersede a turnId-bearing record when the reply turn is UNRESOLVED (liveTurnId == null)', () => {
+    // HIGH-finding core guard: a late reply we cannot attribute to a turn must
+    // NEVER delete a message that positively belongs to some turn. Pre-fix the
+    // null branch superseded ANY record — deleting a possibly-different turn's
+    // legitimate message.
+    const d = decideSupersede(rec({ turnId: 'turn-A' }), {
+      liveTurnId: null,
+      now: 1_000_000 + 10_000,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('different-turn')
+  })
+
+  it('does NOT supersede once the record is past its TTL', () => {
+    const d = decideSupersede(rec(), {
+      liveTurnId: 'turn-A',
+      now: 1_000_000 + DEFAULT_SUPERSEDE_TTL_MS + 1,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('expired')
+  })
+
+  it('returns no-record when there is nothing to supersede', () => {
+    const d = decideSupersede(undefined, { liveTurnId: null, now: 1_000_000 })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('no-record')
+  })
+
+  it('a null-turnId record is superseded ONLY by an equally-unresolved (null) reply', () => {
+    // A synthetic/no-nonce flush: only a reply that ALSO has no resolvable turn
+    // matches it — it never clobbers a turn we CAN identify.
+    const live = decideSupersede(rec({ turnId: null }), {
+      liveTurnId: 'turn-Z',
+      now: 1_000_000,
+    })
+    expect(live.supersede).toBe(false)
+    expect(live.reason).toBe('different-turn')
+
+    const unresolved = decideSupersede(rec({ turnId: null }), {
+      liveTurnId: null,
+      now: 1_000_000,
+    })
+    expect(unresolved.supersede).toBe(true)
+  })
+})
+
+describe('FlushedTurnSupersedeRegistry — record / peek / take lifecycle', () => {
+  it('records a flush and supersedes the same turn`s later reply end to end', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [7, 8], text: 'x' }, 1000)
+    const d = reg.take('chat1', undefined, { liveTurnId: 'turn-A', now: 5000 })
+    expect(d.supersede).toBe(true)
+    expect(d.deleteMessageIds).toEqual([7, 8])
+  })
+
+  it('take() CONSUMES the matched record so a replayed reply does not double-delete', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [7], text: 'x' }, 1000)
+    const first = reg.take('chat1', undefined, { liveTurnId: 'turn-A', now: 2000 })
+    expect(first.supersede).toBe(true)
+    // Replay of the same reply — the flushed message is already gone.
+    const second = reg.take('chat1', undefined, { liveTurnId: 'turn-A', now: 2001 })
+    expect(second.supersede).toBe(false)
+    expect(second.reason).toBe('no-record')
+  })
+
+  it('peek() does NOT consume — repeated peeks keep returning supersede', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [7], text: 'x' }, 1000)
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 2000 }).supersede).toBe(true)
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 2001 }).supersede).toBe(true)
+  })
+
+  it('does not record a flush that posted zero messages', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [], text: 'x' }, 1000)
+    expect(reg.take('chat1', undefined, { liveTurnId: 'turn-A', now: 2000 }).supersede).toBe(false)
+  })
+
+  it('keys per chat|thread — a flush in one thread never supersedes a reply in another', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    reg.record('chat1', 42, { turnId: 'turn-A', messageIds: [7], text: 'x' }, 1000)
+    // different thread, same chat
+    expect(reg.take('chat1', 99, { liveTurnId: 'turn-A', now: 2000 }).supersede).toBe(false)
+    // correct thread supersedes
+    expect(reg.take('chat1', 42, { liveTurnId: 'turn-A', now: 2000 }).supersede).toBe(true)
+  })
+
+  // ---- HIGH finding regression: wrong-delete via a null-turn late reply. ----
+  describe('HIGH regression — two concurrent turns on one lane', () => {
+    it('turn A`s late reply supersedes ONLY A`s flush, never turn B`s legitimate message', () => {
+      const reg = new FlushedTurnSupersedeRegistry()
+      // Turn A flushes msg 100.
+      reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [100], text: 'a' }, 1000)
+      // Turn B flushes msg 200 (B's real answer message).
+      reg.record('chat1', undefined, { turnId: 'turn-B', messageIds: [200], text: 'b' }, 1100)
+
+      // Turn A's real reply lands late, resolved (via origin_turn_id) to turn A.
+      const dA = reg.take('chat1', undefined, { liveTurnId: 'turn-A', now: 1200 })
+      expect(dA.supersede).toBe(true)
+      expect(dA.deleteMessageIds).toEqual([100]) // NOT [200] — B's message is untouched.
+
+      // B's own message is still independently supersedable by B's reply — proof
+      // A's reply did not consume or clobber B's record.
+      const dB = reg.take('chat1', undefined, { liveTurnId: 'turn-B', now: 1300 })
+      expect(dB.supersede).toBe(true)
+      expect(dB.deleteMessageIds).toEqual([200])
+    })
+
+    it('an UNRESOLVED (null-turn) late reply does NOT delete a different turn`s legitimate message', () => {
+      // This is the exact wrong-delete the review flagged. Pre-fix: single lane
+      // slot overwritten to {turn-B,[200]} + promiscuous null branch → the null
+      // reply superseded and DELETED msg 200 (B's good answer). Post-fix: a null
+      // liveTurnId matches no turnId-bearing record, so nothing is deleted.
+      const reg = new FlushedTurnSupersedeRegistry()
+      reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [100], text: 'a' }, 1000)
+      reg.record('chat1', undefined, { turnId: 'turn-B', messageIds: [200], text: 'b' }, 1100)
+
+      const d = reg.take('chat1', undefined, { liveTurnId: null, now: 1200 })
+      expect(d.supersede).toBe(false)
+      expect(d.deleteMessageIds).toEqual([])
+
+      // Both records survive — neither turn's message was wrongly deleted.
+      expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 1300 }).supersede).toBe(true)
+      expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-B', now: 1300 }).supersede).toBe(true)
+    })
+  })
+
+  it('size() evicts expired records and prunes emptied lanes', () => {
+    const reg = new FlushedTurnSupersedeRegistry({ ttlMs: 1000 })
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [1], text: 'a' }, 1000)
+    reg.record('chat1', undefined, { turnId: 'turn-B', messageIds: [2], text: 'b' }, 1000)
+    expect(reg.size(1500)).toBe(2)
+    expect(reg.size(3000)).toBe(0)
+  })
+
+  it('record() actively sweeps expired records (LOW-2 GC — no orphan accumulation)', () => {
+    const reg = new FlushedTurnSupersedeRegistry({ ttlMs: 1000 })
+    reg.record('chat1', undefined, { turnId: 'turn-A', messageIds: [1], text: 'a' }, 1000)
+    // A much later flush on a DIFFERENT lane sweeps the now-expired turn-A record.
+    reg.record('chat2', undefined, { turnId: 'turn-B', messageIds: [2], text: 'b' }, 5000)
+    // Only the fresh record remains; the orphan was swept, not left to leak.
+    expect(reg.size(5000)).toBe(1)
+    expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 5000 }).reason).toBe('no-record')
+  })
+})

package/telegram-plugin/tests/nested-worker-visibility-harness.test.ts

@@ -267,6 +267,26 @@ describe('nested (depth-2+) worker — end-to-end visibility harness', () => {
     expect(lastChild.text).not.toContain('starting…')
     expect(lastChild.text).toContain('index.ts')
 
+    // #3233 — DELIBERATE orchestrator-suppression behaviour. The depth-1
+    // 'depth-1 orchestrator' parent ran ZERO tools of its own: it only
+    // DISPATCHED the nested child. The skeleton first-paint cue (#3231) fires
+    // on every no-growth poll, so a naive implementation gives that pure
+    // orchestrator its OWN persistent "starting…" worker-feed row — redundant
+    // clutter, because the child's row already carries the liveness. The
+    // watcher suppresses the skeleton cue for any entry that has dispatched a
+    // child (parent_agent_id linkage), so the orchestrator NEVER earns a
+    // "starting…" row while its child provides the live signal. This is NOT a
+    // "0 own tools" rule (that would re-break the 205s-blackout incident this
+    // PR fixes — a leaf that blocks on its FIRST tool also has 0 completed
+    // tools and MUST still paint); it keys strictly on the parent/child link.
+    const allFeed = [...h.bot.sent, ...h.bot.edits]
+    const orchestratorStartingRows = allFeed.filter(
+      (m) => m.text.includes('depth-1 orchestrator') && m.text.includes('starting…'),
+    )
+    expect(orchestratorStartingRows.length).toBe(0)
+    // …while the child (a genuine leaf) DID surface real, live tool activity.
+    expect(childMsgs.some((m) => m.text.includes('index.ts'))).toBe(true)
+
     // More tool activity → climbing tool count, still live.
     h.appendWorker('child01', toolUse('t2', 'Bash', { command: 'ls -la /repo' }))
     h.advance(1000)

package/telegram-plugin/tests/subagent-progress-inbound-builder.test.ts

@@ -264,6 +264,36 @@ describe('decideSubagentProgress', () => {
     if (!d.deliver) expect(d.reason).toBe('foreground')
   })
 
+  // #3233 — worker-feed-DISABLED legacy path: a contentless skeleton liveness
+  // cue must NOT be relayed as a synthesized "still working" inbound (that
+  // would be a blank card). It degrades to a no-op, deterministically, BEFORE
+  // bucketing so it can never advance the bucket tracker.
+  it('skeleton liveness cue is dropped (no blank card) even when every other gate would pass', () => {
+    // Same input that DELIVERS in the happy-path test above (bucket 1, chat
+    // resolves) — only `skeleton` flips it off. Empty summary mirrors the real
+    // skeleton cue.
+    const d = decideSubagentProgress(baseInput({ skeleton: true, latestSummary: '' }))
+    expect(d.deliver).toBe(false)
+    if (!d.deliver) expect(d.reason).toBe('skeleton-liveness')
+  })
+
+  it('skeleton suppression fires before bucketing — a background skeleton at bucket>=1 never delivers', () => {
+    // ≤1 relay per interval is trivially satisfied: skeleton cues deliver ZERO
+    // inbounds regardless of how many no-growth polls fire within a bucket.
+    for (const elapsedMs of [7 * 60 * 1000, 8 * 60 * 1000, 9 * 60 * 1000]) {
+      const d = decideSubagentProgress(baseInput({ skeleton: true, latestSummary: '', elapsedMs }))
+      expect(d.deliver, `elapsedMs=${elapsedMs}`).toBe(false)
+    }
+  })
+
+  it('a NON-skeleton cue with identical inputs still delivers (guard is skeleton-scoped, not summary-scoped)', () => {
+    // Red-on-regression companion: proves the drop keys on `skeleton`, not on
+    // the empty summary — a real tool-only cue (empty prose summary) still
+    // delivers, so the guard cannot silently swallow genuine progress.
+    const d = decideSubagentProgress(baseInput({ skeleton: false, latestSummary: '' }))
+    expect(d.deliver).toBe(true)
+  })
+
   it('falls back to owner chat when fleet chat is empty', () => {
     const d = decideSubagentProgress(baseInput({ fleetChatId: '' }))
     expect(d.deliver).toBe(true)

package/telegram-plugin/tests/subagent-watcher-first-paint-independence.test.ts

@@ -0,0 +1,171 @@
+/**
+ * First-paint independence (#3231) regression.
+ *
+ * LIVE BUG (a57fbf, 2026-07-13): an async foreground sub-agent registered at
+ * 13:17:27, did two Bash calls, then its first tool BLOCKED for ~99s (no JSONL
+ * growth). Its spawning turn ended at 13:17:48 while it kept running, so there
+ * was neither a live parent turn to nest into NOR a worker-feed row to paint —
+ * and because the worker card is driven ONLY by growth-triggered onProgress
+ * cues, NOTHING surfaced. The card did not appear until 13:20:52, 205s after
+ * registration, on the next growth event that happened to route to the feed.
+ *
+ * The watcher's contract fix: a running, non-historical entry must emit a
+ * growth-INDEPENDENT skeleton liveness cue on every no-growth poll — an empty
+ * step line carrying the entry's real current state — so the gateway can paint
+ * (and keep alive) the card from registration onward, regardless of whether the
+ * worker's JSONL is currently growing. The gateway routes it: inert on the
+ * foreground-nest path (empty child), row-creating on the orphan/background
+ * worker-feed path.
+ *
+ * These assert OUTCOMES on the onProgress cue stream with an INJECTED clock.
+ * A skeleton cue is identified by its explicit `skeleton: true` discriminator
+ * (it also carries an empty `latestSummary` and no `progressLine`).
+ *
+ * RED-ON-REGRESSION: before the fix, readSubTail early-returns on a no-growth
+ * poll BEFORE firing any onProgress cue, so ZERO skeleton cues are emitted and
+ * every assertion below fails — reproducing the invisible-card window.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentToolUse(name: string, id: string) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
+}
+
+interface Cue { agentId: string; progressLine?: string; latestSummary: string; elapsedMs: number; skeleton?: boolean }
+
+describe('sub-agent card first-paint independence (#3231)', () => {
+  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 = ''
+    }
+  })
+
+  const RESCAN_MS = 1000
+
+  function startWatcher(agentDir: string) {
+    let currentTime = 100_000
+    const cues: Cue[] = []
+    const intervals: Array<{ fn: () => void; ref: number }> = []
+    let nextRef = 1
+    const watcher = startSubagentWatcher({
+      agentDir,
+      onFinish: () => {},
+      onProgress: ({ agentId, progressLine, latestSummary, elapsedMs, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, elapsedMs, skeleton })
+      },
+      stallThresholdMs: 600_000,
+      silentSynthesisStallThresholdMs: 600_000,
+      rescanMs: RESCAN_MS,
+      now: () => currentTime,
+      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: () => ({ ref: nextRef++ }),
+      clearTimeout: () => {},
+      log: () => {},
+    })
+    started.push(watcher)
+    return {
+      watcher,
+      cues,
+      poll: () => intervals[0]?.fn(),
+      advance: (ms: number) => { currentTime += ms },
+      now: () => currentTime,
+    }
+  }
+
+  const skeletonCues = (cues: Cue[]): Cue[] =>
+    cues.filter((c) => c.skeleton === true)
+
+  function makeSubagentDir(root: string): string {
+    const agentDir = join(root, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    return agentDir
+  }
+
+  it('emits a growth-independent skeleton cue on the first no-growth poll after registration', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-deadbeef.jsonl')
+
+    // Start the watcher on an empty subagents dir, THEN the worker spawns — the
+    // real async Agent-tool path (the JSONL appears post-boot, so the entry is
+    // live/non-historical, not a boot-time rediscovery). Only its prompt is on
+    // disk, no assistant output yet (it is "thinking"): the pre-content window
+    // the user stares at.
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // Next poll: the JSONL has NOT grown. Pre-fix, readSubTail early-returns and
+    // NO cue fires — the card is invisible. Post-fix, a skeleton cue surfaces so
+    // the gateway can paint the card without waiting for the worker's output.
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    const skel = skeletonCues(h.cues)
+    expect(skel.length, 'a skeleton cue must fire on a no-growth poll').toBeGreaterThanOrEqual(1)
+    // Tight bound vs the ~205s live behaviour: first cue is within a couple polls
+    // of registration, NOT minutes.
+    expect(skel[0].elapsedMs).toBeLessThanOrEqual(2 * RESCAN_MS)
+  })
+
+  it('keeps surfacing skeleton cues while a worker is silent after an early tool burst (blocked first tool)', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-silent-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-a57fbf00.jsonl')
+
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Debug delegation regression')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // The worker does two quick Bash calls (the a57fbf shape) …
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+    h.advance(RESCAN_MS)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b2')))
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    // … then its tool BLOCKS: no JSONL growth for a long stretch (~30 polls).
+    // The card must NOT go dark — a skeleton cue must fire on essentially every
+    // no-growth poll so the feed row is created/kept-alive and the heartbeat can
+    // climb the elapsed. Pre-fix, zero cues fire across the entire silent window.
+    const before = h.cues.length
+    for (let i = 0; i < 30; i++) {
+      h.advance(RESCAN_MS)
+      h.poll()
+    }
+    const duringSilence = h.cues.slice(before)
+    const skel = duringSilence.filter((c) => c.skeleton === true)
+    expect(skel.length, 'silent worker must keep emitting skeleton cues').toBeGreaterThanOrEqual(20)
+    // No skeleton cue ever fabricates content — the step line stays empty.
+    for (const c of skel) expect(c.latestSummary).toBe('')
+  })
+})

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

@@ -39,7 +39,7 @@ function subAgentToolUse(name: string, id: string) {
   return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
 }
 
-interface Cue { progressLine?: string; latestSummary: string }
+interface Cue { progressLine?: string; latestSummary: string; skeleton?: boolean }
 
 describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
   let tmpRoot = ''
@@ -64,8 +64,8 @@ describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
     const watcher = startSubagentWatcher({
       agentDir,
       onFinish: () => {},
-      onProgress: ({ agentId, progressLine, latestSummary }) => {
-        cues.push({ agentId, progressLine, latestSummary })
+      onProgress: ({ agentId, progressLine, latestSummary, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, skeleton })
       },
       stallThresholdMs: 600_000,
       silentSynthesisStallThresholdMs: 600_000,
@@ -91,8 +91,10 @@ describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
   }
 
   function narrativeCues(cues: Cue[]): string[] {
-    // Narrative cues carry NO progressLine; tool-label cues do.
-    return cues.filter((c) => c.progressLine == null).map((c) => c.latestSummary)
+    // Narrative cues carry NO progressLine; tool-label cues do. Skeleton
+    // liveness cues (#3231) also carry no progressLine but an empty summary —
+    // exclude them here so this counts only real narrative content.
+    return cues.filter((c) => !c.skeleton && c.progressLine == null).map((c) => c.latestSummary)
   }
 
   it('paints a parked opening narration after the flush window with NO tool event', () => {

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

@@ -584,9 +584,10 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
           // Narrative ticks carry NO progressLine (tool ticks do); record them.
-          if (progressLine == null) narrativeCues.push(latestSummary)
+          // Skeleton liveness cues (#3231) are not narrative — exclude them.
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo path')))
@@ -614,8 +615,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -647,8 +648,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          allCues.push({ progressLine, latestSummary })
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton) allCues.push({ progressLine, latestSummary })
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -698,8 +699,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
@@ -728,8 +729,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
@@ -761,8 +762,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))

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

@@ -21,6 +21,8 @@ import {
   isCompositeSilentNoise,
   endsWithSilentMarker,
   isTurnFlushSafetyEnabled,
+  selectFlushDeliveryText,
+  FLUSH_SUBSTANTIVE_MIN_CHARS,
 } from '../turn-flush-safety.js'
 // Rich-message send-path primitives (Bot API 10.1, #2669/#2692). The #2798
 // regression suite below reconstructs the exact gateway turn-flush render
@@ -571,3 +573,72 @@ describe('isTurnFlushSafetyEnabled', () => {
     }
   })
 })
+
+describe('selectFlushDeliveryText — deliver the terminal answer, strip only narration', () => {
+  const answer = 'A'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS + 20)
+
+  it('delivers ONLY the terminal answer when narration precedes the answer', () => {
+    // The duplicate-reply root cause: the flush fired while the model was still
+    // composing its reply, so capturedText held intent-narration blocks THEN
+    // the composed answer. Pre-fix the flush dumped the whole blob; post-fix it
+    // delivers only the answer. This test FAILS on the pre-fix `join('\n\n')`.
+    const blocks = ["Let me check that.", "I'll look it up now.", answer]
+    const out = selectFlushDeliveryText(blocks)
+    expect(out).toBe(answer)
+    expect(out).not.toContain('Let me check')
+    expect(out).not.toContain("I'll look it up")
+  })
+
+  // MEDIUM finding (adversarial review): a LONG (>=200) narration block FOLLOWED
+  // by a SHORT (<200) real answer. The pre-fix `find last block >= 200` returned
+  // the narration and DROPPED the short real answer. The terminal block is the
+  // answer regardless of length. FAILS on the pre-fix threshold scan.
+  it('delivers a SHORT real answer that follows a LONG (>=200) narration block', () => {
+    const verboseNarration =
+      'Let me pull the numbers together before I answer — ' +
+      'X'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    const realAnswer = 'Revenue was 4.2M, up 12% year over year.' // < 200 chars
+    expect(verboseNarration.length).toBeGreaterThanOrEqual(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    expect(realAnswer.length).toBeLessThan(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    const out = selectFlushDeliveryText([verboseNarration, realAnswer])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Let me pull the numbers')
+  })
+
+  it('keeps the FULL joined text when an earlier block is real content, never truncating to the last paragraph', () => {
+    // Two substantive blocks, neither an intent-narration opener: this is a
+    // genuine multi-paragraph answer written as several blocks. Delivering only
+    // the last paragraph would drop real content — keep the whole thing.
+    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('keeps short two-paragraph answers joined (short legit answer preserved)', () => {
+    const blocks = ['First short paragraph.', 'Second short paragraph.']
+    expect(selectFlushDeliveryText(blocks)).toBe('First short paragraph.\n\nSecond short paragraph.')
+  })
+
+  it('a single block is delivered verbatim regardless of length', () => {
+    expect(selectFlushDeliveryText(['short answer'])).toBe('short answer')
+    expect(selectFlushDeliveryText([answer])).toBe(answer)
+  })
+
+  it('trims and drops empty blocks', () => {
+    expect(selectFlushDeliveryText(['  ', '', '  hi  '])).toBe('hi')
+    expect(selectFlushDeliveryText([])).toBe('')
+  })
+
+  it('decideTurnFlush delivers the narrowed answer, not the whole blob', () => {
+    const decision = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: ['Let me check.', 'Now let me compose the reply.', answer],
+    })
+    expect(decision.kind).toBe('flush')
+    if (decision.kind === 'flush') {
+      expect(decision.text).toBe(answer)
+      expect(decision.text).not.toContain('Let me check')
+    }
+  })
+})