switchroom 0.14.17 → 0.14.18

package/dist/agent-scheduler/index.js

@@ -11068,6 +11068,9 @@ var TelegramChannelSchema = exports_external.object({
     short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
     author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
   }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default — content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+  coalesce: exports_external.object({
+    window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+  }).optional().describe("Inbound coalescing — how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
   webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default — webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 — see #577.)"),
   webhook_dispatch: exports_external.object({
     github: exports_external.array(exports_external.object({

package/dist/auth-broker/index.js

@@ -11068,6 +11068,9 @@ var TelegramChannelSchema = exports_external.object({
     short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
     author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
   }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default — content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+  coalesce: exports_external.object({
+    window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+  }).optional().describe("Inbound coalescing — how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
   webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default — webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 — see #577.)"),
   webhook_dispatch: exports_external.object({
     github: exports_external.array(exports_external.object({

package/dist/cli/notion-write-pretool.mjs

@@ -11815,6 +11815,9 @@ var TelegramChannelSchema = exports_external.object({
     short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
     author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
   }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default \u2014 content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+  coalesce: exports_external.object({
+    window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+  }).optional().describe("Inbound coalescing \u2014 how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
   webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default \u2014 webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 \u2014 see #577.)"),
   webhook_dispatch: exports_external.object({
     github: exports_external.array(exports_external.object({

package/dist/cli/switchroom.js

@@ -13632,6 +13632,9 @@ var init_schema = __esm(() => {
       short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
       author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
     }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default \u2014 content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+    coalesce: exports_external.object({
+      window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+    }).optional().describe("Inbound coalescing \u2014 how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
     webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default \u2014 webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 \u2014 see #577.)"),
     webhook_dispatch: exports_external.object({
       github: exports_external.array(exports_external.object({
@@ -49413,8 +49416,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.14.17";
-var COMMIT_SHA = "95c1d475";
+var VERSION = "0.14.18";
+var COMMIT_SHA = "dddb8617";
 
 // src/cli/agent.ts
 init_source();
@@ -52681,6 +52684,9 @@ function buildAccessJson2(agentConfig, telegramConfig, resolvedTopicId, userId)
   if (tg?.telegraph) {
     access.telegraph = tg.telegraph;
   }
+  if (typeof tg?.coalesce?.window_ms === "number") {
+    access.coalescingGapMs = tg.coalesce.window_ms;
+  }
   return JSON.stringify(access, null, 2) + `
 `;
 }

package/dist/host-control/main.js

@@ -13803,6 +13803,9 @@ var TelegramChannelSchema = exports_external.object({
     short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
     author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
   }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default — content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+  coalesce: exports_external.object({
+    window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+  }).optional().describe("Inbound coalescing — how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
   webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default — webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 — see #577.)"),
   webhook_dispatch: exports_external.object({
     github: exports_external.array(exports_external.object({

package/dist/vault/approvals/kernel-server.js

@@ -11383,6 +11383,9 @@ var init_schema = __esm(() => {
       short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
       author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
     }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default — content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+    coalesce: exports_external.object({
+      window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+    }).optional().describe("Inbound coalescing — how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
     webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default — webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 — see #577.)"),
     webhook_dispatch: exports_external.object({
       github: exports_external.array(exports_external.object({

package/dist/vault/broker/server.js

@@ -11383,6 +11383,9 @@ var init_schema = __esm(() => {
       short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
       author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
     }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default — content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+    coalesce: exports_external.object({
+      window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+    }).optional().describe("Inbound coalescing — how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
     webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default — webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 — see #577.)"),
     webhook_dispatch: exports_external.object({
       github: exports_external.array(exports_external.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.14.17",
+  "version": "0.14.18",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_shared/telegram-style.md.hbs

@@ -34,13 +34,14 @@ If both `queued` and `steering` are somehow present, `steering` wins (explicit o
 **Self-narrate the classification.** At the top of your reply for any `steering` or `queued` message, include a brief italic one-liner so the user can correct you — e.g. `_↪️ Treating as steer on the prior task_` or `_📥 Queued as a new task_`.
 
 **Formatting** (Telegram HTML — `reply` and `stream_reply` default to `format: "html"` and convert markdown for you):
-- Use **bold** sparingly for emphasis on key facts only
+- In ordinary one-or-two-line conversational replies, keep **bold** light — emphasis on key facts only, never decoration.
+- **A multi-section message needs visual hierarchy or it reads as a flat wall.** When a reply groups several blocks — a status update, a "where things stand", a message announcing you're dispatching work, a summary with distinct buckets — give each section a **bold label on its own line** and separate sections with **one blank line**. Bold the label (e.g. `**✅ Done / running**`, `**🔲 Remaining**`, `**Next**`); the markdown→HTML converter renders `**label**` as bold, so the eye can find the structure. An emoji prefix with no bold leaves every line at equal weight — that's the plain-text dump to avoid. Bullet lines under a label are fine (`•` or `-`, one point per line).
 - Use `inline code` for filenames, commands, identifiers
 - Use ```fenced code blocks``` for multi-line code
-- Lists are fine; nested lists are not (Telegram flattens them awkwardly)
-- Don't use markdown headings (`##`) in replies — Telegram has no `<h1>` and they render as plain bold lines
-- Keep lines short — long unwrapped lines are hard to read on mobile
-- One idea per message when possible; the user can always ask for more
+- Nested lists are not supported (Telegram flattens them awkwardly) — keep bullets one level deep.
+- Don't use markdown headings (`##`) in replies — bold the label instead (`**Blockers**`, not `## Blockers`).
+- Keep lines short — long unwrapped lines are hard to read on mobile.
+- One idea per message for a quick exchange; a structured update can carry several ideas, but only when each sits under its own bold label with blank-line spacing between them.
 
 **Sound human, not AI.** The canonical list of AI-tells to avoid lives in `SOUL.md` under "Never". Apply those rules to every outbound message, not just long-form. For drafts above ~500 chars, or where you're unsure if the voice lands right, invoke the bundled `/humanizer` skill for a polish pass (it catalogues 29 patterns in detail). If `HUMANIZER_VOICE_FILE` is set and readable, treat its content as the user's personal voice template: match length, tone, vocabulary, and formatting habits described there. The user can generate one with `/humanizer-calibrate`.
 

package/telegram-plugin/dist/gateway/gateway.js

@@ -23737,6 +23737,9 @@ var init_schema = __esm(() => {
       short_name: exports_external.string().optional().describe("Telegraph account display name. Defaults to the agent's slug. Used at " + "first-publish to lazily create the account; cached thereafter."),
       author_name: exports_external.string().optional().describe("Telegraph article byline. Defaults to soul.name when set.")
     }).optional().describe("Long-reply publishing via Telegraph (#579). When enabled, replies " + "above the threshold publish as a Telegraph article rendered in " + "Telegram via native Instant View. Off by default \u2014 content " + "residency is real for some personas (lawyer, health-coach with PHI). " + "Cascades from defaults.channels.telegram.telegraph. " + "(Migrated from per-agent root in #596.)"),
+    coalesce: exports_external.object({
+      window_ms: exports_external.number().int().nonnegative().optional().describe("Sliding-window (ms) for merging consecutive inbound messages from " + "the same sender+topic into ONE Claude turn. Each new message resets " + "the timer; the turn starts once the sender pauses for this long. " + "Catches forwarded bursts, pasted text the Telegram client split " + "into several messages, and mixed text+media forwards. Default 500. " + "Set 0 to disable (every message becomes its own turn). Raise for " + "users who think in multiple short messages; the trade-off is the " + "single-message turn start is delayed by this much (the \uD83D\uDC40 ack still " + "fires immediately, so perceived latency is unchanged).")
+    }).optional().describe("Inbound coalescing \u2014 how the gateway groups rapid consecutive messages " + "into a single turn so a forwarded album or split paste doesn't fan out " + "into N separate turns. Cascades from defaults.channels.telegram.coalesce."),
     webhook_sources: exports_external.array(exports_external.enum(["github", "generic"])).optional().describe("External webhook sources allowed to ingest events into this agent's " + "log. POST /webhook/<agent>/<source> on the switchroom web server. " + "Each source has its own signature verification ('github' = " + "X-Hub-Signature-256 HMAC-SHA256, 'generic' = Bearer token). " + "Per-source secret read from ~/.switchroom/webhook-secrets.json " + "keyed by [agent][source]. Verified events append to " + "<agent>/telegram/webhook-events.jsonl for the agent to read on " + "demand. Off by default \u2014 webhook is the only untrusted-inbound " + "surface in the system, so opt-in is mandatory. " + "Cascades from defaults.channels.telegram.webhook_sources. " + "(Migrated from per-agent root in #596 \u2014 see #577.)"),
     webhook_dispatch: exports_external.object({
       github: exports_external.array(exports_external.object({
@@ -46341,23 +46344,70 @@ function redeliverBufferedInbound(buffer, agent, send, spool) {
   const pending = buffer.drain(agent);
   let redelivered = 0;
   let rebuffered = 0;
-  for (const msg of pending) {
+  for (const { merged, originals } of planBufferedRedelivery(pending)) {
     let delivered = false;
     try {
-      delivered = send(msg);
+      delivered = send(merged);
     } catch {
       delivered = false;
     }
     if (delivered) {
-      redelivered++;
-      spool?.ack(msg);
+      for (const o of originals)
+        spool?.ack(o);
+      redelivered += originals.length;
     } else {
-      buffer.push(agent, msg);
-      rebuffered++;
+      for (const o of originals)
+        buffer.push(agent, o);
+      rebuffered += originals.length;
     }
   }
   return { drained: pending.length, redelivered, rebuffered };
 }
+function isMergeableUserInbound(msg) {
+  return msg.type === "inbound" && (msg.meta == null || msg.meta.source == null);
+}
+function inboundHasMedia(msg) {
+  return msg.imagePath != null || msg.attachment != null;
+}
+function planBufferedRedelivery(pending) {
+  const out = [];
+  let run2 = [];
+  let runHasMedia = false;
+  const sameTarget = (a, b) => a.chatId === b.chatId && (a.threadId ?? null) === (b.threadId ?? null) && a.userId === b.userId;
+  const flush = () => {
+    if (run2.length === 0)
+      return;
+    out.push({ merged: run2.length === 1 ? run2[0] : mergeRun(run2), originals: run2 });
+    run2 = [];
+    runHasMedia = false;
+  };
+  for (const msg of pending) {
+    const msgHasMedia = inboundHasMedia(msg);
+    const canJoin = run2.length > 0 && isMergeableUserInbound(msg) && isMergeableUserInbound(run2[run2.length - 1]) && sameTarget(run2[run2.length - 1], msg) && !(runHasMedia && msgHasMedia);
+    if (!canJoin)
+      flush();
+    run2.push(msg);
+    runHasMedia = runHasMedia || msgHasMedia;
+  }
+  flush();
+  return out;
+}
+function mergeRun(run2) {
+  const last = run2[run2.length - 1];
+  const mediaEntry = run2.find(inboundHasMedia);
+  const merged = {
+    ...last,
+    text: run2.map((m) => m.text).join(`
+`)
+  };
+  delete merged.imagePath;
+  delete merged.attachment;
+  if (mediaEntry?.imagePath != null)
+    merged.imagePath = mediaEntry.imagePath;
+  if (mediaEntry?.attachment != null)
+    merged.attachment = mediaEntry.attachment;
+  return merged;
+}
 function idleDrainTick(buffer, agent, isBridgeAlive, send, spool) {
   if (!agent)
     return null;
@@ -46932,23 +46982,70 @@ function redeliverBufferedInbound2(buffer, agent, send, spool) {
   const pending = buffer.drain(agent);
   let redelivered = 0;
   let rebuffered = 0;
-  for (const msg of pending) {
+  for (const { merged, originals } of planBufferedRedelivery2(pending)) {
     let delivered = false;
     try {
-      delivered = send(msg);
+      delivered = send(merged);
     } catch {
       delivered = false;
     }
     if (delivered) {
-      redelivered++;
-      spool?.ack(msg);
+      for (const o of originals)
+        spool?.ack(o);
+      redelivered += originals.length;
     } else {
-      buffer.push(agent, msg);
-      rebuffered++;
+      for (const o of originals)
+        buffer.push(agent, o);
+      rebuffered += originals.length;
     }
   }
   return { drained: pending.length, redelivered, rebuffered };
 }
+function isMergeableUserInbound2(msg) {
+  return msg.type === "inbound" && (msg.meta == null || msg.meta.source == null);
+}
+function inboundHasMedia2(msg) {
+  return msg.imagePath != null || msg.attachment != null;
+}
+function planBufferedRedelivery2(pending) {
+  const out = [];
+  let run2 = [];
+  let runHasMedia = false;
+  const sameTarget = (a, b) => a.chatId === b.chatId && (a.threadId ?? null) === (b.threadId ?? null) && a.userId === b.userId;
+  const flush = () => {
+    if (run2.length === 0)
+      return;
+    out.push({ merged: run2.length === 1 ? run2[0] : mergeRun2(run2), originals: run2 });
+    run2 = [];
+    runHasMedia = false;
+  };
+  for (const msg of pending) {
+    const msgHasMedia = inboundHasMedia2(msg);
+    const canJoin = run2.length > 0 && isMergeableUserInbound2(msg) && isMergeableUserInbound2(run2[run2.length - 1]) && sameTarget(run2[run2.length - 1], msg) && !(runHasMedia && msgHasMedia);
+    if (!canJoin)
+      flush();
+    run2.push(msg);
+    runHasMedia = runHasMedia || msgHasMedia;
+  }
+  flush();
+  return out;
+}
+function mergeRun2(run2) {
+  const last = run2[run2.length - 1];
+  const mediaEntry = run2.find(inboundHasMedia2);
+  const merged = {
+    ...last,
+    text: run2.map((m) => m.text).join(`
+`)
+  };
+  delete merged.imagePath;
+  delete merged.attachment;
+  if (mediaEntry?.imagePath != null)
+    merged.imagePath = mediaEntry.imagePath;
+  if (mediaEntry?.attachment != null)
+    merged.attachment = mediaEntry.attachment;
+  return merged;
+}
 
 // gateway/inbound-delivery-machine-dispatch.ts
 var enabled6 = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== "0";
@@ -51140,10 +51237,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.14.17";
-var COMMIT_SHA = "95c1d475";
-var COMMIT_DATE = "2026-05-30T05:17:47Z";
-var LATEST_PR = 2005;
+var VERSION = "0.14.18";
+var COMMIT_SHA = "dddb8617";
+var COMMIT_DATE = "2026-05-30T23:35:26Z";
+var LATEST_PR = 2010;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -52852,19 +52949,22 @@ function looksLikeAuthCode(text) {
     return true;
   return false;
 }
+var bufferedAttachmentKeys = new Set;
 var inboundCoalescer = createInboundCoalescer({
   gapMs: () => loadAccess().coalescingGapMs ?? 500,
   merge: (entries) => {
     const last = entries[entries.length - 1];
+    const withAttachment = entries.find((e) => e.downloadImage != null || e.attachment != null);
     return {
       text: entries.map((e) => e.text).join(`
 `),
       ctx: last.ctx,
-      downloadImage: last.downloadImage,
-      attachment: last.attachment
+      downloadImage: withAttachment?.downloadImage,
+      attachment: withAttachment?.attachment
     };
   },
-  onFlush: (_key, merged) => {
+  onFlush: (key, merged) => {
+    bufferedAttachmentKeys.delete(key);
     handleInbound(merged.ctx, merged.text, merged.downloadImage, merged.attachment);
   }
 });
@@ -56020,19 +56120,29 @@ function safeName(s) {
   return s?.replace(/[<>\[\]\r\n;]/g, "_");
 }
 async function handleInboundCoalesced(ctx, text, downloadImage, attachment) {
-  if (downloadImage || attachment)
-    return handleInbound(ctx, text, downloadImage, attachment);
   if (parseInterruptMarker(text).isInterrupt) {
-    return handleInbound(ctx, text, undefined, undefined);
+    return handleInbound(ctx, text, downloadImage, attachment);
+  }
+  const hasAttachment = downloadImage != null || attachment != null;
+  if (hasAttachment && ctx.message?.media_group_id != null) {
+    return handleInbound(ctx, text, downloadImage, attachment);
   }
   const from = ctx.from;
   if (!from)
     return;
+  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);
+    }
+  }
   maybeEarlyAckReaction(ctx, from);
   const key = inboundCoalesceKey(String(ctx.chat.id), ctx.message?.message_thread_id, String(from.id));
   const result = inboundCoalescer.enqueue(key, { text, ctx, downloadImage, attachment });
   if (result.bypass)
-    return handleInbound(ctx, text, undefined, undefined);
+    return handleInbound(ctx, text, downloadImage, attachment);
+  if (hasAttachment)
+    bufferedAttachmentKeys.add(key);
 }
 function maybeEarlyAckReaction(ctx, from) {
   const msgId = ctx.message?.message_id;
@@ -60298,7 +60408,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 {
@@ -60334,7 +60444,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) => {
   const voice = ctx.message.voice;
@@ -60346,7 +60456,7 @@ bot.on("message:voice", async (ctx) => {
       const text = ctx.message.caption ? `${ctx.message.caption}
 
 [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,
@@ -60355,7 +60465,7 @@ bot.on("message:voice", async (ctx) => {
       return;
     }
   }
-  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 });
 });
 async function maybeTranscribeVoice(fileId, mimeType, language) {
   let apiKey = null;
@@ -60415,15 +60525,15 @@ async function maybeTranscribeVoice(fileId, mimeType, language) {
 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) => {
   const sticker = ctx.message.sticker;
@@ -60433,13 +60543,13 @@ bot.on("message:sticker", async (ctx) => {
   if (sticker.set_name)
     parts.push(`from "${sticker.set_name}"`);
   const text = parts.length > 0 ? `(sticker \u2014 ${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) => {
   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/gateway.ts

@@ -2997,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
@@ -3008,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)
   },
 })
@@ -8534,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),
@@ -8581,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)
 }
 
 /**
@@ -15560,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 {
@@ -15603,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 => {
@@ -15626,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,
@@ -15636,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 })
 })
 
 /**
@@ -15728,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 => {
@@ -15753,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 => {
@@ -15766,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,

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

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest'
-import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
+import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, planBufferedRedelivery, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
 import type { InboundMessage } from '../gateway/ipc-protocol.js'
 
 function inbound(source: string, ts = Date.now()): InboundMessage {
@@ -23,6 +23,35 @@ function inbound(source: string, ts = Date.now()): InboundMessage {
   }
 }
 
+/** An ordinary Telegram user message — NO meta.source, so it's mergeable. */
+function userMsg(
+  opts: {
+    text: string
+    chatId?: string
+    threadId?: number
+    userId?: number
+    ts?: number
+    imagePath?: string
+    attachment?: InboundMessage['attachment']
+  },
+): InboundMessage {
+  const ts = opts.ts ?? Date.now()
+  const m: InboundMessage = {
+    type: 'inbound',
+    chatId: opts.chatId ?? 'c1',
+    messageId: ts,
+    user: 'alice',
+    userId: opts.userId ?? 42,
+    ts,
+    text: opts.text,
+    meta: {},
+  }
+  if (opts.threadId != null) m.threadId = opts.threadId
+  if (opts.imagePath != null) m.imagePath = opts.imagePath
+  if (opts.attachment != null) m.attachment = opts.attachment
+  return m
+}
+
 describe('pending-inbound-buffer', () => {
   it('push + drain — FIFO order per agent', () => {
     const buf = createPendingInboundBuffer({ log: () => {} })
@@ -313,3 +342,258 @@ describe('durable-spool integration (finn/carrie lost-on-restart fix)', () => {
     })
   })
 })
+
+describe('planBufferedRedelivery — merge-on-drain (forwarded-burst across a turn boundary)', () => {
+  it('passes a single message through unchanged (run of one)', () => {
+    const a = userMsg({ text: 'solo', ts: 1 })
+    const plan = planBufferedRedelivery([a])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged).toBe(a) // identity preserved, no synthetic copy
+    expect(plan[0]!.originals).toEqual([a])
+  })
+
+  it('merges consecutive same-sender user messages into one turn (texts joined by \\n)', () => {
+    const a = userMsg({ text: 'first', ts: 1 })
+    const b = userMsg({ text: 'second', ts: 2 })
+    const c = userMsg({ text: 'third', ts: 3 })
+    const plan = planBufferedRedelivery([a, b, c])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.text).toBe('first\nsecond\nthird')
+    expect(plan[0]!.originals).toEqual([a, b, c]) // all three acked/rebuffered together
+  })
+
+  it('anchors the merged turn on the LAST message identity/meta', () => {
+    const a = userMsg({ text: 'first', ts: 10 })
+    const b = userMsg({ text: 'second', ts: 20 })
+    const plan = planBufferedRedelivery([a, b])
+    expect(plan[0]!.merged.messageId).toBe(20)
+    expect(plan[0]!.merged.ts).toBe(20)
+  })
+
+  it('NEVER merges a system inbound — meta.source isolates the #1150 wake-up class', () => {
+    const u1 = userMsg({ text: 'hi', ts: 1 })
+    const grant = inbound('vault_grant_approved', 2)
+    const u2 = userMsg({ text: 'there', ts: 3 })
+    const plan = planBufferedRedelivery([u1, grant, u2])
+    // The grant breaks the run; nothing merges across it.
+    expect(plan.map((p) => p.merged.text)).toEqual([
+      'hi',
+      'synthetic vault_grant_approved',
+      'there',
+    ])
+    expect(plan.every((p) => p.originals.length === 1)).toBe(true)
+  })
+
+  it('does not merge across different senders', () => {
+    const a = userMsg({ text: 'from-alice', userId: 1, ts: 1 })
+    const b = userMsg({ text: 'from-bob', userId: 2, ts: 2 })
+    const plan = planBufferedRedelivery([a, b])
+    expect(plan).toHaveLength(2)
+  })
+
+  it('does not merge across different topics (threadId)', () => {
+    const a = userMsg({ text: 'planning', threadId: 7, ts: 1 })
+    const b = userMsg({ text: 'admin', threadId: 9, ts: 2 })
+    const plan = planBufferedRedelivery([a, b])
+    expect(plan).toHaveLength(2)
+  })
+
+  it('does not merge across different chats', () => {
+    const a = userMsg({ text: 'dm', chatId: 'cA', ts: 1 })
+    const b = userMsg({ text: 'group', chatId: 'cB', ts: 2 })
+    const plan = planBufferedRedelivery([a, b])
+    expect(plan).toHaveLength(2)
+  })
+
+  it('carries a single attachment along even when it is NOT the last message', () => {
+    const photo = userMsg({ text: 'look', ts: 1, imagePath: '/tmp/p.jpg' })
+    const txt = userMsg({ text: 'at this', ts: 2 })
+    const plan = planBufferedRedelivery([photo, txt])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.text).toBe('look\nat this')
+    expect(plan[0]!.merged.imagePath).toBe('/tmp/p.jpg')
+  })
+
+  it('carries a single document attachment from the entry that owns it', () => {
+    const txt = userMsg({ text: 'here', ts: 1 })
+    const doc = userMsg({
+      text: '',
+      ts: 2,
+      attachment: { fileId: 'F1', mimeType: 'application/pdf', fileName: 'r.pdf' },
+    })
+    const plan = planBufferedRedelivery([txt, doc])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.attachment).toEqual({
+      fileId: 'F1',
+      mimeType: 'application/pdf',
+      fileName: 'r.pdf',
+    })
+  })
+
+  it('splits a run rather than putting two attachments in one turn (no silent media loss)', () => {
+    const p1 = userMsg({ text: 'one', ts: 1, imagePath: '/tmp/a.jpg' })
+    const p2 = userMsg({ text: 'two', ts: 2, imagePath: '/tmp/b.jpg' })
+    const plan = planBufferedRedelivery([p1, p2])
+    expect(plan).toHaveLength(2)
+    expect(plan[0]!.merged.imagePath).toBe('/tmp/a.jpg')
+    expect(plan[1]!.merged.imagePath).toBe('/tmp/b.jpg')
+  })
+
+  it('a leading text then media then text → text+media merge, then a fresh run', () => {
+    const t1 = userMsg({ text: 'intro', ts: 1 })
+    const p = userMsg({ text: 'pic', ts: 2, imagePath: '/tmp/p.jpg' })
+    const t2 = userMsg({ text: 'caption', ts: 3 })
+    const plan = planBufferedRedelivery([t1, p, t2])
+    // All three share one attachment max → single merged turn.
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.text).toBe('intro\npic\ncaption')
+    expect(plan[0]!.merged.imagePath).toBe('/tmp/p.jpg')
+  })
+
+  it('preserves the run total — sum of originals equals input length (lossless)', () => {
+    const msgs = [
+      userMsg({ text: 'a', ts: 1 }),
+      userMsg({ text: 'b', ts: 2 }),
+      inbound('cron', 3),
+      userMsg({ text: 'c', ts: 4 }),
+    ]
+    const plan = planBufferedRedelivery(msgs)
+    const total = plan.reduce((n, p) => n + p.originals.length, 0)
+    expect(total).toBe(msgs.length)
+  })
+
+  it('end-to-end: redeliverBufferedInbound fans a 3-message burst into ONE send', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('ziggy', userMsg({ text: 'part 1', ts: 1 }))
+    buf.push('ziggy', userMsg({ text: 'part 2', ts: 2 }))
+    buf.push('ziggy', userMsg({ text: 'part 3', ts: 3 }))
+    const sent: string[] = []
+    const r = redeliverBufferedInbound(buf, 'ziggy', (m) => {
+      sent.push(m.text)
+      return true
+    })
+    expect(sent).toEqual(['part 1\npart 2\npart 3']) // ONE turn, not three
+    expect(r).toEqual({ drained: 3, redelivered: 3, rebuffered: 0 })
+    expect(buf.depth('ziggy')).toBe(0)
+  })
+
+  it('end-to-end: a failed send re-buffers ALL originals of the merged run (lossless)', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('ziggy', userMsg({ text: 'part 1', ts: 1 }))
+    buf.push('ziggy', userMsg({ text: 'part 2', ts: 2 }))
+    const r = redeliverBufferedInbound(buf, 'ziggy', () => false)
+    expect(r).toEqual({ drained: 2, redelivered: 0, rebuffered: 2 })
+    expect(buf.depth('ziggy')).toBe(2) // both originals back, nothing lost
+    expect(buf.drain('ziggy').map((m) => m.text)).toEqual(['part 1', 'part 2'])
+  })
+})
+
+describe('planBufferedRedelivery — seeded fuzz over random burst schedules', () => {
+  // Tiny deterministic PRNG (mulberry32) so failures reproduce from the seed.
+  function rng(seed: number): () => number {
+    let s = seed >>> 0
+    return () => {
+      s |= 0
+      s = (s + 0x6d2b79f5) | 0
+      let t = Math.imul(s ^ (s >>> 15), 1 | s)
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+    }
+  }
+
+  const SOURCES = ['vault_grant_approved', 'cron', 'reaction', 'approval', 'handback']
+
+  function randomSchedule(rand: () => number): InboundMessage[] {
+    const n = 1 + Math.floor(rand() * 12)
+    const out: InboundMessage[] = []
+    for (let i = 0; i < n; i++) {
+      const roll = rand()
+      if (roll < 0.3) {
+        // system inbound (has meta.source) — never mergeable
+        out.push(inbound(SOURCES[Math.floor(rand() * SOURCES.length)]!, i + 1))
+      } else {
+        // user message: random sender/topic/chat, sometimes media
+        const hasImg = rand() < 0.2
+        const hasDoc = !hasImg && rand() < 0.15
+        out.push(
+          userMsg({
+            text: `m${i}`,
+            ts: i + 1,
+            chatId: rand() < 0.5 ? 'cA' : 'cB',
+            userId: rand() < 0.5 ? 1 : 2,
+            threadId: rand() < 0.4 ? (rand() < 0.5 ? 7 : 9) : undefined,
+            imagePath: hasImg ? `/tmp/img${i}.jpg` : undefined,
+            attachment: hasDoc
+              ? { fileId: `F${i}`, mimeType: 'application/pdf' }
+              : undefined,
+          }),
+        )
+      }
+    }
+    return out
+  }
+
+  function hasMedia(m: InboundMessage): boolean {
+    return m.imagePath != null || m.attachment != null
+  }
+  function isSystem(m: InboundMessage): boolean {
+    return m.meta != null && m.meta.source != null
+  }
+
+  it('holds all invariants across 5000 random schedules', () => {
+    const rand = rng(0xC0FFEE)
+    for (let iter = 0; iter < 5000; iter++) {
+      const pending = randomSchedule(rand)
+      const plan = planBufferedRedelivery(pending)
+
+      // 1. Lossless + order-preserving: flattening originals reproduces input.
+      const flat = plan.flatMap((p) => p.originals)
+      expect(flat).toEqual(pending)
+
+      // 2. Count is conserved.
+      expect(flat.length).toBe(pending.length)
+
+      for (const { merged, originals } of plan) {
+        // 3. A multi-message run never carries >1 attachment.
+        const mediaCount = originals.filter(hasMedia).length
+        expect(mediaCount).toBeLessThanOrEqual(1)
+
+        // 4. A system inbound is NEVER part of a multi-message run, and is
+        //    never silently mutated (passes through by identity).
+        if (originals.length > 1) {
+          expect(originals.every((m) => !isSystem(m))).toBe(true)
+        } else {
+          expect(merged).toBe(originals[0])
+        }
+
+        // 5. Every message in a merged run shares the same (chat, thread, user).
+        if (originals.length > 1) {
+          const k = (m: InboundMessage) =>
+            `${m.chatId}|${m.threadId ?? null}|${m.userId}`
+          expect(new Set(originals.map(k)).size).toBe(1)
+          // text is the \n-join of the run in order
+          expect(merged.text).toBe(originals.map((m) => m.text).join('\n'))
+          // the single attachment (if any) comes from the owning entry
+          const owner = originals.find(hasMedia)
+          expect(merged.imagePath).toBe(owner?.imagePath)
+          expect(merged.attachment).toEqual(owner?.attachment)
+        }
+      }
+    }
+  })
+
+  it('redeliver counts always satisfy drained == redelivered + rebuffered (5000 schedules)', () => {
+    const rand = rng(0x5EED)
+    for (let iter = 0; iter < 5000; iter++) {
+      const pending = randomSchedule(rand)
+      const buf = createPendingInboundBuffer({ log: () => {} })
+      for (const m of pending) buf.push('fuzz', m)
+      // Randomly succeed/fail each send to exercise both branches.
+      const r = redeliverBufferedInbound(buf, 'fuzz', () => rand() < 0.5)
+      expect(r.drained).toBe(pending.length)
+      expect(r.redelivered + r.rebuffered).toBe(r.drained)
+      // Whatever didn't deliver is still buffered (nothing lost).
+      expect(buf.depth('fuzz')).toBe(r.rebuffered)
+    }
+  })
+})

package/telegram-plugin/tests/worker-feed-dispatch.test.ts

@@ -61,3 +61,80 @@ describe('resolveWorkerFeedDispatch (#2002 regression pin)', () => {
     expect(resolveWorkerFeedDispatch(null, '').isBackground).toBe(false)
   })
 })
+
+// Deterministic PRNG (mulberry32) so a failing case is reproducible from the
+// printed seed rather than flaking once and vanishing.
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0
+  return () => {
+    a |= 0
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+// Adversarial description fragments the gateway might hand us — empty, the
+// literal watcher placeholder, whitespace-only, control chars, multi-byte
+// unicode/emoji, and a pathologically long task. A registry description is
+// only "real" (must win the feed header) when it's a non-empty string.
+const DESC_POOL: (string | null)[] = [
+  null,
+  '',
+  'sub-agent',
+  '   ',
+  '\n\t',
+  'Background ten-step worker',
+  'Crawl the repo for dead code',
+  '🔧 deploy · staging',
+  'café — naïve façade',
+  '0',
+  'false',
+  'a'.repeat(4096),
+  'line1\nline2\nline3',
+  'desc with "quotes" & <tags>',
+]
+
+const WATCHER_POOL = ['sub-agent', '', 'sub-agent ', 'fallback', '🤖', 'x'.repeat(512)]
+
+describe('resolveWorkerFeedDispatch — randomized property sweep', () => {
+  it('holds the #2002 invariants across 20k random registry rows', () => {
+    for (let seed = 1; seed <= 20000; seed++) {
+      const rng = mulberry32(seed)
+      const pick = <T>(arr: T[]): T => arr[Math.floor(rng() * arr.length)]!
+
+      const rowMissing = rng() < 0.25
+      const background = rng() < 0.5
+      const description = pick(DESC_POOL)
+      const watcher = pick(WATCHER_POOL)
+      const sub = rowMissing ? null : makeSub({ background, description })
+
+      const out = resolveWorkerFeedDispatch(sub, watcher)
+      const ctx = `seed=${seed} rowMissing=${rowMissing} bg=${background} desc=${JSON.stringify(description)} watcher=${JSON.stringify(watcher)}`
+
+      // 1. Types are always concrete — the feed renderer never sees undefined.
+      expect(typeof out.isBackground, ctx).toBe('boolean')
+      expect(typeof out.feedDescription, ctx).toBe('string')
+
+      // 2. isBackground mirrors the row (or false when missing) — a registry
+      //    miss must never promote a foreground turn into a background one.
+      expect(out.isBackground, ctx).toBe(rowMissing ? false : background)
+
+      const realDescription =
+        !rowMissing && typeof description === 'string' && description.length > 0
+
+      if (realDescription) {
+        // 3. THE bug guard: a real registry description always wins the header,
+        //    regardless of the watcher's generic 'sub-agent' placeholder.
+        expect(out.feedDescription, ctx).toBe(description)
+      } else {
+        // 4. Otherwise we fall back to exactly the watcher label, untouched.
+        expect(out.feedDescription, ctx).toBe(watcher)
+      }
+
+      // 5. Pure + deterministic: identical inputs yield a deep-equal result.
+      expect(resolveWorkerFeedDispatch(sub, watcher), ctx).toEqual(out)
+    }
+  })
+})