switchroom 0.19.26 → 0.19.28

package/telegram-plugin/gateway/flood-reply-queue.ts

@@ -0,0 +1,168 @@
+/**
+ * flood-reply-queue.ts — durably queue a USER-FACING reply that Telegram's
+ * flood window refused, instead of throwing its content away.
+ *
+ * The hole this closes (#3861). `retryApiCall` short-circuits BEFORE the wire
+ * when the persisted breaker reports a window longer than its in-process sleep
+ * ceiling, throwing the `FLOOD_WAIT_ACTIVE` marker (`retry-api-call.ts:198`,
+ * `:252`). That is the right call for the WIRE — nothing can succeed while the
+ * ban is open — but it is a bare `throw`, and the reply path's chunk-loop catch
+ * only re-wrapped it:
+ *
+ *     reply failed after 0 of 1 chunk(s) sent: FLOOD_WAIT_ACTIVE
+ *
+ * The composed answer died in that string. Reproduced live on 2026-07-28: the
+ * error came back to the MCP caller and NO record appeared in the agent's
+ * `telegram/outbox/`. The durable-outbox work-loss guarantee was real for the
+ * outbox-delivered paths and false for the interactive reply path — so during a
+ * multi-hour ban the agent's actual answers to the operator were the one class
+ * of content that was silently lost.
+ *
+ * What this module does: classify the failure, and for anything that is not
+ * droppable (`cosmetic`) write the text into the SAME durable outbox the sweep
+ * already drains, under a CONTENT-derived nonce. The sweep (which since #3854
+ * defers while the window is open) delivers it when the window closes.
+ *
+ * Two design choices worth stating, because both are load-bearing:
+ *
+ * 1. CONTENT-derived nonce, not the turn nonce. `writeOutboxRecordAtomic` is
+ *    idempotent per nonce and the sweep's delivered-keys journal is keyed by
+ *    nonce, so a content nonce gives caller-retry dedup (same text ⇒ same file
+ *    ⇒ one delivery, and after delivery the journal makes a re-queue a no-op)
+ *    WITHOUT inheriting the turn nonce's failure mode: an earlier successful
+ *    reply in the same turn journals `turn.turnId` as delivered, which would
+ *    make a later flood-blocked answer queued under that same nonce
+ *    `skip-journaled` — i.e. dropped. Never drop the answer.
+ *
+ * 2. `cosmetic` is NOT queued. A typing indicator or a card edit that missed
+ *    its moment is worthless (and actively confusing) delivered hours later;
+ *    the priority classes already in the tree say so. `critical` / `useful` /
+ *    untagged are queued.
+ */
+
+import { sha256Hex, writeOutboxRecordAtomic, type OutboxRecord } from '../outbox.js'
+import { isFloodWaitActiveError } from '../retry-api-call.js'
+
+/** The `source` stamped on records this module writes (diagnostic only). */
+export const FLOOD_QUEUED_SOURCE = 'flood-deferred-reply'
+
+/** Priority classes as used by `retry-api-call.ts` / `outbound-class.ts`. */
+export type QueuePriorityClass = 'critical' | 'useful' | 'cosmetic' | undefined
+
+/**
+ * True when `err` is a Telegram flood rejection — the local `FLOOD_WAIT_ACTIVE`
+ * fail-fast, a raw 429, or a wrapper whose message carries either.
+ *
+ * Deliberately duck-typed as well as `instanceof`-checked: the marker error
+ * carries Telegram's own `{ error_code: 429, parameters: { retry_after } }`
+ * shape, several surfaces re-wrap it in a plain `Error`, and the reply path's
+ * own partial-failure contract wraps it in
+ * `reply failed after N of M chunk(s) sent: …`.
+ */
+export function isFloodRejection(err: unknown): boolean {
+  if (isFloodWaitActiveError(err)) return true
+  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 (typeof e.parameters?.retry_after === 'number') return true
+  }
+  const msg = err instanceof Error ? err.message : String(err ?? '')
+  if (msg.includes('FLOOD_WAIT_ACTIVE')) return true
+  return /too many requests/i.test(msg) && /retry[ _-]?after/i.test(msg)
+}
+
+/** Telegram's stated `retry_after` (seconds) if the error carries one. */
+export function floodRetryAfterSec(err: unknown): number | null {
+  const e = err as { retryAfterSec?: number; parameters?: { retry_after?: number } } | null
+  if (e != null && typeof e === 'object') {
+    if (typeof e.retryAfterSec === 'number') return e.retryAfterSec
+    if (typeof e.parameters?.retry_after === 'number') return e.parameters.retry_after
+  }
+  const msg = err instanceof Error ? err.message : String(err ?? '')
+  const m = /retry[ _-]?after[^0-9]{0,4}(\d+)/i.exec(msg)
+  return m != null ? Number(m[1]) : null
+}
+
+/**
+ * Stable, content-derived outbox nonce for a flood-deferred send. Same
+ * chat + thread + text ⇒ same nonce ⇒ exactly one delivery however many times
+ * the caller retries. Prefixed so a record's provenance is obvious on disk.
+ */
+export function floodQueueNonce(
+  chatId: string,
+  threadId: number | null,
+  text: string,
+): string {
+  return `flood-${sha256Hex(`${chatId}\u0000${threadId ?? '_'}\u0000${text}`).slice(0, 40)}`
+}
+
+export interface FloodQueueInput {
+  /** The error that killed the send. */
+  err: unknown
+  chatId: string
+  threadId: number | null
+  /** The UNDELIVERED text (for a partial failure, only the chunks that never landed). */
+  text: string
+  /** Priority class of the send. `cosmetic` is never queued. */
+  priorityClass?: QueuePriorityClass
+  /** Per-session origin chat, for the sweep's F2 scoped routing fallback. */
+  originChatId?: string | null
+  originThreadId?: number | null
+  createdAt?: number
+  stateDir?: string
+  /** Injected for tests; defaults to the real atomic outbox writer. */
+  write?: (record: OutboxRecord, stateDir?: string) => boolean
+}
+
+export interface FloodQueueResult {
+  turnNonce: string
+  retryAfterSec: number | null
+  /** Human-readable outcome for the MCP caller, so the model does NOT recompose. */
+  notice: string
+}
+
+/**
+ * Queue a flood-blocked send to the durable outbox.
+ *
+ * Returns `null` — meaning "not handled, let the caller throw" — when the error
+ * is not a flood rejection, when the class is `cosmetic` (legitimately
+ * droppable), when there is no text left to deliver, or when the disk write
+ * failed. A `null` return must never be mistaken for "delivered".
+ */
+export function queueFloodBlockedReply(input: FloodQueueInput): FloodQueueResult | null {
+  const { err, chatId, threadId, text } = input
+  if (!isFloodRejection(err)) return null
+  if (input.priorityClass === 'cosmetic') return null
+  if (chatId === '' || text === '') return null
+
+  const turnNonce = floodQueueNonce(chatId, threadId, text)
+  const createdAt = input.createdAt ?? Date.now()
+  const record: OutboxRecord = {
+    turnNonce,
+    chatId,
+    threadId,
+    text,
+    textSha256: sha256Hex(text),
+    createdAt,
+    source: FLOOD_QUEUED_SOURCE,
+    ...(input.originChatId != null ? { originChatId: input.originChatId } : {}),
+    ...(input.originThreadId != null ? { originThreadId: input.originThreadId } : {}),
+  }
+  const write = input.write ?? writeOutboxRecordAtomic
+  if (!write(record, input.stateDir)) return null
+
+  const retryAfterSec = floodRetryAfterSec(err)
+  const when =
+    retryAfterSec != null && retryAfterSec > 0
+      ? ` Telegram's flood window has ~${retryAfterSec}s left`
+      : ' A Telegram flood window is open'
+  return {
+    turnNonce,
+    retryAfterSec,
+    notice:
+      `reply QUEUED (not yet visible to the user):${when}, so this answer was written ` +
+      `to the durable outbox and will be delivered automatically when the window ` +
+      `closes. Do NOT resend it — a resend is deduplicated, and every extra call ` +
+      `extends the ban. (outbox nonce ${turnNonce})`,
+  }
+}

package/telegram-plugin/gateway/gateway.ts

@@ -180,7 +180,7 @@ import {
 import { fmtLocalStamp, resolveEnvTimezone, renderLogTimestampsLocal } from '../shared/local-time.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { DeferredDoneReactions } from '../reaction-defer.js'
-import { createWorkerActivityFeed, isWorkerActivityFeedEnabled } from '../worker-activity-feed.js'
+import { createWorkerActivityFeed, isWorkerActivityFeedEnabled, workerFeedEditPriorityClass } from '../worker-activity-feed.js'
 import {
   detectMemoryLegibilityEvent,
   isMemoryLegibilityEnabled,
@@ -195,8 +195,8 @@ import {
   renderConsolidationLine,
 } from '../consolidation-legibility.js'
 import type { WebhookGatewayRecord } from '../../src/web/webhook-gateway-record.js'
-import { reconcilePin, type PinBotApi } from '../status-pin-driver.js'
-import type { PinState, DesiredPin } from '../status-pin.js'
+import { executePinLeg, type PinBotApi } from '../status-pin-driver.js'
+import type { PinState, DesiredPin, PinLegAction } from '../status-pin.js'
 import { PinRightsCache } from '../status-pin.js'
 import { formatTurnLifecycle, detectStatusSurfaceDegraded } from './status-surface-log.js'
 import { parseSourceMessageId } from './source-message-id.js'
@@ -294,7 +294,7 @@ import {
   retryWithThreadFallback,
   isFloodWaitActiveError,
 } from '../retry-api-call.js'
-import { installEditFloodFuse } from '../edit-flood-fuse.js'
+import { installEditFloodFuse, editFloodFuseConfigFromEnv } from '../edit-flood-fuse.js'
 import { createSendGate, sendGateConfigFromEnv, isSendGateShed } from '../send-gate.js'
 import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
 import { installTgPostLogger, installRichMarkdownGuard, withTgPostTags } from '../shared/bot-runtime.js'
@@ -404,6 +404,7 @@ import {
   type OperatorEvent,
   type OperatorEventKind,
 } from '../operator-events.js'
+import { createMcpFailureHook } from './mcp-failure-hook.js'
 import { pendingUserNoticeGate } from '../pending-user-notice.js'
 import { recordOperatorEvent } from '../operator-events-history.js'
 import {
@@ -637,7 +638,7 @@ import type { HostdRequest, HostdResponse } from '../../src/host-control/protoco
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 import { createBootSweepGate, runBootPinSweepSteps } from './boot-sweep-gate.js'
-import { runStatusPinReconcile } from './status-pin-retarget.js'
+import { runStatusPinReconcile, type StatusPinClaim } from './status-pin-retarget.js'
 import { createPeriodicSweepGuard } from './periodic-sweep-guard.js'
 import { withDeadline } from './with-deadline.js'
 import { createStatusPinApi, type PinCapableBot, type RobustApiSeam } from './status-pin-api.js'
@@ -691,6 +692,7 @@ import {
 } from './queued-card-store.js'
 import {
   decideWorkerPinReaps,
+  groupPinStatus,
   storeOnlyWorkerPinCandidates,
   WORKER_PIN_TTL_MS_DEFAULT,
 } from './worker-pin-reaper.js'
@@ -5865,7 +5867,7 @@ const redactAuthCodeApi = {
  * flood sleep and added a pre-call gate for LONG open windows. This wrapper
  * pre-dates neither mechanism nor fights them — it sits under the emitter's own
  * flood gate, which short-circuits earlier still (a typing ping during a ban
- * never even reaches the retry layer). Defense in depth, in that order.
+ * never even reaches the retry layer; #3853 adds the READ hook here too).
  */
 // No `log` hook: retryApiCall's flood line reads "waiting Ns", which would be a
 // lie here — we never wait, we drop. And the error the caller finally sees names
@@ -5875,7 +5877,7 @@ const redactAuthCodeApi = {
 // the real value is still in hand.
 const recordTypingFloodWait = makeFloodWaitRecorder(FLOOD_STATE_PATH)
 const nonEssentialApiCall = createRetryApiCall({
-  maxRetries: 1,
+  maxRetries: 1, floodWaitRemainingMs: probeFloodWaitRemainingMs, // #3853 read side
   sleep: async () => {},
   onFloodWait: (retryAfterSec) => {
     recordTypingFloodWait(retryAfterSec)
@@ -8524,19 +8526,18 @@ const PIN_STATUS_WHILE_WORKING = (() => {
 // It does NOT touch the reply / stream_reply send handlers (the v1 bug was send
 // handlers unconditionally unpinning on every send) and runs NO polling
 // watchdog / getChat().pinned_message reconciler.
-const statusPinState = new Map<string, PinState>()
+// ONE registry, keyed by pinKey → { messageId, chatId, pinnedAt } (#3809).
+// This was three parallel Maps (state / chatIds / pinnedAt), written on the
+// same commit but free to diverge; a `wk:` claim that lost its chatId entry was
+// skipped by the mid-session reaper on every pass AND excluded from the durable
+// store-orphan net, i.e. silently unreapable until the next boot. One record
+// makes the invariant structural — see StatusPinClaim in status-pin-retarget.ts.
+//
 // F2 serialization: same-pinKey reconciles run one-at-a-time via
 // `withPinReconcileLock` (status-pin-store.ts — kept there so it's
 // unit-testable) so each reads a fresh `prev`; see its doc for the stale-`prev`
 // race it closes. Adds zero Telegram API calls (a serialized noop still no-ops).
-// Companion registry: pinKey → chatId, so the pre-restart sweep can unpin
-// owned pins without threading the chat id through every call site. Written on
-// every desired-pinned reconcile, cleared alongside the state on unpin.
-const statusPinChatIds = new Map<string, string>()
-// Companion registry: pinKey → wall-clock ms the claim was FIRST taken (a
-// re-pin of the same key keeps the original timestamp). Feeds the TTL gate of
-// the mid-session `wk:` pin reaper (#3001); cleared alongside the state.
-const statusPinPinnedAt = new Map<string, number>()
+const statusPinClaims = new Map<string, StatusPinClaim>()
 // Rights-aware negative cache (#3024): chats where an auto status-pin attempt
 // failed with the permanent "not enough rights to manage pinned messages" 400.
 // Per-process only — a restart clears it so a later-granted pin right re-enables
@@ -8660,7 +8661,7 @@ const TOOL_PIN_TTL_MS = (() => {
 // mutation never rejects (persist is fail-open, load is fail-open).
 function persistBannerRow(row: PersistedStatusPin | null): void {
   if (!bannerPinPersistEnabled) return
-  void mutateStatusPinRow(
+  void mutateStatusPinRow( // allow-raw-pin-store: banner row bookkeeping — the slot banner has its own sanctioned driver; this only mirrors its outcome into the shared store file.
     STATUS_PIN_STORE_PATH,
     statusPinStoreFs,
     BANNER_PIN_KEY,
@@ -8700,7 +8701,7 @@ async function statusPinBootCleanup(): Promise<void> {
   const { cleared, retained, kept, total } = await runStatusPinBootCleanup({
     path: STATUS_PIN_STORE_PATH,
     fs: statusPinStoreFs,
-    unpin: (chatId, messageId) => api.unpinChatMessage(chatId, messageId),
+    unpin: (chatId, messageId) => api.unpinChatMessage(chatId, messageId), // allow-raw-pin: boot cleanup runs BEFORE any claim exists — it reconciles the durable rows themselves, so there is nothing to route through reconcileStatusPin.
   })
   if (total > 0) {
     process.stderr.write(
@@ -8763,7 +8764,7 @@ async function activityCardBootReaper(): Promise<void> {
       ),
     unpinCard: (record) =>
       robustApiCall(
-        () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId),
+        () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId), // allow-raw-pin: activity-card boot reaper — unpins a card recovered from the CARD store, which has no status-pin claim to reconcile through.
         {
           chat_id: record.chatId,
           ...(record.threadId != null ? { threadId: record.threadId } : {}),
@@ -8942,12 +8943,12 @@ async function runMidSessionCardReaper(): Promise<void> {
         // claim is tracked (e.g. claim already dropped out-of-band).
         unpinCard: async (record) => {
           const pinKey = `fg:${record.turnKey}`
-          if (statusPinState.has(pinKey)) {
+          if (statusPinClaims.has(pinKey)) {
             await reconcileStatusPin(pinKey, record.chatId, { pinned: false })
             return true
           }
           return robustApiCall(
-            () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId),
+            () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId), // allow-raw-pin: activity-card mid-session reaper — same as the boot reaper: a card-store record, not a status-pin claim.
             {
               chat_id: record.chatId,
               ...(record.threadId != null ? { threadId: record.threadId } : {}),
@@ -8975,17 +8976,12 @@ async function runMidSessionCardReaper(): Promise<void> {
   //    the durable store row clear together.
   if (WORKER_PIN_REAPER_ENABLED && PIN_STATUS_WHILE_WORKING) {
     try {
-      const inMemoryKeys = new Set(
-        [...statusPinState.keys()].filter((k) => k.startsWith('wk:')),
-      )
-      const inMemoryCandidates = [...inMemoryKeys].map((k) => ({
-        pinKey: k,
-        chatId: statusPinChatIds.get(k) ?? '',
-        // A missing timestamp (should not happen — set on every claim)
-        // degrades to "claimed just now": terminality can still reap it,
-        // the TTL gate never can. Conservative, never a spurious unpin.
-        pinnedAt: statusPinPinnedAt.get(k) ?? now,
-      }))
+      // One record per claim (#3809): chatId and pinnedAt are fields of the
+      // claim, so neither can go missing and strand the key as unreapable.
+      const inMemoryCandidates = [...statusPinClaims.entries()]
+        .filter(([k]) => k.startsWith('wk:'))
+        .map(([pinKey, claim]) => ({ pinKey, chatId: claim.chatId, pinnedAt: claim.pinnedAt }))
+      const inMemoryKeys = new Set(inMemoryCandidates.map((c) => c.pinKey))
       // #3001 durable group net: fold in `wk:` rows that live in the DURABLE
       // store but have NO in-memory claim — the divergence window where the
       // claim was lost but the Telegram pin + store row survive. These would
@@ -9012,8 +9008,11 @@ async function runMidSessionCardReaper(): Promise<void> {
           // missed unpin → 'terminal' (reap now). The feed's own group-empty
           // unpin is the primary path; this is the missed-unpin backstop.
           if (agentId.startsWith('group:')) {
-            const feedKey = agentId.slice('group:'.length)
-            return workerActivityFeed?.hasRunningInFeed(feedKey) ? 'running' : 'terminal'
+            // groupPinStatus distinguishes "no feed to ask" (→ 'unknown', TTL
+            // only) from "the feed says this group is done" (→ 'terminal',
+            // reap now). The `?.` shorthand conflated them and could unpin a
+            // LIVE group pin during a feed-null window (#3811).
+            return groupPinStatus(workerActivityFeed, agentId.slice('group:'.length))
           }
           if (turnsDb == null) return 'unknown'
           try {
@@ -9044,7 +9043,7 @@ async function runMidSessionCardReaper(): Promise<void> {
           // are best-effort/idempotent; a failed unpin still drops the row so
           // the next boot's cleanup is the final backstop.
           try {
-            await statusPinApi().unpinChatMessage(reap.chatId, reap.messageId)
+            await statusPinApi().unpinChatMessage(reap.chatId, reap.messageId) // allow-raw-pin: store-orphan reap — by definition there is NO in-memory claim, so this unpins the exact tracked message id (group-safe, never unpin-all).
           } catch (err) {
             process.stderr.write(
               `telegram gateway: worker-pin reaper store-orphan unpin failed ` +
@@ -9052,7 +9051,7 @@ async function runMidSessionCardReaper(): Promise<void> {
                 `${(err as Error).message}\n`,
             )
           }
-          await mutateStatusPinRow(
+          await mutateStatusPinRow( // allow-raw-pin-store: drops the row for the store orphan unpinned immediately above; there is no claim to reconcile.
             STATUS_PIN_STORE_PATH,
             statusPinStoreFs,
             reap.pinKey,
@@ -9142,14 +9141,15 @@ async function reconcileStatusPinInner(
   // settled — always the true current claim. Closes the stale-`prev` race (a
   // turn-end clear dropping the disk row under a flood-delayed open-pin) and the
   // older duplicate-pin concern (two edits both reading prev=null).
-  const prev = statusPinState.get(pinKey) ?? null
+  const claim = statusPinClaims.get(pinKey)
+  const prev: PinState | null = claim == null ? null : { messageId: claim.messageId }
 
-  const runReconcileFrom = (from: PinState | null, want: DesiredPin) =>
-    reconcilePin({
+  const runReconcileFrom = (action: PinLegAction, from: PinState | null) =>
+    executePinLeg({
       api: statusPinApi(),
       chatId,
       prevState: from,
-      desired: want,
+      action,
       rightsCache: statusPinRightsCache,
       onPinRightsDisabled: (chat) => {
         // Logged ONCE per chat per process (#3024). Every subsequent auto-pin
@@ -9179,11 +9179,7 @@ async function reconcileStatusPinInner(
       ? { path: STATUS_PIN_STORE_PATH, fs: statusPinStoreFs }
       : null,
     runPin: runReconcileFrom,
-    registries: {
-      state: statusPinState,
-      chatIds: statusPinChatIds,
-      pinnedAt: statusPinPinnedAt,
-    },
+    claims: statusPinClaims,
   })
 }
 
@@ -9200,14 +9196,10 @@ async function reconcileStatusPinInner(
  *  crash / interrupt never leaves a permanent pin behind. Best-effort;
  *  clears the claim regardless of the unpin outcome (drop-on-unpin). */
 async function unpinAllStatusPins(): Promise<void> {
-  const keys = [...statusPinState.keys()]
-  for (const key of keys) {
-    const st = statusPinState.get(key)
-    if (st == null) continue
-    // Recover the chat id from the state map's companion key registry.
-    const chatId = statusPinChatIds.get(key)
-    if (chatId == null) { statusPinState.delete(key); statusPinPinnedAt.delete(key); continue }
-    await reconcileStatusPin(key, chatId, { pinned: false })
+  // The chat id is a FIELD of the claim (#3809), so every claim is unpinnable —
+  // there is no "claim we know about but cannot address" branch to fall through.
+  for (const [key, claim] of [...statusPinClaims.entries()]) {
+    await reconcileStatusPin(key, claim.chatId, { pinned: false })
   }
 }
 
@@ -9226,14 +9218,14 @@ async function unpinAllStatusPins(): Promise<void> {
 let dmPinSweepEligible = false
 const dmPinSweeper: DmPinSweeper = createDmPinSweeper({
   unpinAll: (chatId) =>
-    robustApiCall(() => lockedBot.api.unpinAllChatMessages(chatId), {
+    robustApiCall(() => lockedBot.api.unpinAllChatMessages(chatId), { // allow-raw-pin: DM-only boot sweep — clears pins this process cannot enumerate (pre-restart orphans) and immediately re-pins the live tracked ids below.
       chat_id: chatId,
       verb: 'dm-pin-sweep.unpin-all',
     }),
   pinSilent: (chatId, messageId) =>
     robustApiCall(
       () =>
-        lockedBot.api.pinChatMessage(chatId, messageId, {
+        lockedBot.api.pinChatMessage(chatId, messageId, { // allow-raw-pin: the re-pin half of the DM boot sweep — restores ids the sweep just cleared; the claims themselves are untouched.
           disable_notification: true,
         }),
       { chat_id: chatId, verb: 'dm-pin-sweep.repin' },
@@ -9248,8 +9240,8 @@ const dmPinSweeper: DmPinSweeper = createDmPinSweeper({
   // degrades to in-memory-only. The sweeper dedupes.
   liveTrackedMessageIds: (chatId) => {
     const ids: number[] = []
-    for (const [key, st] of statusPinState.entries()) {
-      if (statusPinChatIds.get(key) === chatId) ids.push(st.messageId)
+    for (const claim of statusPinClaims.values()) {
+      if (claim.chatId === chatId) ids.push(claim.messageId)
     }
     if (statusPinPersistEnabled || bannerPinPersistEnabled || toolPinPersistEnabled) {
       try {
@@ -13341,7 +13333,7 @@ async function executePinMessage(args: Record<string, unknown>): Promise<unknown
   // failure the agent should see.
   const pinMsgId = Number(args.message_id)
   await robustApiCall(
-    () => lockedBot.api.pinChatMessage(pinChatId, pinMsgId),
+    () => lockedBot.api.pinChatMessage(pinChatId, pinMsgId), // allow-raw-pin: MCP `pin_message` tool — an explicit, agent-requested pin of an arbitrary message, not a progress surface with a claim.
     { chat_id: pinChatId, verb: 'pin_message' },
   )
   // An explicit pin succeeded here, so the bot demonstrably HAS pin rights in
@@ -13358,7 +13350,7 @@ async function executePinMessage(args: Record<string, unknown>): Promise<unknown
   // failure must never fail the tool call the pin already landed for.
   if (toolPinPersistEnabled) {
     const toolPinKey = `tool:${pinChatId}:${pinMsgId}`
-    void mutateStatusPinRow(STATUS_PIN_STORE_PATH, statusPinStoreFs, toolPinKey, {
+    void mutateStatusPinRow(STATUS_PIN_STORE_PATH, statusPinStoreFs, toolPinKey, { // allow-raw-pin-store: records the TTL-scoped `tool:` row for the explicit pin above so the boot sweep can expire it.
       pinKey: toolPinKey,
       chatId: pinChatId,
       messageId: pinMsgId,
@@ -14016,7 +14008,13 @@ function surfaceConsolidationLegibility(
   })
 }
 
+/** Blocked-paid-dependency alerting — policy in `mcp-credential-failure.ts`,
+ *  seam in `gateway/mcp-failure-hook.ts`. Tees the SAME
+ *  `emitGatewayOperatorEvent` path so there is ONE operator-alert mechanism. */
+const noteMcpDependencyFailure = createMcpFailureHook({ agent: AGENT_NAME, emit: emitGatewayOperatorEvent })
+
 function handleSessionEvent(ev: SessionEvent): void {
+  noteMcpDependencyFailure(ev)
   handleSessionEventCore(gatewayStreamRenderDeps(), ev)
 }
 
@@ -21957,7 +21955,7 @@ bot.on('callback_query:data', async ctx => {
     // ALREADY dispatched above (independently of this host round-trip)
     // so the turn never blocked — finalizeCallback here only edits the
     // card; no synthInbound (would double-fire the verdict).
-    await finalizeCallback(ctx, {
+    await finalizeCallback(ctx, { apiCall: robustApiCall,
       ackText: 'Rule applied for this session; saving durably in background…'.slice(0, 200),
       newText: baseText ? `${baseText}\n\n${interimLabel}` : interimLabel,
     })
@@ -22269,7 +22267,7 @@ bot.on('callback_query:data', async ctx => {
   // decision. Operator could re-tap and flip Deny → Allow after the
   // permission was already broadcast. Routing through finalizeCallback
   // strips the keyboard atomically with the status-line edit.
-  await finalizeCallback(ctx, {
+  await finalizeCallback(ctx, { apiCall: robustApiCall,
     ackText: ackText.slice(0, 200),
     newText: baseText ? `${baseText}\n\n${labelWithResume}` : labelWithResume,
     synthInbound: () => {
@@ -22349,8 +22347,7 @@ const voiceHandlerDeps: VoiceHandlerDeps = {
 // site (check-bot-api-wrapping stays satisfied — the raw call remains in
 // gateway.ts, already inside the retry policy).
 const pinnedMessageHandlerDeps: PinnedMessageHandlerDeps = {
-  statusPinState,
-  statusPinChatIds,
+  statusPinClaims,
   deleteServiceMessage: (chatId, serviceMsgId) =>
     robustApiCall(
       () => lockedBot.api.deleteMessage(chatId, serviceMsgId),
@@ -22965,8 +22962,8 @@ async function initGatewayBot(): Promise<void> {
   // outbound call can bypass (grammY has no route to the network that skips the
   // transformer stack). Kill-switch SWITCHROOM_EDIT_FUSE=0; see edit-flood-fuse.ts.
   installEditFloodFuse(bot, {
-    enabled: process.env.SWITCHROOM_EDIT_FUSE !== '0',
-    onTrip: (i) => process.stderr.write(`edit-flood-fuse ${i.action} method=${i.method} key=${i.key}\n`),
+    ...editFloodFuseConfigFromEnv(process.env),
+    onTrip: (i) => process.stderr.write(`edit-flood-fuse ${i.action} method=${i.method} key=${i.key} class=${i.cls}\n`),
   })
 
   // Diagnostic update tap (#3300): one compact line per received update, logged
@@ -23986,7 +23983,7 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                   )
                   return sent as { message_id: number }
                 },
-                editMessageText: (cid, mid, text, editOpts) =>
+                editMessageText: (cid, mid, text, editOpts, editMeta) =>
                   robustApiCall(
                     () =>
                       lockedBot.api.editMessageText(
@@ -23995,12 +23992,12 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                         richMessage(text),
                         editOpts as Parameters<typeof lockedBot.api.editMessageText>[3],
                       ),
-                    // Worker-feed EDITs are COSMETIC — pass messageId/editPayload
-                    // so the per-message floor + coalescing + no-op skip engage.
+                    // Repaints COSMETIC, terminal frame USEFUL (#3848); messageId/
+                    // editPayload engage the floor + coalescing + no-op skip.
                     {
                       chat_id: cid,
                       verb: 'worker-feed',
-                      priorityClass: 'cosmetic',
+                      priorityClass: workerFeedEditPriorityClass(editMeta),
                       messageId: mid,
                       editPayload: text,
                     },
@@ -24058,7 +24055,7 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 if (messageId != null) {
                   void reconcileStatusPin(key, chatId, { pinned: true, messageId })
                 } else {
-                  const unpinChat = chatId || statusPinChatIds.get(key)
+                  const unpinChat = chatId || statusPinClaims.get(key)?.chatId
                   if (unpinChat != null && unpinChat.length > 0) {
                     void reconcileStatusPin(key, unpinChat, { pinned: false })
                   }

package/telegram-plugin/gateway/mcp-failure-hook.ts

@@ -0,0 +1,74 @@
+/**
+ * mcp-failure-hook.ts — the gateway-side wiring that turns a blocked PAID MCP
+ * DEPENDENCY into an operator alert.
+ *
+ * Ken: "If perplexity fails for any agent we should have hard warning via
+ * message here per other failures."
+ *
+ * MCP providers (Perplexity, Eraser, Brevo, Postiz, Meta/Google Ads,
+ * Cloudflare) never touch LiteLLM, so the operator-event path that catches an
+ * OpenRouter 402 never sees them — an expired Perplexity key would otherwise
+ * die as a transient red step in the live feed and nobody would learn the fleet
+ * had lost a paid capability.
+ *
+ * This tees the SAME `emitGatewayOperatorEvent` path (redact → per-kind
+ * cooldown → operator-only audience via `OPERATOR_ACTIONABLE_KINDS` → brief
+ * user notice), so there is ONE operator-alert mechanism in switchroom, not
+ * two. All the policy — what counts as a key problem, what stays silent, the
+ * 6-hour re-notify cadence — lives in `../mcp-credential-failure.ts`; this file
+ * is only the seam.
+ *
+ * Extracted from `gateway.ts` rather than inlined there, per the
+ * switchroom#2996 anti-inflation ratchet (`scripts/check-gateway-line-ratchet.mjs`).
+ */
+
+import type { SessionEvent } from '../session-tail.js'
+import type { OperatorEvent } from '../operator-events.js'
+import { McpFailureWatcher, renderMcpFailureDetail } from '../mcp-credential-failure.js'
+
+export interface McpFailureHookDeps {
+  agent: string
+  emit: (event: OperatorEvent) => void
+  now?: () => number
+}
+
+/**
+ * Build the `handleSessionEvent` side-hook. One watcher per gateway process,
+ * captured in the closure.
+ *
+ * Silent by default: only a credit/credential/quota class raises anything, and
+ * only once per (server, class) per re-notify window. A bad query, a 404, a
+ * timeout, a transient 429 or a successful call all return without emitting.
+ *
+ * Never throws — alerting is a side channel and must not break the live feed.
+ */
+export function createMcpFailureHook(deps: McpFailureHookDeps): (ev: SessionEvent) => void {
+  const watcher = new McpFailureWatcher()
+  const clock = deps.now ?? (() => Date.now())
+  return function noteMcpDependencyFailure(ev: SessionEvent): void {
+    try {
+      if (ev.kind === 'tool_use') {
+        watcher.onToolUse(ev.toolUseId, ev.toolName)
+        return
+      }
+      if (ev.kind !== 'tool_result') return
+      const alert = watcher.onToolResult({
+        toolUseId: ev.toolUseId,
+        isError: ev.isError,
+        errorText: ev.errorText,
+        agent: deps.agent,
+        now: clock(),
+      })
+      if (alert == null) return
+      deps.emit({
+        kind: 'mcp-dependency-blocked',
+        agent: deps.agent,
+        detail: renderMcpFailureDetail(alert),
+        suggestedActions: [],
+        firstSeenAt: new Date(clock()),
+      })
+    } catch {
+      // Side channel — never let alerting break the live feed.
+    }
+  }
+}

package/telegram-plugin/gateway/narrative-lane.ts

@@ -838,6 +838,20 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
           id,
         )
       }
+      // #3812 — release the status-pin claim BEFORE the message goes away,
+      // symmetric with the durable card-record drop above. `turn-end.ts` also
+      // unpins `fg:<statusKey>`, but that runs LATER: on the
+      // CLEAR_STATUS_ON_COMPLETION path the message is DELETED here, so by turn
+      // end the claim named a dead id and the unpin was a guaranteed-4xx API
+      // call every single turn. Worse, the durable status-pins.json row pointed
+      // at a deleted message for that whole window, so a crash there handed the
+      // next boot's sweep a row it would also fail to unpin — burning an
+      // attempt off the BOOT_UNPIN_MAX_ATTEMPTS forfeit ladder for nothing.
+      //
+      // AWAITED so the unpin (and its durable-row clear) is ordered strictly
+      // before the delete. turn-end stays the idempotent backstop: it no-ops
+      // once nothing is claimed for the key.
+      await reconcileStatusPin(`fg:${statusKey(chat, thread)}`, chat, { pinned: false })
       if (CLEAR_STATUS_ON_COMPLETION) {
         try {
           await robustApiCall(