switchroom 0.16.47 → 0.17.1

package/telegram-plugin/dist/server.js

@@ -17208,7 +17208,7 @@ function findActiveSessionFile(projectsDir) {
 }
 function parseChannelMeta(content) {
   const grab = (key) => {
-    const m = content.match(new RegExp(`${key}="([^"]+)"`));
+    const m = content.match(new RegExp(`(?:^|[\\s"'])${key}="([^"]+)"`));
     return m ? m[1] : null;
   };
   return {
@@ -17414,7 +17414,12 @@ function projectSubagentLine(line, agentId, state) {
       if (ct === "tool_use") {
         const name = c.name ?? "";
         if (name === "Agent" || name === "Task") {
-          events.push({ kind: "sub_agent_nested_spawn", agentId });
+          events.push({
+            kind: "sub_agent_nested_spawn",
+            agentId,
+            toolUseId: c.id ?? null,
+            input: c.input ?? undefined
+          });
         } else {
           events.push({
             kind: "sub_agent_tool_use",
@@ -24098,7 +24103,6 @@ var ALWAYS_LOAD_TOOLS, LINEAR_TOOLS, LINEAR_ENV = "SWITCHROOM_TELEGRAM_LINEAR";
 var init_tool_filter = __esm(() => {
   ALWAYS_LOAD_TOOLS = new Set([
     "reply",
-    "stream_reply",
     "get_recent_messages",
     "react",
     "edit_message",
@@ -24347,7 +24351,7 @@ var init_bridge = __esm(async () => {
     instructions: [
       "The sender reads Telegram, not this session. Anything you want them to see must go through the reply tool \u2014 your transcript output never reaches their chat.",
       "",
-      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file \u2014 it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings \u2014 image_path_2, image_path_3, \u2026 (Read each) and attachment_file_id_2, attachment_file_id_3, \u2026 (download_attachment each). Process every one, not just the first. Reply with the reply tool \u2014 pass chat_id back. The reply and stream_reply tools quote-reply to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
+      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file \u2014 it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. A single message may carry SEVERAL attachments (a forwarded album or a text+multi-image burst): when attachment_count is set (>1), also handle the numbered siblings \u2014 image_path_2, image_path_3, \u2026 (Read each) and attachment_file_id_2, attachment_file_id_3, \u2026 (download_attachment each). Process every one, not just the first. Reply with the reply tool \u2014 pass chat_id back. The reply tool quote-replies to the latest inbound user message by default, so you do NOT need to pass reply_to for normal responses. Pass reply_to (a message_id) only when quoting a specific earlier message, or pass quote:false to send a bare (non-quoted) message.',
       "",
       `reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, edit_message for interim progress updates, and delete_message when you need to truly remove a message (prefer edit_message if you just want to change text \u2014 delete is for retraction). Edits don't trigger push notifications \u2014 when a long task completes, send a new reply so the user's device pings. Use send_typing to show a typing indicator during long operations. Use pin_message to pin important outputs. Use forward_message to quote/resurface earlier messages.`,
       "",
@@ -24402,45 +24406,6 @@ var init_bridge = __esm(async () => {
         required: ["chat_id", "text"]
       }
     },
-    {
-      name: "stream_reply",
-      description: "Post the final answer for this turn. The plugin renders an event-driven progress card (Plan \u2192 Run \u2192 Done with live tool bullets, elapsed time, and status emoji) for free while the turn is in-flight, so you do not need to narrate intermediate progress. Call `stream_reply` exactly once per turn with done=true and the complete answer text. Hard cap is 32768 chars (the rich-message wire limit) \u2014 longer text is dropped by a defensive guard, so use `reply` for anything that long (it chunks). Calling with done=false is an error in this environment (the progress card already owns the mid-turn surface). inline_keyboard adds tappable buttons under the final message \u2014 see `reply` for shape and constraints.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          chat_id: { type: "string" },
-          text: { type: "string", description: "Full text snapshot. NOT a delta \u2014 pass the complete current content each call." },
-          done: { type: "boolean", description: "Must be true. Posts this text as the final answer for the turn and locks the message." },
-          message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message if not specified." },
-          origin_turn_id: { type: "string", description: "In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message's topic even if another topic's turn started meanwhile. Omit in DMs / single-topic chats." },
-          format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
-          reply_to: { type: "string", description: "Message ID to quote-reply to. Overrides the default (latest inbound)." },
-          quote: { type: "boolean", description: "Opt out of the default quote-reply behavior. Default: true. Ignored when reply_to is explicitly set." },
-          protect_content: { type: "boolean", description: "When true, Telegram prevents the message from being forwarded or saved." },
-          quote_text: { type: "string", description: "Surgical quote: specific text to highlight from the reply_to message. Requires reply_to." },
-          disable_notification: { type: "boolean", description: "When true, the INITIAL message send is silent (no device ping). Has no effect on subsequent edits \u2014 Telegram never pings on editMessageText. Default false. Use for mid-turn stream starts you do not want to ping; omit on the final answer." },
-          inline_keyboard: {
-            type: "array",
-            description: '2D array of tappable buttons under the final message. Same shape and constraints as `reply.inline_keyboard` \u2014 each button has `text` and EXACTLY ONE of `url` or `callback_data`, plus optional `ack_text` (custom tap-toast; default "\u2713 received") and `single_use` (default true; set false to keep the keyboard tappable after a tap). Tap on a callback_data button is delivered to this agent as an inbound channel event with meta.button_callback_data set.',
-            items: {
-              type: "array",
-              items: {
-                type: "object",
-                properties: {
-                  text: { type: "string" },
-                  url: { type: "string" },
-                  callback_data: { type: "string" },
-                  ack_text: { type: "string", description: 'Toast text shown on tap. Default "\u2713 received".' },
-                  single_use: { type: "boolean", description: "Default true. Set false to keep the keyboard tappable after this button is tapped." }
-                },
-                required: ["text"]
-              }
-            }
-          }
-        },
-        required: ["chat_id", "text"]
-      }
-    },
     {
       name: "react",
       description: "Add an emoji reaction to a Telegram message. Telegram only accepts a fixed whitelist (\uD83D\uDC4D \uD83D\uDC4E \u2764 \uD83D\uDD25 \uD83D\uDC40 \uD83C\uDF89 etc) \u2014 non-whitelisted emoji will be rejected.",

package/telegram-plugin/format.ts

@@ -132,8 +132,18 @@ export function repairEscapedWhitespace(text: string): string {
 interface MaskedCode {
   masked: string
   restore: (s: string) => string
-  /** The placeholder prefix injected for each masked region (fence or span). */
+  /**
+   * The placeholder prefix injected for FENCED-BLOCK masks only. A masked
+   * fenced block occupies a whole line, so `isFenceOpenLine` / `isMarkerLine`
+   * treat a line that STARTS with this prefix as a block construct. INLINE
+   * code spans get a DISTINCT prefix (see maskCodeRegions) that deliberately
+   * does NOT start with this one — so a line that merely opens with an inline
+   * span (e.g. `\`key\` = \`value\``) reads as ordinary prose and still gets
+   * its line break hardened.
+   */
   placeholder: string
+  /** Remove EVERY mask (fenced + inline) — used to measure visible length. */
+  stripPlaceholders: (s: string) => string
 }
 
 /**
@@ -144,31 +154,40 @@ interface MaskedCode {
  * Fenced blocks are extracted FIRST and only when CLOSED (matching ```), so an
  * unclosed fence is left intact rather than misparsed by the inline pass. Inline
  * spans use `[^\`\n]+` — the same definition the chunker treats as code.
+ *
+ * Fenced and inline masks carry DISTINCT prefixes (`\x00RMF…` vs `\x00RMI…`).
+ * This matters because the fenced prefix is what the block-structure predicates
+ * (`isFenceOpenLine`, `isMarkerLine`) use to recognise a standalone masked code
+ * block. Sharing one prefix (the pre-fix bug) made a line that merely STARTS
+ * with an inline code span look like a fenced block, so its lone `\n` was never
+ * hardened and the card collapsed into one run-on line (real victim:
+ * `/vault get` rendering `\`key\` = \`value\``).
  */
 function maskCodeRegions(text: string, nonce: string): MaskedCode {
-  const CODE_MASK_PH = `\x00RM${nonce}_`
+  const FENCE_MASK_PH = `\x00RMF${nonce}_`
+  const INLINE_MASK_PH = `\x00RMI${nonce}_`
   const codeMasks: string[] = []
 
   const masked = text
     .replace(/```[\s\S]*?```/g, (m) => {
       const idx = codeMasks.length
       codeMasks.push(m)
-      return `${CODE_MASK_PH}${idx}\x00`
+      return `${FENCE_MASK_PH}${idx}\x00`
     })
     .replace(/`[^`\n]+`/g, (m) => {
       const idx = codeMasks.length
       codeMasks.push(m)
-      return `${CODE_MASK_PH}${idx}\x00`
+      return `${INLINE_MASK_PH}${idx}\x00`
     })
 
-  const restoreRe = new RegExp(
-    `${CODE_MASK_PH.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)\x00`,
-    'g',
-  )
+  // Restore / strip match EITHER prefix, keyed on the shared index space.
+  const escNonce = nonce.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const anyMaskRe = new RegExp(`\x00RM[FI]${escNonce}_(\\d+)\x00`, 'g')
   const restore = (s: string): string =>
-    s.replace(restoreRe, (_m, idx) => codeMasks[Number(idx)] ?? _m)
+    s.replace(anyMaskRe, (_m, idx) => codeMasks[Number(idx)] ?? _m)
+  const stripPlaceholders = (s: string): string => s.replace(anyMaskRe, '')
 
-  return { masked, restore, placeholder: CODE_MASK_PH }
+  return { masked, restore, placeholder: FENCE_MASK_PH, stripPlaceholders }
 }
 
 // ---------------------------------------------------------------------------
@@ -344,6 +363,92 @@ export function normalizeParagraphBreaks(text: string): string {
   return restore(out)
 }
 
+// ---------------------------------------------------------------------------
+// Card line-break hardener — for DETERMINISTIC command/card bodies
+// ---------------------------------------------------------------------------
+
+/**
+ * Harden the lone `\n` line breaks of a DETERMINISTIC card body into GFM hard
+ * breaks (`  \n`, two trailing spaces) so every field lands on its own line
+ * under Telegram's Bot API 10.1 rich-message (GFM) renderer.
+ *
+ * Why this exists (the run-on-blob bug): the rich path (#2669) renders a lone
+ * `\n` between two non-blank lines as a *soft* break — the two lines collapse
+ * onto the same visual line with a space between them. Agent PROSE is repaired
+ * on the reply path by `normalizeParagraphBreaks`, but the ~98 slash-command
+ * card replies dispatched through `switchroomReply(…, { html: true })` are sent
+ * as RAW markdown with no normalization. Their builders stack short labelled
+ * fields (`**5h window** …`, `**Model** …`, `Auth: ✓ Max …`) joined by a single
+ * `\n`, so the whole card renders as one run-on blob.
+ *
+ * A deterministic card is NOT free prose — every newline its builder emits is
+ * an INTENDED line break. So this hardener promotes UNCONDITIONALLY (no
+ * sentence-terminal-punctuation gate, unlike `normalizeParagraphBreaks`) with
+ * one exception: a line that participates in a genuine GFM block construct
+ * (list / table / blockquote / heading / fenced code) keeps its single `\n` so
+ * its native stacking / contiguity survives — a monospace table inside a ```
+ * fence is never touched (it is code-masked AND the fence lines are excluded).
+ * Real `\n\n` paragraph gaps (a builder's block separators) are preserved.
+ *
+ * This is the string-level sibling of `stackCardLines` (card-format.ts), which
+ * does the same promotion from a pre-split `string[]` of guaranteed
+ * single-line, non-block entries. Use `hardenCardBreaks` where the card body is
+ * already an assembled string (e.g. the `switchroomReply` chokepoint) and may
+ * legitimately contain GFM block constructs.
+ *
+ * Runs on code-masked text and is idempotent — a break already hardened to
+ * `  \n` re-hardens to the same `  \n`.
+ */
+export function hardenCardBreaks(text: string): string {
+  if (!text.includes('\n')) return text
+
+  const nonce = Math.random().toString(36).slice(2)
+  const { masked, restore, placeholder } = maskCodeRegions(text, nonce)
+
+  // Collapse 3+ newline runs to a single clean `\n\n` gap (mirrors
+  // normalizeParagraphBreaks step 1) so a stray extra blank line never becomes
+  // an oversized gap. A genuine one-blank-line `\n\n` block gap is preserved.
+  const out = masked.replace(/\n{3,}/g, '\n\n')
+
+  // A line participating in a GFM block construct whose single-`\n` contiguity
+  // must survive (its interior must NOT get a hard break).
+  const isBlockConstructLine = (line: string): boolean =>
+    isListItemLine(line) ||
+    isTableRowLine(line) ||
+    isTableDelimiterLine(line) ||
+    isBlockquoteLine(line) ||
+    isHeadingLine(line) ||
+    isFenceOpenLine(line, placeholder)
+
+  const lines = out.split('\n')
+  const pieces: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i]
+    const isLast = i === lines.length - 1
+    const next = isLast ? '' : lines[i + 1]
+    // Promote only between two non-blank content lines where NEITHER is a GFM
+    // block-construct line (so lists / tables / quotes / headings / fences keep
+    // their native single-`\n` stacking). A blank current/next line is a `\n\n`
+    // paragraph gap — never promote across it.
+    const promote =
+      !isLast &&
+      line.trim() !== '' &&
+      next.trim() !== '' &&
+      !isBlockConstructLine(line) &&
+      !isBlockConstructLine(next)
+    if (promote) {
+      // Strip trailing whitespace so a re-run emits exactly one `  \n` (never
+      // accumulate spaces). Include `\r` for CRLF sources.
+      line = line.replace(/[ \t\r]+$/, '')
+    }
+    pieces.push(line)
+    if (isLast) break
+    pieces.push(promote ? '  \n' : '\n')
+  }
+
+  return restore(pieces.join(''))
+}
+
 // ---------------------------------------------------------------------------
 // Paragraph spacers — restore a VISIBLE blank line between prose paragraphs
 // ---------------------------------------------------------------------------
@@ -623,14 +728,11 @@ export function stripExcessBold(text: string): string {
   if (!text.includes('**')) return text
 
   const nonce = Math.random().toString(36).slice(2)
-  const { masked, restore, placeholder } = maskCodeRegions(text, nonce)
+  const { masked, restore, placeholder, stripPlaceholders } = maskCodeRegions(text, nonce)
 
-  // Non-code character budget: masked text with the placeholders removed.
-  const placeholderRe = new RegExp(
-    `${placeholder.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\d+\x00`,
-    'g',
-  )
-  const visible = masked.replace(placeholderRe, '')
+  // Non-code character budget: masked text with BOTH fenced + inline masks
+  // removed (stripPlaceholders handles the two distinct prefixes).
+  const visible = stripPlaceholders(masked)
   if (visible.length < 100) return restore(masked)
 
   let boldChars = 0

package/telegram-plugin/gateway/approvals-commands.ts

@@ -13,7 +13,7 @@
  * add on top of the same client. Tracked in the migration TODO inline.
  */
 
-import { escapeMarkdown, codeSpanSafe } from '../format.js';
+import { escapeMarkdown, codeSpanSafe, hardenCardBreaks } from '../format.js';
 import type { Bot, Context } from "grammy";
 import { richMessage } from "../rich-send.js";
 import {
@@ -84,7 +84,11 @@ export function registerApprovalsCommands(
           );
         })
         .join("\n");
-      await ctx.replyWithRichMessage(richMessage(`**Active approvals**\n\n${summary}\n\n${detail}`));
+      // hardenCardBreaks: the per-agent `summary` rows and per-decision
+      // `detail` rows are single-`\n`-joined field lines that would soft-
+      // collapse into one blob under the GFM rich renderer. Harden them into
+      // GFM hard breaks (block gaps between the three sections preserved).
+      await ctx.replyWithRichMessage(richMessage(hardenCardBreaks(`**Active approvals**\n\n${summary}\n\n${detail}`)));
       return;
     }
 

package/telegram-plugin/gateway/busy-key-reaper.ts

@@ -0,0 +1,113 @@
+/**
+ * #2787 Mechanism B — the `claudeBusyKeys` orphan-reaper lifecycle, extracted
+ * so the gateway glue that mutates the busy-key set stays in lockstep with its
+ * shadow insertion-timestamp map and is unit-testable WITHOUT importing
+ * `gateway.ts` (which boots the bot + IPC listener on module load and so cannot
+ * run inside a unit test). The gateway keeps ownership of the two containers
+ * (`claudeBusyKeys: Set`, `claudeBusyKeySince: Map`) and calls these helpers at
+ * every mark / reap site; `disconnect-flush.ts` clears them at bridge death.
+ * The test harness (`tests/busy-key-reaper.test.ts`) wires the SAME containers,
+ * the SAME delivery queue, and the real `flushOnAgentDisconnect` to reproduce
+ * the disconnect → reconnect → re-mark and slow-vs-orphan delivery sequences.
+ *
+ * Two invariants this module enforces:
+ *
+ *  1. LOCKSTEP. The timestamp map shadows actual SET MEMBERSHIP, not its own
+ *     prior presence. `markBusyKeyLockstep` stamps a fresh timestamp whenever a
+ *     key transitions idle→busy (`claudeBusyKeys.has(key) === false`). Gating on
+ *     the set — not on `since.has` — is load-bearing: a disconnect flush clears
+ *     `claudeBusyKeys` directly, so if the shadow map ever lagged, a `!since.has`
+ *     guard would decline to re-stamp on the reconnect→re-mark and leave a
+ *     stale, >TTL-old timestamp on a freshly-marked key — which the reaper would
+ *     then reap out from under a live delivery.
+ *
+ *  2. SLOW-DELIVERY SAFETY (the #1922 hazard). `busy` is marked EAGERLY at
+ *     delivery, and the gateway→claude enqueue-ack lag can be up to ~5 MINUTES
+ *     under load (#1922). During that eager-mark→enqueue window the gateway's
+ *     `currentTurn` is null yet the turn is real-and-merely-slow. A bare
+ *     time-grace reaper cannot tell "slow" from "orphaned" and would reap a
+ *     genuine delivery, re-opening the idle-drain gate while claude is about to
+ *     process the very inbound whose key it just reaped (duplicate / concurrent
+ *     delivery on the CORE inbound path). So the reap is PROOF-GATED: a key is
+ *     reaped ONLY when it has NO entry in the delivery-confirm queue. A
+ *     slow-but-real inbound is tracked there from delivery until claude's
+ *     `enqueue` ack (via the never-drop re-deliver loop), so any key still
+ *     awaiting its turn is present and skipped — no matter how slow. The time
+ *     grace is retained as defense-in-depth, defaulting well above the observed
+ *     ack-lag tail. Only a busy-marked key with NO pending delivery AND age past
+ *     the grace is a true orphan (its turn acked and should have cleared busy at
+ *     turn_end, or it was a steer/interrupt inbound excluded from tracking that
+ *     amends a now-absent turn) — reaping those can never clobber a slow one.
+ */
+
+/** Lockstep mark: add to the busy set and, on the idle→busy transition only,
+ *  stamp the insertion time. Keyed on set membership so a re-mark after a
+ *  disconnect flush (which cleared the set directly) always re-stamps fresh. */
+export function markBusyKeyLockstep(
+  keys: Set<string>,
+  since: Map<string, number>,
+  key: string,
+  now: number,
+): void {
+  const wasBusy = keys.has(key)
+  keys.add(key)
+  if (!wasBusy) since.set(key, now)
+}
+
+/** Lockstep clear: delete from both containers. */
+export function clearBusyKeyLockstep(
+  keys: Set<string>,
+  since: Map<string, number>,
+  key: string,
+): void {
+  keys.delete(key)
+  since.delete(key)
+}
+
+export interface ReapOptions {
+  /** Grace before a busy-marked key with no pending delivery is a true orphan. */
+  ttlMs: number
+  /** True iff a delivery-confirm entry is still tracked for this key — i.e. a
+   *  slow-but-real inbound awaiting its enqueue ack. Such keys are NEVER reaped,
+   *  regardless of age (the #1922 slow-delivery guarantee). */
+  hasPendingDelivery: (key: string) => boolean
+  /** Optional line logger for each reaped key (observability). */
+  log?: (msg: string) => void
+}
+
+/**
+ * Reap orphaned busy markers. Call ONLY once the gateway has asserted no turn is
+ * in flight (`currentTurn == null`). Returns the keys reaped (for the caller's
+ * metrics / assertions). Also prunes shadow-map entries whose key already left
+ * the set, so the map can't grow unbounded.
+ */
+export function reapOrphanBusyKeys(
+  keys: Set<string>,
+  since: Map<string, number>,
+  now: number,
+  opts: ReapOptions,
+): string[] {
+  const reaped: string[] = []
+  for (const key of [...since.keys()]) {
+    if (!keys.has(key)) {
+      since.delete(key)
+      continue
+    }
+    // Proof gate: a key with a pending delivery is a slow-but-real inbound still
+    // awaiting its enqueue ack (the never-drop re-deliver loop owns it) — NEVER
+    // an orphan, regardless of age. Skip so a multi-minute (#1922) delivery
+    // can't be reaped out from under claude.
+    if (opts.hasPendingDelivery(key)) continue
+    const stampedAt = since.get(key) ?? now
+    if (now - stampedAt >= opts.ttlMs) {
+      keys.delete(key)
+      since.delete(key)
+      reaped.push(key)
+      opts.log?.(
+        `telegram gateway: reaped orphan busy key=${key} (no turn in flight, ` +
+          `no pending delivery, >${opts.ttlMs}ms) — unwedging idle-drain`,
+      )
+    }
+  }
+  return reaped
+}

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -42,6 +42,12 @@ export interface DisconnectFlushDeps<Ctrl extends { finalize: (reason?: 'done' |
    *  activeTurnStartedAt — the bridge just died, every turn it
    *  was handed is dead by definition. */
   claudeBusyKeys: Set<string>
+  /** #2787: insertion-timestamp map for `claudeBusyKeys`, backing the orphan
+   *  reaper. MUST stay in lockstep with `claudeBusyKeys` at every clear site —
+   *  a stale timestamp surviving a clear makes a later re-marked key look
+   *  >TTL-old and get reaped against a live delivery. Deleted alongside every
+   *  `claudeBusyKeys.delete`/`.clear` below. */
+  claudeBusyKeySince: Map<string, number>
 
   /** Open draft-stream handles keyed by chat:thread:replyId. */
   activeDraftStreams: Map<string, Stream>
@@ -82,6 +88,7 @@ export function flushOnAgentDisconnect<
     activeReactionMsgIds,
     activeTurnStartedAt,
     claudeBusyKeys,
+    claudeBusyKeySince,
     activeDraftStreams,
     clearActiveReactions,
     disposeProgressDriver,
@@ -109,6 +116,7 @@ export function flushOnAgentDisconnect<
     activeReactionMsgIds.delete(key)
     activeTurnStartedAt.delete(key)
     claudeBusyKeys.delete(key)
+    claudeBusyKeySince.delete(key) // #2787: keep orphan-TTL map in lockstep
   }
   clearActiveReactions()
 
@@ -129,6 +137,7 @@ export function flushOnAgentDisconnect<
       activeTurnStartedAt.delete(k)
       activeReactionMsgIds.delete(k)
       claudeBusyKeys.delete(k)
+      claudeBusyKeySince.delete(k) // #2787: keep orphan-TTL map in lockstep
     }
     log(
       `telegram gateway: disconnect-flush swept ${danglingKeys.length} dangling turn key(s) ` +
@@ -156,6 +165,8 @@ export function flushOnAgentDisconnect<
     const orphanCount = claudeBusyKeys.size
     const orphanKeys = [...claudeBusyKeys]
     claudeBusyKeys.clear()
+    // #2787: keep the orphan-TTL map in lockstep with the set it shadows.
+    for (const k of orphanKeys) claudeBusyKeySince.delete(k)
     log(
       `telegram gateway: disconnect-flush cleared ${orphanCount} orphan claudeBusyKeys ` +
       `entr${orphanCount === 1 ? 'y' : 'ies'} (synthetic-inbound deliveries that never turn_ended)` +

package/telegram-plugin/gateway/escalation-bridge-gate.ts

@@ -0,0 +1,46 @@
+/**
+ * escalation-bridge-gate.ts — the bridge-alive gate for the obligation sweep's
+ * ESCALATE branch, extracted from obligationSweep so the "do NOT direct-send the
+ * 'I may have missed this' nudge while the Telegram bridge is down" decision
+ * (#2788 Gap A) is EXECUTABLE in a pure unit test.
+ *
+ * The bug (#2788 Gap A): the obligation sweep keeps running while the Telegram
+ * bridge is disconnected. Unlike the represent branch (which goes through the
+ * bridge → buffer and is naturally stranded behind a dead bridge), the escalate
+ * branch DIRECT-SENDS via `bot.api.sendMessage`, bypassing the bridge. So during
+ * a transient bridge flap the user could receive a false "I may have missed this"
+ * even though the real reply is simply queued behind the outage and will land the
+ * moment the bridge recovers.
+ *
+ * The fix is a deferral, not a drop: obligations already survive bridge death
+ * (they live in the durable ledger and are re-evaluated every sweep), so gating
+ * the escalate SEND on bridge-alive and returning without closing leaves the
+ * obligation OPEN. The next sweep after the bridge reconnects re-drives it — the
+ * nudge is deferred until it can reflect a real, post-recovery miss. This adds NO
+ * unbounded liveness dependency: the entire gateway's inbound delivery already
+ * rests on the bridge eventually reconnecting / the process restarting.
+ *
+ * PURE — no Telegram, no IPC; the gateway injects `bridgeAlive` (read from
+ * `ipcServer.getClient(agent)?.isAlive()`).
+ */
+
+export interface EscalationBridgeGateDeps {
+  /**
+   * True when this agent's bridge sidecar is currently registered and alive on
+   * the IPC server — i.e. a direct escalate send can actually reflect delivery
+   * reality rather than racing a queued-behind-a-dead-bridge reply.
+   */
+  bridgeAlive: boolean
+}
+
+/**
+ * Decide whether the escalate branch should DEFER (skip this sweep, leave the
+ * obligation OPEN) because the bridge is down.
+ *
+ * Returns true ⇒ defer: do not send the nudge, do not close — the durable
+ * obligation is re-driven on a later sweep once the bridge recovers.
+ * Returns false ⇒ the bridge is alive; proceed with escalation.
+ */
+export function shouldDeferEscalationForBridge(deps: EscalationBridgeGateDeps): boolean {
+  return !deps.bridgeAlive
+}

package/telegram-plugin/gateway/gate-parity-probe.ts

@@ -0,0 +1,102 @@
+/**
+ * Gate-parity drift probe — scaffolding for the inbound-delivery
+ * state-machine cutover (#2794, RFC PR3b→PR4).
+ *
+ * ## Why this exists
+ *
+ * The inbound-delivery pipeline is mid-migration and TRIPLE-maintained:
+ *
+ *   1. the pure state machine (`inbound-delivery-machine.ts`) — the model,
+ *   2. the shadow (`inbound-delivery-machine-shadow.ts`) — module-scope
+ *      machine state advanced by `shadowEmit`, now AUTHORITATIVE for the
+ *      turn-in-flight gate via `isMachineInTurn()`,
+ *   3. the legacy imperative `claudeBusyKeys` set — still fully maintained
+ *      in parallel and read as the kill-switch fallback.
+ *
+ * Per #2794 the standing risk is DRIFT: because the same turn-lifecycle
+ * fact ("is a turn in flight?") is tracked in two live places, a fix in
+ * one can silently diverge from the other. The machine is authoritative
+ * today, but `claudeBusyKeys` is still wired and still read on the
+ * kill-switch path — so the two MUST NOT drift in the dangerous direction.
+ *
+ * ## What "agree" means (and the ONE intended divergence)
+ *
+ * The machine and `claudeBusyKeys` are designed to agree on every
+ * WELL-FORMED schedule (every turnStart has a matching turnEnd). They are
+ * deliberately allowed to diverge in exactly ONE direction on a MALFORMED
+ * schedule — an orphaned turnStart (turn B opens before turn A's turnEnd
+ * ever lands, the gymbro/clerk 5-min dangle of 2026-05-28):
+ *
+ *   - `busykeys_dangle`  — machine reads idle (self-healed via TTL tick or
+ *                          single-activeTurn reopen) while `claudeBusyKeys`
+ *                          still holds an orphan key. This is EXPECTED and
+ *                          GOOD: it is precisely the wedge the machine was
+ *                          made authoritative to kill. Not a drift alarm.
+ *
+ *   - `machine_over_holds` — machine reads in-flight while `claudeBusyKeys`
+ *                            is empty. This is the DANGEROUS direction: the
+ *                            now-authoritative gate would hold closed while
+ *                            the imperative view says idle — a NEW wedge
+ *                            class the cutover must never introduce. This
+ *                            is the drift #2794 warns about; surface it.
+ *
+ * This module is a pure classifier plus a log-only runtime probe. It
+ * performs NO I/O of its own beyond an optional injected log sink and
+ * changes NO delivery behaviour — it only observes. Deleting it once the
+ * `claudeBusyKeys` shadow is removed in PR4 is a no-op for behaviour.
+ */
+
+export type GateParityDivergence = 'none' | 'busykeys_dangle' | 'machine_over_holds'
+
+/**
+ * Classify the relationship between the machine's authoritative
+ * turn-in-flight read and the legacy imperative `claudeBusyKeys` size.
+ * Pure — no side effects.
+ */
+export function gateParityDivergence(
+  machineInTurn: boolean,
+  busyKeysSize: number,
+): GateParityDivergence {
+  const busy = busyKeysSize > 0
+  if (machineInTurn === busy) return 'none'
+  // machine idle, busyKeys non-empty → the orphan dangle the machine heals.
+  if (!machineInTurn && busy) return 'busykeys_dangle'
+  // machine in-flight, busyKeys empty → the dangerous over-hold.
+  return 'machine_over_holds'
+}
+
+/**
+ * True only for divergences that indicate a real cutover regression
+ * (the machine holding a gate the imperative shadow believes is open).
+ * The benign `busykeys_dangle` — the very wedge the machine fixes — is
+ * NOT flagged, so this probe has zero false positives on the known-good
+ * self-heal path.
+ */
+export function isDangerousGateDivergence(d: GateParityDivergence): boolean {
+  return d === 'machine_over_holds'
+}
+
+/**
+ * Log-only runtime drift canary. Call at the authoritative gate read.
+ * Emits a single grep-friendly `gw-trace gate-drift` line ONLY on the
+ * dangerous over-hold direction. Returns the machine value UNCHANGED so
+ * it can wrap the gate read without altering behaviour:
+ *
+ *   return probeGateParity(isMachineInTurn(), claudeBusyKeys.size)
+ *
+ * @param log  optional sink (default stderr) — test hook.
+ */
+export function probeGateParity(
+  machineInTurn: boolean,
+  busyKeysSize: number,
+  log: (line: string) => void = (line) => process.stderr.write(line),
+): boolean {
+  const d = gateParityDivergence(machineInTurn, busyKeysSize)
+  if (isDangerousGateDivergence(d)) {
+    log(
+      `gw-trace gate-drift kind=${d} machineInTurn=${machineInTurn} ` +
+        `busyKeys=${busyKeysSize} note=machine-authoritative-gate-holds-while-imperative-idle\n`,
+    )
+  }
+  return machineInTurn
+}