switchroom 0.16.29 → 0.16.46

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

@@ -577,6 +577,97 @@ describe('projectSubagentLine', () => {
     ])
   })
 
+  // ── Upstream-shape regression (Claude Code ≥2.1.x split-message writes) ──
+  // One logical assistant message is now persisted as MULTIPLE JSONL lines
+  // sharing one message.id, one content-block per line, and the terminal
+  // stop_reason (end_turn) is stamped on EVERY split line — including the
+  // leading [thinking] line that precedes the [text: final answer] line.
+  // Regression: firing the sub-agent terminal on the thinking-only line marks
+  // the sub-agent done and hands back stale/empty text BEFORE the real handback
+  // [text] line is projected. These pin the fix: the terminal must ride the
+  // content-bearing line, not the thinking-only split preamble.
+  it('does NOT emit sub_agent_turn_end on a thinking-only end_turn split line', () => {
+    // The FIRST line of a split terminal message: thinking only, but carries
+    // stop_reason end_turn (observed verbatim in 2.1.199 transcripts).
+    const st = { hasEmittedStart: true }
+    const events = projectSubagentLine(
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          id: 'msg_split',
+          stop_reason: 'end_turn',
+          content: [{ type: 'thinking', thinking: 'deciding how to summarise', signature: 'sig' }],
+        },
+      }),
+      'X',
+      st,
+    )
+    // Thinking is a projection no-op for sub-agents; crucially, NO premature
+    // terminal — the handback text has not been seen yet.
+    expect(events.some((e) => e.kind === 'sub_agent_turn_end')).toBe(false)
+  })
+
+  it('emits the handback text THEN one turn_end across a split end_turn message', () => {
+    // The full split terminal message, as two consecutive JSONL lines sharing
+    // message.id — the shape that dropped background sub-agent handbacks.
+    const st = { hasEmittedStart: true }
+    const thinkingLine = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_split2',
+        stop_reason: 'end_turn',
+        content: [{ type: 'thinking', thinking: '...', signature: 'sig' }],
+      },
+    })
+    const textLine = JSON.stringify({
+      type: 'assistant',
+      message: {
+        id: 'msg_split2',
+        stop_reason: 'end_turn',
+        content: [{ type: 'text', text: 'Handback: the fix is in session-tail.' }],
+      },
+    })
+    const all = [
+      ...projectSubagentLine(thinkingLine, 'X', st),
+      ...projectSubagentLine(textLine, 'X', st),
+    ]
+    // The handback text must be emitted, and exactly one turn_end, and the
+    // text must come BEFORE the turn_end so the watcher captures the real
+    // result before it marks the entry done.
+    const textEvents = all.filter((e) => e.kind === 'sub_agent_text')
+    const endEvents = all.filter((e) => e.kind === 'sub_agent_turn_end')
+    expect(textEvents.length).toBe(1)
+    expect((textEvents[0] as { text: string }).text).toBe('Handback: the fix is in session-tail.')
+    expect(endEvents.length).toBe(1)
+    const textIdx = all.findIndex((e) => e.kind === 'sub_agent_text')
+    const endIdx = all.findIndex((e) => e.kind === 'sub_agent_turn_end')
+    expect(textIdx).toBeLessThan(endIdx)
+  })
+
+  it('still fires terminal on the legacy single-line [thinking, text](end_turn) shape', () => {
+    // Graceful degradation: the OLD one-line-all-blocks shape has a text block
+    // on the same line, so the terminal fires exactly as before.
+    const st = { hasEmittedStart: true }
+    const events = projectSubagentLine(
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          stop_reason: 'end_turn',
+          content: [
+            { type: 'thinking', thinking: '...', signature: 'sig' },
+            { type: 'text', text: 'Legacy handback.' },
+          ],
+        },
+      }),
+      'X',
+      st,
+    )
+    const textIdx = events.findIndex((e) => e.kind === 'sub_agent_text')
+    const endIdx = events.findIndex((e) => e.kind === 'sub_agent_turn_end')
+    expect(textIdx).toBeGreaterThanOrEqual(0)
+    expect(endIdx).toBeGreaterThan(textIdx)
+  })
+
   it('does NOT emit sub_agent_turn_end for a tool-using assistant message (stop_reason tool_use)', () => {
     // A mid-run assistant message that calls a tool has stop_reason 'tool_use'
     // and keeps going — it must not be mistaken for completion.

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

@@ -0,0 +1,294 @@
+/**
+ * status-pin boot-recovery — the HEADLINE crash-recovery path, exercised against
+ * the REAL store + reconcile wrapper the gateway wires up (not just the pure
+ * decision fn). It reproduces the full sequence the gateway performs:
+ *
+ *   reconcile a pin → persist (persist-before-pin) → simulate a crash (SKIP the
+ *   clean SIGTERM sweep `unpinAllStatusPins`) → boot a "new gateway" (fresh
+ *   Maps, same on-disk store) → runStatusPinBootCleanup → assert the orphan pin
+ *   is unpinned AND the store is emptied.
+ *
+ * We cannot import gateway.ts directly (its module top-level runs the whole boot
+ * IIFE incl. the startup mutex + bot.start). Instead we model the gateway's
+ * status-pin subsystem faithfully with the SAME functions gateway.ts calls
+ * (reconcileAndPersistStatusPin, reconcilePin, runStatusPinBootCleanup) over an
+ * in-memory fs + a fake Telegram whose pin set we can inspect — so a regression
+ * in the ordering / cleanup contract reds here.
+ *
+ * Two variants:
+ *   (A) confirmed pin → crash before the clean sweep → recovered next boot.
+ *   (B) pending pin (crash INSIDE the persist-after-pin window, Fix 1) →
+ *       recovered next boot.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  loadStatusPins,
+  persistStatusPins,
+  reconcileAndPersistStatusPin,
+  runStatusPinBootCleanup,
+  type PersistedStatusPin,
+  type StatusPinStoreFsSeam,
+} from "../gateway/status-pin-store.js";
+import { reconcilePin } from "../status-pin-driver.js";
+import type { PinState, DesiredPin } from "../status-pin.js";
+import { decidePinAction } from "../status-pin.js";
+
+const PATH = "/state/agent/telegram/status-pins.json";
+
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed));
+  const fs: StatusPinStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`);
+      return files.get(p)!;
+    },
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (a, b) => {
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`);
+      files.set(b, files.get(a)!);
+      files.delete(a);
+    },
+    existsSync: (p) => files.has(p),
+  };
+  return { fs, files };
+}
+
+/** A fake Telegram that records the current pinned message set per chat, so we
+ *  can assert an orphan is left pinned after a crash and unpinned after boot. */
+function fakeTelegram() {
+  const pinned = new Set<string>(); // `${chatId}:${messageId}`
+  return {
+    pinned,
+    api: {
+      pinChatMessage: async (chat_id: string | number, message_id: number) => {
+        pinned.add(`${chat_id}:${message_id}`);
+      },
+      unpinChatMessage: async (chat_id: string | number, message_id: number) => {
+        pinned.delete(`${chat_id}:${message_id}`);
+      },
+    },
+  };
+}
+
+/**
+ * A faithful stand-in for the gateway's status-pin subsystem — the SAME wiring
+ * as gateway.ts's `reconcileStatusPin` / `unpinAllStatusPins` / boot cleanup,
+ * with injectable fs + api so a single test can span a "crash" and a fresh boot.
+ */
+function makeGateway(fs: StatusPinStoreFsSeam, tg: ReturnType<typeof fakeTelegram>) {
+  const statusPinState = new Map<string, PinState>();
+  const statusPinChatIds = new Map<string, string>();
+
+  const snapshotExcept = (exceptKey: string): PersistedStatusPin[] => {
+    const out: PersistedStatusPin[] = [];
+    for (const [pinKey, st] of statusPinState) {
+      if (pinKey === exceptKey) continue;
+      const chatId = statusPinChatIds.get(pinKey);
+      if (chatId == null) continue;
+      out.push({ pinKey, chatId, messageId: st.messageId });
+    }
+    return out;
+  };
+
+  async function reconcileStatusPin(pinKey: string, chatId: string, desired: DesiredPin) {
+    const prev = statusPinState.get(pinKey) ?? null;
+    const action = decidePinAction(prev, desired);
+    const op =
+      action.kind === "pin"
+        ? ({ kind: "pin", messageId: action.messageId } as const)
+        : ({ kind: "clear" } as const);
+    const next = await reconcileAndPersistStatusPin({
+      path: PATH,
+      fs,
+      pinKey,
+      chatId,
+      op,
+      snapshotOthers: () => snapshotExcept(pinKey),
+      applyPin: () =>
+        reconcilePin({ api: tg.api, chatId, prevState: prev, desired }),
+      log: () => {},
+    });
+    if (next == null) {
+      statusPinState.delete(pinKey);
+      statusPinChatIds.delete(pinKey);
+    } else {
+      statusPinState.set(pinKey, next);
+      statusPinChatIds.set(pinKey, chatId);
+    }
+  }
+
+  async function bootCleanup() {
+    return runStatusPinBootCleanup({
+      path: PATH,
+      fs,
+      unpin: (chatId, messageId) => tg.api.unpinChatMessage(chatId, messageId),
+      log: () => {},
+    });
+  }
+
+  return { statusPinState, reconcileStatusPin, bootCleanup };
+}
+
+describe("status-pin boot recovery (gateway wiring)", () => {
+  it("(A) confirmed pin → crash skips the clean sweep → next boot unpins the orphan + empties the store", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // ── Session 1: reconcile a pin. persist-before-pin runs; pin lands. ──
+    const gw1 = makeGateway(fs, tg);
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: true, messageId: 715 });
+
+    // Pin is live in Telegram and recorded on disk (confirmed).
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "fg:c:3", chatId: "-100123", messageId: 715 },
+    ]);
+
+    // ── CRASH: we deliberately DO NOT run the clean SIGTERM sweep
+    //    (unpinAllStatusPins). The pin stays live; gw1's Maps vanish. ──
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+
+    // ── Session 2: brand-new gateway, empty Maps, SAME on-disk store. ──
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has("-100123:715")).toBe(false); // orphan unpinned
+    expect(loadStatusPins(PATH, fs)).toEqual([]); // store emptied
+  });
+
+  it("(B) pending pin (crash inside the persist-after-pin window) → recovered next boot", async () => {
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+
+    // Simulate the exact Fix-1 crash window: the pin API lands, then the
+    // process is SIGKILLed before the confirming rewrite. We model that by
+    // reconcileAndPersistStatusPin whose applyPin pins then throws.
+    await expect(
+      reconcileAndPersistStatusPin({
+        path: PATH,
+        fs,
+        pinKey: "fg:c:3",
+        chatId: "-100123",
+        op: { kind: "pin", messageId: 715 },
+        snapshotOthers: () => [],
+        applyPin: async () => {
+          await tg.api.pinChatMessage("-100123", 715); // pin lands in Telegram
+          throw new Error("SIGKILL before confirm rewrite");
+        },
+        log: () => {},
+      }),
+    ).rejects.toThrow("SIGKILL");
+
+    // Orphan is live in Telegram; a PENDING record is on disk.
+    expect(tg.pinned.has("-100123:715")).toBe(true);
+    expect(loadStatusPins(PATH, fs)).toEqual([
+      { pinKey: "fg:c:3", chatId: "-100123", messageId: 715, pending: true },
+    ]);
+
+    // Fresh boot recovers it from the pending record.
+    const gw2 = makeGateway(fs, tg);
+    const res = await gw2.bootCleanup();
+    expect(res).toEqual({ cleared: 1, total: 1 });
+    expect(tg.pinned.has("-100123:715")).toBe(false);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+  });
+
+  it("clean shutdown (sweep DID run) leaves nothing for boot cleanup to do", async () => {
+    // Contrast: when the SIGTERM sweep runs (unpin each key), the store is
+    // emptied and the pin removed — boot cleanup is a no-op. This guards the
+    // ordering the other way: normal shutdown must NOT rely on boot cleanup.
+    const { fs } = memFs();
+    const tg = fakeTelegram();
+    const gw1 = makeGateway(fs, tg);
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: true, messageId: 715 });
+    // Clean sweep: unpin the key.
+    await gw1.reconcileStatusPin("fg:c:3", "-100123", { pinned: false });
+    expect(tg.pinned.size).toBe(0);
+    expect(loadStatusPins(PATH, fs)).toEqual([]);
+
+    const gw2 = makeGateway(fs, tg);
+    expect(await gw2.bootCleanup()).toEqual({ cleared: 0, total: 0 });
+  });
+});
+
+/**
+ * Mutex-gating (P2). The boot cleanup issues real unpins against a SHARED
+ * per-agent store, so a LOSING double-boot must NOT run it — else it would strip
+ * a still-alive sibling gateway's legitimate pins. gateway.ts gates the call
+ * inside the won-lock branch (only the boot that wins acquireStartupLock calls
+ * statusPinBootCleanup; the loser process.exit(1)s first).
+ *
+ * A full held-lock integration test is impractical (gateway.ts's boot IIFE runs
+ * the mutex + bot.start at import). So we assert STRUCTURALLY that the cleanup
+ * call sits inside the won-lock branch and never at the top-level import scope,
+ * and that the loser (blocked) branch exits before it.
+ */
+describe("status-pin boot cleanup is mutex-gated (structural)", () => {
+  const gatewaySrc = readFileSync(
+    fileURLToPath(new URL("../gateway/gateway.ts", import.meta.url)),
+    "utf8",
+  );
+
+  it("does NOT invoke statusPinBootCleanup at module import scope", () => {
+    // The invocation must be gated on winning the mutex, never fired eagerly at
+    // import. A bare top-level `statusPinBootCleanup()` (not inside the lock
+    // block) would let a losing double-boot strip a live sibling's pins.
+    // The definition + the deliberate DO-NOT-invoke note are allowed; assert
+    // there is a note explaining the gating, and that every actual call is
+    // preceded (in source order) by the acquireStartupLock outcome check.
+    expect(gatewaySrc).toContain("acquireStartupLock");
+    // The comment documenting WHY it isn't invoked at import time.
+    expect(gatewaySrc).toMatch(
+      /NOT invoked here at import time|gated on winning the startup mutex/,
+    );
+  });
+
+  it("every statusPinBootCleanup() call site follows the won-lock check", () => {
+    // Find each *invocation* (with parens), excluding the declaration.
+    const lines = gatewaySrc.split("\n");
+    const lockIdx = lines.findIndex((l) => l.includes("acquireStartupLock({"));
+    expect(lockIdx).toBeGreaterThan(-1);
+
+    const declIdx = lines.findIndex((l) =>
+      /async function statusPinBootCleanup/.test(l),
+    );
+    expect(declIdx).toBeGreaterThan(-1);
+
+    const callIdxs = lines
+      .map((l, i) => ({ l, i }))
+      .filter(
+        ({ l, i }) =>
+          i !== declIdx &&
+          /statusPinBootCleanup\(\)/.test(l) &&
+          !l.trimStart().startsWith("//") &&
+          !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);
+    }
+  });
+
+  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.
+    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()");
+    expect(exitIdx).toBeGreaterThan(-1);
+    expect(cleanupIdx).toBeGreaterThan(-1);
+    // The exit for the blocked branch appears before the winner's cleanup call.
+    expect(exitIdx).toBeLessThan(cleanupIdx);
+  });
+});

package/telegram-plugin/tests/status-pin-service-message-suppression.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Structural test for the `bot.on('message:pinned_message')` handler that
+ * suppresses the "pinned a message" service message Telegram inserts when
+ * OUR silent status-pin fires.
+ *
+ * Why structural: like every other gateway handler, this closure is wired
+ * inline against the live `bot` instance and is not exported — a functional
+ * invocation would require booting the full grammy runtime against a mocked
+ * Bot API. The gateway suite settled on file-level grep assertions for
+ * exactly this reason (see `inbound-message-types.test.ts`). The regression
+ * we care about: a future hand dropping the handler, dropping the ownership
+ * guard (which would let us delete manual/operator pins), or swapping the
+ * house deletion wrapper for a raw `bot.api.deleteMessage` (allowlist drift).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import {
+  pinnedMessageIsOurs,
+  type TrackedStatusPin,
+} from '../gateway/status-pin-store.js'
+
+const SRC = readFileSync(
+  new URL('../gateway/gateway.ts', import.meta.url),
+  'utf8',
+)
+
+/**
+ * Extract the body of the `bot.on('message:pinned_message', …)` handler:
+ * from the `bot.on(` line to the matching outer-scope closing brace.
+ */
+function pinnedMessageHandler(): string {
+  const needle = `bot.on('message:pinned_message'`
+  const start = SRC.indexOf(needle)
+  expect(start, `handler ${needle} not found`).toBeGreaterThan(0)
+  const firstBrace = SRC.indexOf('{', start)
+  let depth = 0
+  for (let i = firstBrace; i < SRC.length; i++) {
+    const c = SRC[i]
+    if (c === '{') depth++
+    else if (c === '}') {
+      depth--
+      if (depth === 0) return SRC.slice(start, i + 1)
+    }
+  }
+  throw new Error('could not find end of pinned_message handler')
+}
+
+describe('status-pin service-message suppression', () => {
+  it("registers a bot.on('message:pinned_message') handler", () => {
+    expect(SRC).toContain(`bot.on('message:pinned_message'`)
+  })
+
+  const body = pinnedMessageHandler()
+
+  it('guards on ownership via the chat-scoped pinnedMessageIsOurs helper', () => {
+    // Must consult our tracked pins — never blindly delete a pin service
+    // message (which would nuke manual/operator pins too) — AND it must be
+    // chat-scoped (pinnedMessageIsOurs requires chatId + messageId), never a
+    // messageId-only match.
+    expect(body).toContain('statusPinState')
+    expect(body).toMatch(/pinned_message\?\.message_id/)
+    expect(body).toContain('pinnedMessageIsOurs(')
+    // The chatId computed from the update must be fed to the guard.
+    expect(body).toMatch(/pinnedMessageIsOurs\(trackedPins\(\), chatId, pinnedId\)/)
+    // And the tracked entries must carry their chat association.
+    expect(body).toContain('statusPinChatIds.get(pinKey)')
+  })
+
+  it('bails out when the pinned message is not one of ours', () => {
+    // A `return` guard for the non-owned case must exist.
+    expect(body).toMatch(/if \(!isOurs\(\)\) return/)
+  })
+
+  it('deletes the service message through the robust wrapper (not a raw api call)', () => {
+    expect(body).toContain('robustApiCall(')
+    expect(body).toContain('deleteMessage')
+    // The message deleted is the service message itself, not the pinned msg.
+    expect(body).toContain('serviceMsgId')
+    // House verb tag so operators can trace it.
+    expect(body).toContain("verb: 'status-pin.delete-service-message'")
+  })
+
+  it('tolerates the reconcile-store race with a short retry', () => {
+    // The service update can arrive before reconcileStatusPin stores the
+    // PinState; a single delayed re-check covers that window.
+    expect(body).toContain('setTimeout')
+  })
+})
+
+/**
+ * BEHAVIORAL coverage of the ownership decision (BUG 1). The handler decides
+ * whether to delete a `pinned_message` service message by calling the real
+ * `pinnedMessageIsOurs(tracked, chatId, pinnedId)`. This models the exact
+ * gateway decision and asserts the delete fires ONLY for a same-chat match —
+ * the structural grep above would pass even with the messageId-only bug live.
+ */
+describe('service-message deletion decision (chat-scoped)', () => {
+  // Two tracked status pins in DIFFERENT chats. Chat A's pin id (715) collides
+  // with an incoming pin update in chat B.
+  const tracked: TrackedStatusPin[] = [
+    { chatId: '-100AAA', messageId: 715 },
+    { chatId: '-100BBB', messageId: 42 },
+  ]
+
+  // Mirror the handler: delete iff pinnedMessageIsOurs(...) is true.
+  const wouldDelete = (chatId: string, pinnedId: number) =>
+    pinnedMessageIsOurs(tracked, chatId, pinnedId)
+
+  it('does NOT delete chat B service message when its pin id collides with chat A', () => {
+    // Chat B, pinned id 715 → belongs to chat A, not B. Must NOT delete
+    // (this is the operator-manual-pin-notice safety case).
+    expect(wouldDelete('-100BBB', 715)).toBe(false)
+  })
+
+  it('DOES delete on a genuine same-chat match', () => {
+    expect(wouldDelete('-100AAA', 715)).toBe(true)
+    expect(wouldDelete('-100BBB', 42)).toBe(true)
+  })
+
+  it('does NOT delete a foreign pin id in a tracked chat', () => {
+    expect(wouldDelete('-100AAA', 9999)).toBe(false)
+  })
+})
+
+/**
+ * SUPERGROUP / forum-topic coverage. The handler reads only ctx.chat.id +
+ * ctx.msg.message_id and deletes by (chat_id, message_id) — topic-agnostic,
+ * with no private-chat assumption. In a forum supergroup the pinned status
+ * message carries a message_thread_id, but:
+ *   - deletion needs no thread arg (chat_id + message_id is sufficient), and
+ *   - message_id is unique per chat even across topics, so a single chat-scoped
+ *     match is correct regardless of which topic the pin lives in.
+ * These tests model a pinned_message update whose chat is a supergroup (and a
+ * forum variant carrying message_thread_id) and assert the same chat-scoped
+ * decision holds.
+ */
+describe('service-message deletion in supergroups / forum topics', () => {
+  // A status pin tracked in a supergroup chat, plus a collision partner in a
+  // different supergroup.
+  const tracked: TrackedStatusPin[] = [
+    { chatId: '-1001111', messageId: 500 }, // supergroup A
+    { chatId: '-1002222', messageId: 500 }, // supergroup B, SAME id as A
+  ]
+
+  // Model the handler's identity extraction from a grammy-shaped update. The
+  // thread id is present on forum updates but deliberately NOT part of the
+  // ownership/delete identity.
+  type PinnedUpdate = {
+    chat: { id: number; type: 'private' | 'supergroup' }
+    message_id: number
+    message_thread_id?: number
+    pinned_message: { message_id: number }
+  }
+  const wouldDelete = (u: PinnedUpdate) =>
+    pinnedMessageIsOurs(tracked, String(u.chat.id), u.pinned_message.message_id)
+
+  it('deletes on a genuine same-chat match in a plain supergroup', () => {
+    const update: PinnedUpdate = {
+      chat: { id: -1001111, type: 'supergroup' },
+      message_id: 9001, // the service message
+      pinned_message: { message_id: 500 },
+    }
+    expect(wouldDelete(update)).toBe(true)
+  })
+
+  it('deletes on a same-chat match in a FORUM topic (message_thread_id set)', () => {
+    const update: PinnedUpdate = {
+      chat: { id: -1001111, type: 'supergroup' },
+      message_id: 9002,
+      message_thread_id: 77, // forum topic — irrelevant to the delete identity
+      pinned_message: { message_id: 500 },
+    }
+    expect(wouldDelete(update)).toBe(true)
+  })
+
+  it('does NOT delete when the id collides across two supergroups', () => {
+    // Supergroup B receives a pin update for id 500, which also happens to be
+    // supergroup A's tracked status-pin id. Chat-scoped guard keeps them apart.
+    const update: PinnedUpdate = {
+      chat: { id: -1002222, type: 'supergroup' },
+      message_id: 9003,
+      message_thread_id: 12,
+      pinned_message: { message_id: 500 },
+    }
+    // 500 IS tracked for chat -1002222 too in this fixture, so this is a
+    // genuine match — assert the positive, then flip to a true cross-chat miss.
+    expect(wouldDelete(update)).toBe(true)
+
+    // A supergroup NOT in the tracked set, colliding on id 500 → must NOT fire.
+    const foreign: PinnedUpdate = {
+      chat: { id: -1009999, type: 'supergroup' },
+      message_id: 9004,
+      message_thread_id: 5,
+      pinned_message: { message_id: 500 },
+    }
+    expect(wouldDelete(foreign)).toBe(false)
+  })
+
+  it('the handler logs a missing-admin-right hint on delete failure (supergroup)', () => {
+    // Structural: the catch block names the likely supergroup cause so an
+    // operator isn't left with silent nothing.
+    const src = readFileSync(
+      new URL('../gateway/gateway.ts', import.meta.url),
+      'utf8',
+    )
+    expect(src).toContain('could not delete pin service message')
+    expect(src).toContain('missing can_delete_messages')
+  })
+})