switchroom 0.19.19 → 0.19.22

package/telegram-plugin/status-pin-driver.ts

@@ -16,11 +16,18 @@
  *     `🛠 Worker` message). We NEVER send a new message to pin. This is
  *     the boundary that keeps us inside the one sanctioned exception on
  *     `chat-is-the-single-source-of-truth`.
- *   - On UNPIN we DROP THE CLAIM (clear state) EVEN IF `unpinChatMessage`
- *     throws. This is the whole point: pin state must never get stuck.
- *     The message may have been unpinned out-of-band (operator, or a
- *     crash) — re-claiming it would be more confusing than surfacing it
- *     again later, and a stuck claim would leave a permanent pin.
+ *   - On UNPIN we DROP THE CLAIM (clear state) when the unpin succeeded OR
+ *     failed TERMINALLY (`isUnpinTerminalError`: Telegram answered with a
+ *     stable 4xx — rights revoked, message/chat gone). Pin state must never
+ *     get stuck: the message may have been unpinned out-of-band (operator,
+ *     or a crash), and re-claiming it would be more confusing than surfacing
+ *     it again later.
+ *   - #3664 Defect B: a NEVER-CONFIRMED failure (`FLOOD_WAIT_ACTIVE` — a
+ *     local pre-call fail-fast — network, 5xx, retries exhausted) is the one
+ *     case we do NOT drop: the message is provably still pinned, so the claim
+ *     is RETAINED for retry. Dropping it erased both the in-memory claim and
+ *     the durable store row, orphaning a live pin nothing could ever find
+ *     again. Retention is bounded by the boot sweep's forfeit ladder.
  *   - API failures are reported via `onError` but never throw; the caller
  *     decides logging cadence.
  *
@@ -30,7 +37,7 @@
  */
 
 import type { PinState, DesiredPin, PinRightsCache } from './status-pin.js'
-import { decidePinAction, isPinRightsError } from './status-pin.js'
+import { decidePinAction, isPinRightsError, isUnpinTerminalError } from './status-pin.js'
 
 /** Minimal subset of grammy's `bot.api` the pin driver depends on.
  *  Lets tests swap in a fake without dragging in the full Bot type. */
@@ -75,8 +82,10 @@ export interface ReconcilePinArgs {
  *   - `pin`  : pins the existing message SILENTLY; on failure the claim is
  *              NOT taken (returns prevState) so the next reconcile retries
  *              rather than tracking a message it never pinned.
- *   - `unpin`: unpins best-effort and returns `null` — the claim is dropped
- *              EVEN IF the unpin throws (never leave state stuck pinned).
+ *   - `unpin`: unpins best-effort and returns `null` — the claim is dropped on
+ *              success and on a TERMINAL failure (never leave state stuck
+ *              pinned). A never-confirmed failure returns prevState so the
+ *              still-pinned message keeps a record to retry from (#3664).
  *   - `noop` : returns prevState unchanged.
  */
 export async function reconcilePin(
@@ -89,27 +98,41 @@ export async function reconcilePin(
   if (action.kind === 'unpin') {
     // Skip the unpin API call in a chat the bot can't manage pins in — the
     // call would fail with the same rights 400 and spam the log. The claim is
-    // dropped either way (below), so skipping is safe.
-    if (!args.rightsCache?.isBlocked(args.chatId)) {
-      try {
-        await args.api.unpinChatMessage(args.chatId, action.messageId)
-      } catch (err) {
-        // Symmetric with the pin path below: a permanent rights 400 on UNPIN
-        // (rights revoked mid-session after we pinned) also enters the
-        // negative cache and logs once via onPinRightsDisabled — otherwise
-        // every later unpin attempt would burn an API call and spam
-        // `status-pin unpin failed` per attempt, the exact class this cache
-        // exists to kill (#3073 review finding). Claim is dropped regardless.
-        if (args.rightsCache && isPinRightsError(err)) {
-          const firstTime = args.rightsCache.block(args.chatId)
-          if (firstTime) args.onPinRightsDisabled?.(args.chatId)
-        } else {
-          args.onError?.('unpin', err)
-        }
+    // dropped (a pin we can never unpin is not worth tracking), so skipping
+    // is safe.
+    if (args.rightsCache?.isBlocked(args.chatId)) return null
+    try {
+      await args.api.unpinChatMessage(args.chatId, action.messageId)
+    } catch (err) {
+      // Symmetric with the pin path below: a permanent rights 400 on UNPIN
+      // (rights revoked mid-session after we pinned) also enters the
+      // negative cache and logs once via onPinRightsDisabled — otherwise
+      // every later unpin attempt would burn an API call and spam
+      // `status-pin unpin failed` per attempt, the exact class this cache
+      // exists to kill (#3073 review finding). That class is terminal, so the
+      // claim is dropped below.
+      if (args.rightsCache && isPinRightsError(err)) {
+        const firstTime = args.rightsCache.block(args.chatId)
+        if (firstTime) args.onPinRightsDisabled?.(args.chatId)
+      } else {
+        args.onError?.('unpin', err)
       }
+      // #3664 Defect B: drop the claim ONLY on a TERMINAL failure — one where
+      // Telegram answered and the answer can't change (4xx ≠ 429: rights
+      // revoked, message/chat gone, bot kicked). On a NEVER-CONFIRMED failure
+      // (`FLOOD_WAIT_ACTIVE`, which is a local pre-call fail-fast; network;
+      // 5xx; retries exhausted) the message is still pinned, so we RETAIN the
+      // claim: returning prevState makes the caller keep both the in-memory
+      // claim and the durable status-pins.json row (see the non-null branch of
+      // reconcileAndPersistStatusPin), so the next reconcile, the mid-session
+      // reaper and the next-boot sweep can all retry. Dropping the last record
+      // of a pin that is provably still up is strictly worse than a claim that
+      // retries — and retention is bounded by the boot sweep's
+      // BOOT_UNPIN_MAX_ATTEMPTS forfeit ladder.
+      if (!isUnpinTerminalError(err)) return args.prevState
     }
-    // Drop the claim regardless of the unpin outcome. A stuck claim would
-    // leave a permanent pin on a crash / out-of-band unpin — the exact
+    // Unpin confirmed (or terminally rejected) — drop the claim. A stuck claim
+    // would leave a permanent pin on a crash / out-of-band unpin — the exact
     // failure this driver exists to prevent (see slot-banner-driver.ts).
     return null
   }

package/telegram-plugin/status-pin.ts

@@ -21,7 +21,8 @@
  * gateway (via `status-pin-driver.ts`) translates a `PinAction` into
  * actual Telegram API calls. The design mirrors `slot-banner.ts` +
  * `slot-banner-driver.ts` — one pure decision, one side-effecting
- * reconcile, the claim dropped on unpin even when the API throws.
+ * reconcile, the claim dropped on unpin unless the unpin never reached
+ * Telegram at all (`isUnpinTerminalError`, #3664).
  */
 
 /** The message the framework is currently claiming as pinned for a key. */
@@ -43,8 +44,9 @@ export type PinAction =
    *  back into PinState. No new message is sent — this pins a message the
    *  chat already rendered. */
   | { kind: 'pin'; messageId: number }
-  /** Unpin + forget. Caller unpins (best-effort) and clears state EVEN IF
-   *  the unpin call throws. */
+  /** Unpin + forget. Caller unpins (best-effort) and clears state on success
+   *  or a TERMINAL failure; a never-confirmed failure keeps the claim so the
+   *  still-pinned message can be retried (`isUnpinTerminalError`, #3664). */
   | { kind: 'unpin'; messageId: number }
 
 /**
@@ -53,8 +55,8 @@ export type PinAction =
  *
  * Exactly one action per (prev, desired) — the whole point is that pin
  * state can never get stuck: an in-flight → done transition always yields
- * an `unpin`, and the driver drops the claim on unpin regardless of API
- * outcome.
+ * an `unpin`, and the driver drops the claim once the unpin is confirmed
+ * or terminally rejected (see `isUnpinTerminalError`).
  */
 export function decidePinAction(
   prev: PinState | null,
@@ -114,6 +116,42 @@ export function isPinRightsError(err: unknown): boolean {
   return errorDescription(err).includes('not enough rights')
 }
 
+/**
+ * True when an UNPIN failure is TERMINAL — Telegram received the request and
+ * answered definitively, so the answer will not change on retry and the claim
+ * is safe to drop (#3664 Defect B).
+ *
+ * The distinction that matters: a 4xx (other than 429) means the call REACHED
+ * Telegram and was rejected for a reason that is stable — the bot lacks pin
+ * rights, the message/chat is gone, the bot was kicked. Re-issuing the same
+ * unpin forever cannot help, and holding the claim would leave the driver
+ * stuck (the failure mode the drop-on-unpin contract exists to prevent).
+ *
+ * Everything else is NOT confirmed and MUST retain the claim:
+ *
+ *   - `FLOOD_WAIT_ACTIVE` (retry-api-call.ts) — a purely LOCAL fail-fast: the
+ *     send gate refused to make the call, so no request ever left the process
+ *     and the message is provably still pinned. It carries Telegram's 429
+ *     duck-type shape, which is why 429 is excluded here.
+ *   - `retryApiCall: max retries exceeded`, network HttpError, 5xx — the
+ *     unpin may never have landed.
+ *
+ * Dropping the claim on those erased the in-memory claim AND (via
+ * `reconcileAndPersistStatusPin`, which deletes the durable row on a null
+ * return) the persisted record — leaving a message pinned in Telegram that no
+ * reaper and no boot sweep could ever see again. Retaining is bounded: the
+ * boot sweep retries a retained row and forfeits it after
+ * `BOOT_UNPIN_MAX_ATTEMPTS`, so a retained claim can't be permanent either.
+ */
+export function isUnpinTerminalError(err: unknown): boolean {
+  if (isPinRightsError(err)) return true
+  if (err != null && typeof err === 'object') {
+    const code = (err as { error_code?: unknown }).error_code
+    if (typeof code === 'number') return code >= 400 && code < 500 && code !== 429
+  }
+  return false
+}
+
 /**
  * Per-process, per-chat negative cache for chats the bot cannot pin in.
  *

package/telegram-plugin/tests/activity-card-send-gate.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Regression: the live activity/progress card must be RATE-BOUND by the send
+ * gate (#3620).
+ *
+ * ── The bug this pins ─────────────────────────────────────────────────────
+ * `drainActivitySummary` edited the card with
+ *     robustApiCall(() => bot.api.editMessageText(...), { chat_id, verb })
+ * — no `messageId`, no `editPayload`. `sendGate.gate()` only routes to its
+ * edit path when BOTH are present, so every card edit fell through to the
+ * plain-send path and got NONE of the per-message protections:
+ *   - no 1500ms per-message edit floor
+ *   - no last-write-wins coalescing  (the incident logged `coalesced=0`)
+ *   - no identical-payload no-op skip (`dropped=0`)
+ *   - no long-horizon per-message edit budget
+ * and, being untagged, it was admitted as `critical` (UNTAGGED_SEND_CLASS) —
+ * never shed, queued unbounded. One message could therefore be edited at the
+ * per-chat bucket rate for as long as a turn ran, which earned agent
+ * `overlord` a 3713s Telegram flood ban on 2026-07-25.
+ *
+ * ── Oracle ────────────────────────────────────────────────────────────────
+ * The REAL `createNarrativeLane` driven against a fake bot recorder, with the
+ * REAL `createSendGate` wired into `robustApiCall` on a deterministic fake
+ * clock — i.e. the exact production seam, no re-implementation.
+ *
+ * ── The outcome asserted (not the code path) ──────────────────────────────
+ * The per-chat/global buckets are configured WIDE OPEN so they cannot be the
+ * thing doing the limiting; the only remaining brake is the per-message edit
+ * discipline. Then N=40 renders over 10s of fake time must produce a bounded
+ * number of API calls AND the last call must carry the NEWEST body. On the
+ * pre-fix code this test fails on the call count (40 edits issued).
+ */
+import { describe, it, expect } from 'vitest'
+import { tmpdir } from 'node:os'
+import { createNarrativeLane } from '../gateway/narrative-lane.js'
+import { createSendGate, SEND_GATE_DEFAULTS, type Clock, type SendGateOpts } from '../send-gate.js'
+import type { CurrentTurn, NarrativeLaneDeps } from '../gateway/gateway.js'
+
+const CHAT = '1001'
+
+// ── deterministic clock (same shape as send-gate.test.ts) ─────────────────
+class FakeClock implements Clock {
+  private cur = 0
+  private seq = 0
+  private timers: { at: number; id: number; resolve: () => void }[] = []
+
+  now(): number {
+    return this.cur
+  }
+
+  sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.timers.push({ at: this.cur + ms, id: this.seq++, resolve })
+    })
+  }
+
+  async advance(ms: number): Promise<void> {
+    const target = this.cur + ms
+    for (;;) {
+      await flush()
+      const due = this.timers
+        .filter((t) => t.at <= target)
+        .sort((a, b) => a.at - b.at || a.id - b.id)
+      if (due.length === 0) break
+      const t = due[0]!
+      this.timers = this.timers.filter((x) => x !== t)
+      this.cur = t.at
+      t.resolve()
+      await flush()
+    }
+    this.cur = target
+    await flush()
+  }
+}
+
+function flush(): Promise<void> {
+  return new Promise<void>((r) => setImmediate(r))
+}
+
+// ── fake bot recorder ─────────────────────────────────────────────────────
+interface RecordedCall { method: string; text: string; message_id?: number; at: number }
+
+function makeFakeBot(clock: FakeClock) {
+  const calls: RecordedCall[] = []
+  let nextId = 3000
+  const api = {
+    sendRichMessage: async (_c: string, b: { markdown: string }) => {
+      const id = ++nextId
+      calls.push({ method: 'sendRichMessage', text: b.markdown, message_id: id, at: clock.now() })
+      return { message_id: id }
+    },
+    sendMessage: async (_c: string, t: string) => {
+      const id = ++nextId
+      calls.push({ method: 'sendMessage', text: t, message_id: id, at: clock.now() })
+      return { message_id: id }
+    },
+    editMessageText: async (_c: string, m: number, b: unknown) => {
+      calls.push({
+        method: 'editMessageText',
+        text: typeof b === 'string' ? b : (b as { markdown: string }).markdown,
+        message_id: m,
+        at: clock.now(),
+      })
+      return {}
+    },
+    deleteMessage: async () => true,
+  }
+  return { api, calls }
+}
+
+function makeLaneTurn(lane: ReturnType<typeof createNarrativeLane>): CurrentTurn {
+  const turn = {
+    turnId: 'turn-gate-1',
+    sessionChatId: CHAT,
+    sessionThreadId: undefined,
+    sourceMessageId: null,
+    registryKey: null,
+    startedAt: 0,
+    currentModel: null,
+    totalTokens: 0,
+    labeledToolCount: 0,
+    mirrorLines: [] as string[],
+    foregroundSubAgents: new Map<string, string[]>(),
+    activityPendingRender: null as string | null,
+    activityLastSentRender: null as string | null,
+    activityMessageId: null as number | null,
+    activityInFlight: null as Promise<void> | null,
+    activityEverOpened: false,
+    activityDrainFailures: 0,
+    finalAnswerEverDelivered: false,
+    finalAnswerDelivered: false,
+    replyCalled: false,
+    capturedText: [] as string[],
+    lastReplyText: '',
+    answerStream: null,
+    liveness: { recentlyStreaming: () => false, onStreamEvent: () => {}, note: () => {} },
+  } as unknown as CurrentTurn
+  ;(turn as { narrativeGate?: unknown }).narrativeGate = lane.makeNarrativeGate(turn)
+  return turn
+}
+
+/**
+ * The lane wired to the REAL send gate. `bucketOverrides` lets a case widen the
+ * chat/global buckets so the ONLY brake left is the per-message edit discipline
+ * (that is what makes the assertion a statement about the fix and not about the
+ * unrelated per-chat bucket).
+ */
+function makeGatedLane(bucketOverrides: Record<string, number> = {}) {
+  const clock = new FakeClock()
+  const { api, calls } = makeFakeBot(clock)
+  const gate = createSendGate({
+    enabled: true,
+    clock,
+    globalPerSec: 1000,
+    globalBurst: 1000,
+    perChatPerSec: 1000,
+    perChatBurst: 1000,
+    perGroupPerMin: 100000,
+    perGroupBurst: 100000,
+    ...bucketOverrides,
+  })
+  const noop = () => {}
+  const fakeEA = {
+    mayDrain: () => true,
+    openOrEditCard: (_p: string, fn: () => void) => fn(),
+    finalizeCard: (fn: () => void) => fn(),
+    markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+  }
+  const deps = {
+    ACTIVITY_CARD_STORE_PATH: `${tmpdir()}/lane-sendgate-activity-cards.json`,
+    CLEAR_STATUS_ON_COMPLETION: false,
+    FEED_HEARTBEAT_ENABLED: false,
+    FEED_HEARTBEAT_MIN_STALE_MS: 6000,
+    FEED_LIVENESS_OPEN_ENABLED: false,
+    FEED_LIVENESS_OPEN_MS: 5000,
+    PIN_STATUS_WHILE_WORKING: false,
+    POST_ANSWER_LIVENESS_STALE_MS: 90000,
+    STATIC: false,
+    activeDraftStreams: new Map(),
+    activityCardPersistEnabled: false,
+    activityCardStoreFs: {
+      readFileSync: () => '', writeFileSync: noop, mkdirSync: noop, renameSync: noop, unlinkSync: noop,
+    },
+    bot: { api },
+    cardDrainGate: (_t: unknown, _ea: unknown, run: () => void) => run(),
+    currentTurnMap: { get: () => null, byKey: new Map() },
+    earlyLivenessOpenTimers: new Map(),
+    emissionAuthorityFor: () => fakeEA,
+    feedOpenGateDeps: () => ({ hasOutboundDeliveredSince: () => false, historyEnabled: false, finalAnswerMinChars: 200 }),
+    getCurrentTurn: () => null,
+    reconcileStatusPin: noop,
+    robustApiCall: (fn: () => Promise<unknown>, opts?: SendGateOpts) => gate.gate(fn, opts),
+    statusKey: (c: string, t?: number | null) => `${c}:${t ?? 'main'}`,
+  } as unknown as NarrativeLaneDeps
+  const lane = createNarrativeLane(deps)
+  return { lane, calls, clock, gate }
+}
+
+describe('activity card ↔ send gate (#3620)', () => {
+  it('40 rapid card updates over 10s collapse to a handful of edits, newest last', async () => {
+    // Buckets are wide open: whatever bounds the edits here is the PER-MESSAGE
+    // edit discipline, which is exactly what the fix engages.
+    const { lane, calls, clock } = makeGatedLane()
+    const turn = makeLaneTurn(lane)
+
+    lane.showNarrativeStep(turn, 'Step 0 opening the card')
+    await clock.advance(10)
+    await turn.activityInFlight
+    expect(turn.activityMessageId).not.toBeNull()
+
+    const N = 40
+    const windowMs = 10_000
+    for (let i = 1; i <= N; i++) {
+      lane.showNarrativeStep(turn, `Step ${i} of the work`)
+      await clock.advance(windowMs / N)
+    }
+    // Let any in-flight floor sleep settle so the newest body is painted.
+    await clock.advance(SEND_GATE_DEFAULTS.editFloorMs * 2)
+    await turn.activityInFlight
+    await lane.drainActivitySummary(turn)
+    await clock.advance(SEND_GATE_DEFAULTS.editFloorMs * 2)
+    await turn.activityInFlight
+
+    const edits = calls.filter((c) => c.method === 'editMessageText')
+    // (a) BOUNDED: 10s of fake time under a 1500ms floor admits at most
+    // ceil(10000/1500)+1 = 8 edits (+2 for the post-window settle drains). The
+    // pre-fix code issues one edit per render (40) and fails here.
+    const K = Math.ceil(windowMs / SEND_GATE_DEFAULTS.editFloorMs) + 3
+    expect(edits.length).toBeLessThanOrEqual(K)
+    expect(edits.length).toBeGreaterThan(0)
+    // Every edit went to the one card — never a second bubble.
+    expect(calls.filter((c) => c.method === 'sendRichMessage')).toHaveLength(1)
+    expect(edits.every((e) => e.message_id === turn.activityMessageId)).toBe(true)
+    // (b) NEWEST WINS: the last edit carries the latest state, and no
+    // intermediate frame is issued after it.
+    expect(edits[edits.length - 1]!.text).toContain(`Step ${N} of the work`)
+    // (c) SPACING: consecutive edits of the same message respect the floor.
+    for (let i = 1; i < edits.length; i++) {
+      expect(edits[i]!.at - edits[i - 1]!.at).toBeGreaterThanOrEqual(SEND_GATE_DEFAULTS.editFloorMs)
+    }
+  })
+
+  it('a shed card edit is not treated as painted — the newest render survives for the next drain', async () => {
+    // A one-token-per-minute chat bucket: the card open consumes it, so the
+    // next COSMETIC card edit sheds.
+    const { lane, calls, clock } = makeGatedLane({ perChatPerSec: 1 / 60, perChatBurst: 1 })
+    const turn = makeLaneTurn(lane)
+
+    lane.showNarrativeStep(turn, 'Opening the card')
+    await clock.advance(10)
+    await turn.activityInFlight
+    expect(calls.filter((c) => c.method === 'sendRichMessage')).toHaveLength(1)
+
+    lane.showNarrativeStep(turn, 'A shed update')
+    await clock.advance(10)
+    await turn.activityInFlight
+    // Shed → nothing hit the API, and the render is still PENDING (not
+    // mis-recorded as sent), so it is not silently lost.
+    expect(calls.filter((c) => c.method === 'editMessageText')).toHaveLength(0)
+    expect(turn.activityPendingRender).not.toBeNull()
+    expect(turn.activityPendingRender).not.toBe(turn.activityLastSentRender)
+
+    // Once the bucket refills, the next drain paints the NEWEST body — not the
+    // shed intermediate one.
+    lane.showNarrativeStep(turn, 'The newest update')
+    await clock.advance(120_000)
+    await turn.activityInFlight
+    await lane.drainActivitySummary(turn)
+    await clock.advance(10_000)
+    await turn.activityInFlight
+
+    const edits = calls.filter((c) => c.method === 'editMessageText')
+    expect(edits.length).toBeGreaterThan(0)
+    expect(edits[edits.length - 1]!.text).toContain('The newest update')
+  })
+})

package/telegram-plugin/tests/activity-card-wiring.test.ts

@@ -119,26 +119,35 @@ describe('activity-card durability wiring', () => {
 
   it('the boot reaper runs ONLY after the startup mutex is won (never at import time)', () => {
     // #3026: the reaper is now invoked via the mutex-gated orchestrator
-    // runBootPinCleanupAndDmSweep() (which awaits it alongside
+    // runBootPinCleanupAndDmSweep() (which runs it alongside
     // statusPinBootCleanup + queuedCardBootReaper, then runs the DM
     // stale-pin sweep). Invariant unchanged: reachable only post-lock.
-    // (1) The orchestrator awaits the reaper.
+    // (1) The orchestrator runs the reaper. Since the #3664 S2 salvage the
+    // steps are INJECTED into runBootPinSweepSteps (each individually
+    // absorbed, so a throwing reaper cannot strand the DM sweep behind it)
+    // instead of being awaited inline — so the marker is the step binding.
     const orchestrator = between(
       gatewaySrc,
-      'async function runBootPinCleanupAndDmSweep()',
+      'function runBootPinCleanupAndDmSweep()',
       'dmPinSweepEligible = true',
     )
-    expect(orchestrator).toMatch(/await activityCardBootReaper\(\)/)
+    expect(orchestrator).toMatch(/activityCardReaper: activityCardBootReaper,/)
     // (2) Both orchestrator invocation sites (mutex-won + mutex-fallback)
-    // sit AFTER acquireStartupLock.
+    // sit AFTER acquireStartupLock. Since #3664 they ARM the boot sweep gate
+    // rather than dispatching directly: the sweep now also needs `lockedBot`
+    // to exist (gate.botReady() at the end of initGatewayBot), because every
+    // boot unpin was dereferencing an unassigned lockedBot. The mutex half of
+    // the invariant — reachable only post-lock — is unchanged and asserted
+    // here; the bot-ready half lives in boot-pin-sweep-wiring.test.ts.
     const afterLock = between(gatewaySrc, 'await acquireStartupLock({', 'catch (err)')
-    expect(afterLock).toMatch(/void runBootPinCleanupAndDmSweep\(\)/)
-    // (3) Neither the reaper nor the orchestrator is invoked at module import
+    expect(afterLock).toMatch(/bootPinSweepGate\.arm\(\)/)
+    // (3) Neither the reaper nor the sweep is armed/invoked at module import
     // time — the same losing-double-boot hazard the NOTE at
     // statusPinBootCleanup documents.
     const beforeMain = gatewaySrc.split('await acquireStartupLock({')[0] ?? ''
     expect(beforeMain).not.toMatch(/^\s*void activityCardBootReaper\(\)/m)
     expect(beforeMain).not.toMatch(/^\s*void runBootPinCleanupAndDmSweep\(\)/m)
+    expect(beforeMain).not.toMatch(/^\s*bootPinSweepGate\.(arm|botReady)\(\)/m)
   })
 
   it('the reaper wrapper counts a benign-400 as vanished, not finalized (honest boot log)', () => {

package/telegram-plugin/tests/boot-pin-sweep-wiring.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Boot pin sweep WIRING fence (#3664 Defect A).
+ *
+ * The behaviour lives in `boot-sweep-gate.test.ts`; this file pins the gateway
+ * WIRING, because the regression was a wiring regression: `caa4d7568` (#3310)
+ * moved the `lockedBot` assignment into `initGatewayBot()` and left the sweep's
+ * kick-off at module-eval time. `tsc` stayed green (the `!` definite-assignment
+ * assertion on `lockedBot` suppresses the error) and no test noticed, so every
+ * boot-cleanup unpin threw `undefined is not an object` for a month.
+ *
+ * These are STRUCTURAL assertions (the gateway module can't be instantiated
+ * in-process — same pattern as silence-liveness-wiring.test.ts) that fail if a
+ * future refactor re-introduces a module-eval-time dispatch of the sweep.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+
+describe('boot pin sweep wiring (#3664)', () => {
+  it('never dispatches runBootPinCleanupAndDmSweep() directly — only through the gate', () => {
+    // The original bug shape, verbatim: a fire-and-forget call at module-eval
+    // time. Any direct invocation (voided or awaited) bypasses the bot-ready
+    // half of the precondition.
+    const directCalls =
+      gatewaySrc.match(/(?<!function\s)(?<![.\w])runBootPinCleanupAndDmSweep\s*\(/g) ?? []
+    expect(directCalls).toEqual([])
+  })
+
+  it('passes the sweep to the gate as a reference, and arms it at both mutex sites', () => {
+    expect(gatewaySrc).toContain('createBootSweepGate({ run: runBootPinCleanupAndDmSweep')
+    // Both startup-lock outcomes (mutex acquired, and the non-atomic
+    // writePidFile fallback) arm — neither may dispatch on its own.
+    const armSites = gatewaySrc.match(/bootPinSweepGate\.arm\(\)/g) ?? []
+    expect(armSites.length).toBe(2)
+  })
+
+  it('signals botReady() only from initGatewayBot, AFTER lockedBot is assigned', () => {
+    const readySites = gatewaySrc.match(/bootPinSweepGate\.botReady\(\)/g) ?? []
+    expect(readySites.length).toBe(1)
+
+    const initStart = gatewaySrc.indexOf('async function initGatewayBot()')
+    const assignIdx = gatewaySrc.indexOf('lockedBot = chatLock.wrapBot(')
+    const readyIdx = gatewaySrc.indexOf('bootPinSweepGate.botReady()')
+    expect(initStart).toBeGreaterThan(-1)
+    expect(assignIdx).toBeGreaterThan(initStart)
+    expect(readyIdx).toBeGreaterThan(assignIdx)
+  })
+
+  it('runs the sweep steps through runBootPinSweepSteps, not a bare await chain', () => {
+    // Salvage S2. The BEHAVIOUR (a throwing step must not strand the steps
+    // behind it, and must never strand the DM-eligibility flip) is proven in
+    // boot-sweep-gate.test.ts. This fence is what makes that proof apply to the
+    // gateway: the reapers must reach the runner as injected steps, and nothing
+    // may reintroduce the bare sequential chain that skipped the isolation.
+    expect(gatewaySrc).toContain('return runBootPinSweepSteps({')
+    const stepFns = ['statusPinBootCleanup', 'activityCardBootReaper', 'queuedCardBootReaper']
+    for (const stepFn of stepFns) {
+      // Passed BY REFERENCE as a step, never invoked inline in the sweep.
+      expect(gatewaySrc).toContain(`: ${stepFn},`)
+      const inlineAwaits = gatewaySrc.match(new RegExp(`await\\s+${stepFn}\\s*\\(`, 'g')) ?? []
+      expect(inlineAwaits).toEqual([])
+    }
+    // The DM-eligibility flip is what a throw used to strand, so it must live
+    // INSIDE the enableDmSweep step callback — not as a statement sequenced
+    // after the reapers, where one rejection skips it for the whole session.
+    const lines = gatewaySrc.split('\n')
+    const flipIdxs = lines
+      .map((l, i) => ({ l, i }))
+      .filter(({ l }) => /^\s*dmPinSweepEligible = true\s*$/.test(l))
+      .map(({ i }) => i)
+    expect(flipIdxs.length).toBe(1)
+    expect(lines[flipIdxs[0] - 1]).toContain('enableDmSweep: () => {')
+  })
+
+  it('routes the pin API through the asserting seam, never a raw lockedBot.api pin', () => {
+    // Salvage S1/S3: `statusPinApi()` must build on `createStatusPinApi`, which
+    // asserts the bot exists and converts a send-gate SHED into a throw. A
+    // hand-rolled `robustApiCall(() => lockedBot.api.pinChatMessage(...))`
+    // anywhere in the gateway would bypass both invariants.
+    expect(gatewaySrc).toContain('return createStatusPinApi(')
+    // Every `status-pin.*` verb is now issued from status-pin-api.ts. A raw
+    // `robustApiCall(() => lockedBot.api.unpinChatMessage(…), { verb:
+    // 'status-pin.unpin' })` reappearing here would be a driver call that
+    // skips assertBotReady + assertLanded.
+    const statusPinVerbs = gatewaySrc.match(/verb:\s*['"`]status-pin\.(?:un)?pin['"`]/g) ?? []
+    expect(statusPinVerbs).toEqual([])
+  })
+
+  it('arms only from inside the startup-mutex block, never at bare module scope', () => {
+    // Every arm() site must be indented (i.e. nested inside the
+    // `if (isGatewayMain) { … }` startup-lock block), never a top-level
+    // statement that would run unconditionally on import.
+    for (const line of gatewaySrc.split('\n')) {
+      if (line.includes('bootPinSweepGate.arm()')) {
+        expect(line.startsWith(' ')).toBe(true)
+      }
+    }
+  })
+})