switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/progress-card-pin-manager.test.ts

@@ -1,773 +0,0 @@
-/**
- * Integration tests for the pin-lifecycle manager.
- *
- * Previously this logic lived inline in gateway.ts (progressDriver
- * setup block) and was unreachable from tests — the full
- * first-emit → pin → edit → turn-end → unpin sequence had no direct
- * coverage. This suite pins all the behaviors the gateway depends on,
- * plus failure branches that only exist in production until now.
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import {
-  createPinManager,
-  type PinManager,
-  type PinManagerDeps,
-  type ActivePinEntry,
-  type TimerHandle,
-} from '../progress-card-pin-manager.js'
-import { errors } from './fake-bot-api.js'
-
-interface PendingTimer {
-  fn: () => void
-  ms: number
-  cancelled: boolean
-  fired: boolean
-}
-
-interface Harness {
-  mgr: PinManager
-  deps: {
-    pin: ReturnType<typeof vi.fn>
-    unpin: ReturnType<typeof vi.fn>
-    deleteMessage: ReturnType<typeof vi.fn>
-    addPin: ReturnType<typeof vi.fn>
-    removePin: ReturnType<typeof vi.fn>
-    log: ReturnType<typeof vi.fn>
-  }
-  /** Recorded sidecar state — tests assert on this directly. */
-  sidecar: ActivePinEntry[]
-  /** Captured pin-delay timers — tests fire them manually. */
-  timers: PendingTimer[]
-  /** Fire every pending (not-yet-fired, not-cancelled) timer. */
-  fireTimers(): void
-}
-
-/** Build a harness with sensible defaults. `now` is fixed at 10_000. */
-function mkHarness(overrides: Partial<PinManagerDeps> = {}): Harness {
-  const sidecar: ActivePinEntry[] = []
-  const timers: PendingTimer[] = []
-
-  const deps = {
-    pin: vi.fn(async () => true),
-    unpin: vi.fn(async () => true),
-    deleteMessage: vi.fn(async () => true),
-    addPin: vi.fn((entry: ActivePinEntry) => {
-      sidecar.push(entry)
-    }),
-    removePin: vi.fn((chatId: string, messageId: number) => {
-      const idx = sidecar.findIndex((e) => e.chatId === chatId && e.messageId === messageId)
-      if (idx >= 0) sidecar.splice(idx, 1)
-    }),
-    log: vi.fn(),
-  }
-
-  const scheduleTimer = (fn: () => void, ms: number): TimerHandle => {
-    const entry: PendingTimer = { fn, ms, cancelled: false, fired: false }
-    timers.push(entry)
-    return {
-      cancel() {
-        entry.cancelled = true
-      },
-    }
-  }
-
-  const mgr = createPinManager({
-    ...deps,
-    now: () => 10_000,
-    scheduleTimer,
-    ...overrides,
-  })
-
-  const fireTimers = (): void => {
-    // Snapshot so timers pushed during firing don't run this pass.
-    const snapshot = [...timers]
-    for (const t of snapshot) {
-      if (t.cancelled || t.fired) continue
-      t.fired = true
-      t.fn()
-    }
-  }
-
-  return { mgr, deps, sidecar, timers, fireTimers }
-}
-
-describe('createPinManager', () => {
-  describe('considerPin — first emit', () => {
-    it('pins the message, records the sidecar entry, tracks the turnKey', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({
-        chatId: 'chat-1',
-        threadId: '42',
-        turnKey: 'chat-1:42:1',
-        messageId: 500,
-        isFirstEmit: true,
-      })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // Bot API was called with the exact shape the gateway used inline.
-      expect(h.deps.pin).toHaveBeenCalledWith('chat-1', 500, { disable_notification: true })
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-      // Sidecar recorded the pin with the injected clock.
-      expect(h.sidecar).toEqual([
-        { chatId: 'chat-1', messageId: 500, turnKey: 'chat-1:42:1', pinnedAt: 10_000, agentId: '__parent__' },
-      ])
-      // In-memory index reflects the pin.
-      expect(h.mgr.pinnedTurnKeys()).toEqual(['chat-1:42:1'])
-      expect(h.mgr.pinnedMessageId('chat-1:42:1')).toBe(500)
-    })
-
-    it('ignores emits where isFirstEmit=false', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({
-        chatId: 'chat-1',
-        turnKey: 'chat-1:1',
-        messageId: 500,
-        isFirstEmit: false,
-      })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.deps.addPin).not.toHaveBeenCalled()
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-    })
-
-    it('is idempotent — a second isFirstEmit for the same turnKey does nothing', async () => {
-      const h = mkHarness()
-      const c = {
-        chatId: 'c',
-        turnKey: 'c:1',
-        messageId: 500,
-        isFirstEmit: true,
-      }
-      h.mgr.considerPin(c)
-      h.mgr.considerPin({ ...c, messageId: 501 })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // Only the first pin landed.
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-      expect(h.deps.pin).toHaveBeenCalledWith('c', 500, { disable_notification: true })
-      expect(h.deps.addPin).toHaveBeenCalledTimes(1)
-      expect(h.mgr.pinnedMessageId('c:1')).toBe(500)
-    })
-
-    it('different turnKeys pin independently', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:2', messageId: 501, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(2)
-      expect(h.mgr.pinnedTurnKeys().sort()).toEqual(['c:1', 'c:2'])
-    })
-
-    it('works without a sidecar (no agentDir in production = no addPin wired)', async () => {
-      const h = mkHarness({ addPin: undefined, removePin: undefined })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalled()
-      expect(h.mgr.pinnedMessageId('c:1')).toBe(500)
-    })
-  })
-
-  describe('considerPin — failure rollback', () => {
-    it('firePin API rejection deletes from pinned map and clears sidecar', async () => {
-      const h = mkHarness()
-      h.deps.pin.mockRejectedValueOnce(errors.forbidden('pinChatMessage'))
-
-      h.mgr.considerPin({
-        chatId: 'c',
-        turnKey: 'c:1',
-        messageId: 500,
-        isFirstEmit: true,
-      })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // Sidecar rolled back.
-      expect(h.deps.removePin).toHaveBeenCalledWith('c', 500)
-      expect(h.sidecar).toEqual([])
-      // Log captured the failure.
-      expect(h.deps.log).toHaveBeenCalledWith(
-        expect.stringMatching(/progress-card pin failed/),
-      )
-      // In-memory entry is dropped — the pin never landed, so a later
-      // completeTurn must not issue an unpin against a non-existent pin.
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-      expect(h.mgr.pinnedMessageId('c:1')).toBeUndefined()
-
-      // Trigger an unpin and assert deps.unpin was NOT called — the key
-      // was already removed from `pinned`, so completeTurn is a no-op.
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-
-    it('pin rejection with 429: log line still fires, no retry', async () => {
-      const h = mkHarness()
-      h.deps.pin.mockRejectedValueOnce(errors.floodWait(3, 'pinChatMessage'))
-
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-      expect(h.deps.log).toHaveBeenCalled()
-    })
-  })
-
-  describe('completeTurn — unpin', () => {
-    it('unpins the pinned message and clears the sidecar', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.sidecar).toHaveLength(1)
-
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-      expect(h.sidecar).toEqual([])
-      expect(h.mgr.pinnedMessageId('c:1')).toBeUndefined()
-    })
-
-    it('no-op when the turn was never pinned', async () => {
-      const h = mkHarness()
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:never' })
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-
-    it('duplicate completeTurn does not double-unpin', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledTimes(1)
-      expect(h.deps.removePin).toHaveBeenCalledTimes(1)
-    })
-
-    it('unpin rejection still removes the sidecar entry', async () => {
-      const h = mkHarness()
-      h.deps.unpin.mockRejectedValueOnce(errors.badRequest('chat not found', 'unpinChatMessage'))
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      // Sidecar is cleared on unpin-attempt regardless of outcome —
-      // the sidecar exists for crash recovery, so leaving stale entries
-      // would cause duplicate unpins on the next boot.
-      expect(h.sidecar).toEqual([])
-      expect(h.deps.log).toHaveBeenCalledWith(
-        expect.stringMatching(/progress-card unpin failed/),
-      )
-    })
-  })
-
-  describe('unpinForChat — external cancellation hook', () => {
-    it('unpins every pinned turn matching a chat+thread', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:2', messageId: 501, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', threadId: '99', turnKey: 'c:99:1', messageId: 502, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.mgr.pinnedTurnKeys()).toHaveLength(3)
-
-      h.mgr.unpinForChat('c', 42)
-      await h.mgr.drainInFlight()
-
-      // Thread 42's pins were cleared, thread 99's remains.
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 501)
-      expect(h.deps.unpin).not.toHaveBeenCalledWith('c', 502)
-      expect(h.mgr.pinnedTurnKeys()).toEqual(['c:99:1'])
-    })
-
-    it('unpinForChat with no threadId matches chat-root turns only', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:1', messageId: 501, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.unpinForChat('c', undefined)
-      await h.mgr.drainInFlight()
-
-      // Only the chat-root turn (prefix "c:") was unpinned. The threaded
-      // turn (prefix "c:42:") also starts with "c:" in string terms —
-      // verify behaviour carefully. By current design, unpinForChat
-      // with no thread matches `c:` prefix — including threaded turns.
-      // This is the contract the gateway had before extraction.
-      // If we wanted to change it to chat-root-only, that'd be a
-      // deliberate spec change.
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-    })
-
-    it('unpinForChat on an empty manager is safe', async () => {
-      const h = mkHarness()
-      h.mgr.unpinForChat('c', 42)
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-
-    it('unpinForChat is safe mid-iteration when pins mutate the map', async () => {
-      const h = mkHarness()
-      for (let i = 1; i <= 5; i++) {
-        h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: `c:42:${i}`, messageId: 499 + i, isFirstEmit: true })
-      }
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // Snapshot-before-iterate is important: the doUnpin path mutates
-      // the pinned map. If iteration used the live map directly, we'd
-      // miss entries.
-      h.mgr.unpinForChat('c', 42)
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledTimes(5)
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-    })
-  })
-
-  describe('multi-turn lifecycle', () => {
-    it('pin → complete → new turn with same chat keeps things independent', async () => {
-      const h = mkHarness()
-
-      // Turn 1
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-
-      // Turn 2 on the same chat
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:2', messageId: 501, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:2' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(2)
-      expect(h.deps.unpin).toHaveBeenCalledTimes(2)
-      expect(h.deps.pin.mock.calls[0][1]).toBe(500)
-      expect(h.deps.pin.mock.calls[1][1]).toBe(501)
-    })
-
-    it('concurrent turns across chats: each turn is pinned + unpinned independently', async () => {
-      const h = mkHarness()
-
-      h.mgr.considerPin({ chatId: 'A', turnKey: 'A:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'B', turnKey: 'B:1', messageId: 501, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.mgr.pinnedTurnKeys().sort()).toEqual(['A:1', 'B:1'])
-
-      h.mgr.completeTurn({ chatId: 'A', turnKey: 'A:1' })
-      await h.mgr.drainInFlight()
-      expect(h.mgr.pinnedTurnKeys()).toEqual(['B:1'])
-
-      h.mgr.completeTurn({ chatId: 'B', turnKey: 'B:1' })
-      await h.mgr.drainInFlight()
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-    })
-
-    it('reused turnKey after complete starts fresh (unpinned set was cleared)', async () => {
-      const h = mkHarness()
-
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      // Unlikely but defensive: if the driver ever reuses the same
-      // turnKey, the manager starts clean.
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 777, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(2)
-      expect(h.mgr.pinnedMessageId('c:1')).toBe(777)
-    })
-  })
-
-  describe('captureServiceMessage — pin-service-msg deletion', () => {
-    it('deletes the service message when it wraps a tracked pin', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 500, serviceMessageId: 9001 })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.deleteMessage).toHaveBeenCalledWith('c', 9001)
-    })
-
-    it('ignores service messages wrapping pins we did not track', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 999, serviceMessageId: 9001 })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.deleteMessage).not.toHaveBeenCalled()
-    })
-
-    it('issue #94: deletes service messages for externally-tracked pins (worker card)', async () => {
-      // Worker / sub-agent cards are pinned via the gateway directly,
-      // not through `considerPin`. They register with `trackExternalPin`
-      // so `captureServiceMessage` recognises their service messages and
-      // suppresses the "Clerk pinned …" system noise (matching the main
-      // card's behaviour). Without this branch the worker card's pin
-      // event would slip through unmatched.
-      const h = mkHarness()
-      h.mgr.trackExternalPin('c', 777)
-
-      h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 777, serviceMessageId: 9002 })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.deleteMessage).toHaveBeenCalledWith('c', 9002)
-    })
-
-    it('issue #94: untrackExternalPin stops further captures', async () => {
-      const h = mkHarness()
-      h.mgr.trackExternalPin('c', 777)
-      h.mgr.untrackExternalPin('c', 777)
-
-      h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 777, serviceMessageId: 9002 })
-      await h.mgr.drainInFlight()
-
-      // Once untracked, the manager treats the pin as unknown again and
-      // declines to delete — same shape as the "ignores untracked pins"
-      // test above.
-      expect(h.deps.deleteMessage).not.toHaveBeenCalled()
-    })
-
-    it('no-op when deleteMessage is not wired', async () => {
-      const h = mkHarness({ deleteMessage: undefined })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(() => {
-        h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 500, serviceMessageId: 9001 })
-      }).not.toThrow()
-      await h.mgr.drainInFlight()
-    })
-
-    it('deleteMessage rejection is logged and does not throw', async () => {
-      const h = mkHarness()
-      h.deps.deleteMessage.mockRejectedValueOnce(errors.badRequest('message to delete not found', 'deleteMessage'))
-
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.captureServiceMessage({ chatId: 'c', pinnedMessageId: 500, serviceMessageId: 9001 })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.log).toHaveBeenCalledWith(
-        expect.stringMatching(/pin service-msg delete failed/),
-      )
-    })
-
-    it('unpin deletes a service message that was captured but not yet deleted', async () => {
-      // Simulate: capture arrives, but deleteMessage is pending forever —
-      // then an unpin fires. Because captureServiceMessage already
-      // attempted the delete and removed its entry, unpin won't double-fire;
-      // this guards the inverse scenario where capture never arrived.
-      // Here we test the safety-net path: no capture → no stray delete.
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // No captureServiceMessage call — simulates a lost/unmatched update.
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-      expect(h.deps.deleteMessage).not.toHaveBeenCalled()
-    })
-  })
-
-  describe('drainInFlight', () => {
-    it('resolves even when no promises are pending', async () => {
-      const h = mkHarness()
-      await expect(h.mgr.drainInFlight()).resolves.toBeUndefined()
-    })
-
-    it('awaits both the pin catch-chain and the unpin finally-chain', async () => {
-      const h = mkHarness()
-      // Slow pin + slow unpin → drainInFlight should cover both.
-      let resolvePin!: () => void
-      let resolveUnpin!: () => void
-      h.deps.pin.mockImplementationOnce(() => new Promise<true>((r) => { resolvePin = () => r(true) }))
-      h.deps.unpin.mockImplementationOnce(() => new Promise<true>((r) => { resolveUnpin = () => r(true) }))
-
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-
-      const drained = h.mgr.drainInFlight()
-      resolvePin()
-      resolveUnpin()
-      await drained
-
-      // After drain, removePin should have fired (from unpin's finally).
-      expect(h.deps.removePin).toHaveBeenCalled()
-    })
-  })
-
-  describe('deferred pin timing — fast turns stay silent', () => {
-    it('considerPin does not call pin synchronously — timer is scheduled', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      await h.mgr.drainInFlight()
-
-      // Timer scheduled, but not fired → no pin yet. Default pinDelayMs
-      // is now 0 (fast-turn suppression is owned upstream by the
-      // driver's initialDelayMs); the setTimeout indirection remains so
-      // completeTurn can still cancel a pin that hasn't landed yet.
-      expect(h.timers).toHaveLength(1)
-      expect(h.timers[0].ms).toBe(0)
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.deps.addPin).not.toHaveBeenCalled()
-      expect(h.mgr.pinnedTurnKeys()).toEqual([])
-    })
-
-    it('fast turn: completeTurn before timer fires → never pins, never unpins', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      // Turn completes before pinDelayMs elapses. The timer is cancelled
-      // and no pin/unpin ever touches Telegram.
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      // Even if the timer somehow fires later (belt-and-braces), it should
-      // be marked cancelled and skipped.
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-      expect(h.deps.addPin).not.toHaveBeenCalled()
-      expect(h.sidecar).toEqual([])
-    })
-
-    it('slow turn: pin fires when timer elapses, then completeTurn unpins', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      await h.mgr.drainInFlight()
-      expect(h.deps.pin).not.toHaveBeenCalled()
-
-      // Timer elapses → pin lands.
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.deps.pin).toHaveBeenCalledWith('c', 500, { disable_notification: true })
-      expect(h.mgr.pinnedMessageId('c:1')).toBe(500)
-
-      // completeTurn after the pin → unpin lands.
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-      expect(h.mgr.pinnedMessageId('c:1')).toBeUndefined()
-    })
-
-    it('unpinForChat cancels pending (not-yet-fired) timers', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:2', messageId: 501, isFirstEmit: true })
-
-      // Clear pending pins before any timer fires.
-      h.mgr.unpinForChat('c', 42)
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      // No pins, no unpins — the timers were cancelled and never fired.
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-
-    it('unpinForChat cancels pending timers AND unpins already-fired pins', async () => {
-      const h = mkHarness()
-      // First pin: fire its timer → already pinned.
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-
-      // Second pin: timer still pending.
-      h.mgr.considerPin({ chatId: 'c', threadId: '42', turnKey: 'c:42:2', messageId: 501, isFirstEmit: true })
-
-      h.mgr.unpinForChat('c', 42)
-      h.fireTimers() // noop — second timer was cancelled.
-      await h.mgr.drainInFlight()
-
-      // First pin got unpinned; second never pinned.
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-      expect(h.deps.unpin).not.toHaveBeenCalledWith('c', 501)
-    })
-
-    it('custom pinDelayMs overrides the default', async () => {
-      const h = mkHarness({ pinDelayMs: 5_000 })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-
-      expect(h.timers).toHaveLength(1)
-      expect(h.timers[0].ms).toBe(5_000)
-    })
-
-    it('pinDelayMs=0 still defers through the timer (no sync pin)', async () => {
-      // Guards against a tempting optimization: "if pinDelayMs === 0,
-      // pin synchronously." We pass it through the timer anyway so the
-      // contract is uniform (considerPin never blocks, never pins
-      // before control returns).
-      const h = mkHarness({ pinDelayMs: 0 })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.timers).toHaveLength(1)
-
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  describe('per-agent composite key — one pin per (turnKey, agentId)', () => {
-    it('distinct agentIds under the same turnKey pin independently', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true, agentId: 'parent' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 501, isFirstEmit: true, agentId: 'sub-a' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 502, isFirstEmit: true, agentId: 'sub-b' })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(3)
-      expect(h.mgr.pinnedTurnKeys()).toEqual(['c:1'])
-      expect(h.mgr.pinnedAgentIds('c:1').sort()).toEqual(['parent', 'sub-a', 'sub-b'])
-      expect(h.mgr.pinnedMessageId('c:1', 'parent')).toBe(500)
-      expect(h.mgr.pinnedMessageId('c:1', 'sub-a')).toBe(501)
-      expect(h.mgr.pinnedMessageId('c:1', 'sub-b')).toBe(502)
-    })
-
-    it('idempotent within a (turnKey, agentId) — second considerPin is a no-op', async () => {
-      const h = mkHarness()
-      const c = { chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true, agentId: 'sub-a' }
-      h.mgr.considerPin(c)
-      h.mgr.considerPin({ ...c, messageId: 999 })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(1)
-      expect(h.deps.pin).toHaveBeenCalledWith('c', 500, { disable_notification: true })
-      expect(h.mgr.pinnedMessageId('c:1', 'sub-a')).toBe(500)
-    })
-
-    it('completeTurn for one agentId leaves siblings under the same turnKey untouched', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true, agentId: 'parent' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 501, isFirstEmit: true, agentId: 'sub-a' })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1', agentId: 'sub-a' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledTimes(1)
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 501)
-      expect(h.mgr.pinnedAgentIds('c:1')).toEqual(['parent'])
-      expect(h.mgr.pinnedMessageId('c:1', 'parent')).toBe(500)
-    })
-
-    it('legacy callers (no agentId) get the parent-sentinel default', async () => {
-      const h = mkHarness()
-      // Old call shape: no agentId. Uses PARENT_AGENT_ID under the hood.
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.mgr.pinnedAgentIds('c:1')).toEqual(['__parent__'])
-      // pinnedMessageId without agentId resolves the parent sentinel.
-      expect(h.mgr.pinnedMessageId('c:1')).toBe(500)
-      // completeTurn without agentId targets the parent sentinel too.
-      h.mgr.completeTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).toHaveBeenCalledWith('c', 500)
-    })
-
-    it('parent and a sub-agent for the legacy turnKey pin under different sentinels', async () => {
-      // Mixed call shape: parent uses no agentId (sentinel), sub-agent
-      // passes an explicit one. They must not collide.
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 501, isFirstEmit: true, agentId: 'sub-a' })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).toHaveBeenCalledTimes(2)
-      expect(h.mgr.pinnedAgentIds('c:1').sort()).toEqual(['__parent__', 'sub-a'])
-    })
-  })
-
-  describe('completeAllForTurn — catastrophic cleanup', () => {
-    it('unpins every agentId pinned under a turnKey', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true, agentId: 'parent' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 501, isFirstEmit: true, agentId: 'sub-a' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 502, isFirstEmit: true, agentId: 'sub-b' })
-      // A different turn — must not be affected.
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:2', messageId: 600, isFirstEmit: true, agentId: 'parent' })
-      h.fireTimers()
-      await h.mgr.drainInFlight()
-
-      h.mgr.completeAllForTurn({ chatId: 'c', turnKey: 'c:1' })
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.unpin).toHaveBeenCalledTimes(3)
-      const unpinnedIds = h.deps.unpin.mock.calls.map((args) => args[1]).sort((a, b) => Number(a) - Number(b))
-      expect(unpinnedIds).toEqual([500, 501, 502])
-      expect(h.mgr.pinnedTurnKeys()).toEqual(['c:2'])
-    })
-
-    it('cancels pending (not-yet-fired) timers under the turnKey', async () => {
-      const h = mkHarness()
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 500, isFirstEmit: true, agentId: 'parent' })
-      h.mgr.considerPin({ chatId: 'c', turnKey: 'c:1', messageId: 501, isFirstEmit: true, agentId: 'sub-a' })
-      // Timers scheduled but not fired yet.
-      h.mgr.completeAllForTurn({ chatId: 'c', turnKey: 'c:1' })
-      h.fireTimers() // noop — both timers were cancelled
-      await h.mgr.drainInFlight()
-
-      expect(h.deps.pin).not.toHaveBeenCalled()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-
-    it('safe on a turnKey with no pins', async () => {
-      const h = mkHarness()
-      h.mgr.completeAllForTurn({ chatId: 'c', turnKey: 'c:never' })
-      await h.mgr.drainInFlight()
-      expect(h.deps.unpin).not.toHaveBeenCalled()
-    })
-  })
-})