switchroom 0.14.18 → 0.14.20

package/telegram-plugin/dist/server.js

@@ -24260,7 +24260,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. 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 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.',
       "",
       `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.`,
       "",

package/telegram-plugin/gateway/coalesce-attachments.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure helpers for A2 multi-attachment coalescing — kept out of `gateway.ts`
+ * so the cap/ordering and numbered-meta logic can be unit-tested without the
+ * gateway's `loadAccess()` / IPC machinery.
+ *
+ * Inbound model: each Telegram message carries at most one attachment, so the
+ * coalescer accumulates one attachment per buffered entry. On flush the
+ * gateway folds up to `coalesce.max_attachments` of them into a single turn —
+ * the first is the primary (unsuffixed `image_path` / `attachment_*` meta),
+ * the rest are numbered siblings (`image_path_2`, `attachment_file_id_2`, …).
+ */
+
+export interface CoalesceAttachmentMeta {
+  kind: string
+  file_id: string
+  size?: number
+  mime?: string
+  name?: string
+}
+
+/** A resolved extra attachment: photos are pre-downloaded to `imagePath`;
+ *  documents/voice carry only `attachment` metadata (agent fetches the file
+ *  via `download_attachment`). */
+export interface ResolvedExtraAttachment {
+  imagePath?: string
+  attachment?: CoalesceAttachmentMeta
+}
+
+/**
+ * Split the attachment-bearing entries of a coalesce window into the primary
+ * entry plus the capped list of extras. Preserves arrival order so a
+ * `[photo][text][photo]` burst keeps both photos in the order sent. Entries
+ * past `maxAttachments` are dropped here (the gateway bypasses them to their
+ * own turn upstream, so nothing is actually lost).
+ *
+ * `maxAttachments` is floored at 1 — a cap of 0 or negative would strip the
+ * primary, silently dropping the only attachment.
+ */
+export function splitCoalescedAttachments<T>(
+  entries: T[],
+  hasAttachment: (e: T) => boolean,
+  maxAttachments: number,
+): { primary: T | undefined; extras: T[] } {
+  const withAttachment = entries.filter(hasAttachment)
+  const capped = withAttachment.slice(0, Math.max(1, maxAttachments))
+  const [primary, ...extras] = capped
+  return { primary, extras: extras }
+}
+
+/**
+ * Build the numbered meta fields for the resolved extra attachments. The
+ * primary occupies the unsuffixed keys, so extras start at `_2`.
+ */
+export function buildExtraAttachmentMeta(
+  resolved: ResolvedExtraAttachment[],
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  resolved.forEach((ex, i) => {
+    const n = i + 2
+    if (ex.imagePath) out[`image_path_${n}`] = ex.imagePath
+    if (ex.attachment) {
+      out[`attachment_kind_${n}`] = ex.attachment.kind
+      out[`attachment_file_id_${n}`] = ex.attachment.file_id
+      if (ex.attachment.size != null) out[`attachment_size_${n}`] = String(ex.attachment.size)
+      if (ex.attachment.mime) out[`attachment_mime_${n}`] = ex.attachment.mime
+      if (ex.attachment.name) out[`attachment_name_${n}`] = ex.attachment.name
+    }
+  })
+  return out
+}

package/telegram-plugin/gateway/gateway.ts

@@ -35,6 +35,11 @@ import {
   type AskUserOutcome,
 } from '../ask-user.js'
 import { parseInterruptMarker } from '../interrupt-marker.js'
+import {
+  ToolFlightTracker,
+  decideInterruptTiming,
+  resolveInterruptMaxWaitMs,
+} from './interrupt-defer.js'
 import {
   resolveStickerSendArgs,
   resolveGifSendArgs,
@@ -51,6 +56,7 @@ import {
 } from '../telegraph.js'
 import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
+import { splitCoalescedAttachments, buildExtraAttachmentMeta } from './coalesce-attachments.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { DeferredDoneReactions } from '../reaction-defer.js'
 import { createWorkerActivityFeed } from '../worker-activity-feed.js'
@@ -770,6 +776,19 @@ type Access = {
   parseMode?: 'html' | 'markdownv2' | 'text'
   disableLinkPreview?: boolean
   coalescingGapMs?: number
+  /** A2: max media attachments folded into one coalesced turn. Default 1
+   *  (single-attachment behaviour). Projected from
+   *  channels.telegram.coalesce.max_attachments by scaffold. */
+  coalesceMaxAttachments?: number
+  /** Problem B: when true, a `!` interrupt that lands mid-tool-call is
+   *  deferred until the in-flight tool finishes (bounded by
+   *  interruptMaxWaitMs) before SIGINT + resume. Default false (fire
+   *  synchronously). Projected from channels.telegram.interrupt.safe_boundary. */
+  interruptSafeBoundary?: boolean
+  /** Upper bound (ms) to wait for a safe boundary before firing a deferred
+   *  interrupt anyway. Default 8000. Projected from
+   *  channels.telegram.interrupt.max_wait_ms. */
+  interruptMaxWaitMs?: number
   statusReactions?: boolean
   historyEnabled?: boolean
   historyRetentionDays?: number
@@ -868,6 +887,9 @@ function readAccessFile(): Access {
       parseMode: parsed.parseMode,
       disableLinkPreview: parsed.disableLinkPreview,
       coalescingGapMs: parsed.coalescingGapMs,
+      coalesceMaxAttachments: parsed.coalesceMaxAttachments,
+      interruptSafeBoundary: parsed.interruptSafeBoundary,
+      interruptMaxWaitMs: parsed.interruptMaxWaitMs,
       statusReactions: parsed.statusReactions,
       historyEnabled: parsed.historyEnabled,
       historyRetentionDays: parsed.historyRetentionDays,
@@ -1380,6 +1402,78 @@ type CurrentTurn = {
 
 let currentTurn: CurrentTurn | null = null
 
+// Problem B — deferred safe-boundary interrupt.
+//
+// `toolFlightTracker` mirrors the session-event stream to know whether a
+// top-level tool call is open right now (an unsafe point to SIGINT). When the
+// `interrupt.safe_boundary` flag is on and a `!` lands mid-tool-call, we don't
+// fire the SIGINT — we stash the fully-built replacement inbound here and fire
+// it (SIGINT + deliver) at the next clean boundary (tool_result drains the
+// last open tool, or turn_end), or when the max-wait timer expires. Rapid
+// repeated `!` while one is pending coalesce: the latest body replaces the
+// stashed inbound, the original deadline is preserved (bounded wait).
+const toolFlightTracker = new ToolFlightTracker()
+
+interface PendingDeferredInterrupt {
+  agentName: string
+  inboundMsg: InboundMessage
+  chatId: string
+  msgId: number | null
+  threadId: number | undefined
+  registeredAt: number
+  deadlineTimer: ReturnType<typeof setTimeout>
+}
+let pendingDeferredInterrupt: PendingDeferredInterrupt | null = null
+
+/**
+ * Fire a stashed deferred interrupt: SIGINT the (now safely-bounded) turn via
+ * tmux, then deliver the replacement body as a fresh inbound — the same two
+ * primitives the synchronous `!` path uses, just gated on a clean boundary.
+ * Idempotent: nulls the slot and clears the timer before doing any work so a
+ * boundary event and the timeout can't double-fire.
+ */
+async function fireDeferredInterrupt(reason: 'boundary' | 'timeout'): Promise<void> {
+  const pending = pendingDeferredInterrupt
+  if (pending == null) return
+  pendingDeferredInterrupt = null
+  clearTimeout(pending.deadlineTimer)
+
+  const waitedMs = Date.now() - pending.registeredAt
+  process.stderr.write(
+    `telegram gateway: deferred-interrupt firing reason=${reason} agent=${pending.agentName} ` +
+    `chat=${pending.chatId} waited_ms=${waitedMs} in_flight=${toolFlightTracker.inFlightCount()}\n`,
+  )
+
+  try {
+    const { sendAgentInterrupt } = await import('../../src/agents/tmux.js')
+    const r = sendAgentInterrupt({ agentName: pending.agentName })
+    if ('ok' in r) {
+      process.stderr.write(
+        `telegram gateway: deferred-interrupt SIGINT delivered via tmux send-keys agent=${pending.agentName}\n`,
+      )
+    } else {
+      process.stderr.write(
+        `telegram gateway: deferred-interrupt SIGINT via tmux failed agent=${pending.agentName}: ${r.error}\n`,
+      )
+    }
+  } catch (err) {
+    process.stderr.write(`telegram gateway: deferred-interrupt SIGINT failed: ${(err as Error).message}\n`)
+  }
+
+  // Deliver the replacement body as a fresh turn to the freshly-killed
+  // bridge — same sendToAgent + buffer-on-miss primitive the synchronous
+  // interrupt carve-out uses at the handleInbound delivery site.
+  const delivered = ipcServer.sendToAgent(pending.agentName, pending.inboundMsg)
+  if (delivered) {
+    markClaudeBusyForInbound(pending.inboundMsg)
+  } else {
+    pendingInboundBuffer.push(pending.agentName, pending.inboundMsg)
+    process.stderr.write(
+      `telegram gateway: deferred-interrupt body buffered (bridge miss) agent=${pending.agentName} chat=${pending.chatId}\n`,
+    )
+  }
+}
+
 // #549 fix — preamble suppression for the answer-stream path.
 //
 // Background: assistant text emitted before a tool_use is "preamble"
@@ -1954,6 +2048,24 @@ function paintStatusReactionError(chatId: string, threadId: number | undefined):
   ctrl.setError()
 }
 
+/**
+ * Flip the current turn's status reaction off 🙏 (awaiting-approval) back
+ * to a working glyph once a permission verdict has been dispatched. The
+ * turn was suspended *inside* the bridge's permission call, so `currentTurn`
+ * still points at it; the verdict un-parks claude and it resumes the SAME
+ * turn. `setThinking()` re-arms the stall watchdog that `setAwaiting()`
+ * suspended, so a genuine post-approval hang still promotes to 🥱/😨, and
+ * it is replaced by the real tool glyph (✍/⚡) as soon as the resumed turn
+ * fires its next PreToolUse. Non-terminal — 👍 still waits for `turn_end`.
+ */
+function resumeReactionAfterVerdict(): void {
+  const turn = currentTurn
+  if (turn == null) return
+  activeStatusReactions
+    .get(statusKey(turn.sessionChatId, turn.sessionThreadId))
+    ?.setThinking()
+}
+
 function resolveThreadId(chat_id: string, explicit?: string | number | null): number | undefined {
   if (explicit != null) return Number(explicit)
   return chatThreadMap.get(chat_id)
@@ -2876,6 +2988,9 @@ const pendingStateReaper = setInterval(() => {
       // dispatchPermissionVerdict so it's buffered+redelivered too if
       // the bridge is also offline at sweep time.
       dispatchPermissionVerdict({ type: 'permission', requestId: k, behavior: 'deny' })
+      // The auto-deny un-parks the suspended turn — flip 🙏 → working so
+      // it doesn't sit on the awaiting glyph (or stall) after the timeout.
+      resumeReactionAfterVerdict()
       process.stderr.write(
         `telegram gateway: permission TTL expired — auto-deny request=${k} ` +
         `tool=${v.tool_name} (no operator response in ` +
@@ -2993,28 +3108,43 @@ type AttachmentMeta = {
   name?: string
 }
 
+// One attachment slot carried by a coalesced message — primary or extra.
+type CoalesceAttachment = {
+  downloadImage?: () => Promise<string | undefined>
+  attachment?: AttachmentMeta
+}
+
 // CoalescePayload is what the InboundCoalescer carries per buffered message.
 // `ctx` must be the *latest* message's context (latest message_id, etc.) so
 // the merge function picks the last entry's ctx.
 //
-// A single attachment-bearing message may ride along in a coalesce window
-// (so a [text][photo] forward becomes one turn). The handleInboundCoalesced
-// guards ensure AT MOST ONE attachment per window — albums (media_group_id)
-// and a second attachment both bypass to their own turn — so the single
-// `downloadImage`/`attachment` slot is never silently overwritten. Folding a
-// whole album into one multi-attachment turn is the A2 follow-on.
+// Each inbound Telegram message carries at most one attachment, so an enqueued
+// payload sets at most `downloadImage`/`attachment`. The merge collects every
+// attachment-bearing entry in the window (up to coalesce.max_attachments): the
+// first becomes the primary `downloadImage`/`attachment`, the rest ride along
+// in `extraAttachments` (A2). When the cap is 1 (default), the
+// handleInboundCoalesced guards still bypass a second attachment / album part
+// to its own turn, so the single-attachment behaviour is byte-for-byte
+// preserved.
 type CoalescePayload = {
   text: string
   ctx: Context
   downloadImage?: () => Promise<string | undefined>
   attachment?: AttachmentMeta
+  // Set only by `merge`: the 2nd..Nth attachments folded into this turn.
+  extraAttachments?: CoalesceAttachment[]
 }
 
-// Coalesce keys whose open window already holds an attachment-bearing entry.
-// A second attachment for the same key bypasses coalescing (see
-// handleInboundCoalesced) so the single-attachment merge can't drop a photo.
-// Cleared on flush (below) and on the synchronous bypass path.
-const bufferedAttachmentKeys = new Set<string>()
+// Count of attachment-bearing entries currently buffered per coalesce key.
+// A new attachment for a key whose count has reached the per-agent cap
+// (coalesce.max_attachments, default 1) bypasses coalescing (see
+// handleInboundCoalesced) so no media is dropped past the cap. Cleared on
+// flush (below) and on the synchronous bypass path.
+const bufferedAttachmentKeys = new Map<string, number>()
+
+function coalesceMaxAttachments(): number {
+  return Math.max(1, loadAccess().coalesceMaxAttachments ?? 1)
+}
 
 const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
   // Read per-call from the access file so an operator-tuned
@@ -3026,21 +3156,36 @@ const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
   gapMs: () => loadAccess().coalescingGapMs ?? 500,
   merge: (entries) => {
     const last = entries[entries.length - 1]
-    // At most one entry carries an attachment (guarded upstream), so pick
-    // whichever entry has it rather than blindly taking `last` — a
-    // [photo][text] burst keeps its image even though the last entry is
-    // text-only.
-    const withAttachment = entries.find((e) => e.downloadImage != null || e.attachment != null)
+    // Collect every attachment-bearing entry in arrival order. The first is
+    // the primary (unsuffixed image_path/attachment_* meta); the remainder,
+    // capped at max_attachments, become numbered extras. A [photo][text]
+    // burst keeps its image even though the last entry is text-only.
+    const { primary, extras } = splitCoalescedAttachments(
+      entries,
+      (e) => e.downloadImage != null || e.attachment != null,
+      coalesceMaxAttachments(),
+    )
     return {
-      text: entries.map((e) => e.text).join('\n'),
+      // Drop empty texts (e.g. caption-less album parts) so the join doesn't
+      // emit blank lines between attachments.
+      text: entries.map((e) => e.text).filter((t) => t.length > 0).join('\n'),
       ctx: last.ctx,
-      downloadImage: withAttachment?.downloadImage,
-      attachment: withAttachment?.attachment,
+      downloadImage: primary?.downloadImage,
+      attachment: primary?.attachment,
+      extraAttachments: extras.length > 0
+        ? extras.map((e) => ({ downloadImage: e.downloadImage, attachment: e.attachment }))
+        : undefined,
     }
   },
   onFlush: (key, merged) => {
     bufferedAttachmentKeys.delete(key)
-    void handleInbound(merged.ctx, merged.text, merged.downloadImage, merged.attachment)
+    void handleInbound(
+      merged.ctx,
+      merged.text,
+      merged.downloadImage,
+      merged.attachment,
+      merged.extraAttachments,
+    )
   },
 })
 
@@ -4107,6 +4252,14 @@ const ipcServer: IpcServer = createIpcServer({
     const threadHint = msg.threadId != null ? String(msg.threadId) : undefined
     progressDriver?.ingest(ev, chatHint, threadHint)
     handleSessionEvent(ev)
+    // Problem B: keep the deferred-interrupt boundary tracker in lockstep with
+    // the session stream (tool_use opens, tool_result/turn_end close). If a `!`
+    // interrupt is parked waiting for a clean boundary and this event drains
+    // the last in-flight tool, fire it now rather than waiting out the timer.
+    toolFlightTracker.onEvent(ev)
+    if (pendingDeferredInterrupt != null && !toolFlightTracker.isMidToolCall()) {
+      void fireDeferredInterrupt('boundary')
+    }
     // #1122 silence-poke: surface activity signals from the session
     // stream so the 300s framework-fallback message wording is honest
     // (thinking vs working, plus the longest-running in-flight tool).
@@ -4227,6 +4380,16 @@ const ipcServer: IpcServer = createIpcServer({
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}\n`)
       })
     }
+    // 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
+    // unanswered. The verdict path (`resumeReactionAfterVerdict`) flips it
+    // back to a working state the instant you tap.
+    if (activeTurn != null) {
+      activeStatusReactions
+        .get(statusKey(activeTurn.sessionChatId, activeTurn.sessionThreadId))
+        ?.setAwaiting()
+    }
   },
 
   onHeartbeat(_client: IpcClient, _msg: HeartbeatMessage) {
@@ -8561,29 +8724,31 @@ async function handleInboundCoalesced(
   }
 
   const hasAttachment = downloadImage != null || attachment != null
-
-  // Albums (media_group_id) are NOT coalesced in A1 — each part keeps its
-  // own turn exactly as before. The single-attachment merge can carry only
-  // one image, so folding a 3-photo album into one turn requires the
-  // multi-attachment inbound payload (the A2 follow-on). Bypass to preserve
-  // current per-part behavior and avoid dropping sibling photos.
-  if (hasAttachment && ctx.message?.media_group_id != null) {
+  const maxAttachments = coalesceMaxAttachments()
+
+  // Albums (media_group_id): coalesce only when the cap allows >1 attachment
+  // (A2). At the default cap of 1 each album part keeps its own turn exactly
+  // as before — the single-attachment merge can't carry sibling photos, so
+  // bypassing avoids dropping them. With a raised cap the parts share the
+  // coalesce key and fold into one multi-attachment turn (the cap-overflow
+  // bypass below catches parts past the cap).
+  if (hasAttachment && ctx.message?.media_group_id != null && maxAttachments <= 1) {
     return handleInbound(ctx, text, downloadImage, attachment)
   }
 
   const from = ctx.from
   if (!from) return
 
-  // A second attachment landing in an already-open window would clobber the
-  // first under the single-attachment merge. Bypass it to its own turn so no
-  // media is silently dropped; A2's multi-attachment payload lifts this.
+  // An attachment past the per-agent cap would be dropped by the capped merge.
+  // Bypass it to its own turn so no media is silently lost. At the default
+  // cap of 1 this fires on the SECOND attachment, preserving A1 behaviour.
   if (hasAttachment) {
     const probeKey = inboundCoalesceKey(
       String(ctx.chat!.id),
       ctx.message?.message_thread_id,
       String(from.id),
     )
-    if (bufferedAttachmentKeys.has(probeKey)) {
+    if ((bufferedAttachmentKeys.get(probeKey) ?? 0) >= maxAttachments) {
       return handleInbound(ctx, text, downloadImage, attachment)
     }
   }
@@ -8620,9 +8785,10 @@ async function handleInboundCoalesced(
   // Coalescing disabled (window <= 0): flush immediately, preserving any
   // media this message carried.
   if (result.bypass) return handleInbound(ctx, text, downloadImage, attachment)
-  // Mark the open window as holding an attachment so a second attachment for
-  // this key bypasses rather than clobbers (cleared in onFlush).
-  if (hasAttachment) bufferedAttachmentKeys.add(key)
+  // Count the open window's attachments so a third+ (or second, at the
+  // default cap) bypasses rather than overflows the capped merge (cleared
+  // in onFlush).
+  if (hasAttachment) bufferedAttachmentKeys.set(key, (bufferedAttachmentKeys.get(key) ?? 0) + 1)
 }
 
 /**
@@ -8659,6 +8825,10 @@ async function handleInbound(
   text: string,
   downloadImage: (() => Promise<string | undefined>) | undefined,
   attachment?: AttachmentMeta,
+  // A2: 2nd..Nth attachments folded into this coalesced turn. Each is
+  // resolved (photos downloaded) and surfaced as numbered meta fields
+  // (image_path_2, attachment_file_id_2, …) alongside the primary.
+  extraAttachments?: CoalesceAttachment[],
 ): Promise<void> {
   const isTopicMessage = ctx.message?.is_topic_message ?? false
   const messageThreadId = ctx.message?.message_thread_id
@@ -8816,18 +8986,32 @@ async function handleInbound(
   // unauthorized senders never reach this code (gate() above).
   // Interrupt requires the same trust as sending a normal message.
   const interrupt = parseInterruptMarker(text)
+  // Problem B: defer this `!`'s SIGINT to a safe boundary instead of firing it
+  // synchronously below. Set only when the `interrupt.safe_boundary` flag is on
+  // AND a top-level tool call is in flight AND the body is non-empty (an empty
+  // `!` is an explicit halt-now and stays immediate). When set, we skip the
+  // synchronous SIGINT here and stash the built inbound at the delivery site.
+  let deferInterrupt = false
   if (interrupt.isInterrupt) {
     const agentName = process.env.SWITCHROOM_AGENT_NAME
+    const access = loadAccess()
+    deferInterrupt =
+      !interrupt.emptyBody &&
+      decideInterruptTiming({
+        safeBoundaryEnabled: access.interruptSafeBoundary === true,
+        midToolCall: toolFlightTracker.isMidToolCall(),
+      }) === 'defer'
     process.stderr.write(
       `telegram gateway: interrupt-marker received chat_id=${chat_id} agent=${agentName ?? '-'} ` +
-      `body_len=${interrupt.body.length} empty=${interrupt.emptyBody}\n`,
+      `body_len=${interrupt.body.length} empty=${interrupt.emptyBody} defer=${deferInterrupt} ` +
+      `in_flight=${toolFlightTracker.inFlightCount()}\n`,
     )
     if (msgId != null) {
       void bot.api.setMessageReaction(chat_id, msgId, [
         { type: 'emoji', emoji: '⚡' as ReactionTypeEmoji['emoji'] },
       ]).catch(() => {})
     }
-    if (agentName) {
+    if (agentName && !deferInterrupt) {
       try {
         // The gateway runs INSIDE the agent container in docker mode,
         // so calling `interruptAgent` (which probes `docker inspect`
@@ -8924,6 +9108,7 @@ async function handleInbound(
       requestId: request_id,
       behavior,
     })
+    resumeReactionAfterVerdict()
     if (msgId != null) {
       const emoji = behavior === 'allow' ? '✅' : '❌'
       void bot.api.setMessageReaction(chat_id, msgId, [
@@ -9573,6 +9758,25 @@ async function handleInbound(
 
   const imagePath = downloadImage ? await downloadImage() : undefined
 
+  // A2: resolve the extra attachments (2nd..Nth in a coalesced multi-media
+  // burst). Photos are downloaded the same way as the primary; documents/
+  // voice carry only attachment metadata (the agent fetches them via
+  // download_attachment). Numbered meta fields below let the agent see each.
+  const extraResolved: Array<{ imagePath?: string; attachment?: AttachmentMeta }> = []
+  if (extraAttachments && extraAttachments.length > 0) {
+    for (const ex of extraAttachments) {
+      const exImagePath = ex.downloadImage ? await ex.downloadImage() : undefined
+      extraResolved.push({ imagePath: exImagePath, attachment: ex.attachment })
+    }
+  }
+  // Flatten the numbered meta fields once so the InboundMessage literal can
+  // spread them. Primary is "1" (unsuffixed); extras start at "_2".
+  const extraMeta = buildExtraAttachmentMeta(extraResolved)
+  // Total attachment count (primary + extras) so the agent knows how many to
+  // expect without probing for numbered fields. Only emitted when >1.
+  const primaryHasAttachment = imagePath != null || attachment != null
+  const attachmentCount = (primaryHasAttachment ? 1 : 0) + extraResolved.length
+
   // Telegram-native reply context (issue #119). Same pattern as server.ts:
   // `replyToText` is raw (for SQLite); `replyToTextEscaped` is XML-escaped
   // (for channel meta).
@@ -9682,6 +9886,10 @@ async function handleInbound(
         ...(attachment.mime ? { attachment_mime: attachment.mime } : {}),
         ...(attachment.name ? { attachment_name: attachment.name } : {}),
       } : {}),
+      // A2: numbered fields for the 2nd..Nth attachment + a total count so
+      // the agent reads every item in a coalesced multi-media burst.
+      ...(attachmentCount > 1 ? { attachment_count: String(attachmentCount) } : {}),
+      ...extraMeta,
     },
   }
 
@@ -9713,6 +9921,40 @@ async function handleInbound(
   // line ~7357 already populated the Map for THIS inbound's turn;
   // reading the live size here would self-block (see the comment on
   // turnInFlightAtReceipt for the wedge symptom this fixes).
+  // Problem B: a deferred `!` interrupt. The synchronous SIGINT was skipped
+  // above (a tool was in flight) — claude is still working. Don't deliver the
+  // replacement body now (it would race the live tool); stash the fully-built
+  // inbound and let `fireDeferredInterrupt` SIGINT + deliver at the next clean
+  // boundary, or when the max-wait timer expires. Rapid repeated `!` coalesce:
+  // the latest body replaces the stashed inbound, the original deadline holds
+  // so the wait stays bounded.
+  if (deferInterrupt) {
+    const selfAgentDefer = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    if (pendingDeferredInterrupt != null) {
+      pendingDeferredInterrupt.inboundMsg = inboundMsg
+      pendingDeferredInterrupt.msgId = msgId ?? null
+      process.stderr.write(
+        `telegram gateway: deferred-interrupt coalesced (replacing pending body) agent=${selfAgentDefer} chat=${chat_id} msg=${msgId ?? '-'}\n`,
+      )
+    } else {
+      const maxWaitMs = resolveInterruptMaxWaitMs(loadAccess().interruptMaxWaitMs)
+      pendingDeferredInterrupt = {
+        agentName: selfAgentDefer,
+        inboundMsg,
+        chatId: chat_id,
+        msgId: msgId ?? null,
+        threadId: messageThreadId ?? undefined,
+        registeredAt: Date.now(),
+        deadlineTimer: setTimeout(() => { void fireDeferredInterrupt('timeout') }, maxWaitMs),
+      }
+      process.stderr.write(
+        `telegram gateway: deferred-interrupt parked agent=${selfAgentDefer} chat=${chat_id} ` +
+        `msg=${msgId ?? '-'} max_wait_ms=${maxWaitMs} in_flight=${toolFlightTracker.inFlightCount()}\n`,
+      )
+    }
+    return
+  }
+
   if (
     decideInboundDelivery({
       turnInFlight: turnInFlightAtReceipt,
@@ -11759,6 +12001,7 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
   }
   // Forward to connected bridges — same IPC the button handler uses.
   dispatchPermissionVerdict({ type: 'permission', requestId: request_id, behavior })
+  resumeReactionAfterVerdict()
   pendingPermissions.delete(request_id)
   process.stderr.write(
     `[telegram gateway] slash-${behavior} request_id=${request_id} tool=${details.tool_name} by=${senderId}\n`,
@@ -15409,6 +15652,10 @@ bot.on('callback_query:data', async ctx => {
       behavior: 'allow',
       rule: chosen.rule,
     })
+    // The turn resumes now (independent of the host persistence round-trip
+    // below). Un-park 🙏 → working immediately so the operator sees the
+    // agent continue while hostd writes the durable rule.
+    resumeReactionAfterVerdict()
 
     // (3) Decide the persistence path. tryHostdDispatch returns
     // "not-configured" when host_control is disabled or the per-agent
@@ -15562,7 +15809,16 @@ bot.on('callback_query:data', async ctx => {
 
   // Forward permission decision to connected bridges
   pendingPermissions.delete(request_id)
-  const label = behavior === 'allow' ? '✅ Allowed' : '❌ Denied'
+  // Deterministic "▶️ resuming…" beat (framework-posted, not model text):
+  // the verdict un-parks the suspended turn, so confirm to the operator
+  // that the agent received it and is continuing — closing the "is it
+  // working or did my tap do nothing?" gap. Allow and deny both resume the
+  // turn (deny just hands claude a refusal it then handles).
+  const resumeAgent = process.env.SWITCHROOM_AGENT_NAME
+  const resumeBeat = resumeAgent
+    ? `▶️ ${escapeHtmlForTg(resumeAgent)} resuming…`
+    : '▶️ resuming…'
+  const label = `${behavior === 'allow' ? '✅ Allowed' : '❌ Denied'} · ${resumeBeat}`
   // HTML-escape the source text — same hazard as the scope-commit and
   // recent-denial paths above. The permission card body
   // (formatPermissionCardBody) appends claude-supplied `description`
@@ -15590,6 +15846,9 @@ bot.on('callback_query:data', async ctx => {
         requestId: request_id,
         behavior: behavior as 'allow' | 'deny',
       })
+      // Un-park the status reaction: 🙏 → working, re-arming the stall
+      // watchdog that setAwaiting() suspended.
+      resumeReactionAfterVerdict()
     },
   })
 })