switchroom 0.18.11 → 0.18.13

package/telegram-plugin/gateway/gateway.ts

@@ -34,6 +34,7 @@ import {
   type AskUserArgs,
   type AskUserOutcome,
 } from '../ask-user.js'
+import { redactAskUserFields, redactChecklistFields } from '../outbound-field-redact.js'
 import { parseInterruptMarker } from '../interrupt-marker.js'
 import {
   ToolFlightTracker,
@@ -112,7 +113,7 @@ import {
 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 } from '../status-pin.js'
+import { decidePinAction, PinRightsCache } from '../status-pin.js'
 import { formatTurnLifecycle, detectStatusSurfaceDegraded } from './status-surface-log.js'
 import { parseSourceMessageId } from './source-message-id.js'
 import {
@@ -155,6 +156,7 @@ import {
   computeBootSweepStripTargets,
   distinctRequestIds,
 } from './permission-rearm.js'
+import { sweepPermissionTtl } from './permission-ttl-sweep.js'
 import { createMissedApprovalsStore, type MissedApproval } from './missed-approvals-store.js'
 import {
   createAlwaysAllowPersistQueue,
@@ -168,6 +170,15 @@ import {
   buildMissedApprovalRetryInbound,
 } from './missed-approvals-card.js'
 import { pickRecoveredPermissionOrigin } from './permission-card-origin.js'
+import {
+  createBlockedApprovalStore,
+  safeActionForRecord,
+  selectOldestHeld,
+  selectHeldForRedelivery,
+  holdReasonFor,
+  heldRetryBackoffMs,
+  type UndeliverableMark,
+} from './approval-hold.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { appendActivityLabel, clipNarrative, renderActivityFeedWithNested, formatStepSuffix, type SessionActivityHeader } from '../tool-activity-summary.js'
 import { formatModelLabel } from '../model-label.js'
@@ -177,6 +188,7 @@ import { REPLY_TOOLS, isDraftOfReply } from '../narrative-dedup.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { createTurnTypingLoop } from './turn-typing-loop.js'
+import { createTypingEmitter, TYPING_REFRESH_MS } from '../typing-emitter.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
 import { handlePtyPartialPure, type PtyHandlerState } from '../pty-partial-handler.js'
 import { handleStreamReply } from '../stream-reply-handler.js'
@@ -186,10 +198,23 @@ import {
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
   isPhotoDimensionRejectError,
+  isFloodWaitActiveError,
 } from '../retry-api-call.js'
+import { createSendGate, sendGateEnabledFromEnv } from '../send-gate.js'
+import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
 import { classifyPhotoFile, rerouteResultSuffix } from '../photo-precheck.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
-import { floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
+import {
+  floodStatePath,
+  floodWindowsPath,
+  makeFloodWaitRecorder,
+  makeFloodWaitProbe,
+  makeFloodWindowRecorder,
+  loadInitialFloodWindows,
+  readFloodWindows,
+  markFloodWindowAlerted,
+  suppressNonEssentialSendMs,
+} from '../flood-circuit-breaker.js'
 import { buildAttachmentPath, assertInsideInbox } from '../attachment-path.js'
 import { logStreamingEvent } from '../streaming-metrics.js'
 import * as signalTracker from '../turn-signal-tracker.js'
@@ -253,6 +278,14 @@ import {
   cancelAccountAuthSession,
   cleanScratchDir as cleanAuthAddScratchDir,
 } from './auth-add-flow.js'
+import {
+  pendingLoopbackFlows,
+  startLoopbackFlow,
+  submitLoopbackRedirect,
+  cancelLoopbackFlow,
+  shouldConsumeLoopbackPaste,
+  trackFlowExit,
+} from './auth-loopback-relay.js'
 import {
   initHistory, recordInbound, recordOutbound, recordEdit,
   deleteFromHistory, query as queryHistory, getLatestInboundMessageId,
@@ -308,10 +341,13 @@ import {
 } from '../telegram-button-constraints.js'
 import {
   wrapAgentCallbacks,
+  redactAgentKeyboard,
   parseAgentCallback,
   extractAgentButtonMeta,
   keyboardIsSingleUse,
   finalizeCallback,
+  resolveTapAnnotation,
+  applyTapAnnotationEdit,
   type AgentButtonMeta,
 } from '../inline-keyboard-callbacks.js'
 import {
@@ -340,6 +376,8 @@ import {
   decideTurnFlush,
   isTurnFlushSafetyEnabled,
 } from '../turn-flush-safety.js'
+// #1667 — pure decision core for the turn_end answer-delivery gate (#1664).
+import { decideTurnEndGate } from './turn-end-gate.js'
 // #1122 PR3: turn-flush-prose-recovery removed with the progress card.
 import { resolveAgentDirFromEnv } from '../agent-dir.js'
 import {
@@ -408,6 +446,7 @@ import {
   readSessionModelFileRaw,
   restoreSessionModelFileRaw,
   clearSessionModelFile,
+  clearSessionModelBootAttempts,
   readConfiguredDefaultModel,
   writeRelaunchModelIntent,
   clearRelaunchModelIntent,
@@ -453,7 +492,7 @@ import { resolveOutboundTopic as resolveOutboundTopicHelper, topicForRecipient,
 import { readTurnUsages } from '../../src/agents/perf.js'
 import { buildContextOccupancy, writeContextOccupancySnapshot } from './context-occupancy.js'
 import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
-import { decideIdleClear, idleDurationToMs, DEFAULT_IDLE_CLEAR_MS } from './idle-clear.js'
+import { decideIdleClear, classifyIdleEvent, idleDurationToMs, DEFAULT_IDLE_CLEAR_MS } from './idle-clear.js'
 import { nextCompactNotify, idleCompactNotifyState, type CompactNotifyState } from './compact-notify.js'
 import {
   tryHostdDispatch,
@@ -463,12 +502,19 @@ import {
   pollHostdStatus,
   hostdGetStatusOnce,
   warnLegacySpawnIfHostdDisabled,
+  withOperatorAttestation,
   _resetHostdEnabledCache,
 } from './hostd-dispatch.js'
 import { formatUpdateStatusLine } from './update-status-line.js'
 import type { HostdRequest, HostdResponse } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
+import {
+  createDmPinSweeper,
+  collectDmChatIdsFromStores,
+  unexpiredStoreRepinIds,
+  type DmPinSweeper,
+} from './dm-pin-sweep.js'
 import { startWebhookIngestServer } from './webhook-ingest-server.js'
 import { recordWebhookEvent } from '../../src/web/webhook-gateway-record.js'
 
@@ -495,6 +541,7 @@ import {
   type TrackedStatusPin,
 } from './status-pin-store.js'
 import {
+  loadActivityCards,
   writeActivityCardRecord,
   clearActivityCardRecord,
   runActivityCardBootReaper,
@@ -502,6 +549,13 @@ import {
   restartOrphanCardFinalizeText,
   type ActivityCardStoreFsSeam,
 } from './activity-card-store.js'
+import {
+  loadQueuedCards,
+  writeQueuedCardRecord,
+  clearQueuedCardRecord,
+  runQueuedCardBootReaper,
+  type QueuedCardStoreFsSeam,
+} from './queued-card-store.js'
 import {
   decideWorkerPinReaps,
   WORKER_PIN_TTL_MS_DEFAULT,
@@ -511,6 +565,7 @@ import { shouldSuppressRepresent } from './represent-guard.js'
 import { shouldDeferEscalationForBridge } from './escalation-bridge-gate.js'
 import { createInboundSpool } from './inbound-spool.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
+import { withTurnEndGateBackstop } from './turn-end-gate-backstop.js'
 import { decideInboundDelivery, reserveInboundDelivery } from './inbound-delivery-gate.js'
 import { mayDrainBufferedInbound, shouldArmNoReplyDrain } from './serialize-drain-gate.js'
 import { decideFeedReopen } from './feed-reopen-gate.js'
@@ -589,6 +644,7 @@ import type {
   SendOutboundMessage,
   QuotaWallDetectedMessage,
   QueryPendingPermissionMessage,
+  CheckPreApprovedMessage,
   PostSkillProposalMessage,
   PermissionEvent,
   RolloutStatusPostMessage,
@@ -637,8 +693,8 @@ import {
   startSubagentWatcher,
   type SubagentWatcherHandle,
 } from '../subagent-watcher.js'
-import { listRecords as listWorktreeRecords } from '../../src/worktree/registry.js'
-import { ownedWorktreeCwds } from '../worktree-watch-cwds.js'
+import { listRecords as listWorktreeRecords, touchHeartbeat as touchWorktreeHeartbeat } from '../../src/worktree/registry.js'
+import { makeWorktreeWatchProvider } from '../worktree-watch-cwds.js'
 import {
   startBootCard,
   resolvePersonaName,
@@ -664,6 +720,7 @@ import {
 import { createScopedGrantStore } from './scoped-grant-store.js'
 import { grantRestartDecision, type GrantRestartDecision } from './grant-restart.js'
 import { synthesizeAllowRuleDiff, extractAddedAllowRule } from '../permission-diff.js'
+import { isDiffPreApproved } from './pre-approval-check.js'
 import {
   readClaudeJsonOverage,
   evaluateCreditState,
@@ -790,6 +847,69 @@ process.on('beforeExit', () => {
 // ─── Env + state dir ──────────────────────────────────────────────────────
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const permCardStore = createPermissionCardStore(STATE_DIR)
+// #3084 follow-up — the blocked-approval surface. A SHARED top-level directory
+// (compose binds host `~/.switchroom/blocked-approvals` here), not per-agent
+// state: switchroom-web reads every agent's record from one place, and the
+// records are 0644 so its uid-1000 process can actually read them. The agent's
+// own telegram state is 0600 and is NOT web-readable.
+// If the mount is missing (a container predating the volume), the write lands
+// inside the container and the hold still works — only the off-Telegram
+// SURFACE is lost. The record is best-effort by construction; it must never be
+// able to fail the hold back into an auto-deny.
+const BLOCKED_APPROVALS_DIR =
+  process.env.SWITCHROOM_BLOCKED_APPROVALS_DIR ?? '/state/blocked-approvals'
+// The canonical "which agent am I" identity (profiles/_base/start.sh.hbs:430).
+const AGENT_NAME = process.env.SWITCHROOM_AGENT_NAME ?? 'agent'
+const blockedApprovalStore = createBlockedApprovalStore(
+  BLOCKED_APPROVALS_DIR,
+  AGENT_NAME,
+  // Fallback: the agent's OWN state dir, which the scaffold chowns to the agent
+  // uid, so a write there always succeeds. Guarantees the record can never be
+  // silently lost when the shared dir isn't writable by this agent's uid.
+  process.env.SWITCHROOM_AGENT_STATE_DIR ?? '/state/agent',
+)
+
+/**
+ * Rewrite the blocked-approval surface from the LIVE pending state.
+ *
+ * A reconcile, not a delete — deliberately. The store holds one record per
+ * agent, but an agent can hold SEVERAL permissions at once: Claude Code issues
+ * parallel tool calls, each hitting `canUseTool`, and
+ * `cancelPendingPermissionsForHalt` iterates multiple pendings. A naive
+ * `clear()` on any single resolution would delete the file while ANOTHER
+ * request was still held, blinding the operator to a real, live block.
+ *
+ * So derive the record from whatever is still held. Oldest block wins — it has
+ * been waiting longest. Nothing held → clear.
+ *
+ * Also called at BOOT. `pendingPermissions` is in-memory and empty on a fresh
+ * process, so this clears any record orphaned by a restart mid-hold — otherwise
+ * the dashboard would show a permanently blocked agent forever. Nothing can
+ * legitimately be held across a restart: the bridge re-sends unresolved requests
+ * on IPC reconnect (`bridge/permission-ledger.ts`), which re-raises them and
+ * re-marks them if the channel is still shut.
+ */
+function reconcileBlockedApprovals(): void {
+  // Selection (oldest hold wins; null ⇒ nothing held) is the pure, unit-tested
+  // `selectOldestHeld` in approval-hold.ts — keep policy out of gateway.ts.
+  const oldest = selectOldestHeld(pendingPermissions)
+  if (oldest == null) {
+    blockedApprovalStore.clear()
+    return
+  }
+  blockedApprovalStore.write({
+    agent: AGENT_NAME,
+    requestId: oldest.requestId,
+    toolName: oldest.pend.tool_name,
+    // NOT bare naturalAction(): for Bash/Glob/Grep/WebFetch/mcp__* it
+    // interpolates the RAW tool input, and this file is world-readable.
+    action: safeActionForRecord(naturalAction, oldest.pend.tool_name, oldest.pend.input_preview),
+    blockedSince: oldest.pend.startedAt,
+    undeliverableSince: oldest.mark.since,
+    retryableAt: oldest.mark.retryableAt,
+    reason: oldest.mark.reason,
+  })
+}
 // Durable store for the four AGENT-INITIATED approval-card families
 // (vault_request_access / vault_request_save / request_secret /
 // mental_model_propose). Persists card METADATA only — never any secret value
@@ -1347,6 +1467,17 @@ type Access = {
     short_name?: string
     author_name?: string
   }
+  /** Auto-confirm "✅ You chose: X" annotation on inline_keyboard taps
+   *  (#789). When enabled, tapping an agent-emitted single-use button
+   *  annotates the source message body so the chat surface is
+   *  self-documenting. Off by default; only honored when parseMode is the
+   *  default 'html'. Projected from
+   *  channels.telegram.button_choice_confirmation by scaffold. */
+  button_choice_confirmation?: {
+    enabled?: boolean
+    format?: string
+    timezone?: 'gateway' | 'utc'
+  }
 }
 
 function defaultAccess(): Access {
@@ -1431,6 +1562,8 @@ function readAccessFile(): Access {
       voice_in: parsed.voice_in,
       voice_out: parsed.voice_out,
       telegraph: parsed.telegraph,
+      // #789: button-choice-confirmation config projected by scaffold.
+      button_choice_confirmation: parsed.button_choice_confirmation,
     }
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') return defaultAccess()
@@ -2586,6 +2719,17 @@ function turnInFlightForGate(): boolean {
   // Keeping the gate closed for as long as there is an outstanding approval
   // card prevents that race. The gate reopens when the card is tapped or times
   // out (pendingPermissions.delete in finalizeCallback / TTL sweep).
+  //
+  // #3084 follow-up — ONE case now has no timeout valve: an approval HELD
+  // because its card could not be DELIVERED (a Telegram flood ban) never
+  // expires, by design. The leash may not fabricate a verdict for an ask no
+  // human ever saw, so the entry — and therefore this gate — persists until a
+  // human answers. An agent can consequently buffer normal inbound for the
+  // duration of a channel outage. That is the intended trade: a buffered
+  // message is recoverable, a silently auto-denied approval is not. The escape
+  // hatches are unaffected — /allow, /deny and /pending are grammy command
+  // handlers and do not sit behind this gate — and the block is surfaced
+  // off-Telegram in blocked-approvals/<agent>.json.
   const hasPendingApproval = pendingPermissions.size > 0
   if (!isDeliveryCutoverEnabled()) return claudeBusyKeys.size > 0 || hasPendingApproval
   // Machine is authoritative. Run the log-only drift canary (#2794): the
@@ -3659,6 +3803,9 @@ function postQueuedStatus(chatId: string, bufferedThread: number, inFlightThread
       return
     }
     queuedStatusMsgIds.set(key, { chatId, threadId: bufferedThread, messageId })
+    // #3002: write through to the durable store so a gateway restart before the
+    // in-process reap can still delete this orphaned card on boot.
+    persistQueuedCard(key, chatId, bufferedThread, messageId)
   })()
 }
 
@@ -3695,6 +3842,9 @@ function reapQueuedStatus(chatId: string, thread: number | undefined): void {
   const entry = queuedStatusMsgIds.get(key)
   if (entry == null) return
   queuedStatusMsgIds.delete(key)
+  // #3002: drop the durable row too, scoped to this exact message id (reap-race
+  // guard) so a fresh live card under the same key keeps its own protection.
+  clearQueuedCard(key, entry.messageId)
   void swallowingApiCall(
     () => bot.api.deleteMessage(chatId, entry.messageId),
     { chat_id: chatId, verb: 'queued-status.reap', ...(entry.threadId != null ? { threadId: entry.threadId } : {}) },
@@ -3807,6 +3957,8 @@ function postBusyAck(chatId: string, threadId: number | undefined, text: string)
       return
     }
     queuedStatusMsgIds.set(key, { chatId, threadId: threadId ?? null, messageId })
+    // #3002: write through to the durable store (see postQueuedStatus).
+    persistQueuedCard(key, chatId, threadId ?? null, messageId)
   })()
 }
 
@@ -3981,6 +4133,7 @@ function cancelPendingPermissionsForHalt(origin: string): void {
     void stripCancelledPermissionCards(details.card_text, details.cards)
     pendingPermissions.delete(requestId)
     permCardStore.remove(requestId)
+    reconcileBlockedApprovals()
     process.stderr.write(
       `telegram gateway: halt-now cancelled pending permission origin=${origin} ` +
       `request=${requestId} tool=${details.tool_name}\n`,
@@ -4805,10 +4958,18 @@ function maybeProactiveCompact(): void {
 // ─── Idle auto-clear ──────────────────────────────────────────────────────
 // Wall-clock idle → /clear (idle-clear.ts). Independent of proactive-compact
 // (occupancy-driven at the turn-end gate): a fully-idle agent never ends a
-// turn, so this runs on its own interval. Any activity (inbound / turn start /
-// cron fire) resets the timer via markIdleActivity(); fires once per idle
-// period; never mid-turn (turnInFlightForGate, the same gate compaction uses).
+// turn, so this runs on its own interval. "Idle" means NOTHING HAS HAPPENED
+// since the last thing happened — inbound, cron fire, or ANY claude session
+// event (turn start, tool call, tool result, text, sub-agent event, turn end)
+// resets the timer via markIdleActivity(); a turn ending additionally stamps
+// markIdleTurnEnd(). Fires once per idle period; never mid-turn
+// (turnInFlightForGate, the same gate compaction uses).
+//
+// It is emphatically NOT "no turn has *started* recently" — that reading wiped
+// overlord's 3h of working context on 2026-07-11 for the crime of being busy.
+// See the idle-clear.ts header.
 let lastIdleActivityAt = Date.now();
+let lastIdleTurnEndAt: number | null = null;
 let idleAutoCleared = false;
 let idleClearDispatching = false;
 
@@ -4818,6 +4979,15 @@ function markIdleActivity(): void {
   idleAutoCleared = false;
 }
 
+/**
+ * Stamp "a turn just ended". The idle window is measured from
+ * max(lastActivityAt, lastTurnEndedAt), so a turn that ran LONGER than the
+ * window can't be cleared on the first tick after `turnInFlight` goes false.
+ */
+function markIdleTurnEnd(): void {
+  lastIdleTurnEndAt = Date.now();
+}
+
 /** Idle window in ms: env override → per-agent config → 3h default. 0 disables. */
 function resolveIdleClearMs(): number {
   const env = process.env.SWITCHROOM_IDLE_CLEAR_MS;
@@ -4849,6 +5019,7 @@ function maybeIdleClear(): void {
   const decision = decideIdleClear(
     {
       lastActivityAt: lastIdleActivityAt,
+      lastTurnEndedAt: lastIdleTurnEndAt,
       idleClearMs,
       alreadyCleared: idleAutoCleared,
       turnInFlight: turnInFlightForGate(),
@@ -5275,6 +5446,241 @@ const PHOTO_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp'])
 // The length/newline text splitter moved to outbound-send-path.ts (#2996) as
 // `chunkText`; the sole gateway caller now goes through `computeReplyChunks`.
 
+// ─── Robust API call wrapper ──────────────────────────────────────────────
+// Extracted to telegram-plugin/retry-api-call.ts so it's unit-testable in
+// isolation; the gateway just composes the pure policy with its own logger.
+// #2923: the shared flood-wait marker. Every observed 429 retry_after window
+// is persisted here via onFloodWait, and both boot-card callsites consult the
+// SAME file to suppress a restart card while a per-bot flood ban is open (so a
+// restart doesn't post into the window and extend the ban). Falls back to a
+// no-op recorder when TELEGRAM_STATE_DIR is unset (dev/one-shot contexts).
+// STATE_DIR always resolves (env or a ~/.claude fallback), so this is live.
+// Declared ABOVE the typing indicator because the typing sends now route
+// through the same policy (#3084) — see nonEssentialApiCall below.
+const FLOOD_STATE_PATH = floodStatePath(STATE_DIR)
+// #3084 PR 2/3 — sibling file for SCOPED flood windows (global / chat / group /
+// msg-edit). Kept separate from the single-object flood-wait.json so #3094's
+// makeFloodWaitProbe schema is untouched (part3-design §7).
+const FLOOD_WINDOWS_PATH = floodWindowsPath(STATE_DIR)
+const recordFloodWindow = makeFloodWindowRecorder(FLOOD_WINDOWS_PATH)
+
+// #3084 PR 2/3 — deterministic outbound send gate (token buckets + per-message
+// edit floor + no-op-edit skip + PRIORITY SHEDDING + DEGRADED MODE). Wrapped
+// HERE at the robustApiCall layer so every Bot API call routed through the
+// standard retry policy also transits one scheduler (no call site can bypass
+// it). ON BY DEFAULT (escape hatch): only when SWITCHROOM_TELEGRAM_SEND_GATE is
+// explicitly set to 0/false/off/no is the gate a pure passthrough and the retry
+// policy behaves exactly as before. Composes with #3094's pre-call flood gate
+// and #3097's non-essential
+// drop policy — those decide whether a call happens at all; this paces the
+// calls that do.
+//
+// §7 restart-proof flood state: initialWindows are loaded from disk BEFORE the
+// gate (and thus before ANY outbound call, boot cards included), so a boot mid-
+// ban never resends into an open window. onWindowOpen write-throughs every
+// runtime-opened window to FLOOD_WINDOWS_PATH; bootRamp starts the global
+// bucket at half capacity for 10s to absorb the boot-card burst.
+const sendGate = createSendGate({
+  enabled: sendGateEnabledFromEnv(),
+  initialWindows: loadInitialFloodWindows(FLOOD_STATE_PATH, FLOOD_WINDOWS_PATH, Date.now()),
+  bootRamp: {},
+  onWindowOpen: (scopeKey, untilTs) => recordFloodWindow(scopeKey, untilTs),
+})
+
+// Hoisted so the held-card re-delivery sweep (#3084 follow-up) asks the SAME
+// probe `robustApiCall` does, off the same on-disk window. The sweep's check and
+// the retry policy's own pre-call short-circuit are then two independent reads
+// of one source of truth, not two notions of "is the channel open".
+const probeFloodWaitRemainingMs = makeFloodWaitProbe(FLOOD_STATE_PATH)
+const rawRobustApiCall = createRetryApiCall({
+  log: (line) => process.stderr.write(line),
+  onFloodWait: (retryAfterSec) => {
+    // #2923/#3094 — persist the single-object global window (probe reads this).
+    makeFloodWaitRecorder(FLOOD_STATE_PATH)(retryAfterSec)
+    // #3084 PR 2 — also open a GLOBAL send-gate window so cosmetic traffic sheds
+    // for the ban's duration even on a SHORT (slept-and-retried) 429 that never
+    // throws FLOOD_WAIT_ACTIVE. Scope-precise windows are opened by the gate's
+    // own FLOOD_WAIT_ACTIVE catch (which has the call's opts).
+    try {
+      sendGate.openFloodWindow('global', Date.now() + Math.max(0, retryAfterSec) * 1000)
+    } catch {
+      /* best-effort — never let the window hook break the retry path */
+    }
+  },
+  // #3094: while a LONG per-bot ban is open, don't issue the call at all.
+  // retryApiCall no longer sleeps a multi-hour retry_after (it throws
+  // FLOOD_WAIT_ACTIVE instead), and the card surfaces re-drive on a 5-6s
+  // heartbeat — without this gate that turns the fix into an amplifier that
+  // fires thousands of requests into the open window and extends the ban.
+  floodWaitRemainingMs: probeFloodWaitRemainingMs,
+})
+
+const robustApiCall = <T>(
+  fn: () => Promise<T>,
+  opts?: Parameters<typeof rawRobustApiCall<T>>[1],
+): Promise<T> => sendGate.gate(() => rawRobustApiCall(fn, opts), opts)
+
+// Fire-and-forget wrapper for outbound surfaces that previously had
+// `.catch(() => {})` directly on `bot.api.*` calls. Resolves to undefined
+// (instead of crashing the gateway) on THREAD_NOT_FOUND, give-up, 403,
+// and any non-benign error — logs a one-liner so the failure isn't
+// completely silent. See #1075.
+const swallowingApiCall = createSwallowingRetryApiCall(
+  robustApiCall,
+  (line) => process.stderr.write(line),
+)
+
+/**
+ * The ONE seam every `setMessageReaction` in this gateway goes through (#3155).
+ *
+ * Reactions are cosmetic outbound traffic. Before this seam, ~13 raw
+ * `bot.api.setMessageReaction(...)` / `lockedBot.api.setMessageReaction(...)`
+ * call sites fired reactions OUTSIDE the send gate AND the flood circuit
+ * breaker, so:
+ *
+ *   (a) reaction spam was never PACED/SHED by the gate when it's on — a busy
+ *       turn's status-reaction churn added straight onto the per-bot flood
+ *       budget the REPLIES need; and
+ *   (b) a 429 from a reaction was INVISIBLE to the breaker — the flood window
+ *       is only learned through the retry module's `onFloodWait` hook, which a
+ *       raw `bot.api` call never reaches. Reactions were a residual flood
+ *       vector even with the gate ON.
+ *
+ * Routing through `robustApiCall` (= chat-lock → send-gate → retry/breaker,
+ * the SAME path every other outbound call takes) with
+ * `priorityClass: 'cosmetic'` fixes both: the gate paces/sheds reactions under
+ * pressure, and a 429 runs `onFloodWait` so the window is recorded. Callers
+ * keep their own fire-and-forget / `.catch(() => {})` / `await` semantics —
+ * this returns the promise and does NOT swallow.
+ */
+const gatedSetMessageReaction = (
+  chatId: string,
+  messageId: number,
+  reaction: ReactionTypeEmoji[],
+): Promise<unknown> =>
+  robustApiCall(() => lockedBot.api.setMessageReaction(chatId, messageId, reaction), {
+    chat_id: chatId,
+    verb: 'set-message-reaction',
+    priorityClass: 'cosmetic',
+  })
+
+/** React with a single emoji through the gate (cosmetic). Wraps {@link gatedSetMessageReaction}. */
+const sendReaction = (
+  chatId: string,
+  messageId: number,
+  emoji: ReactionTypeEmoji['emoji'],
+): Promise<unknown> => gatedSetMessageReaction(chatId, messageId, [{ type: 'emoji', emoji }])
+
+/**
+ * Bot-API surface handed to `redactAuthCodeMessage` (#488) so its 🔑 reaction
+ * routes through the send gate + flood breaker like every other reaction
+ * (#3155). The OAuth-code DELETE stays raw/best-effort exactly as before — its
+ * own `.then(onOk, onErr)` logging (the "token may still be visible" breadcrumb)
+ * must keep firing, which a swallowing wrapper would suppress.
+ */
+const redactAuthCodeApi = {
+  deleteMessage: (chatId: string, messageId: number) =>
+    // allow-raw-bot-api: auth-code redact delete stays raw/best-effort (behavior unchanged, #488); #3155 gates only the reaction.
+    bot.api.deleteMessage(chatId, messageId),
+  setMessageReaction: (
+    chatId: string,
+    messageId: number,
+    reaction: Array<{ type: 'emoji'; emoji: string }>,
+  ) => gatedSetMessageReaction(chatId, messageId, reaction as ReactionTypeEmoji[]),
+}
+
+/**
+ * The wrapper for NON-ESSENTIAL sends that must NEVER retry (#3084).
+ *
+ * A typing indicator is disposable: if it fails, the correct answer is to drop
+ * it, because a retry spends more of the per-bot flood budget the REPLIES need
+ * — retrying is what feeds a ban. But it must not be SILENT either: the typing
+ * loop was the single largest emitter (55% of outbound volume) and it called
+ * `bot.api` raw with `.catch(() => {})`, so the #2923 flood circuit breaker —
+ * which only learns about 429s through `createRetryApiCall`'s `onFloodWait`
+ * hook — was blind to 429s from the biggest source of them.
+ *
+ * `maxRetries: 1` + a no-op sleep gives exactly one attempt at the API, whatever
+ * the outcome: a 429 still runs `onFloodWait` (recording the window to the
+ * breaker), and then the call ends — a SHORT ban falls out of the loop as
+ * `max retries exceeded`, a LONG one throws #3094's `FLOOD_WAIT_ACTIVE`. Either
+ * way the ping is dropped, never slept and never retried. That is the whole
+ * point: a retried non-essential send is what feeds a ban.
+ *
+ * Composes cleanly on top of #3094 (`bbe14471`): that PR bounded the in-process
+ * 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.
+ */
+// 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
+// neither the code nor the retry_after (retryApiCall replaces the original on
+// give-up) — and retry_after is the single number an operator needs during a
+// ban. So the honest 429 line is written HERE, in the onFloodWait hook, where
+// the real value is still in hand.
+const recordTypingFloodWait = makeFloodWaitRecorder(FLOOD_STATE_PATH)
+const nonEssentialApiCall = createRetryApiCall({
+  maxRetries: 1,
+  sleep: async () => {},
+  onFloodWait: (retryAfterSec) => {
+    recordTypingFloodWait(retryAfterSec)
+    process.stderr.write(
+      `telegram gateway: 429 flood-wait on a NON-ESSENTIAL send (retry_after=${retryAfterSec}s) — ` +
+        `recorded to the flood breaker; the send is DROPPED, not retried (#3084)\n`,
+    )
+  },
+})
+
+// #3084 PR 3/3 — observability + operator flood alerts (part3-design §6).
+// A low-frequency, change-gated stats line + flood-window open/close snapshots
+// to the gateway-supervisor log, and ONE operator alert per prolonged flood
+// window. All feature-flagged: when the send gate is OFF, `stats().enabled` is
+// false and both `tick()`s are pure no-ops (the interval is not even scheduled).
+const SEND_GATE_OBSERVE_INTERVAL_MS = 15_000
+const sendGateStatsLogger = createStatsLogger({
+  stats: () => sendGate.stats(),
+  log: (line) => process.stderr.write(line),
+  clock: { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)) },
+})
+const floodWindowObserver = createFloodWindowObserver({
+  clock: { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)) },
+  log: (line) => process.stderr.write(line),
+  stats: () => sendGate.stats(),
+  readWindows: (now) => readFloodWindows(FLOOD_WINDOWS_PATH, now),
+  markAlerted: (scopeKey, alertedAt) =>
+    markFloodWindowAlerted(FLOOD_WINDOWS_PATH, scopeKey, alertedAt, Date.now()),
+  operatorChatId: () => loadAccess().allowFrom[0], // resolved per-tick (allowFrom can change)
+  sendAlert: async (text) => {
+    const operator = loadAccess().allowFrom[0]
+    if (operator === undefined) {
+      process.stderr.write(
+        `telegram gateway: send-gate flood alert not sent — no operator chat (allowFrom empty)\n`,
+      )
+      return
+    }
+    await robustApiCall(
+      // allow-raw-bot-api: operator flood alert, routed through robustApiCall.
+      () => bot.api.sendRichMessage(operator, richMessage(text), {}),
+      { chat_id: String(operator), verb: 'send-gate-flood-alert', priorityClass: 'critical' },
+    )
+  },
+})
+if (sendGateEnabledFromEnv()) {
+  const observeTimer = setInterval(() => {
+    try {
+      sendGateStatsLogger.tick()
+    } catch {
+      /* observability must never crash the gateway */
+    }
+    void floodWindowObserver.tick().catch(() => {
+      /* best-effort — a failed observer tick must not surface */
+    })
+  }, SEND_GATE_OBSERVE_INTERVAL_MS)
+  // Don't keep the event loop alive for observability alone.
+  observeTimer.unref?.()
+}
+
 // ─── Typing indicator ─────────────────────────────────────────────────────
 // All four state maps re-keyed from `chat_id` to `chatKey(chat, thread)`
 // in PR3 of the supergroup-mode rollout. In supergroup mode one agent
@@ -5311,33 +5717,94 @@ const CHAT_ACTION_WHITELIST = new Set([
 ] as const)
 type ChatAction = typeof CHAT_ACTION_WHITELIST extends Set<infer T> ? T : never
 
-function startTypingLoop(
-  chat_id: string,
-  thread_id: number | null = null,
-  action: ChatAction = 'typing',
-): void {
-  stopTypingLoop(chat_id, thread_id)
-  const key = chatKey(chat_id, thread_id) as string
-  const sendOpts = thread_id != null ? { message_thread_id: thread_id } : undefined
-  const send = () => {
-    bot.api.sendChatAction(chat_id, action, sendOpts).then(
+/**
+ * The ONE seam every chat action in this gateway goes through (#3084).
+ *
+ * Both typing loops (tool-use `typingIntervals` below and the turn-level
+ * `turnTypingLoop`) and the one-shot inbound pings share this emitter, so the
+ * per-chat-key floor holds ACROSS them: at most one `sendChatAction` per chat
+ * key per ~4 s window, no matter how many times a loop is restarted. That is
+ * what decouples the typing rate from the agent's TOOL-CALL rate — the
+ * regression that earned a 4.6-hour flood ban. A cold start (no ping inside
+ * the floor) still fires instantly, so "typing…" lands the moment a turn
+ * begins; only redundant restarts are dropped — and a dropped tick arms a
+ * coalesced catch-up, so the indicator never goes dark for longer than the
+ * floor. While a flood window is open, typing — non-essential by definition —
+ * is not emitted at all.
+ *
+ * (`sendChatAction` is outside `check-bot-api-wrapping`'s pattern by design —
+ * chat actions take no `message_thread_id`, so they were never in the
+ * THREAD_NOT_FOUND blast radius the guard polices. It's routed through the
+ * retry module anyway, because that is where the flood breaker's `onFloodWait`
+ * hook lives and typing is the largest 429 source there is.)
+ */
+const typingEmitter = createTypingEmitter({
+  chatKey: (chat_id, thread_id) => chatKey(chat_id, thread_id) as string,
+  isSuppressed: () => suppressNonEssentialSendMs(FLOOD_STATE_PATH, Date.now()) > 0,
+  send: (chat_id, thread_id, action) => {
+    const sendOpts = thread_id != null ? { message_thread_id: thread_id } : undefined
+    void nonEssentialApiCall(
+      () => bot.api.sendChatAction(chat_id, action as ChatAction, sendOpts),
+      { chat_id, verb: 'sendChatAction' },
+    ).then(
       () => { typingBackoffMs = 0 },
       (err) => {
         const msg = err instanceof Error ? err.message : String(err)
         if (msg.includes('401') || msg.includes('Unauthorized')) {
+          const key = chatKey(chat_id, thread_id) as string
           typingBackoffMs = Math.min(Math.max(typingBackoffMs * 2 || 1000, 1000), TYPING_BACKOFF_MAX)
           stopTypingLoop(chat_id, thread_id)
           const retry = setTimeout(() => {
             typingRetryTimers.delete(key)
-            startTypingLoop(chat_id, thread_id, action)
+            startTypingLoop(chat_id, thread_id, action as ChatAction)
           }, typingBackoffMs)
           typingRetryTimers.set(key, retry)
+          return
         }
+        // A flood-wait already logged its retry_after (and hit the breaker) in
+        // onFloodWait above. What lands here is either retryApiCall's opaque
+        // give-up error (short ban) or #3094's FLOOD_WAIT_ACTIVE marker (long
+        // ban / pre-call gate) — neither names the retry_after, so don't
+        // double-log a strictly less informative line. Both are DROPS: a
+        // typing ping is never retried, and the marker is caught here (this is
+        // an onRejected handler), so it can't surface as an unhandled rejection
+        // out of a fire-and-forget ping.
+        if (isFloodWaitActiveError(err) || msg.includes('max retries exceeded')) return
+        // Everything else is DROPPED, never retried — but logged, so the
+        // largest outbound emitter is no longer silent (#3084).
+        process.stderr.write(
+          `telegram gateway: sendChatAction dropped (non-essential, not retried): ${msg}\n`,
+        )
       },
     )
-  }
+  },
+})
+
+/** Fire one chat action for (chat, thread), subject to the shared floor. */
+function emitChatAction(
+  chat_id: string,
+  thread_id: number | null = null,
+  action: ChatAction = 'typing',
+): void {
+  typingEmitter.emit(chat_id, thread_id, action)
+}
+
+function startTypingLoop(
+  chat_id: string,
+  thread_id: number | null = null,
+  action: ChatAction = 'typing',
+): void {
+  stopTypingLoop(chat_id, thread_id)
+  const key = chatKey(chat_id, thread_id) as string
+  // The immediate fire is FLOOR-GATED (it was not, and that is #3084): the
+  // tool-use wrapper restarts this loop on every tool call, so an unguarded
+  // immediate send made the ping rate equal the tool-call rate and the 4 s
+  // interval decorative. The emitter drops the restart's ping when this key
+  // already pinged inside the window, and lets it straight through on a cold
+  // start — so a turn still lights up "typing…" instantly.
+  const send = () => emitChatAction(chat_id, thread_id, action)
   send()
-  typingIntervals.set(key, setInterval(send, 4000))
+  typingIntervals.set(key, setInterval(send, TYPING_REFRESH_MS))
 }
 
 function stopTypingLoop(chat_id: string, thread_id: number | null = null): void {
@@ -5357,14 +5824,19 @@ function stopTypingLoop(chat_id: string, thread_id: number | null = null): void
 // kill it and the chat would go dark for the rest of the turn — the exact
 // black-box gap this closes. The dedicated map (private to the factory) makes
 // the turn loop structurally immune to those stops: only the canonical turn-end
-// stop clears it. The redundant `typing` pings while a reply is mid-flight are
-// harmless — same action, and sendChatAction is cheap.
+// stop clears it.
+//
+// The interval map stays separate — but the SENDS do not (#3084). This loop and
+// `typingIntervals` target the SAME chat key, and the old comment here claimed
+// the redundant pings were "harmless — same action, and sendChatAction is
+// cheap". They are not cheap: they spend the per-bot flood budget the replies
+// need, and two independently-restarting loops on one key is exactly how the
+// rate compounded. Both loops now emit through `typingEmitter`, so the
+// per-chat-key floor is SHARED and neither loop can out-shout the other.
 const turnTypingLoop = createTurnTypingLoop({
-  sendChatAction: (chat_id, thread_id) => {
-    const sendOpts = thread_id != null ? { message_thread_id: thread_id } : undefined
-    void bot.api.sendChatAction(chat_id, 'typing', sendOpts).catch(() => {})
-  },
+  sendChatAction: (chat_id, thread_id) => emitChatAction(chat_id, thread_id, 'typing'),
   chatKey: (chat_id, thread_id) => chatKey(chat_id, thread_id) as string,
+  refreshMs: TYPING_REFRESH_MS,
 })
 
 function startTurnTypingLoop(chat_id: string, thread_id: number | null = null): void {
@@ -5373,6 +5845,11 @@ function startTurnTypingLoop(chat_id: string, thread_id: number | null = null):
 
 function stopTurnTypingLoop(chat_id: string, thread_id: number | null = null): void {
   turnTypingLoop.stop(chat_id, thread_id)
+  // Canonical turn-end: cancel any catch-up the floor armed, so a tick dropped
+  // in the last seconds of the turn can't resurrect "typing…" after the reply
+  // has landed. Deliberately NOT done in `stopTypingLoop` — the tool loop stops
+  // on every tool result, which is exactly the churn the catch-up covers.
+  typingEmitter.cancelPending(chat_id, thread_id)
 }
 
 const typingWrapper = createTypingWrapper({
@@ -5381,31 +5858,6 @@ const typingWrapper = createTypingWrapper({
   isSurfaceTool: isTelegramSurfaceTool,
 })
 
-// ─── Robust API call wrapper ──────────────────────────────────────────────
-// Extracted to telegram-plugin/retry-api-call.ts so it's unit-testable in
-// isolation; the gateway just composes the pure policy with its own logger.
-// #2923: the shared flood-wait marker. Every observed 429 retry_after window
-// is persisted here via onFloodWait, and both boot-card callsites consult the
-// SAME file to suppress a restart card while a per-bot flood ban is open (so a
-// restart doesn't post into the window and extend the ban). Falls back to a
-// no-op recorder when TELEGRAM_STATE_DIR is unset (dev/one-shot contexts).
-// STATE_DIR always resolves (env or a ~/.claude fallback), so this is live.
-const FLOOD_STATE_PATH = floodStatePath(STATE_DIR)
-const robustApiCall = createRetryApiCall({
-  log: (line) => process.stderr.write(line),
-  onFloodWait: makeFloodWaitRecorder(FLOOD_STATE_PATH),
-})
-
-// Fire-and-forget wrapper for outbound surfaces that previously had
-// `.catch(() => {})` directly on `bot.api.*` calls. Resolves to undefined
-// (instead of crashing the gateway) on THREAD_NOT_FOUND, give-up, 403,
-// and any non-benign error — logs a one-liner so the failure isn't
-// completely silent. See #1075.
-const swallowingApiCall = createSwallowingRetryApiCall(
-  robustApiCall,
-  (line) => process.stderr.write(line),
-)
-
 /**
  * Adapter factory for `startBootCard`'s `BotApiForBootCard` interface.
  *
@@ -5440,7 +5892,8 @@ function wrapBootCardApi(
             richMessage(text),
             sendOpts as Parameters<typeof lockedBot.api.sendRichMessage>[2],
           ),
-        opts(cid),
+        // #3084 PR 2: boot/config card CREATION is USEFUL (queue with TTL).
+        { ...opts(cid), priorityClass: 'useful' },
       )
       return sent as { message_id: number }
     },
@@ -5453,7 +5906,9 @@ function wrapBootCardApi(
             richMessage(text),
             editOpts as Parameters<typeof lockedBot.api.editMessageText>[3],
           ),
-        opts(cid),
+        // A boot-card EDIT is COSMETIC — shed under pressure; pass
+        // messageId/editPayload so the per-message floor + no-op skip engage.
+        { ...opts(cid), priorityClass: 'cosmetic', messageId: mid, editPayload: text },
       ) as Promise<unknown>,
     // Strict edit for the boot-card edit-in-place probe: distinguishes
     // "message gone" (→ 'gone', caller sends fresh) from a landed/identical
@@ -5505,7 +5960,8 @@ function wrapIssuesCardApi(
             richMessage(text),
             sendOpts as Parameters<typeof lockedBot.api.sendRichMessage>[2],
           ),
-        opts(cid),
+        // #3084 PR 2: issues-card creation is USEFUL.
+        { ...opts(cid), priorityClass: 'useful' },
       )
       return sent as { message_id: number }
     },
@@ -5518,7 +5974,8 @@ function wrapIssuesCardApi(
             richMessage(text),
             editOpts as Parameters<typeof lockedBot.api.editMessageText>[3],
           ),
-        opts(cid),
+        // An issues-card EDIT is COSMETIC.
+        { ...opts(cid), priorityClass: 'cosmetic', messageId: mid, editPayload: text },
       ) as Promise<unknown>,
     deleteMessage: (cid, mid) =>
       robustApiCall(() => lockedBot.api.deleteMessage(cid, mid), opts(cid)) as Promise<unknown>,
@@ -5552,7 +6009,11 @@ const STATUS_QUERY_RE = /^\s*status\??\s*$/i
 
 // ─── Permission handling ──────────────────────────────────────────────────
 const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i
-const pendingPermissions = new Map<string, { tool_name: string; description: string; input_preview: string; startedAt: number; card_text: string; cards: { chatId: string; messageId: number; threadId?: number | null }[] }>()
+// `undeliverable` (#3084 follow-up): set when the card send failed against a
+// known-open Telegram flood window. While it is set the entry is HELD — the TTL
+// sweep skips it (never auto-deny an ask no human ever saw) and the reaper
+// re-posts the card once the window closes. Cleared on successful delivery.
+const pendingPermissions = new Map<string, { tool_name: string; description: string; input_preview: string; startedAt: number; card_text: string; cards: { chatId: string; messageId: number; threadId?: number | null }[]; undeliverable?: UndeliverableMark | null; redeliveryFailures?: number }>()
 // PERMISSION_TTL_MS / ttlForTool / the timed-out card builder now live in
 // ./permission-timeout.ts (pure + unit-testable). hostd gated verbs get a
 // 30-min window; everything else keeps the 10-min default.
@@ -5770,6 +6231,23 @@ function sweepStaleMentalModelCorrelations(now = Date.now()): void {
   pendingMentalModelCorrelations.sweep(now)
 }
 
+// #2975 Stage 2 — read-only pre-approval predicate. hostd asks (over the
+// approval-gateway socket, via `check_pre_approved`) whether an EXACT
+// (agent, diff) pair is already operator-consented so it can skip the
+// config_propose_edit rate limit for that persist. The forge-resistant,
+// read-only matching lives in the pure `isDiffPreApproved` (pre-approval-
+// check.ts) so its contract — true only for a byte-exact registered pair,
+// NEVER a mutation — is unit-testable without importing this module. Here we
+// only bind it to the live correlation stores + helpers.
+function isDiffPreApprovedLive(agentName: string, unifiedDiff: string): boolean {
+  return isDiffPreApproved(agentName, unifiedDiff, {
+    alwaysAllow: pendingAlwaysAllowCorrelations,
+    mentalModel: pendingMentalModelCorrelations,
+    extractAddedAllowRule,
+    mentalModelCorrelationKey,
+  })
+}
+
 // Scoped-approval store: the 30-min window that backs the "✅ Allow" tap for
 // narrow non-destructive scopes (not a separate button — it IS what Allow
 // means for those). Operator-tapped, gateway-side ONLY (never pushed to the
@@ -6525,9 +7003,260 @@ function restorePendingApprovalCards(): number {
   return restored
 }
 
+/**
+ * Post the Approve/Deny card for `requestId` to every permission-card target.
+ *
+ * Extracted from `onPermissionRequest` (#3084 follow-up) so it has TWO callers:
+ * the initial delivery, and the reaper's held-card re-delivery once a flood
+ * window closes. Both paths must behave identically — same routing, same
+ * thread-fallback, same landed-card bookkeeping, same hold-on-flood-wait — so
+ * there is exactly one implementation of "post this card".
+ *
+ * Everything it needs is rebuilt from the pending entry, so a re-delivery an
+ * hour later renders the same card the operator would have seen at T+0.
+ */
+function postPermissionCard(
+  requestId: string,
+  pend: NonNullable<ReturnType<typeof pendingPermissions.get>>,
+): void {
+  // Register the in-flight flag HERE, not at the call sites, so BOTH callers are
+  // covered. The sweep used to add it itself, but the ipcServer initial-delivery
+  // call site did not — so a reaper tick landing between window-close and a slow
+  // in-flight INITIAL send settling could post a duplicate card. One registration
+  // point, one release point (the `.finally` below / the sync-throw catch).
+  heldCardsInFlight.add(requestId)
+
+  // One increment per ATTEMPT, not per failing target. `targets` is N-wide and
+  // every failing target runs the same `.catch` — incrementing there ratcheted
+  // the backoff ladder N× faster than the documented 1m/2m/4m…30m. Compute the
+  // attempt number once, up front; every failing target stamps the SAME value.
+  const attemptFailures = (pend.redeliveryFailures ?? 0) + 1
+
+  try {
+  const text = pend.card_text
+  const showAlways =
+    resolveScopedAllowChoices(pend.tool_name, pend.input_preview) != null
+  const keyboard = buildPermissionActionRow(requestId, showAlways)
+  // Route the card to the SAME place the post-verdict resume message lands
+  // (resolvePermissionCardTargets): the ORIGINATING chat+topic when there's an
+  // active turn — so a supergroup agent's card appears IN the topic the
+  // operator asked from (marko's "CRM (Brevo)"), not the operator DM — else the
+  // configured operator DMs, thread-stripped. The old code iterated `allowFrom`
+  // unconditionally, so a supergroup card could only ever reach operator DMs
+  // (the topic chat id is never in `allowFrom`) (marko, 2026-06-03).
+  const targets = resolvePermissionCardTargets()
+
+  // ONE settle across ALL targets, not one per target (reviewer F1).
+  //
+  // The in-flight flag (guard iii) exists so the reaper can't re-post a card whose
+  // previous post hasn't settled. `resolvePermissionCardTargets()` returns N
+  // targets — it ends in `allowFrom.map(...)` — and on the RE-delivery path N>1 is
+  // the COMMON case: re-delivery after a multi-hour ban is by construction past the
+  // 30-min origin-recovery window, so it falls through to the operator-DM fan-out.
+  // Clearing the flag per-target released it the moment the FIRST target settled
+  // while others were still in flight, and the next tick re-posted to all of them —
+  // a double delivery. Settle once, when every target is done.
+  const sends = targets.map(({ chatId, threadId }) => {
+    // The rich-markdown path pairs with formatPermissionCardBody (#1790) so its
+    // bold/italic render. retryWithThreadFallback: if the topic was
+    // deleted/recreated (stale thread id → 400 "message thread not found"),
+    // re-send thread-less into the main chat so the card still ARRIVES rather
+    // than vanishing.
+    // allow-raw-bot-api: wrapped in retryWithThreadFallback (retry policy); topic-aware send
+    return retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+      robustApiCall,
+      (tid) =>
+        bot.api.sendRichMessage(chatId, richMessage(text), {
+          reply_markup: keyboard,
+          ...(tid != null ? { message_thread_id: tid } : {}),
+        }),
+      { threadId, chat_id: chatId, verb: 'permission_request' },
+    ).then(sent => {
+      // Record the live card's (chat, message) so the reaper can strip its inline
+      // keyboard — a stale Approve button left tappable dispatches a verdict for a
+      // dead request_id (Bug 2). The entry may already be gone (operator tapped
+      // before this resolved); guard the lookup.
+      const live = pendingPermissions.get(requestId)
+      if (live && sent && typeof sent.message_id === 'number') {
+        // #2787: record where the card ACTUALLY LANDED so the confirm sweep scopes
+        // its re-delivery suspension to the real chat/topic. `sent.message_thread_id`
+        // reflects reality in all three cases: topic success → tid, main-chat /
+        // fallback → undefined.
+        const landedThreadId = sent.message_thread_id ?? undefined
+        live.cards.push({ chatId, messageId: sent.message_id, threadId: landedThreadId })
+        // The card LANDED — the operator can see and tap it, so the block is over.
+        // Drop the hold mark and reconcile the off-Telegram surface. (PR 3 also
+        // resets `startedAt` here: the TTL measures how long the operator had to
+        // answer, and until this moment they had nothing to answer.)
+        if (live.undeliverable != null) {
+          live.undeliverable = null
+          live.redeliveryFailures = 0
+          // RESET THE TTL CLOCK. Load-bearing, not cosmetic. `startedAt` is when
+          // the agent asked; the TTL measures how long the operator had to
+          // answer. Until this instant they had NOTHING to answer — the card did
+          // not exist in any chat. Without the reset, a card held through a 4.6h
+          // ban lands already-expired against a 60-min TTL and the very next
+          // reaper tick auto-denies it: we would have MOVED the silent denial,
+          // not removed it.
+          live.startedAt = Date.now()
+          reconcileBlockedApprovals()
+          process.stderr.write(
+            `telegram gateway: permission-card RE-DELIVERED request=${requestId} ` +
+            `tool=${live.tool_name} chat=${chatId} — the operator can answer now; ` +
+            `TTL clock restarted (they had zero seconds while the channel was shut)\n`,
+          )
+        }
+        permCardStore.add({
+          requestId,
+          chatId,
+          messageId: sent.message_id,
+          startedAt: live.startedAt,
+          toolName: live.tool_name,
+          cardText: live.card_text,
+        })
+      }
+    }).catch(e => {
+      process.stderr.write(`telegram gateway: permission_request send to ${chatId} failed: ${e}\n`)
+      const live = pendingPermissions.get(requestId)
+      if (live == null) return // operator already resolved it — nothing to hold
+
+      // A card already landed on ANOTHER target, so the ask is NOT undeliverable —
+      // the operator can see and tap it (reviewer F2). Marking it held here would be
+      // a PERMANENT wedge: `selectHeldForRedelivery` skips entries that have cards,
+      // so the mark could never be cleared, and PR 3's TTL freeze would then keep
+      // the entry alive forever with the surface stuck on "blocked".
+      if (live.cards.length > 0) return
+
+      // The card did NOT land anywhere. Before this the error was logged and
+      // dropped: the entry sat with `cards: []`, the operator saw nothing, and 60
+      // minutes later the TTL sweep AUTO-DENIED an approval no human had ever been
+      // shown. Now we hold it — but only for a TRANSIENT cause. `holdReasonFor`
+      // decides; a permanent 400 (a card that will never format) still falls through
+      // to the TTL, which PR 3 makes safe by giving the no-card timeout a
+      // missed-approvals fallback.
+      const reason = holdReasonFor(e)
+      if (reason == null) return
+
+      // Bound the RATE, never the RETRY. A held entry is re-selected every tick, so a
+      // target that keeps failing would otherwise re-send every 60s forever — the
+      // amplifier this series exists to avoid. Back off instead (1m, 2m, 4m … 30m).
+      // We never STOP retrying: a terminal give-up would strand the card even after
+      // the channel recovered, and because turnInFlightForGate() holds the inbound
+      // gate while a permission is pending, that would silently buffer the operator's
+      // messages forever. Escalate the surface, never the verdict — and never abandon
+      // the card.
+      const failures = attemptFailures
+      live.redeliveryFailures = failures
+      const now = Date.now()
+      // A flood-wait carries Telegram's own window end; everything else backs off.
+      const retryableAt = isFloodWaitActiveError(e) ? e.untilTs : now + heldRetryBackoffMs(failures)
+      // `since` is set ONCE — it is when the block began, not when we last retried.
+      live.undeliverable = { since: live.undeliverable?.since ?? now, retryableAt, reason }
+      // Reconcile the shared surface SYNCHRONOUSLY, here in the failure handler — not
+      // on the 60s reaper tick. The operator is locked out of Telegram; this record is
+      // the only way they learn an agent is blocked, so it must be live in under a
+      // second, not up to a minute.
+      reconcileBlockedApprovals()
+      process.stderr.write(
+        `telegram gateway: permission-card HELD (undeliverable) request=${requestId} ` +
+        `tool=${live.tool_name} reason=${reason} attempt=${failures} ` +
+        `retryable_at=${new Date(retryableAt).toISOString()}` +
+        ` — approval is held, NOT denied; re-delivering when the channel returns ` +
+        `(backoff ${Math.round(heldRetryBackoffMs(failures) / 60000)}m)\n`,
+      )
+    })
+  })
+
+  // Settle ONCE, after every target. `allSettled` never rejects, so the flag is
+  // always released — including when `targets` is empty (no active turn AND no
+  // configured operator DM), in which case `sends` is [] and this resolves at once.
+  void Promise.allSettled(sends).finally(() => {
+    heldCardsInFlight.delete(requestId)
+  })
+  } catch (e) {
+    // A SYNCHRONOUS throw (resolveScopedAllowChoices / buildPermissionActionRow /
+    // resolvePermissionCardTargets) never reaches the `.finally` above — without
+    // this catch the in-flight flag would leak and the request would never be
+    // re-selected by the sweep. Release the flag, then rethrow so the caller
+    // (the sweep's own try/catch, or the ipc handler) sees the failure.
+    heldCardsInFlight.delete(requestId)
+    throw e
+  }
+}
+
+/**
+ * Request ids whose card post is mid-flight — INITIAL delivery or re-delivery.
+ * Guard (iii) against double-delivery: the 60s reaper must not re-post a card
+ * whose previous post hasn't settled yet (a slow send would otherwise be
+ * re-issued every tick). Registered at the top of postPermissionCard (so both
+ * callers are covered) and cleared in its `.finally` — or its sync-throw catch.
+ */
+const heldCardsInFlight = new Set<string>()
+
+/**
+ * Re-deliver held permission cards once the flood window closes (#3084
+ * follow-up, PR 2).
+ *
+ * The whole point of holding rather than auto-denying is that the ask comes
+ * BACK. This is the half that brings it back.
+ *
+ * `selectHeldForRedelivery` owns the guards (window closed, held, no landed
+ * card, not in flight, per-tick cap). `robustApiCall`'s own pre-call probe is a
+ * further, independent short-circuit downstream — if the window re-opens
+ * between selection and send, the send refuses itself and the entry is simply
+ * re-marked with the longer window.
+ *
+ * The per-tick cap is the ban-safety property: a backlog of held cards must not
+ * BURST the instant the window closes, because that burst is the one realistic
+ * way this design could re-earn the ban it exists to survive. Deferred ids are
+ * LOGGED, never silently dropped — they go out on the next tick.
+ */
+function sweepHeldPermissionCards(): void {
+  const remaining = probeFloodWaitRemainingMs()
+  const { send, deferred } = selectHeldForRedelivery(pendingPermissions.entries(), {
+    floodRemainingMs: remaining,
+    inFlight: heldCardsInFlight,
+    now: Date.now(),
+  })
+  if (send.length === 0) return
+
+  process.stderr.write(
+    `telegram gateway: flood window closed — re-delivering ${send.length} held ` +
+    `permission card(s)` +
+    (deferred.length > 0
+      ? `; ${deferred.length} deferred to the next tick by the per-tick cap ` +
+        `(${deferred.join(', ')}) — deferred, NOT dropped`
+      : '') + '\n',
+  )
+  for (const requestId of send) {
+    const pend = pendingPermissions.get(requestId)
+    if (pend == null) continue
+    try {
+      // postPermissionCard registers the in-flight flag itself (so the ipc
+      // initial-delivery caller is covered too) and releases it once every
+      // target settles — or on a sync throw, in its own catch.
+      postPermissionCard(requestId, pend)
+    } catch (e) {
+      // A synchronous throw must not escape the setInterval callback (it would
+      // kill the whole reaper tick, TTL sweep included). postPermissionCard has
+      // already released the flag; delete again defensively so the entry is
+      // re-selectable on the next tick, and log rather than rethrow.
+      heldCardsInFlight.delete(requestId)
+      process.stderr.write(
+        `telegram gateway: held-card re-delivery for ${requestId} threw ` +
+        `synchronously: ${e} — flag released, will retry on the next tick\n`,
+      )
+    }
+  }
+}
+
 // 60-second sweep drops anything past its documented TTL.
 const pendingStateReaper = setInterval(() => {
   const now = Date.now()
+  // #3084 follow-up — bring held cards BACK the moment the channel reopens.
+  // Runs before the TTL sweep below so a card that can be re-delivered on this
+  // tick is re-delivered, not considered for expiry.
+  sweepHeldPermissionCards()
   // OAuth-code state grouped first (pinned by secret-detect-oauth-code.test.ts).
   pendingReauthFlows.sweep(now)
   for (const [k, v] of pendingAuthAddFlows) {
@@ -6539,6 +7268,21 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of awaitingAuthCodeAt) {
     if (now - v > AUTH_CODE_CONTEXT_TTL_MS) awaitingAuthCodeAt.delete(k)
   }
+  // Loopback OAuth relay flows (issue #2582) — same TTL. Kill the waiting
+  // CLI child so an abandoned consent never lingers with a bound listener.
+  // Placed AFTER the OAuth-code cluster above, which secret-detect-oauth-
+  // code.test.ts pins as contiguous within the first 800 chars of the
+  // reaper (same precedent as the Microsoft connect sweep below). A flow
+  // with a submit in flight is skipped (PR #3100 review finding 3): a paste
+  // near the TTL boundary must not have its child killed mid-registration —
+  // the submit path owns cleanup once `submitting` is set.
+  for (const [k, v] of pendingLoopbackFlows) {
+    if (v.submitting) continue
+    if (now - v.startedAt > REAUTH_INTERCEPT_TTL_MS) {
+      cancelLoopbackFlow(v)
+      pendingLoopbackFlows.delete(k)
+    }
+  }
   // Microsoft connect flows self-expire at the device code's own expiry
   // (~15 min) — sweep past that + grace so an abandoned card doesn't pin
   // its key. Setting cancelled makes any still-running poll bail. Placed
@@ -6561,11 +7305,19 @@ const pendingStateReaper = setInterval(() => {
     if (now >= v.expiresAt) pendingAuthRmFlows.delete(k)
   }
   pendingVaultOps.sweep(now)
-  for (const [k, v] of pendingPermissions) {
-    // hostd gated fleet-mutation verbs get a longer (30-min) human-scale
-    // decision window than the 10-min default (Bug 2 fix #2).
-    const ttl = ttlForTool(v.tool_name)
-    if (now - v.startedAt > ttl) {
+  // THE LEASH. The sweep — the guard AND the auto-deny it gates — now lives in
+  // permission-ttl-sweep.ts, and the outcome test's harness drives that exact
+  // function. It used to be an inline loop here while the harness kept a PRIVATE
+  // copy of the guard, so deleting the real check left every behavioural assertion
+  // GREEN and only a source-text grep noticed. A test that cannot fail is not a
+  // test, and this is the test for `no-self-escalation`. One implementation, two
+  // callers: there is no longer a gateway-side line whose deletion restores the
+  // auto-deny without removing the sweep entirely.
+  sweepPermissionTtl({
+    entries: pendingPermissions,
+    now,
+    ttlForTool,
+    onExpire: (k, v, ttl) => {
       // Don't just drop it: the claude turn is suspended INSIDE the MCP
       // permission call waiting for a verdict. A silent delete left it
       // wedged forever when the operator never tapped — permanent
@@ -6612,8 +7364,19 @@ const pendingStateReaper = setInterval(() => {
       // returns. Anchor to the card's own origin surface (where the operator
       // would have tapped), so the digest lands in the same topic — not a
       // fanned-out DM. Skip if the card was never posted anywhere.
+      // The `cards[0]` hole (#3084 follow-up): this used to skip silently when the
+      // card had never landed (`cards: []` → `origin === undefined`). That is
+      // exactly the undeliverable case — so the request was auto-denied AND erased
+      // from the only record that would have brought it back. The safety net had a
+      // hole shaped exactly like the accident.
+      //
+      // Held entries no longer reach this code at all (the TTL freeze above skips
+      // them), so this is belt-and-braces: ANY future path that times out a card
+      // which never landed — including a PERMANENT 400, which holdReasonFor()
+      // deliberately does not hold — still lands in the digest. Fall back to where
+      // the card WOULD have gone.
       if (MISSED_APPROVAL_REOFFER_ENABLED) {
-        const origin = v.cards[0]
+        const origin = v.cards[0] ?? resolvePermissionCardTargets()[0]
         if (origin != null) {
           missedApprovalsStore.add({
             requestId: k,
@@ -6632,8 +7395,9 @@ const pendingStateReaper = setInterval(() => {
       )
       pendingPermissions.delete(k)
       permCardStore.remove(k)
-    }
-  }
+      reconcileBlockedApprovals()
+    },
+  })
   // Drop no-repeat suppression entries past the safety-cap window (the primary
   // bound is the operator-activity reset; this just keeps the map from growing).
   for (const [sig, at] of permissionTimeoutSignatures) {
@@ -7194,6 +7958,12 @@ const statusPinChatIds = new Map<string, string>()
 // 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>()
+// 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
+// auto-pin. The explicit `pin_message` MCP tool deliberately does NOT consult
+// this cache (it always attempts and surfaces the error to the agent).
+const statusPinRightsCache = new PinRightsCache()
 
 // Durable snapshot of the pin claim set on the persistent per-agent volume
 // (STATE_DIR = /state/agent/telegram in prod). Closes the crash hole: the
@@ -7228,6 +7998,48 @@ const activityCardStoreFs: ActivityCardStoreFsSeam = {
 }
 const activityCardPersistEnabled = !STATIC
 
+// Durable handle for the component-5 queued-status placeholder + #2995 busy-ack
+// card (#3002). Both track their sent message id only in the in-memory
+// `queuedStatusMsgIds` Map, so a restart between posting a card and its
+// promote/reap strands a permanent stale "⏳ Queued…" line. Persisted on POST,
+// cleared on in-process reap; a boot-time reaper (wired alongside
+// `activityCardBootReaper`, same startup-mutex ordering constraint) DELETES any
+// leftover card and clears the store — a "Queued" claim is always wrong after a
+// restart, so deletion is the honest terminal (reap-on-boot only, no
+// promote-across-restart). STATIC mode skips disk — same gate as the sibling
+// stores.
+const QUEUED_CARD_STORE_PATH = join(STATE_DIR, 'queued-cards-pending.json')
+const queuedCardStoreFs: QueuedCardStoreFsSeam = {
+  readFileSync: (p: string) => readFileSync(p, 'utf8'),
+  writeFileSync: (p: string, d: string) => writeFileSync(p, d),
+  renameSync: (a: string, b: string) => renameSync(a, b),
+  existsSync: (p: string) => existsSync(p),
+}
+const queuedCardPersistEnabled = !STATIC
+
+// Write-through helpers (#3002) — mirror the in-memory `queuedStatusMsgIds`
+// set/delete onto the durable store. Best-effort + gated: no-op when the store
+// isn't usable (STATIC = no durable volume). Called from postQueuedStatus /
+// postBusyAck (post) and reapQueuedStatus (delete).
+function persistQueuedCard(
+  key: string,
+  chatId: string,
+  threadId: number | null,
+  messageId: number,
+): void {
+  if (!queuedCardPersistEnabled) return
+  writeQueuedCardRecord(QUEUED_CARD_STORE_PATH, queuedCardStoreFs, {
+    key,
+    chatId,
+    threadId,
+    messageId,
+  })
+}
+function clearQueuedCard(key: string, messageId?: number): void {
+  if (!queuedCardPersistEnabled) return
+  clearQueuedCardRecord(QUEUED_CARD_STORE_PATH, queuedCardStoreFs, key, messageId)
+}
+
 // Slot-banner pin persistence (#421 crash-recovery). The slot banner is pinned
 // in the owner chat when the agent is on a non-default OAuth slot. Rather than a
 // parallel store + second boot hook, its pin is persisted in the SAME
@@ -7395,6 +8207,40 @@ async function activityCardBootReaper(): Promise<void> {
     )
   }
 }
+
+/**
+ * Boot-time reaper for orphaned queued-status / busy-ack cards (#3002). Thin
+ * gateway wrapper over the pure `runQueuedCardBootReaper` — binds the live fs
+ * seam, a robust Telegram delete, and the logger. Deletes any card persisted by
+ * a prior (crashed/restarted) session and clears the store: a "⏳ Queued…" /
+ * "On it" claim is always wrong after a restart, so deletion is the honest
+ * terminal (reap-on-boot only, no promote-across-restart).
+ *
+ * MUST run ONLY after this gateway wins the startup mutex — same shared-file
+ * ordering constraint as `activityCardBootReaper` / `statusPinBootCleanup`.
+ */
+async function queuedCardBootReaper(): Promise<void> {
+  if (!queuedCardPersistEnabled) return
+  const { deleted, total } = await runQueuedCardBootReaper({
+    path: QUEUED_CARD_STORE_PATH,
+    fs: queuedCardStoreFs,
+    deleteCard: (record) =>
+      robustApiCall(
+        () => lockedBot.api.deleteMessage(record.chatId, record.messageId),
+        {
+          chat_id: record.chatId,
+          ...(record.threadId != null ? { threadId: record.threadId } : {}),
+          verb: 'queued-card.boot-reap-delete',
+        },
+      ),
+  })
+  if (total > 0) {
+    process.stderr.write(
+      `telegram gateway: queued-card: deleted ${deleted}/${total} ` +
+        `orphaned queued/busy-ack card(s) from a prior session\n`,
+    )
+  }
+}
 // ─── Mid-session stale-card reaper (#2918) ──────────────────────────────────
 // The boot reapers (markOrphanedWithTimeoutClassification + activityCardBoot-
 // Reaper) run ONCE at startup. A turn whose owning SDK subprocess dies
@@ -7651,6 +8497,16 @@ async function reconcileStatusPinInner(
       chatId,
       prevState: prev,
       desired,
+      rightsCache: statusPinRightsCache,
+      onPinRightsDisabled: (chat) => {
+        // Logged ONCE per chat per process (#3024). Every subsequent auto-pin
+        // attempt in this chat is skipped silently until a restart clears the
+        // cache — replacing the 41x/48h `status-pin pin failed` spam marko saw.
+        process.stderr.write(
+          `telegram gateway: status-pin disabled for chat ${chat}: bot lacks ` +
+            `pin rights; grant 'Pin messages' admin right to re-enable after restart\n`,
+        )
+      },
       onError: (phase, err) => {
         const msg = err instanceof Error ? err.message : String(err)
         process.stderr.write(
@@ -7752,6 +8608,105 @@ async function unpinAllStatusPins(): Promise<void> {
   }
 }
 
+// ─── DM stale-pin sweep (#3026) ─────────────────────────────────────────────
+// In a user DM the Bot API skips the boot getChat() probe (positive chat IDs
+// return `400 chat not found` until the user messages) AND getChat() exposes
+// only the NEWEST pin — DMs STACK pins and there is no list-pins method, so
+// older orphan pins are invisible to the probe-based sweep forever. The durable
+// fix: once per DM chat per boot, `unpinAllChatMessages` (safe in a DM — every
+// pin is bot-authored) then re-pin the live tracked cards. Groups keep the
+// probe path (unpin-all there would nuke human pins).
+//
+// Eligibility mirrors statusPinBootCleanup's mutex gate: set true ONLY after
+// this gateway wins the startup lock, so a losing double-boot never clears the
+// live holder's pins.
+let dmPinSweepEligible = false
+const dmPinSweeper: DmPinSweeper = createDmPinSweeper({
+  unpinAll: (chatId) =>
+    robustApiCall(() => lockedBot.api.unpinAllChatMessages(chatId), {
+      chat_id: chatId,
+      verb: 'dm-pin-sweep.unpin-all',
+    }),
+  pinSilent: (chatId, messageId) =>
+    robustApiCall(
+      () =>
+        lockedBot.api.pinChatMessage(chatId, messageId, {
+          disable_notification: true,
+        }),
+      { chat_id: chatId, verb: 'dm-pin-sweep.repin' },
+    ),
+  // Pins that must survive the unpin-all: live in-memory status-pin claims
+  // for this chat (fg:/wk:/tool:/banner: — non-empty for a first-inbound
+  // sweep landing mid-turn) UNIONED with the deliberately-retained store
+  // rows — unexpired `tool:` pins (#3001) survive statusPinBootCleanup by
+  // design and must survive this sweep too. Read LIVE from the store so
+  // both the boot sweep (in-memory maps still empty then) and a later
+  // first-inbound sweep see them. Best-effort: a store read failure
+  // 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)
+    }
+    if (statusPinPersistEnabled || bannerPinPersistEnabled || toolPinPersistEnabled) {
+      try {
+        ids.push(
+          ...unexpiredStoreRepinIds(
+            loadStatusPins(STATUS_PIN_STORE_PATH, statusPinStoreFs),
+            chatId,
+            Date.now(),
+          ),
+        )
+      } catch (err) {
+        process.stderr.write(
+          `telegram gateway: dm-pin-sweep: store repin scan failed ` +
+            `(chat=${chatId}): ${(err as Error).message}\n`,
+        )
+      }
+    }
+    return ids
+  },
+  eligible: () => dmPinSweepEligible,
+  log: (line) => process.stderr.write(line),
+})
+
+/**
+ * Boot-time pin cleanup + DM stale-pin sweep, sequenced under the startup
+ * mutex. Collects the DM chat IDs with a prior-session pin record BEFORE the
+ * store reapers empty the stores, runs the three existing boot reapers, marks
+ * the DM sweep eligible (this gateway now owns the shared state), then
+ * unpin-alls each recorded DM chat. Fire-and-forget from the caller — never
+ * blocks boot, never rejects unhandled.
+ */
+async function runBootPinCleanupAndDmSweep(): Promise<void> {
+  let dmChatIds: string[] = []
+  try {
+    dmChatIds = collectDmChatIdsFromStores({
+      statusPins:
+        statusPinPersistEnabled || bannerPinPersistEnabled || toolPinPersistEnabled
+          ? loadStatusPins(STATUS_PIN_STORE_PATH, statusPinStoreFs)
+          : [],
+      activityCards: activityCardPersistEnabled
+        ? loadActivityCards(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs)
+        : [],
+      queuedCards: queuedCardPersistEnabled
+        ? loadQueuedCards(QUEUED_CARD_STORE_PATH, queuedCardStoreFs)
+        : [],
+    })
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: dm-pin-sweep: store scan failed: ${(err as Error).message}\n`,
+    )
+  }
+  await statusPinBootCleanup()
+  await activityCardBootReaper()
+  await queuedCardBootReaper()
+  // This gateway now owns the shared per-agent pin state — enable the DM
+  // unpin-all path (both the boot sweep below and lazy first-inbound sweeps).
+  dmPinSweepEligible = true
+  for (const id of dmChatIds) await dmPinSweeper.sweep(id)
+}
+
 // Activity feed. The gateway streams a live "what it's doing" tool-activity
 // feed for every turn. The PreToolUse sidecar emits a `tool_label` per tool
 // call (flush-independent, so it stays real-time on fast/clustered-tool
@@ -7904,8 +8859,9 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
     // pins from a prior (dead) session. Gated here (not at import time) so a
     // LOSING double-boot never unpins the live holder's legitimate pins.
     // Fire-and-forget: cleanup is best-effort and must not block boot.
-    void statusPinBootCleanup()
-    void activityCardBootReaper()
+    // #3026: sequenced so the DM stale-pin sweep runs after the reapers and
+    // only once this gateway owns the shared state.
+    void runBootPinCleanupAndDmSweep()
   } catch (err) {
     process.stderr.write(
       `telegram gateway: boot.lock_acquire_failed err=${(err as Error).message} agent=${SWITCHROOM_AGENT_NAME}\n`,
@@ -7921,8 +8877,8 @@ function ensureIssuesCard(chatId: string, threadId: number | undefined): void {
       // probe + 409-retry loop is still the liveness guard on this path. A
       // successful writePidFile here means no live holder was detected, so
       // running orphan cleanup is consistent with the pre-mutex behaviour.
-      void statusPinBootCleanup()
-      void activityCardBootReaper()
+      // #3026: same sequenced cleanup + DM stale-pin sweep as the mutex path.
+      void runBootPinCleanupAndDmSweep()
     } catch (writeErr) {
       process.stderr.write(`telegram gateway: writePidFile failed: ${writeErr}\n`)
     }
@@ -8644,6 +9600,13 @@ pendingProgress.startTimer({
         chat_id: ctx.chatId,
         verb: 'pending-progress-edit',
         ...(ctx.threadId != null ? { threadId: ctx.threadId } : {}),
+        // #3084 PR 2 / L1: the progress-card edit is the #1 documented ban
+        // trigger (repeated editMessageText on one message). Tag COSMETIC and
+        // pass messageId/editPayload so the gate's per-message floor + no-op
+        // skip + coalescing engage, and the edit sheds while a window is open.
+        priorityClass: 'cosmetic',
+        messageId: ctx.messageId,
+        editPayload: ctx.literalText ? ctx.newText : richMessage(ctx.newText),
       },
     )
   },
@@ -9256,6 +10219,16 @@ const ipcServer: IpcServer = createIpcServer({
     // this call is safe wherever it sits relative to the cron early-return
     // above (#3038 review finding 5).
     bridgeDeadWatchdog.noteBridgeRegistered(client.agentName)
+    // #3043 item 2: a REAL bridge registering is proof the boot came all the
+    // way up healthy — clear start.sh's crashloop boot-attempts counter so only
+    // boots that genuinely fail BEFORE the bridge registers accumulate toward
+    // the 3-strike override clear. Without this, three quick operator
+    // hand-bounces of a healthy agent (each <150s apart) spuriously wipe a
+    // working model override. Best-effort; no-op when the file is absent.
+    if (client.agentName != null) {
+      const smBootDir = resolveAgentDirFromEnv()
+      if (smBootDir != null) clearSessionModelBootAttempts(smBootDir)
+    }
     client.send({ type: 'status', status: 'agent_connected' })
 
     // Phase 2b PR 3a — bridgeUp cutover. The state machine's `bridgeUp`
@@ -9480,6 +10453,16 @@ const ipcServer: IpcServer = createIpcServer({
         // scripts/check-plugin-references.mjs (TS2722).
         progressDriver?.dispose?.({ preservePending: true })
       },
+      // #2650: the bridge died mid-turn — its turn-long `typing…` loop never
+      // hits the canonical turn-end stop, leaving a stale "typing…" until the
+      // next turn. Sweep every live loop here (gated to registered-agent
+      // disconnect inside flushOnAgentDisconnect).
+      stopTurnTypingLoops: () => {
+        turnTypingLoop.stopAll()
+        // Shutdown drain: also cancel every armed catch-up so no typing ping
+        // fires after the gateway has stopped.
+        typingEmitter.reset()
+      },
       // When dangling activeTurnStartedAt keys were swept (setDone raced
       // disconnect), the module-scope `currentTurn` may also point at the
       // dead bridge's turn. Null it so the next inbound starts a fresh
@@ -9702,7 +10685,8 @@ const ipcServer: IpcServer = createIpcServer({
     // `card_text` is retained so the TTL reaper can re-edit the SAME body
     // with a "timed out" footer while stripping the keyboard atomically
     // (Bug 2 fix #1) — the reaper has no grammy ctx to read the live text.
-    pendingPermissions.set(requestId, { tool_name: toolName, description, input_preview: inputPreview, startedAt: Date.now(), card_text: text, cards: [] })
+    const pendEntry = { tool_name: toolName, description, input_preview: inputPreview, startedAt: Date.now(), card_text: text, cards: [] }
+    pendingPermissions.set(requestId, pendEntry)
     // Compact action row: ❌ Deny · ✅ Allow · 🔁 Always… — the scope of an
     // "always" grant stays hidden until the operator taps "🔁 Always…",
     // which swaps the row for a scope choice (this file / any file ⚠️). The
@@ -9710,67 +10694,15 @@ const ipcServer: IpcServer = createIpcServer({
     // rule for this tool; unknown tools get the two-button row only. "Allow"
     // itself auto-grants a 30-min window for narrow non-destructive scopes
     // (decided in the allow handler), so there is no separate time-box button.
-    const showAlways = resolveScopedAllowChoices(toolName, inputPreview) != null
-    const keyboard = buildPermissionActionRow(requestId, showAlways)
-    // Route the card to the SAME place the post-verdict resume message
-    // lands (resolvePermissionCardTargets): the ORIGINATING chat+topic when
-    // there's an active turn — so a supergroup agent's card appears IN the
-    // topic the operator asked from (marko's "CRM (Brevo)"), not the
-    // operator DM — else the configured operator DMs, thread-stripped. The
-    // old code iterated `allowFrom` unconditionally, so a supergroup card
-    // could only ever reach operator DMs (the topic chat id is never in
-    // `allowFrom`) (marko, 2026-06-03).
+    // Captured BEFORE the send: the status-reaction parking below needs the
+    // turn that raised this card, and `currentTurn` can be re-pointed by a
+    // concurrent inbound while the send is in flight.
     const activeTurn = currentTurn
-    const targets = resolvePermissionCardTargets()
-    for (const { chatId, threadId } of targets) {
-      // The rich-markdown path pairs with formatPermissionCardBody (#1790)
-      // so its bold/italic render. retryWithThreadFallback: if the topic was
-      // deleted/recreated (stale thread id → 400 "message thread not
-      // found"), re-send thread-less into the main chat so the card still
-      // ARRIVES rather than vanishing → 10-min TTL auto-deny → wedge.
-      // allow-raw-bot-api: wrapped in retryWithThreadFallback (retry policy); topic-aware send
-      void retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
-        robustApiCall,
-        (tid) =>
-          bot.api.sendRichMessage(chatId, richMessage(text), {
-            reply_markup: keyboard,
-            ...(tid != null ? { message_thread_id: tid } : {}),
-          }),
-        { threadId, chat_id: chatId, verb: 'permission_request' },
-      ).then(sent => {
-        // Record the live card's (chat, message) so the TTL reaper can strip
-        // its inline keyboard on auto-deny — a stale Approve button left
-        // tappable dispatches a verdict for a dead request_id (Bug 2). The
-        // entry may already be gone (operator tapped before this resolved);
-        // guard the lookup.
-        const pend = pendingPermissions.get(requestId)
-        if (pend && sent && typeof sent.message_id === 'number') {
-          // #2787: record where the card ACTUALLY LANDED so the confirm sweep
-          // scopes its re-delivery suspension to the real chat/topic. When
-          // retryWithThreadFallback hit THREAD_NOT_FOUND (stale/renumbered
-          // topic) it re-sent thread-less into the main chat — the returned
-          // Message then carries no message_thread_id, so we must record the
-          // landed topic (undefined → suspend by bare chatId), NOT the stale
-          // requested `threadId`. Keying suspension on the stale topic would
-          // leave the main-chat card unsuspended (a re-deliver could clobber
-          // the live card) while needlessly suspending a topic that holds
-          // nothing. `sent.message_thread_id` reflects reality in all three
-          // cases: topic success → tid, main-chat / fallback → undefined.
-          const landedThreadId = sent.message_thread_id ?? undefined
-          pend.cards.push({ chatId, messageId: sent.message_id, threadId: landedThreadId })
-          permCardStore.add({
-            requestId,
-            chatId,
-            messageId: sent.message_id,
-            startedAt: pend.startedAt,
-            toolName: pend.tool_name,
-            cardText: pend.card_text,
-          })
-        }
-      }).catch(e => {
-        process.stderr.write(`telegram gateway: permission_request send to ${chatId} failed: ${e}\n`)
-      })
-    }
+    // #3084 follow-up — the send now lives in postPermissionCard() so the
+    // reaper can RE-DRIVE it when a flood window closes. This is the first
+    // delivery attempt; if it fails against an open ban the entry is marked
+    // undeliverable and held, never auto-denied.
+    postPermissionCard(requestId, pendEntry)
     // Park the turn's status reaction on 🙏 (awaiting your tap) and
     // suspend the stall watchdog — a turn blocked on the operator is not
     // stalled, so it must not degrade to 🥱/😨 while the card sits
@@ -10481,6 +11413,36 @@ const ipcServer: IpcServer = createIpcServer({
     }
   },
 
+  // #2975 Stage 2 — read-only pre-approval query from hostd. Answer whether the
+  // EXACT (agent, diff) pair is already operator-consented so hostd can skip the
+  // config_propose_edit rate limit for that persist. NEVER mutates state: it
+  // only peeks the correlation maps by byte-exact match (isDiffPreApproved).
+  // Fail-closed by construction — any agent mismatch or missing correlation
+  // answers `preApproved: false`.
+  onCheckPreApproved(client: IpcClient, msg: CheckPreApprovedMessage) {
+    let preApproved = false
+    try {
+      const self = process.env.SWITCHROOM_AGENT_NAME
+      // This gateway serves exactly one agent; a query for a different agent
+      // can never be pre-approved here.
+      if (!self || msg.agentName === self) {
+        preApproved = isDiffPreApprovedLive(msg.agentName, msg.unifiedDiff)
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: check_pre_approved errored — ${(err as Error).message} (failing closed)\n`,
+      )
+      preApproved = false
+    }
+    try {
+      client.send({ type: 'pre_approved_result', correlationId: msg.correlationId, preApproved })
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: check_pre_approved reply failed: ${(err as Error).message}\n`,
+      )
+    }
+  },
+
   // #2670 one-tap self-improvement — persist a skill-improvement proposal and
   // post its Approve/Dismiss card. The store transition + apply-injection on
   // Approve are owned by handleSkillProposalCallback (so a gateway restart
@@ -10824,10 +11786,21 @@ async function executeSendChecklist(args: Record<string, unknown>): Promise<{ co
 
   assertAllowedChat(chat_id)
 
-  const sent = await rawSendChecklist({
-    chat_id,
+  // #2044 outbound secret scrub. Checklist title + task strings are
+  // agent-authored free text sent to Telegram, same class as the reply
+  // `text` path and ask_user — route both through the SAME redactor before
+  // send (via the pure, unit-tested redactChecklistFields helper) so an
+  // echoed token / DATABASE_URL is masked.
+  const { title: redactedTitle, tasks: redactedTasks } = redactChecklistFields(
     title,
     tasks,
+    (t) => redactOutboundText(t, 'send_checklist'),
+  )
+
+  const sent = await rawSendChecklist({
+    chat_id,
+    title: redactedTitle!,
+    tasks: redactedTasks!,
     ...(threadId != null ? { message_thread_id: threadId } : {}),
     ...(replyTo != null ? { reply_to_message_id: replyTo } : {}),
     ...(protectContent ? { protect_content: true } : {}),
@@ -10909,7 +11882,19 @@ async function executeUpdateChecklist(args: Record<string, unknown>): Promise<{
 
   assertAllowedChat(chat_id)
 
-  await rawEditMessageChecklist({ chat_id, message_id, title, tasks })
+  // #2044 outbound secret scrub. update_checklist forwards the same
+  // agent-authored title + task text to Telegram as send_checklist, so it
+  // shares the identical leak class — redact both through the reply-path
+  // redactor (via the shared redactChecklistFields helper) before the edit
+  // lands. title / tasks may be undefined here (partial patch); the helper
+  // passes undefined through untouched.
+  const { title: redactedTitle, tasks: redactedTasks } = redactChecklistFields(
+    title,
+    tasks,
+    (t) => redactOutboundText(t, 'update_checklist'),
+  )
+
+  await rawEditMessageChecklist({ chat_id, message_id, title: redactedTitle, tasks: redactedTasks })
 
   process.stderr.write(`telegram gateway: update_checklist: updated chatId=${chat_id} messageId=${message_id}\n`)
   return { content: [{ type: 'text', text: `checklist updated (id: ${message_id})` }] }
@@ -11637,8 +12622,18 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
         .join('; ')
       throw new Error(`inline_keyboard validation failed: ${summary}`)
     }
-    replyButtonMeta = extractAgentButtonMeta(rawKeyboard)
-    replyMarkup = { inline_keyboard: wrapAgentCallbacks(rawKeyboard) }
+    // #3148 fast-follow: mask any secret an agent put in a visible button
+    // `text` label, its `ack_text` toast, or a `copy_text.text` clipboard
+    // payload BEFORE the keyboard is sent — the same outbound scrub the reply
+    // `text` body uses. `callback_data` (the routing key) is left exact.
+    // Feeding BOTH the meta extraction and the callback wrap from the redacted
+    // copy means the stashed toast, the tap echo (`button_text`), and the
+    // "✅ You chose: <label>" annotation (#789) all read already-masked bytes.
+    const redactedKeyboard = redactAgentKeyboard(rawKeyboard, (s) =>
+      redactOutboundText(s, 'reply_inline_keyboard'),
+    )
+    replyButtonMeta = extractAgentButtonMeta(redactedKeyboard)
+    replyMarkup = { inline_keyboard: wrapAgentCallbacks(redactedKeyboard) }
   }
 
   // on-demand voice: append a single '🔊 Listen' button that synthesizes the
@@ -11963,13 +12958,15 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
       robustApiCall(
         // allow-raw-bot-api: injected chunk-loop adapter — sendRichMessage routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks' fallback ladder
         () => lockedBot.api.sendRichMessage(chat_id, body as never, opts as never),
-        { threadId: tid, chat_id },
+        // #3084 PR 2: the final reply is CRITICAL — never shed; degraded mode
+        // fails fast (structured flood_wait) instead of blocking the MCP reply.
+        { threadId: tid, chat_id, priorityClass: 'critical' },
       ),
     sendLiteral: (opts, txt, tid) =>
       robustApiCall(
         // allow-raw-bot-api: injected chunk-loop adapter — literal format:'text' send routed through robustApiCall; THREAD_NOT_FOUND handled by sendReplyChunks
         () => lockedBot.api.sendMessage(chat_id, txt, opts as never),
-        { threadId: tid, chat_id },
+        { threadId: tid, chat_id, priorityClass: 'critical' },
       ),
     sendLiteralRaw: (opts, txt) =>
       // allow-raw-bot-api: literal last-resort fallback (plaintext parse-reject / length re-split); wrapping would re-enter the parse/length policy that just rejected the payload
@@ -11981,7 +12978,10 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
       robustApiCall(
         // allow-raw-bot-api: preview edit-in-place routed through robustApiCall; thread fallback handled by sendReplyChunks
         () => lockedBot.api.editMessageText(chat_id, mid, body as never, opts as never),
-        { threadId: tid, chat_id },
+        // Finalizing the reply into the preview message — still CRITICAL (this
+        // IS the answer). Pass messageId/editPayload so the gate's per-message
+        // floor + no-op skip engage on the edit (part3-design §4/§5, PR1 L1).
+        { threadId: tid, chat_id, priorityClass: 'critical', messageId: mid, editPayload: body },
       ),
     richMessage,
     logOutbound,
@@ -12604,6 +13604,21 @@ async function executeAskUser(rawArgs: Record<string, unknown>): Promise<unknown
   const args = validateAskUserArgs(rawArgs as unknown as AskUserArgs)
   assertAllowedChat(args.chatId)
 
+  // #2044 outbound secret scrub. The question text and each option/button
+  // label are agent-authored free text sent to Telegram, exactly like the
+  // reply `text` path — an agent that echoes a token or DATABASE_URL it just
+  // read into a question or a button label would transmit it unmasked. Route
+  // both through the SAME redactor as reply (via the pure, unit-tested
+  // redactAskUserFields helper), assigning back onto the validated args so
+  // every downstream consumer — the send, the timeout-edit re-render, and
+  // the tap-echo of the chosen label stored in pendingAskUser — sees the
+  // masked value.
+  const scrubbed = redactAskUserFields(args.question, args.options, (t) =>
+    redactOutboundText(t, 'ask_user'),
+  )
+  args.question = scrubbed.question
+  args.options = scrubbed.options
+
   // Resolve thread + reply-to using the same auto-thread heuristic
   // executeReply uses, so an agent that omits message_thread_id still
   // routes into the right forum topic and quotes the user's last
@@ -13704,9 +14719,11 @@ async function executeReact(args: Record<string, unknown>): Promise<unknown> {
   if (!args.message_id) throw new Error('react: message_id is required')
   if (!args.emoji) throw new Error('react: emoji is required')
   assertAllowedChat(String(args.chat_id ?? ''))
-  await lockedBot.api.setMessageReaction(String(args.chat_id ?? ''), Number(args.message_id), [
-    { type: 'emoji', emoji: args.emoji as ReactionTypeEmoji['emoji'] },
-  ])
+  await sendReaction(
+    String(args.chat_id ?? ''),
+    Number(args.message_id),
+    args.emoji as ReactionTypeEmoji['emoji'],
+  )
   return { content: [{ type: 'text', text: 'reacted' }] }
 }
 
@@ -13846,6 +14863,12 @@ async function executePinMessage(args: Record<string, unknown>): Promise<unknown
     () => lockedBot.api.pinChatMessage(pinChatId, pinMsgId),
     { chat_id: pinChatId, verb: 'pin_message' },
   )
+  // An explicit pin succeeded here, so the bot demonstrably HAS pin rights in
+  // this chat now — clear any auto-pin negative-cache entry (#3024) so the auto
+  // status-pin path resumes immediately rather than waiting for a restart. The
+  // explicit tool itself never consults the cache; a failure above still
+  // surfaces to the agent as a normal tool error (robustApiCall rethrows).
+  statusPinRightsCache.clear(pinChatId)
   // #3001: register the tool pin in the shared status-pin store under a
   // `tool:` key so it is no longer fire-and-forget. Unlike work-scoped
   // fg:/wk: rows a tool pin has no "work finished" event, so a restart does
@@ -14962,6 +15985,21 @@ function handleSessionEvent(ev: SessionEvent): void {
       liveTurn.liveness.onStreamEvent(ev.kind, durationMs, Date.now())
     }
   }
+  // Idle-clear clocks (#3084 follow-up). EVERY genuine session event is
+  // activity — an agent that is thinking, calling a tool, streaming text or
+  // driving a sub-agent is NOT idle, whether or not the gateway currently has a
+  // turn open. Stamping only at turn START (the old behaviour) is what let a
+  // 3-hour working stretch be scored as zero activity and `/clear`ed the moment
+  // the window elapsed. A turn ending stamps the turn-end clock too, so a turn
+  // that outran the window is not wiped the instant `turnInFlight` goes false.
+  // This runs for the whole event stream, including every `sub_agent_*` kind —
+  // background workers keep the timer warm exactly as long as they are working.
+  {
+    const durationMs = ev.kind === 'turn_end' ? ev.durationMs : undefined
+    const signal = classifyIdleEvent(ev.kind, durationMs)
+    if (signal.activity) markIdleActivity()
+    if (signal.turnEnded) markIdleTurnEnd()
+  }
   switch (ev.kind) {
     case 'enqueue': {
       // Drain any orphaned typing-wrap entries left over from a crashed
@@ -15100,7 +16138,9 @@ function handleSessionEvent(ev: SessionEvent): void {
         // per-topic `byKey[statusKey]` entry AND the most-recent mirror. The key is
         // the SAME statusKey the ctor's façade was constructed with just above.
         setCurrentTurn(next, statusKey(ev.chatId, enqThreadIdNum))
-        markIdleActivity() // any turn start (main session) is activity — re-arm idle clear
+        // (turn start already stamped the idle clock at the top of
+        // handleSessionEvent, along with every other session event — see the
+        // idle-clear block there.)
         // Early-open the "Working…" liveness card at turn start so narration /
         // thinking emitted BEFORE the first tool surfaces within ~a second
         // instead of after the old 12 s threshold (the dead-air gap). Fires the
@@ -15584,6 +16624,14 @@ function handleSessionEvent(ev: SessionEvent): void {
                   chat_id: chatId,
                   verb: 'answer-stream.editMessageText',
                   ...(tid != null ? { threadId: tid } : {}),
+                  // #3084 PR 2 / L1: answer-stream edits are COSMETIC — a
+                  // dropped stream tick costs nothing (the next carries full
+                  // text). messageId/editPayload engage the per-message floor +
+                  // coalescing + no-op skip so rapid stream edits don't storm
+                  // the same message (the top ban trigger).
+                  priorityClass: 'cosmetic',
+                  messageId,
+                  editPayload: richMessage(text),
                 },
               )
             },
@@ -15777,6 +16825,24 @@ function handleSessionEvent(ev: SessionEvent): void {
           return
         }
       }
+      // #2094 finding 1 — turn_end gate-wedge backstop. Capture the turn
+      // BEFORE the body runs (the body re-reads currentTurn as `turn`, then
+      // nulls it via endCurrentTurnAtomic on every clean branch). The guarded
+      // finally in withTurnEndGateBackstop forces the canonical purge iff a
+      // throw in a pre-purge op (redactOutboundText, progressDriver?.
+      // takeOverCard, narrative dedup, answer-stream finalize, …) skipped
+      // endCurrentTurnAtomic → purgeReactionTracking, which would otherwise
+      // leave activeTurnStartedAt + claudeBusyKeys populated and wedge the
+      // #1556 inbound gate closed. No-op on the happy path (key already gone).
+      const turnEndBackstopTurn = currentTurn
+      const turnEndBackstopKey =
+        turnEndBackstopTurn != null
+          ? statusKey(turnEndBackstopTurn.sessionChatId, turnEndBackstopTurn.sessionThreadId)
+          : null
+      withTurnEndGateBackstop(
+        turnEndBackstopKey,
+        turnEndBackstopTurn,
+        () => {
       // Drain any still-pending tool dispatch typing entries — covers
       // transcript truncation or a Claude Code crash mid-tool.
       typingWrapper.drainAll()
@@ -16003,6 +17069,17 @@ function handleSessionEvent(ev: SessionEvent): void {
             capturedText: turn.capturedText,
             flushEnabled: TURN_FLUSH_SAFETY_ENABLED,
           })
+      // #1667 — resolve the turn_end answer-delivery gate once, here, via the
+      // pure decision core. The three dispositions below (silent-marker,
+      // turn-flush, #1664 re-prompt) delegate to this so the gateway runs the
+      // exact code the regression test exercises. `finalAnswerDelivered` is read
+      // at its tail value: the answer-stream materialize branch above has
+      // already run (and may have set it true); the flush branch, which also
+      // sets it, is not yet entered and does not affect the gate's own outcome.
+      const turnEndDecision = decideTurnEndGate({
+        flushDecision,
+        finalAnswerDelivered: turn.finalAnswerDelivered,
+      })
       if (flushDecision.kind === 'skip' && flushDecision.reason !== 'reply-called') {
         process.stderr.write(
           `telegram gateway: turn-flush skipped — reason=${flushDecision.reason}\n`,
@@ -16041,7 +17118,7 @@ function handleSessionEvent(ev: SessionEvent): void {
       //  2. NOT send any reply message to the user.
       //  3. Unpin the progress card so no orphaned ⚙️ Working… lingers.
       //  4. Log at debug level and fall through to normal state cleanup.
-      if (flushDecision.kind === 'skip' && flushDecision.reason === 'silent-marker') {
+      if (turnEndDecision === 'silent_end') {
         // Don't try to distinguish NO_REPLY vs HEARTBEAT_OK in the log line:
         // `isSilentFlushMarker` accepts trailing punctuation (e.g. "NO_REPLY.")
         // and case variants, so a strict equality check would print the wrong
@@ -16131,7 +17208,7 @@ function handleSessionEvent(ev: SessionEvent): void {
         return
       }
 
-      if (flushDecision.kind === 'flush') {
+      if (turnEndDecision === 'flush' && flushDecision.kind === 'flush') {
         let capturedText = flushDecision.text
         // #2798 — turn-flush delivers the model's terminal prose when it
         // skipped reply/stream_reply, but historically bypassed the reply
@@ -16267,9 +17344,12 @@ function handleSessionEvent(ev: SessionEvent): void {
                 // the reaction is only finalized by the `turn_end` IPC
                 // handler — mid-turn delivery proofs (local history,
                 // stream finalize callbacks, executeReply post-send) no
-                // longer transition the emoji. This branch just purges
-                // the per-turn reaction tracking entry and returns.
-                purgeReactionTracking(statusKey(backstopChatId, backstopThreadId))
+                // longer transition the emoji. This branch just returns.
+                // #2094 cosmetic: the per-turn reaction tracking was ALREADY
+                // purged synchronously by endCurrentTurnAtomic (before this
+                // async IIFE ran). The old redundant purgeReactionTracking
+                // here re-fired on an already-cleared key WITHOUT `endingTurn`,
+                // emitting an inconsistent shadow trace. Removed.
                 return
               }
             } catch {}
@@ -16405,9 +17485,13 @@ function handleSessionEvent(ev: SessionEvent): void {
             // #1713: backstop send failed — finalize as error so the
             // turn ends cleanly with 😱 rather than leaving it open.
             if (backstopCtrl) backstopCtrl.finalize('error')
-          } finally {
-            purgeReactionTracking(statusKey(backstopChatId, backstopThreadId))
           }
+          // #2094 cosmetic: the trailing `finally { purgeReactionTracking() }`
+          // was removed. endCurrentTurnAtomic already ran the canonical purge
+          // (with the authoritative `endingTurn`) synchronously before this
+          // async IIFE started, so re-purging here only re-fired on an
+          // already-cleared key without `endingTurn` — an inconsistent shadow
+          // trace. The #2094 finding-1 backstop covers any pre-purge throw.
         })()
         return
       }
@@ -16496,7 +17580,10 @@ function handleSessionEvent(ev: SessionEvent): void {
         // HEARTBEAT_OK silent-marker turns return earlier and never reach
         // this path. The turn-flush 'flush' branch also returns earlier
         // (and sets finalAnswerDelivered=true defensively).
-        if (turn.finalAnswerDelivered === false) {
+        // #1667 — this is the reply-called tail; `turnEndDecision === 'reprompt'`
+        // is exactly `turn.finalAnswerDelivered === false` here (silent-marker
+        // and flush both returned earlier), delegated to the pure gate core.
+        if (turnEndDecision === 'reprompt') {
           // PR #2892 (deterministic-turn-liveness RFC Phase 2) hardening:
           // wire the represent-guard-style staleness
           // check (`recordSilentTurnEnd`'s `hasOutboundDeliveredSince` dep) so
@@ -16600,6 +17687,14 @@ function handleSessionEvent(ev: SessionEvent): void {
       // #549 fix — preamble flush already happened at the TOP of this
       // turn_end handler (before turn.answerStream is nulled). See
       // comment near line 3431.
+      return
+        }, // end withTurnEndGateBackstop body (#2094 finding 1)
+        {
+          hasActiveTurn: (k) => activeTurnStartedAt.has(k),
+          purge: (k, endingTurn) => purgeReactionTracking(k, endingTurn),
+          log: (m) => process.stderr.write(m + '\n'),
+        },
+      )
       return
     }
   }
@@ -16607,6 +17702,17 @@ function handleSessionEvent(ev: SessionEvent): void {
 
 // ─── PTY partial handler ─────────────────────────────────────────────────
 function handlePtyPartial(text: string): void {
+  // #2044 outbound secret scrub. The PTY-tail partial is the assistant's
+  // reply text extracted from Claude Code's TUI as it renders — an agent
+  // that echoes a secret shows it here (in the live draft-preview stream)
+  // BEFORE the reply tool ever fires, and this path forwards the text
+  // straight to Telegram with no other redaction. Mask at the gateway
+  // boundary through the SAME reply-path redactor so the draft stream, its
+  // dedup key, and lastPtyPreviewByChat all compare redacted-against-
+  // redacted — the identical in-place-mutation invariant the answer stream
+  // relies on. Idempotent: replaying a buffered (already-masked) partial
+  // re-masks to itself.
+  text = redactOutboundText(text, 'pty_preview')
   // #1067: build the PtyHandlerState from a snapshot of currentTurn.
   // The pty-partial-handler module keeps its own state-shape contract
   // (currentSessionChatId / currentSessionThreadId) because it's
@@ -16641,6 +17747,13 @@ function handlePtyPartial(text: string): void {
 }
 
 function handlePtyActivity(text: string): void {
+  // #2044 outbound secret scrub. PTY-activity is agent-derived free text
+  // forwarded to Telegram via handleStreamReply — same leak class as the
+  // draft preview above. Redact through the reply-path redactor before it
+  // streams. (This handler is currently unwired in the gateway — the live
+  // PTY path is handlePtyPartial — but the mask is kept here so the fix is
+  // durable if the activity lane is ever re-armed.)
+  text = redactOutboundText(text, 'pty_activity')
   // #1067: snapshot at entry. handleStreamReply is async and runs in
   // the background via void; the closure already captures `chatId` /
   // `threadId` locals, so the supersession is correctly scoped.
@@ -16993,9 +18106,7 @@ function maybeEarlyAckReaction(ctx: Context, from: NonNullable<Context['from']>)
   if (activeTurnStartedAt.has(statusKey(chatId, threadId))) return
   const access = loadAccess()
   if (!access.allowFrom.includes(String(from.id))) return
-  void bot.api.setMessageReaction(chatId, msgId, [
-    { type: 'emoji', emoji: '👀' as ReactionTypeEmoji['emoji'] },
-  ]).catch(() => {})
+  void sendReaction(chatId, msgId, '👀' as ReactionTypeEmoji['emoji']).catch(() => {})
   // #2527: log the early-ack fire so operators can see how often the
   // fast pre-coalesce DM path triggers vs. the controller path.
   logStreamingEvent({ kind: 'early_ack_reaction', chatId, messageId: msgId, emoji: '👀' })
@@ -17004,7 +18115,9 @@ function maybeEarlyAckReaction(ctx: Context, from: NonNullable<Context['from']>)
   // model text. No fake content — Telegram clients render this natively
   // and it auto-expires after ~5s if not refreshed (the answer-lane
   // first edit will land long before then under the new defaults).
-  void bot.api.sendChatAction(chatId, 'typing').catch(() => {})
+  // Through the shared emitter (#3084): a cold chat still lights up
+  // instantly; a chat already pinged inside the floor doesn't pay twice.
+  emitChatAction(chatId, null, 'typing')
 }
 
 /**
@@ -17063,6 +18176,16 @@ async function handleInbound(
   // #2862 — operator is back; re-offer any approvals that timed out meanwhile.
   maybePostMissedApprovalDigest('operator inbound')
 
+  // #3026 — first inbound from a DM after boot: clear any stale STACKED pins
+  // the boot getChat() probe can't see (DMs skip the probe AND getChat only
+  // exposes the newest pin). unpin-all once per DM chat per boot, then re-pin
+  // live tracked cards. once-guarded (dedups with the boot sweep); no-op for
+  // groups and until the startup mutex is won. Fire-and-forget.
+  {
+    const inboundChatId = ctx.chat?.id
+    if (inboundChatId != null) void dmPinSweeper.sweep(String(inboundChatId))
+  }
+
   // Capture wall-clock receive time for inbound_ack metric (#203).
   // Must be after gate() so early-exit paths (drop/pair) don't skew the delta.
   //
@@ -17224,9 +18347,7 @@ async function handleInbound(
     )
     if (inFlight) {
       if (msgId != null) {
-        void bot.api.setMessageReaction(chat_id, msgId, [
-          { type: 'emoji', emoji: '⚡' as ReactionTypeEmoji['emoji'] },
-        ]).catch(() => {})
+        void sendReaction(chat_id, msgId, '⚡' as ReactionTypeEmoji['emoji']).catch(() => {})
       }
       await executeHaltNow('stop-keyword')
     }
@@ -17271,9 +18392,7 @@ async function handleInbound(
       `in_flight=${toolFlightTracker.inFlightCount()}\n`,
     )
     if (msgId != null) {
-      void bot.api.setMessageReaction(chat_id, msgId, [
-        { type: 'emoji', emoji: '⚡' as ReactionTypeEmoji['emoji'] },
-      ]).catch(() => {})
+      void sendReaction(chat_id, msgId, '⚡' as ReactionTypeEmoji['emoji']).catch(() => {})
     }
     if (interrupt.emptyBody) {
       // #3020: empty `!` is a pure halt (no replacement body) — same shared
@@ -17407,9 +18526,7 @@ async function handleInbound(
     })
     if (msgId != null) {
       const emoji = behavior === 'allow' ? '✅' : '❌'
-      void bot.api.setMessageReaction(chat_id, msgId, [
-        { type: 'emoji', emoji: emoji as ReactionTypeEmoji['emoji'] },
-      ]).catch(() => {})
+      void sendReaction(chat_id, msgId, emoji as ReactionTypeEmoji['emoji']).catch(() => {})
     }
     return
   }
@@ -17465,7 +18582,7 @@ async function handleInbound(
         )
       }
       // Redact the OAuth code paste from chat history (#488).
-      redactAuthCodeMessage(bot.api as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+      redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
       return
     }
     // Stale — drop the pending entry but let the message fall through
@@ -17474,6 +18591,101 @@ async function handleInbound(
     pendingAuthAddFlows.delete(interceptKey)
   }
 
+  // Loopback OAuth relay paste-back intercept (issue #2582) — sibling to
+  // the /auth add intercept above. When a Google/Microsoft loopback relay is
+  // pending for this chat and the operator pastes their `127.0.0.1:<port>`
+  // redirect URL, validate `state` and hand the code to the waiting CLI
+  // listener. The LLM never sees the code (same hygiene rationale as above).
+  // Consume-gate is deliberately narrow (PR #3100 review finding 1): only a
+  // message that actually parses as a loopback redirect — carrying a code,
+  // or a provider `error` param — is consumed and deleted. Unrelated chatter
+  // that merely mentions localhost/127.0.0.1 flows through untouched.
+  const pendingLoop = pendingLoopbackFlows.get(interceptKey)
+  if (pendingLoop && shouldConsumeLoopbackPaste(text)) {
+    const elapsed = Date.now() - pendingLoop.startedAt
+    if (elapsed < REAUTH_INTERCEPT_TTL_MS) {
+      if (pendingLoop.submitting) {
+        // A submit is already in flight (double-paste race). Don't call
+        // submitLoopbackRedirect — it would answer a non-retryable "already
+        // completed" and we'd delete the entry out from under the first
+        // submit. Benign ack; still redact (the paste carries a live code).
+        await switchroomReply(
+          ctx,
+          '_Still finishing the previous paste — one moment._',
+          { html: true },
+        )
+        redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+        return
+      }
+      const result = await submitLoopbackRedirect(pendingLoop, text.trim())
+      if (result.ok) {
+        pendingLoopbackFlows.delete(interceptKey)
+        await switchroomReply(
+          ctx,
+          `✓ ${pendingLoop.provider === 'google' ? 'Google' : 'Microsoft'} account ` +
+            `\`${escapeHtmlForTg(pendingLoop.email)}\` registered with the auth-broker.`,
+          { html: true },
+        )
+        // Redact the pasted redirect (carries the OAuth code) from history.
+        redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+        return
+      }
+      if (result.retryable) {
+        // Keep the flow pending so the operator can paste again.
+        await switchroomReply(
+          ctx,
+          `**Paste not accepted:** ${escapeHtmlForTg(result.reason)}\n` +
+            `Re-open the consent URL, approve, and paste the full ` +
+            `\`127.0.0.1\` URL from your address bar. \`/auth ${pendingLoop.provider} cancel\` to abort.`,
+          { html: true },
+        )
+        // Redact even a rejected paste — it may still carry a live code.
+        redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+        return
+      }
+      // Non-retryable — the flow is spent. Kill the CLI child before
+      // dropping the entry (re-review finding, PR #3100): on the attempts-
+      // exhausted path the child is still alive with a bound 127.0.0.1
+      // listener and nothing else would ever reap it. cancelLoopbackFlow is
+      // idempotent — safe on the already-exited / timed-out paths too.
+      cancelLoopbackFlow(pendingLoop)
+      pendingLoopbackFlows.delete(interceptKey)
+      await switchroomReply(
+        ctx,
+        `**/auth ${pendingLoop.provider} add failed:** ${escapeHtmlForTg(result.reason)}`,
+        { html: true },
+      )
+      redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+      return
+    }
+    // Stale — the intercept window has closed. Kill the child and drop the
+    // entry, then fall through to the fail-safe below. We deliberately do NOT
+    // let the paste reach the agent: the pasted `code` may still be live
+    // (security audit #3084, F3), so the fail-safe redacts it.
+    cancelLoopbackFlow(pendingLoop)
+    pendingLoopbackFlows.delete(interceptKey)
+  }
+
+  // Fail-safe redaction (security audit #3084, F2/F3). A message that looks
+  // like a loopback OAuth redirect/code — even one too malformed to parse
+  // cleanly, or one that arrived just after the intercept TTL closed, or one
+  // with no active flow at all — must NEVER reach the (prompt-injectable)
+  // agent session or linger unredacted in chat while carrying a possibly-live
+  // credential. shouldConsumeLoopbackPaste is narrow (requires a loopback host
+  // reference AND a code/error param), so ordinary chatter mentioning
+  // localhost flows through untouched. Redact and drop rather than forward.
+  if (shouldConsumeLoopbackPaste(text)) {
+    redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+    await switchroomReply(
+      ctx,
+      '_That looked like an OAuth redirect/code, so I removed it from chat and did not forward it. ' +
+        'If a Google/Microsoft account add is in progress, re-run the add command and paste the fresh ' +
+        '`127.0.0.1` URL — the previous code may have expired._',
+      { html: true },
+    )
+    return
+  }
+
   // Auth-code intercept
   const pendingReauth = pendingReauthFlows.get(interceptKey)
   if (pendingReauth && looksLikeAuthCode(text)) {
@@ -17498,7 +18710,7 @@ async function handleInbound(
       // Single-use code so a third party can't replay it after exchange,
       // but plaintext OAuth tokens in chat history are still poor
       // hygiene. The helper handles delete + 🔑 reaction silently.
-      redactAuthCodeMessage(bot.api as never, chat_id, msgId ?? null, line => process.stderr.write(line))
+      redactAuthCodeMessage(redactAuthCodeApi as never, chat_id, msgId ?? null, line => process.stderr.write(line))
       return
     }
     pendingReauthFlows.delete(interceptKey)
@@ -17707,11 +18919,8 @@ async function handleInbound(
   // Typing indicator in the ORIGINATING topic — on a supergroup-topic inbound,
   // an un-threaded sendChatAction shows "typing" in General, not the topic the
   // user is in. messageThreadId is the inbound's thread (undefined in a DM).
-  void bot.api.sendChatAction(
-    chat_id,
-    'typing',
-    messageThreadId != null ? { message_thread_id: messageThreadId } : {},
-  ).catch(() => {})
+  // Floor-gated through the shared emitter (#3084).
+  emitChatAction(chat_id, messageThreadId ?? null, 'typing')
 
   // Parse explicit prefixes first. `/steer ` / `/s ` opts IN to steering;
   // `/queue ` / `/q ` are legacy aliases that opt in to the new default (queued).
@@ -17964,12 +19173,12 @@ async function handleInbound(
       if (isSteering) {
         // Explicit steer: mark with 🤝 on the inbound message; leave the
         // existing StatusReactionController running for the in-flight turn.
-        void bot.api.setMessageReaction(chat_id, msgId, [{ type: 'emoji', emoji: '🤝' }]).catch(() => {})
+        void sendReaction(chat_id, msgId, '🤝').catch(() => {})
       } else if (priorTurnInFlight) {
         // Queued mid-turn message (new default): don't touch the existing
         // controller; just ack the inbound message with 👀 so the user
         // knows we received it, without disrupting the in-flight reaction.
-        void bot.api.setMessageReaction(chat_id, msgId, [{ type: 'emoji', emoji: '👀' }]).catch(() => {})
+        void sendReaction(chat_id, msgId, '👀').catch(() => {})
         // #203: time-to-ack metric — measure gateway-receive → ack-post delta.
         logStreamingEvent({ kind: 'inbound_ack', chatId: chat_id, messageId: msgId, ackDelayMs: Date.now() - inboundReceivedAt })
       } else {
@@ -18012,9 +19221,7 @@ async function handleInbound(
         // msgId here and use it as the reaction-session token in log events.
         const ctrlTurnToken = `${chat_id}:${msgId}`
         const ctrl = new StatusReactionController(async (emoji) => {
-          await bot.api.setMessageReaction(chat_id, msgId, [
-            { type: 'emoji', emoji: emoji as ReactionTypeEmoji['emoji'] },
-          ])
+          await sendReaction(chat_id, msgId, emoji as ReactionTypeEmoji['emoji'])
           // #203: every status-reaction transition is a user-visible signal.
           signalTracker.noteSignal(key, Date.now())
         }, allowedReactions, {
@@ -18097,9 +19304,7 @@ async function handleInbound(
         }
       }
     } else if (access.ackReaction) {
-      void bot.api.setMessageReaction(chat_id, msgId, [
-        { type: 'emoji', emoji: access.ackReaction as ReactionTypeEmoji['emoji'] },
-      ]).catch(() => {})
+      void sendReaction(chat_id, msgId, access.ackReaction as ReactionTypeEmoji['emoji']).catch(() => {})
       // #203: time-to-ack metric for the custom-ack-reaction path.
       logStreamingEvent({ kind: 'inbound_ack', chatId: chat_id, messageId: msgId, ackDelayMs: Date.now() - inboundReceivedAt })
     }
@@ -18792,6 +19997,17 @@ function escapeHtmlForTg(text: string): string {
   return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
+// #789 — button-choice-confirmation ("✅ You chose: X") annotation state.
+//
+// Two once-per-process warning dedupe sets keyed by agent slug: one for the
+// parseMode gate (annotation only supports the default 'html' parse mode),
+// one for the single_use mismatch (a re-tappable keyboard can never be
+// annotated, so a confirmation request on it silently no-ops). The decision
+// + rendered text are pure functions in inline-keyboard-callbacks.ts
+// (resolveTapAnnotation) so they can be unit-tested against the exact payload.
+const buttonConfirmParseModeWarned = new Set<string>()
+const buttonConfirmSingleUseWarned = new Set<string>()
+
 // Wrap CLI/command output in a fenced code block (content is literal there).
 function preBlock(text: string): string {
   return '```\n' + text.replace(/```/g, '`​``') + '\n```'
@@ -19431,7 +20647,7 @@ async function sweepBeforeSelfRestart(): Promise<void> {
   try {
     await sweepActiveReactions(
       agentDir,
-      (chatId, messageId) => lockedBot.api.setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji: '👍' as ReactionTypeEmoji['emoji'] }]),
+      (chatId, messageId) => sendReaction(chatId, messageId, '👍' as ReactionTypeEmoji['emoji']),
       { log: (msg) => process.stderr.write(`telegram gateway: pre-restart reaction sweep — ${msg}\n`) },
     )
   } catch (err) {
@@ -20127,6 +21343,30 @@ async function buildAgentMetadata(agentName: string): Promise<AgentMetadata> {
     auth: authSummary,
     audit: buildAgentAudit(agentName),
     live: await buildLiveProbeRows(agentName),
+    sendGate: buildSendGateStatus(),
+  }
+}
+
+/**
+ * Build the `/status` send-gate block (#3084 PR 3, part3-design §6). Returns
+ * `undefined` when the gate flag is OFF so `/status` renders exactly as it did
+ * before the gate existed. Queued / shed totals come from the live counters;
+ * open flood windows are read from the persisted sibling file (already pruned).
+ */
+function buildSendGateStatus(): AgentMetadata['sendGate'] {
+  const s = sendGate.stats()
+  if (!s.enabled) return undefined
+  const openWindows = readFloodWindows(FLOOD_WINDOWS_PATH, Date.now()).map((w) => ({
+    scopeKey: w.scopeKey,
+    untilTs: w.untilTs,
+  }))
+  return {
+    queued: s.global.queued,
+    shed: s.global.shed,
+    expired: s.global.expired,
+    failedFast: s.global.failedFast,
+    dropped: s.global.dropped,
+    openWindows,
   }
 }
 
@@ -21447,15 +22687,25 @@ bot.command('update', async ctx => {
   const skipImages = passthrough.includes('--skip-images')
   const rebuild = passthrough.includes('--rebuild')
   const updateRequestId = hostdRequestId('gw-update')
-  const hostdResp = await tryHostdDispatch(getMyAgentName(), {
-    v: 1,
-    op: 'update_apply',
-    request_id: updateRequestId,
-    args: {
-      ...(skipImages ? { skip_images: true } : {}),
-      ...(rebuild ? { rebuild: true } : {}),
-    },
-  })
+  // #1841 — forward the cached operator passphrase as the 2nd factor when
+  // hostd requires operator-attest on update_apply. No-op when the vault
+  // is locked / no passphrase is cached (feature-off posture unchanged).
+  const updatePassphrase = vaultPassphraseCache.get(chatId)?.passphrase
+  const hostdResp = await tryHostdDispatch(
+    getMyAgentName(),
+    withOperatorAttestation(
+      {
+        v: 1,
+        op: 'update_apply',
+        request_id: updateRequestId,
+        args: {
+          ...(skipImages ? { skip_images: true } : {}),
+          ...(rebuild ? { rebuild: true } : {}),
+        },
+      },
+      updatePassphrase,
+    ),
+  )
   if (hostdResp === 'not-configured') {
     warnLegacySpawnIfHostdDisabled('update_apply')
     spawnSwitchroomDetached(
@@ -21705,6 +22955,7 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
   })
   pendingPermissions.delete(request_id)
   permCardStore.remove(request_id)
+  reconcileBlockedApprovals()
   process.stderr.write(
     `[telegram gateway] slash-${behavior} request_id=${request_id} tool=${details.tool_name} by=${senderId}\n`,
   )
@@ -23008,6 +24259,84 @@ bot.command("auth", async ctx => {
     return
   }
 
+  // `/auth google add|cancel` and `/auth microsoft add|cancel` — the
+  // Telegram-native OAuth loopback relay (issue #2582). Gateway-routed for the
+  // same reason as `/auth add`: they drive a child-process listener lifecycle
+  // the broker client can't model. Admin-gated identically.
+  if (parsed.kind === 'provider-add' || parsed.kind === 'provider-cancel') {
+    if (!isAuthAdmin({ isAdmin })) {
+      await switchroomReply(
+        ctx,
+        `**Not authorized.** \`/auth ${parsed.provider}\` is admin-only.\n` +
+          `Set \`admin: true\` on this agent in switchroom.yaml to unlock.`,
+        { html: true },
+      )
+      return
+    }
+    const loopKey = chatKey(chatId, ctx.message?.message_thread_id ?? null) as string
+    if (parsed.kind === 'provider-cancel') {
+      const existing = pendingLoopbackFlows.get(loopKey)
+      if (!existing) {
+        await switchroomReply(ctx, `_No pending \`/auth ${parsed.provider} add\` flow in this chat._`, { html: true })
+        return
+      }
+      cancelLoopbackFlow(existing)
+      pendingLoopbackFlows.delete(loopKey)
+      await switchroomReply(ctx, 'Cancelled.', { html: true })
+      return
+    }
+    // parsed.kind === 'provider-add'
+    if (pendingLoopbackFlows.has(loopKey)) {
+      await switchroomReply(
+        ctx,
+        `_An \`/auth ${parsed.provider} add\` flow is already in progress for this chat. ` +
+          `Finish the paste, or send \`/auth ${parsed.provider} cancel\` to abort._`,
+        { html: true },
+      )
+      return
+    }
+    try {
+      const { consentUrl, state, port, child } = await startLoopbackFlow(
+        parsed.provider,
+        parsed.email,
+        { replace: parsed.replace, write: parsed.write, orgMode: parsed.orgMode },
+      )
+      const newFlow = {
+        provider: parsed.provider,
+        email: parsed.email,
+        state,
+        port,
+        consentUrl,
+        child,
+        startedAt: Date.now(),
+        submitting: false,
+        attempts: 0,
+      }
+      // Record child exit on the flow so a pre-paste crash fails fast
+      // instead of hanging out the completion timeout (PR #3100 finding 4).
+      trackFlowExit(newFlow)
+      pendingLoopbackFlows.set(loopKey, newFlow)
+      const providerName = parsed.provider === 'google' ? 'Google' : 'Microsoft'
+      await switchroomReply(
+        ctx,
+        `**Adding ${providerName} account** \`${escapeHtmlForTg(parsed.email)}\`\n\n` +
+          `1. Open this URL on your phone and approve:\n${consentUrl}\n\n` +
+          `2. The redirect to \`127.0.0.1\` will fail to load — that's expected.\n` +
+          `3. Copy the **full URL** from your browser's address bar (it holds ` +
+          `\`?code=...&state=...\`) and paste it back here.\n\n` +
+          `Send \`/auth ${parsed.provider} cancel\` to abort.`,
+        { html: true },
+      )
+    } catch (err) {
+      await switchroomReply(
+        ctx,
+        `**/auth ${parsed.provider} add failed:** ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
+        { html: true },
+      )
+    }
+    return
+  }
+
   const client = await getAuthBrokerClient(currentAgent)
   if (!client) {
     await switchroomReply(ctx, "**/auth unavailable:** auth-broker client is not loaded (post-RFC-H rewire in progress?).", { html: true })
@@ -23201,6 +24530,9 @@ const callbackQueryHandlers = createCallbackQueryHandlers({
   getAdminOnlyKeys: () => ADMIN_ONLY_KEYS,
   vaultKeyRegex: VAULT_KEY_REGEX,
   mentalModelProposeTtlMs: MENTAL_MODEL_PROPOSE_TTL_MS,
+  // #2975 Stage 1 — loud-failure funnel for a rate-window retry that also
+  // failed (cooldown + record + broadcast in one place).
+  emitOperatorEvent: emitGatewayOperatorEvent,
 })
 const {
   handleVaultRecentDenialCallback,
@@ -23691,7 +25023,18 @@ bot.command('usage', async ctx => {
         // /auth snapshot does. switchroomReply routes through the rich path
         // (replyWithRichMessage), which accepts reply_markup. Build a grammy
         // InlineKeyboard so the markup type matches switchroomReply's contract.
-        const kbRows = buildSnapshotKeyboard(snapshots, { now: new Date(), demo })
+        // Defense-in-depth (mirrors the operator-private `/auth` treatment,
+        // gateway.ts ~24036): outside a private chat, strip the
+        // `auth:use:<label>` "Switch fleet" rows so the fleet-wide account-
+        // swap button is never even offered in a group/forum. The dispatch-
+        // site allowFrom gate is the load-bearing control; this just avoids
+        // dangling a privileged button in front of non-operators.
+        let kbRows = buildSnapshotKeyboard(snapshots, { now: new Date(), demo })
+        if (ctx.chat?.type !== 'private') {
+          kbRows = kbRows.filter(
+            (row) => !row.some((b) => b.callbackData?.startsWith('auth:use:')),
+          )
+        }
         const keyboard = new InlineKeyboard()
         kbRows.forEach((row, ri) => {
           if (ri > 0) keyboard.row()
@@ -23819,7 +25162,19 @@ bot.on('callback_query:data', async ctx => {
   // Auth dashboard buttons (`auth:<verb>:<agent>[:<slot>]`). Route
   // through a dedicated handler that maps each action onto the
   // existing CLI invocations plus dashboard refresh.
+  //
+  // Strict allowFrom gate like every other mutating callback family
+  // (`eff:`/`apv:`/`cfg:`/`cn:`/`mdl:`). Its absence was a vulnerability:
+  // `auth:use:<label>` drives `client.setActive(label)`, a fleet-wide
+  // OAuth account swap — on an admin forum/supergroup agent with an empty
+  // group allowFrom, any member could tap it and swap the active account.
   if (data.startsWith('auth:')) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
     await handleAuthDashboardCallback(ctx)
     return
   }
@@ -24634,8 +25989,74 @@ bot.on('callback_query:data', async ctx => {
     // opts out via `single_use: false`. With no stashed meta (e.g.
     // gateway restarted between send and tap) the default fires too,
     // which is the desired UX.
-    const stripKeyboard = metaForMessage == null || keyboardIsSingleUse(metaForMessage)
-    if (stripKeyboard && cbMessageId != null) {
+    const singleUse = metaForMessage == null || keyboardIsSingleUse(metaForMessage)
+
+    // Source message body text — photos/stickers/etc. carry no `text`.
+    const cbMsg = ctx.callbackQuery?.message
+    const sourceText = cbMsg && 'text' in cbMsg && typeof cbMsg.text === 'string'
+      ? cbMsg.text
+      : undefined
+
+    // #789: pure decision for the "✅ You chose: X" body annotation. Per-message
+    // override (the tapped button's inline_keyboard_confirm) wins over the agent
+    // default; fires only on single-use keyboards with body text + a label and
+    // the default 'html' parse mode.
+    const annotation = resolveTapAnnotation({
+      ...(tapMeta?.inline_keyboard_confirm != null
+        ? { perMessageOverride: tapMeta.inline_keyboard_confirm }
+        : {}),
+      singleUse,
+      ...(access.button_choice_confirmation != null
+        ? { config: access.button_choice_confirmation }
+        : {}),
+      parseMode: access.parseMode ?? 'html',
+      ...(sourceText != null ? { sourceText } : {}),
+      ...(buttonText != null ? { label: buttonText } : {}),
+      // escapeLabel deliberately omitted → defaults to the real HTML-entity
+      // escaper (escapeHtmlEntities). The GFM-markdown escaper
+      // (escapeHtmlForTg, #2669) is WRONG here: it doesn't escape &/</> (a
+      // label containing them would 400 the HTML editMessageText) and it
+      // garbles text under HTML parse mode (`Do_it` → `Do\_it`).
+    })
+
+    const warnKey = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    // Round-1 minor finding: a confirmation requested on a single_use:false
+    // (re-tappable) keyboard can never fire. Warn once per agent-process.
+    if (annotation.warnSingleUseMismatch && !buttonConfirmSingleUseWarned.has(warnKey)) {
+      buttonConfirmSingleUseWarned.add(warnKey)
+      process.stderr.write(
+        `telegram gateway: button_choice_confirmation skipped — inline_keyboard_confirm requested on a single_use:false (re-tappable) keyboard; annotation only fires on single-use keyboards (#789)\n`,
+      )
+    }
+    // Parse-mode gate (Blocker 1): annotation is emitted with HTML. Warn once
+    // per agent-process when a non-html parseMode suppresses it.
+    if (annotation.warnParseMode && !buttonConfirmParseModeWarned.has(warnKey)) {
+      buttonConfirmParseModeWarned.add(warnKey)
+      process.stderr.write(
+        `telegram gateway: button_choice_confirmation skipped — agent parseMode=${access.parseMode ?? 'html'}, only 'html' supported (#789)\n`,
+      )
+    }
+
+    if (annotation.annotate && cbMessageId != null) {
+      // Single API call (Blocker 2): editMessageText accepts reply_markup, so
+      // we annotate the body AND strip the keyboard in one edit. If the edit
+      // rejects (400 on an HTML edge case, over-long body, too-old message…),
+      // applyTapAnnotationEdit falls back to a keyboard-only strip so
+      // single-use protection still holds — the meta is deleted below either
+      // way, so a swallowed failure must not leave the keyboard live.
+      await applyTapAnnotationEdit(
+        {
+          editMessageText: (text, other) => ctx.editMessageText(text, other),
+          editMessageReplyMarkup: other => ctx.editMessageReplyMarkup(other),
+        },
+        annotation.text as string,
+      )
+      if (metaForMessage != null) {
+        agentButtonMeta.delete(`${cbChatId}:${cbMessageId}`)
+      }
+    } else if (singleUse && cbMessageId != null) {
+      // No annotation (disabled, non-single-use, non-html parseMode, or no
+      // body text) — preserve the historical keyboard-only strip.
       await ctx.editMessageReplyMarkup({
         reply_markup: { inline_keyboard: [] },
       }).catch(() => {})
@@ -24714,6 +26135,7 @@ bot.on('callback_query:data', async ctx => {
 
     pendingPermissions.delete(request_id)
     permCardStore.remove(request_id)
+    reconcileBlockedApprovals()
 
     // (2) Dispatch the in-flight permission verdict IMMEDIATELY — before
     // any host round-trip — so the turn never blocks on persistence.
@@ -25009,6 +26431,7 @@ bot.on('callback_query:data', async ctx => {
   const grantAgent = selfAgentName()
   pendingPermissions.delete(request_id)
   permCardStore.remove(request_id)
+  reconcileBlockedApprovals()
   if (timeBox && grantAgent) {
     recordScopedGrant(scopedGrants, grantAgent, timeBox.rule, Date.now(), scopedTtl)
     // Write-through so the window survives a gateway restart (#2863). Absolute
@@ -25453,9 +26876,7 @@ async function handleAckOnly(
     const chat_id = String(ctx.chat!.id)
     const msgId = ctx.message?.message_id
     if (msgId != null) {
-      void bot.api.setMessageReaction(chat_id, msgId, [
-        { type: 'emoji', emoji: (opts.emoji ?? '👀') as ReactionTypeEmoji['emoji'] },
-      ]).catch(() => {})
+      void sendReaction(chat_id, msgId, (opts.emoji ?? '👀') as ReactionTypeEmoji['emoji']).catch(() => {})
     }
     const prefix = opts.warn ? 'WARN ' : ''
     process.stderr.write(`telegram gateway: ${prefix}inbound ${kind} ack-only chat_id=${chat_id} from=${ctx.from?.id ?? '?'}\n`)
@@ -25488,9 +26909,7 @@ async function handleRefusal(
     const msgId = ctx.message?.message_id
     const messageThreadId = ctx.message?.message_thread_id
     if (msgId != null) {
-      void bot.api.setMessageReaction(chat_id, msgId, [
-        { type: 'emoji', emoji: '🚫' as ReactionTypeEmoji['emoji'] },
-      ]).catch(() => {})
+      void sendReaction(chat_id, msgId, '🚫' as ReactionTypeEmoji['emoji']).catch(() => {})
     }
     // #1075: thread-id-bearing — swallow on THREAD_NOT_FOUND so a
     // deleted topic doesn't crash the refusal handler.
@@ -26049,16 +27468,22 @@ function flushReactionBatch(batch: ReactionBatch): void {
     text,
     meta,
   }
-  const delivered = ipcServer.sendToAgent(agentName, inbound)
-  if (delivered) markClaudeBusyForInbound(inbound)
+  // #2094 finding 3 — route the reaction flush through the SAME #1556
+  // decideInboundDelivery gate every other synthetic inbound uses (via
+  // deliverResumeSyntheticOrBuffer), instead of a raw ipcServer.sendToAgent.
+  // A reaction that lands WHILE a turn is in flight was previously fired
+  // mid-turn — the bridge typed it into the CLI composer where it stranded
+  // by the turn-completion race (the #1556 composer wedge). Now a mid-turn
+  // reaction buffers-until-idle (the turn-complete hook + idle-drain timer
+  // flush pendingInboundBuffer the instant claude goes idle, landing cleanly
+  // as a fresh turn); an idle reaction delivers now, buffering only on a
+  // genuine bridge-offline miss — the #1150 buffer-on-failure guarantee,
+  // preserved inside the helper.
+  const delivered = deliverResumeSyntheticOrBuffer(agentName, inbound)
   process.stderr.write(
     `telegram gateway: reactions.dispatch agent=${agentName} chat=${batch.chatId} ` +
     `count=${batch.reactions.length} batched=${batch.batched} delivered=${delivered}\n`,
   )
-  // #1150: buffer-on-failure for reaction-triggered wake-ups too.
-  if (!delivered) {
-    pendingInboundBuffer.push(agentName, inbound)
-  }
 }
 
 // ─── Inbound message_reaction handler ────────────────────────────────────
@@ -26506,6 +27931,10 @@ async function shutdown(signal: string): Promise<void> {
   // Now finish the cleanup the drain didn't touch.
   inboundCoalescer.reset()
   pendingReauthFlows.clear()
+  // Kill any in-flight loopback relay CLI children so they don't outlive the
+  // gateway with a bound 127.0.0.1 listener (issue #2582).
+  for (const [, v] of pendingLoopbackFlows) cancelLoopbackFlow(v)
+  pendingLoopbackFlows.clear()
   pendingVaultOps.clear()
   pendingPermissions.clear()
   permissionTimeoutSignatures.clear()
@@ -26539,7 +27968,7 @@ process.on('SIGINT', () => void shutdown('SIGINT'))
   if (startupAgentDir != null) {
     void sweepActiveReactions(
       startupAgentDir,
-      (chatId, messageId) => lockedBot.api.setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji: '👍' as ReactionTypeEmoji['emoji'] }]),
+      (chatId, messageId) => sendReaction(chatId, messageId, '👍' as ReactionTypeEmoji['emoji']),
       { log: (msg) => process.stderr.write(`telegram gateway: startup reaction sweep — ${msg}\n`) },
     )
   }
@@ -26949,6 +28378,22 @@ void (async () => {
           )
         }
 
+        // #3084 follow-up — drop a blocked-approval record orphaned by a restart
+        // mid-hold. `pendingPermissions` is in-memory and empty on a fresh
+        // process, so this reconciles the surface to "nothing held". Without it,
+        // a gateway restart during a flood ban would leave a record on disk that
+        // nothing ever clears, and the dashboard would show a permanently
+        // blocked agent. The ASK itself survives: the bridge re-sends unresolved
+        // permission requests on IPC reconnect, which re-raises them (and
+        // re-marks them held if the channel is still shut).
+        try {
+          reconcileBlockedApprovals()
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: blocked-approval boot reconcile failed: ${(err as Error).message}\n`,
+          )
+        }
+
         // Boot-time pin sweep
         try {
           const bootAccess = loadAccess()
@@ -27382,7 +28827,8 @@ void (async () => {
                         richMessage(text),
                         sendOpts as Parameters<typeof lockedBot.api.sendRichMessage>[2],
                       ),
-                    { chat_id: cid, verb: 'worker-feed' },
+                    // #3084 PR 2: worker-feed card CREATION (handback) is USEFUL.
+                    { chat_id: cid, verb: 'worker-feed', priorityClass: 'useful' },
                   )
                   return sent as { message_id: number }
                 },
@@ -27395,7 +28841,15 @@ void (async () => {
                         richMessage(text),
                         editOpts as Parameters<typeof lockedBot.api.editMessageText>[3],
                       ),
-                    { chat_id: cid, verb: 'worker-feed' },
+                    // Worker-feed EDITs are COSMETIC — pass messageId/editPayload
+                    // so the per-message floor + coalescing + no-op skip engage.
+                    {
+                      chat_id: cid,
+                      verb: 'worker-feed',
+                      priorityClass: 'cosmetic',
+                      messageId: mid,
+                      editPayload: text,
+                    },
                   ),
               },
               log: (msg) => process.stderr.write(`telegram gateway: ${msg}\n`),
@@ -27423,30 +28877,41 @@ void (async () => {
               // Best-effort: a registry read failure (e.g. no worktree dir
               // on an agent that never claims one) must not affect the
               // primary agentCwd watch.
-              extraWatchCwdsProvider: () =>
-                // Fail-CLOSED ownership filter (unset identity ⇒ nothing;
-                // ownerless records excluded; registry throw ⇒ []). Extracted
-                // to telegram-plugin/worktree-watch-cwds.ts so the #1116 /
-                // Gap-2 ownership predicate is under direct unit test — see
-                // telegram-plugin/tests/worktree-watch-cwds.test.ts.
-                ownedWorktreeCwds({
-                  self: process.env.SWITCHROOM_AGENT_NAME,
-                  listRecords: listWorktreeRecords,
-                  // Durable, non-env identity fallback (#1116 / #2893): when
-                  // SWITCHROOM_AGENT_NAME is somehow unset, derive this
-                  // agent's own identity from its own directory so worktree
-                  // ownership still resolves (env is only the fast path).
-                  // `watcherAgentDir` is guaranteed non-null in this branch
-                  // (the whole watcher is gated on it above). Kill-switch
-                  // SWITCHROOM_WORKTREE_IDENTITY_FALLBACK=0 restores the
-                  // pre-fix env-only behaviour.
-                  agentDir:
-                    process.env.SWITCHROOM_WORKTREE_IDENTITY_FALLBACK === '0'
-                      ? undefined
-                      : watcherAgentDir,
-                  log: (msg) =>
-                    process.stderr.write(`telegram gateway: ${msg}\n`),
-                }),
+              // On every ~1s rescan tick the provider does BOTH:
+              //   1. advances the heartbeat of every worktree THIS agent owns
+              //      — the F1/H3 production driver that keeps `touchHeartbeat`
+              //      alive (it had ZERO callers, so every claim read "stale"
+              //      10 min after creation and the reaper's staleness
+              //      guarantee collapsed); throttled to ≤1 write / 2 min per
+              //      record, and
+              //   2. returns the fail-CLOSED set of owned worktree cwds for the
+              //      watcher to also watch (#1116 / Gap-2 ownership predicate).
+              // Extracted to telegram-plugin/worktree-watch-cwds.ts as
+              // `makeWorktreeWatchProvider` so the wiring — specifically that
+              // the provider ACTUALLY drives heartbeats, not just cwds — is
+              // under direct unit test (see the provider behaviour test in
+              // telegram-plugin/tests/worktree-watch-cwds.test.ts). Fully
+              // best-effort: it never throws out of the provider.
+              extraWatchCwdsProvider: makeWorktreeWatchProvider({
+                self: process.env.SWITCHROOM_AGENT_NAME,
+                // Durable, non-env identity fallback (#1116 / #2893): when
+                // SWITCHROOM_AGENT_NAME is somehow unset, derive this agent's
+                // own identity from its own directory so worktree ownership
+                // still resolves (env is only the fast path). `watcherAgentDir`
+                // is guaranteed non-null in this branch (the whole watcher is
+                // gated on it above). Kill-switch
+                // SWITCHROOM_WORKTREE_IDENTITY_FALLBACK=0 restores the pre-fix
+                // env-only behaviour. One `agentDir` governs BOTH the heartbeat
+                // refresh and the cwd derivation.
+                agentDir:
+                  process.env.SWITCHROOM_WORKTREE_IDENTITY_FALLBACK === '0'
+                    ? undefined
+                    : watcherAgentDir,
+                listRecords: listWorktreeRecords,
+                touchHeartbeat: touchWorktreeHeartbeat,
+                log: (msg) =>
+                  process.stderr.write(`telegram gateway: ${msg}\n`),
+              }),
               // Bug 0 fix: previously omitted, leaving the watcher unable to
               // write liveness/stall/turn_end updates to the registry DB.
               // Liveness writes are now persisted across the gateway lifetime.