switchroom 0.18.12 → 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,
@@ -340,6 +341,7 @@ import {
 } from '../telegram-button-constraints.js'
 import {
   wrapAgentCallbacks,
+  redactAgentKeyboard,
   parseAgentCallback,
   extractAgentButtonMeta,
   keyboardIsSingleUse,
@@ -691,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,
@@ -5466,9 +5468,10 @@ const recordFloodWindow = makeFloodWindowRecorder(FLOOD_WINDOWS_PATH)
 // 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). Feature-flagged, default OFF: when SWITCHROOM_TELEGRAM_SEND_GATE !== '1'
-// the gate is a pure passthrough and the retry policy behaves exactly as
-// before. Composes with #3094's pre-call flood gate and #3097's non-essential
+// 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.
 //
@@ -5527,6 +5530,65 @@ const swallowingApiCall = createSwallowingRetryApiCall(
   (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).
  *
@@ -11724,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 } : {}),
@@ -11809,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})` }] }
@@ -12537,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
@@ -13509,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
@@ -14609,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' }] }
 }
 
@@ -17590,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
@@ -17624,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.
@@ -17976,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: '👀' })
@@ -18219,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')
     }
@@ -18266,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
@@ -18402,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
   }
@@ -18460,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
@@ -18492,7 +18614,7 @@ async function handleInbound(
           '_Still finishing the previous paste — one moment._',
           { html: true },
         )
-        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
       }
       const result = await submitLoopbackRedirect(pendingLoop, text.trim())
@@ -18505,7 +18627,7 @@ async function handleInbound(
           { html: true },
         )
         // Redact the pasted redirect (carries the OAuth code) from history.
-        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
       }
       if (result.retryable) {
@@ -18518,7 +18640,7 @@ async function handleInbound(
           { html: true },
         )
         // Redact even a rejected paste — it may still carry a live code.
-        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
       }
       // Non-retryable — the flow is spent. Kill the CLI child before
@@ -18533,7 +18655,7 @@ async function handleInbound(
         `**/auth ${pendingLoop.provider} add failed:** ${escapeHtmlForTg(result.reason)}`,
         { html: true },
       )
-      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 — the intercept window has closed. Kill the child and drop the
@@ -18553,7 +18675,7 @@ async function handleInbound(
   // reference AND a code/error param), so ordinary chatter mentioning
   // localhost flows through untouched. Redact and drop rather than forward.
   if (shouldConsumeLoopbackPaste(text)) {
-    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))
     await switchroomReply(
       ctx,
       '_That looked like an OAuth redirect/code, so I removed it from chat and did not forward it. ' +
@@ -18588,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)
@@ -19051,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 {
@@ -19099,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, {
@@ -19184,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 })
     }
@@ -20529,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) {
@@ -24905,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()
@@ -25033,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
   }
@@ -26735,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`)
@@ -26770,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.
@@ -27831,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`) },
     )
   }
@@ -28740,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.

package/telegram-plugin/history.ts

@@ -178,6 +178,57 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     }
   }
 
+  // Migration (review finding H5): make INSERT OR REPLACE idempotent for thread-less rows.
+  //
+  // The table's PRIMARY KEY is (chat_id, thread_id, message_id), but thread_id
+  // is nullable and SQLite treats NULL as DISTINCT from NULL in a PK/UNIQUE
+  // index. Every DM and every non-topic group message has thread_id = NULL, so
+  // two inserts of the same (chat_id, message_id) with NULL thread do NOT
+  // conflict — `INSERT OR REPLACE` APPENDS a duplicate row instead of replacing
+  // it. On the documented at-least-once boot replay / synthesized-resume
+  // re-record, an already-stored message is duplicated, inflating
+  // get_recent_messages and the getRecentOutboundCount / hasOutboundDeliveredSince
+  // counters that feed the silence / over-ping detectors.
+  //
+  // Fix: a UNIQUE index over COALESCE(thread_id, '') gives every logical
+  // (chat, thread-or-general, message_id) key a NON-null uniqueness value, so
+  // REPLACE conflict-resolves and dedupes thread-less rows too. INSERT OR
+  // REPLACE resolves against ANY unique index, so no writer change is needed.
+  // A forum-topic row (non-null thread) and a general row (NULL thread) that
+  // share a message_id keep DISTINCT keys (the topic id vs ''), so they stay
+  // separate. Stored thread_id values remain real NULLs, so every read path
+  // (`thread_id IS NULL` / `thread_id = ?`) is unchanged.
+  const LOGICAL_KEY_INDEX = 'idx_messages_logical_key'
+  const logicalKeyIndexExists =
+    db
+      .prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?`)
+      .get(LOGICAL_KEY_INDEX) != null
+  if (!logicalKeyIndexExists) {
+    // De-dupe rows an earlier (pre-fix) build already appended, keeping the
+    // NEWEST row per logical key (highest ts, then highest rowid = the last
+    // write, which is what INSERT OR REPLACE would have left). This MUST run
+    // before the UNIQUE index is created, or CREATE UNIQUE INDEX would fail on
+    // the existing duplicates. On a fresh/empty DB it is a harmless no-op.
+    db.exec(`
+      DELETE FROM messages
+      WHERE rowid NOT IN (
+        SELECT keep_rowid FROM (
+          SELECT rowid AS keep_rowid,
+                 ROW_NUMBER() OVER (
+                   PARTITION BY chat_id, COALESCE(thread_id, ''), message_id
+                   ORDER BY ts DESC, rowid DESC
+                 ) AS rn
+          FROM messages
+        )
+        WHERE rn = 1
+      )
+    `)
+    db.exec(
+      `CREATE UNIQUE INDEX IF NOT EXISTS ${LOGICAL_KEY_INDEX} ` +
+        `ON messages (chat_id, COALESCE(thread_id, ''), message_id)`,
+    )
+  }
+
   // Readable by owner and others so the web dashboard (different uid than the
   // agent) can stream replies back to Hermes Desktop. The WAL sidecar files
   // (-shm/-wal) are also chmod'd so SQLite readonly opens succeed for uid=1000.