switchroom 0.13.52 → 0.13.54

package/telegram-plugin/tests/outbound-ordering.test.ts

@@ -170,6 +170,234 @@ describe('wrapBot — bot.api.* calls auto-lock by first-arg chat id', () => {
     expect(rb.message_id).toBe(20)
   })
 
+  it('SAME chat + DIFFERENT thread sendMessage calls dispatch concurrently (supergroup-mode unblock)', async () => {
+    // PR2 of supergroup-mode: chat-lock moved from chatId-only keying
+    // to (chat, thread) keying. Two topics in the same supergroup must
+    // not artificially serialize at the bot.api layer.
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    const dTopicA = deferred<{ message_id: number }>()
+    const dTopicB = deferred<{ message_id: number }>()
+    const started: string[] = []
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      started.push(`A:${t}`)
+      return dTopicA.promise
+    })
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      started.push(`B:${t}`)
+      return dTopicB.promise
+    })
+
+    // Same chatId "supergrp" but different message_thread_id.
+    const pA = wrapped.api.sendMessage('supergrp', 'planning msg', { message_thread_id: 17 })
+    const pB = wrapped.api.sendMessage('supergrp', 'cron digest', { message_thread_id: 23 })
+    await Promise.resolve(); await Promise.resolve()
+    // BOTH should have started — supergroup-mode parallelism guarantee.
+    expect(started).toEqual(['A:planning msg', 'B:cron digest'])
+
+    // Resolve B first; A's resolution must not delay B's return.
+    dTopicB.resolve({ message_id: 200 })
+    const rB = await pB
+    expect(rB.message_id).toBe(200)
+
+    dTopicA.resolve({ message_id: 100 })
+    const rA = await pA
+    expect(rA.message_id).toBe(100)
+  })
+
+  it('SAME chat + SAME thread sendMessage calls STILL serialize (per-topic ordering preserved)', async () => {
+    // Per-topic message order matters (a reply tied to a message_id
+    // must see that message exist first). The lock must still serialize
+    // within a topic.
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    const dSlow = deferred<{ message_id: number }>()
+    const startOrder: string[] = []
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      startOrder.push(`first:${t}`)
+      const r = await dSlow.promise
+      startOrder.push(`first:end:${t}`)
+      return r
+    })
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      startOrder.push(`second:${t}`)
+      return { message_id: 2 }
+    })
+
+    const p1 = wrapped.api.sendMessage('supergrp', 'first', { message_thread_id: 17 })
+    const p2 = wrapped.api.sendMessage('supergrp', 'second', { message_thread_id: 17 })
+
+    await Promise.resolve(); await Promise.resolve()
+    // Same thread → second waits for first.
+    expect(startOrder).toEqual(['first:first'])
+
+    dSlow.resolve({ message_id: 1 })
+    await Promise.all([p1, p2])
+    expect(startOrder).toEqual(['first:first', 'first:end:first', 'second:second'])
+  })
+
+  it('a 429 from one topic does NOT stall sends to a different topic in the same chat', async () => {
+    // CPO #8=B guardrail: when grammY's autoRetry transformer backs off
+    // on a 429 in topic A, topic B's sends must keep flowing. This test
+    // pins the contract by simulating a slow/rejecting first call (proxy
+    // for a 429+backoff path) on topic A and asserting topic B doesn't
+    // wait on it.
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    // Topic A's send hangs (proxy for an in-flight 429-backoff path);
+    // topic B's send must NOT wait on it.
+    const dTopicA = deferred<{ message_id: number }>()
+    const started: string[] = []
+    bot.api.sendMessage.mockImplementationOnce(async () => {
+      started.push('topicA:start')
+      return dTopicA.promise
+    })
+    bot.api.sendMessage.mockImplementationOnce(async () => {
+      started.push('topicB:start')
+      return { message_id: 2 }
+    })
+
+    const pA = wrapped.api.sendMessage('supergrp', 'overloaded', { message_thread_id: 17 })
+    const pB = wrapped.api.sendMessage('supergrp', 'unaffected', { message_thread_id: 23 })
+
+    // Topic B should complete WITHOUT waiting on topic A's hang.
+    const rB = await pB
+    expect(rB.message_id).toBe(2)
+    expect(started).toContain('topicB:start')
+
+    // Resolve A so the lock chain drains cleanly.
+    dTopicA.resolve({ message_id: 1 })
+    const rA = await pA
+    expect(rA.message_id).toBe(1)
+  })
+
+  it('strips message_thread_id=1 from sendMessage opts (General-topic Bot API quirk)', async () => {
+    // Telegram's General topic has id=1 at MTProto but the Bot API
+    // REJECTS message_thread_id=1 on send with HTTP 400 "message thread
+    // not found" (tdlib/telegram-bot-api#447). The wrapper strips id=1
+    // from the opts bag before the underlying API call.
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    bot.api.sendMessage.mockImplementationOnce(async () => ({ message_id: 1 }))
+
+    await wrapped.api.sendMessage('supergrp', 'hello General', { message_thread_id: 1 })
+
+    const callOpts = bot.api.sendMessage.mock.calls[0]![2]
+    expect(callOpts).toBeDefined()
+    expect((callOpts as Record<string, unknown>).message_thread_id).toBeUndefined()
+  })
+
+  it('preserves other opts when stripping message_thread_id=1', async () => {
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+    bot.api.sendMessage.mockImplementationOnce(async () => ({ message_id: 1 }))
+
+    await wrapped.api.sendMessage('supergrp', 'hello', {
+      message_thread_id: 1,
+      parse_mode: 'HTML',
+      reply_to_message_id: 42,
+    })
+
+    const callOpts = bot.api.sendMessage.mock.calls[0]![2] as Record<string, unknown>
+    expect(callOpts.message_thread_id).toBeUndefined()
+    expect(callOpts.parse_mode).toBe('HTML')
+    expect(callOpts.reply_to_message_id).toBe(42)
+  })
+
+  it('does NOT mutate the caller\'s opts object (strip uses a copy)', async () => {
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+    bot.api.sendMessage.mockImplementationOnce(async () => ({ message_id: 1 }))
+
+    const callerOpts = { message_thread_id: 1, parse_mode: 'HTML' as const }
+    await wrapped.api.sendMessage('supergrp', 'hello', callerOpts)
+
+    expect(callerOpts.message_thread_id).toBe(1)  // caller's object untouched
+  })
+
+  it('does NOT strip non-1 thread IDs', async () => {
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+    bot.api.sendMessage.mockImplementationOnce(async () => ({ message_id: 1 }))
+
+    await wrapped.api.sendMessage('supergrp', 'planning msg', { message_thread_id: 17 })
+
+    const callOpts = bot.api.sendMessage.mock.calls[0]![2] as Record<string, unknown>
+    expect(callOpts.message_thread_id).toBe(17)  // non-General threads untouched
+  })
+
+  it('two SAME-chat General-topic sends still serialize (id=1 normalized to chat-root lane)', async () => {
+    // After stripping id=1, the lock key normalizes to chatKey(chatId, null)
+    // = `chatId:_`. Two General-topic sends queue through the same
+    // chat-root lane preserving order (Telegram per-chat order matters).
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    const dSlow = deferred<{ message_id: number }>()
+    const order: string[] = []
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      order.push(`first:${t}`)
+      const r = await dSlow.promise
+      order.push(`first:end:${t}`)
+      return r
+    })
+    bot.api.sendMessage.mockImplementationOnce(async (_c: string, t: string) => {
+      order.push(`second:${t}`)
+      return { message_id: 2 }
+    })
+
+    const p1 = wrapped.api.sendMessage('supergrp', 'general msg 1', { message_thread_id: 1 })
+    const p2 = wrapped.api.sendMessage('supergrp', 'general msg 2', { message_thread_id: 1 })
+
+    await Promise.resolve(); await Promise.resolve()
+    expect(order).toEqual(['first:general msg 1'])  // second waits
+
+    dSlow.resolve({ message_id: 1 })
+    await Promise.all([p1, p2])
+    expect(order).toEqual(['first:general msg 1', 'first:end:general msg 1', 'second:general msg 2'])
+  })
+
+  it('General-topic strip does NOT serialize against non-General sends in the same chat', async () => {
+    // id=1 → chat-root lane. id=17 → its own lane. Independent dispatch.
+    const lock = createChatLock()
+    const bot = createMockBot()
+    const wrapped = lock.wrapBot({ api: bot.api as unknown as Record<string, unknown> }) as unknown as typeof bot
+
+    const dGeneral = deferred<{ message_id: number }>()
+    const dPlanning = deferred<{ message_id: number }>()
+    const started: string[] = []
+    bot.api.sendMessage.mockImplementationOnce(async () => {
+      started.push('general')
+      return dGeneral.promise
+    })
+    bot.api.sendMessage.mockImplementationOnce(async () => {
+      started.push('planning')
+      return dPlanning.promise
+    })
+
+    const pGeneral = wrapped.api.sendMessage('supergrp', 'g', { message_thread_id: 1 })
+    const pPlanning = wrapped.api.sendMessage('supergrp', 'p', { message_thread_id: 17 })
+
+    await Promise.resolve(); await Promise.resolve()
+    expect(started).toEqual(['general', 'planning'])  // both started concurrently
+
+    dPlanning.resolve({ message_id: 17 })
+    dGeneral.resolve({ message_id: 1 })
+    await Promise.all([pGeneral, pPlanning])
+  })
+
   it('react (setMessageReaction) queues behind an in-flight reply (sendMessage) to the same chat', async () => {
     const lock = createChatLock()
     const bot = createMockBot()

package/telegram-plugin/tests/parallel-turns-deadlock-fix.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest'
+
+/**
+ * PR3b regression pin: supergroup-mode parallel-turns deadlock fix.
+ *
+ * The bug. Pre-fix, the gateway used ONE map `activeTurnStartedAt`
+ * for two distinct concerns:
+ *   (a) "user-visible turn started" — set eagerly in the fresh-turn
+ *       branch on inbound RECEIPT, used by per-key reads (status-query
+ *       metric, wedge detection, progress timeout, etc.) that want a
+ *       receipt-side timestamp.
+ *   (b) "claude is currently busy on this turn" — the fleet-wide gate
+ *       at purgeReactionTracking / releaseTurnBufferGate /
+ *       idle-drain / inbound buffer-or-deliver, where `.size === 0`
+ *       means "claude is idle, safe to flush buffered inbound."
+ *
+ * Under fleet-shared / DM topology the two concerns coincide — every
+ * received inbound is delivered to claude — so the singleton worked.
+ *
+ * Under SUPERGROUP-OWNED topology (one agent owns the whole
+ * supergroup, multiple topics share the gateway process), they
+ * diverge:
+ *
+ *   1. Topic A delivers + processes — keyA in activeTurnStartedAt
+ *      (set on receipt) AND claudeBusyKeys (set on delivery).
+ *   2. Topic B inbound arrives → fresh-turn branch eagerly sets
+ *      keyB in activeTurnStartedAt, displays 👀 / starts typing.
+ *   3. `decideInboundDelivery` reads `turnInFlight = .size > 0` →
+ *      TRUE (keyA present) → B is buffered, NOT delivered to claude.
+ *   4. A's turn_end → purgeReactionTracking deletes keyA →
+ *      `.size === 0` check fires the held-inbound flush. BUT under
+ *      old (singleton) semantics, keyB is STILL in
+ *      activeTurnStartedAt (set in step 2, never cleared because B
+ *      never started in claude so no turn_end ever fires for B).
+ *   5. `.size > 0` (keyB lingers) → flush never runs → B's buffered
+ *      msg never delivered → B's user sees 👀 forever.
+ *
+ *   DEADLOCK.
+ *
+ * The fix splits concerns. `activeTurnStartedAt` keeps semantic (a)
+ * — set on receipt, all per-key reads use it. `claudeBusyKeys` (new)
+ * carries semantic (b) — set ONLY on successful sendToAgent
+ * (delivery), cleared on turn_end / disconnect / buffer-gate-release.
+ * Fleet gates switch to claudeBusyKeys. The deadlock breaks because
+ * step 5's gate now reads `claudeBusyKeys.size` which only ever held
+ * keyA (delivered) → after step 4's delete, size === 0 → flush →
+ * B's buffered msg delivered → claudeBusyKeys.add(keyB) → ... →
+ * B's eventual turn_end clears keyB.
+ *
+ * This test pins the load-bearing invariants. The actual wiring
+ * lives in `gateway.ts` and `disconnect-flush.ts`; this file is the
+ * structural-contract regression guard so a future "let's simplify
+ * the gates back to one map" refactor fails loudly here.
+ */
+
+describe('PR3b parallel-turns deadlock fix: claudeBusyKeys decoupled from activeTurnStartedAt', () => {
+  function makeState() {
+    const activeTurnStartedAt = new Map<string, number>()
+    const claudeBusyKeys = new Set<string>()
+    return { activeTurnStartedAt, claudeBusyKeys }
+  }
+
+  // Mirror the gateway's fresh-turn-on-receipt path (the part that
+  // updates the two maps). Stripped to ONLY the state mutations we
+  // care about for this invariant.
+  function receiveInbound(state: ReturnType<typeof makeState>, key: string, at: number): void {
+    state.activeTurnStartedAt.set(key, at)
+    // CRITICAL: claudeBusyKeys is NOT touched here. The whole point
+    // of the split is that receipt ≠ delivery.
+  }
+
+  function deliverToClaude(state: ReturnType<typeof makeState>, key: string): void {
+    // Mirror of markClaudeBusyForInbound at every successful
+    // sendToAgent callsite in gateway.ts.
+    state.claudeBusyKeys.add(key)
+  }
+
+  function turnEnd(state: ReturnType<typeof makeState>, key: string): void {
+    // Mirror of purgeReactionTracking + releaseTurnBufferGate —
+    // both maps cleared together at turn_end.
+    state.activeTurnStartedAt.delete(key)
+    state.claudeBusyKeys.delete(key)
+  }
+
+  function fleetGateOpen(state: ReturnType<typeof makeState>): boolean {
+    // Mirror of the four fleet-wide gates:
+    //   purgeReactionTracking line 1393:  if (claudeBusyKeys.size === 0)
+    //   releaseTurnBufferGate line 1484:  if (claudeBusyKeys.size === 0)
+    //   onScheduleRestart line 4020:      turnInFlight = .size > 0
+    //   idle-drain tick line 4343:        if (.size > 0) return false
+    //   handleInbound line 8087:          turnInFlightAtReceipt = .size > 0
+    return state.claudeBusyKeys.size === 0
+  }
+
+  it('pre-fix scenario: singleton map deadlocks supergroup-mode parallel turns', () => {
+    // Simulate the BROKEN behavior — one map serving both concerns
+    // (i.e. what would happen if claudeBusyKeys did NOT exist and
+    // the gates read activeTurnStartedAt.size). This is the
+    // *opposite* of the test below; documents what we're fixing.
+    const legacyState = new Map<string, number>()
+    const legacyFleetGate = () => legacyState.size === 0
+
+    // Step 1: A delivered (eager set on receipt)
+    legacyState.set('keyA', 100)
+    // Step 2: B received but buffered (eager set fires regardless)
+    legacyState.set('keyB', 200)
+    expect(legacyFleetGate()).toBe(false)
+
+    // Step 4: A's turn_end clears keyA
+    legacyState.delete('keyA')
+    // DEADLOCK — keyB lingers forever because B never started
+    // in claude so no turn_end ever fires for B.
+    expect(legacyFleetGate()).toBe(false)
+    expect(legacyState.has('keyB')).toBe(true)
+  })
+
+  it('post-fix scenario: split maps let A.turn_end unblock B', () => {
+    const state = makeState()
+
+    // Step 1: A's inbound received AND delivered to claude.
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    expect(state.activeTurnStartedAt.has('keyA')).toBe(true)
+    expect(state.claudeBusyKeys.has('keyA')).toBe(true)
+
+    // Step 2: B's inbound received, but `decideInboundDelivery`
+    // returned buffer-until-idle (turnInFlightAtReceipt was true
+    // because keyA is in claudeBusyKeys). B's fresh-turn branch
+    // STILL fired — eager activeTurnStartedAt[keyB] set —
+    // for the user-visible 👀 / typing indicator.
+    receiveInbound(state, 'keyB', 200)
+    // CRITICAL: claudeBusyKeys does NOT contain keyB because B was
+    // buffered, not delivered. The split semantics is the entire
+    // PR3b contract.
+    expect(state.activeTurnStartedAt.has('keyB')).toBe(true)
+    expect(state.claudeBusyKeys.has('keyB')).toBe(false)
+    expect(state.claudeBusyKeys.size).toBe(1)
+    expect(fleetGateOpen(state)).toBe(false)
+
+    // Step 4: A's turn_end clears keyA from BOTH maps.
+    turnEnd(state, 'keyA')
+
+    // Step 5 (the deadlock fix): fleet gate now OPENS because
+    // claudeBusyKeys is empty, even though activeTurnStartedAt
+    // still has keyB (which is fine — that's the user-visible
+    // receipt timestamp, not the claude-busy flag).
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(state.activeTurnStartedAt.has('keyB')).toBe(true)
+    expect(fleetGateOpen(state)).toBe(true)
+
+    // The flush triggers → B's buffered msg gets sent →
+    // deliverToClaude fires for keyB → busy gate closes again.
+    deliverToClaude(state, 'keyB')
+    expect(fleetGateOpen(state)).toBe(false)
+
+    // B's turn_end completes the cycle.
+    turnEnd(state, 'keyB')
+    expect(state.activeTurnStartedAt.size).toBe(0)
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(fleetGateOpen(state)).toBe(true)
+  })
+
+  it('per-key reads (priorTurnStartedAt timing, status-query metric) keep working on activeTurnStartedAt', () => {
+    // The split must not regress per-key timestamp reads. These all
+    // want the RECEIPT timestamp (the user's send-time, not when
+    // claude finally got to it), so they correctly read
+    // activeTurnStartedAt — preserved across the buffer window.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    receiveInbound(state, 'keyB', 200) // buffered, no deliverToClaude
+
+    // A second message on keyB arriving during the buffer window —
+    // mid-turn classification reads activeTurnStartedAt.get(keyB)
+    // for `priorTurnStartedAt`, which must still be 200 (the
+    // original receipt time, even though B never reached claude).
+    expect(state.activeTurnStartedAt.get('keyB')).toBe(200)
+    // And keyA's receipt timestamp is preserved too — A's
+    // follow-ups during its own processing window get accurate
+    // secondsSinceTurnStart metric.
+    expect(state.activeTurnStartedAt.get('keyA')).toBe(100)
+  })
+
+  it('disconnect-flush sweeps both maps together (the bridge died, all in-flight turns are dead)', () => {
+    // Mirror of the disconnect-flush sweep loop in disconnect-flush.ts —
+    // a registered-agent disconnect clears both maps because every
+    // turn it was processing is dead by definition.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    receiveInbound(state, 'keyB', 200) // buffered
+
+    // Bridge dies (claude crashed mid-A). Sweep both maps.
+    for (const k of [...state.activeTurnStartedAt.keys()]) {
+      state.activeTurnStartedAt.delete(k)
+      state.claudeBusyKeys.delete(k)
+    }
+
+    expect(state.activeTurnStartedAt.size).toBe(0)
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(fleetGateOpen(state)).toBe(true)
+  })
+
+  it('idempotent: multiple inbounds for the same key (e.g. A user spamming) are a single entry', () => {
+    // Set semantics — A's 5 follow-up messages while A is processing
+    // collapse to a single claudeBusyKeys entry. Turn_end clears
+    // once; size accounting stays correct.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    deliverToClaude(state, 'keyA')
+    deliverToClaude(state, 'keyA')
+    expect(state.claudeBusyKeys.size).toBe(1)
+    turnEnd(state, 'keyA')
+    expect(state.claudeBusyKeys.size).toBe(0)
+  })
+})

package/telegram-plugin/tests/slash-command-smart-split.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import { resolveOutboundTopic } from '../../src/telegram/topic-router.js'
+
+/**
+ * PR5 — supergroup-mode slash-command smart-split (CPO #4).
+ *
+ * The gateway wires `runSwitchroomCommand` → `switchroomReply` →
+ * `slashCommandReplyOpts(ctx, classification)` → `resolveOutboundTopic`.
+ * The helper is a thin classifier on top of the existing router; this
+ * test pins the END contract that drives all 4 heavy-output commands
+ * (/logs, /audit, /upgradestatus, /memory) and any future mutation
+ * additions:
+ *
+ *   - query → follows the originating topic (or undefined for fleet/DM)
+ *   - mutation → admin alias (or undefined for fleet/DM)
+ *   - heavy → admin alias (or undefined for fleet/DM)
+ *
+ * The gateway wrapper additionally collapses `target === originThreadId`
+ * back to `{}` so a query in the originating topic doesn't write a
+ * redundant `message_thread_id` opt. That's a wire-shape micro-opt
+ * tested separately at the call site.
+ */
+
+describe('PR5 slash-command smart split — router contract', () => {
+  const supergroup = {
+    default_topic_id: 1,
+    topic_aliases: { planning: 17, admin: 31, alerts: 42 },
+  }
+  const fleet = {} // no chat_id / default_topic_id → fleet/DM
+
+  describe('query class', () => {
+    it('supergroup: follows originThreadId', () => {
+      expect(
+        resolveOutboundTopic(supergroup, {
+          kind: 'command-query',
+          originThreadId: 17,
+        }),
+      ).toBe(17)
+    })
+
+    it('fleet: returns originThreadId unchanged (caller passes-through)', () => {
+      expect(
+        resolveOutboundTopic(fleet, {
+          kind: 'command-query',
+          originThreadId: 17,
+        }),
+      ).toBe(17)
+    })
+
+    it('supergroup, no origin thread (chat root): default_topic_id fallback', () => {
+      // command-query returns originThreadId verbatim, including
+      // undefined; the wrapper collapses undefined to "no override"
+      // and grammY's ctx.reply picks the originating topic anyway.
+      expect(
+        resolveOutboundTopic(supergroup, {
+          kind: 'command-query',
+          originThreadId: undefined,
+        }),
+      ).toBeUndefined()
+    })
+  })
+
+  describe('mutation class', () => {
+    it('supergroup: routes to admin alias', () => {
+      expect(resolveOutboundTopic(supergroup, { kind: 'command-mutation' })).toBe(31)
+    })
+
+    it('supergroup with no admin alias: default_topic_id fallback', () => {
+      const cfg = { default_topic_id: 1, topic_aliases: { planning: 17 } }
+      expect(resolveOutboundTopic(cfg, { kind: 'command-mutation' })).toBe(1)
+    })
+
+    it('fleet: returns undefined (caller falls through to ctx.reply)', () => {
+      expect(resolveOutboundTopic(fleet, { kind: 'command-mutation' })).toBeUndefined()
+    })
+  })
+
+  describe('heavy class (the 4 commands actually wired in PR5)', () => {
+    it('supergroup: /logs /audit /upgradestatus /memory all route to admin', () => {
+      // All four commands fold through the same `slashCommandReplyOpts(ctx, "heavy")`
+      // wrapper, which fires the same router event. One assertion covers
+      // all of them.
+      expect(resolveOutboundTopic(supergroup, { kind: 'command-heavy' })).toBe(31)
+    })
+
+    it('supergroup with no admin alias: default_topic_id fallback', () => {
+      const cfg = { default_topic_id: 1, topic_aliases: { planning: 17 } }
+      expect(resolveOutboundTopic(cfg, { kind: 'command-heavy' })).toBe(1)
+    })
+
+    it('fleet: returns undefined (caller falls through to ctx.reply)', () => {
+      expect(resolveOutboundTopic(fleet, { kind: 'command-heavy' })).toBeUndefined()
+    })
+  })
+
+  describe('separation contract: query vs mutation/heavy take different paths', () => {
+    // Pins the structural intent: a query and a mutation issued from
+    // the SAME originating topic in the SAME supergroup must resolve
+    // to DIFFERENT topics. If anyone collapses the three classes back
+    // to one event kind, this test fails loudly.
+    it('query.originThread !== mutation.adminAlias', () => {
+      const q = resolveOutboundTopic(supergroup, {
+        kind: 'command-query',
+        originThreadId: 17,
+      })
+      const m = resolveOutboundTopic(supergroup, { kind: 'command-mutation' })
+      const h = resolveOutboundTopic(supergroup, { kind: 'command-heavy' })
+      expect(q).toBe(17)
+      expect(m).toBe(31)
+      expect(h).toBe(31)
+      expect(q).not.toBe(m)
+      expect(m).toBe(h) // mutation and heavy both → admin
+    })
+  })
+})

package/telegram-plugin/tests/typing-wrap.test.ts

@@ -2,8 +2,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createTypingWrapper } from '../typing-wrap.js'
 
 function makeDeps(overrides: { isSurfaceTool?: (name: string) => boolean } = {}) {
-  const startTypingLoop = vi.fn<(chatId: string) => void>()
-  const stopTypingLoop = vi.fn<(chatId: string) => void>()
+  // PR3 supergroup-mode: start/stop now take (chatId, threadId?). The
+  // existing tests cover the chatId-only case (threadId omitted → null);
+  // new tests below pin the per-thread isolation.
+  const startTypingLoop = vi.fn<(chatId: string, threadId?: number | null) => void>()
+  const stopTypingLoop = vi.fn<(chatId: string, threadId?: number | null) => void>()
   const isSurfaceTool =
     overrides.isSurfaceTool ??
     ((name: string) =>
@@ -28,7 +31,7 @@ describe('createTypingWrapper', () => {
     w.onToolUse('t1', 'chat-A', 'Bash')
     // First tool on a fresh chat fires immediately — no timer wait required.
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.startTypingLoop).toHaveBeenCalledWith('chat-A')
+    expect(deps.startTypingLoop).toHaveBeenCalledWith('chat-A', null)
   })
 
   it('a parallel second tool on the same chat uses the debounce', () => {
@@ -69,7 +72,7 @@ describe('createTypingWrapper', () => {
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
     w.onToolResult('t1')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.stopTypingLoop).toHaveBeenCalledWith('chat-A')
+    expect(deps.stopTypingLoop).toHaveBeenCalledWith('chat-A', null)
   })
 
   it('skips surface tools (reply/stream_reply/edit_message/react)', () => {
@@ -93,16 +96,16 @@ describe('createTypingWrapper', () => {
     w.onToolUse('t1', 'chat-A', 'Bash')
     w.onToolUse('t2', 'chat-B', 'Grep')
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
-    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A')
-    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-B')
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A', null)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-B', null)
 
     w.onToolResult('t1')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A')
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A', null)
 
     w.onToolResult('t2')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(2)
-    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-B')
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-B', null)
   })
 
   it('drainAll clears pending entries and stops any started loops', () => {
@@ -138,4 +141,58 @@ describe('createTypingWrapper', () => {
     vi.advanceTimersByTime(2)
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
   })
+
+  // ─── PR3 supergroup-mode: per-(chat,thread) lane isolation ────────────
+  it('SAME chat + DIFFERENT threads each get their own immediate-fire lane', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    // Both are "first tool on lane" — both fire immediately, not debounced.
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)
+    w.onToolUse('t2', 'chat-A', 'Read', 23)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A', 17)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-A', 23)
+  })
+
+  it('SAME chat + SAME thread STILL uses debounce on the second tool', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)
+    w.onToolUse('t2', 'chat-A', 'Read', 17)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(500)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+  })
+
+  it('stopping topic A does NOT clear topic B\'s lane (the headline bug fix)', () => {
+    // The bug: chatId-only keying meant `activeChats.delete(chatId)`
+    // when topic A's tool ended ALSO marked topic B's lane as inactive,
+    // so topic B's next tool would re-fire immediately (wrong — it's
+    // already typing) and a subsequent stop could mismatch.
+    // Per-(chat,thread) lane keying preserves independence.
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)   // topic A lane: active
+    w.onToolUse('t2', 'chat-A', 'Read', 23)   // topic B lane: active (independent)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+
+    w.onToolResult('t1')  // topic A done
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A', 17)
+    // Topic B is still active — a third tool on topic B should DEBOUNCE
+    // (lane is still active), not fire immediately.
+    w.onToolUse('t3', 'chat-A', 'Edit', 23)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)  // no immediate fire
+    vi.advanceTimersByTime(500)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(3)
+    expect(deps.startTypingLoop).toHaveBeenLastCalledWith('chat-A', 23)
+  })
+
+  it('treats undefined / null threadId as the same lane (chatKey null/0 collapse)', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash')           // undefined thread
+    w.onToolUse('t2', 'chat-A', 'Read', null)     // null thread — same lane
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)  // only first fires immediately
+    expect(deps.startTypingLoop).toHaveBeenLastCalledWith('chat-A', null)
+  })
 })