switchroom 0.18.11 → 0.18.13

package/telegram-plugin/gateway/callback-query-handlers.ts

@@ -83,6 +83,7 @@ import { getAuthBrokerClient } from './auth-broker-client.js'
 import { chatKey } from './chat-key.js'
 import { tryHostdDispatch, hostdRequestId } from './hostd-dispatch.js'
 import type { HostdRequest } from '../../src/host-control/protocol.js'
+import type { OperatorEvent } from '../operator-events.js'
 import type { InboundMessage } from './ipc-protocol.js'
 import type { SweepableCardStore } from './approval-card-stores.js'
 import type { SweepableStore } from './pending-state-stores.js'
@@ -389,6 +390,13 @@ export interface CallbackQueryHandlersDeps {
   vaultKeyRegex: RegExp
   /** MENTAL_MODEL_PROPOSE_TTL_MS (config-driven approval-card lifetime). */
   mentalModelProposeTtlMs: number
+  /**
+   * Emit an operator-visible event through the gateway's single funnel
+   * (`emitGatewayOperatorEvent`: cooldown + record + broadcast). Used by the
+   * #2975 Stage-1 backstop to loudly surface an approved mental-model persist
+   * whose rate-window retry also failed.
+   */
+  emitOperatorEvent: (event: OperatorEvent) => void
 }
 
 // Freshness throttle for the /auth dashboard ↻ refresh button — one live
@@ -435,6 +443,7 @@ export function createCallbackQueryHandlers(deps: CallbackQueryHandlersDeps) {
     getAdminOnlyKeys,
     vaultKeyRegex: VAULT_KEY_REGEX,
     mentalModelProposeTtlMs: MENTAL_MODEL_PROPOSE_TTL_MS,
+    emitOperatorEvent,
   } = deps
   const bot = deps.bot as CallbackBotApi
   const lockedBot = deps.lockedBot as CallbackBotApi
@@ -1035,7 +1044,20 @@ async function handleMentalModelProposeCallback(ctx: Context, data: string): Pro
         return { state: 'error' as const, reason: 'hostd config-edit is not configured (host_control disabled or socket absent)' }
       }
       if (resp.result === 'completed') return { state: 'applied' as const }
-      if (resp.result === 'denied') return { state: 'denied' as const, reason: resp.error ?? 'operator/host denied the edit' }
+      if (resp.result === 'denied') {
+        // #2975 Stage 1 — a rate-limit denial carries a structured
+        // `fix.retry_after` (hostd server.ts ~2270-2280). Surface it as a
+        // distinct `rate_limited` state so the resolver schedules ONE retry
+        // at the window-open time instead of dropping the approved change.
+        const env = resp.error_envelope
+        if (env?.code === 'E_RATE_LIMITED' && env.fix?.kind === 'retry_after') {
+          const retryAtMs = Date.parse(env.fix.retry_at)
+          if (!Number.isNaN(retryAtMs)) {
+            return { state: 'rate_limited' as const, reason: resp.error ?? 'config_propose_edit rate limit exceeded', retryAtMs }
+          }
+        }
+        return { state: 'denied' as const, reason: resp.error ?? 'operator/host denied the edit' }
+      }
       return { state: 'error' as const, reason: resp.error ?? `hostd returned '${resp.result}'` }
     },
     // Ensure is delegated to reconcile: config_propose_edit's apply triggers a
@@ -1046,6 +1068,52 @@ async function handleMentalModelProposeCallback(ctx: Context, data: string): Pro
     injectInbound: (inbound: InboundMessage) => {
       deliverResumeSyntheticOrBuffer(pending.agent, inbound)
     },
+    // #2975 Stage 1 — schedule EXACTLY ONE re-dispatch of a rate-limited but
+    // operator-approved persist. A bare setTimeout (bounded, single-shot; the
+    // resolver never re-schedules). Stage-1 caveat: this timer lives only in
+    // gateway memory, so a gateway restart before it fires LOSES the retry —
+    // acceptable for Stage 1 (Stage 2's hostd checkPreApproved bypass removes
+    // the collision). Clamp the delay to a signed-32-bit setTimeout ceiling so
+    // a far-future window doesn't overflow into an immediate fire.
+    scheduleRetry: (delayMs: number, fn: () => void | Promise<void>) => {
+      const clamped = Math.min(Math.max(0, delayMs), 2_147_483_647)
+      setTimeout(() => {
+        void (async () => {
+          try {
+            await fn()
+          } catch (err) {
+            process.stderr.write(
+              `telegram gateway: mental_model_propose retry threw: ${(err as Error).message}\n`,
+            )
+          }
+        })()
+      }, clamped)
+    },
+    editProposalCardRateWindow: (retryAtMs: number) => {
+      if (pending.card_message_id == null) return
+      const at = new Date(retryAtMs)
+      const hh = String(at.getHours()).padStart(2, '0')
+      const mm = String(at.getMinutes()).padStart(2, '0')
+      void ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          richMessage(
+            `⏳ _Approved — applying **${escapeHtmlForTg(pending.agent)}**'s mental model \`${pending.spec.name}\` at ${hh}:${mm} (config-edit rate window). It isn't lost; it'll persist automatically when the window opens._`,
+          ),
+          { reply_markup: { inline_keyboard: [] }, link_preview_options: { is_disabled: true } },
+        )
+        .catch(() => {})
+    },
+    notifyPersistFailed: (reason: string) => {
+      emitOperatorEvent({
+        kind: 'mental-model-persist-failed',
+        agent: pending.agent,
+        detail: `Mental model "${pending.spec.name}" — ${reason}`,
+        suggestedActions: [],
+        firstSeenAt: new Date(),
+      })
+    },
     log: (m: string) => process.stderr.write(`telegram gateway: ${m}\n`),
   }
 
@@ -1088,6 +1156,13 @@ async function handleMentalModelProposeCallback(ctx: Context, data: string): Pro
       process.stderr.write(`telegram gateway: mental_model_propose approve threw: ${(err as Error).message}\n`)
       result = { outcome: 'failed' as const, reason: (err as Error).message }
     }
+    // #2975 Stage 1 — a rate-limited persist already edited the card to the
+    // "applying at HH:MM (rate window)" state and scheduled its own retry,
+    // which will resolve the turn via its own inbound. Leave that card intact;
+    // do NOT overwrite it with a success/failure label here.
+    if (result.outcome === 'scheduled_retry') {
+      return
+    }
     if (pending.card_message_id != null) {
       const label =
         result.outcome === 'applied'
@@ -2459,6 +2534,18 @@ async function handleOperatorEventCallback(ctx: Context, data: string): Promise<
 // stub so any stale pinned message that fires an `auth:*` tap is
 // silently dismissed instead of crashing the gateway.
 async function handleAuthDashboardCallback(ctx: Context): Promise<void> {
+  // Strict allowFrom gate, identical to every other mutating handler in
+  // this file (handleOperatorEventCallback, the vra:/vrs:/vd:/vg: families).
+  // Its absence was a security hole: `auth:use:<label>` drives
+  // `client.setActive(label)` — a fleet-wide OAuth account swap — so an
+  // ungated handler let any tapper (e.g. a member of an admin forum/
+  // supergroup with an empty group allowFrom) swap the active account.
+  const senderId = String(ctx.from?.id ?? '')
+  const access = loadAccess()
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return
+  }
   const data = ctx.callbackQuery?.data ?? ''
   const currentAgent = getMyAgentName()
 

package/telegram-plugin/gateway/config-approval-handler.ts

@@ -474,7 +474,12 @@ export async function handleRequestConfigFinalize(
   const body =
     msg.outcome === "applied"
       ? `✅ **Applied**${msg.detail ? `\n${escapeMarkdown(msg.detail)}` : ""}${liveNote}`
-      : `⚠️ **Reconcile failed; rolled back**${msg.detail ? `\n${escapeMarkdown(msg.detail)}` : ""}`;
+      : msg.outcome === "aborted_config_changed"
+        ? // Nothing was written: the config drifted during the approval window
+          // and the apply aborted rather than land a different effect than the
+          // operator approved (#3121 follow-up).
+          `🚫 **Not applied — config changed since proposal**${msg.detail ? `\n${escapeMarkdown(msg.detail)}` : ""}`
+        : `⚠️ **Reconcile failed; rolled back**${msg.detail ? `\n${escapeMarkdown(msg.detail)}` : ""}`;
   try {
     // Finalize is terminal — strip the keyboard so the buttons are gone.
     await deps.editCard({

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -57,6 +57,15 @@ export interface DisconnectFlushDeps<Ctrl extends { finalize: (reason?: 'done' |
   /** Progress driver — disposed with `preservePending: true` for sub-agent JTBDs (#393). */
   disposeProgressDriver: () => void
 
+  /** #2650: stop EVERY live turn-typing loop (the per-(chat,thread)
+   *  `setInterval` started by `turn-typing-loop.ts`). The bridge just died
+   *  mid-turn; its turn-long `typing…` loop is never stopped by the canonical
+   *  turn-end (which will never arrive), so a stale "typing…" shows to the user
+   *  until the next turn's `start()` self-heals it. Wire to
+   *  `() => turnTypingLoop.stopAll()`. Called ONLY on a registered-agent
+   *  disconnect — an anonymous one-shot never owned a turn-typing loop. */
+  stopTurnTypingLoops: () => void
+
   /** Optional: called when the registered-agent disconnect found dangling
    *  `activeTurnStartedAt` entries the controller loop did not clear (i.e.
    *  `finalize()` already ran on the canonical reply path, leaving
@@ -92,6 +101,7 @@ export function flushOnAgentDisconnect<
     activeDraftStreams,
     clearActiveReactions,
     disposeProgressDriver,
+    stopTurnTypingLoops,
     onDanglingTurnsSwept,
     log,
   } = deps
@@ -181,6 +191,15 @@ export function flushOnAgentDisconnect<
   // deferred-completion-timeout path remain active. Fix for #393.
   disposeProgressDriver()
 
+  // #2650: sweep the turn-typing loops. The bridge died mid-turn, so the
+  // canonical turn-end that would normally call `turnTypingLoop.stop` will
+  // never arrive — every live per-(chat,thread) `typing…` interval is now
+  // orphaned and would show a stale "typing…" to the user until the next
+  // turn's `start()` self-heals it. This is gated to a real registered-agent
+  // disconnect (we returned early above for anonymous clients), so an
+  // anonymous one-shot never triggers the sweep.
+  stopTurnTypingLoops()
+
   // Finalize any open draft streams so they don't hang mid-edit.
   for (const [key, stream] of activeDraftStreams.entries()) {
     if (!stream.isFinal()) void stream.finalize().catch(() => {})

package/telegram-plugin/gateway/dm-pin-sweep.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  isDmChatId,
+  collectDmChatIdsFromStores,
+  createDmPinSweeper,
+  unexpiredStoreRepinIds,
+  type DmPinSweeperDeps,
+} from './dm-pin-sweep'
+
+// Synthetic chat IDs only (check-no-pii-secrets): positive = DM, negative =
+// group/supergroup.
+const DM_A = '5000001'
+const DM_B = '5000002'
+const GROUP = '-1002000000001'
+
+describe('isDmChatId', () => {
+  it('true for positive integer DM ids', () => {
+    expect(isDmChatId(DM_A)).toBe(true)
+    expect(isDmChatId('1')).toBe(true)
+  })
+  it('false for group/supergroup (negative), zero, non-integer, non-numeric', () => {
+    expect(isDmChatId(GROUP)).toBe(false)
+    expect(isDmChatId('-1')).toBe(false)
+    expect(isDmChatId('0')).toBe(false)
+    expect(isDmChatId('1.5')).toBe(false)
+    expect(isDmChatId('abc')).toBe(false)
+    expect(isDmChatId('')).toBe(false)
+    expect(isDmChatId('Infinity')).toBe(false)
+  })
+})
+
+describe('collectDmChatIdsFromStores', () => {
+  it('collects distinct DM chat ids across all three stores and drops non-DMs', () => {
+    const ids = collectDmChatIdsFromStores({
+      statusPins: [{ chatId: DM_A }, { chatId: GROUP }, { chatId: DM_A }],
+      activityCards: [{ chatId: DM_B }, { chatId: '0' }],
+      queuedCards: [{ chatId: DM_A }, { chatId: '-77' }],
+    })
+    expect(new Set(ids)).toEqual(new Set([DM_A, DM_B]))
+    expect(ids).toHaveLength(2)
+  })
+  it('handles missing store arrays', () => {
+    expect(collectDmChatIdsFromStores({})).toEqual([])
+    expect(collectDmChatIdsFromStores({ statusPins: [{ chatId: GROUP }] })).toEqual([])
+  })
+})
+
+function makeDeps(overrides: Partial<DmPinSweeperDeps> = {}): {
+  deps: DmPinSweeperDeps
+  unpinAll: ReturnType<typeof vi.fn>
+  pinSilent: ReturnType<typeof vi.fn>
+} {
+  const unpinAll = vi.fn(async () => undefined)
+  const pinSilent = vi.fn(async () => undefined)
+  const deps: DmPinSweeperDeps = {
+    unpinAll,
+    pinSilent,
+    liveTrackedMessageIds: () => [],
+    eligible: () => true,
+    log: () => {},
+    ...overrides,
+  }
+  return { deps, unpinAll, pinSilent }
+}
+
+describe('createDmPinSweeper', () => {
+  it('DM with tracked pins: unpin-all exactly once, then re-pin exactly the live ids', async () => {
+    const { deps, unpinAll, pinSilent } = makeDeps({
+      liveTrackedMessageIds: (chatId) => (chatId === DM_A ? [111, 222] : []),
+    })
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+    expect(unpinAll).toHaveBeenCalledWith(DM_A)
+    expect(pinSilent.mock.calls).toEqual([
+      [DM_A, 111],
+      [DM_A, 222],
+    ])
+    expect(sweeper.hasSwept(DM_A)).toBe(true)
+  })
+
+  it('DM with no tracked pins: unpin-all once, no re-pin', async () => {
+    const { deps, unpinAll, pinSilent } = makeDeps()
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+    expect(pinSilent).not.toHaveBeenCalled()
+  })
+
+  it('group/supergroup id: never unpin-all (keeps human pins)', async () => {
+    const { deps, unpinAll, pinSilent } = makeDeps()
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(GROUP)
+    await sweeper.sweep('-1')
+    expect(unpinAll).not.toHaveBeenCalled()
+    expect(pinSilent).not.toHaveBeenCalled()
+  })
+
+  it('not eligible (lost startup mutex): does nothing', async () => {
+    const { deps, unpinAll } = makeDeps({ eligible: () => false })
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    expect(unpinAll).not.toHaveBeenCalled()
+    expect(sweeper.hasSwept(DM_A)).toBe(false)
+  })
+
+  it('second sweep of same chat does not re-sweep', async () => {
+    const { deps, unpinAll } = makeDeps()
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    await sweeper.sweep(DM_A)
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+  })
+
+  it('concurrent triggers on the same chat fire unpin-all only once', async () => {
+    let resolveUnpin: () => void = () => {}
+    const unpinAll = vi.fn(
+      () =>
+        new Promise<void>((res) => {
+          resolveUnpin = res
+        }),
+    )
+    const { deps } = makeDeps({ unpinAll })
+    const sweeper = createDmPinSweeper(deps)
+    const p1 = sweeper.sweep(DM_A)
+    const p2 = sweeper.sweep(DM_A)
+    resolveUnpin()
+    await Promise.all([p1, p2])
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+  })
+
+  it('429 / unpin-all rejects: degrades without throwing, still re-pins live ids', async () => {
+    const unpinAll = vi.fn(async () => {
+      throw new Error('429: Too Many Requests: retry after 30')
+    })
+    const { deps, pinSilent } = makeDeps({
+      unpinAll,
+      liveTrackedMessageIds: () => [333],
+    })
+    const sweeper = createDmPinSweeper(deps)
+    // Must not reject.
+    await expect(sweeper.sweep(DM_A)).resolves.toBeUndefined()
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+    expect(pinSilent).toHaveBeenCalledWith(DM_A, 333)
+  })
+
+  it('re-pin failure is absorbed and does not reject', async () => {
+    const pinSilent = vi.fn(async () => {
+      throw new Error('pin failed')
+    })
+    const { deps } = makeDeps({
+      pinSilent,
+      liveTrackedMessageIds: () => [444],
+    })
+    const sweeper = createDmPinSweeper(deps)
+    await expect(sweeper.sweep(DM_A)).resolves.toBeUndefined()
+  })
+
+  it('no unhandled rejection escapes a failing sweep (fire-and-forget safe)', async () => {
+    const unhandled: unknown[] = []
+    const onUnhandled = (r: unknown): void => {
+      unhandled.push(r)
+    }
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const { deps } = makeDeps({
+        unpinAll: async () => {
+          throw new Error('boom')
+        },
+        liveTrackedMessageIds: () => [555],
+      })
+      const sweeper = createDmPinSweeper(deps)
+      // Fire-and-forget, as the gateway does.
+      void sweeper.sweep(DM_A)
+      await new Promise((r) => setTimeout(r, 10))
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+    expect(unhandled).toEqual([])
+  })
+})
+
+describe('tool-pin survival (#3001 contract, review blocker on #3074)', () => {
+  const NOW = 1_752_000_000_000
+
+  it('unexpiredStoreRepinIds keeps unexpired tool rows for the chat, drops expired / work-scoped / other-chat rows', () => {
+    const rows = [
+      // Unexpired tool pin in this chat — MUST survive.
+      { chatId: DM_A, messageId: 10, expiresAt: NOW + 60_000 },
+      // Expired tool pin — due for sweeping, NOT re-pinned.
+      { chatId: DM_A, messageId: 11, expiresAt: NOW - 1 },
+      // Work-scoped row (no expiresAt) — stale after restart, NOT re-pinned.
+      { chatId: DM_A, messageId: 12 },
+      // Unexpired tool pin in a DIFFERENT chat — not this chat's re-pin set.
+      { chatId: DM_B, messageId: 13, expiresAt: NOW + 60_000 },
+    ]
+    expect(unexpiredStoreRepinIds(rows, DM_A, NOW)).toEqual([10])
+    expect(unexpiredStoreRepinIds(rows, DM_B, NOW)).toEqual([13])
+  })
+
+  // Composition test mirroring the gateway wiring: liveTrackedMessageIds
+  // unions in-memory claims with unexpired store rows.
+  function gatewayStyleDeps(args: {
+    inMemory: number[]
+    storeRows: { chatId: string; messageId: number; expiresAt?: number }[]
+  }): ReturnType<typeof makeDeps> {
+    return makeDeps({
+      liveTrackedMessageIds: (chatId) => [
+        ...args.inMemory,
+        ...unexpiredStoreRepinIds(args.storeRows, chatId, NOW),
+      ],
+    })
+  }
+
+  it('(a) boot sweep: DM with an unexpired tool: row → unpinAll once, then that messageId re-pinned', async () => {
+    const { deps, unpinAll, pinSilent } = gatewayStyleDeps({
+      inMemory: [], // fresh boot — in-memory claims empty
+      storeRows: [{ chatId: DM_A, messageId: 777, expiresAt: NOW + 60_000 }],
+    })
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+    expect(pinSilent.mock.calls).toEqual([[DM_A, 777]])
+  })
+
+  it('(b) expired tool: row is NOT re-pinned', async () => {
+    const { deps, unpinAll, pinSilent } = gatewayStyleDeps({
+      inMemory: [],
+      storeRows: [{ chatId: DM_A, messageId: 778, expiresAt: NOW - 1 }],
+    })
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    expect(unpinAll).toHaveBeenCalledTimes(1)
+    expect(pinSilent).not.toHaveBeenCalled()
+  })
+
+  it('(c) first-inbound sweep preserves an unexpired tool pin alongside a live in-memory claim, deduped', async () => {
+    const { deps, pinSilent } = gatewayStyleDeps({
+      inMemory: [500, 777], // live fg: claim + the tool pin also claimed in-memory
+      storeRows: [{ chatId: DM_A, messageId: 777, expiresAt: NOW + 60_000 }],
+    })
+    const sweeper = createDmPinSweeper(deps)
+    await sweeper.sweep(DM_A)
+    // 777 appears in BOTH sources but is re-pinned exactly once.
+    expect(pinSilent.mock.calls).toEqual([
+      [DM_A, 500],
+      [DM_A, 777],
+    ])
+  })
+})

package/telegram-plugin/gateway/dm-pin-sweep.ts

@@ -0,0 +1,178 @@
+/**
+ * DM pin sweep (#3026) — durable clearing of stale bot-authored pins in
+ * user DM chats.
+ *
+ * Why this exists (two independent gaps the probe-based boot sweep can't
+ * close for DMs):
+ *
+ *   1. The boot pin sweep (`shouldSweepChatAtBoot`) deliberately SKIPS
+ *      positive (DM) chat IDs — the Bot API returns `400 chat not found`
+ *      for a user who never messaged the bot. So DM chats were never
+ *      boot-swept at all, and stale pins from a prior session lingered
+ *      across restarts (observed fleet-wide 2026-07-11).
+ *
+ *   2. Even when a DM chat IS reachable, `getChat()` exposes ONLY the
+ *      NEWEST pinned message. Telegram DMs STACK pins and the Bot API has
+ *      no list-pins method, so older orphan pins are invisible to a
+ *      probe-based (unpin-one-by-message-id) sweep forever.
+ *
+ * The durable fix, DM-only: call `unpinAllChatMessages` ONCE per DM chat
+ * per gateway boot (clearing the whole stack — safe in a DM, where
+ * virtually every pin is bot-authored), then immediately RE-PIN the live
+ * tracked cards from the in-memory pin claims (silent, `disable_notification`)
+ * so a genuinely in-flight status/worker pin survives the sweep.
+ *
+ * Groups/supergroups (negative IDs) are NOT touched here — an unpin-all
+ * there would nuke human pins. They keep the existing probe-based path.
+ *
+ * This module is the PURE half (chat-id classification, store→DM-chat-id
+ * collection, and a dependency-injected sweeper with the once-per-boot
+ * guard). The gateway binds the live Bot API + in-memory claim map.
+ */
+
+/**
+ * True iff `chatId` is a user DM chat: a positive integer. Group and
+ * supergroup IDs are negative; zero / non-numeric / non-integer are
+ * malformed and never DMs.
+ */
+export function isDmChatId(chatId: string): boolean {
+  const n = Number(chatId)
+  return Number.isFinite(n) && Number.isInteger(n) && n > 0
+}
+
+/**
+ * Collect the DISTINCT DM chat IDs that appear in ANY of the persisted pin
+ * stores — the set of DM chats the gateway has a record of having pinned
+ * something in during a prior session. These are the DM chats worth
+ * sweeping at boot (an unpin-all is wasted on a DM we never pinned in).
+ *
+ * Pure over its input records; callers pass the loaded store snapshots
+ * (status pins, activity cards, queued/busy-ack cards). Non-DM chat IDs
+ * are filtered out.
+ */
+export function collectDmChatIdsFromStores(input: {
+  statusPins?: readonly { chatId: string }[]
+  activityCards?: readonly { chatId: string }[]
+  queuedCards?: readonly { chatId: string }[]
+}): string[] {
+  const out = new Set<string>()
+  const add = (rows?: readonly { chatId: string }[]): void => {
+    if (rows == null) return
+    for (const r of rows) if (isDmChatId(r.chatId)) out.add(r.chatId)
+  }
+  add(input.statusPins)
+  add(input.activityCards)
+  add(input.queuedCards)
+  return [...out]
+}
+
+/**
+ * The messageIds in `chatId` that must SURVIVE a DM unpin-all because they
+ * belong to deliberately-retained store rows: unexpired time-scoped `tool:`
+ * pins (the `pin_message` MCP tool, #3001), which `runStatusPinBootCleanup`
+ * intentionally KEEPS across restarts. Work-scoped rows (no `expiresAt`) are
+ * stale by definition after a restart and are NOT re-pin candidates; expired
+ * time-scoped rows are due for sweeping.
+ *
+ * Pure over a loaded store snapshot; the gateway binds a LIVE store read into
+ * `liveTrackedMessageIds` so BOTH the boot sweep and a first-inbound sweep
+ * see the kept rows (the in-memory claim maps are empty at boot).
+ */
+export function unexpiredStoreRepinIds(
+  rows: readonly { chatId: string; messageId: number; expiresAt?: number }[],
+  chatId: string,
+  now: number,
+): number[] {
+  const out: number[] = []
+  for (const r of rows) {
+    if (r.chatId !== chatId) continue
+    if (r.expiresAt != null && r.expiresAt > now) out.push(r.messageId)
+  }
+  return out
+}
+
+export interface DmPinSweeperDeps {
+  /** Clear EVERY pinned message in a chat. Bound to the gateway's
+   *  robust/retry API wrapper so a 429 flood-wait is retried, then
+   *  degrades (rejects) rather than crashing — the sweeper absorbs it. */
+  unpinAll: (chatId: string) => Promise<unknown>
+  /** Silently re-pin an EXISTING message (disable_notification). Bound to
+   *  the gateway's robust/retry API wrapper. */
+  pinSilent: (chatId: string, messageId: number) => Promise<unknown>
+  /** Pin message ids in this chat that must survive the unpin-all: the
+   *  in-memory status-pin claims still owned by an in-flight turn/worker,
+   *  UNIONED with the deliberately-retained store rows (unexpired `tool:`
+   *  pins, #3001 — see unexpiredStoreRepinIds). The gateway binds both
+   *  sources; duplicates are deduped by the sweeper before re-pinning. */
+  liveTrackedMessageIds: (chatId: string) => number[]
+  /** Gate: sweep ONLY when the gateway won the startup mutex. The stores
+   *  and the chat's pins are shared per-agent state; a LOSING double-boot
+   *  must never unpin the live holder's legitimate pins. */
+  eligible: () => boolean
+  /** Optional structured log sink. */
+  log?: (line: string) => void
+}
+
+export interface DmPinSweeper {
+  /**
+   * Sweep a single DM chat: unpin-all then re-pin live tracked cards.
+   * At most ONCE per chat per sweeper lifetime (one gateway boot). No-op
+   * for non-DM chats, when not eligible, or when already swept. Never
+   * throws — a failed unpin-all/re-pin degrades and is logged.
+   */
+  sweep(chatId: string): Promise<void>
+  /** True if this chat has already been swept this boot (test/observability). */
+  hasSwept(chatId: string): boolean
+}
+
+export function createDmPinSweeper(deps: DmPinSweeperDeps): DmPinSweeper {
+  const swept = new Set<string>()
+  return {
+    hasSwept: (chatId) => swept.has(chatId),
+    async sweep(chatId: string): Promise<void> {
+      if (!isDmChatId(chatId)) return
+      if (!deps.eligible()) return
+      if (swept.has(chatId)) return
+      // Claim the once-guard BEFORE the first await so two concurrent
+      // triggers (boot + first-inbound landing in the same tick) can't
+      // both fire the unpin-all.
+      swept.add(chatId)
+
+      // Snapshot live claims BEFORE the unpin-all so we know exactly which
+      // messages to restore. Dedupe — the in-memory and store-row sources
+      // can both report the same messageId.
+      const liveIds = [...new Set(deps.liveTrackedMessageIds(chatId))]
+
+      try {
+        await deps.unpinAll(chatId)
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        deps.log?.(
+          `telegram gateway: dm-pin-sweep: unpin-all failed (chat=${chatId}): ${msg}\n`,
+        )
+        // Degrade: the stack may still hold stale pins, but we don't
+        // crash and we don't retry this boot. Fall through to re-pin the
+        // live claims (harmless if the unpin didn't land).
+      }
+
+      for (const messageId of liveIds) {
+        try {
+          await deps.pinSilent(chatId, messageId)
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err)
+          deps.log?.(
+            `telegram gateway: dm-pin-sweep: re-pin failed ` +
+              `(chat=${chatId} msg=${messageId}): ${msg}\n`,
+          )
+        }
+      }
+
+      if (liveIds.length > 0) {
+        deps.log?.(
+          `telegram gateway: dm-pin-sweep: cleared stacked pins in DM ${chatId}, ` +
+            `re-pinned ${liveIds.length} live card(s)\n`,
+        )
+      }
+    },
+  }
+}