switchroom 0.18.21 → 0.18.22

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

@@ -0,0 +1,230 @@
+/**
+ * Turn-flush supersede registry (2026-07 duplicate-reply fix).
+ *
+ * The duplicate-reply class this closes:
+ *
+ *   1. A turn-flush (the answer-ready quiescence flush OR the older turn-end
+ *      backstop) posts the model's terminal text as a Telegram message, because
+ *      the turn appeared to end without a `reply` tool call.
+ *   2. ~10 s later the model's REAL `reply` tool call lands (it was still
+ *      composing it when the flush fired, or claude-code replayed an un-acked
+ *      tool_call after a bridge reconnect).
+ *   3. The gateway sends that as a SECOND message → the user sees a duplicate.
+ *
+ * The pre-existing `OutboundDedupCache` did NOT catch this because it matches on
+ * EXACT normalised-text equality: a flush that dumped `narration\n\nanswer`
+ * never equals the clean `answer`-only reply, so the containment case slipped
+ * through (216 occurrences in older logs via the turn-end backstop alone).
+ *
+ * This registry SUBSTANTIALLY REDUCES the class, keyed on the turn IDENTITY
+ * (the per-turn `turnId` nonce) rather than on text. When a flush sends, it
+ * records `{ turnId, messageIds }` for the chat/thread. When a `reply` for the
+ * SAME turn later lands, the gateway SUPERSEDES the flushed message(s) — deletes
+ * them and lets the canonical reply send path deliver exactly one clean message
+ * (delete+resend; the caller may also edit-in-place). A reply for a DIFFERENT
+ * (newer) turn never supersedes — that turn owns its own message.
+ *
+ * NOT fully deterministic — a residual race remains. The flush→reply direction
+ * this registry covers, plus the controller's fire-time recount for the
+ * reply→flush direction, close the COMMON ~10 s replay-gap case; but if a reply
+ * and a flush interleave so the reply's `take()` runs BEFORE the flush's
+ * `record()` (a much smaller window), `take` finds no record and the duplicate
+ * can still slip through. We deliberately trade that residual window for the
+ * safety guarantee that we NEVER delete a message we cannot positively attribute
+ * to the reply's own turn (identity-only supersede — see `decideSupersede`).
+ *
+ * Pure module: no I/O, no globals, no clock reads beyond the caller-supplied
+ * `now`. Fully unit-testable; the gateway wires the actual delete/send.
+ */
+
+/** TTL after which a recorded flush is forgotten. 60 s comfortably spans the
+ *  observed ~10 s flush→reply replay gap with margin, and matches the outbound
+ *  dedup window so the two mechanisms age out together. */
+export const DEFAULT_SUPERSEDE_TTL_MS = 60_000
+
+export interface FlushedTurnRecord {
+  /** The per-turn `turnId` nonce (`deriveTurnId` shape) of the flushed turn.
+   *  Keying on this — NOT the stable `chatId:threadId` statusKey — is what makes
+   *  the supersede turn-identity-scoped: a later, unrelated turn on the same
+   *  chat has a different `turnId` and must NOT clobber this record's message. */
+  turnId: string | null
+  /** The Telegram message id(s) the flush posted (edit target + any extra
+   *  chunk messages). Superseding deletes all of them. */
+  messageIds: number[]
+  /** The text the flush delivered — retained for diagnostics/logging only. The
+   *  supersede decision NEVER compares text (that is the whole point: it fires
+   *  even when the flushed text differs from the reply text). */
+  text: string
+  /** Wall-clock ms when recorded. */
+  ts: number
+}
+
+/**
+ * The supersede decision for a landing reply. Pure so the gateway runs the
+ * exact code the regression tests exercise (`gateway.ts` is not importable in
+ * tests — the repo's `decideTurnFlush` / `decideCapturedProseDelivery` pattern).
+ */
+export interface SupersedeDecision {
+  /** True → the reply belongs to an already-flushed turn; the gateway must
+   *  delete `deleteMessageIds` and deliver the reply as the single message. */
+  supersede: boolean
+  /** Message ids the gateway must delete before/instead of the fresh send.
+   *  Empty when `supersede` is false. */
+  deleteMessageIds: number[]
+  /** Machine-readable reason (for logs / tests). */
+  reason: 'supersede' | 'no-record' | 'expired' | 'different-turn'
+}
+
+/**
+ * Decide whether a landing reply supersedes a recorded flush.
+ *
+ * Supersede IFF the record is present, fresh (within TTL), AND positively
+ * attributable to the reply's turn by IDENTITY:
+ *   - a turnId-bearing record is superseded ONLY by a reply whose resolved
+ *     `liveTurnId` equals `record.turnId`;
+ *   - a null-turnId record (a synthetic/no-nonce flush) is superseded ONLY by a
+ *     reply that ALSO has no resolvable turn (`liveTurnId == null`).
+ *
+ * Crucially, a reply with `liveTurnId == null` does NOT supersede a
+ * turnId-bearing record: we never delete a message we cannot positively
+ * attribute to the reply's own turn. (The earlier revision superseded ANY
+ * record on a null live turn, which — combined with a single overwriting lane
+ * slot — could late-delete a DIFFERENT turn's legitimate message. The gateway
+ * now resolves a last-known turnId for the reply before calling in, so the
+ * common late-replay case still matches by identity rather than relying on the
+ * promiscuous null branch.)
+ */
+export function decideSupersede(
+  record: FlushedTurnRecord | undefined,
+  args: { liveTurnId: string | null; now: number; ttlMs?: number },
+): SupersedeDecision {
+  const ttlMs = args.ttlMs ?? DEFAULT_SUPERSEDE_TTL_MS
+  if (record == null) return { supersede: false, deleteMessageIds: [], reason: 'no-record' }
+  if (args.now - record.ts > ttlMs) {
+    return { supersede: false, deleteMessageIds: [], reason: 'expired' }
+  }
+  const sameTurn =
+    record.turnId != null
+      ? record.turnId === args.liveTurnId
+      : args.liveTurnId == null
+  if (!sameTurn) {
+    return { supersede: false, deleteMessageIds: [], reason: 'different-turn' }
+  }
+  return { supersede: true, deleteMessageIds: [...record.messageIds], reason: 'supersede' }
+}
+
+/** Sentinel key for records whose flush carried no turnId nonce. */
+const NULL_TURN_KEY = '<<null-turn>>'
+
+function turnKey(turnId: string | null): string {
+  return turnId == null ? NULL_TURN_KEY : turnId
+}
+
+/**
+ * In-memory registry of recently-flushed turns, keyed by `chatId|threadId` and
+ * then by the flush's `turnId` nonce WITHIN that lane. Holding a per-turnId map
+ * (rather than a single overwriting slot) is what makes the identity guarantee
+ * airtight: two turns can each flush a message on the same lane, and each turn's
+ * later reply supersedes ONLY its own flushed message — turn B's reply can never
+ * reach turn A's record, and a late turn-A reply can never reach turn B's.
+ *
+ * Bounded by TTL eviction (swept on every `record`); chat count per gateway is
+ * small and a lane holds at most a handful of concurrent-turn records.
+ */
+export class FlushedTurnSupersedeRegistry {
+  private readonly entries = new Map<string, Map<string, FlushedTurnRecord>>()
+  private readonly ttlMs: number
+
+  constructor(opts: { ttlMs?: number } = {}) {
+    this.ttlMs = opts.ttlMs ?? DEFAULT_SUPERSEDE_TTL_MS
+  }
+
+  /** Record a flush's posted message(s) so a later same-turn reply supersedes
+   *  them, keyed on the flush's `turnId` within the chat/thread lane. No record
+   *  is kept when the flush posted zero messages. Sweeps expired records first
+   *  (lightweight active GC — LOW-2) so orphan records never accumulate. */
+  record(
+    chatId: string,
+    threadId: number | undefined,
+    rec: { turnId: string | null; messageIds: number[]; text: string },
+    now: number,
+  ): void {
+    if (rec.messageIds.length === 0) return
+    this.sweep(now)
+    const lane = makeKey(chatId, threadId)
+    let laneMap = this.entries.get(lane)
+    if (laneMap == null) {
+      laneMap = new Map<string, FlushedTurnRecord>()
+      this.entries.set(lane, laneMap)
+    }
+    laneMap.set(turnKey(rec.turnId), {
+      turnId: rec.turnId,
+      messageIds: [...rec.messageIds],
+      text: rec.text,
+      ts: now,
+    })
+  }
+
+  /** Decide supersede for a landing reply WITHOUT consuming the record. Selects
+   *  the record whose turnId matches the reply's resolved `liveTurnId` (or the
+   *  null-turnId record when `liveTurnId == null`). */
+  peek(
+    chatId: string,
+    threadId: number | undefined,
+    args: { liveTurnId: string | null; now: number },
+  ): SupersedeDecision {
+    const rec = this.entries.get(makeKey(chatId, threadId))?.get(turnKey(args.liveTurnId))
+    return decideSupersede(rec, { liveTurnId: args.liveTurnId, now: args.now, ttlMs: this.ttlMs })
+  }
+
+  /** Decide supersede AND, on a supersede, consume the matched record (so a
+   *  second replay of the same reply doesn't try to delete the same — now gone —
+   *  messages again). Returns the same decision `peek` would. */
+  take(
+    chatId: string,
+    threadId: number | undefined,
+    args: { liveTurnId: string | null; now: number },
+  ): SupersedeDecision {
+    const lane = makeKey(chatId, threadId)
+    const decision = this.peek(chatId, threadId, args)
+    if (decision.supersede) {
+      const laneMap = this.entries.get(lane)
+      laneMap?.delete(turnKey(args.liveTurnId))
+      if (laneMap != null && laneMap.size === 0) this.entries.delete(lane)
+    }
+    return decision
+  }
+
+  /** Drop all records for a chat/thread (e.g. after the flushed message was
+   *  deleted through another path). Idempotent. */
+  forget(chatId: string, threadId: number | undefined): void {
+    this.entries.delete(makeKey(chatId, threadId))
+  }
+
+  /** Test-only: clear all entries. */
+  clear(): void {
+    this.entries.clear()
+  }
+
+  /** Evict every record past its TTL and prune emptied lanes. */
+  private sweep(now: number): void {
+    for (const [lane, laneMap] of this.entries) {
+      for (const [tk, rec] of laneMap) {
+        if (now - rec.ts > this.ttlMs) laneMap.delete(tk)
+      }
+      if (laneMap.size === 0) this.entries.delete(lane)
+    }
+  }
+
+  /** Test-only: live record count after TTL eviction. */
+  size(now: number): number {
+    this.sweep(now)
+    let total = 0
+    for (const laneMap of this.entries.values()) total += laneMap.size
+    return total
+  }
+}
+
+function makeKey(chatId: string, threadId: number | undefined): string {
+  return threadId == null ? chatId : `${chatId}|${threadId}`
+}

package/telegram-plugin/gateway/gateway.ts

@@ -88,6 +88,7 @@ import {
   type TelegraphAccount,
 } from '../telegraph.js'
 import { OutboundDedupCache } from '../recent-outbound-dedup.js'
+import { FlushedTurnSupersedeRegistry } from '../flushed-turn-supersede.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import {
   splitCoalescedAttachments,
@@ -2220,6 +2221,14 @@ const deferredDoneReactions = new DeferredDoneReactions<StatusReactionController
 // path threw `outboundDedup is not defined` at runtime, blocking ALL outbound
 // from the agent. Restore the module-level singleton here.
 const outboundDedup = new OutboundDedupCache()
+// 2026-07 duplicate-reply fix — turnId-keyed supersede. When a turn-flush
+// (answer-ready quiescence OR the turn-end backstop) posts the model's terminal
+// text and the model's REAL `reply` for the SAME turn lands later, the reply
+// SUPERSEDES the flushed message (delete + canonical resend) instead of shipping
+// a second message. Keyed on the per-turn `turnId` nonce, NOT on text — so it
+// catches the containment case the exact-text `outboundDedup` misses (a
+// `narration\n\nanswer` flush never equals the clean `answer`-only reply).
+const flushedTurnSupersede = new FlushedTurnSupersedeRegistry()
 /**
  * Per-chat cache of `available_reactions` from `getChat`. Populated lazily —
  * the FIRST message in a chat creates a controller without the filter (null
@@ -12902,6 +12911,50 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     }
   }
 
+  // 2026-07 duplicate-reply fix — turnId-keyed supersede (consumption side).
+  // If an earlier turn-flush (answer-ready quiescence OR the turn-end backstop)
+  // already posted THIS turn's terminal text and the model's REAL `reply` for
+  // the same turn is landing now (it was still composing the tool call when the
+  // flush fired, or claude-code replayed the tool_call after a bridge
+  // reconnect), delete the flushed message(s) so the canonical reply below
+  // delivers exactly one clean message instead of a second one. Keyed on the
+  // per-turn `turnId` nonce, so it fires even when the flushed narration+answer
+  // blob differs from the clean answer-only reply — the containment case the
+  // exact-text `outboundDedup` above structurally cannot catch. A reply for a
+  // DIFFERENT newer live turn never supersedes (decideSupersede → different-turn),
+  // so a fresh turn's answer is never clobbered.
+  {
+    const replyThreadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+    // Resolve the turnId this reply belongs to by IDENTITY, not just the live
+    // `currentTurn`. A late reply lands with `currentTurn == null` (silence poke
+    // cleared it — Bug D) or with a transiently-cleared currentTurn while its own
+    // turn is really still the owner (LOW-1); in both cases the turn is still
+    // resolvable from the `origin_turn_id` nonce the model echoes back (Tier 2 —
+    // the same last-known-turn resolver the chat-routing / obligation code uses).
+    // Passing this resolved turnId means supersede matches the flushed record by
+    // identity instead of falling back to a null-liveTurnId branch that would
+    // otherwise be free to delete a DIFFERENT turn's legitimate message.
+    const resolvedTurnId =
+      turn?.turnId ?? findTurnByOriginId(args.origin_turn_id as string | undefined)?.turnId ?? null
+    const decision = flushedTurnSupersede.take(
+      chat_id,
+      replyThreadId,
+      { liveTurnId: resolvedTurnId, now: Date.now() },
+    )
+    if (decision.supersede) {
+      process.stderr.write(
+        `telegram gateway: reply: superseding flushed turn message(s) ` +
+        `chatId=${chat_id} ids=${JSON.stringify(decision.deleteMessageIds)}\n`,
+      )
+      for (const id of decision.deleteMessageIds) {
+        await swallowingApiCall(
+          () => lockedBot.api.deleteMessage(chat_id, id),
+          { chat_id, verb: 'reply.supersedeFlushed' },
+        )
+      }
+    }
+  }
+
   const files = (args.files as string[] | undefined) ?? []
   const quoteOptIn = args.quote !== false
   let reply_to = args.reply_to != null ? Number(args.reply_to) : undefined
@@ -18264,6 +18317,22 @@ function handleSessionEvent(ev: SessionEvent): void {
               Date.now(),
               currentTurn?.registryKey ?? null,
             )
+            // 2026-07 duplicate-reply fix — record the flushed message id(s)
+            // keyed on THIS turn's `turnId` nonce so a late `reply` for the same
+            // turn supersedes them (delete + canonical resend) instead of
+            // shipping a duplicate. `turn` is the ending turn atom captured at
+            // the top of this branch (endCurrentTurnAtomic nulled currentTurn,
+            // but the captured `turn` still carries the honest turnId). Covers
+            // BOTH flush paths — answer-ready quiescence and the turn-end
+            // backstop both funnel through this single IIFE.
+            if (sentIds.length > 0) {
+              flushedTurnSupersede.record(
+                backstopChatId,
+                backstopThreadId,
+                { turnId: turn.turnId, messageIds: sentIds, text: capturedText },
+                Date.now(),
+              )
+            }
             // #1713: route the backstop terminal through finalize() —
             // single terminal path keeps the controller contract clean.
             if (backstopCtrl) backstopCtrl.finalize('done')

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/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')
+    }
+  })
+})

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

@@ -1513,7 +1513,7 @@ describe('worker-feed send-gate shed contract', () => {
     expect(bot.edits[0].text).toContain('2 tools')
   })
 
-  it('does not falsely finalize on a shed terminal edit — re-drives the finalize once the gate clears', async () => {
+  it('a shed terminal edit drops the finished row immediately but stages the recap for a heartbeat re-drive (#3207)', async () => {
     let clock = 10_000
     const bot = makeGateBot(() => 0)
     const feed = createWorkerActivityFeed({
@@ -1522,25 +1522,30 @@ describe('worker-feed send-gate shed contract', () => {
       firstPaintMinMs: 0,
       minEditIntervalMs: 0,
       floodWaitRemainingMs: () => 0,
+      setInterval: () => 1,
+      clearInterval: () => {},
     })
 
     await feed.update('w1', 'chat', view({ toolCount: 1 }))
     expect(bot.sent).toHaveLength(1)
 
-    // Gate sheds the terminal edit (undefined).
+    // Gate sheds the terminal edit (SEND_GATE_SHED sentinel).
     clock = 20_000
     bot.shedNextEdit = true
     await feed.finish('w1', view({ state: 'done', toolCount: 5 }))
     expect(bot.editCalls).toBe(1)
     expect(bot.edits).toHaveLength(0)
-    // NOT finalized: the handle survives (pendingFinish staged) rather than
-    // being torn down with the card frozen on its last running render.
-    expect(feed.has('w1')).toBe(true)
+    // #3207: the finished row is dropped RIGHT AWAY — it is NOT kept alive to
+    // leak the group/pin when the terminal edit fails. The recap is staged for
+    // the heartbeat re-drive instead (a second finish() would be a no-op: the
+    // agent is already finalized + removed).
+    expect(feed.has('w1')).toBe(false)
+    expect(feed.size).toBe(0)
 
-    // Re-drive with the gate clear: the terminal recap lands and the handle
-    // finalizes.
+    // A heartbeat with the gate clear re-drives the staged recap → it lands.
     clock = 30_000
-    await feed.finish('w1', view({ state: 'done', toolCount: 5 }))
+    feed.heartbeatTick()
+    await new Promise((r) => setTimeout(r, 0))
     expect(bot.edits).toHaveLength(1)
     expect(bot.edits[0].text).toContain('_done · 5 tools')
     expect(feed.has('w1')).toBe(false)