switchroom 0.18.11 → 0.18.13

package/telegram-plugin/tests/session-tail-sidecar-reap.test.ts

@@ -0,0 +1,268 @@
+/**
+ * FD/timer-leak regression test for the session-tail PreToolUse sidecars
+ * (review finding M1).
+ *
+ * `ToolLabelSidecar`s (each holding a stat-poll timer + file handle) were only
+ * reaped in the global `stop()`. Every session rotation (`/clear`, compaction →
+ * new sessionId) and every finished sub-agent minted a fresh sidecar that then
+ * lived until process exit — hundreds of leaked timers/handles on a long-lived
+ * agent.
+ *
+ * We mock the sidecar factory so each instance is a cheap fake with a `stop`
+ * spy, then drive a real parent-session rotation and a real sub-agent reap and
+ * assert the ended session's sidecar was stopped. Both assertions FAIL on
+ * pre-fix code (stop only in `stop()`).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, utimesSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSessionTail, getProjectsDirForCwd } from '../session-tail.js'
+import type { SidecarOptions, ToolLabelSidecar } from '../tool-label-sidecar.js'
+
+// ─── Sidecar factory injection: record every fake instance keyed by sessionId ─
+// We do NOT `vi.mock('../tool-label-sidecar.js')`. Under bun's vitest-compat
+// layer `vi.mock` is PROCESS-GLOBAL (not file-scoped like vitest), and CI's
+// bun-test-run shard runs this whole `tests/` dir in ONE process — so a module
+// mock here would leak into the real `tool-label-sidecar.test.ts` suite and
+// replace the module under test, failing its 7 assertions. Instead we inject a
+// fake sidecar factory through `startSessionTail`'s `createSidecar` seam (the
+// repo's bun-safe DI precedent — see `vault-write-posture.test.ts`), so the
+// shared module cache is never touched. Sibling `subagent-watcher-fd-leak.test.ts`
+// uses the same injected-fake style.
+interface FakeSidecar extends ToolLabelSidecar {
+  sessionId: string
+  stop: ReturnType<typeof vi.fn>
+}
+const created = { instances: [] as FakeSidecar[] }
+const fakeSidecarFactory = (opts: SidecarOptions): ToolLabelSidecar => {
+  const inst: FakeSidecar = {
+    sessionId: opts.sessionId,
+    stop: vi.fn(),
+    getLabel: () => undefined,
+    onLabel: () => () => {},
+    poll: () => {},
+  }
+  created.instances.push(inst)
+  return inst
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const tempDirs: string[] = []
+let prevStateDir: string | undefined
+
+beforeEach(() => {
+  created.instances.length = 0
+  prevStateDir = process.env.TELEGRAM_STATE_DIR
+  const stateDir = mkdtempSync(join(tmpdir(), 'sidecar-state-'))
+  tempDirs.push(stateDir)
+  process.env.TELEGRAM_STATE_DIR = stateDir
+})
+
+afterEach(() => {
+  if (prevStateDir === undefined) delete process.env.TELEGRAM_STATE_DIR
+  else process.env.TELEGRAM_STATE_DIR = prevStateDir
+  for (const d of tempDirs) {
+    try { rmSync(d, { recursive: true, force: true }) } catch { /* ignore */ }
+  }
+  tempDirs.length = 0
+})
+
+function mkProjectsDir(): { claudeHome: string; cwd: string; projectsDir: string } {
+  const base = mkdtempSync(join(tmpdir(), 'session-tail-sidecar-'))
+  tempDirs.push(base)
+  const cwd = join(base, 'agent')
+  const claudeHome = join(base, 'claude-home')
+  const projectsDir = getProjectsDirForCwd(cwd, claudeHome)
+  mkdirSync(projectsDir, { recursive: true })
+  return { claudeHome, cwd, projectsDir }
+}
+
+const setMtime = (path: string, seconds: number): void => utimesSync(path, seconds, seconds)
+const wait = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
+const assistantText = (text: string): string =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text }] } }) + '\n'
+const toolUseLine = (name: string, id: string): string =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }) + '\n'
+
+const findSidecar = (sessionId: string): FakeSidecar | undefined =>
+  created.instances.find((i) => i.sessionId === sessionId)
+
+describe('session-tail sidecar reap (M1) — parent session rotation', () => {
+  it('stops the prior session sidecar when the active file rotates', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const first = join(projectsDir, 'session-one.jsonl')
+    const second = join(projectsDir, 'session-two.jsonl')
+
+    writeFileSync(first, assistantText('parent one'))
+    setMtime(first, 1_000_000)
+
+    const handle = startSessionTail({ cwd, claudeHome, rescanIntervalMs: 30, onEvent: () => {}, createSidecar: fakeSidecarFactory })
+    try {
+      await wait(120) // initial attach → sidecar 'session-one' created
+      expect(findSidecar('session-one')).toBeDefined()
+      expect(findSidecar('session-one')!.stop).not.toHaveBeenCalled()
+
+      // A newer session file appears (compaction / clear rotation).
+      const nowSec = Math.floor(Date.now() / 1000)
+      writeFileSync(second, assistantText('parent two'))
+      setMtime(second, nowSec + 20)
+      setMtime(first, nowSec + 5)
+      await wait(200) // rescan flips to session-two → session-one must be reaped
+
+      expect(findSidecar('session-two')).toBeDefined()
+      // The rotated-away session's sidecar is stopped at runtime, not left for stop().
+      expect(findSidecar('session-one')!.stop).toHaveBeenCalledTimes(1)
+      // The now-active session's sidecar stays alive.
+      expect(findSidecar('session-two')!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (M1) — idle sub-agent', () => {
+  it('stops a sub-agent sidecar when its idle sub-tail is reaped', async () => {
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const parent = join(projectsDir, 'parent.jsonl')
+    writeFileSync(parent, assistantText('parent'))
+    setMtime(parent, Math.floor(Date.now() / 1000))
+
+    // Sub-agents live under <parentSessionId>/subagents/agent-<id>.jsonl.
+    const subDir = join(projectsDir, 'parent', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-sub123.jsonl')
+    // A tool_use line makes the sub-tail lazily create its sidecar (keyed by
+    // the file stem 'agent-sub123').
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_1'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      // Reap sub-tails idle for >1000ms so the test doesn't wait 5 minutes but
+      // still respects the L1 floor clamp (Math.max(1000, …) — a smaller value
+      // is silently lifted to 1s) and leaves a window to observe the
+      // not-yet-reaped state.
+      subTailIdleReapMs: 1000,
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(100) // attach parent + sub, read tool_use → sidecar created
+      const sub = findSidecar('agent-sub123')
+      expect(sub).toBeDefined()
+      expect(sub!.stop).not.toHaveBeenCalled()
+
+      // Let the sub-tail go idle past the reap window; a rescan tick reaps it.
+      await wait(1300)
+      expect(sub!.stop).toHaveBeenCalledTimes(1)
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (L1) — reap window is floor-clamped', () => {
+  it('does NOT instant-reap a live sub-tail under a zero (or negative) idle window', async () => {
+    // A `subTailIdleReapMs` of 0 (or negative) would, without the
+    // Math.max(1000, …) clamp, make `reapIdleSubTails` compute
+    // `cutoff = Date.now() - 0`, which is ALWAYS ≥ a live sub-tail's slightly-
+    // earlier `lastActivityAt` — so every live sub-agent sidecar would be
+    // reaped on the very first rescan tick. The clamp lifts the effective
+    // window to the 1s floor, so a sub-tail active moments ago survives.
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const parent = join(projectsDir, 'parent.jsonl')
+    writeFileSync(parent, assistantText('parent'))
+    setMtime(parent, Math.floor(Date.now() / 1000))
+
+    const subDir = join(projectsDir, 'parent', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-subzero.jsonl')
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_z'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      subTailIdleReapMs: 0, // pathological: pre-clamp this instant-reaps
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(100) // attach parent + sub → sidecar 'agent-subzero' created
+      const sub = findSidecar('agent-subzero')
+      expect(sub).toBeDefined()
+      expect(sub!.stop).not.toHaveBeenCalled()
+
+      // Several rescan ticks pass (well under the 1s clamp floor). A live
+      // sub-tail whose activity is <1s old must NOT be reaped — so its sidecar
+      // stays alive. Pre-clamp, the first tick reaps it (sub.stop called once).
+      await wait(200)
+      expect(sub!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})
+
+describe('session-tail sidecar reap (M1) — namespace safety', () => {
+  it('a parent-session rotation does NOT stop a concurrently-live sub-agent sidecar', async () => {
+    // The rotation reap in attachToFile stops the sidecar keyed by the
+    // rotated-away parent's JSONL stem (a UUID). A live sub-agent's sidecar is
+    // keyed by its OWN file stem ('agent-<id>'). Because the two key namespaces
+    // never collide, rotating the parent must leave the sub-agent's sidecar
+    // untouched — otherwise a `/clear` or compaction mid-worker would silently
+    // kill the live worker's label sidecar. Reviewer verified by code-reading
+    // only; this locks it in.
+    const { claudeHome, cwd, projectsDir } = mkProjectsDir()
+    const first = join(projectsDir, 'session-one.jsonl')
+    const second = join(projectsDir, 'session-two.jsonl')
+
+    writeFileSync(first, assistantText('parent one'))
+    setMtime(first, 1_000_000)
+
+    // A live sub-agent under the CURRENT (session-one) parent. Its tool_use
+    // line makes the sub-tail create a sidecar keyed 'agent-subns'.
+    const subDir = join(projectsDir, 'session-one', 'subagents')
+    mkdirSync(subDir, { recursive: true })
+    const subFile = join(subDir, 'agent-subns.jsonl')
+    writeFileSync(subFile, toolUseLine('Bash', 'toolu_ns'))
+
+    const handle = startSessionTail({
+      cwd,
+      claudeHome,
+      rescanIntervalMs: 30,
+      // Large window so the sub-tail is never idle-reaped during the test —
+      // we're isolating the rotation path, not the idle path.
+      subTailIdleReapMs: 60_000,
+      onEvent: () => {},
+      createSidecar: fakeSidecarFactory,
+    })
+    try {
+      await wait(120) // attach parent + sub → both sidecars created
+      const parentSidecar = findSidecar('session-one')
+      const subSidecar = findSidecar('agent-subns')
+      expect(parentSidecar).toBeDefined()
+      expect(subSidecar).toBeDefined()
+      expect(parentSidecar!.stop).not.toHaveBeenCalled()
+      expect(subSidecar!.stop).not.toHaveBeenCalled()
+
+      // Parent session rotates (compaction / clear → new sessionId).
+      const nowSec = Math.floor(Date.now() / 1000)
+      writeFileSync(second, assistantText('parent two'))
+      setMtime(second, nowSec + 20)
+      setMtime(first, nowSec + 5)
+      await wait(200) // rescan flips active file to session-two
+
+      // The rotated-away PARENT sidecar is reaped …
+      expect(parentSidecar!.stop).toHaveBeenCalledTimes(1)
+      // … but the concurrently-live SUB-agent sidecar is NOT — different stem
+      // namespace, so the rotation reap never targets it.
+      expect(subSidecar!.stop).not.toHaveBeenCalled()
+    } finally {
+      handle.stop()
+    }
+  })
+})

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

@@ -232,18 +232,43 @@ describe("status-pin boot cleanup is mutex-gated (structural)", () => {
     );
   });
 
-  it("every statusPinBootCleanup() call site follows the won-lock check", () => {
-    // Find each *invocation* (with parens), excluding the declaration.
+  it("every boot pin-cleanup call site follows the won-lock check", () => {
+    // #3026: boot cleanup is now invoked via the mutex-gated orchestrator
+    // runBootPinCleanupAndDmSweep(), which awaits statusPinBootCleanup()
+    // (+ the other reapers) and then runs the DM stale-pin sweep. The
+    // invariant is unchanged: cleanup must only run after the lock is won.
     const lines = gatewaySrc.split("\n");
     const lockIdx = lines.findIndex((l) => l.includes("acquireStartupLock({"));
     expect(lockIdx).toBeGreaterThan(-1);
 
+    // Every `void runBootPinCleanupAndDmSweep()` invocation must come AFTER
+    // the acquireStartupLock outcome is available (the boot block the winner
+    // — or the link()-unsupported fallback — reaches).
+    const callIdxs = lines
+      .map((l, i) => ({ l, i }))
+      .filter(
+        ({ l }) =>
+          /void runBootPinCleanupAndDmSweep\(\)/.test(l) &&
+          !l.trimStart().startsWith("//"),
+      )
+      .map(({ i }) => i);
+    expect(callIdxs.length).toBeGreaterThan(0);
+    for (const idx of callIdxs) {
+      expect(idx).toBeGreaterThan(lockIdx);
+    }
+
+    // statusPinBootCleanup() itself must only ever be invoked from INSIDE
+    // that orchestrator — never at a bare post-import call site that a
+    // losing double-boot could reach.
     const declIdx = lines.findIndex((l) =>
       /async function statusPinBootCleanup/.test(l),
     );
     expect(declIdx).toBeGreaterThan(-1);
-
-    const callIdxs = lines
+    const orchestratorIdx = lines.findIndex((l) =>
+      /async function runBootPinCleanupAndDmSweep/.test(l),
+    );
+    expect(orchestratorIdx).toBeGreaterThan(-1);
+    const invocationIdxs = lines
       .map((l, i) => ({ l, i }))
       .filter(
         ({ l, i }) =>
@@ -253,25 +278,21 @@ describe("status-pin boot cleanup is mutex-gated (structural)", () => {
           !l.includes("statusPinBootCleanup() is deliberately NOT"),
       )
       .map(({ i }) => i);
-
-    // There must be at least one real call, and every real call must come
-    // AFTER the acquireStartupLock outcome is available (i.e. inside the boot
-    // block that only the winner reaches).
-    expect(callIdxs.length).toBeGreaterThan(0);
-    for (const idx of callIdxs) {
-      expect(idx).toBeGreaterThan(lockIdx);
+    expect(invocationIdxs.length).toBeGreaterThan(0);
+    for (const idx of invocationIdxs) {
+      expect(idx).toBeGreaterThan(orchestratorIdx);
     }
   });
 
   it("the blocked (losing) boot exits before reaching cleanup", () => {
     // In the mutex block, `outcome.status === 'blocked'` must lead to
-    // process.exit(1) BEFORE any statusPinBootCleanup() call in that block —
-    // so a loser never touches the shared store.
+    // process.exit(1) BEFORE the winner's runBootPinCleanupAndDmSweep() call
+    // in that block — so a loser never touches the shared store.
     const blockedIdx = gatewaySrc.indexOf("outcome.status === 'blocked'");
     expect(blockedIdx).toBeGreaterThan(-1);
     const afterBlocked = gatewaySrc.slice(blockedIdx);
     const exitIdx = afterBlocked.indexOf("process.exit(1)");
-    const cleanupIdx = afterBlocked.indexOf("void statusPinBootCleanup()");
+    const cleanupIdx = afterBlocked.indexOf("void runBootPinCleanupAndDmSweep()");
     expect(exitIdx).toBeGreaterThan(-1);
     expect(cleanupIdx).toBeGreaterThan(-1);
     // The exit for the blocked branch appears before the winner's cleanup call.

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)
+    }
+  })
+})