polygram 0.18.2 → 0.20.0

package/lib/telegram/streamer.js

@@ -45,7 +45,7 @@ const DEFAULT_THROTTLE_MS = 1000;
 const THROTTLE_FLOOR_MS = 250;
 
 function createStreamer({
-  send,                                   // async (text) -> { message_id }
+  send,                    // async (text) -> { message_id, _hadReplyAnchor? }
   edit,                                   // async (msg_id, text) -> void
   deleteMessage = null,                   // async (msg_id) -> void  [optional]
   minChars = DEFAULT_MIN_CHARS,
@@ -87,13 +87,17 @@ function createStreamer({
   // Optional progressive rich-message rendering. A null callback keeps
   // the streamer on its plain-text path.
   //
-  // toRichPayload(text, { partial }) -> { blocks, usedRich } | null
+  // toRichPayload(text, { partial }) ->
+  //   { blocks, usedRich, rescueEntries? } | null
   //   Called on every flush/finalize with the CURRENT latestText/finalText
   //   (untruncated — rich content is never char-truncated with a "..."
   //   the way plain live-preview text is; partial:true tells it to hold
   //   back a possibly-incomplete trailing block, see lib/telegram/rich.js).
   //   usedRich:false (or a null return) means "not rich this tick" — the
   //   streamer falls through to the existing plain-text path unchanged.
+  //   Final media-bearing payloads include rescueEntries. The streamer
+  //   carries them into redelivery results and uses their presence to
+  //   decide whether a detached intermediate bubble needs sealing.
   //   The callback may return a different result on each call when live
   //   configuration or capability state changes.
   toRichPayload = null,
@@ -107,6 +111,7 @@ function createStreamer({
   throttleMs = Math.max(THROTTLE_FLOOR_MS, throttleMs);
   let state = 'idle';       // 'idle' | 'live' | 'finalized'
   let msgId = null;
+  let hadReplyAnchor = false;
   let currentText = '';     // what's on screen right now (truncated to maxLen) — plain-path only
   let currentRichJson = null; // JSON.stringify of the last-sent rich blocks, or null when not in rich mode
   let latestText = '';      // latest we've been told about
@@ -114,6 +119,8 @@ function createStreamer({
   let pendingEdit = null;   // timer id
   let flushPromise = null;  // serialized flush chain (for back-pressure)
   let flushQueued = false;  // latest text changed while a flush was active
+  let initialSendPromise = null; // active generation's initial send
+  let sealChain = Promise.resolve(); // detached bubbles, in boundary order
   let bubbleGeneration = 0; // invalidates state commits from superseded bubbles
   // 0.7.2: msg_ids of bubbles that have been superseded by
   // forceNewMessage(). The caller (polygram.js handleMessage at
@@ -175,21 +182,36 @@ function createStreamer({
     // delivered via the caller's normal path on finalize().
     if (state === 'idle') {
       if (text.length < minChars) return;
+      const generation = bubbleGeneration;
       state = 'live';
       currentText = truncateForLive(text);
+      let sendPromise;
       try {
-        const res = await send(currentText);
+        sendPromise = Promise.resolve(send(currentText));
+      } catch (err) {
+        sendPromise = Promise.reject(err);
+      }
+      initialSendPromise = sendPromise;
+      try {
+        const res = await sendPromise;
+        if (generation !== bubbleGeneration) return;
         msgId = res?.message_id ?? null;
+        hadReplyAnchor = res?._hadReplyAnchor === true;
         lastEditTs = clock();
         if (msgId == null) {
           // Caller failed to get a message_id — revert to idle; finalize
           // will fall through to normal send path.
           state = 'idle';
           msgId = null;
+          hadReplyAnchor = false;
         }
       } catch (err) {
+        if (generation !== bubbleGeneration) return;
         logger.error(`[stream] initial send failed: ${err.message}`);
         state = 'idle';
+        hadReplyAnchor = false;
+      } finally {
+        if (initialSendPromise === sendPromise) initialSendPromise = null;
       }
       return;
     }
@@ -210,9 +232,9 @@ function createStreamer({
   // Decide the rich-vs-plain payload for the CURRENT latestText/finalText.
   // Shared by flush() and finalize() so the "only attempt rich under the
   // rich char cap" guard and the upgrade-event firing live in one place.
-  function resolveRichPayload(text, { partial }) {
+  function resolveRichPayload(text, { partial, allowOverflow = false }) {
     if (!toRichPayload) return null;
-    if (text.length > richMaxLen) {
+    if (text.length > richMaxLen && !allowOverflow) {
       // Edge case, not fully engineered (documented limitation): a
       // mid-stream reply that's ALREADY past the rich cap while still
       // growing. Rather than flap into a truncated/ellipsis rich render
@@ -241,11 +263,15 @@ function createStreamer({
       return flushPromise;
     }
 
+    const generation = bubbleGeneration;
     const run = (async () => {
       do {
         flushQueued = false;
         await flushOnce();
-      } while (flushQueued && state === 'live' && msgId != null);
+      } while (flushQueued
+        && generation === bubbleGeneration
+        && state === 'live'
+        && msgId != null);
     })();
     flushPromise = run;
     try {
@@ -272,6 +298,7 @@ function createStreamer({
         // can render the same Markdown through the plain-text path.
         const editResult = await edit(editMsgId, {
           rich: true, blocks: richPayload.blocks, sourceText,
+          phase: 'preview', hadReplyAnchor,
         });
         if (generation !== bubbleGeneration || msgId !== editMsgId) return;
         // A rich editor can resolve successfully after sending the same
@@ -307,6 +334,62 @@ function createStreamer({
     }
   }
 
+  function appendSealJob(job, label = 'seal') {
+    const run = sealChain.then(job);
+    sealChain = run.catch((err) => {
+      const errorClass = err?.name || 'Error';
+      logger.error?.(`[stream] ${label} failed (${errorClass})`);
+    });
+    return sealChain;
+  }
+
+  async function drainSeals() {
+    while (true) {
+      const pending = sealChain;
+      await pending;
+      if (pending === sealChain) return;
+    }
+  }
+
+  async function awaitDetached(promise, label) {
+    try {
+      await promise;
+    } catch (err) {
+      logger.error?.(`[stream] ${label} failed (${err?.name || 'Error'})`);
+    }
+  }
+
+  async function sealBubble(snapshot) {
+    let targetMsgId = snapshot.msgId;
+    let targetHadReplyAnchor = snapshot.hadReplyAnchor;
+
+    if (snapshot.initialSendPromise) {
+      const res = await snapshot.initialSendPromise;
+      targetMsgId = res?.message_id ?? targetMsgId;
+      targetHadReplyAnchor = res?._hadReplyAnchor === true;
+    }
+    if (snapshot.flushPromise) {
+      await awaitDetached(snapshot.flushPromise, 'detached bubble flush');
+    }
+    if (targetMsgId == null || snapshot.sourceText.length > richMaxLen || !toRichPayload) return;
+
+    const payload = toRichPayload(snapshot.sourceText, { partial: false });
+    if (!payload?.usedRich || !Array.isArray(payload.rescueEntries)
+      || payload.rescueEntries.length === 0) {
+      return;
+    }
+    const json = JSON.stringify(payload.blocks);
+    if (json === snapshot.currentRichJson) return;
+
+    await edit(targetMsgId, {
+      rich: true,
+      blocks: payload.blocks,
+      sourceText: snapshot.sourceText,
+      phase: 'seal',
+      hadReplyAnchor: targetHadReplyAnchor,
+    });
+  }
+
   // 0.7.0: explicitly drain any pending edit. Useful when the caller
   // is about to make a finalize/discard decision and wants the bubble's
   // visual state to be accurate (no stale half-rendered text under a
@@ -314,6 +397,7 @@ function createStreamer({
   async function flushDraft() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; await flush(); }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
   }
 
   // Reset bubble state so the next onChunk creates a NEW message.
@@ -330,18 +414,29 @@ function createStreamer({
   // rc.44 reverts to the 0.7.0 preserve-all default. Opt back into
   // the 0.7.2 behaviour with `preserveIntermediateBubbles: false`.
   //
-  // When preserving, we still cancel the pending throttled edit (it
-  // wouldn't fire after we transition to a new bubble anyway) but
-  // there may be a recently-flushed edit in flight whose result we
-  // don't await — the bubble will display whatever its last
-  // successful edit landed, which is typically very close to the
-  // segment's final text (throttle is 250ms; segments take seconds).
+  // The old bubble is detached synchronously. Preserved bubbles enqueue
+  // one final media-aware edit behind any request already targeting that
+  // message; terse bubbles retain late initial-send ids for cleanup.
   function forceNewMessage() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
-    if (msgId != null && !preserveIntermediateBubbles) {
-      archived.push(msgId);
-    }
+    const snapshot = {
+      sourceText: latestText,
+      msgId,
+      hadReplyAnchor,
+      currentRichJson,
+      initialSendPromise,
+      flushPromise,
+    };
+    const hadOutgoingMessage = state === 'live'
+      && (snapshot.msgId != null || snapshot.initialSendPromise != null);
+
+    // Detach in-flight work before resetting. Conditional identity checks
+    // in onChunk()/flush() keep old completions from clearing new promises
+    // or committing state into the next generation.
+    initialSendPromise = null;
+    flushPromise = null;
     msgId = null;
+    hadReplyAnchor = false;
     currentText = '';
     currentRichJson = null; // new bubble starts plain — see toRichPayload doc
     latestText = '';
@@ -349,6 +444,27 @@ function createStreamer({
     lastEditTs = 0;
     flushQueued = false;
     bubbleGeneration += 1;
+
+    if (!hadOutgoingMessage) return;
+
+    if (preserveIntermediateBubbles) {
+      appendSealJob(() => sealBubble(snapshot));
+      return;
+    }
+
+    if (snapshot.msgId != null) archived.push(snapshot.msgId);
+    if (snapshot.initialSendPromise || snapshot.flushPromise) {
+      appendSealJob(async () => {
+        if (snapshot.initialSendPromise) {
+          const res = await snapshot.initialSendPromise;
+          const lateMsgId = res?.message_id ?? null;
+          if (lateMsgId != null) archived.push(lateMsgId);
+        }
+        if (snapshot.flushPromise) {
+          await awaitDetached(snapshot.flushPromise, 'detached bubble cleanup flush');
+        }
+      }, 'detached bubble cleanup');
+    }
   }
 
   // 0.7.0: delete the current bubble via the injected deleteMessage
@@ -365,6 +481,7 @@ function createStreamer({
   async function discard() {
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
     const idToDelete = msgId;
     state = 'finalized';
     msgId = null;
@@ -399,6 +516,7 @@ function createStreamer({
     if (state === 'finalized') return { streamed: false, msgId, finalEditOk: false, overflow: false };
     if (pendingEdit) { cancel(pendingEdit); pendingEdit = null; }
     if (flushPromise) { try { await flushPromise; } catch {} }
+    await drainSeals();
 
     if (state === 'idle') {
       state = 'finalized';
@@ -414,15 +532,20 @@ function createStreamer({
     // apples-to-apples (currentText was already transformed in onChunk).
     let body = applyTransform(finalText ?? latestText);
     if (errorSuffix) body = `${body}\n\n⚠️ ${errorSuffix}`;
+    const finalHadReplyAnchor = hadReplyAnchor;
 
     // Finalization evaluates the complete body, so no trailing block is
     // held back as potentially incomplete.
-    const richPayload = resolveRichPayload(body, { partial: false });
+    const richPayload = resolveRichPayload(body, { partial: false, allowOverflow: true });
     if (richPayload) {
       // Rich finalization uses the rich-message cap; applying the smaller
       // plain-message cap would unnecessarily redeliver valid rich bodies.
       if (body.length > richMaxLen) {
-        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true };
+        return {
+          streamed: true, msgId, finalText: body, finalEditOk: false, overflow: true,
+          rescueEntries: richPayload.rescueEntries || [],
+          hadReplyAnchor: finalHadReplyAnchor,
+        };
       }
       const json = JSON.stringify(richPayload.blocks);
       if (json === currentRichJson) {
@@ -430,7 +553,10 @@ function createStreamer({
       }
       const wasRich = currentRichJson !== null;
       try {
-        const editResult = await edit(msgId, { rich: true, blocks: richPayload.blocks, sourceText: body });
+        const editResult = await edit(msgId, {
+          rich: true, blocks: richPayload.blocks, sourceText: body,
+          phase: 'final', hadReplyAnchor: finalHadReplyAnchor,
+        });
         // A fallback still delivered the final content, but as plain text.
         const wentRich = editResult == null || editResult.wentRich !== false;
         if (wentRich) {
@@ -440,10 +566,20 @@ function createStreamer({
           currentText = body;
           currentRichJson = null;
         }
+        if (editResult?.bubbleRemoved) {
+          msgId = null;
+          currentText = '';
+          currentRichJson = null;
+          hadReplyAnchor = false;
+        }
         return { streamed: true, msgId, finalText: body, finalEditOk: true, overflow: false };
       } catch (err) {
         logger.error(`[stream] final rich edit failed: ${err.message}`);
-        return { streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false };
+        return {
+          streamed: true, msgId, finalText: body, finalEditOk: false, overflow: false,
+          rescueEntries: richPayload.rescueEntries || [],
+          hadReplyAnchor: finalHadReplyAnchor,
+        };
       }
     }
 
@@ -485,6 +621,7 @@ function createStreamer({
     finalize,
     flushDraft,
     forceNewMessage,
+    drainSeals,
     discard,
     archive,
     getArchived,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.18.2",
+  "version": "0.20.0",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {

package/polygram.js

@@ -49,7 +49,7 @@ const { extractAssistantText } = require('@shumkov/orchestra');
 // and reused by createChannelsToolDispatcher inside main() — Claude replies
 // containing code blocks or HTML-style tags aren't split mid-element by the
 // size cap.
-const { createChannelsToolDispatcher } = require('./lib/process/channels-tool-dispatcher');
+const { createChannelsToolDispatcher, buildAllowedRoots } = require('./lib/process/channels-tool-dispatcher');
 const { createTmuxRunner } = require('@shumkov/orchestra');
 const { sweepTmuxOrphans } = require('@shumkov/orchestra').orphanSweep;
 // rc.42: autosteer-buffer module deleted. Native SDK priority push
@@ -98,7 +98,16 @@ const { createStreamer } = require('./lib/telegram/streamer');
 const { chunkMarkdownText } = require('./lib/telegram/chunk');
 const {
   toTelegramRichBlocks, resolveRichTextEnabled, isRichCapabilityError, isRichContentError,
+  stripMediaMarkdown,
 } = require('./lib/telegram/rich');
+const {
+  createRichMediaResolver,
+  createMediaDeliveryContext,
+  createMediaFileIdCache,
+  collectMediaRescueEntries,
+  PHOTO_UPLOAD_CEILING,
+  OTHER_MEDIA_UPLOAD_CEILING,
+} = require('./lib/telegram/rich-media');
 const { createRichEditor } = require('./lib/telegram/rich-edit');
 const { buildPolygramDisplayHint } = require('./lib/telegram/display-hint');
 const { redactBotToken, stripUrlCredentials } = require('./lib/error/net');
@@ -321,6 +330,7 @@ let richKnownUnsupported = false;
 // safe to reference early because it's a stable function that does its
 // own live lookups internally when called.
 let richEditMessageText;
+let richMediaFileIdCache;
 
 // 0.15 secret redaction (agent-flagged path): the agent marks a secret it saw
 // in the user's message with `[redact:<secret>]`. parseResponse / stripInlineTags
@@ -992,7 +1002,6 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     effort: chatConfig.effort,
     ...(linkPreview === false ? { linkPreview: false } : {}),
   };
-
   // 0.7.2: only the FIRST bubble in a turn quotes the user's message
   // via reply_parameters. When a tool-heavy turn produces multiple
   // assistant messages (each spawning its own bubble via
@@ -1018,9 +1027,77 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // content qualifies. Those delivery paths intentionally remain plain.
   // Re-read both controls for every flush so a config change or a
   // capability result applies to the turn already in progress.
+  // Typed media resolution for rich replies. Same
+  // trust boundary as reply(files): roots are the per-session staging
+  // dir plus the session's spawn cwd (topic override wins, mirroring
+  // getSessionSpawnIdentity) — path-set parity with the channels
+  // dispatcher, which builds its roots from the same inputs. URL media
+  // is disabled when a self-hosted Bot API server is configured (its
+  // URL-fetch origin is unverified — see lib/telegram/rich-media.js).
+  const _mediaTopicCfg = getTopicConfig(chatConfig, threadIdStr || null);
+  const mediaAllowedRoots = buildAllowedRoots({
+    sessionKey,
+    sessionCwd: _mediaTopicCfg.cwd || chatConfig.cwd || null,
+  });
+  const maxMediaOverride = resolveMaxFileOverride(config, chatId, threadId);
+  const resolveRichMedia = createRichMediaResolver({
+    allowedRoots: mediaAllowedRoots,
+    fileIdCache: richMediaFileIdCache,
+    maxPhotoBytes: Math.min(
+      PHOTO_UPLOAD_CEILING,
+      maxMediaOverride ?? PHOTO_UPLOAD_CEILING,
+    ),
+    maxOtherMediaBytes: Math.min(
+      OTHER_MEDIA_UPLOAD_CEILING,
+      maxMediaOverride ?? OTHER_MEDIA_UPLOAD_CEILING,
+    ),
+    allowUrlMedia: !config.bot?.apiRoot,
+    logEvent: (kind, detail) => logEvent(kind, {
+      chat_id: chatId, thread_id: threadId, bot: BOT_NAME, ...detail,
+    }),
+  });
   const toRichPayload = (text, opts) => {
     if (richKnownUnsupported || !resolveRichTextEnabled(config, chatId, threadId)) return null;
-    return toTelegramRichBlocks(text, opts);
+    const payload = toTelegramRichBlocks(text, { ...opts, resolveMedia: resolveRichMedia });
+    if (!opts.partial && payload?.usedRich) {
+      return {
+        ...payload,
+        rescueEntries: collectMediaRescueEntries(payload.blocks),
+      };
+    }
+    return payload;
+  };
+  const mediaContext = createMediaDeliveryContext({
+    allowedRoots: mediaAllowedRoots,
+    fileIdCache: richMediaFileIdCache,
+    tg,
+    bot,
+    chatId,
+    threadId,
+    replyToMessageId: msg.message_id,
+    botName: BOT_NAME,
+    logEvent: (kind, detail) => logEvent(kind, {
+      chat_id: chatId, thread_id: threadId, bot: BOT_NAME, ...detail,
+    }),
+    setDeliveryError: () => reactor?.setState('ERROR'),
+    logger: { warn: (m) => console.error(`[${label}] ${m}`) },
+  });
+  // Plain-path text hygiene for rich-enabled chats: the live preview
+  // streams PLAIN until the rich gate trips (and stays plain if the
+  // capability latch fires), so a reply's image markdown — including a
+  // still-incomplete trailing "![shot](/abs/pa…" fragment — would
+  // otherwise render its raw local path into the visible bubble.
+  // Degrade media markdown to caption text on every plain send/edit.
+  // The streamer's internal dedup state keeps the UNsanitized text on
+  // both sides of its comparisons, so this stays a display-only
+  // transform (same class as tg()'s markdown→HTML conversion).
+  const sanitizeLiveText = (text) => {
+    if (!resolveRichTextEnabled(config, chatId, threadId)) return text;
+    const clean = stripMediaMarkdown(text);
+    // An image-only chunk can sanitize to nothing; keep the bubble
+    // alive with a minimal placeholder rather than tripping tg()'s
+    // empty-text guard.
+    return clean.trim() ? clean : '…';
   };
 
   const streamer = createStreamer({
@@ -1035,8 +1112,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       logEvent('rich-streaming-upgrade', { chat_id: chatId, thread_id: threadId, bot: BOT_NAME });
     },
     send: async (text) => {
+      const hadReplyAnchor = !firstBubbleSent;
       const params = {
-        chat_id: chatId, text,
+        chat_id: chatId, text: sanitizeLiveText(text),
         ...(threadId && { message_thread_id: threadId }),
       };
       if (!firstBubbleSent) {
@@ -1047,7 +1125,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         params.reply_parameters = { message_id: msg.message_id, allow_sending_without_reply: true };
         firstBubbleSent = true;
       }
-      return tg(bot, 'sendMessage', params, outMetaBase);
+      const res = await tg(bot, 'sendMessage', params, outMetaBase);
+      return res && typeof res === 'object'
+        ? { ...res, _hadReplyAnchor: hadReplyAnchor }
+        : res;
     },
     edit: async (messageId, payload) => {
       // The streamer emits either a plain string or a rich payload with
@@ -1057,6 +1138,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         return richEditMessageText({
           bot, chatId, threadId, messageId,
           blocks: payload.blocks, sourceText: payload.sourceText,
+          phase: payload.phase,
+          mediaContext,
+          hadReplyAnchor: payload.hadReplyAnchor,
         });
       }
       const text = payload;
@@ -1070,7 +1154,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         return await tg(bot, 'editMessageText', {
           chat_id: chatId,
           message_id: messageId,
-          text,
+          text: sanitizeLiveText(text),
         }, { source: 'bot-reply-stream-edit', botName: BOT_NAME });
       } catch (err) {
         // Stream-edit failures would otherwise be invisible — edits
@@ -1078,7 +1162,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         // want the failure path specifically surfaced). Log to events.
         logEvent('telegram-edit-failed', {
           chat_id: chatId, msg_id: messageId,
-          api_error: err.message?.slice(0, 200),
+          // Network errors can embed the request URL, which carries the
+          // bot token — redact before persisting, matching rich-edit.js
+          // and api.js's handling of the same error class.
+          api_error: redactBotToken(err.message)?.slice(0, 200),
           bot: BOT_NAME,
         });
         throw err;
@@ -1674,6 +1761,7 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         if (fin.finalEditOk) {
           // Preview was successfully edited to the final text.
           // No follow-up messages needed.
+          await mediaContext.flushPartialDeliveryWarning(outMetaBase);
           await sendInlineStickers();
           await sendInlineReactions();
           await cleanupArchivedBubbles();
@@ -1685,7 +1773,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
           // stuck. reactor.stop() in the finally only kills timers,
           // not the visible reaction. Clear here, mirroring the
           // rc.10 block — AFTER delivery so there's no visual gap.
-          reactor.clear().catch(() => {});
+          if (!mediaContext.deliveryIncomplete) {
+            reactor.clear().catch(() => {});
+          }
           clearAutosteeredReactions(sessionKey).catch(() => {});
           console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | streamed | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
           markReplied();
@@ -1694,9 +1784,20 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         // Preview can't hold the final body (overflow OR last edit
         // failed even after our HTML→plain fallback). Delete it and
         // send the body as proper chunks.
-        try { await streamer.discard(); }
+        let discarded = { msgId: fin.msgId, deleted: false };
+        try { discarded = await streamer.discard(); }
         catch (err) { console.error(`[${label}] discard failed: ${err.message}`); }
-        const chunks = chunkMarkdownText(parsed.text, TG_CHUNK_BUDGET);
+        if (discarded.msgId != null && !discarded.deleted) {
+          mediaContext.recordDeletionFailures(1);
+        }
+        // Rich-enabled chats may carry media markdown; plain chunks cannot
+        // render it, and a raw `![cap](/abs/path)` would leak a local path.
+        // Degrade the chunk text to captions before the validated media
+        // entries are redelivered as ordered sidecars below.
+        const redeliverText = resolveRichTextEnabled(config, chatId, threadId)
+          ? stripMediaMarkdown(parsed.text)
+          : parsed.text;
+        const chunks = chunkMarkdownText(redeliverText, TG_CHUNK_BUDGET);
         const r = await deliverReplies({
           bot,
           send: (b, method, params, m) => tg(b, method, params, m),
@@ -1708,29 +1809,20 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
           logger: { error: (m) => console.error(`[${label}] ${m}`) },
         });
         const reason = fin.overflow ? 'overflow' : 'edit-failed';
+        mediaContext.recordTextFailures(r.failed.length);
+        const mediaResult = await mediaContext.rescueEntries(fin.rescueEntries, {
+          trigger: reason,
+          anchorFirst: chunks.length === 0 && discarded.deleted && fin.hadReplyAnchor,
+          meta: outMeta,
+        });
         logEvent('telegram-stream-redeliver', {
           chat_id: chatId, msg_id: msg.message_id,
           reason, chunks: chunks.length,
           delivered: r.sent.length, failed: r.failed.length,
+          media_delivered: mediaResult.sent, media_failed: mediaResult.failed,
           bot: BOT_NAME,
         });
-        // 0.7.1: surface partial-failure to the user. Without this,
-        // a chunk-3-of-5 failure leaves a coherent-looking reply with
-        // a silent gap (the user reads chunks 1, 2, 4, 5 unaware
-        // that chunk 3 was dropped). Append a warning + flip the
-        // reactor to ERROR so something visible signals "look here".
-        if (r.failed.length > 0) {
-          reactor.setState('ERROR');
-          try {
-            await tg(bot, 'sendMessage', {
-              chat_id: chatId,
-              text: `⚠️ ${r.failed.length} of ${chunks.length} message parts failed to deliver. The reply may be incomplete — please retry.`,
-              ...(threadId && { message_thread_id: threadId }),
-            }, { ...outMetaBase, source: 'partial-delivery-warning' });
-          } catch (warnErr) {
-            console.error(`[${label}] partial-delivery warning failed: ${warnErr.message}`);
-          }
-        }
+        await mediaContext.flushPartialDeliveryWarning(outMetaBase);
         await sendInlineStickers();
           await sendInlineReactions();
         await cleanupArchivedBubbles();
@@ -1739,10 +1831,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         // the rc.10 deferred-clear block, so the reactor would stay
         // stuck. Clear it (and autosteered ✍) here, after delivery —
         // but ONLY on a clean delivery. When r.failed.length>0 the
-        // ERROR state (😨) was set above as the "look here" signal
-        // for the partial-delivery failure; clearing it would wipe
-        // that signal, so leave the reactor as-is in that case.
-        if (r.failed.length === 0) {
+        // The aggregate warning sets ERROR as the "look here" signal
+        // for any text, media, or cleanup failure. Clearing it would
+        // wipe that signal, so leave the reactor as-is in that case.
+        if (!mediaContext.deliveryIncomplete) {
           reactor.clear().catch(() => {});
         }
         clearAutosteeredReactions(sessionKey).catch(() => {});
@@ -1774,7 +1866,13 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       // 0.7.0: use markdown-aware chunker + deliverReplies primitive.
       // The old chunkText was newline/byte-only; chunkMarkdownText also
       // respects code-fence boundaries (closes + reopens across chunks).
-      const chunks = chunkMarkdownText(parsed.text, TG_CHUNK_BUDGET);
+      // Short replies never went live-rich, so image markdown from a
+      // rich-enabled chat degrades to caption text here too — never a
+      // raw local path in the bubble.
+      const shortText = resolveRichTextEnabled(config, chatId, threadId)
+        ? stripMediaMarkdown(parsed.text)
+        : parsed.text;
+      const chunks = chunkMarkdownText(shortText, TG_CHUNK_BUDGET);
       await deliverReplies({
         bot,
         send: (b, method, params, m) => tg(b, method, params, m),
@@ -1787,8 +1885,10 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       });
     }
 
+    await mediaContext.flushPartialDeliveryWarning(outMetaBase);
     await sendInlineStickers();
           await sendInlineReactions();
+    await cleanupArchivedBubbles();
     // rc.10: clear progress reactions AFTER the reply has been
     // delivered so the user doesn't see a "reactions cleared, then
     // ~1-3s of nothing, then reply bubble" gap. The reply bubble
@@ -1796,7 +1896,9 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
     // with the delivery completion is the smooth UX path. Both
     // fire-and-forget — these are best-effort cleanups, not part of
     // the reply contract.
-    reactor.clear().catch(() => {});
+    if (!mediaContext.deliveryIncomplete) {
+      reactor.clear().catch(() => {});
+    }
     // 0.8.0-rc.14: also clear ✍ reactions on every follow-up
     // message that was autosteered into THIS turn — they live in
     // separate handleMessage scopes whose reactors are already GC'd.
@@ -2337,6 +2439,7 @@ async function main() {
     db = dbClient.open(DB_PATH);
     console.log(`[db] opened ${DB_PATH}`);
     tg = createSender(db, console, config);
+    richMediaFileIdCache = createMediaFileIdCache();
     richEditMessageText = createRichEditor({
       tg,
       botName: BOT_NAME,
@@ -2348,6 +2451,7 @@ async function main() {
       setRichKnownUnsupported: () => { richKnownUnsupported = true; },
       getApiRoot: () => config.bot?.apiRoot || null,
       stripUrlCreds: stripUrlCredentials,
+      sanitizeFallbackText: stripMediaMarkdown,
     });
     pairings = createPairingsStore(db.raw);
     approvals = createApprovalsStore(db.raw);