switchroom 0.18.10 → 0.18.12

package/telegram-plugin/tests/status-pin.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { GrammyError } from 'grammy'
-import { decidePinAction } from '../status-pin.js'
+import { decidePinAction, isPinRightsError, PinRightsCache } from '../status-pin.js'
 import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
 import type { PinState } from '../status-pin.js'
 
@@ -200,3 +200,277 @@ describe('reconcilePin — pin-rights 400 must never crash (marko 2026-07-01)',
     }
   })
 })
+
+// ── #3024: rights-aware negative cache ─────────────────────────────────────
+// marko logged 41 identical `pinChatMessage` "not enough rights" rejections in
+// 48h — one per auto status-pin attempt in a group where the bot isn't a pin
+// admin. The permanent-rights class is now cached per-chat so the SECOND and
+// later attempts skip the API call entirely and stop spamming the log. Synthetic
+// chat IDs only (the real ones in the issue are operator PII).
+describe('isPinRightsError (pure classifier)', () => {
+  it('matches the permanent pin-rights 400 (grammy .description)', () => {
+    expect(
+      isPinRightsError(
+        grammyError(400, 'Bad Request: not enough rights to manage pinned messages in the chat'),
+      ),
+    ).toBe(true)
+  })
+
+  it('matches a plain Error carrying the rights text', () => {
+    expect(isPinRightsError(new Error('not enough rights to manage pinned messages'))).toBe(true)
+  })
+
+  it('does NOT match transient classes (429 flood-wait, network)', () => {
+    expect(isPinRightsError(grammyError(429, 'Too Many Requests: retry after 5'))).toBe(false)
+    expect(isPinRightsError(new Error('fetch failed'))).toBe(false)
+    expect(isPinRightsError(grammyError(400, 'Bad Request: message to edit not found'))).toBe(false)
+  })
+})
+
+describe('PinRightsCache (pure)', () => {
+  it('block() returns true only the first time a chat is added (log-once)', () => {
+    const cache = new PinRightsCache()
+    expect(cache.isBlocked('-1009000000001')).toBe(false)
+    expect(cache.block('-1009000000001')).toBe(true)
+    expect(cache.block('-1009000000001')).toBe(false)
+    expect(cache.isBlocked('-1009000000001')).toBe(true)
+  })
+
+  it('clear() forgets a chat (rights re-granted)', () => {
+    const cache = new PinRightsCache()
+    cache.block('-1009000000001')
+    expect(cache.clear('-1009000000001')).toBe(true)
+    expect(cache.isBlocked('-1009000000001')).toBe(false)
+    expect(cache.clear('-1009000000001')).toBe(false)
+  })
+})
+
+/** A fake Bot API counting pin calls, throwing a chosen error on pin. */
+function countingApi(pinError?: unknown) {
+  let pinCalls = 0
+  let unpinCalls = 0
+  const api: PinBotApi = {
+    pinChatMessage: async () => {
+      pinCalls += 1
+      if (pinError) throw pinError
+    },
+    unpinChatMessage: async () => {
+      unpinCalls += 1
+    },
+  }
+  return {
+    api,
+    get pinCalls() {
+      return pinCalls
+    },
+    get unpinCalls() {
+      return unpinCalls
+    },
+  }
+}
+
+describe('reconcilePin — rights-aware negative cache (#3024)', () => {
+  const rightsErr = () =>
+    grammyError(400, 'Bad Request: not enough rights to manage pinned messages in the chat')
+
+  it('first rights failure: attempts once, logs once, records the chat', async () => {
+    const cache = new PinRightsCache()
+    const disabled: string[] = []
+    const pinFails: string[] = []
+    const t = countingApi(rightsErr())
+
+    const next = await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000001',
+      prevState: null,
+      desired: { pinned: true, messageId: 4 },
+      rightsCache: cache,
+      onPinRightsDisabled: (chat) => disabled.push(chat),
+      onError: (phase) => pinFails.push(phase),
+    })
+
+    expect(t.pinCalls).toBe(1) // it did try
+    expect(next).toBeNull() // no claim taken
+    expect(disabled).toEqual(['-1009000000001']) // logged once
+    expect(pinFails).toEqual([]) // NOT routed through the per-attempt onError
+    expect(cache.isBlocked('-1009000000001')).toBe(true)
+  })
+
+  it('second attempt in the same chat makes NO api call and logs nothing', async () => {
+    const cache = new PinRightsCache()
+    const disabled: string[] = []
+    const pinFails: string[] = []
+    const t = countingApi(rightsErr())
+
+    const common = {
+      chatId: '-1009000000001',
+      prevState: null,
+      desired: { pinned: true, messageId: 4 } as const,
+      rightsCache: cache,
+      onPinRightsDisabled: (chat: string) => disabled.push(chat),
+      onError: (phase: 'pin' | 'unpin') => pinFails.push(phase),
+    }
+
+    await reconcilePin({ api: t.api, ...common })
+    await reconcilePin({ api: t.api, ...common })
+
+    expect(t.pinCalls).toBe(1) // second attempt short-circuited before the API
+    expect(disabled).toEqual(['-1009000000001']) // still logged exactly once
+    expect(pinFails).toEqual([])
+  })
+
+  it('a DIFFERENT chat is unaffected by another chat being blocked', async () => {
+    const cache = new PinRightsCache()
+    cache.block('-1009000000001')
+    const t = countingApi() // pin succeeds here
+
+    const next = await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000002',
+      prevState: null,
+      desired: { pinned: true, messageId: 7 },
+      rightsCache: cache,
+      onPinRightsDisabled: () => {
+        throw new Error('should not disable a healthy chat')
+      },
+    })
+
+    expect(t.pinCalls).toBe(1)
+    expect(next).toEqual({ messageId: 7 })
+    expect(cache.isBlocked('-1009000000002')).toBe(false)
+  })
+
+  it('a 429 (transient) does NOT enter the cache — retry behaviour preserved', async () => {
+    const cache = new PinRightsCache()
+    const disabled: string[] = []
+    const pinFails: string[] = []
+    const t = countingApi(grammyError(429, 'Too Many Requests: retry after 5'))
+
+    await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000003',
+      prevState: null,
+      desired: { pinned: true, messageId: 9 },
+      rightsCache: cache,
+      onPinRightsDisabled: (chat) => disabled.push(chat),
+      onError: (phase) => pinFails.push(phase),
+    })
+
+    expect(cache.isBlocked('-1009000000003')).toBe(false) // NOT cached
+    expect(disabled).toEqual([]) // no rights-disable log
+    expect(pinFails).toEqual(['pin']) // routed through onError → normal retry path
+
+    // A follow-up attempt still hits the API (no negative cache in the way).
+    await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000003',
+      prevState: null,
+      desired: { pinned: true, messageId: 9 },
+      rightsCache: cache,
+      onError: (phase) => pinFails.push(phase),
+    })
+    expect(t.pinCalls).toBe(2)
+  })
+
+  it('a later successful pin clears a previously-blocked chat', async () => {
+    const cache = new PinRightsCache()
+    cache.block('-1009000000004')
+    const t = countingApi() // succeeds
+
+    // While blocked, the pin is skipped (no claim, no API call).
+    const skipped = await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000004',
+      prevState: null,
+      desired: { pinned: true, messageId: 3 },
+      rightsCache: cache,
+    })
+    expect(skipped).toBeNull()
+    expect(t.pinCalls).toBe(0)
+
+    // Simulate rights granted: unblock, then a pin succeeds and stays clear.
+    cache.clear('-1009000000004')
+    const next = await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000004',
+      prevState: null,
+      desired: { pinned: true, messageId: 3 },
+      rightsCache: cache,
+    })
+    expect(next).toEqual({ messageId: 3 })
+    expect(cache.isBlocked('-1009000000004')).toBe(false)
+  })
+
+  it('UNPIN rights-failure (rights revoked mid-session) blocks the chat, logs once, second unpin makes no API call', async () => {
+    const cache = new PinRightsCache()
+    const disabled: string[] = []
+    const unpinFails: string[] = []
+    let unpinCalls = 0
+    const api: PinBotApi = {
+      pinChatMessage: async () => {},
+      unpinChatMessage: async () => {
+        unpinCalls += 1
+        throw rightsErr()
+      },
+    }
+    const common = {
+      api,
+      chatId: '-1009000000007',
+      desired: { pinned: false } as const,
+      rightsCache: cache,
+      onPinRightsDisabled: (chat: string) => disabled.push(chat),
+      onError: (phase: 'pin' | 'unpin') => unpinFails.push(phase),
+    }
+
+    const first = await reconcilePin({ ...common, prevState: { messageId: 21 } })
+    expect(first).toBeNull() // claim dropped regardless (drop-on-unpin contract)
+    expect(unpinCalls).toBe(1) // it did try once
+    expect(disabled).toEqual(['-1009000000007']) // logged exactly once
+    expect(unpinFails).toEqual([]) // NOT routed through per-attempt onError
+    expect(cache.isBlocked('-1009000000007')).toBe(true)
+
+    const second = await reconcilePin({ ...common, prevState: { messageId: 22 } })
+    expect(second).toBeNull() // claim still dropped
+    expect(unpinCalls).toBe(1) // second attempt short-circuited before the API
+    expect(disabled).toEqual(['-1009000000007']) // no second log
+  })
+
+  it('a blocked chat skips the UNPIN api call too (drops the claim silently)', async () => {
+    const cache = new PinRightsCache()
+    cache.block('-1009000000005')
+    const t = countingApi()
+
+    const next = await reconcilePin({
+      api: t.api,
+      chatId: '-1009000000005',
+      prevState: { messageId: 12 },
+      desired: { pinned: false },
+      rightsCache: cache,
+    })
+
+    expect(next).toBeNull() // claim dropped
+    expect(t.unpinCalls).toBe(0) // but no wasted API call
+  })
+
+  it('fire-and-forget with the cache leaks NO unhandledRejection', async () => {
+    const rejections: unknown[] = []
+    const onUnhandled = (err: unknown) => rejections.push(err)
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const cache = new PinRightsCache()
+      const t = countingApi(rightsErr())
+      void reconcilePin({
+        api: t.api,
+        chatId: '-1009000000006',
+        prevState: null,
+        desired: { pinned: true, messageId: 4 },
+        rightsCache: cache,
+        onPinRightsDisabled: () => {},
+      })
+      await new Promise((r) => setTimeout(r, 20))
+      expect(rejections).toEqual([])
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+})

package/telegram-plugin/tests/subagent-watcher-deferral-log-ratelimit.test.ts

@@ -0,0 +1,316 @@
+/**
+ * #3092 — the "silent-stall terminal synthesis deferred" line must not be
+ * re-emitted on every rescan tick.
+ *
+ * `checkStalls()` runs on the ~1s rescan interval and re-evaluates the
+ * in-flight deferral every time. The DECISION is correct (a worker inside a
+ * long `Bash` is alive, not dead, and must not have its card finalised) — but
+ * before this gate the decision was also RE-LOGGED every tick. Observed on the
+ * live overlord gateway 2026-07-11: 1,547 near-identical lines in ~35 minutes
+ * for a single worker id, differing only in the idle-seconds counter, while
+ * the gateway was concurrently hitting real Telegram 429 flood bans (#3084)
+ * whose lines were buried in the spam.
+ *
+ * Contract asserted here:
+ *   - first entry into the deferred state logs immediately (diagnosability),
+ *   - subsequent ticks are rate-limited to 1 line / `deferralLogIntervalMs`,
+ *   - the cap-crossing STATE CHANGE (deferral → terminal synthesis) always
+ *     logs,
+ *   - the resume STATE CHANGE (worker resurrects) always logs,
+ *   - the emitted lines still carry worker id / in-flight count / idle / cap.
+ *
+ * Deterministic fake clock + injected setInterval — no real timers.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+import * as fs from 'fs'
+
+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 }] } }
+}
+/** An assistant tool_use with no matching tool_result → the tool call is IN FLIGHT. */
+function bashToolUse(id: string) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', id, name: 'Bash', input: { command: 'npm test' } }] } }
+}
+/** The matching tool_result — drains the in-flight set and resurrects the worker. */
+function bashToolResult(id: string) {
+  return { type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: id, content: 'ok' }] } }
+}
+
+const DEFERRED_RE = /silent-stall terminal synthesis deferred/
+const CAP_RE = /in-flight deferral cap reached/
+const RESOLVED_RE = /in-flight deferral resolved/
+
+function makeHarness(opts: {
+  agentId?: string
+  deferralLogIntervalMs?: number
+  inflightTerminalCapMs?: number
+} = {}) {
+  const {
+    agentId = 'a732f61196738da7d', // the real (synthetic-safe) worker id shape from the incident
+    deferralLogIntervalMs,
+    inflightTerminalCapMs = 2_700_000, // 45 min — the cap in the incident log
+  } = opts
+
+  let currentTime = 1000
+  const logs: string[] = []
+
+  const agentDir = '/home/user/.switchroom/agents/myagent'
+  const sessionId = 'mock-session'
+  const projectsRoot = `${agentDir}/.claude/projects`
+  const projectDir = `${projectsRoot}/mock-cwd`
+  const sessionDir = `${projectDir}/${sessionId}`
+  const subagentsDir = `${sessionDir}/subagents`
+  const jsonlPath = `${subagentsDir}/agent-${agentId}.jsonl`
+  const fileContents = new Map<string, Buffer>()
+  fileContents.set(
+    jsonlPath,
+    Buffer.from(buildJSONL(subAgentUserMsg('bg task'), bashToolUse('tool-B')), 'utf-8'),
+  )
+
+  let lastOpenedPath: string | null = null
+  const mockFs = {
+    existsSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot || ps === projectDir || ps === sessionDir || ps === subagentsDir) return true
+      return fileContents.has(ps)
+    }) as typeof fs.existsSync,
+    readdirSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot) return ['mock-cwd']
+      if (ps === projectDir) return [sessionId]
+      if (ps === sessionDir) return ['subagents']
+      if (ps === subagentsDir) return [`agent-${agentId}.jsonl`]
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) => ({ size: fileContents.get(String(p))?.length ?? 0 }) as fs.Stats) as typeof fs.statSync,
+    openSync: ((p: fs.PathLike) => { lastOpenedPath = String(p); return 42 }) as unknown as typeof fs.openSync,
+    closeSync: (() => { lastOpenedPath = null }) as typeof fs.closeSync,
+    readSync: ((
+      _fd: number, buf: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null,
+    ): number => {
+      const content = lastOpenedPath != null ? fileContents.get(lastOpenedPath) : undefined
+      if (!content) return 0
+      const pos = position ?? 0
+      const src = content.slice(pos, pos + length)
+      ;(src as Buffer).copy(buf as Buffer, offset)
+      return src.length
+    }) as unknown as typeof fs.readSync,
+    watch: (() => ({ close: vi.fn() }) as unknown as fs.FSWatcher) as unknown as typeof fs.watch,
+  }
+
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  let nextRef = 1
+  const watcher = startSubagentWatcher({
+    agentDir,
+    // Tight windows so the deferral is reachable in a handful of ticks; the
+    // rate-limit under test is orthogonal to how we got into the state.
+    stallThresholdMs: 1000,
+    silentSynthesisStallThresholdMs: 5000,
+    silentStallTerminalMs: 5000,
+    inflightTerminalCapMs,
+    deferralLogIntervalMs,
+    rescanMs: 1000, // the production 1Hz tick — the cadence that produced the spam
+    log: (line) => logs.push(line),
+    now: () => currentTime,
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearInterval: (h) => {
+      const { ref } = h as { ref: number }
+      const idx = intervals.findIndex((i) => i.ref === ref)
+      if (idx !== -1) intervals.splice(idx, 1)
+    },
+    fs: mockFs,
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      intervals.sort((a, b) => a.fireAt - b.fireAt)
+      const next = intervals[0]
+      if (!next || next.fireAt > currentTime) break
+      next.fireAt += next.ms
+      next.fn()
+    }
+  }
+
+  /**
+   * Drive N discrete 1s ticks with the clock advancing between each — the
+   * faithful simulation of the production loop. (A single advance(N*1000)
+   * would fire N callbacks all observing the SAME `now`, which would mask a
+   * time-based gate.)
+   */
+  const tick = (n: number): void => { for (let i = 0; i < n; i++) advance(1000) }
+
+  const unmarkHistorical = (): void => {
+    const e = watcher.getRegistry().get(agentId)
+    if (e) e.historical = false
+  }
+
+  /** Land the matching tool_result — the worker resurrects. */
+  const resumeWorker = (): void => {
+    fileContents.set(
+      jsonlPath,
+      Buffer.from(
+        buildJSONL(subAgentUserMsg('bg task'), bashToolUse('tool-B'), bashToolResult('tool-B')),
+        'utf-8',
+      ),
+    )
+  }
+
+  /**
+   * The resumed worker starts a NEW long tool call (no tool_result) — it goes
+   * quiet again with something in flight, so the deferral path is re-entered.
+   */
+  const startNewToolCall = (): void => {
+    fileContents.set(
+      jsonlPath,
+      Buffer.from(
+        buildJSONL(
+          subAgentUserMsg('bg task'),
+          bashToolUse('tool-B'),
+          bashToolResult('tool-B'),
+          bashToolUse('tool-C'),
+        ),
+        'utf-8',
+      ),
+    )
+  }
+
+  return { logs, advance, tick, unmarkHistorical, resumeWorker, startNewToolCall, agentId }
+}
+
+describe('subagent-watcher: deferral log rate-limit (#3092)', () => {
+  it('logs the deferral ONCE on entry, then at most once per interval — not once per 1Hz tick', () => {
+    const h = makeHarness({ deferralLogIntervalMs: 60_000 })
+    h.advance(500)
+    h.unmarkHistorical()
+
+    // Get into the deferred state: cross the long-runner stall window, then
+    // the post-stall terminal window, with `tool-B` still in flight.
+    h.tick(12)
+    const afterEntry = h.logs.filter((l) => DEFERRED_RE.test(l))
+    expect(afterEntry.length).toBe(1) // first entry IS logged — diagnosability preserved
+
+    // The line must still carry the full diagnostic payload.
+    expect(afterEntry[0]).toContain(h.agentId)
+    expect(afterEntry[0]).toContain('1 tool call(s) still in flight')
+    expect(afterEntry[0]).toMatch(/\d+s idle < 2700s cap/)
+
+    // Now 600 more 1Hz ticks = 10 minutes of a persistently-stalled worker.
+    // Pre-fix this emitted ~600 lines. With a 60s interval it may emit at
+    // most ~10 more.
+    h.tick(600)
+    const deferred = h.logs.filter((l) => DEFERRED_RE.test(l))
+    expect(deferred.length).toBeLessThanOrEqual(11) // 1 entry + ≤10 periodic
+    expect(deferred.length).toBeGreaterThanOrEqual(2) // still periodically visible
+    // The regression this guards: NOT one line per tick.
+    expect(deferred.length).toBeLessThan(50)
+  })
+
+  it('reproduces the incident scale: ~35min at 1Hz emits a handful of lines, not ~1500', () => {
+    // The real evidence: 1,547 lines in ~35 minutes for one worker id.
+    const h = makeHarness({ deferralLogIntervalMs: 60_000 })
+    h.advance(500)
+    h.unmarkHistorical()
+    h.tick(2100) // 35 minutes of 1Hz ticks
+
+    const deferred = h.logs.filter((l) => DEFERRED_RE.test(l))
+    // 35 min / 60s ≈ 35 periodic lines + the entry line. Wildly below 1,547.
+    expect(deferred.length).toBeLessThanOrEqual(40)
+    // Every emitted line still names the worker and its in-flight count.
+    for (const line of deferred) {
+      expect(line).toContain(h.agentId)
+      expect(line).toContain('tool call(s) still in flight')
+    }
+  })
+
+  it('STATE CHANGE — a resurrecting worker always logs, even mid-suppression', () => {
+    const h = makeHarness({ deferralLogIntervalMs: 60_000 })
+    h.advance(500)
+    h.unmarkHistorical()
+    h.tick(12) // enter the deferred state (1 line)
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(1)
+
+    h.tick(20) // 20 suppressed ticks — well inside the 60s window
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(1)
+
+    // The worker resurrects (the incident worker did exactly this).
+    h.resumeWorker()
+    h.tick(2)
+
+    const resolved = h.logs.filter((l) => RESOLVED_RE.test(l))
+    expect(resolved.length).toBe(1) // the transition is NOT suppressed
+    expect(resolved[0]).toContain(h.agentId)
+    expect(resolved[0]).toContain('deferral was correct')
+    // The suppressed volume is accounted for, not silently dropped.
+    expect(resolved[0]).toMatch(/\d+ deferral tick\(s\) suppressed/)
+    expect(h.logs.some((l) => /stall cleared/.test(l))).toBe(true)
+  })
+
+  it('STATE CHANGE — crossing the cap always logs the terminal synthesis', () => {
+    // Compressed cap so the crossing is reachable in a bounded tick count.
+    const h = makeHarness({ deferralLogIntervalMs: 60_000, inflightTerminalCapMs: 120_000 })
+    h.advance(500)
+    h.unmarkHistorical()
+    h.tick(12)
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(1)
+
+    h.tick(130) // cross the 120s cap
+    const cap = h.logs.filter((l) => CAP_RE.test(l))
+    expect(cap.length).toBe(1) // the cap-crossing is NOT suppressed
+    expect(cap[0]).toContain(h.agentId)
+    expect(cap[0]).toContain('proceeding with terminal synthesis')
+    expect(cap[0]).toMatch(/\d+ deferral tick\(s\) suppressed/)
+
+    // And the deferral lines over that whole window stayed bounded.
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBeLessThanOrEqual(4)
+  })
+
+  it('a re-stall after a resume logs its first deferral again (gate re-arms)', () => {
+    const h = makeHarness({ deferralLogIntervalMs: 60_000 })
+    h.advance(500)
+    h.unmarkHistorical()
+    h.tick(12)
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(1)
+
+    h.resumeWorker()
+    h.tick(2)
+    expect(h.logs.filter((l) => RESOLVED_RE.test(l)).length).toBe(1)
+
+    // The resumed worker goes quiet again inside a NEW tool call. Its first
+    // deferral must log immediately rather than being swallowed by the
+    // still-open 60s window from the previous stall episode.
+    h.startNewToolCall()
+    h.tick(14)
+    expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(2)
+  })
+
+  it('env override SWITCHROOM_SUBAGENT_DEFERRAL_LOG_INTERVAL_MS is honored', () => {
+    const saved = process.env.SWITCHROOM_SUBAGENT_DEFERRAL_LOG_INTERVAL_MS
+    process.env.SWITCHROOM_SUBAGENT_DEFERRAL_LOG_INTERVAL_MS = '10000'
+    try {
+      const h = makeHarness() // no config arg → env wins
+      h.advance(500)
+      h.unmarkHistorical()
+      h.tick(12)
+      expect(h.logs.filter((l) => DEFERRED_RE.test(l)).length).toBe(1)
+
+      // 60 ticks at a 10s interval → ~6 more lines, not 60.
+      h.tick(60)
+      const deferred = h.logs.filter((l) => DEFERRED_RE.test(l)).length
+      expect(deferred).toBeGreaterThanOrEqual(5)
+      expect(deferred).toBeLessThanOrEqual(9)
+    } finally {
+      if (saved === undefined) delete process.env.SWITCHROOM_SUBAGENT_DEFERRAL_LOG_INTERVAL_MS
+      else process.env.SWITCHROOM_SUBAGENT_DEFERRAL_LOG_INTERVAL_MS = saved
+    }
+  })
+})

package/telegram-plugin/tests/turn-end-gate-backstop.test.ts

@@ -0,0 +1,92 @@
+/**
+ * #2094 finding 1 — turn_end gate-wedge backstop.
+ *
+ * Outcome contract: if a pre-purge op in the turn_end handler body THROWS
+ * before the canonical purge (endCurrentTurnAtomic → purgeReactionTracking)
+ * runs, the guarded finally must still clear this turn's gate state
+ * (activeTurnStartedAt + the mirrored claudeBusyKeys) so the #1556 inbound
+ * gate re-opens for the next inbound. On the happy path — where the body
+ * clears the key itself — the backstop must be a no-op (no double purge), and
+ * the original error must always propagate.
+ */
+import { describe, it, expect } from 'vitest'
+import { withTurnEndGateBackstop } from '../gateway/turn-end-gate-backstop.js'
+
+interface Turn {
+  sessionChatId: string
+  sessionThreadId?: number
+}
+
+function statusKey(chatId: string, threadId?: number): string {
+  return `${chatId}:${threadId ?? '_'}`
+}
+
+/** Mirror of the production gate state + a purge that clears it, as
+ * purgeReactionTracking does (activeTurnStartedAt.delete + claudeBusyKeys
+ * drain for the key). */
+function freshGate(turn: Turn) {
+  const key = statusKey(turn.sessionChatId, turn.sessionThreadId)
+  const activeTurnStartedAt = new Map<string, number>([[key, Date.now()]])
+  const claudeBusyKeys = new Set<string>([key])
+  const purgeCalls: Array<{ key: string; endingTurn: Turn | undefined }> = []
+  const purge = (k: string, endingTurn: Turn | undefined) => {
+    purgeCalls.push({ key: k, endingTurn })
+    activeTurnStartedAt.delete(k)
+    claudeBusyKeys.delete(k)
+  }
+  return { key, activeTurnStartedAt, claudeBusyKeys, purge, purgeCalls }
+}
+
+function deps(gate: ReturnType<typeof freshGate>) {
+  return {
+    hasActiveTurn: (k: string) => gate.activeTurnStartedAt.has(k),
+    purge: gate.purge,
+    log: () => {},
+  }
+}
+
+describe('withTurnEndGateBackstop (#2094 finding 1)', () => {
+  it('a throw in a pre-purge op still clears the gate for the next inbound', () => {
+    const turn: Turn = { sessionChatId: '12345' }
+    const gate = freshGate(turn)
+
+    // The body throws BEFORE it reaches endCurrentTurnAtomic → purge (models
+    // a throw in redactOutboundText / progressDriver?.takeOverCard).
+    expect(() =>
+      withTurnEndGateBackstop(gate.key, turn, () => {
+        throw new Error('redactOutboundText blew up')
+      }, deps(gate)),
+    ).toThrow('redactOutboundText blew up')
+
+    // Outcome: gate is OPEN again — both maps cleared, so the #1556 inbound
+    // gate no longer wedges the next inbound.
+    expect(gate.activeTurnStartedAt.has(gate.key)).toBe(false)
+    expect(gate.claudeBusyKeys.has(gate.key)).toBe(false)
+    // The backstop fired exactly once, forwarding the ending turn.
+    expect(gate.purgeCalls).toEqual([{ key: gate.key, endingTurn: turn }])
+  })
+
+  it('is a no-op on the happy path (body already purged) — no double purge', () => {
+    const turn: Turn = { sessionChatId: '12345', sessionThreadId: 7 }
+    const gate = freshGate(turn)
+
+    withTurnEndGateBackstop(gate.key, turn, () => {
+      // Model the canonical clean branch: endCurrentTurnAtomic → purge ran.
+      gate.purge(gate.key, turn)
+    }, deps(gate))
+
+    // Purge happened exactly once (the canonical one); the finally saw the
+    // key already gone and did NOT re-fire the inconsistent shadow trace.
+    expect(gate.purgeCalls).toHaveLength(1)
+    expect(gate.activeTurnStartedAt.has(gate.key)).toBe(false)
+  })
+
+  it('does nothing when there was no live turn (null key)', () => {
+    const gate = freshGate({ sessionChatId: '12345' })
+    // A different, unrelated gate state; null key means no turn to end.
+    let ran = false
+    withTurnEndGateBackstop(null, null, () => { ran = true }, deps(gate))
+    expect(ran).toBe(true)
+    expect(gate.purgeCalls).toHaveLength(0)
+  })
+})