switchroom 0.19.19 → 0.19.22

package/telegram-plugin/edit-flood-fuse.ts

@@ -0,0 +1,477 @@
+/**
+ * Edit-flood fuse — a LAST-RESORT rate ceiling installed at the one seam no
+ * outbound call can bypass (#3620).
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────
+ * The send gate (`send-gate.ts`) is the primary pacer, and every call that
+ * goes through `robustApiCall` is admitted by it. But two properties make it
+ * a gate with side doors rather than a failsafe:
+ *
+ *   1. Its per-message protections (edit floor, last-write-wins coalescing,
+ *      no-op skip, long-horizon edit budget) are OPT-IN: `gate()` routes to
+ *      the edit path only when the caller passes BOTH `messageId` and
+ *      `editPayload` (send-gate.ts, `gate()`). A caller that forgets gets a
+ *      plain send — no floor, no coalescing.
+ *   2. An untagged call is admitted as `critical` (UNTAGGED_SEND_CLASS), the
+ *      class that is never shed and queues unbounded.
+ *
+ * That combination is exactly what earned agent `overlord` a 3713-second
+ * flood ban on 2026-07-25: the live activity card edited ONE message id with
+ * neither key nor class, so it ran at the per-chat bucket rate (60/min) for
+ * an hour. Keying that call site fixes that call site — it does not make the
+ * next unkeyed call site impossible.
+ *
+ * ── Why a grammY transformer ──────────────────────────────────────────────
+ * The gateway constructs exactly ONE `new Bot(TOKEN)`, and grammY routes
+ * 100% of outbound API traffic through that instance's transformer stack —
+ * `bot.api.*`, `ctx.api.*`, anything holding a reference to the `Api` object,
+ * wrapped or raw, gated or not. Installing here is therefore STRUCTURAL, not
+ * conventional: a new call site cannot opt out, because there is no code path
+ * to the network that skips the transformer stack. (`shared/bot-runtime.ts`
+ * already proves the seam with `installTgPostLogger`.)
+ *
+ * ── What it does (and deliberately does NOT do) ───────────────────────────
+ *   - EDITS of the same `${chat_id}:${message_id}` are capped at
+ *     `perMessageMaxPerWindow` per `perMessageWindowMs` (default 20/60s).
+ *     Over-budget edits WAIT for the window to slide, and while they wait a
+ *     newer edit to the same message SUPERSEDES them — last-write-wins at the
+ *     chokepoint, for every caller, including ones that never heard of the
+ *     send gate. A superseded or over-deferred edit is DROPPED (resolved as a
+ *     benign no-op), which is safe precisely because the next render of any
+ *     card carries full state.
+ *   - NON-EDIT sends are PACED (per-chat rolling ceiling) but NEVER dropped.
+ *     Dropping a reply would lose a user-visible answer; dropping a repaint
+ *     costs nothing. Pacing is capped at `maxDeferMs`, after which the call
+ *     passes through rather than blocking a reply for an unbounded time.
+ *   - On an observed 429 the ceilings TIGHTEN multiplicatively (AIMD) for
+ *     `tightenMs`, then restore. `retry-api-call.ts` sleeps `retry_after` and
+ *     resumes at FULL rate; nothing in the stack previously reduced the
+ *     sustained rate after a soft 429.
+ *
+ * ── Where the ceiling actually sits (review 2026-07-26, R1) ───────────────
+ * An earlier draft of this docblock claimed the fuse "sits ABOVE every
+ * legitimate cadence". That is FALSE and the claim mattered, so it is
+ * corrected here rather than deleted. The in-repo cadences are:
+ *
+ *   - send gate `editFloorMs` = 1500ms          ⇒ up to 40 edits/min/message
+ *   - send gate cosmetic budget 150 / 300s      ⇒ 30 edits/min/message
+ *   - worker feed's own floor 2500ms            ⇒ 24 edits/min/message
+ *
+ * The per-message ceiling here is 20/60s, i.e. BELOW all three. That is
+ * deliberate — Telegram's own per-group limit is ~20 messages/minute and
+ * edits count against it, so the *legitimate* cadences are themselves above
+ * what Telegram tolerates; that is precisely how `overlord` got banned while
+ * every in-repo pacer believed it was behaving. The fuse is therefore the
+ * BINDING constraint on a hot card, not a never-reached backstop.
+ *
+ * Because it binds routinely, "over budget" must never mean "silently
+ * lost". Two rules follow, and both are load-bearing:
+ *   - per-MESSAGE over-budget edits SUPERSEDE (newest wins, older frame is
+ *     discarded) — safe, because the frame that killed it will paint;
+ *   - per-CHAT over-budget edits may only be DROPPED while a NEWER frame for
+ *     that same message is still in flight to repaint it. When the waiting
+ *     frame is the only one for its card (a turn-final `finalize`, say) it is
+ *     RELEASED late instead of dropped. Dropping it would freeze the card
+ *     mid-run AND return `true` to the send gate, which would then record a
+ *     never-painted payload as on-screen and no-op-skip every retry.
+ */
+
+import type { Bot } from 'grammy'
+
+import type { Clock } from './send-gate.js'
+import { systemClock } from './send-gate.js'
+
+/** Methods that mutate an EXISTING message — droppable, coalescible. */
+const EDIT_METHODS: ReadonlySet<string> = new Set([
+  'editMessageText',
+  'editMessageCaption',
+  'editMessageMedia',
+  'editMessageReplyMarkup',
+  'editMessageLiveLocation',
+  // Review 2026-07-26 (R2): the checklist tools drive this one exactly like a
+  // card — `update_checklist` re-edits ONE message id in a loop
+  // (gateway.ts `_rawEditMessageChecklist`, called through `bot.api.raw`, which
+  // grammY routes through the transformer stack like everything else). Omitting
+  // it left a same-shaped flood path completely unfused.
+  'editMessageChecklist',
+])
+
+/** Methods that CREATE user-visible output — paced, never dropped. */
+const SEND_METHODS: ReadonlySet<string> = new Set([
+  'sendMessage', 'sendPhoto', 'sendDocument', 'sendMediaGroup', 'sendAnimation',
+  'sendVideo', 'sendVoice', 'sendAudio', 'sendSticker', 'sendLocation',
+  'forwardMessage', 'forwardMessages', 'copyMessage', 'copyMessages',
+  // Review 2026-07-26 (R3): `sendRichMessage` is the plugin's PRIMARY send —
+  // every rich reply, every activity-card OPEN, every stream finalisation goes
+  // through it (`rich-send.ts`, `narrative-lane.ts`, `stream-render.ts`).
+  // Leaving it out meant the "non-edit sends are paced" property applied to
+  // almost nothing that this gateway actually sends. Sends are never dropped,
+  // so this only ever adds a bounded (`maxDeferMs`) delay under real pressure.
+  // NOTE: `sendRichMessageDraft` is deliberately NOT here — an ephemeral
+  // 30s-preview draft is high-cadence by design and is not a persisted message.
+  'sendRichMessage',
+])
+
+export interface EditFloodFuseConfig {
+  /** Master switch. When false, `apply` is a pure passthrough. Default true. */
+  enabled?: boolean
+  clock?: Clock
+  /** Hard ceiling on edits to ONE message id. Default 20 per 60s. */
+  perMessageMaxPerWindow?: number
+  perMessageWindowMs?: number
+  /** Hard ceiling on edits to ONE chat across all messages. Default 30 per 60s. */
+  perChatEditMaxPerWindow?: number
+  /** Pacing ceiling on non-edit sends to ONE chat. Default 25 per 60s. */
+  perChatSendMaxPerWindow?: number
+  perChatWindowMs?: number
+  /** Longest a call may be held before it is dropped (edit) / released (send). Default 30s. */
+  maxDeferMs?: number
+  /** Multiplicative decrease applied to every ceiling after a 429. Default 0.5. */
+  tightenFactor?: number
+  /** How long a tightened ceiling stays in force. Default 10 minutes. */
+  tightenMs?: number
+  /** Observability hook; fired whenever the fuse binds. */
+  onTrip?: (info: { method: string; key: string; action: 'deferred' | 'dropped' | 'superseded' }) => void
+}
+
+export interface EditFloodFuseStats {
+  enabled: boolean
+  /** Calls the fuse held back waiting for a window to slide. */
+  deferred: number
+  /** Edits dropped because the window never opened inside `maxDeferMs`. */
+  dropped: number
+  /** Edits dropped because a NEWER edit to the same message arrived. */
+  superseded: number
+  /** 429s observed (each one tightens the ceilings). */
+  floodObserved: number
+  /** Whether a tightened ceiling is in force right now. */
+  tightened: boolean
+  /** Live per-message ceiling (post-AIMD). */
+  perMessageCeiling: number
+}
+
+export const EDIT_FLOOD_FUSE_DEFAULTS = {
+  perMessageMaxPerWindow: 20,
+  perMessageWindowMs: 60_000,
+  perChatEditMaxPerWindow: 30,
+  perChatSendMaxPerWindow: 25,
+  perChatWindowMs: 60_000,
+  maxDeferMs: 30_000,
+  tightenFactor: 0.5,
+  tightenMs: 600_000,
+} as const
+
+/** grammY resolves an edit with `true` when there is nothing to return. */
+const DROPPED_RESULT = true
+
+interface Window {
+  ts: number[]
+  /** The newest waiter on this key; a fresh waiter supersedes it. */
+  waiter: { kill: () => void } | null
+  /**
+   * How many calls for this key are currently inside `apply` (per-MESSAGE keys
+   * only). Read at the per-chat defer deadline: dropping is only honest while
+   * a NEWER frame for the same message is still in flight to repaint. See the
+   * docblock's "Where the ceiling actually sits" (R1).
+   */
+  inflight: number
+}
+
+/**
+ * The fuse as a pure, clock-injectable unit. `apply` has the grammY
+ * transformer shape so it can be handed straight to `bot.api.config.use`.
+ */
+export function createEditFloodFuse(config: EditFloodFuseConfig = {}) {
+  const enabled = config.enabled ?? true
+  const clock = config.clock ?? systemClock
+  const D = EDIT_FLOOD_FUSE_DEFAULTS
+  const perMessageMax = config.perMessageMaxPerWindow ?? D.perMessageMaxPerWindow
+  const perMessageWindowMs = config.perMessageWindowMs ?? D.perMessageWindowMs
+  const perChatEditMax = config.perChatEditMaxPerWindow ?? D.perChatEditMaxPerWindow
+  const perChatSendMax = config.perChatSendMaxPerWindow ?? D.perChatSendMaxPerWindow
+  const perChatWindowMs = config.perChatWindowMs ?? D.perChatWindowMs
+  const maxDeferMs = config.maxDeferMs ?? D.maxDeferMs
+  const tightenFactor = config.tightenFactor ?? D.tightenFactor
+  const tightenMs = config.tightenMs ?? D.tightenMs
+  const onTrip = config.onTrip
+
+  const windows = new Map<string, Window>()
+  const counters = { deferred: 0, dropped: 0, superseded: 0, floodObserved: 0 }
+  /** Timestamp until which the AIMD tightening is in force (0 = untightened). */
+  let tightenedUntil = 0
+
+  function isTightened(now: number): boolean {
+    return tightenedUntil > now
+  }
+
+  /**
+   * AIMD multiplicative decrease. Applied to every ceiling while tightened;
+   * floored at 1 so the fuse never deadlocks a surface completely.
+   */
+  function ceiling(base: number, now: number): number {
+    if (!isTightened(now)) return base
+    return Math.max(1, Math.floor(base * tightenFactor))
+  }
+
+  function win(key: string): Window {
+    let w = windows.get(key)
+    if (w === undefined) {
+      w = { ts: [], waiter: null, inflight: 0 }
+      windows.set(key, w)
+    }
+    return w
+  }
+
+  function prune(w: Window, now: number, windowMs: number): void {
+    const cutoff = now - windowMs
+    while (w.ts.length > 0 && w.ts[0]! <= cutoff) w.ts.shift()
+  }
+
+  /**
+   * Bounded LRU-ish eviction so a long-lived process cannot grow the map
+   * without limit. A window with no in-flight waiter and no timestamps inside
+   * the widest window is dead state.
+   */
+  let sinceEvict = 0
+  function evict(now: number): void {
+    if (windows.size < 4096) return
+    // Sweep at most once per 1024 admissions: an unconditional sweep would be
+    // O(n) on EVERY outbound call once the map is large, i.e. the fuse itself
+    // would become the latency problem it exists to prevent.
+    if (++sinceEvict < 1024) return
+    sinceEvict = 0
+    const widest = Math.max(perMessageWindowMs, perChatWindowMs)
+    for (const [k, w] of windows) {
+      // `inflight > 0` keeps a key whose caller is mid-wait: evicting it would
+      // hand that caller a stale Window object while a FRESH one (empty `ts`)
+      // took its place in the map, resetting the ceiling for everyone else.
+      if (w.waiter === null && w.inflight === 0
+        && (w.ts.length === 0 || w.ts[w.ts.length - 1]! <= now - widest)) {
+        windows.delete(k)
+      }
+    }
+  }
+
+  /** ms until `w` has room, or 0 if it has room now. */
+  function waitFor(w: Window, now: number, windowMs: number, max: number): number {
+    prune(w, now, windowMs)
+    if (w.ts.length < max) return 0
+    return Math.max(1, w.ts[0]! + windowMs - now)
+  }
+
+  function payloadKeys(payload: unknown): { chat: string | null; msg: string | null } {
+    const p = (payload ?? {}) as Record<string, unknown>
+    const chat = p.chat_id != null ? String(p.chat_id) : null
+    const msg = p.message_id != null ? String(p.message_id) : null
+    return { chat, msg }
+  }
+
+  /** Record a 429 (whatever shape it arrives in) and tighten. */
+  function noteFlood(now: number): void {
+    counters.floodObserved++
+    tightenedUntil = now + tightenMs
+  }
+
+  function looksLikeFlood(err: unknown): boolean {
+    const e = err as { error_code?: number; parameters?: { retry_after?: number } } | null
+    if (e != null && typeof e === 'object') {
+      if (e.error_code === 429) return true
+      if (e.parameters != null && typeof e.parameters.retry_after === 'number') return true
+    }
+    // Match on the SEMANTIC markers only. A bare "429" substring
+    // false-positives on ordinary server text (e.g. "message 429 not found"),
+    // and a false positive here halves every ceiling for ten minutes.
+    const msg = err instanceof Error ? err.message : String(err ?? '')
+    return /too many requests/i.test(msg) || /retry[ _-]?after/i.test(msg)
+  }
+
+/**
+   * How a call that finds no room behaves:
+   *   supersede — per-message edits: a newer edit to the SAME message kills it
+   *   drop      — per-chat edits: waits, then drops at the defer deadline
+   *   release   — sends: waits, then passes through (never lost)
+   */
+  type WaitMode = 'supersede' | 'drop' | 'release'
+
+  /** Give back a slot reserved by `awaitRoom` (used when a later tier denies). */
+  function unreserve(key: string, at: number): void {
+    const w = windows.get(key)
+    if (w === undefined) return
+    const i = w.ts.lastIndexOf(at)
+    if (i >= 0) w.ts.splice(i, 1)
+  }
+
+  /**
+   * Wait for room on `key` and RESERVE the slot on success. Reserving inside
+   * the same synchronous step as the check is what makes the ceiling hold
+   * under concurrency: N producers that all pass a check-then-act test in the
+   * same tick would each admit, and N parallel sub-agents is exactly the shape
+   * that turns a ceiling into N× the ceiling.
+   *
+   * Returns the reserved timestamp, or null when the call must be dropped.
+   */
+  async function awaitRoom(
+    key: string, windowMs: number, max: number, method: string, mode: WaitMode,
+    /**
+     * Consulted ONLY at the defer deadline for `mode: 'drop'`. Returning false
+     * converts the drop into a late release: this call is the last thing that
+     * will ever paint its message, so losing it is not "shedding a stale
+     * frame", it is freezing a card. Absent ⇒ drop unconditionally (the
+     * pre-review behaviour).
+     */
+    dropGuard?: () => boolean,
+  ): Promise<number | null> {
+    const w = win(key)
+    const deadline = clock.now() + maxDeferMs
+    let counted = false
+    for (;;) {
+      const now = clock.now()
+      const wait = waitFor(w, now, windowMs, ceiling(max, now))
+      if (wait === 0) {
+        w.ts.push(now)
+        return now
+      }
+      if (now >= deadline) {
+        // Held as long as we are willing to hold. An edit is dropped (the next
+        // render carries full state); a send is released (losing a reply is
+        // worse than a late one).
+        if (mode !== 'release' && (dropGuard === undefined || dropGuard())) {
+          counters.dropped++
+          onTrip?.({ method, key, action: 'dropped' })
+          return null
+        }
+        // A send — or an edit that nothing newer will repaint — is released
+        // rather than dropped, and still takes a slot so the window reflects
+        // what actually went out.
+        w.ts.push(now)
+        return now
+      }
+      if (!counted) {
+        counters.deferred++
+        counted = true
+        onTrip?.({ method, key, action: 'deferred' })
+      }
+      // Last-write-wins: a newer edit to the same message kills this one. Only
+      // valid on the per-MESSAGE tier — on a per-chat key the "newer" edit is
+      // usually to a DIFFERENT message, and killing an unrelated card's edit is
+      // not last-write-wins, it is data loss.
+      let killed = false
+      if (mode === 'supersede') {
+        w.waiter?.kill()
+        const superseded = new Promise<void>((resolve) => {
+          w.waiter = { kill: () => { killed = true; resolve() } }
+        })
+        await Promise.race([clock.sleep(Math.min(wait, deadline - now)), superseded])
+        if (killed) {
+          counters.superseded++
+          onTrip?.({ method, key, action: 'superseded' })
+          return null
+        }
+        w.waiter = null
+      } else {
+        await clock.sleep(Math.min(wait, deadline - now))
+      }
+    }
+  }
+
+  /** The grammY transformer body. */
+  async function apply<R>(
+    method: string,
+    payload: unknown,
+    next: () => Promise<R>,
+  ): Promise<R> {
+    if (!enabled) return next()
+
+    const isEdit = EDIT_METHODS.has(method)
+    const isSend = SEND_METHODS.has(method)
+    if (!isEdit && !isSend) return runObserved(next)
+
+    const { chat, msg } = payloadKeys(payload)
+    // Inline-message edits carry no chat/message id — nothing to key on, and
+    // they are not part of any card loop. Pass through (still observed).
+    if (chat == null) return runObserved(next)
+
+    const now = clock.now()
+    evict(now)
+
+    if (isEdit) {
+      if (msg == null) return runObserved(next)
+      const msgKey = `m:${chat}:${msg}`
+      const mw = win(msgKey)
+      // Counted BEFORE the first await so a frame that arrives while an older
+      // one is waiting is visible to that older one's `dropGuard`.
+      mw.inflight++
+      try {
+        const msgSlot = await awaitRoom(msgKey, perMessageWindowMs, perMessageMax, method, 'supersede')
+        if (msgSlot === null) return DROPPED_RESULT as unknown as R
+        const chatKey = `ce:${chat}`
+        const chatSlot = await awaitRoom(
+          chatKey, perChatWindowMs, perChatEditMax, method, 'drop',
+          // R1: only drop while something newer for THIS message is still in
+          // flight to repaint it. `> 1` = this frame plus at least one newer.
+          () => mw.inflight > 1,
+        )
+        if (chatSlot === null) {
+          // Denied by the second tier — hand the first tier's slot back so a
+          // dropped edit never consumes budget it did not use.
+          unreserve(msgKey, msgSlot)
+          return DROPPED_RESULT as unknown as R
+        }
+        return runObserved(next)
+      } finally {
+        mw.inflight--
+      }
+    }
+
+    const chatKey = `cs:${chat}`
+    await awaitRoom(chatKey, perChatWindowMs, perChatSendMax, method, 'release')
+    return runObserved(next)
+  }
+
+  /** Run the downstream call, tightening the ceilings if it floods. */
+  async function runObserved<R>(next: () => Promise<R>): Promise<R> {
+    try {
+      const res = await next()
+      // grammY throws on ok:false, but a transformer installed BELOW another
+      // one can still observe a raw ApiResponse — handle both shapes.
+      const r = res as unknown as { ok?: boolean; error_code?: number }
+      if (r != null && typeof r === 'object' && r.ok === false && r.error_code === 429) {
+        noteFlood(clock.now())
+      }
+      return res
+    } catch (err) {
+      if (looksLikeFlood(err)) noteFlood(clock.now())
+      throw err
+    }
+  }
+
+  function stats(): EditFloodFuseStats {
+    const now = clock.now()
+    return {
+      enabled,
+      deferred: counters.deferred,
+      dropped: counters.dropped,
+      superseded: counters.superseded,
+      floodObserved: counters.floodObserved,
+      tightened: isTightened(now),
+      perMessageCeiling: ceiling(perMessageMax, now),
+    }
+  }
+
+  return { apply, stats }
+}
+
+export type EditFloodFuse = ReturnType<typeof createEditFloodFuse>
+
+/**
+ * The bot handle the fuse installs on. Typed against grammY's own `Bot` so the
+ * transformer signature is checked by the compiler, not by convention.
+ */
+export type FuseInstallable = Bot
+
+export function installEditFloodFuse(bot: FuseInstallable, config: EditFloodFuseConfig = {}): EditFloodFuse {
+  const fuse = createEditFloodFuse(config)
+  bot.api.config.use(async (prev, method, payload, signal) =>
+    fuse.apply(method, payload, () => prev(method, payload, signal)))
+  return fuse
+}

package/telegram-plugin/format.ts

@@ -326,13 +326,25 @@ export function normalizeParagraphBreaks(text: string): string {
   //       it was the "stray blank line" seen in real replies. Collapse it.
   //
   // Deliberately ASCII-only: the `[ \t\r]` character class excludes U+00A0 by
-  // construction, so a line whose only content is a non-breaking space a user
-  // legitimately typed is left intact rather than silently collapsed. (This
-  // used to also protect the NBSP paragraph spacer that addParagraphSpacers
-  // injected downstream; that spacer pass was removed in the #2669 follow-up —
-  // paragraph gaps now rely on plain `\n\n` — but keeping this ASCII-only is
-  // still the conservative choice.) Runs on code-masked text, so a blank-ish
-  // line inside a fenced block is parked and never touched.
+  // construction, so a line whose only content is a non-breaking space is left
+  // intact rather than silently collapsed.
+  //
+  // That is load-bearing, not merely conservative. `addParagraphSpacers` (below)
+  // wedges a U+00A0-only line into every prose paragraph gap to force a VISIBLE
+  // gap (#2692) and is LIVE on the outbound path today — gateway/
+  // outbound-send-path.ts (`normalizeOutboundBody`) and gateway/gateway.ts (the
+  // rich `sendRichMessage` chunker). Within a single `normalizeOutboundBody`
+  // pass the spacer is injected AFTER this normalizer, so this pass usually does
+  // not see it — but the ASCII-only class is a deliberate, pinned invariant, not
+  // an accident of that ordering: tests/paragraph-normalizer.test.ts ("the
+  // deliberate U+00A0 spacer … is preserved") asserts
+  // `normalizeParagraphBreaks(spaced) === spaced`, so this function stays safe
+  // to re-enter over already-spacered text. Widening `[ \t\r]` to catch U+00A0
+  // would eat the spacer, fail that test, and regress #2692.
+  //
+  // It also leaves a non-breaking space a user legitimately typed alone. Runs on
+  // code-masked text, so a blank-ish line inside a fenced block is parked and
+  // never touched.
   let out = masked
     // Collapse any run of newlines interleaved with ASCII whitespace-only
     // interior lines down to a single clean `\n\n`. Requires at least one

package/telegram-plugin/gateway/boot-sweep-gate.ts

@@ -0,0 +1,164 @@
+/**
+ * boot-sweep-gate.ts — control flow for the boot pin sweep (#3664): WHEN it may
+ * start (`createBootSweepGate`, the two-condition arming gate) and HOW its steps
+ * are sequenced once it does (`runBootPinSweepSteps`, per-step isolation).
+ *
+ * Why this exists
+ * ---------------
+ * The boot orphan sweep (`runBootPinCleanupAndDmSweep` → `statusPinBootCleanup`
+ * → `unpinChatMessage`) has TWO independent preconditions, and they are
+ * satisfied at two different points of the gateway's boot:
+ *
+ *   1. **Ownership** — this process won the startup mutex, so it is the sole
+ *      live owner of the shared per-agent pin state. Established during module
+ *      evaluation (`acquireStartupLock`, plus the non-atomic fallback path).
+ *      A LOSING double-boot must never unpin the live holder's pins.
+ *   2. **A Telegram handle** — `lockedBot` is assigned, so an unpin can
+ *      actually reach Telegram. Established much later, inside
+ *      `initGatewayBot()` at boot.
+ *
+ * Before this gate the sweep was kicked off fire-and-forget the moment (1) was
+ * satisfied, i.e. at module-eval time — thousands of lines before (2). Every
+ * boot-cleanup unpin therefore threw `undefined is not an object (evaluating
+ * 'lockedBot.api')` before touching the network, the row was retained with an
+ * incremented attempt counter, and after `BOOT_UNPIN_MAX_ATTEMPTS` the only
+ * record of a still-pinned message was forfeited. That was a regression from
+ * `caa4d7568` (#3310), which moved the Bot construction — and with it the
+ * `lockedBot` assignment — out of module scope into `initGatewayBot()` while
+ * leaving the sweep's kick-off where it was.
+ *
+ * The gate makes the ordering DETERMINISTIC rather than a race: the sweep runs
+ * exactly once, when BOTH signals have arrived, in whichever order they arrive.
+ * It cannot regress by code motion — moving either signal site around cannot
+ * make the sweep fire before the other signal.
+ *
+ * Deliberately dependency-free and side-effect-free so it is provable in
+ * isolation (`telegram-plugin/tests/boot-sweep-gate.test.ts`); the gateway owns
+ * the wiring.
+ */
+
+export interface BootSweepGate {
+  /** Signal (1): this gateway owns the shared per-agent pin state. */
+  arm(): void
+  /** Signal (2): the Telegram bot handle exists — API calls can be made. */
+  botReady(): void
+  /** True once the sweep has been dispatched. Test/introspection seam. */
+  hasRun(): boolean
+}
+
+/**
+ * Build a gate that dispatches `run` exactly once, after BOTH `arm()` and
+ * `botReady()` have been called. Both signals are idempotent and
+ * order-independent. `run` is dispatched fire-and-forget; a rejection is routed
+ * to `onError` so it can never surface as an unhandled rejection (the sweep is
+ * best-effort and must never take the gateway down).
+ */
+export function createBootSweepGate(args: {
+  run: () => Promise<void>
+  onError?: (err: unknown) => void
+}): BootSweepGate {
+  let armed = false
+  let ready = false
+  let started = false
+
+  const maybeRun = (): void => {
+    if (started || !armed || !ready) return
+    started = true
+    void (async () => {
+      try {
+        await args.run()
+      } catch (err) {
+        args.onError?.(err)
+      }
+    })()
+  }
+
+  return {
+    arm(): void {
+      armed = true
+      maybeRun()
+    },
+    botReady(): void {
+      ready = true
+      maybeRun()
+    },
+    hasRun(): boolean {
+      return started
+    },
+  }
+}
+
+/** Dependencies of {@link runBootPinSweepSteps}. All side effects are injected
+ *  so the sequencing contract is provable without a gateway. */
+export interface BootPinSweepSteps {
+  /** Pure fs scan for DM chat ids with a prior-session pin record. MUST run
+   *  BEFORE the reapers, which empty those same stores. */
+  scanDmChatIds: () => string[]
+  statusPinCleanup: () => Promise<unknown>
+  activityCardReaper: () => Promise<unknown>
+  queuedCardReaper: () => Promise<unknown>
+  /** Flips the flag authorising the DM unpin-all path — for this sweep AND for
+   *  later lazy first-inbound sweeps. */
+  enableDmSweep: () => void
+  sweepDm: (chatId: string) => Promise<unknown>
+  log?: (line: string) => void
+}
+
+/**
+ * Run one sweep step, absorbing (and logging) a throw. See
+ * {@link runBootPinSweepSteps} for why isolation is mandatory here.
+ *
+ * Absorbs unconditionally: a non-`Error` throw is stringified rather than
+ * logged as `undefined`, and a `log` that itself throws (a closed stderr on a
+ * dying process) is swallowed too — otherwise the one function whose whole job
+ * is "never let a step take the sweep down" could take the sweep down.
+ */
+async function step(name: string, fn: () => Promise<unknown>, log: (line: string) => void) {
+  try {
+    await fn()
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    try {
+      log(`telegram gateway: boot pin sweep step '${name}' failed: ${msg}\n`)
+    } catch {
+      /* stderr is gone — nothing useful left to do */
+    }
+  }
+}
+
+/**
+ * Sequence the boot sweep's steps, each individually absorbed.
+ *
+ * Why isolation is mandatory (#3664 salvage S2). The steps used to run as a
+ * bare sequential `await` chain. `runStatusPinBootCleanup` absorbs its own
+ * per-row throws, but the two card reapers issue real Bot API calls and can
+ * reject outright — and a rejection there did not merely skip the later
+ * reapers, it skipped `enableDmSweep()`. That flag authorises the DM
+ * unpin-all path for the WHOLE SESSION (the boot sweep AND every later lazy
+ * first-inbound sweep), so one throwing reaper silently disabled DM stale-pin
+ * cleanup entirely.
+ *
+ * That was unreachable before #3664 only because the sweep never actually ran
+ * — every step died on `undefined is not an object (evaluating
+ * 'lockedBot.api')` before doing anything. Making the sweep work for the first
+ * time is precisely what makes an earlier step's throw newly reachable, so the
+ * isolation lands with the fix rather than after it.
+ *
+ * Never rejects: every step is best-effort and the caller fire-and-forgets it.
+ */
+export async function runBootPinSweepSteps(deps: BootPinSweepSteps): Promise<void> {
+  const log = deps.log ?? ((l: string) => process.stderr.write(l))
+
+  let dmChatIds: string[] = []
+  await step('dm-chat-scan', async () => {
+    dmChatIds = deps.scanDmChatIds()
+  }, log)
+
+  await step('status-pin-cleanup', deps.statusPinCleanup, log)
+  await step('activity-card-reaper', deps.activityCardReaper, log)
+  await step('queued-card-reaper', deps.queuedCardReaper, log)
+
+  // Unconditional: reached even when every step above threw. See the docblock.
+  await step('enable-dm-sweep', async () => deps.enableDmSweep(), log)
+  for (const id of dmChatIds) await step(`dm-sweep:${id}`, () => deps.sweepDm(id), log)
+}