switchroom 0.16.23 → 0.16.27

package/telegram-plugin/tests/{stream-controller-html-fallback.test.ts → stream-controller-parse-fallback.test.ts}

@@ -1,78 +1,77 @@
 /**
- * Integration tests for stream-controller HTML parse-failure fallback
- * (issue #657).
+ * Integration tests for the stream-controller parse-failure fallback
+ * (issue #657, post-#2669 rich-message path).
  *
- * Contract:
- *   - When the FIRST sendMessage with parse_mode=HTML returns
- *     `400 Bad Request: can't parse entities`, the recovery is a single
- *     fresh sendMessage with parse_mode stripped — no edit (there is no
- *     message_id to edit yet). Total outbound: ONE message_id, not two.
- *   - When a subsequent editMessageText with parse_mode=HTML returns the
- *     same 400, the recovery is editMessageText AGAIN on the same
- *     message_id (with parse_mode stripped). Never sendMessage.
+ * Contract (unchanged dup-message semantics, new rich transport):
+ *   - When the FIRST `sendRichMessage({ markdown })` returns
+ *     `400 Bad Request: can't parse entities`, recovery is a single fresh
+ *     plain `sendMessage` (the raw markdown as a literal string, no parser)
+ *     — no edit (there is no message_id to edit yet). Total outbound: ONE
+ *     message_id, not two.
+ *   - When a subsequent `editMessageText({ markdown })` returns the same
+ *     400, recovery is `editMessageText` AGAIN on the same message_id with
+ *     a PLAIN string (no rich wrapper). Never a fresh send.
  *
  * The previous behaviour (the bug #657 fixes) was a duplicate plain-text
- * sendMessage on every HTML parse rejection — visible to the user as two
- * messages, one with raw `<b>` tags and one rendered correctly.
+ * sendMessage on every parse rejection — visible to the user as two
+ * messages, one raw and one rendered correctly.
  */
 
 import { describe, it, expect, vi } from 'vitest'
 import { createStreamController } from '../stream-controller.js'
 import { createFakeBotApi, errors } from './fake-bot-api.js'
 
-describe('stream-controller HTML parse-failure fallback (#657)', () => {
-  it('first send: parse-entities 400 → ONE retry without parse_mode, same outbound count', async () => {
+describe('stream-controller parse-failure fallback (#657)', () => {
+  it('first rich send: parse-entities 400 → ONE plain-text retry, same outbound count', async () => {
     const bot = createFakeBotApi({ startMessageId: 1000 })
-    // Inject a parse-entities 400 for the first sendMessage. The
-    // controller must catch it and retry with parse_mode stripped.
+    // Inject a parse-entities 400 for the first sendRichMessage. The
+    // controller must catch it and retry as a plain sendMessage.
     bot.faults.next(
-      'sendMessage',
+      'sendRichMessage',
       errors.badRequest("can't parse entities: Unsupported start tag \"frobnicate\""),
     )
 
     const stream = createStreamController({
       bot: bot as unknown as { api: ReturnType<typeof createFakeBotApi>['api'] },
       chatId: 'c1',
-      parseMode: 'HTML',
       throttleMs: 0,
     })
 
-    await stream.update('<frobnicate>hello</frobnicate>')
+    await stream.update('**broken _markdown')
     await stream.finalize()
 
     // Exactly one message landed.
     expect(bot.state.sent).toHaveLength(1)
-    // The recovery send had no parse_mode.
-    expect(bot.state.sent[0].parse_mode).toBeUndefined()
-    // The body was rendered as plain text (tags stripped).
-    expect(bot.state.sent[0].text).toContain('hello')
-    expect(bot.state.sent[0].text).not.toContain('<frobnicate>')
+    // The recovery send was a plain sendMessage, not a rich one.
+    expect(bot.state.sent[0].rich).toBeFalsy()
+    // The raw markdown body shipped verbatim as the literal fallback.
+    expect(bot.state.sent[0].text).toBe('**broken _markdown')
     // The stream's message id matches the surviving send.
     expect(stream.getMessageId()).toBe(bot.state.sent[0].message_id)
   })
 
-  it('edit on existing message: parse-entities 400 → editMessageText retry on SAME id, never sendMessage', async () => {
+  it('edit on existing message: parse-entities 400 → plain editMessageText on SAME id, never a fresh send', async () => {
     const bot = createFakeBotApi({ startMessageId: 2000 })
 
     const stream = createStreamController({
       bot: bot as unknown as { api: ReturnType<typeof createFakeBotApi>['api'] },
       chatId: 'c1',
-      parseMode: 'HTML',
       throttleMs: 0,
     })
 
-    // First update lands cleanly as a sendMessage.
-    await stream.update('<b>v1</b>')
+    // First update lands cleanly as a rich send.
+    await stream.update('**v1**')
     expect(bot.state.sent).toHaveLength(1)
+    expect(bot.state.sent[0].rich).toBe(true)
     const firstId = bot.state.sent[0].message_id
 
     // Second update: inject a parse-entities 400 on editMessageText.
     bot.faults.next(
       'editMessageText',
-      errors.badRequest("can't parse entities: Unmatched end tag at byte offset 12"),
+      errors.badRequest("can't parse entities: Can't find end of the entity"),
     )
 
-    await stream.update('<b>v2 broken</b><i>extra')
+    await stream.update('**v2 broken _extra')
     await stream.finalize()
 
     // Critical assertion: still ONE outbound message_id total — the
@@ -86,13 +85,13 @@ describe('stream-controller HTML parse-failure fallback (#657)', () => {
     for (const call of editCalls) {
       expect(call[1]).toBe(firstId) // same message_id
     }
-    // The final edit had parse_mode stripped (key absent).
+    // The final edit passed a PLAIN string (the fallback), not { markdown }.
     const finalCall = editCalls[editCalls.length - 1]
-    expect(finalCall[3].parse_mode).toBeUndefined()
-    // The stored text reflects the plain-text fallback.
+    expect(typeof finalCall[2]).toBe('string')
+    expect(finalCall[2]).toBe('**v2 broken _extra')
+    // The stored text reflects the plain-text fallback body.
     const finalText = bot.state.currentText.get(firstId)
-    expect(finalText).toBeDefined()
-    expect(finalText).not.toContain('<b>')
+    expect(finalText).toBe('**v2 broken _extra')
   })
 
   it('non-parse 400 (e.g. message-not-found) is NOT swallowed by the fallback', async () => {
@@ -101,25 +100,24 @@ describe('stream-controller HTML parse-failure fallback (#657)', () => {
     const stream = createStreamController({
       bot: bot as unknown as { api: ReturnType<typeof createFakeBotApi>['api'] },
       chatId: 'c1',
-      parseMode: 'HTML',
       throttleMs: 0,
     })
 
-    await stream.update('<b>v1</b>')
+    await stream.update('**v1**')
     const firstId = bot.state.sent[0].message_id
 
     // Inject message-not-found on the next edit. This is NOT a parse
     // error — the existing not-found recovery in draft-stream.ts should
-    // handle it (clear messageId, re-send) and our parse-fallback
-    // wrapper must let it propagate.
+    // handle it (clear messageId, re-send) and the parse-fallback wrapper
+    // must let it propagate.
     bot.faults.next('editMessageText', errors.messageToEditNotFound())
 
-    await stream.update('<b>v2</b>')
+    await stream.update('**v2**')
     await stream.finalize()
 
     // The not-found recovery path produces a fresh send — that's the
-    // pre-existing contract. We're asserting it still fires after our
-    // changes (i.e. we didn't accidentally catch this error class too).
+    // pre-existing contract. We're asserting it still fires (i.e. the
+    // parse-fallback didn't accidentally catch this error class too).
     // After: 1 original send + 1 re-send = 2 messages.
     expect(bot.state.sent.length).toBeGreaterThanOrEqual(2)
     expect(bot.state.sent[0].message_id).toBe(firstId)

package/telegram-plugin/tests/stream-controller.test.ts

@@ -2,6 +2,12 @@
  * Integration tests for `createStreamController` — the wiring layer
  * between `createDraftStream` and grammy's `bot.api`.
  *
+ * Post-#2669: the default path sends via `bot.api.sendRichMessage(chat,
+ * { markdown }, opts)` and edits via `bot.api.editMessageText(chat, id,
+ * { markdown }, opts)`. A `literalText: true` stream takes the plain
+ * `sendMessage` / plain-string `editMessageText` path instead. Both share
+ * one opts object, so a rich send is always followed by a rich edit.
+ *
  * Uses the ported openclaw-style mock bot harness (`bot-api.harness.ts`).
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
@@ -15,32 +21,32 @@ describe('createStreamController', () => {
   beforeEach(() => vi.useFakeTimers())
   afterEach(() => vi.useRealTimers())
 
-  it('first update calls bot.api.sendMessage with rendered text + options', async () => {
+  it('first update calls bot.api.sendRichMessage with raw markdown + options', async () => {
     const stream = createStreamController({
       bot,
       chatId: '123',
       threadId: 42,
-      parseMode: 'HTML',
       throttleMs: 1000,
     })
 
-    void stream.update('<b>hi</b>')
+    void stream.update('**hi**')
     await microtaskFlush()
 
-    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
     expect(bot.api.editMessageText).not.toHaveBeenCalled()
-    const [chat_id, text, opts] = bot.api.sendMessage.mock.calls[0]
+    const [chat_id, rich, opts] = bot.api.sendRichMessage.mock.calls[0]
     expect(chat_id).toBe('123')
-    expect(text).toBe('<b>hi</b>')
-    expect(opts).toMatchObject({
-      parse_mode: 'HTML',
-      message_thread_id: 42,
-      link_preview_options: { is_disabled: true },
-    })
+    // Raw GFM markdown passed straight through, unescaped, no HTML.
+    expect(rich).toEqual({ markdown: '**hi**' })
+    expect(opts).toMatchObject({ message_thread_id: 42 })
+    // sendRichMessage does NOT accept link_preview_options (stripped on the
+    // rich send path).
+    expect(opts.link_preview_options).toBeUndefined()
     expect(stream.getMessageId()).toBe(500)
   })
 
-  it('subsequent updates call editMessageText against the captured id', async () => {
+  it('subsequent updates call editMessageText({ markdown }) against the captured id', async () => {
     const stream = createStreamController({ bot, chatId: '123', throttleMs: 1000 })
 
     void stream.update('step 1')
@@ -49,15 +55,33 @@ describe('createStreamController', () => {
     void stream.update('step 1 — step 2')
     await microtaskFlush()
 
-    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
     const [chat_id, id, text] = bot.api.editMessageText.mock.calls[0]
     expect(chat_id).toBe('123')
     expect(id).toBe(500)
-    expect(text).toBe('step 1 — step 2')
+    // The edit carries the rich-message wrapper, not a plain string.
+    expect(text).toEqual({ markdown: 'step 1 — step 2' })
   })
 
-  it('finalize() flushes pending text as an edit immediately', async () => {
+  it('literalText:true takes the plain sendMessage / plain-string edit path', async () => {
+    const stream = createStreamController({ bot, chatId: '123', throttleMs: 1000, literalText: true })
+
+    void stream.update('raw < text >')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage).not.toHaveBeenCalled()
+    expect(bot.api.sendMessage.mock.calls[0][1]).toBe('raw < text >')
+
+    vi.advanceTimersByTime(1000)
+    void stream.update('raw < text > more')
+    await microtaskFlush()
+    expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
+    // Literal edits pass a plain string, not { markdown }.
+    expect(bot.api.editMessageText.mock.calls[0][2]).toBe('raw < text > more')
+  })
+
+  it('finalize() flushes pending text as a rich edit immediately', async () => {
     const stream = createStreamController({ bot, chatId: '123', throttleMs: 1000 })
 
     void stream.update('draft')
@@ -69,7 +93,7 @@ describe('createStreamController', () => {
     await stream.finalize()
 
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
-    expect(bot.api.editMessageText.mock.calls[0][2]).toBe('final')
+    expect(bot.api.editMessageText.mock.calls[0][2]).toEqual({ markdown: 'final' })
     expect(stream.isFinal()).toBe(true)
   })
 
@@ -96,18 +120,20 @@ describe('createStreamController', () => {
     expect(onEdit).toHaveBeenCalledWith(500, 11)
   })
 
-  it('omits parse_mode when not provided (plain text mode)', async () => {
-    const stream = createStreamController({ bot, chatId: '1' })
-    void stream.update('plain')
+  it('rich send strips link_preview_options but keeps message_thread_id', async () => {
+    const stream = createStreamController({ bot, chatId: '1', threadId: 9 })
+    void stream.update('hi')
     await microtaskFlush()
-    expect(bot.api.sendMessage.mock.calls[0][2]?.parse_mode).toBeUndefined()
+    const opts = bot.api.sendRichMessage.mock.calls[0][2]
+    expect(opts.link_preview_options).toBeUndefined()
+    expect(opts.message_thread_id).toBe(9)
   })
 
   it('omits message_thread_id when threadId is undefined', async () => {
     const stream = createStreamController({ bot, chatId: '1' })
     void stream.update('no thread')
     await microtaskFlush()
-    expect(bot.api.sendMessage.mock.calls[0][2]?.message_thread_id).toBeUndefined()
+    expect(bot.api.sendRichMessage.mock.calls[0][2]?.message_thread_id).toBeUndefined()
   })
 
   it('rapid updates collapse to the latest; exactly one edit lands', async () => {
@@ -115,7 +141,7 @@ describe('createStreamController', () => {
 
     void stream.update('initial')
     await microtaskFlush()
-    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
 
     void stream.update('a')
     void stream.update('b')
@@ -127,7 +153,7 @@ describe('createStreamController', () => {
     await microtaskFlush()
 
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
-    expect(bot.api.editMessageText.mock.calls[0][2]).toBe('c')
+    expect(bot.api.editMessageText.mock.calls[0][2]).toEqual({ markdown: 'c' })
   })
 
   it('treats "message is not modified" edit errors as success (swallow)', async () => {
@@ -159,7 +185,7 @@ describe('createStreamController', () => {
     expect(retry.mock.calls[0][1]).toEqual({ threadId: undefined, chat_id: '1' })
   })
 
-  it('replyMarkup is included in sendMessage opts', async () => {
+  it('replyMarkup is included in sendRichMessage opts', async () => {
     const keyboard = { inline_keyboard: [[{ text: 'Steer', callback_data: 'steer:1' }]] }
     const stream = createStreamController({
       bot, chatId: '1', throttleMs: 1000, replyMarkup: keyboard,
@@ -167,11 +193,11 @@ describe('createStreamController', () => {
     void stream.update('hello')
     await microtaskFlush()
 
-    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
-    expect(bot.api.sendMessage.mock.calls[0][2]?.reply_markup).toBe(keyboard)
+    expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage.mock.calls[0][2]?.reply_markup).toBe(keyboard)
   })
 
-  it('replyMarkup persists through editMessageText calls', async () => {
+  it('replyMarkup rides on both the rich send AND the rich edit', async () => {
     const keyboard = { inline_keyboard: [[{ text: 'Steer', callback_data: 'steer:1' }]] }
     const stream = createStreamController({
       bot, chatId: '1', throttleMs: 1000, replyMarkup: keyboard,
@@ -183,6 +209,7 @@ describe('createStreamController', () => {
     void stream.update('second')
     await microtaskFlush()
 
+    expect(bot.api.sendRichMessage.mock.calls[0][2]?.reply_markup).toBe(keyboard)
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
     expect(bot.api.editMessageText.mock.calls[0][3]?.reply_markup).toBe(keyboard)
   })
@@ -206,11 +233,11 @@ describe('createStreamController', () => {
     const stream = createStreamController({ bot, chatId: '1', throttleMs: 1000 })
     void stream.update('hello')
     await microtaskFlush()
-    expect(bot.api.sendMessage.mock.calls[0][2]?.reply_markup).toBeUndefined()
+    expect(bot.api.sendRichMessage.mock.calls[0][2]?.reply_markup).toBeUndefined()
   })
 
   it('send failure is swallowed by draft-stream loop (pinned behaviour)', async () => {
-    bot.api.sendMessage.mockImplementationOnce(async () => {
+    bot.api.sendRichMessage.mockImplementationOnce(async () => {
       throw new Error('network down')
     })
 
@@ -218,45 +245,29 @@ describe('createStreamController', () => {
     void stream.update('will fail')
     await microtaskFlush()
 
-    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
     expect(stream.getMessageId()).toBeNull()
-    // This pins the current "swallow and continue" semantics. When we
-    // harden error handling later, this test flips to expect a thrown
-    // error or a status-reaction signal — whichever we decide.
   })
 
-  it('initialMessageId — first update edits the supplied id, no sendMessage fires (#626)', async () => {
-    // The full-stack proof of the gateway-emit idempotency hook: the
-    // pin manager hands us an existing message id, the controller
-    // initializes its state to that id, and the very first update
-    // routes to bot.api.editMessageText against id 7777 — NEVER to
-    // bot.api.sendMessage. This is the invariant that makes "multiple
-    // status messages per turn" structurally impossible when the pin
-    // manager has tracked a card for the current turnKey.
+  it('initialMessageId — first update edits the supplied id via rich edit, no send fires (#626)', async () => {
     const stream = createStreamController({
       bot,
       chatId: '999',
       threadId: 7,
-      parseMode: 'HTML',
       throttleMs: 1000,
       initialMessageId: 7777,
     })
-    void stream.update('<b>edit-only</b>')
+    void stream.update('**edit-only**')
     await microtaskFlush()
+    expect(bot.api.sendRichMessage).not.toHaveBeenCalled()
     expect(bot.api.sendMessage).not.toHaveBeenCalled()
     expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
     const [chat_id, id, text, opts] = bot.api.editMessageText.mock.calls[0]
     expect(chat_id).toBe('999')
     expect(id).toBe(7777)
-    expect(text).toBe('<b>edit-only</b>')
-    expect(opts).toMatchObject({
-      parse_mode: 'HTML',
-      message_thread_id: 7,
-      link_preview_options: { is_disabled: true },
-    })
-    // The handle reports the supplied id immediately so the gateway
-    // can chain pinManager.considerPin with the right id even on the
-    // first edit.
+    expect(text).toEqual({ markdown: '**edit-only**' })
+    // The edit keeps message_thread_id but not reply_parameters/protect.
+    expect(opts).toMatchObject({ message_thread_id: 7 })
     expect(stream.getMessageId()).toBe(7777)
   })
 })

package/telegram-plugin/tests/stream-reply-error-paths.test.ts

@@ -3,30 +3,28 @@
  * fake bot API (with fault injection) and the real retry policy.
  *
  * These tests exercise the full error chain (fake GrammyError → retry
- * policy → draft-stream → caller result) end to end. Before this suite,
- * those paths existed only in production.
+ * policy → draft-stream → caller result) end to end. Post-#2669 the
+ * default path is the rich-message send (`sendRichMessage`) / rich edit
+ * (`editMessageText({ markdown })`), so faults are injected on those
+ * methods and the wire body is the raw GFM markdown (no HTML render).
  *
  * NOTE on draft-stream behaviour: the current implementation SILENTLY
  * SWALLOWS any error that isn't specifically recognised (not-modified,
- * message-to-edit-not-found). A 403, thread-not-found, or exhausted 429
- * all end up logged and dropped. The handler's "finalized without
- * sending any message" check at stream-reply-handler.ts:397 is the only
- * signal a caller gets that something went wrong. These tests document
- * that contract rather than the one a strict API would have — changing
- * it is tracked separately.
+ * message-to-edit-not-found, parse-entities). A 403, thread-not-found, or
+ * exhausted 429 all end up logged and dropped. The handler's "finalized
+ * without sending any message" check is the only signal a caller gets
+ * that something went wrong.
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { handleStreamReply, type StreamReplyDeps, type StreamReplyState } from '../stream-reply-handler.js'
 import type { DraftStreamHandle } from '../draft-stream.js'
-import { markdownToHtml as realMarkdownToHtml } from '../format.js'
 import { createRetryApiCall } from '../retry-api-call.js'
 import { createFakeBotApi, errors, type FakeBot } from './fake-bot-api.js'
 
 function makeState(): StreamReplyState {
   return {
     activeDraftStreams: new Map<string, DraftStreamHandle>(),
-    activeDraftParseModes: new Map<string, 'HTML' | 'MarkdownV2' | undefined>(),
   }
 }
 
@@ -37,13 +35,12 @@ function makeDeps(
   return {
     bot: bot as unknown as StreamReplyDeps['bot'],
     retry: createRetryApiCall(),
-    markdownToHtml: (t) => realMarkdownToHtml(t),
-    escapeMarkdownV2: (t) => t,
     repairEscapedWhitespace: (t) => t,
     assertAllowedChat: () => {},
     resolveThreadId: (_, explicit) => (explicit != null ? Number(explicit) : undefined),
     disableLinkPreview: true,
-    defaultFormat: 'html',
+    // Anything other than the literal 'text' is the rich-markdown path.
+    defaultFormat: 'markdown',
     logStreamingEvent: () => {},
     historyEnabled: false,
     recordOutbound: () => {},
@@ -55,12 +52,7 @@ function makeDeps(
 
 /**
  * Pump vi fake timers + microtasks until all pending work settles.
- * The draft-stream's `flushLoop` has setTimeout(0) schedules that need
- * explicit advancement even at throttleMs=0, plus intermediate awaits.
- *
  * vi.advanceTimersByTimeAsync isn't implemented under bun's test runner.
- * Polyfill via the sync advance + explicit microtask flush so this file
- * runs cleanly under both vitest and `bun test`.
  */
 async function advanceFakeClock(ms: number): Promise<void> {
   const viAny = vi as { advanceTimersByTimeAsync?: (ms: number) => Promise<void> }
@@ -91,8 +83,8 @@ describe('stream-reply-handler × real retry × fake bot', () => {
   })
 
   describe('flood-wait retry', () => {
-    it('retries after retry_after and the message lands', async () => {
-      bot.faults.next('sendMessage', errors.floodWait(2))
+    it('retries after retry_after and the rich message lands', async () => {
+      bot.faults.next('sendRichMessage', errors.floodWait(2, 'sendRichMessage'))
       const state = makeState()
       const deps = makeDeps(bot)
 
@@ -109,7 +101,8 @@ describe('stream-reply-handler × real retry × fake bot', () => {
       expect(result.status).toBe('finalized')
       expect(result.messageId).toBe(500)
       expect(bot.state.sent).toHaveLength(1)
-      expect(bot.api.sendMessage).toHaveBeenCalledTimes(2)
+      expect(bot.state.sent[0].rich).toBe(true)
+      expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(2)
     })
 
     it('flood-wait on editMessageText is transparent to caller', async () => {
@@ -128,16 +121,12 @@ describe('stream-reply-handler × real retry × fake bot', () => {
       const r = await pending
 
       expect(r.status).toBe('updated')
-      expect(bot.state.currentText.get(500)).toBe(realMarkdownToHtml('v2'))
+      // Raw markdown is the stored body — no HTML render.
+      expect(bot.state.currentText.get(500)).toBe('v2')
     })
   })
 
   describe('editMessageText transient failures (swallowed by retry)', () => {
-    // These tests use REAL timers because draft-stream's throttling
-    // sequence across two updates is hard to deterministically pump with
-    // fake timers (the setTimeout(0) schedule is inside a promise chain
-    // that re-enters after the first flush completes). Real timers +
-    // a tiny throttle keeps the test fast and reliable.
     beforeEach(() => vi.useRealTimers())
 
     it('retry returns undefined for "message is not modified"; stream continues', async () => {
@@ -170,17 +159,8 @@ describe('stream-reply-handler × real retry × fake bot', () => {
   })
 
   describe('non-retryable errors (current behaviour: swallowed by draft-stream)', () => {
-    // The following tests document the current swallow-all contract in
-    // draft-stream.ts. When a send fails with 403 / thread-not-found / a
-    // retry-exhausted network error, draft-stream's catch-all at line 182
-    // logs + continues. The HANDLER then sees getMessageId() == null on
-    // finalize and throws the "finalized without sending" error.
-    //
-    // If draft-stream grows a lastError hook later, these assertions
-    // should be tightened to match the real underlying error.
-
     it('403 forbidden surfaces as "finalized without sending" on done=true', async () => {
-      bot.faults.next('sendMessage', errors.forbidden())
+      bot.faults.next('sendRichMessage', errors.forbidden('sendRichMessage'))
       const state = makeState()
       const deps = makeDeps(bot)
 
@@ -190,7 +170,7 @@ describe('stream-reply-handler × real retry × fake bot', () => {
     })
 
     it('thread-not-found surfaces as "finalized without sending" on done=true', async () => {
-      bot.faults.next('sendMessage', errors.threadNotFound())
+      bot.faults.next('sendRichMessage', errors.threadNotFound('sendRichMessage'))
       const state = makeState()
       const deps = makeDeps(bot)
 
@@ -203,4 +183,29 @@ describe('stream-reply-handler × real retry × fake bot', () => {
       ).rejects.toThrowError(/finalized without sending/)
     })
   })
+
+  describe('parse-entities fallback (#657) end to end', () => {
+    it('first rich send rejected for bad markdown → retries SAME turn as plain text, one message', async () => {
+      bot.faults.next(
+        'sendRichMessage',
+        errors.badRequest("can't parse entities: bad markdown", 'sendRichMessage'),
+      )
+      const state = makeState()
+      const deps = makeDeps(bot)
+
+      const pending = handleStreamReply(
+        { chat_id: 'c', text: '**broken _markdown', done: true },
+        state,
+        deps,
+      )
+      await settle(0)
+      const result = await pending
+
+      expect(result.status).toBe('finalized')
+      // Exactly one message — the plain-text recovery send.
+      expect(bot.state.sent).toHaveLength(1)
+      expect(bot.state.sent[0].rich).toBeFalsy()
+      expect(bot.state.sent[0].text).toBe('**broken _markdown')
+    })
+  })
 })