switchroom 0.18.8 → 0.18.9

package/telegram-plugin/gateway/inbound-delivery-machine-dispatch.ts

@@ -7,17 +7,41 @@
  * (b) execute the returned effects against real I/O. This module owns
  * step (b) for the cutover.
  *
- * Scope of THIS PR — bridgeUp only:
- *   - drainBuffer                       → executed
- *   - redeliverPersistedPermVerdicts    → executed
+ * Effects wired to real executors (all effect kinds now handled):
+ *   - drainBuffer                       → redeliverBufferedInbound
+ *   - redeliverPersistedPermVerdicts    → pendingPermissionBuffer.drain → send
+ *   - deliverToBridge                   → client.send / ipcServer.sendToAgent
+ *   - bufferInbound                     → pendingInboundBuffer.push
+ *   - persistInbound                    → inboundSpool.put
+ *   - deliverPermVerdict                → client.send / ipcServer.sendToAgent
+ *   - persistPermVerdict                → pendingPermissionBuffer.push
+ *   - setTurnStarted / clearTurnStarted → onSetTurnStarted / onClearTurnStarted
+ *   - noteOutbound                      → onNoteOutbound
+ *   - firePoke                          → onFirePoke
  *   - logTrace                          → executed
  *
- * Other effects (deliverToBridge, bufferInbound, persistInbound,
- * setTurnStarted, clearTurnStarted, noteOutbound, firePoke,
- * deliverPermVerdict, persistPermVerdict) still flow through their
- * existing imperative paths in `gateway.ts`. The dispatcher logs them
- * as `not-yet-cutover` so a future PR can wire them without grep-and-
- * pray. NEVER silently no-op: the trace is the gate.
+ * Live call sites (post PR3c flip, #2794):
+ *   - bridgeUp (gateway onClientRegistered): drainBuffer /
+ *     redeliverPersistedPermVerdicts / logTrace.
+ *   - handleInbound DEFERRED_INBOUND_EMIT: the inbound-routing effects
+ *     (deliverToBridge / bufferInbound / persistInbound / setTurnStarted)
+ *     are AUTHORITATIVE when the cutover is on — the imperative twin in
+ *     gateway.ts runs only under the kill switch or the documented
+ *     carve-outs (interrupt-while-in-turn, bridge_dead). The twin is
+ *     deleted in PR4 after the 48h bake (see the "Hard removal plan"
+ *     checklist in the RFC: PR3b step 2 / PR4 remain open).
+ *   - turnEnd lifecycle effects remain shadow-only: the imperative
+ *     turn-end sites (purgeReactionTracking / releaseTurnBufferGate)
+ *     already execute the effect-equivalents with gates the machine does
+ *     not model yet (serialize-until-replied drain); PR3b step 2 tracks
+ *     that flip.
+ *
+ * The gateway-internal turn/poke effects (setTurnStarted,
+ * clearTurnStarted, noteOutbound, firePoke) map to gateway-scope state
+ * (`claudeBusyKeys`, the silence-poke ladder) that this decoupled module
+ * cannot reach directly, so they are dispatched through OPTIONAL
+ * callbacks on the ctx. When a callback is absent the effect logs an
+ * `unwired` trace rather than silently no-opping — the trace is the gate.
  *
  * Kill switch: `SWITCHROOM_DELIVERY_MACHINE_CUTOVER=0` disables
  * dispatcher execution and the gateway falls back to imperative-only.
@@ -26,10 +50,11 @@
 
 import type {
   Effect,
+  ChatKey,
   InboundMessage as MachineInboundMessage,
 } from './inbound-delivery-machine.js'
 import type { IpcServer, IpcClient } from './ipc-server.js'
-import type { InboundMessage } from './ipc-protocol.js'
+import type { InboundMessage, PermissionEvent } from './ipc-protocol.js'
 import type { PendingInboundBuffer } from './pending-inbound-buffer.js'
 import { redeliverBufferedInbound } from './pending-inbound-buffer.js'
 import type { InboundSpool } from './inbound-spool.js'
@@ -54,6 +79,26 @@ export interface DispatchCtx {
    * (clerk lost-message incident, 2026-06-03.)
    */
   readonly onUserInboundDelivered?: (merged: InboundMessage) => void
+  // ── Gateway-internal turn/poke effect callbacks ──────────────────
+  // These effects map to gateway-scope state (`claudeBusyKeys`, the
+  // silence-poke ladder) that this decoupled module cannot reach. The
+  // gateway supplies them when it flips inbound routing through the
+  // machine (PR3c). Absent → the effect logs an `unwired` trace.
+  readonly onSetTurnStarted?: (key: ChatKey, at: number) => void
+  /**
+   * Optional: observe the outcome of a `deliverToBridge` effect. The
+   * imperative twin branches on `sendToAgent`'s boolean (delivered →
+   * steer-ack + busy-mark + delivery-confirm tracking; miss → release
+   * reservation + durable-buffer + restart notice). The machine cannot
+   * model a send that fails while the bridge is nominally alive, so the
+   * PR3c live call site needs the result to run the same post-send
+   * branches the twin runs. Called once per deliverToBridge effect,
+   * after the send attempt, before `onUserInboundDelivered` enrolment.
+   */
+  readonly onDeliverResult?: (key: ChatKey, ok: boolean, msg: InboundMessage) => void
+  readonly onClearTurnStarted?: (key: ChatKey) => void
+  readonly onNoteOutbound?: (key: ChatKey, at: number) => void
+  readonly onFirePoke?: (key: ChatKey, level: 'soft' | 'firm' | 'fallback') => void
 }
 
 const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
@@ -168,20 +213,133 @@ function dispatchOne(effect: Effect, ctx: DispatchCtx): void {
       return
     }
 
-    // The cases below are KNOWN effect kinds that this PR does NOT
-    // cut over. The imperative paths still run for them; the
-    // dispatcher logs the event so future cutover PRs can grep for
-    // exactly the call sites to migrate.
-    case 'deliverToBridge':
-    case 'bufferInbound':
-    case 'persistInbound':
-    case 'setTurnStarted':
-    case 'clearTurnStarted':
-    case 'noteOutbound':
-    case 'firePoke':
-    case 'deliverPermVerdict':
+    case 'deliverToBridge': {
+      // Route a single inbound to the live bridge. The machine's
+      // InboundMessage.payload carries the real ipc-protocol
+      // InboundMessage; the machine treats it as opaque.
+      const msg = effect.msg.payload as InboundMessage
+      let ok = false
+      try {
+        if (ctx.client) {
+          ctx.client.send(msg)
+          ok = true
+        } else {
+          ok = ctx.ipcServer.sendToAgent(ctx.selfAgent, msg)
+        }
+      } catch (err) {
+        log(
+          `telegram gateway: dispatch deliverToBridge send threw agent=${ctx.selfAgent} ` +
+            `key=${effect.key}: ${(err as Error).message}\n`,
+        )
+        ok = false
+      }
+      if (ctx.onDeliverResult) {
+        try {
+          ctx.onDeliverResult(effect.key, ok, msg)
+        } catch {
+          /* observer is best-effort; never breaks delivery */
+        }
+      }
+      if (ok && ctx.onUserInboundDelivered) {
+        // Enrol in the deliver-until-acked sweep — a socket write is not
+        // proof claude consumed it (see onUserInboundDelivered doc).
+        // Pass UNCONDITIONALLY, mirroring the drainBuffer path above:
+        // the callback self-gates via shouldTrackDelivery (inbound-
+        // delivery-confirm.ts), which REJECTS sourced messages and
+        // tracks real user inbounds (meta.source undefined) — exactly
+        // the messages the sweep protects. Do NOT pre-filter on
+        // meta.source here; an inverted guard would skip user inbounds
+        // and enrol only messages the inner gate discards.
+        try {
+          ctx.onUserInboundDelivered(msg)
+        } catch {
+          /* enrolment is best-effort; never breaks delivery */
+        }
+      }
+      log(`gw-trace dispatch deliverToBridge key=${effect.key} ok=${ok}\n`)
+      return
+    }
+
+    case 'bufferInbound': {
+      const msg = effect.msg.payload as InboundMessage
+      const buffered = ctx.pendingInboundBuffer.push(ctx.selfAgent, msg)
+      log(`gw-trace dispatch bufferInbound key=${effect.key} buffered=${buffered}\n`)
+      return
+    }
+
+    case 'persistInbound': {
+      // Durable spool. `pendingInboundBuffer.push` already spools when a
+      // spool is attached to the buffer, so a persistInbound paired with
+      // a bufferInbound is idempotent (put() is idempotent by spoolId).
+      const msg = effect.msg.payload as InboundMessage
+      const put = ctx.inboundSpool ? ctx.inboundSpool.put(ctx.selfAgent, msg) : false
+      log(`gw-trace dispatch persistInbound key=${effect.key} put=${put}\n`)
+      return
+    }
+
+    case 'deliverPermVerdict': {
+      // Branch order differs from the imperative twin
+      // (gateway.ts dispatchPermissionVerdict), which always goes via
+      // `ipcServer.sendToAgent` — it runs outside any bridgeUp context,
+      // so it has no just-registered client handle. Here `ctx.client`
+      // is preferred WHEN PRESENT for the same reason as drainBuffer /
+      // redeliverPersistedPermVerdicts above: on the bridgeUp path the
+      // registry lookup may not yet observe the just-registered client,
+      // and a direct send to the connecting socket is the reliable
+      // route. PR3c's live call site for machine-driven permVerdict
+      // events (non-bridgeUp) must construct the ctx WITHOUT `client`,
+      // which makes this branch behave exactly like the twin
+      // (sendToAgent). Note the twin additionally buffers on a failed
+      // send; the machine models that as a separate persistPermVerdict
+      // effect (bridge_dead state), so no fallback push here.
+      const ev = effect.verdict.payload as PermissionEvent
+      let ok = false
+      try {
+        if (ctx.client) {
+          ctx.client.send(ev as never)
+          ok = true
+        } else {
+          ok = ctx.ipcServer.sendToAgent(ctx.selfAgent, ev as never)
+        }
+      } catch (err) {
+        log(
+          `telegram gateway: dispatch deliverPermVerdict send threw agent=${ctx.selfAgent} ` +
+            `request=${effect.verdict.requestId}: ${(err as Error).message}\n`,
+        )
+        ok = false
+      }
+      log(`gw-trace dispatch deliverPermVerdict request=${effect.verdict.requestId} ok=${ok}\n`)
+      return
+    }
+
     case 'persistPermVerdict': {
-      log(`gw-trace dispatch not-yet-cutover effect=${effect.kind}\n`)
+      const ev = effect.verdict.payload as PermissionEvent
+      const pushed = ctx.pendingPermissionBuffer.push(ctx.selfAgent, ev)
+      log(`gw-trace dispatch persistPermVerdict request=${effect.verdict.requestId} pushed=${pushed}\n`)
+      return
+    }
+
+    case 'setTurnStarted': {
+      if (ctx.onSetTurnStarted) ctx.onSetTurnStarted(effect.key, effect.at)
+      else log(`gw-trace dispatch unwired effect=setTurnStarted key=${effect.key}\n`)
+      return
+    }
+
+    case 'clearTurnStarted': {
+      if (ctx.onClearTurnStarted) ctx.onClearTurnStarted(effect.key)
+      else log(`gw-trace dispatch unwired effect=clearTurnStarted key=${effect.key}\n`)
+      return
+    }
+
+    case 'noteOutbound': {
+      if (ctx.onNoteOutbound) ctx.onNoteOutbound(effect.key, effect.at)
+      else log(`gw-trace dispatch unwired effect=noteOutbound key=${effect.key}\n`)
+      return
+    }
+
+    case 'firePoke': {
+      if (ctx.onFirePoke) ctx.onFirePoke(effect.key, effect.level)
+      else log(`gw-trace dispatch unwired effect=firePoke key=${effect.key} level=${effect.level}\n`)
       return
     }
   }

package/telegram-plugin/gateway/inbound-delivery-machine.ts

@@ -261,6 +261,14 @@ export function transition(state: State, event: Event): Transition {
       const alive = state.global.kind !== 'bridge_dead'
 
       if (!alive) {
+        // ANCHORED STRING — `inbound_bridge_dead_buffer` is load-bearing:
+        // gateway.ts's PR3c bridge-dead carve-out keys off this exact stage
+        // string to route the inbound to the imperative twin (whose
+        // shouldTrackDelivery drop semantics + restart notice are the
+        // contract the machine doesn't model). Renaming it silently reroutes
+        // that carve-out; a pin test in inbound-delivery-cutover-flip.test.ts
+        // breaks on rename. Both the string key-off and this anchor are
+        // deleted in PR4 with the twin.
         return {
           state,
           effects: [

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -0,0 +1,375 @@
+// Outbound send-path — deterministic text pipeline + chunking core (#2996).
+//
+// Phase 2 of the gateway.ts decomposition (issue #2996, plan §3B). This
+// module owns the pure, side-effect-free heart of the reply/stream/turn-flush
+// outbound pipeline: the normalize → redact → punctuation/bold → voice-scrub
+// text transform, the effective-text spacing decision, the length-limit
+// chunking, and the oversize-chunk re-split. These are exactly the transforms
+// where the recent oversize / redaction / voice-scrub regressions landed, and
+// extracting them here makes them unit-testable in isolation (see
+// outbound-send-path.test.ts golden snapshots).
+//
+// Deliberately NOT moved here (they stay in gateway.ts, delegating to this
+// module): the side-effecting send orchestration — currentTurn pinning,
+// emission-authority / over-ping decisions, activity-card finalize, voice
+// synthesis + sends, typing loops, history recording, the shared
+// `outboundDedup` singleton check/record, and the raw bot.api send loop with
+// its partial-failure contract. Those read gateway module state and are not
+// byte-identically relocatable without an invocable-executeReply harness that
+// this pure-core extraction is itself the prerequisite for.
+//
+// currentTurn coupling (#1067/#1664): this module NEVER reads the currentTurn
+// global. Every function here is pure over its arguments — turn identity is
+// pinned by the caller and never observed here.
+
+import {
+  repairEscapedWhitespace,
+  normalizeParagraphBreaks,
+  normalizePunctuation,
+  stripExcessBold,
+  addParagraphSpacers,
+  splitMarkdownChunks,
+  hardSliceToCap,
+  RICH_MESSAGE_MAX_CHARS,
+} from '../format.js'
+import { scrubVoice } from '../text-voice-scrub.js'
+import { isMessageTooLongError, isHtmlParseRejectError } from '../retry-api-call.js'
+
+/** The redactor the caller injects. In gateway this is `redactOutboundText`,
+ *  which wraps `redact()` and logs (never the secret value) when a mask fires.
+ *  Injected rather than imported so the redaction structural-wiring test
+ *  (`gateway-outbound-redact.test.ts`) keeps pinning the helper in gateway.ts,
+ *  and so this module stays free of the stderr side effect. */
+export type RedactFn = (text: string, site: string) => string
+
+export interface NormalizeOutboundResult {
+  /** The fully-normalized text. This is the value used downstream as the
+   *  dedup key, the Telegraph threshold input, and (after effective-text
+   *  spacing) the chunk source. Callers apply it exactly as the pre-#2996
+   *  inline pipeline did. */
+  text: string
+  /** Number of voice-scrub replacements applied (dashes → commas/periods,
+   *  opener strips). >0 means the voice scrub mutated the text; the caller
+   *  emits the `voice_scrub_applied` runtime metric on that condition. */
+  voiceReplaced: number
+}
+
+/**
+ * Stage 1 — the deterministic outbound text transform, byte-identical to the
+ * inline pipeline at the entry of executeReply (and mirrored on the
+ * answer-stream + turn-flush paths):
+ *
+ *   1. repairEscapedWhitespace  — undo LLM JSON-escape bungles
+ *   2. normalizeParagraphBreaks — promote lone prose breaks to GFM hard breaks
+ *   3. redact (injected)        — outbound secret scrub (#2044), BEFORE the
+ *                                 punctuation/bold normalizers so a secret with
+ *                                 an em-dash or `**` is matched literally
+ *   4. stripExcessBold∘normalizePunctuation — fleet-consistent formatting
+ *   5. scrubVoice               — em/en dash → comma/period (#1683)
+ *
+ * The order is load-bearing and MUST NOT change (each step's comment in the
+ * former inline site documents why). Pure over its arguments.
+ */
+export function normalizeOutboundBody(
+  rawText: string,
+  site: string,
+  redact: RedactFn,
+): NormalizeOutboundResult {
+  let text = normalizeParagraphBreaks(repairEscapedWhitespace(rawText))
+  text = redact(text, site)
+  text = stripExcessBold(normalizePunctuation(text))
+  let voiceReplaced = 0
+  const scrub = scrubVoice(text)
+  if (scrub.replaced > 0) {
+    text = scrub.scrubbed
+    voiceReplaced = scrub.replaced
+  }
+  return { text, voiceReplaced }
+}
+
+/**
+ * Effective-text spacing (#2669 rich-message regression fix). The rich GFM
+ * renderer collapses `\n\n` gaps tight, so prose paragraphs render jammed.
+ * Inject a visible blank-line spacer on the rich path only; the literal
+ * (`format:'text'`) path stays byte-exact. Pure.
+ */
+export function computeEffectiveText(text: string, literalText: boolean): string {
+  return literalText ? text : addParagraphSpacers(text)
+}
+
+/**
+ * Length-limit chunking. The literal path uses the newline/length `chunk()`
+ * splitter; the rich path uses `splitMarkdownChunks` (markdown-boundary-aware).
+ * Pure. `chunk` is passed in so the splitter (moved here as `chunkText`) and
+ * this decision stay colocated without a circular gateway import.
+ */
+export function computeReplyChunks(args: {
+  effectiveText: string
+  literalText: boolean
+  limit: number
+  chunkMode: 'length' | 'newline'
+}): string[] {
+  const { effectiveText, literalText, limit, chunkMode } = args
+  return literalText
+    ? chunkText(effectiveText, limit, chunkMode)
+    : splitMarkdownChunks(effectiveText, limit)
+}
+
+/**
+ * Oversize-chunk re-split (length-error recovery). A single pre-computed chunk
+ * can still exceed the wire cap when `splitMarkdownChunks` hit an indivisible
+ * region and emitted it whole (a giant fenced block, a no-boundary blob).
+ * Re-split at the hard `RICH_MESSAGE_MAX_CHARS` cap; for a truly indivisible
+ * block, fall back to a hard character cut so each delivered piece stays under
+ * the wire cap. Byte-identical to the inline `sendChunkResplit` piece
+ * computation. Pure.
+ */
+export function resplitOversizeChunk(piece: string): string[] {
+  const subPieces = splitMarkdownChunks(piece, RICH_MESSAGE_MAX_CHARS)
+  return subPieces.length > 1 ? subPieces : hardSliceToCap(piece, RICH_MESSAGE_MAX_CHARS)
+}
+
+/**
+ * Length/newline text splitter (relocated verbatim from gateway.ts). Splits
+ * `text` into <= `limit`-char pieces. In `newline` mode it prefers a paragraph
+ * break, then a line break, then a space past the halfway point; `length` mode
+ * cuts hard at the limit. Pure.
+ */
+export function chunkText(text: string, limit: number, mode: 'length' | 'newline'): string[] {
+  if (text.length <= limit) return [text]
+  const out: string[] = []
+  let rest = text
+  while (rest.length > limit) {
+    let cut = limit
+    if (mode === 'newline') {
+      const para = rest.lastIndexOf('\n\n', limit)
+      const line = rest.lastIndexOf('\n', limit)
+      const space = rest.lastIndexOf(' ', limit)
+      cut = para > limit / 2 ? para : line > limit / 2 ? line : space > 0 ? space : limit
+    }
+    out.push(rest.slice(0, cut))
+    rest = rest.slice(cut).replace(/^\n+/, '')
+  }
+  if (rest) out.push(rest)
+  return out
+}
+
+// ─── Send orchestration (#2996 step 1) ────────────────────────────────────
+//
+// The reply chunk-send loop, relocated VERBATIM from executeReply so it can be
+// driven from a unit test against a fake bot API (see
+// outbound-send-path.test.ts). This is the highest-bug-density mechanic of the
+// send path — the recent oversize / wire-cap / parse-reject / THREAD_NOT_FOUND
+// fallback fixes all landed HERE — and it was previously reachable only through
+// the non-importable gateway monolith (gateway.ts runs boot logic + Bun.listen
+// at import, so `executeReply` cannot be invoked from vitest/bun in-place).
+//
+// The module stays bot-agnostic: every Telegram send is an INJECTED function
+// dep, so the raw `bot.api.*` calls (and their retry wrapping + allow-raw-bot-api
+// markers) remain in gateway.ts, and a test passes fakes. The caller keeps
+// building the per-chunk send/edit option objects (so the option shape stays
+// byte-identical to the inline site and the deps surface stays small — 8), pins
+// the turn, owns dedup/voice/history, and threads the shared `sentIds` array by
+// reference. currentTurn is NEVER read here (#1067/#1664).
+
+/** Injected Telegram send surface + logging for {@link sendReplyChunks}. In
+ *  gateway these are thin adapters over `lockedBot.api.*` (retry-wrapped where
+ *  the inline site wrapped them); in tests they are fakes recording call shape. */
+export interface ReplyChunkSendDeps {
+  /** robustApiCall-wrapped rich send. Adapter: `sendRichMessage(richMessage(s))`.
+   *  `threadId` (the live value) is passed into the robustApiCall meta so a
+   *  thread-not-found 400 is converted to THREAD_NOT_FOUND, exactly as inline. */
+  sendRich: (opts: Record<string, unknown>, richBody: unknown, threadId: number | undefined) => Promise<{ message_id: number }>
+  /** robustApiCall-wrapped literal send. Adapter: `sendMessage(chunk)`. */
+  sendLiteral: (opts: Record<string, unknown>, text: string, threadId: number | undefined) => Promise<{ message_id: number }>
+  /** UNwrapped literal send (last-resort fallbacks that must NOT re-enter the
+   *  retry policy that just rejected the payload). Adapter: raw `sendMessage`. */
+  sendLiteralRaw: (opts: Record<string, unknown>, text: string) => Promise<{ message_id: number }>
+  /** UNwrapped rich send (length-error re-split last resort). Adapter: raw
+   *  `sendRichMessage(richMessage(piece))`. */
+  sendRichRaw: (opts: Record<string, unknown>, richBody: unknown) => Promise<{ message_id: number }>
+  /** robustApiCall-wrapped preview edit-in-place. */
+  editPreview: (messageId: number, body: unknown, opts: Record<string, unknown>, threadId: number | undefined) => Promise<unknown>
+  /** rich-markdown wrapper (`richMessage`). Applied to a chunk/piece string. */
+  richMessage: (s: string) => unknown
+  /** outbound logger (`logOutbound`). */
+  logOutbound: (path: 'reply', chatId: string, messageId: number, chars: number, extra?: string) => void
+  /** delete a stale preview message (`deleteStalePreview`). */
+  deleteStalePreview: (id: number) => Promise<void>
+  /** stderr sink (`process.stderr.write`). */
+  stderr: (s: string) => void
+}
+
+/** Mutable send state + per-chunk option builders for {@link sendReplyChunks}.
+ *  The caller owns option shape (byte-identical to the inline site). */
+export interface ReplyChunkSendState {
+  chatId: string
+  chunks: string[]
+  literalText: boolean
+  /** voice-only mode with a full synthesis skips the text body entirely. */
+  suppressText: boolean
+  /** current thread id; re-split/fallbacks may drop it (THREAD_NOT_FOUND). */
+  threadId: number | undefined
+  /** a stale draft-stream preview to edit-in-place on the first chunk, or null. */
+  previewMessageId: number | null
+  /** shared results array — appended in place (voice/file sends push too). */
+  sentIds: number[]
+  /** build the send-options object for chunk `i` (last-chunk flag + live thread). */
+  buildSendOpts: (i: number, isLastChunk: boolean, threadId: number | undefined) => Record<string, unknown>
+  /** build the preview edit-in-place options for the first chunk. */
+  buildPreviewEditOpts: (isLastChunk: boolean) => Record<string, unknown>
+}
+
+export interface ReplyChunkSendResult {
+  /** thread id after any THREAD_NOT_FOUND fallback (used by later file sends). */
+  threadId: number | undefined
+  /** preview id after consumption (null once edited/deleted). */
+  previewMessageId: number | null
+}
+
+/**
+ * Send the pre-computed reply chunks. Relocated verbatim from executeReply's
+ * chunk loop. Appends message ids to `state.sentIds` in order. On an
+ * unrecoverable send error it throws the raw error — the caller wraps it into
+ * the `reply failed after N of M chunk(s) sent` partial-failure contract and
+ * runs the typing-loop `finally`, exactly as before.
+ */
+export async function sendReplyChunks(
+  deps: ReplyChunkSendDeps,
+  state: ReplyChunkSendState,
+): Promise<ReplyChunkSendResult> {
+  const { chatId, chunks, literalText, suppressText, sentIds } = state
+  let threadId = state.threadId
+  let previewMessageId = state.previewMessageId
+
+  for (let i = 0; i < chunks.length; i++) {
+    // PR-C2: voice-only mode with a successful synthesis suppresses the
+    // text body — the spoken voice note IS the reply. Bail before the
+    // first chunk send (sentIds stays empty for text); the voice send
+    // below lands the answer. Any other mode (voice+text, or voice-only
+    // that fell back) sends the text chunks as normal.
+    if (suppressText) break
+    const isLastChunk = i === chunks.length - 1
+    const sendOpts = state.buildSendOpts(i, isLastChunk, threadId)
+
+    if (i === 0 && previewMessageId != null) {
+      const editOpts = state.buildPreviewEditOpts(isLastChunk)
+      try {
+        await deps.editPreview(previewMessageId!, literalText ? chunks[i] : deps.richMessage(chunks[i]), editOpts, threadId)
+        sentIds.push(previewMessageId!)
+        previewMessageId = null
+        continue
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        if (/not modified/i.test(msg)) {
+          sentIds.push(previewMessageId!)
+          previewMessageId = null
+          continue
+        }
+        deps.stderr(`telegram gateway: preview edit-in-place failed (${msg}), sending fresh\n`)
+        await deps.deleteStalePreview(previewMessageId!)
+        previewMessageId = null
+      }
+    }
+
+    // Last-resort: resend this chunk as plain text (no rich wrapper, so
+    // the markdown parser never runs). Keeps thread / reply / markup
+    // params; only the formatting is sacrificed. Used when Telegram
+    // rejects our markdown — better an unformatted answer than a
+    // vanished one. The raw markdown source is itself readable prose, so
+    // we send it verbatim rather than strip anything.
+    const sendChunkPlainText = async (opts: Record<string, unknown>): Promise<void> => {
+      const plain =
+        chunks[i].length > 0
+          ? chunks[i]
+          : '⚠️ (a fragment could not be rendered for Telegram)'
+      const sent = await deps.sendLiteralRaw(opts, plain)
+      sentIds.push(sent.message_id)
+      deps.logOutbound('reply', chatId, sent.message_id, plain.length, `chunk=${i + 1}/${chunks.length} plaintext-fallback`)
+      deps.stderr(
+        `telegram gateway: markdown parse-reject — resent chunk ${i + 1}/${chunks.length} as plain text\n`,
+      )
+    }
+
+    // Literal `format:'text'` sends bypass the rich parser entirely
+    // (plain sendMessage, no markdown). The default path ships rich
+    // markdown via sendRichMessage. Both resolve to a Message with a
+    // message_id, which is all the caller reads.
+    //
+    // `wrapped` selects the retry-wrapped adapter (first attempt) vs the
+    // UNwrapped adapter (THREAD_NOT_FOUND retry). The inline site wrapped only
+    // the first attempt in robustApiCall; the retry called the raw send
+    // deliberately, so re-attempting after a dropped thread never re-enters the
+    // retry policy. Preserving that split keeps behavior byte-identical.
+    const sendChunk = (opts: Record<string, unknown>, wrapped: boolean): Promise<{ message_id: number }> => {
+      if (literalText) {
+        return wrapped ? deps.sendLiteral(opts, chunks[i], threadId) : deps.sendLiteralRaw(opts, chunks[i])
+      }
+      // sendRichMessage does NOT accept link_preview_options (rich messages
+      // control previews via entity detection) — drop it for the rich path.
+      const richOpts = { ...opts }
+      delete (richOpts as { link_preview_options?: unknown }).link_preview_options
+      const richBody = deps.richMessage(chunks[i])
+      return wrapped ? deps.sendRich(richOpts, richBody, threadId) : deps.sendRichRaw(richOpts, richBody)
+    }
+
+    // Length-error recovery: a single pre-computed chunk can still exceed the
+    // wire cap when splitMarkdownChunks hit an indivisible region and emitted
+    // it whole (a giant fenced block, a no-boundary blob). Telegram answers
+    // with RICH_MESSAGE_TEXT_TOO_LONG / MESSAGE_TOO_LONG. Re-split this chunk
+    // at a harder boundary and send each piece, rather than misclassifying it
+    // as a parse-reject (which would resend the same oversized payload as
+    // plain text) or surfacing the raw 400.
+    const sendChunkResplit = async (opts: Record<string, unknown>): Promise<void> => {
+      // Re-split at the same cap; for a truly indivisible block this still
+      // yields one oversized piece, but a hard character-cut on the rendered
+      // markdown at least keeps each delivered piece under the wire cap.
+      const pieces = resplitOversizeChunk(chunks[i])
+      for (let p = 0; p < pieces.length; p++) {
+        let sent: { message_id: number }
+        if (literalText) {
+          sent = await deps.sendLiteralRaw(opts, pieces[p])
+        } else {
+          const ro = { ...opts }
+          delete (ro as { link_preview_options?: unknown }).link_preview_options
+          sent = await deps.sendRichRaw(ro, deps.richMessage(pieces[p]))
+        }
+        sentIds.push(sent.message_id)
+        deps.logOutbound('reply', chatId, sent.message_id, pieces[p].length, `chunk=${i + 1}/${chunks.length} resplit=${p + 1}/${pieces.length}`)
+      }
+      deps.stderr(
+        `telegram gateway: rich body too long — re-split chunk ${i + 1}/${chunks.length} into ${pieces.length} piece(s)\n`,
+      )
+    }
+
+    try {
+      const sent = await sendChunk(sendOpts, true)
+      sentIds.push(sent.message_id)
+      deps.logOutbound('reply', chatId, sent.message_id, chunks[i].length, `chunk=${i + 1}/${chunks.length}`)
+    } catch (err) {
+      if (err instanceof Error && err.message === 'THREAD_NOT_FOUND') {
+        threadId = undefined
+        const retryOpts = { ...sendOpts }
+        delete (retryOpts as Record<string, unknown>).message_thread_id
+        try {
+          const sent = await sendChunk(retryOpts, false)
+          sentIds.push(sent.message_id)
+        } catch (retryErr) {
+          // Thread dropped, AND another failure: length → re-split,
+          // parse-reject → plain text, else propagate.
+          if (isMessageTooLongError(retryErr)) await sendChunkResplit(retryOpts)
+          else if (isHtmlParseRejectError(retryErr)) await sendChunkPlainText(retryOpts)
+          else throw retryErr
+        }
+      } else if (isMessageTooLongError(err)) {
+        await sendChunkResplit(sendOpts)
+      } else if (isHtmlParseRejectError(err)) {
+        await sendChunkPlainText(sendOpts)
+      } else {
+        throw err
+      }
+    }
+  }
+
+  return { threadId, previewMessageId }
+}