switchroom 0.14.16 → 0.14.18

package/telegram-plugin/gateway/gateway.ts

@@ -418,7 +418,8 @@ import {
   findMostRecentInterruptedTurn,
   findRecentTurnsForChat,
 } from '../registry/turns-schema.js'
-import { applySubagentsSchema } from '../registry/subagents-schema.js'
+import { applySubagentsSchema, getSubagentByJsonlId } from '../registry/subagents-schema.js'
+import { resolveWorkerFeedDispatch, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
 import { formatIdleFooter } from '../idle-footer.js'
 import { resolveCallingSubagent } from './resolve-calling-subagent.js'
 
@@ -2996,10 +2997,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
@@ -3007,24 +3010,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)
   },
 })
@@ -8533,24 +8548,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),
@@ -8580,7 +8617,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)
 }
 
 /**
@@ -15559,7 +15601,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 {
@@ -15602,7 +15644,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 => {
@@ -15625,7 +15667,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,
@@ -15635,7 +15677,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 })
 })
 
 /**
@@ -15727,17 +15769,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 => {
@@ -15752,7 +15794,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 => {
@@ -15765,7 +15807,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,
@@ -17402,11 +17444,6 @@ void (async () => {
                 // independent of the gateway — see
                 // `subagent-handback-decision.test.ts`.
                 let fleetChatId = ''
-                let isBackground = false
-                // Dispatch-time task description from the registry row —
-                // see the onProgress note; used for the feed's terminal recap
-                // header so it matches the running header ("· <real task>").
-                let dispatchDesc = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
                   for (const f of fleets) {
@@ -17419,17 +17456,18 @@ void (async () => {
                   // peek failures are non-fatal — fall through to the
                   // owner-chat fallback inside decideSubagentHandback.
                 }
+                // Background flag + feed header description, both derived from
+                // the registry row via the pure resolveWorkerFeedDispatch
+                // (worker-feed-dispatch.ts, pinned by its test). Best-effort:
+                // a DB hiccup keeps the watcher's generic label rather than
+                // throwing out of the terminal handler.
+                let dispatch: WorkerFeedDispatch = resolveWorkerFeedDispatch(null, description)
                 if (turnsDb != null) {
                   try {
-                    const row = turnsDb
-                      .prepare('SELECT background, description FROM subagents WHERE jsonl_agent_id = ?')
-                      .get(agentId) as { background: number; description: string | null } | undefined
-                    if (row != null) {
-                      isBackground = row.background === 1
-                      dispatchDesc = row.description ?? ''
-                    }
+                    dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(turnsDb, agentId), description)
                   } catch { /* best-effort */ }
                 }
+                const isBackground = dispatch.isBackground
                 // #PR2 live worker-feed: force the terminal recap edit on
                 // the worker's live message. No-op when no message was ever
                 // posted (trivial workers stay silent; handback covers them).
@@ -17437,7 +17475,7 @@ void (async () => {
                 // it to 'done' so an already-posted message still finalizes.
                 if (workerFeedEnabled) {
                   void workerActivityFeed.finish(agentId, {
-                    description: dispatchDesc || description,
+                    description: dispatch.feedDescription,
                     lastTool: null,
                     toolCount,
                     latestSummary: resultText,
@@ -17517,12 +17555,6 @@ void (async () => {
               // lives in the `onFinish` block just above.
               onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount }) => {
                 let fleetChatId = ''
-                let isBackground = false
-                // The watcher's `description` is its 'sub-agent' default (it
-                // never reassigns it from the worker jsonl). The dispatch-time
-                // task description lives in the registry row — prefer it so the
-                // feed header reads "🔧 Worker · <real task>" not "· sub-agent".
-                let dispatchDesc = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
                   for (const f of fleets) {
@@ -17532,17 +17564,18 @@ void (async () => {
                     }
                   }
                 } catch { /* peek failures non-fatal */ }
+                // The watcher's `description` is its 'sub-agent' default (it
+                // never reassigns it from the worker jsonl). The dispatch-time
+                // task description lives in the registry row — resolveWorkerFeedDispatch
+                // prefers it so the header reads "🔧 Worker · <real task>" not
+                // "· sub-agent" (worker-feed-dispatch.ts, pinned by its test).
+                let dispatch: WorkerFeedDispatch = resolveWorkerFeedDispatch(null, description)
                 if (turnsDb != null) {
                   try {
-                    const row = turnsDb
-                      .prepare('SELECT background, description FROM subagents WHERE jsonl_agent_id = ?')
-                      .get(agentId) as { background: number; description: string | null } | undefined
-                    if (row != null) {
-                      isBackground = row.background === 1
-                      dispatchDesc = row.description ?? ''
-                    }
+                    dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(turnsDb, agentId), description)
                   } catch { /* best-effort */ }
                 }
+                const isBackground = dispatch.isBackground
                 if (!isBackground) return // skip overhead for foreground
 
                 // #PR2 live worker-feed: when ON, the worker's live chat
@@ -17556,7 +17589,7 @@ void (async () => {
                     agentId,
                     fleetChatId || (loadAccess().allowFrom[0] ?? ''),
                     {
-                      description: dispatchDesc || description,
+                      description: dispatch.feedDescription,
                       lastTool,
                       toolCount,
                       latestSummary,

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/gateway/worker-feed-dispatch.ts

@@ -0,0 +1,37 @@
+import type { Subagent } from '../registry/subagents-schema.js'
+
+export interface WorkerFeedDispatch {
+  /** True when the sub-agent was dispatched with `run_in_background: true`. */
+  isBackground: boolean
+  /**
+   * The human-readable task to render in the feed header
+   * ("🔧 Worker · <feedDescription>").
+   */
+  feedDescription: string
+}
+
+/**
+ * Resolve the two registry-derived inputs the worker-activity feed needs:
+ * whether the sub-agent was a background dispatch, and the task description
+ * to show in the feed header.
+ *
+ * The live watcher only carries a generic 'sub-agent' label — it never
+ * reassigns `description` from the worker jsonl. The real dispatch-time
+ * description lives in the registry `subagents` row (written by the pretool
+ * hook from the `Agent(description:)` input). Prefer it; fall back to the
+ * watcher's label only when the row is missing or its description is empty.
+ *
+ * Pure + DB-free so it pins the #2002 behavior under both vitest and bun —
+ * see worker-feed-dispatch.test.ts. The gateway must never inline this
+ * decision again: a regression here silently reverts the feed header to
+ * "· sub-agent".
+ */
+export function resolveWorkerFeedDispatch(
+  sub: Subagent | null,
+  watcherDescription: string,
+): WorkerFeedDispatch {
+  return {
+    isBackground: sub?.background ?? false,
+    feedDescription: (sub?.description ?? '') || watcherDescription,
+  }
+}

package/telegram-plugin/subagent-watcher.ts

@@ -73,7 +73,13 @@ export interface WorkerEntry {
   readonly agentId: string
   /** File path of the JSONL. */
   readonly filePath: string
-  /** Short description — from the sub-agent's first text/narrative line. */
+  /**
+   * Generic 'sub-agent' placeholder — the watcher deliberately does NOT
+   * reassign this from the worker jsonl (see the init at construction and
+   * the "Do NOT overwrite" note in the line-handler). The real dispatch-time
+   * task description lives in the registry `subagents` row; the gateway reads
+   * it there via resolveWorkerFeedDispatch for the worker-feed header.
+   */
   description: string
   /** Current lifecycle state. */
   state: WorkerState
@@ -864,6 +870,9 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
     const entry: WorkerEntry = {
       agentId,
       filePath,
+      // Generic placeholder only — never overwritten from the jsonl. The
+      // gateway substitutes the real registry description for the worker
+      // feed (resolveWorkerFeedDispatch). See the WorkerEntry.description doc.
       description: 'sub-agent',
       state: 'running',
       dispatchedAt: n,

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' }])
+  })
 })