switchroom 0.19.25 → 0.19.27

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,9 +195,9 @@ 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 { decidePinAction, PinRightsCache } 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'
 import {
@@ -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'
@@ -637,6 +637,9 @@ 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, 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'
 import {
   createDmPinSweeper,
@@ -666,11 +669,9 @@ import { buildCapturedDeliverySnapshot, createCapturedResumeDispatcher } from '.
 import {
   loadStatusPins,
   mutateStatusPinRow,
-  reconcileAndPersistStatusPin,
   runStatusPinBootCleanup,
   withPinReconcileLock,
   type PersistedStatusPin,
-  type StatusPinPersistOp,
 } from './status-pin-store.js'
 import {
   loadActivityCards,
@@ -690,6 +691,7 @@ import {
 } from './queued-card-store.js'
 import {
   decideWorkerPinReaps,
+  groupPinStatus,
   storeOnlyWorkerPinCandidates,
   WORKER_PIN_TTL_MS_DEFAULT,
 } from './worker-pin-reaper.js'
@@ -5864,7 +5866,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
@@ -5874,7 +5876,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)
@@ -8523,19 +8525,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
@@ -8659,7 +8660,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,
@@ -8699,7 +8700,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(
@@ -8762,7 +8763,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 } : {}),
@@ -8941,12 +8942,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 } : {}),
@@ -8974,17 +8975,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
@@ -9011,8 +9007,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 {
@@ -9043,7 +9042,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 ` +
@@ -9051,7 +9050,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,
@@ -9069,8 +9068,20 @@ async function runMidSessionCardReaper(): Promise<void> {
   }
 }
 
+// Single-flight: a pass awaits Telegram calls that can park behind a flood-wait
+// for longer than the interval, so ticks fanned out. See periodic-sweep-guard.ts.
+const midSessionReaperGuard = createPeriodicSweepGuard({
+  run: runMidSessionCardReaper,
+  onSkip: () => process.stderr.write(
+    'telegram gateway: mid-session reaper tick skipped — previous pass still running\n',
+  ),
+  onError: (err) => process.stderr.write(
+    `telegram gateway: mid-session reaper pass threw: ${(err as Error).message}\n`,
+  ),
+})
+
 const midSessionCardReaper = isGatewayMain ? setInterval(() => {  // #2996 P0c gate
-  void runMidSessionCardReaper()
+  void midSessionReaperGuard.tick()
 }, MID_SESSION_CARD_REAPER_INTERVAL_MS) : undefined
 midSessionCardReaper?.unref()
 
@@ -9129,14 +9140,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 runReconcile = () =>
-    reconcilePin({
+  const runReconcileFrom = (action: PinLegAction, from: PinState | null) =>
+    executePinLeg({
       api: statusPinApi(),
       chatId,
-      prevState: prev,
-      desired,
+      prevState: from,
+      action,
       rightsCache: statusPinRightsCache,
       onPinRightsDisabled: (chat) => {
         // Logged ONCE per chat per process (#3024). Every subsequent auto-pin
@@ -9155,53 +9167,19 @@ async function reconcileStatusPinInner(
       },
     })
 
-  // Classify the action so we persist INTENT before the pin API call. Only a
-  // fresh `pin` of a message that isn't already our claim opens the leak window
-  // (the API call actually pins something new); everything else (unpin, noop,
-  // re-pin of the same id) clears / leaves the record and is safe to persist
-  // after. See reconcileAndPersistStatusPin for the ordering rationale.
-  const action = decidePinAction(prev, desired)
-  const op: StatusPinPersistOp =
-    action.kind === 'pin'
-      ? { kind: 'pin', messageId: action.messageId }
-      : { kind: 'clear' }
-
-  if (!statusPinPersistEnabled) {
-    // Persistence off (STATIC / feature-off): just reconcile + update Maps.
-    const next = await runReconcile()
-    if (next == null) {
-      statusPinState.delete(pinKey)
-      statusPinChatIds.delete(pinKey)
-      statusPinPinnedAt.delete(pinKey)
-    } else {
-      statusPinState.set(pinKey, next)
-      statusPinChatIds.set(pinKey, chatId)
-      if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
-    }
-    return
-  }
-
-  // Persist-BEFORE-pin ordering lives in reconcileAndPersistStatusPin: for a
-  // pin it writes a `pending` record first, then confirms it after the API call
-  // lands (or drops it on failure). A crash in the window leaves a pending
-  // record boot cleanup will unpin. In-memory Maps are updated from the result.
-  const next = await reconcileAndPersistStatusPin({
-    path: STATUS_PIN_STORE_PATH,
-    fs: statusPinStoreFs,
+  // Persist ordering + the RETARGET two-leg expansion: status-pin-retarget.ts.
+  await runStatusPinReconcile({
     pinKey,
     chatId,
-    op,
-    applyPin: runReconcile,
+    prev,
+    desired,
+    // persist:null ⇒ no durable row (STATIC / feature-off).
+    persist: statusPinPersistEnabled
+      ? { path: STATUS_PIN_STORE_PATH, fs: statusPinStoreFs }
+      : null,
+    runPin: runReconcileFrom,
+    claims: statusPinClaims,
   })
-  if (next == null) {
-    statusPinState.delete(pinKey)
-    statusPinChatIds.delete(pinKey)
-    statusPinPinnedAt.delete(pinKey)
-  } else {
-    statusPinState.set(pinKey, next)
-    statusPinChatIds.set(pinKey, chatId)
-    if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
-  }
 }
 
 // #3207: the per-worker `reconcileWorkerPin(agentId, …)` (keyed `wk:<agentId>`)
@@ -9217,14 +9195,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 })
   }
 }
 
@@ -9243,14 +9217,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' },
@@ -9265,8 +9239,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 {
@@ -13358,7 +13332,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
@@ -13375,7 +13349,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,
@@ -18053,7 +18027,7 @@ function broadcastTierNotice(markdown: string): void {
  *     the user must re-issue `/model <premium>`, which the notice says plainly.
  *   - Effort is NATIVE: no `.session-effort` carrier is written, so the restart
  *     sheds any live /effort override and the downgraded default boots at the
- *     configured `thinking_effort` (the fleet `low` pin, #1978).
+ *     configured `thinking_effort` (#1978 / thinking-effort-risk.ts).
  *   - Loop-bounded by the NATURAL on-default guard: after the downgrade boot the
  *     session runs the configured default (override gone), so a re-entry returns
  *     `skip` ('on-default') and never re-downgrades — even if the default is
@@ -22366,8 +22340,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),
@@ -22750,6 +22723,24 @@ async function shutdown(signal: string): Promise<void> {
     agentName,
   })
 
+  // Status-pin: unpin everything we own before we exit. `sweepBeforeSelfRestart`
+  // covered the gateway's OWN restart verbs, but SIGTERM/SIGINT — `docker
+  // restart`, a compose bounce, a host reboot: the common path — reached
+  // `process.exit(0)` with every live pin still pinned, leaving it at the top of
+  // the chat until the NEXT boot's cleanup won the mutex and built a bot
+  // (empirically: overlord logged `cleared 1/1 orphaned pin(s) from a prior
+  // session` on a routine 2026-07-27 restart). Runs after the drain (no live
+  // turn to race) and before `bot.api` goes away — `bot.stop()` only stops
+  // polling. Deadline-bounded on purpose: a flood-wait-parked unpin must not
+  // push shutdown into the `forceExitTimer` path, which skips the lock release.
+  try {
+    await withDeadline(unpinAllStatusPins(), 5_000, 'status-pin shutdown sweep timed out')
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: shutdown status-pin sweep incomplete: ${(err as Error).message}\n`,
+    )
+  }
+
   // Now finish the cleanup the drain didn't touch.
   inboundCoalescer.reset()
   pendingReauthFlows.clear()
@@ -22964,8 +22955,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
@@ -23985,7 +23976,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(
@@ -23994,12 +23985,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,
                     },
@@ -24057,7 +24048,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/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(