switchroom 0.14.17 → 0.14.19

package/telegram-plugin/gateway/gateway.ts

@@ -1954,6 +1954,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 +2894,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 ` +
@@ -2997,10 +3018,12 @@ type AttachmentMeta = {
 // `ctx` must be the *latest* message's context (latest message_id, etc.) so
 // the merge function picks the last entry's ctx.
 //
-// Image/attachment-bearing messages bypass the coalescer entirely (see
-// handleInboundCoalesced), so those fields stay optional and unused on the
-// coalesce path; preserved for future use if we ever want to coalesce
-// image+text bursts.
+// 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.
 type CoalescePayload = {
   text: string
   ctx: Context
@@ -3008,24 +3031,36 @@ type CoalescePayload = {
   attachment?: AttachmentMeta
 }
 
+// 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>()
+
 const inboundCoalescer = createInboundCoalescer<CoalescePayload>({
-  // Read per-call from the access file so `/access set-coalesce N` takes
-  // effect on the next message without restarting the gateway.
+  // Read per-call from the access file so an operator-tuned
+  // channels.telegram.coalesce.window_ms (projected to coalescingGapMs by
+  // scaffold) takes effect on the next message after apply+restart.
   //
   // Default lowered 1500 → 500 in #553 PR 3 to shrink the gateway-side
-  // contribution to first-real-text latency. Operators can still tune
-  // higher via `/access set-coalesce N` or the access file.
+  // contribution to first-real-text latency.
   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)
     return {
       text: entries.map((e) => e.text).join('\n'),
       ctx: last.ctx,
-      downloadImage: last.downloadImage,
-      attachment: last.attachment,
+      downloadImage: withAttachment?.downloadImage,
+      attachment: withAttachment?.attachment,
     }
   },
-  onFlush: (_key, merged) => {
+  onFlush: (key, merged) => {
+    bufferedAttachmentKeys.delete(key)
     void handleInbound(merged.ctx, merged.text, merged.downloadImage, merged.attachment)
   },
 })
@@ -4213,6 +4248,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) {
@@ -8534,24 +8579,46 @@ async function handleInboundCoalesced(
   downloadImage: (() => Promise<string | undefined>) | undefined,
   attachment?: AttachmentMeta,
 ): Promise<void> {
-  // Image/attachment-bearing messages bypass coalescing — preserves the
-  // legacy invariant that media never gets merged with sibling text.
-  if (downloadImage || attachment) return handleInbound(ctx, text, downloadImage, attachment)
-
-  // `!`-prefix interrupt (#575) ALSO bypasses coalescing. If we let an
+  // `!`-prefix interrupt (#575) bypasses coalescing. If we let an
   // interrupt sit in the coalesce window, an earlier non-`!` message
   // arriving in the same window would prepend itself and the marker
   // would no longer be at position 0 — handleInbound's parser would
   // miss it and the user's interrupt would silently get merged into a
   // normal turn. Bypass to handleInbound directly so the marker
-  // stays at the start of the text.
+  // stays at the start of the text. Checked first so a `!`-prefixed
+  // media caption still interrupts.
   if (parseInterruptMarker(text).isInterrupt) {
-    return handleInbound(ctx, text, undefined, undefined)
+    return handleInbound(ctx, text, downloadImage, attachment)
+  }
+
+  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) {
+    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.
+  if (hasAttachment) {
+    const probeKey = inboundCoalesceKey(
+      String(ctx.chat!.id),
+      ctx.message?.message_thread_id,
+      String(from.id),
+    )
+    if (bufferedAttachmentKeys.has(probeKey)) {
+      return handleInbound(ctx, text, downloadImage, attachment)
+    }
+  }
+
   // F2 fix (#553): fire 👀 reaction on RAW arrival, before the coalesce
   // wait blocks first paint. Pre-fix, the controller's setQueued() inside
   // handleInbound only ran AFTER the coalesce flush (default gapMs=1500),
@@ -8581,7 +8648,12 @@ async function handleInboundCoalesced(
     String(from.id),
   )
   const result = inboundCoalescer.enqueue(key, { text, ctx, downloadImage, attachment })
-  if (result.bypass) return handleInbound(ctx, text, undefined, undefined)
+  // 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)
 }
 
 /**
@@ -8883,6 +8955,7 @@ async function handleInbound(
       requestId: request_id,
       behavior,
     })
+    resumeReactionAfterVerdict()
     if (msgId != null) {
       const emoji = behavior === 'allow' ? '✅' : '❌'
       void bot.api.setMessageReaction(chat_id, msgId, [
@@ -11718,6 +11791,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`,
@@ -15368,6 +15442,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
@@ -15521,7 +15599,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`
@@ -15549,6 +15636,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()
     },
   })
 })
@@ -15560,7 +15650,7 @@ bot.on('message:text', async ctx => {
 
 bot.on('message:photo', async ctx => {
   const caption = ctx.message.caption ?? '(photo)'
-  await handleInbound(ctx, caption, async () => {
+  await handleInboundCoalesced(ctx, caption, async () => {
     const photos = ctx.message.photo
     const best = photos[photos.length - 1]
     try {
@@ -15603,7 +15693,7 @@ bot.on('message:photo', async ctx => {
 bot.on('message:document', async ctx => {
   const doc = ctx.message.document
   const name = safeName(doc.file_name)
-  await handleInbound(ctx, ctx.message.caption ?? `(document: ${name ?? 'file'})`, undefined, { kind: 'document', file_id: doc.file_id, size: doc.file_size, mime: doc.mime_type, name })
+  await handleInboundCoalesced(ctx, ctx.message.caption ?? `(document: ${name ?? 'file'})`, undefined, { kind: 'document', file_id: doc.file_id, size: doc.file_size, mime: doc.mime_type, name })
 })
 
 bot.on('message:voice', async ctx => {
@@ -15626,7 +15716,7 @@ bot.on('message:voice', async ctx => {
       const text = ctx.message.caption
         ? `${ctx.message.caption}\n\n[voice transcript] ${transcript}`
         : `[voice transcript] ${transcript}`
-      await handleInbound(ctx, text, undefined, {
+      await handleInboundCoalesced(ctx, text, undefined, {
         kind: 'voice',
         file_id: voice.file_id,
         size: voice.file_size,
@@ -15636,7 +15726,7 @@ bot.on('message:voice', async ctx => {
     }
     // Fall through to the legacy path on transcription failure.
   }
-  await handleInbound(ctx, ctx.message.caption ?? '(voice message)', undefined, { kind: 'voice', file_id: voice.file_id, size: voice.file_size, mime: voice.mime_type })
+  await handleInboundCoalesced(ctx, ctx.message.caption ?? '(voice message)', undefined, { kind: 'voice', file_id: voice.file_id, size: voice.file_size, mime: voice.mime_type })
 })
 
 /**
@@ -15728,17 +15818,17 @@ async function maybeTranscribeVoice(
 bot.on('message:audio', async ctx => {
   const audio = ctx.message.audio
   const name = safeName(audio.file_name)
-  await handleInbound(ctx, ctx.message.caption ?? `(audio: ${safeName(audio.title) ?? name ?? 'audio'})`, undefined, { kind: 'audio', file_id: audio.file_id, size: audio.file_size, mime: audio.mime_type, name })
+  await handleInboundCoalesced(ctx, ctx.message.caption ?? `(audio: ${safeName(audio.title) ?? name ?? 'audio'})`, undefined, { kind: 'audio', file_id: audio.file_id, size: audio.file_size, mime: audio.mime_type, name })
 })
 
 bot.on('message:video', async ctx => {
   const video = ctx.message.video
-  await handleInbound(ctx, ctx.message.caption ?? '(video)', undefined, { kind: 'video', file_id: video.file_id, size: video.file_size, mime: video.mime_type, name: safeName(video.file_name) })
+  await handleInboundCoalesced(ctx, ctx.message.caption ?? '(video)', undefined, { kind: 'video', file_id: video.file_id, size: video.file_size, mime: video.mime_type, name: safeName(video.file_name) })
 })
 
 bot.on('message:video_note', async ctx => {
   const vn = ctx.message.video_note
-  await handleInbound(ctx, '(video note)', undefined, { kind: 'video_note', file_id: vn.file_id, size: vn.file_size })
+  await handleInboundCoalesced(ctx, '(video note)', undefined, { kind: 'video_note', file_id: vn.file_id, size: vn.file_size })
 })
 
 bot.on('message:sticker', async ctx => {
@@ -15753,7 +15843,7 @@ bot.on('message:sticker', async ctx => {
   if (sticker.emoji) parts.push(sticker.emoji)
   if (sticker.set_name) parts.push(`from "${sticker.set_name}"`)
   const text = parts.length > 0 ? `(sticker — ${parts.join(' ')})` : '(sticker)'
-  await handleInbound(ctx, text, undefined, { kind: 'sticker', file_id: sticker.file_id, size: sticker.file_size })
+  await handleInboundCoalesced(ctx, text, undefined, { kind: 'sticker', file_id: sticker.file_id, size: sticker.file_size })
 })
 
 bot.on('message:animation', async ctx => {
@@ -15766,7 +15856,7 @@ bot.on('message:animation', async ctx => {
   const animation = ctx.message.animation
   const caption = ctx.message.caption
   const text = caption ? `(gif) ${caption}` : '(gif)'
-  await handleInbound(ctx, text, undefined, {
+  await handleInboundCoalesced(ctx, text, undefined, {
     kind: 'animation',
     file_id: animation.file_id,
     size: animation.file_size,

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

@@ -34,10 +34,11 @@ export interface InboundCoalescerOptions<T> {
    * `{ bypass: true }` and the caller should flush immediately).
    *
    * Pass a function (`() => number`) instead of a number when the
-   * window is config-driven and the operator can change it at runtime
-   * — gateway.ts reads it per-call from the access file so a
-   * `/access set-coalesce 500` takes effect on the next message
-   * without restarting the gateway.
+   * window is config-driven: gateway.ts reads it per-call from the
+   * access file (projected there from
+   * `channels.telegram.coalesce.window_ms` by the scaffold) so an
+   * operator-tuned window takes effect on the next message after
+   * apply + restart.
    */
   gapMs: number | (() => number)
   /**
@@ -146,9 +147,9 @@ export function createInboundCoalescer<T>(opts: InboundCoalescerOptions<T>): Inb
  *     CPO decision #9 ratified 2026-05-27)
  *
  * `threadId` collapses `null`/`undefined`/`0` to `_` via the same
- * convention as `chatKey()`. The 1.5s coalesce window is per-topic
- * intent ("user sends 3 sentences as one thought") — applying it
- * cross-topic merges genuinely separate conversations.
+ * convention as `chatKey()`. The coalesce window (default 500ms) is
+ * per-topic intent ("user sends 3 sentences as one thought") — applying
+ * it cross-topic merges genuinely separate conversations.
  */
 export function inboundCoalesceKey(
   chatId: string,

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

@@ -91,28 +91,119 @@ export function redeliverBufferedInbound(
   const pending = buffer.drain(agent)
   let redelivered = 0
   let rebuffered = 0
-  for (const msg of pending) {
+  // Collapse consecutive same-sender Telegram user messages into one turn
+  // (see planBufferedRedelivery) so a forwarded burst that spanned a turn
+  // boundary doesn't fan out into N sequential replies. System inbounds
+  // (vault grants, approvals, cron, handbacks — anything with meta.source)
+  // are never merged and are delivered individually exactly as before.
+  for (const { merged, originals } of planBufferedRedelivery(pending)) {
     let delivered = false
     try {
-      delivered = send(msg)
+      delivered = send(merged)
     } catch {
       delivered = false
     }
     if (delivered) {
-      redelivered++
       // Confirmed delivery to a live registered bridge → the durable
-      // promise is kept; tombstone the spool entry so it is NOT
-      // boot-replayed again. A miss leaves it spooled (re-pushed below
-      // AND still live in the spool) for the next drain / escalation.
-      spool?.ack(msg)
+      // promise is kept; tombstone EVERY original's spool entry so none is
+      // boot-replayed again. The merged message isn't itself spooled — the
+      // originals are, so we ack by original identity.
+      for (const o of originals) spool?.ack(o)
+      redelivered += originals.length
     } else {
-      buffer.push(agent, msg)
-      rebuffered++
+      // Re-buffer the originals (not the merged synthetic) so the spool
+      // identity is preserved and the next drain re-merges them losslessly.
+      for (const o of originals) buffer.push(agent, o)
+      rebuffered += originals.length
     }
   }
   return { drained: pending.length, redelivered, rebuffered }
 }
 
+/** True when `msg` is an ordinary Telegram user message eligible to be
+ *  merged with adjacent siblings. System inbounds (cron, vault grants,
+ *  approvals, subagent handbacks, warmup, reaction triggers) all tag a
+ *  `meta.source`; the user-message inbound built in gateway.ts sets none.
+ *  Restricting to source-less inbounds keeps merge-on-drain away from the
+ *  #1150 wake-up class entirely. */
+function isMergeableUserInbound(msg: InboundMessage): boolean {
+  return msg.type === 'inbound' && (msg.meta == null || msg.meta.source == null)
+}
+
+function inboundHasMedia(msg: InboundMessage): boolean {
+  return msg.imagePath != null || msg.attachment != null
+}
+
+/**
+ * Plan how a drained buffer is re-delivered. Walks `pending` in arrival
+ * order and groups runs of consecutive messages that:
+ *   - are both ordinary Telegram user messages (no meta.source), AND
+ *   - share the same (chatId, threadId, userId), AND
+ *   - would not put two attachments in one turn (A1 carries a single
+ *     attachment; a second media starts a new run so nothing is dropped).
+ *
+ * Each run collapses to one merged InboundMessage (texts joined by '\n',
+ * the run's single attachment carried, the LAST message's identity/meta
+ * kept as the turn anchor). A run of one passes through unchanged. The
+ * returned `originals` preserve spool identity for ack / re-buffer.
+ *
+ * Pure + deterministic so it can be exhaustively fuzzed.
+ */
+export function planBufferedRedelivery(
+  pending: InboundMessage[],
+): { merged: InboundMessage; originals: InboundMessage[] }[] {
+  const out: { merged: InboundMessage; originals: InboundMessage[] }[] = []
+  let run: InboundMessage[] = []
+  let runHasMedia = false
+
+  const sameTarget = (a: InboundMessage, b: InboundMessage): boolean =>
+    a.chatId === b.chatId &&
+    (a.threadId ?? null) === (b.threadId ?? null) &&
+    a.userId === b.userId
+
+  const flush = (): void => {
+    if (run.length === 0) return
+    out.push({ merged: run.length === 1 ? run[0]! : mergeRun(run), originals: run })
+    run = []
+    runHasMedia = false
+  }
+
+  for (const msg of pending) {
+    const msgHasMedia = inboundHasMedia(msg)
+    const canJoin =
+      run.length > 0 &&
+      isMergeableUserInbound(msg) &&
+      isMergeableUserInbound(run[run.length - 1]!) &&
+      sameTarget(run[run.length - 1]!, msg) &&
+      !(runHasMedia && msgHasMedia)
+    if (!canJoin) flush()
+    run.push(msg)
+    runHasMedia = runHasMedia || msgHasMedia
+  }
+  flush()
+  return out
+}
+
+/** 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. */
+function mergeRun(run: InboundMessage[]): InboundMessage {
+  const last = run[run.length - 1]!
+  const mediaEntry = run.find(inboundHasMedia)
+  const merged: 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.
+  delete merged.imagePath
+  delete merged.attachment
+  if (mediaEntry?.imagePath != null) merged.imagePath = mediaEntry.imagePath
+  if (mediaEntry?.attachment != null) merged.attachment = mediaEntry.attachment
+  return merged
+}
+
 /**
  * One opportunistic idle-drain tick. The third drain trigger, beside
  * `onClientRegistered` (bridge re-register) and the silence-poke

package/telegram-plugin/status-reactions.ts

@@ -53,6 +53,7 @@ export type ReactionState =
   | 'web'
   | 'tool'
   | 'compacting'
+  | 'awaiting'
   | 'done'
   | 'error'
   | 'stallSoft'
@@ -78,6 +79,7 @@ export const REACTION_VARIANTS: Record<ReactionState, string[]> = {
   coding:    ['👨‍💻', '✍', '⚡'],     // WORKING: writing / running code
   web:       ['⚡', '🤔', '👌'],      // WORKING: lookup in motion
   compacting:['✍', '🤔', '👀'],
+  awaiting:  ['🙏', '🤔', '👀'],      // BLOCKED ON HUMAN: parked on a permission card
   done:      ['👍', '💯', '🎉'],      // FINISHED: turn_end fired
   error:     ['😱', '😨', '🤯'],      // NON-TERMINAL — recovery allowed
   stallSoft: ['🥱', '😴', '🤔'],
@@ -180,6 +182,22 @@ export class StatusReactionController {
     this.scheduleState('compacting')
   }
 
+  /**
+   * 🙏 — the turn is parked on a human decision (a permission card is
+   * waiting for the operator to tap Allow/Deny). Immediate, non-terminal,
+   * and crucially SUSPENDS the stall watchdog: a turn blocked on the
+   * operator is not stalled, so it must NOT promote to 🥱/😨 while the
+   * card sits unanswered. The next working transition (setTool /
+   * setThinking, fired when the verdict resumes the turn) re-arms the
+   * watchdog normally. Bypasses debounce so 🙏 lands as soon as the card
+   * is posted.
+   */
+  setAwaiting(): void {
+    if (this.finished) return
+    this.scheduleState('awaiting', { immediate: true, skipStallReset: true })
+    this.clearStallTimers()
+  }
+
   /**
    * 😱 — non-terminal error indicator. Paints the error emoji but does
    * NOT end the controller — recovery to a working state is permitted

package/telegram-plugin/tests/inbound-coalesce.test.ts

@@ -140,4 +140,25 @@ describe('createInboundCoalescer', () => {
     expect(flushed).toEqual([])
     expect(c.size()).toBe(0)
   })
+
+  it('hands merge ALL entries in arrival order so the attachment can ride from a non-last entry', () => {
+    // The gateway merge picks the single attachment via entries.find(...),
+    // NOT entries[last]. Pin that the coalescer preserves arrival order and
+    // passes every buffered entry, so a [photo][text] burst keeps the photo.
+    interface MediaPayload { text: string; attachment?: string }
+    const mediaMerge = (entries: MediaPayload[]): MediaPayload => ({
+      text: entries.map((e) => e.text).join('\n'),
+      attachment: entries.find((e) => e.attachment != null)?.attachment,
+    })
+    const flushed: MediaPayload[] = []
+    const c = createInboundCoalescer<MediaPayload>({
+      gapMs: 1500,
+      merge: mediaMerge,
+      onFlush: (_key, merged) => flushed.push(merged),
+    })
+    c.enqueue('c1:u1', { text: 'look', attachment: 'photo-1' }) // media FIRST
+    c.enqueue('c1:u1', { text: 'at this' })                     // text second
+    vi.advanceTimersByTime(1500)
+    expect(flushed).toEqual([{ text: 'look\nat this', attachment: 'photo-1' }])
+  })
 })