switchroom 0.14.19 → 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"
@@ -3014,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
@@ -3047,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,
+    )
   },
 })
 
@@ -4128,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).
@@ -8592,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)
     }
   }
@@ -8651,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)
 }
 
 /**
@@ -8690,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
@@ -8847,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`
@@ -9605,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).
@@ -9714,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,
     },
   }
 
@@ -9745,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,

package/telegram-plugin/gateway/interrupt-defer.ts

@@ -0,0 +1,100 @@
+// Problem B — deferred safe-boundary interrupt.
+//
+// A `!`-prefix interrupt SIGINTs the agent's in-flight turn (tmux C-c) and
+// then resumes with the replacement body as a fresh turn. Firing the SIGINT
+// the instant `!` arrives can land mid-tool-call — a C-c during a Write or a
+// Bash leaves the tool's work half-done. `reference/steer-or-queue-mid-flight.md`
+// names this exact anti-pattern: "Mid-tool-call is not 'amend time.'"
+//
+// We can't pause claude's internal loop (the unmodified-CLI constraint — the
+// only levers are SIGINT via tmux and observing the session JSONL). But we CAN
+// observe when a tool call starts and finishes, and defer the SIGINT to the
+// next clean boundary. This module is the pure, deterministic core of that
+// decision so it can be unit-tested without the gateway's IPC / timers.
+
+/** The session-event shape this tracker cares about. A structural subset of
+ *  the gateway's `SessionEvent` so tests don't need the full union. */
+export interface FlightEvent {
+  kind: string
+  toolUseId?: string | null
+}
+
+/**
+ * Tracks top-level tool calls in flight for the CURRENT turn, keyed by
+ * toolUseId. A `tool_use` adds; its matching `tool_result` removes; a
+ * `turn_end` or a fresh `enqueue` clears the slate (a new turn starts clean,
+ * and a killed turn may never emit the trailing `tool_result`).
+ *
+ * Sub-agent events (`sub_agent_*`) are intentionally ignored: the parent's
+ * `Task` tool_use already sits in the set and represents the user-observable
+ * wait, so the sub-agent's own tool calls don't independently gate the
+ * boundary. Telegram-surface tools are NOT excluded — treating every in-flight
+ * tool as "unsafe to C-c" is the conservative call, and the max-wait bound
+ * keeps a stuck reply tool from stranding the interrupt.
+ */
+export class ToolFlightTracker {
+  private readonly inFlight = new Set<string>()
+
+  onEvent(ev: FlightEvent): void {
+    switch (ev.kind) {
+      case 'tool_use':
+        if (typeof ev.toolUseId === 'string' && ev.toolUseId.length > 0) {
+          this.inFlight.add(ev.toolUseId)
+        }
+        break
+      case 'tool_result':
+        if (typeof ev.toolUseId === 'string' && ev.toolUseId.length > 0) {
+          this.inFlight.delete(ev.toolUseId)
+        }
+        break
+      case 'turn_end':
+      case 'enqueue':
+        this.inFlight.clear()
+        break
+      // dequeue / thinking / text / tool_label / sub_agent_* — no effect.
+      default:
+        break
+    }
+  }
+
+  /** True when at least one top-level tool call is open (unsafe boundary). */
+  isMidToolCall(): boolean {
+    return this.inFlight.size > 0
+  }
+
+  /** Count of in-flight tool calls — exposed for diagnostics/logging. */
+  inFlightCount(): number {
+    return this.inFlight.size
+  }
+
+  clear(): void {
+    this.inFlight.clear()
+  }
+}
+
+export type InterruptTiming = 'fire-now' | 'defer'
+
+/**
+ * Decide whether a `!` interrupt should fire immediately or wait for a safe
+ * boundary. Pure: the gateway feeds the live flag + tracker reading.
+ *
+ *  - flag off                  → fire-now (historical synchronous behaviour)
+ *  - flag on, no tool in flight → fire-now (already at a clean boundary)
+ *  - flag on, tool in flight    → defer (wait for tool_result / turn_end)
+ */
+export function decideInterruptTiming(opts: {
+  safeBoundaryEnabled: boolean
+  midToolCall: boolean
+}): InterruptTiming {
+  if (!opts.safeBoundaryEnabled) return 'fire-now'
+  return opts.midToolCall ? 'defer' : 'fire-now'
+}
+
+/** Floor for the deferred-interrupt max-wait. A non-positive or absent config
+ *  value falls back to the default; we never wait forever. */
+export const DEFAULT_INTERRUPT_MAX_WAIT_MS = 8000
+
+export function resolveInterruptMaxWaitMs(configured: number | undefined): number {
+  if (typeof configured === 'number' && configured > 0) return configured
+  return DEFAULT_INTERRUPT_MAX_WAIT_MS
+}

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -184,10 +184,16 @@ export function planBufferedRedelivery(
   return out
 }
 
+/** Meta keys that describe an attachment — the primary (image_path,
+ *  attachment_*) plus the A2 numbered siblings (image_path_2,
+ *  attachment_file_id_2, …) and attachment_count. */
+const ATTACHMENT_META_RE = /^(image_path|attachment_)/
+
 /** Collapse a >1 run into a single turn. The newest message anchors the
  *  turn (its messageId/ts/user/meta); texts join in arrival order; the
- *  single attachment (if any) rides along from whichever message carried
- *  it. Caller guarantees the run is mergeable + has at most one media. */
+ *  attachment(s) (if any) ride along from whichever message carried them.
+ *  Caller guarantees the run is mergeable + has at most one media-bearing
+ *  entry. */
 function mergeRun(run: InboundMessage[]): InboundMessage {
   const last = run[run.length - 1]!
   const mediaEntry = run.find(inboundHasMedia)
@@ -195,10 +201,21 @@ function mergeRun(run: InboundMessage[]): InboundMessage {
     ...last,
     text: run.map((m) => m.text).join('\n'),
   }
-  // Re-seat the single attachment/imagePath from the entry that owns it
-  // (which may not be `last`), or strip them if the run is text-only.
+  // Re-seat the attachment/imagePath from the entry that owns it (which may
+  // not be `last`), or strip them if the run is text-only.
   delete merged.imagePath
   delete merged.attachment
+  if (mediaEntry != null && mediaEntry !== last) {
+    // The media-bearing entry isn't the anchor, so `last.meta` lacks the
+    // attachment fields the agent reads (image_path / attachment_* and the
+    // A2 numbered siblings). Splice the owning entry's attachment meta keys
+    // into the merged meta so the agent still sees every attachment.
+    const splicedMeta: Record<string, string> = { ...merged.meta }
+    for (const [k, v] of Object.entries(mediaEntry.meta)) {
+      if (ATTACHMENT_META_RE.test(k)) splicedMeta[k] = v
+    }
+    merged.meta = splicedMeta
+  }
   if (mediaEntry?.imagePath != null) merged.imagePath = mediaEntry.imagePath
   if (mediaEntry?.attachment != null) merged.attachment = mediaEntry.attachment
   return merged