switchroom 0.14.55 → 0.14.56

package/telegram-plugin/gateway/serialize-drain-gate.ts

@@ -0,0 +1,111 @@
+/**
+ * Serialize-until-replied buffer-drain gate (multitopic reply-routing).
+ *
+ * Pure decision: when a turn ends and a cross-topic inbound is sitting in
+ * `pendingInboundBuffer`, may the gateway drain (re-deliver) that buffered
+ * inbound *right now*?
+ *
+ * ## The bug this closes
+ *
+ * In a forum supergroup one agent owns the whole supergroup — a single
+ * sequential `claude` CLI with a singleton `currentTurn`. Two questions in
+ * two topics (Brevo=thread 4, then Meta=thread 3) were both answered into
+ * Meta. Root cause #1 of two coupled defects:
+ *
+ *   The buffer drain (`redeliverBufferedInbound`, fired from
+ *   `purgeReactionTracking` and `releaseTurnBufferGate`) ran whenever
+ *   `!turnInFlightForGate()` — i.e. on the bare turn-end signal —
+ *   REGARDLESS of whether the turn that just ended had actually delivered
+ *   its reply. When the Brevo turn emitted its turn-end event BEFORE its
+ *   late reply landed (~42s later), the buffered Meta message drained
+ *   immediately and started the Meta turn. By the time the Brevo reply
+ *   executed, `currentTurn` had flipped to Meta and the reply routed to
+ *   Meta's thread (defect #2, fixed separately by turn-origin routing).
+ *
+ * ## The guarantee
+ *
+ * A buffered cross-topic inbound drains only after the just-ended turn
+ * delivered its reply to its OWN thread. Concretely: Brevo's buffered-Meta
+ * drain waits until Brevo's reply lands in thread 4. Because the canonical
+ * reply path (`executeReply`) sets `finalAnswerDelivered = true` and then
+ * calls `releaseTurnBufferGate`, the drain now happens FROM the reply, not
+ * from the bare turn_end.
+ *
+ * ## Liveness — the no-reply case is NOT handled here
+ *
+ * A turn that legitimately ends with NO reply (greeting already handled,
+ * handback ack, NO_REPLY / HEARTBEAT_OK marker, silent-end) has
+ * `finalAnswerDelivered === false` and would block the drain FOREVER under
+ * this predicate. That is intentional: liveness for the no-reply case is
+ * restored by a *separate* bounded escape-hatch timer in
+ * `endCurrentTurnAtomic` (`SWITCHROOM_SERIALIZE_NOREPLY_DRAIN_MS`), plus
+ * the existing 300s silence-poke unwedge fallback as the long-stop. This
+ * predicate stays pure and total — it never reasons about timers.
+ *
+ * ## Kill switch
+ *
+ * `SWITCHROOM_SERIALIZE_UNTIL_REPLIED=0` reverts to legacy behaviour
+ * (drain on bare turn-end). The kill switch is read by the CALLER, which
+ * passes `enabled` here; when disabled the predicate degenerates to the
+ * old `!turnInFlight` check.
+ */
+
+export interface DrainGateInput {
+  /** A turn is in flight RIGHT NOW (`turnInFlightForGate()`), evaluated at
+   *  the drain site. When true, never drain — claude is busy. */
+  turnInFlight: boolean
+  /** Whether the ending turn delivered its final answer. Read from the
+   *  ending turn's `finalAnswerDelivered`. `undefined` / `null` means
+   *  there is no ending turn handle at this drain site (sibling-key purge,
+   *  restart-init cleanup, idle sweep) — treated as "no turn to wait on",
+   *  so the gate doesn't block. */
+  endingTurnFinalAnswerDelivered?: boolean | null
+  /** Kill-switch state. When false the serialize-until-replied behaviour
+   *  is OFF and the gate reduces to `!turnInFlight` (legacy). */
+  enabled: boolean
+}
+
+/**
+ * Pure. Returns true when the buffered inbound may be drained now.
+ *
+ * - turnInFlight → always false (claude is busy; never drain mid-turn).
+ * - !enabled (kill switch off) → drain whenever idle (legacy behaviour).
+ * - no ending-turn handle (undefined/null) → drain (nothing to wait on).
+ * - ending turn delivered its final answer → drain.
+ * - ending turn ended WITHOUT a final answer → do NOT drain here; the
+ *   bounded no-reply escape hatch (separate timer) releases it.
+ */
+export function mayDrainBufferedInbound(input: DrainGateInput): boolean {
+  if (input.turnInFlight) return false
+  if (!input.enabled) return true
+  const delivered = input.endingTurnFinalAnswerDelivered
+  if (delivered == null) return true
+  return delivered === true
+}
+
+export interface NoReplyDrainArmInput {
+  /** Kill-switch state. Off → never arm (legacy behaviour drains on the
+   *  bare turn-end, so there is nothing to rescue). */
+  enabled: boolean
+  /** Whether the just-ended turn delivered its final answer. A delivered
+   *  turn already drained via the serialize gate — no rescue needed. */
+  finalAnswerDelivered: boolean
+  /** Number of inbounds sitting in the pending-inbound buffer for this
+   *  agent. Only arm when something is actually waiting. */
+  bufferedDepth: number
+}
+
+/**
+ * Component 2 — should the bounded no-reply drain timer be armed when a
+ * turn ends? Pure mirror of the guard inside `armNoReplyDrainTimer`. THIS
+ * is the liveness guarantee in predicate form: a turn that ends with NO
+ * reply (finalAnswerDelivered=false) AND a buffered inbound waiting must
+ * arm the bounded force-drain so the queue can never wedge. A delivered
+ * turn (already drained), an empty buffer (nothing to rescue), or the
+ * feature being disabled → do not arm.
+ */
+export function shouldArmNoReplyDrain(input: NoReplyDrainArmInput): boolean {
+  if (!input.enabled) return false
+  if (input.finalAnswerDelivered === true) return false
+  return input.bufferedDepth > 0
+}

package/telegram-plugin/tests/answer-thread-resolve.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+
+import { resolveAnswerThreadId } from '../gateway/answer-thread-resolve.js'
+
+/**
+ * Component 3 (multitopic reply-routing) — turn-origin answer thread.
+ *
+ * The Brevo answer landed ~42s after Brevo's turn-end; by then currentTurn
+ * had flipped to the Meta turn. executeReply captured `turn = currentTurn`
+ * and, when the model omitted message_thread_id, routed to the LIVE (Meta)
+ * turn's thread — so Brevo's answer landed in Meta. The fix routes by the
+ * ORIGIN turn (matched by origin_turn_id), authoritative even after the
+ * flip, and never falls through to the chat last-seen heuristic for answers.
+ */
+describe('resolveAnswerThreadId', () => {
+  const BREVO = 4
+  const META = 3
+
+  it('explicit model thread wins outright', () => {
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: BREVO,
+        originResolved: true,
+        originThreadId: META, // even if origin says otherwise
+        liveThreadId: META,
+      }),
+    ).toBe(BREVO)
+  })
+
+  it('routes to the ORIGIN turn thread even when currentTurn has flipped (the headline fix)', () => {
+    // Brevo reply executing late: origin=Brevo(4), live currentTurn=Meta(3).
+    // Must land in Brevo, NOT the live Meta thread.
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: true,
+        originThreadId: BREVO,
+        liveThreadId: META,
+      }),
+    ).toBe(BREVO)
+  })
+
+  it('origin thread is authoritative even when it equals the live thread (no flip)', () => {
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: true,
+        originThreadId: BREVO,
+        liveThreadId: BREVO,
+      }),
+    ).toBe(BREVO)
+  })
+
+  it('a DM origin turn yields undefined (no thread), not the live thread', () => {
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: true,
+        originThreadId: undefined, // DM origin
+        liveThreadId: META,
+      }),
+    ).toBeUndefined()
+  })
+
+  it('falls back to the LIVE turn thread only when no origin is resolvable (legacy #1664)', () => {
+    // Model omitted origin_turn_id, or the origin turn was evicted from the
+    // bounded registry: preserve the existing turn-pinned behaviour.
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: false,
+        originThreadId: undefined,
+        liveThreadId: META,
+      }),
+    ).toBe(META)
+  })
+
+  it('DM (no thread anywhere) → undefined', () => {
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: false,
+        originThreadId: undefined,
+        liveThreadId: undefined,
+      }),
+    ).toBeUndefined()
+  })
+
+  it('precedence: explicit > origin > live (never chatThreadMap — not an input)', () => {
+    // The chat last-seen thread is deliberately NOT a parameter: answer
+    // paths can never reach it, which is what closes the wrong-topic bug.
+    // explicit beats both:
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: 9,
+        originResolved: true,
+        originThreadId: BREVO,
+        liveThreadId: META,
+      }),
+    ).toBe(9)
+    // no explicit, origin resolved → origin (not live):
+    expect(
+      resolveAnswerThreadId({
+        explicitThreadId: undefined,
+        originResolved: true,
+        originThreadId: BREVO,
+        liveThreadId: META,
+      }),
+    ).toBe(BREVO)
+  })
+})

package/telegram-plugin/tests/buffer-gate-broadened.test.ts

@@ -68,7 +68,12 @@ describe('buffer-gate release decoupled from final-answer classification', () =>
   }
 
   it('declares a narrow `releaseTurnBufferGate` helper (not the full purgeReactionTracking)', () => {
-    expect(gatewaySrc).toMatch(/function releaseTurnBufferGate\(key: string\): void/)
+    // Multitopic component 1: the signature now also accepts an optional
+    // `endingTurn` so the serialize-until-replied drain gate can read its
+    // finalAnswerDelivered flag. The narrow-helper contract is unchanged.
+    expect(gatewaySrc).toMatch(
+      /function releaseTurnBufferGate\(key: string, endingTurn\?: CurrentTurn\): void/,
+    )
     // The helper docstring must explain WHY split from
     // purgeReactionTracking — future readers need to know.
     const doc = fnDocstring()
@@ -79,7 +84,10 @@ describe('buffer-gate release decoupled from final-answer classification', () =>
   it('releaseTurnBufferGate ONLY clears activeTurnStartedAt + flushes; does NOT touch activeStatusReactions', () => {
     const body = fnBody()
     expect(body).toMatch(/activeTurnStartedAt\.delete\(key\)/)
-    expect(body).toMatch(/pendingInboundBuffer/)
+    // The drain is now routed through the shared `drainBufferedIfAllowed`
+    // helper (multitopic component 1), which owns the pendingInboundBuffer
+    // flush + the serialize-until-replied gate.
+    expect(body).toMatch(/drainBufferedIfAllowed\(/)
     // Critical regression guard: the helper must NOT touch the
     // reaction controller, else #1713's bidirectional ladder
     // collapses to 👍 mid-turn.
@@ -100,11 +108,12 @@ describe('buffer-gate release decoupled from final-answer classification', () =>
     // emits the 👍 reaction on the final-answer happy path).
     expect(slice).toMatch(/isFinalAnswerReply\(/)
     expect(slice).toMatch(/finalizeStatusReaction\(/)
-    // The new unconditional buffer-gate release must ALSO be
-    // present and must be OUTSIDE the isFinalAnswerReply branch
-    // (so trivial-prompt non-notification replies still release
-    // the gate).
-    expect(slice).toMatch(/releaseTurnBufferGate\(statusKey\(chat_id, threadId\)\)/)
+    // The unconditional buffer-gate release must ALSO be present and
+    // must be OUTSIDE the isFinalAnswerReply branch (so trivial-prompt
+    // non-notification replies still release the gate). Multitopic
+    // component 1: the call now passes the turn so the serialize gate
+    // can read finalAnswerDelivered.
+    expect(slice).toMatch(/releaseTurnBufferGate\(statusKey\(chat_id, threadId\), turn \?\? undefined\)/)
     // Structural check: the release must appear AFTER the
     // isFinalAnswerReply block's closing brace but BEFORE the
     // post-send block ends. Easiest pin: it must NOT be inside the

package/telegram-plugin/tests/multitopic-routing-wiring.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Multitopic reply-routing — gateway/bridge wiring guards.
+ *
+ * The gateway IIFE is too entangled to instantiate in-process, so these
+ * are source-level assertions (the same pattern buffer-gate-broadened.test
+ * and reply-terminal-reaction.test use). They pin the load-bearing wiring
+ * of components 3 (turn-origin routing), 4 (topic framing), and 5 (queued-
+ * status UX) so a future refactor that drops a hook trips here.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+const bridgeSrc = readFileSync(
+  resolve(__dirname, '..', 'bridge', 'bridge.ts'),
+  'utf-8',
+)
+
+describe('component 3 — turn-origin reply routing', () => {
+  it('CurrentTurn carries a turnId, and the enqueue handler initialises it', () => {
+    expect(gatewaySrc).toMatch(/turnId: string/)
+    expect(gatewaySrc).toMatch(/const turnId\s*=\s*\n?\s*deriveTurnId\(/)
+    expect(gatewaySrc).toMatch(/rememberRecentTurn\(next\)/)
+  })
+
+  it('the inbound meta stamps origin_turn_id derived from chat/thread/messageId', () => {
+    expect(gatewaySrc).toMatch(/const originTurnId = deriveTurnId\(chat_id, messageThreadId \?\? null, msgId\)/)
+    expect(gatewaySrc).toMatch(/origin_turn_id: originTurnId/)
+  })
+
+  it('deriveTurnId is stable across inbound-build and enqueue (message-id based)', () => {
+    // The id must be derivable identically at both sites — keyed on
+    // chat/thread/messageId, NOT the not-yet-known startedAt.
+    const fn = gatewaySrc.split('function deriveTurnId')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/chatKey\(chatId, threadId \?\? null\)/)
+    expect(fn).toMatch(/messageId/)
+  })
+
+  it('executeReply resolves the answer thread via the origin turn, not the live currentTurn', () => {
+    const fn = gatewaySrc.split('async function executeReply')[1]?.split('\nasync function ')[0] ?? ''
+    expect(fn).toMatch(/TURN_ORIGIN_ROUTING_ENABLED/)
+    expect(fn).toMatch(/findTurnByOriginId\(args\.origin_turn_id/)
+    expect(fn).toMatch(/resolveAnswerThreadId\(/)
+  })
+
+  it('executeStreamReply resolves the answer thread via the origin turn too', () => {
+    const fn = gatewaySrc.split('async function executeStreamReply')[1]?.split('\nasync function ')[0] ?? ''
+    expect(fn).toMatch(/findTurnByOriginId\(args\.origin_turn_id/)
+    expect(fn).toMatch(/resolveAnswerThreadId\(/)
+  })
+
+  it('the reply + stream_reply tool schemas expose origin_turn_id to the model', () => {
+    const occurrences = bridgeSrc.match(/origin_turn_id: \{ type: 'string'/g) ?? []
+    expect(occurrences.length).toBe(2) // reply + stream_reply
+  })
+
+  it('recentTurnsById is a BOUNDED registry (cannot grow unbounded)', () => {
+    expect(gatewaySrc).toMatch(/RECENT_TURNS_MAX/)
+    expect(gatewaySrc).toMatch(/recentTurnsById\.delete\(oldest\)/)
+  })
+})
+
+describe('component 4 — per-turn topic framing', () => {
+  it('the gateway stamps a topic_scope directive for forum-topic inbounds (kill-switched)', () => {
+    expect(gatewaySrc).toMatch(/TOPIC_FRAMING_ENABLED/)
+    expect(gatewaySrc).toMatch(/topic_scope: topicScope/)
+    // Only for topic inbounds — DMs get nothing.
+    expect(gatewaySrc).toMatch(/TOPIC_FRAMING_ENABLED && messageThreadId != null/)
+  })
+
+  it('the bridge instructions frame each channel message as the current topic', () => {
+    expect(bridgeSrc).toMatch(/answer ONLY this message/)
+    expect(bridgeSrc).toMatch(/do not also answer a pending message from another topic/i)
+  })
+})
+
+describe('component 5 — queued-status UX (delete-on-answer)', () => {
+  it('a queuedStatusMsgIds map tracks the placeholder per buffered topic', () => {
+    expect(gatewaySrc).toMatch(/const queuedStatusMsgIds = new Map/)
+  })
+
+  it('Hook A posts a queued status into the buffered message own topic (cross-topic only, kill-switched)', () => {
+    expect(gatewaySrc).toMatch(/postQueuedStatus\(chat_id, messageThreadId, inFlightThread\)/)
+    // Suppressed for DMs and same-topic.
+    expect(gatewaySrc).toMatch(/!isDmChatId\(chat_id\) &&/)
+    expect(gatewaySrc).toMatch(/messageThreadId !== inFlightThread/)
+  })
+
+  it('Hook B promotes the placeholder to "On it" when the buffered turn starts', () => {
+    expect(gatewaySrc).toMatch(/promoteQueuedStatus\(ev\.chatId, enqThreadIdNum\)/)
+  })
+
+  it('Hook C reaps the placeholder on the answer (executeReply / stream)', () => {
+    const reapCalls = gatewaySrc.match(/reapQueuedStatus\(/g) ?? []
+    // definition + executeReply + executeStreamReply + purge cleanup (2 branches)
+    expect(reapCalls.length).toBeGreaterThanOrEqual(4)
+  })
+
+  it('purgeReactionTracking reaps the placeholder on abnormal turn-end (defense-in-depth)', () => {
+    const fn = gatewaySrc.split('function purgeReactionTracking')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/reapQueuedStatus\(/)
+    // Reap sits alongside the activeReactionMsgIds cleanup.
+    expect(fn).toMatch(/activeReactionMsgIds\.delete\(key\)/)
+  })
+
+  it('all queued-status sends/edits/deletes go through the swallowing wrapper (carry thread)', () => {
+    for (const helper of ['postQueuedStatus', 'promoteQueuedStatus', 'reapQueuedStatus']) {
+      const fn = gatewaySrc.split(`function ${helper}`)[1]?.split('\nfunction ')[0] ?? ''
+      expect(fn).toMatch(/swallowingApiCall\(/)
+    }
+  })
+})
+
+describe('kill switches — all five default ON, each independently disableable', () => {
+  it('declares the three named kill switches + the two component switches', () => {
+    expect(gatewaySrc).toMatch(/SWITCHROOM_SERIALIZE_UNTIL_REPLIED !== '0'/)
+    expect(gatewaySrc).toMatch(/SWITCHROOM_SERIALIZE_NOREPLY_DRAIN_MS/)
+    expect(gatewaySrc).toMatch(/SWITCHROOM_QUEUED_STATUS_UX !== '0'/)
+    expect(gatewaySrc).toMatch(/SWITCHROOM_TURN_ORIGIN_ROUTING !== '0'/)
+    expect(gatewaySrc).toMatch(/SWITCHROOM_TOPIC_FRAMING !== '0'/)
+  })
+
+  it('the no-reply drain ms default is 2500 and clamped positive', () => {
+    expect(gatewaySrc).toMatch(/SERIALIZE_NOREPLY_DRAIN_MS\s*=\s*\n?\s*Number\.isFinite\([^)]*\)\s*&&[^?]*\?\s*[^:]*:\s*2_500/)
+  })
+})

package/telegram-plugin/tests/no-reply-bounded-drain.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { shouldArmNoReplyDrain } from '../gateway/serialize-drain-gate.js'
+
+/**
+ * Component 2 (multitopic reply-routing) — bounded no-reply escape hatch.
+ *
+ * THE liveness guarantee. Component 1's serialize gate blocks the
+ * cross-topic buffer drain until the ending turn delivers its reply. A turn
+ * that legitimately ends with NO reply (handback ack, NO_REPLY /
+ * HEARTBEAT_OK marker, silent-end) sets finalAnswerDelivered=false and
+ * would otherwise block the drain FOREVER — and the 300s silence-poke is
+ * disarmed for those turns. The bounded timer rescues it: it force-drains
+ * within SERIALIZE_NOREPLY_DRAIN_MS so the queue can NEVER wedge.
+ *
+ * This file pins (a) the arming predicate `shouldArmNoReplyDrain` shared by
+ * the gateway's `armNoReplyDrainTimer`, (b) the liveness behaviour via a
+ * fake-timer simulation of the exact timer pattern, and (c) source-level
+ * guards that the gateway wires the timer + force-drain on the no-reply
+ * turn-end path.
+ */
+describe('shouldArmNoReplyDrain (the arming predicate)', () => {
+  it('ARMS when a no-reply turn ends with a buffered inbound waiting (the rescue)', () => {
+    expect(
+      shouldArmNoReplyDrain({ enabled: true, finalAnswerDelivered: false, bufferedDepth: 1 }),
+    ).toBe(true)
+  })
+
+  it('does NOT arm when the turn delivered its final answer (serialize gate already drained)', () => {
+    expect(
+      shouldArmNoReplyDrain({ enabled: true, finalAnswerDelivered: true, bufferedDepth: 1 }),
+    ).toBe(false)
+  })
+
+  it('does NOT arm when nothing is buffered (no rescue needed)', () => {
+    expect(
+      shouldArmNoReplyDrain({ enabled: true, finalAnswerDelivered: false, bufferedDepth: 0 }),
+    ).toBe(false)
+  })
+
+  it('does NOT arm when the serialize feature is off (legacy drains on bare turn-end)', () => {
+    expect(
+      shouldArmNoReplyDrain({ enabled: false, finalAnswerDelivered: false, bufferedDepth: 3 }),
+    ).toBe(false)
+  })
+
+  it('is total over the input space', () => {
+    for (const enabled of [true, false]) {
+      for (const finalAnswerDelivered of [true, false]) {
+        for (const bufferedDepth of [0, 1, 5]) {
+          const got = shouldArmNoReplyDrain({ enabled, finalAnswerDelivered, bufferedDepth })
+          const want = enabled && !finalAnswerDelivered && bufferedDepth > 0
+          expect(got).toBe(want)
+        }
+      }
+    }
+  })
+})
+
+describe('no-reply bounded drain — liveness (the queue cannot wedge)', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  // Mirror of the gateway's armNoReplyDrainTimer timer pattern: when the
+  // predicate arms, a setTimeout(forceDrain, NOREPLY_DRAIN_MS) is set; the
+  // force-drain releases the buffer regardless of the serialize gate.
+  function simulateNoReplyTurnEnd(opts: {
+    drainMs: number
+    finalAnswerDelivered: boolean
+    bufferDepthAtEnd: number
+    forceDrain: () => void
+  }): void {
+    if (
+      shouldArmNoReplyDrain({
+        enabled: true,
+        finalAnswerDelivered: opts.finalAnswerDelivered,
+        bufferedDepth: opts.bufferDepthAtEnd,
+      })
+    ) {
+      const t = setTimeout(() => opts.forceDrain(), opts.drainMs)
+      t.unref?.()
+    }
+  }
+
+  it('a no-reply turn followed by a queued cross-topic message releases within ~2.5s', () => {
+    const NOREPLY_DRAIN_MS = 2_500
+    let buffered = 1 // one cross-topic inbound queued behind the no-reply turn
+    const forceDrain = vi.fn(() => { buffered = 0 })
+
+    simulateNoReplyTurnEnd({
+      drainMs: NOREPLY_DRAIN_MS,
+      finalAnswerDelivered: false,
+      bufferDepthAtEnd: buffered,
+      forceDrain,
+    })
+
+    // Before the bound: still queued (serialize gate held it, no reply came).
+    vi.advanceTimersByTime(NOREPLY_DRAIN_MS - 1)
+    expect(forceDrain).not.toHaveBeenCalled()
+    expect(buffered).toBe(1)
+
+    // At the bound: the escape hatch fires and drains. No wedge.
+    vi.advanceTimersByTime(1)
+    expect(forceDrain).toHaveBeenCalledTimes(1)
+    expect(buffered).toBe(0)
+  })
+
+  it('a DELIVERED turn does not arm the timer (the reply already drained)', () => {
+    const forceDrain = vi.fn()
+    simulateNoReplyTurnEnd({
+      drainMs: 2_500,
+      finalAnswerDelivered: true,
+      bufferDepthAtEnd: 1,
+      forceDrain,
+    })
+    vi.advanceTimersByTime(10_000)
+    expect(forceDrain).not.toHaveBeenCalled()
+  })
+})
+
+describe('gateway wiring (source-level guards) — the gateway IIFE is too entangled to instantiate', () => {
+  const gatewaySrc = readFileSync(
+    resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+    'utf-8',
+  )
+
+  it('endCurrentTurnAtomic arms the no-reply drain timer after the serialize-gated purge', () => {
+    const fn = gatewaySrc.split('function endCurrentTurnAtomic')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/purgeReactionTracking\(/)
+    expect(fn).toMatch(/armNoReplyDrainTimer\(turn\)/)
+    // The arm must come AFTER the purge (the purge attempts the gated
+    // drain first; the timer is the fallback for the no-reply case).
+    expect(fn.indexOf('armNoReplyDrainTimer')).toBeGreaterThan(fn.indexOf('purgeReactionTracking'))
+  })
+
+  it('armNoReplyDrainTimer uses the shared predicate + a bounded setTimeout that force-drains', () => {
+    const fn = gatewaySrc.split('function armNoReplyDrainTimer')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/shouldArmNoReplyDrain\(/)
+    expect(fn).toMatch(/setTimeout\(/)
+    expect(fn).toMatch(/SERIALIZE_NOREPLY_DRAIN_MS/)
+    // It must force-drain (bypassing the serialize delivered-check), not
+    // route back through the gated drain — else the no-reply turn would
+    // re-block itself.
+    expect(fn).toMatch(/performBufferDrain\(/)
+    expect(fn).not.toMatch(/drainBufferedIfAllowed\(/)
+  })
+
+  it('the 300s silence-poke fallback remains an independent long-stop (direct redeliver)', () => {
+    // The unwedge fallback calls redeliverBufferedInbound directly — it
+    // must NOT be gated by the serialize predicate, or a stuck no-reply
+    // turn whose bounded timer somehow failed would never recover.
+    expect(gatewaySrc).toMatch(/silence-poke framework-fallback ended wedged turn/)
+  })
+})

package/telegram-plugin/tests/serialize-drain-gate.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+
+import { mayDrainBufferedInbound } from '../gateway/serialize-drain-gate.js'
+
+/**
+ * Component 1 (multitopic reply-routing) — deliver-before-drain gate.
+ *
+ * In a forum supergroup one sequential claude CLI owns every topic with a
+ * singleton currentTurn. The buffer drain used to fire on the bare turn-end
+ * signal regardless of whether the ending turn had delivered its reply, so
+ * a buffered cross-topic message drained the instant the prior turn's
+ * turn-end event landed — even when its reply was still ~42s out. By the
+ * time the prior reply executed, currentTurn had flipped and the reply
+ * routed to the wrong topic.
+ *
+ * The predicate gates the drain: drain only when claude is idle AND (the
+ * kill switch is off, OR there is no ending-turn handle, OR the ending turn
+ * delivered its final answer). The no-reply case (finalAnswerDelivered
+ * false) deliberately blocks here — liveness is restored by the bounded
+ * escape-hatch timer, NOT by this predicate.
+ */
+describe('mayDrainBufferedInbound', () => {
+  it('drains when idle AND the ending turn delivered its final answer', () => {
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: true,
+        enabled: true,
+      }),
+    ).toBe(true)
+  })
+
+  it('does NOT drain when the ending turn ended WITHOUT a reply (the wedge fix)', () => {
+    // The Brevo turn-end fired before its late reply landed; the buffered
+    // Meta message must NOT drain here.
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: false,
+        enabled: true,
+      }),
+    ).toBe(false)
+  })
+
+  it('drains when there is no ending-turn handle (sibling purge / idle sweep)', () => {
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: null,
+        enabled: true,
+      }),
+    ).toBe(true)
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: undefined,
+        enabled: true,
+      }),
+    ).toBe(true)
+  })
+
+  it('NEVER drains while a turn is in flight, regardless of other inputs', () => {
+    for (const delivered of [true, false, null, undefined] as const) {
+      for (const enabled of [true, false]) {
+        expect(
+          mayDrainBufferedInbound({
+            turnInFlight: true,
+            endingTurnFinalAnswerDelivered: delivered,
+            enabled,
+          }),
+        ).toBe(false)
+      }
+    }
+  })
+
+  it('kill switch off → legacy behaviour: drain whenever idle (delivered ignored)', () => {
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: false,
+        enabled: false,
+      }),
+    ).toBe(true)
+    expect(
+      mayDrainBufferedInbound({
+        turnInFlight: false,
+        endingTurnFinalAnswerDelivered: true,
+        enabled: false,
+      }),
+    ).toBe(true)
+  })
+
+  it('is total over the input space', () => {
+    for (const turnInFlight of [true, false]) {
+      for (const delivered of [true, false, null, undefined] as const) {
+        for (const enabled of [true, false]) {
+          const got = mayDrainBufferedInbound({
+            turnInFlight,
+            endingTurnFinalAnswerDelivered: delivered,
+            enabled,
+          })
+          let want: boolean
+          if (turnInFlight) want = false
+          else if (!enabled) want = true
+          else if (delivered == null) want = true
+          else want = delivered === true
+          expect(got).toBe(want)
+        }
+      }
+    }
+  })
+})