switchroom 0.12.18 → 0.12.20

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -30,6 +30,7 @@
  */
 
 import type { InboundMessage } from './ipc-protocol.js'
+import type { InboundSpool } from './inbound-spool.js'
 
 /** Default cap per agent. Tuned for `should fit a reasonable backlog of
  *  approval cards stacked while bridge is offline` but no more. */
@@ -52,6 +53,19 @@ export interface PendingInboundBuffer {
 export interface PendingInboundBufferOptions {
   capPerAgent?: number
   log?: (line: string) => void
+  /**
+   * Durable spool. When set, every `push` is also recorded on the
+   * persistent per-agent volume so a gateway/container restart cannot
+   * silently lose the message (the finn/carrie incident class). The
+   * in-memory queue stays the hot path + cap; the spool is the
+   * crash-survivable record, acked only on confirmed delivery (by
+   * `redeliverBufferedInbound`/`idleDrainTick`), boot-replayed by the
+   * gateway, and escalated-then-dropped if undeliverable past its
+   * bound. The in-memory cap eviction does NOT touch the spool — an
+   * evicted-from-memory entry survives in the spool (strictly safer
+   * than the old silent in-memory drop).
+   */
+  spool?: InboundSpool
 }
 
 /**
@@ -72,6 +86,7 @@ export function redeliverBufferedInbound(
   buffer: PendingInboundBuffer,
   agent: string,
   send: (msg: InboundMessage) => boolean,
+  spool?: InboundSpool,
 ): { drained: number; redelivered: number; rebuffered: number } {
   const pending = buffer.drain(agent)
   let redelivered = 0
@@ -85,6 +100,11 @@ export function redeliverBufferedInbound(
     }
     if (delivered) {
       redelivered++
+      // Confirmed delivery to a live registered bridge → the durable
+      // promise is kept; tombstone the spool entry so it is NOT
+      // boot-replayed again. A miss leaves it spooled (re-pushed below
+      // AND still live in the spool) for the next drain / escalation.
+      spool?.ack(msg)
     } else {
       buffer.push(agent, msg)
       rebuffered++
@@ -107,8 +127,19 @@ export function redeliverBufferedInbound(
  *     which would re-buffer+log-spin every tick; onClientRegistered
  *     will drain on the eventual reconnect instead)
  *   - otherwise → `redeliverBufferedInbound` (lossless: re-buffers any
- *     per-message miss). A message delivered mid-turn is queued
- *     normally by the bridge, same as a live arrival — not lost.
+ *     per-message miss).
+ *
+ * NOTE (#1556): a message delivered mid-turn is NOT safely queued by
+ * the bridge — the prior "queued normally, same as a live arrival"
+ * claim here was the false assumption behind the lawgpt composer
+ * wedge. claude types a mid-turn channel notification into its TUI
+ * composer and the auto-submit races turn-completion, stranding it.
+ * The `idleDrainTick` caller therefore also gates on
+ * `activeTurnStartedAt.size === 0`, so this function is never invoked
+ * mid-turn. The Telegram `handleInbound` delivery path is turn-gated
+ * (gateway.ts); the `inject_inbound` cron/synthetic path is a separate
+ * delivery contract and deliberately not gated — see
+ * `inbound-delivery-gate.ts`.
  *
  * Returns the redeliver counts only when it actually ran, else null
  * (so the caller logs only on a real flush).
@@ -118,11 +149,12 @@ export function idleDrainTick(
   agent: string,
   isBridgeAlive: () => boolean,
   send: (msg: InboundMessage) => boolean,
+  spool?: InboundSpool,
 ): { drained: number; redelivered: number; rebuffered: number } | null {
   if (!agent) return null
   if (buffer.depth(agent) === 0) return null
   if (!isBridgeAlive()) return null
-  return redeliverBufferedInbound(buffer, agent, send)
+  return redeliverBufferedInbound(buffer, agent, send, spool)
 }
 
 export function createPendingInboundBuffer(
@@ -130,6 +162,7 @@ export function createPendingInboundBuffer(
 ): PendingInboundBuffer {
   const cap = opts.capPerAgent ?? DEFAULT_PENDING_INBOUND_CAP
   const log = opts.log ?? ((line: string) => process.stderr.write(line))
+  const spool = opts.spool
   const queues = new Map<string, InboundMessage[]>()
 
   return {
@@ -149,6 +182,12 @@ export function createPendingInboundBuffer(
         )
       }
       q.push(msg)
+      // Durable record FIRST-class to the in-memory queue: spool BEFORE
+      // returning, regardless of the cap eviction above — an entry the
+      // in-memory cap drops still survives in the spool (boot-replayed /
+      // escalated), which is the whole point. spool.put dedups by
+      // spoolId so a boot-replay re-push is a no-op here.
+      spool?.put(agent, msg)
       log(
         `pending-inbound-buffer: agent=${agent} buffered source=${msg.meta?.source ?? '-'} ` +
         `depth_after=${q.length} evicted=${evicted}\n`,

package/telegram-plugin/gateway/turn-state-purge.ts

@@ -0,0 +1,71 @@
+/**
+ * turn-state-purge.ts — defense-in-depth cleanup for the silence-poke
+ * framework-fallback (gateway.ts).
+ *
+ * The fallback's `purgeReactionTracking(fbKey)` clears the canonical
+ * `statusKey(chatId, threadId)` for the exact chat+thread that armed
+ * the silence-poke. But `activeTurnStartedAt` (and its siblings) can
+ * legitimately hold MORE than one entry for the same chat — e.g.:
+ *
+ *   - a normal turn-end handler null'd `currentTurn` but skipped
+ *     `purgeReactionTracking` on a code-path that didn't reach it
+ *     (gateway.ts:5887/5921/6193 — purgeReactionTracking calls in
+ *     those handlers are conditional/not on every branch), so
+ *     `activeTurnStartedAt[oldKey]` is dangling when the fallback
+ *     fires for a NEW key
+ *   - a multi-thread chat (topic-based group, or a `null` vs
+ *     `undefined` thread variant) has entries under different keys of
+ *     the SAME chat
+ *
+ * In either case, the fallback purges `fbKey` but a sibling key for
+ * the same chat remains → `activeTurnStartedAt.size > 0` persists →
+ * `#1556`'s turn-gate holds every new inbound forever → user sees
+ * "not responding" while claude is actually idle (gymbro + klanker,
+ * 2026-05-20).
+ *
+ * This helper sweeps any sibling keys for the firing chat after the
+ * canonical `purgeReactionTracking(fbKey)`, via the same purger.
+ * Multi-chat safe: it only touches keys whose chatId matches — other
+ * chats' active turns are untouched, preserving the deliberate
+ * multi-chat safety #1546 kept.
+ *
+ * Key shape: `statusKey(chatId, threadId)` emits
+ * `${chatId}:${threadId ?? '_'}`. Chat ids are numeric strings (no
+ * `:` inside), so `indexOf(':')` is a safe prefix delimiter. A
+ * "prefix-without-separator" false positive (e.g. chatId `123` vs key
+ * `1234:_`) is structurally impossible because the helper splits on
+ * `:` and equates the prefix, NOT a string-startsWith.
+ *
+ * Pure / dependency-free so the multi-chat-safety and key-shape logic
+ * are unit-testable without standing up a gateway — mirrors the
+ * `#1544 / #1546 / #1549 / #1558` pure-seam idiom.
+ */
+
+export interface PurgeStaleTurnsResult {
+  /** Keys for `chatId` that the helper purged via the callback. */
+  purged: string[]
+}
+
+export function purgeStaleTurnsForChat(
+  chatId: string,
+  keys: Iterable<string>,
+  purger: (key: string) => void,
+): PurgeStaleTurnsResult {
+  if (!chatId) return { purged: [] }
+  const purged: string[] = []
+  // Snapshot first — `purger` typically deletes from the same Map the
+  // caller is iterating; mutating during iteration is correct on JS
+  // Maps but a snapshot makes the contract explicit and lets the
+  // helper accept any iterable.
+  const snapshot: string[] = []
+  for (const k of keys) snapshot.push(k)
+  for (const key of snapshot) {
+    const sep = key.indexOf(':')
+    if (sep < 0) continue // malformed / non-statusKey shape — skip
+    const keyChat = key.slice(0, sep)
+    if (keyChat !== chatId) continue
+    purger(key)
+    purged.push(key)
+  }
+  return { purged }
+}

package/telegram-plugin/tests/inbound-delivery-gate.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { decideInboundDelivery } from '../gateway/inbound-delivery-gate.js'
+
+/**
+ * Regression coverage for #1556 — the lawgpt composer wedge.
+ *
+ * Before this gate, the gateway sent every inbound to the bridge
+ * immediately, buffering only when the bridge was offline. A
+ * non-steering message that arrived mid-turn was typed into claude's
+ * TUI composer and stranded when the auto-submit raced
+ * turn-completion. The deterministic invariant the gate enforces:
+ *
+ *   a non-steering inbound is delivered ONLY when no turn is in flight.
+ *
+ * Steering (/steer, /s) is the sole exemption — reaching claude
+ * mid-turn is the entire point of that feature.
+ */
+describe('decideInboundDelivery', () => {
+  it('delivers immediately when claude is idle (no turn in flight)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: false, isSteering: false }),
+    ).toBe('deliver')
+  })
+
+  it('BUFFERS a non-steering message that arrives mid-turn (the wedge fix)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: true, isSteering: false }),
+    ).toBe('buffer-until-idle')
+  })
+
+  it('delivers a steering message mid-turn (steering is intentionally exempt)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: true, isSteering: true }),
+    ).toBe('deliver')
+  })
+
+  it('delivers a steering message when idle (steer with no active turn)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: false, isSteering: true }),
+    ).toBe('deliver')
+  })
+
+  it('is total: the ONLY deferral path is mid-turn AND not steering', () => {
+    for (const turnInFlight of [true, false]) {
+      for (const isSteering of [true, false]) {
+        const decision = decideInboundDelivery({ turnInFlight, isSteering })
+        const expectBuffer = turnInFlight && !isSteering
+        expect(decision).toBe(expectBuffer ? 'buffer-until-idle' : 'deliver')
+      }
+    }
+  })
+})

package/telegram-plugin/tests/inbound-spool.test.ts

@@ -0,0 +1,229 @@
+/**
+ * inbound-spool — durable, crash-tolerant inbound spool.
+ *
+ * Pins the determinism guarantee: a buffered inbound survives a
+ * gateway/container restart (it's on the persistent volume), is
+ * replayed un-acked, acked only on confirmed delivery, deduped by a
+ * stable id, and escalated-then-dropped if undeliverable past its
+ * bound — so the "your message is queued" promise is ALWAYS resolved
+ * (delivered or visibly retracted), never silently lost (the
+ * finn/carrie lost-on-restart incident class, 2026-05-19).
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createInboundSpool,
+  spoolId,
+  type InboundSpoolFsSeam,
+} from '../gateway/inbound-spool.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+function msg(over: Partial<InboundMessage> = {}): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'c1',
+    messageId: 1001,
+    user: 'ken',
+    userId: 42,
+    ts: 1000,
+    text: 'hello',
+    meta: {},
+    ...over,
+  } as InboundMessage
+}
+
+/** In-memory fake fs keyed by path. Models append, full rewrite, and
+ *  atomic rename (so the tmp→rename compaction path is exercised). */
+function fakeFs(): InboundSpoolFsSeam & { dump(p?: string): string } {
+  const files = new Map<string, string>()
+  return {
+    appendFileSync: (p, d) => files.set(p, (files.get(p) ?? '') + d),
+    readFileSync: (p) => files.get(p) ?? '',
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (from, to) => {
+      files.set(to, files.get(from) ?? '')
+      files.delete(from)
+    },
+    existsSync: (p) => files.has(p),
+    statSizeSync: (p) => Buffer.byteLength(files.get(p) ?? ''),
+    dump: (p = PATH) => files.get(p) ?? '',
+  }
+}
+
+const PATH = '/state/agent/telegram/inbound-spool.jsonl'
+
+describe('spoolId — stable dedup key', () => {
+  it('real Telegram message → m:chat:msgId', () => {
+    expect(spoolId(msg({ chatId: 'c9', messageId: 55 }))).toBe('m:c9:55')
+  })
+  it('synthetic (messageId 0) → s:chat:source:ts (distinct events do not collapse)', () => {
+    const a = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    const b = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 200 }))
+    expect(a).toBe('s:c1:cron:100')
+    expect(a).not.toBe(b) // different ts = different logical event
+  })
+  it('same logical synthetic retried (same ts) dedups to the same id', () => {
+    const a = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    const b = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    expect(a).toBe(b)
+  })
+})
+
+describe('inbound-spool — put / ack / dedup', () => {
+  it('put records a live entry; dedups a re-put of the same id', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    expect(s.put('carrie', msg({ messageId: 7 }))).toBe(true)
+    expect(s.put('carrie', msg({ messageId: 7 }))).toBe(false) // dedup
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()).toHaveLength(1)
+    expect(s.liveEntries()[0].agent).toBe('carrie')
+  })
+
+  it('ack tombstones the entry; ack is idempotent / unknown-id safe', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    const m = msg({ messageId: 7 })
+    s.put('carrie', m)
+    s.ack(m)
+    expect(s.liveCount()).toBe(0)
+    s.ack(m) // idempotent
+    s.ack(msg({ messageId: 999 })) // unknown id, no throw
+    expect(s.liveCount()).toBe(0)
+  })
+
+  it('liveEntries is oldest-first (replay order)', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    s.put('a', msg({ messageId: 1 }))
+    s.put('a', msg({ messageId: 2 }))
+    s.put('a', msg({ messageId: 3 }))
+    expect(s.liveEntries().map((e) => e.msg.messageId)).toEqual([1, 2, 3])
+  })
+})
+
+describe('inbound-spool — crash-survivable replay (the core guarantee)', () => {
+  it('a fresh spool over an existing file rebuilds live state (survives restart)', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('carrie', msg({ messageId: 7, text: 'the craft message' }))
+    s1.put('carrie', msg({ messageId: 8 }))
+    s1.ack(msg({ messageId: 8 })) // 8 delivered before the "crash"
+    // Simulate gateway/container restart: brand-new spool, SAME file.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1)
+    const live = s2.liveEntries()
+    expect(live[0].msg.messageId).toBe(7)
+    expect(live[0].msg.text).toBe('the craft message') // full payload survived
+    expect(live[0].agent).toBe('carrie')
+  })
+
+  it('tolerates a torn final line (crash mid-append) — skips it, keeps the rest', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('carrie', msg({ messageId: 7 }))
+    // Append a half-written record (no newline, invalid JSON tail).
+    fs.appendFileSync(PATH, '{"t":"put","id":"m:c1:8","agen')
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1) // the torn line is ignored, 7 survives
+    expect(s2.liveEntries()[0].msg.messageId).toBe(7)
+  })
+
+  it('ignores any line that does not pass the shape check', () => {
+    const fs = fakeFs()
+    fs.appendFileSync(PATH, 'not json\n')
+    fs.appendFileSync(PATH, '{"t":"put"}\n') // missing id/msg/agent
+    fs.appendFileSync(PATH, '{"t":"weird","id":"x"}\n')
+    fs.appendFileSync(
+      PATH,
+      JSON.stringify({ t: 'put', id: 'm:c1:7', agent: 'a', firstAt: 1, msg: msg({ messageId: 7 }) }) + '\n',
+    )
+    const s = createInboundSpool({ path: PATH, fs })
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()[0].msg.messageId).toBe(7)
+  })
+})
+
+describe('inbound-spool — bounded escalation (promise always resolved)', () => {
+  it('escalates+drops only entries older than the bound; younger untouched', () => {
+    const fs = fakeFs()
+    let t = 1_000_000
+    const s = createInboundSpool({
+      path: PATH,
+      fs,
+      now: () => t,
+      escalateAfterMs: 10_000,
+    })
+    s.put('carrie', msg({ messageId: 1 })) // firstAt = 1_000_000
+    t = 1_005_000
+    s.put('carrie', msg({ messageId: 2 })) // firstAt = 1_005_000
+    t = 1_012_000 // msg1 is 12s old (>10s bound), msg2 is 7s old
+    const escalated: number[] = []
+    const n = s.sweepEscalations((e) => escalated.push(e.msg.messageId as number))
+    expect(n).toBe(1)
+    expect(escalated).toEqual([1])
+    expect(s.liveCount()).toBe(1) // msg2 still live
+    expect(s.liveEntries()[0].msg.messageId).toBe(2)
+  })
+
+  it('an escalated id stays dropped across a restart (tombstoned, not replayed)', () => {
+    const fs = fakeFs()
+    let t = 0
+    const s1 = createInboundSpool({ path: PATH, fs, now: () => t, escalateAfterMs: 100 })
+    s1.put('a', msg({ messageId: 1 }))
+    t = 1000
+    expect(s1.sweepEscalations(() => {})).toBe(1)
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(0) // not resurrected on replay
+  })
+})
+
+describe('inbound-spool — robustness', () => {
+  it('a failing appendFileSync does not throw and keeps in-memory live state', () => {
+    const fs = fakeFs()
+    fs.appendFileSync = () => {
+      throw new Error('ENOSPC')
+    }
+    const logs: string[] = []
+    const s = createInboundSpool({ path: PATH, fs, log: (l) => logs.push(l) })
+    expect(() => s.put('a', msg({ messageId: 1 }))).not.toThrow()
+    expect(s.liveCount()).toBe(1) // live delivery still works (degraded durability)
+    expect(logs.join('')).toContain('durability degraded')
+  })
+
+  it('compacts once past the size bound, dropping acked ids', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs, compactAtBytes: 200 })
+    for (let i = 1; i <= 20; i++) {
+      s.put('a', msg({ messageId: i, text: 'x'.repeat(50) }))
+      s.ack(msg({ messageId: i }))
+    }
+    s.put('a', msg({ messageId: 999 }))
+    // After compaction the file holds only the one live id, not the
+    // 20 acked put+ack pairs.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1)
+    expect(s2.liveEntries()[0].msg.messageId).toBe(999)
+    expect(fs.dump().split('\n').filter(Boolean).length).toBeLessThan(5)
+  })
+
+  it('atomic compaction: a rename crash leaves the ORIGINAL log intact (no loss)', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs, compactAtBytes: 200 })
+    for (let i = 1; i <= 10; i++) {
+      s.put('a', msg({ messageId: i, text: 'y'.repeat(50) }))
+    }
+    // Simulate a crash AFTER the tmp write but BEFORE/at the rename.
+    fs.renameSync = () => {
+      throw new Error('crash mid-compact')
+    }
+    s.put('a', msg({ messageId: 11, text: 'y'.repeat(50) })) // triggers maybeCompact → rename throws
+    // Original append-only log must still hold every live entry — the
+    // failed compaction is a no-op, never a truncation.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(11)
+    expect(s2.liveEntries().map((e) => e.msg.messageId)).toEqual([
+      1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+    ])
+  })
+})

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -247,3 +247,69 @@ describe('idleDrainTick — the 3rd drain trigger (finn orphan gap, 2026-05-19)'
     expect(probed).toBe(false) // cheap path: Map.get only, no bridge probe, no log
   })
 })
+
+describe('durable-spool integration (finn/carrie lost-on-restart fix)', () => {
+  function spySpool() {
+    const puts: string[] = []
+    const acks: string[] = []
+    return {
+      puts,
+      acks,
+      spool: {
+        put: (_a: string, m: InboundMessage) => {
+          puts.push(String(m.messageId))
+          return true
+        },
+        ack: (m: InboundMessage) => {
+          acks.push(String(m.messageId))
+        },
+        liveEntries: () => [],
+        sweepEscalations: () => 0,
+        liveCount: () => 0,
+      },
+    }
+  }
+
+  it('every push is durably spooled (chokepoint for all ~10 push sites)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    buf.push('carrie', inbound('user', 8))
+    expect(sp.puts).toEqual(['7', '8'])
+  })
+
+  it('a CONFIRMED delivery acks the spool; a miss does NOT (stays durable)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    // delivery succeeds → spool acked
+    redeliverBufferedInbound(buf, 'carrie', () => true, sp.spool as never)
+    expect(sp.acks).toEqual(['7'])
+
+    // delivery misses → NOT acked, re-buffered + still spooled
+    const sp2 = spySpool()
+    const buf2 = createPendingInboundBuffer({ log: () => {}, spool: sp2.spool as never })
+    buf2.push('carrie', inbound('user', 9))
+    redeliverBufferedInbound(buf2, 'carrie', () => false, sp2.spool as never)
+    expect(sp2.acks).toEqual([]) // never acked on a miss → survives for retry/escalation
+    expect(buf2.depth('carrie')).toBe(1) // re-buffered in memory too
+  })
+
+  it('idleDrainTick threads the spool through (ack only on delivered)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    idleDrainTick(buf, 'carrie', () => true, () => true, sp.spool as never)
+    expect(sp.acks).toEqual(['7'])
+  })
+
+  it('works with no spool (back-compat: undefined spool is a no-op)', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('carrie', inbound('user', 7))
+    expect(redeliverBufferedInbound(buf, 'carrie', () => true)).toEqual({
+      drained: 1,
+      redelivered: 1,
+      rebuffered: 0,
+    })
+  })
+})

package/telegram-plugin/tests/turn-state-purge.test.ts

@@ -0,0 +1,109 @@
+/**
+ * turn-state-purge — the silence-poke fallback's defense-in-depth
+ * cleanup. Pins the multi-chat safety + key-shape correctness that
+ * the gymbro/klanker held-mid-turn fix (2026-05-20) depends on.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { purgeStaleTurnsForChat } from '../gateway/turn-state-purge.js'
+
+function statusKey(chatId: string, threadId?: number): string {
+  return `${chatId}:${threadId ?? '_'}`
+}
+
+describe('purgeStaleTurnsForChat', () => {
+  it('returns [] and calls nothing when keys is empty', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat('123', [], () => calls++)
+    expect(r.purged).toEqual([])
+    expect(calls).toBe(0)
+  })
+
+  it('returns [] and calls nothing when chatId is empty (guard)', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat('', [statusKey('123')], () => calls++)
+    expect(r.purged).toEqual([])
+    expect(calls).toBe(0)
+  })
+
+  it('purges the canonical DM key for the firing chat (typical case)', () => {
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [statusKey('12345')],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['12345:_'])
+    expect(purged).toEqual(['12345:_'])
+  })
+
+  it('purges every sibling key for the same chat (multi-thread / dangling)', () => {
+    // This is the gymbro/klanker symptom: a stale activeTurnStartedAt
+    // entry under a different thread of the same chat survives the
+    // canonical purgeReactionTracking(fbKey).
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [
+        statusKey('12345'),       // DM, no thread
+        statusKey('12345', 42),    // thread 42
+        statusKey('12345', 99),    // thread 99
+      ],
+      (k) => purged.push(k),
+    )
+    expect(r.purged.sort()).toEqual(['12345:42', '12345:99', '12345:_'])
+    expect(purged).toHaveLength(3)
+  })
+
+  it('NEVER touches keys for OTHER chats (multi-chat safety — the #1546 guard)', () => {
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '12345',
+      [
+        statusKey('12345'),       // target chat — purge
+        statusKey('-1001234567890'),       // different chat — must NOT touch
+        statusKey('-1001234567890', 7),    // different chat thread — must NOT touch
+      ],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['12345:_'])
+    expect(purged).toEqual(['12345:_']) // ONLY the target chat
+  })
+
+  it('does not false-match on a chatId-prefix superstring (e.g. 123 vs 1234)', () => {
+    // If we used a naive startsWith on the WHOLE key, chatId "123"
+    // would falsely match key "1234:_". The helper splits on `:` and
+    // equates the chatId slice, which prevents that.
+    const purged: string[] = []
+    const r = purgeStaleTurnsForChat(
+      '123',
+      [statusKey('123'), statusKey('1234'), statusKey('12')],
+      (k) => purged.push(k),
+    )
+    expect(r.purged).toEqual(['123:_']) // ONLY the exact match
+  })
+
+  it('skips malformed keys (no `:`)', () => {
+    let calls = 0
+    const r = purgeStaleTurnsForChat(
+      '123',
+      ['malformed', '', 'no-colon-here', statusKey('123')],
+      () => calls++,
+    )
+    expect(r.purged).toEqual(['123:_'])
+    expect(calls).toBe(1)
+  })
+
+  it('accepts any iterable (snapshots before iteration — purger may delete)', () => {
+    // The real call site iterates `activeTurnStartedAt.keys()` and
+    // the purger deletes from that same Map. Snapshotting in the
+    // helper prevents iterator skew.
+    const map = new Map<string, number>()
+    map.set('123:_', 1)
+    map.set('123:7', 2)
+    map.set('999:_', 3)
+    const r = purgeStaleTurnsForChat('123', map.keys(), (k) => map.delete(k))
+    expect(r.purged.sort()).toEqual(['123:7', '123:_'])
+    expect([...map.keys()]).toEqual(['999:_']) // multi-chat safety preserved
+  })
+})