switchroom 0.5.0

package/telegram-plugin/docs/waiting-ux-spec.md

@@ -0,0 +1,233 @@
+# Waiting-for-reply UX — v2 spec (three-class contract)
+
+Tracks: [#545](https://github.com/mekenthompson/switchroom/issues/545),
+[#553](https://github.com/mekenthompson/switchroom/issues/553) (PR series)
+
+This document codifies the user-perceived contract for what happens
+between "I sent a Telegram message" and "the agent's reply is locked
+in." The contract varies by **turn class**. The v2 rewrite (#553)
+sharpens the gates: tools alone never trigger the progress card,
+placeholder text is removed entirely, and sub-agents (= background
+workers) are the single concept for parallel work.
+
+## Three turn classes
+
+### Class A — Instant (<2s, NO tools)
+
+| Surface           | Contract                                                               |
+| ----------------- | ---------------------------------------------------------------------- |
+| Status reaction   | 👀 within 800ms of inbound. Terminates with 👍.                        |
+| Progress card     | **Never rendered.** Suppressed regardless of `initialDelayMs`.         |
+| Placeholder text  | **Never sent.** No `🔵 thinking` / `📚 recalling memories` / `💭 thinking`. |
+| Answer text       | First answer-text edit lands within **1500ms** of inbound (Class A budget; pinned in #553 PR 3). |
+| Ladder            | 👀 → 👍. Optional 🤔 if the controller debounce window is crossed.    |
+
+User experience: feels like a chat partner typing back instantly.
+
+### Class B — Short (2–60s, tools, NO sub-agents)
+
+| Surface           | Contract                                                               |
+| ----------------- | ---------------------------------------------------------------------- |
+| Status reaction   | 👀 within 800ms. Ladder progresses through 🤔 / tool-glyphs (🔥/✍/👨‍💻/⚡) before 👍. **Must NOT collapse straight to 👍.** |
+| Progress card     | **Never rendered.** The card gate is `(elapsed >= 60s) OR (sub-agent appeared)` — tools alone do NOT trigger it. |
+| Placeholder text  | **Never sent.**                                                        |
+| Answer text       | First answer-text edit lands within **3000ms** of inbound (Class B/C budget; pinned in #553 PR 3). Streams progressively as the model produces tokens. |
+| Final             | 👍 + locked stream answer.                                             |
+
+User experience: live ladder of tool reactions, answer text starts
+streaming as soon as the model resumes, no fake "thinking" spacers.
+
+### Class C — Long-running (>60s OR sub-agents/background workers)
+
+| Surface           | Contract                                                               |
+| ----------------- | ---------------------------------------------------------------------- |
+| Status reaction   | 👀 within 800ms. Ladder throughout. Settles to 👍 only after full quiescence (all sub-agents terminal). |
+| Progress card     | Renders the moment the gate trips: `(elapsed >= 60s) OR (any sub-agent has appeared)`. Stays pinned-feel and stable. |
+| Card "Done" stamp | **≥ last sub-agent terminal timestamp.** Card never marks Done while a sub-agent is still in flight. |
+| Sub-agent header  | Header count == rendered-list-length. **No drift between summary and bullets.** |
+| Placeholder text  | **Never sent.**                                                        |
+
+A "background worker" ≡ a sub-agent dispatched with
+`Agent({ run_in_background: true })`. There is no separate concept —
+the card gate, the bullet list, and the quiescence check all key on
+the sub-agent stream.
+
+## Key invariants (v2)
+
+1. **No placeholder strings** — `🔵 thinking`, `📚 recalling memories`,
+   and `💭 thinking` must never appear in any `sendMessage` /
+   `editMessageText` payload at any point in any turn class. PR 5
+   removes the production code that emits them.
+2. **Card gate** — `(elapsed >= 60s) OR (any sub-agent has appeared)`.
+   Tool-use count, tool category, and parent narrative content are
+   NOT inputs to the gate.
+3. **First-answer-text deadline** — Class A: <1500ms. Class B/C:
+   <3000ms (committed in #553 PR 3). Budget: 500ms inbound coalesce +
+   ~1s minInitialChars-driven first send + ~1.5s model TTFT for short
+   replies.
+4. **Sub-agent header == list length** — every render of the card.
+
+## PR 1 — foundation: spec + harness extensions (this PR)
+
+PR 1 ships:
+
+- This rewritten spec — supersedes the v1 four-failure-mode framing.
+- Three new helpers on `tests/real-gateway-harness.ts`:
+  - `expectNoPlaceholderEdits(chatId)` — returns recorded calls whose
+    payload matches a banned placeholder string. Tests assert
+    `toEqual([])`.
+  - `expectNoCardSent(chatId)` — wraps `progressCardSendMs` for
+    assertion-friendly use (`.toBeNull()`).
+  - `firstAnswerTextMs(chatId)` — first `sendMessage` /
+    `editMessageText` whose payload is neither a card payload nor a
+    placeholder string.
+- A new RED test file `tests/real-gateway-spec.test.ts` (all
+  `describe.skip`'d) pinning the three-class contract:
+  - Class A — 5 tests
+  - Class B — 4 tests
+  - Class C — 5 tests
+  Each carries a `// TODO(#553-PR-N)` marker for which subsequent PR
+  un-skips it.
+
+PR 1 does NOT change production code. The existing F1/F2/F3/F4
+regression tests stay green; the new spec tests are skipped, so they
+do not gate CI yet.
+
+## PR 2–5 — implementation roadmap
+
+| PR  | Scope                                                                | Un-skips                                            | Status   |
+| --- | -------------------------------------------------------------------- | --------------------------------------------------- | -------- |
+| 2   | Kill instant-draft placeholder; preserve early-ack 👀                | Class A no-placeholder, Class B no-placeholder      | shipped  |
+| 3   | First-answer-text deadline implementation; tighten <Ns numbers       | Class A/B/C answer-text-deadline assertions         | shipped  |
+| 4   | Card-gate rewrite to `(>=60s) OR (sub-agent appeared)`               | Class B no-card; Class C card-gate tests            | shipped  |
+| 5   | Remove `🔵 thinking` / `📚 recalling memories` / `💭 thinking` strings; sub-agent header = list length | Remaining no-placeholder + sub-agent count tests    | shipped  |
+
+**PR 4 status:** shipped the card-gate rewrite. Defaults change
+from `initialDelayMs=30_000, promoteAfterMs=5_000, promoteOnParentToolCount=3`
+to `initialDelayMs=60_000, promoteAfterMs=0 (disabled), promoteOnParentToolCount=0
+(disabled)`. The Class B "no card rendered" and Class C "card renders on
+sub-agent" / "card renders after 60s" tests are un-skipped. F3's late-card
+symptom (long single-tool turn shows no card) is now intentional spec
+behaviour rather than a bug — see `real-gateway-f3-late-card.test.ts`
+header for the reframe.
+
+**PR 5 status (this PR):** ships the placeholder-text removal. The
+pre-allocated draft path, the `update_placeholder` IPC handler, the
+placeholder heartbeat (`placeholder-heartbeat.ts`), the phase enrichment
+(`placeholder-phase.ts`), the `forum-topic-placeholder.ts` substitute,
+and all associated state in `gateway.ts` are deleted. recall.py's
+`update_placeholder` IPC calls now no-op cleanly because the gateway
+no longer registers an `onUpdatePlaceholder` handler — the IPC client
+emits a fire-and-forget JSON line, and the gateway dispatch silently
+ignores the unknown message type. Hindsight (`vendor/hindsight-memory/`)
+is untouched. The Class A/B/C no-placeholder assertions and the Class C
+sub-agent-header-equals-list-length assertion are un-skipped.
+
+## IPC + bridge lifecycle invariants
+
+Pinned by `tests/real-gateway-ipc-lifecycle.test.ts`. These five
+invariants codify behaviors that the user-perceived waiting-UX spec
+above implicitly relies on but which live one layer down — at the
+IPC server / bridge connect-disconnect boundary. Multiple production
+bugs in 2026-05 traced back to the absence of test coverage at this
+layer; this section is the canonical write-up of what the gateway
+must guarantee.
+
+- **I1 — Anonymous IPC client lifecycle is observably invisible.**
+  A client that connects but never registers an agent (e.g. recall.py
+  sending a one-shot legacy IPC message) MUST NOT mutate any active
+  status reactions, MUST NOT dispose the progress driver, and MUST
+  NOT close any draft streams. The disconnect path of an unregistered
+  client is a no-op on user-visible state. (Bug A — premature 👍 on
+  recall.py disconnect, fixed in PR #600.)
+
+- **I2 — Per-agent disconnect isolation.** When agent X's bridge
+  disconnects, only X's status reactions get flushed to `setDone()`.
+  Agent Y's active reactions stay untouched. Switchroom is single-
+  agent-per-gateway today, but the invariant pins the right
+  semantics so multi-agent gateways cannot regress silently.
+
+- **I3 — 👍 fires AFTER real delivery, not after JSONL `turn_end`.**
+  For any reply tool path (`reply`, `stream_reply done=true`), the
+  controller's `setDone()` MUST happen at-or-after the timestamp of
+  the final outbound to Telegram for that reply. Firing on the
+  JSONL `turn_end` event before the round-trip completes produces a
+  visible flash of 👍 with no reply text. (Bug D + Bug Z.)
+
+- **I4 — Legacy IPC types are tolerated, not lethal.** Any message
+  type the gateway no longer handles (e.g. `update_placeholder`
+  after #553 PR 5) MUST be soft-accepted: the validator returns
+  false, `processBuffer` logs and continues, the connection stays
+  open, and no active state is mutated. (Bug B — gateway crash on
+  recall.py's `update_placeholder` after PR 5; fixed in PR #600.)
+
+- **I5 — Wake-audit dedup.** The `.wake-audit-pending` sentinel and
+  audit cycle MUST NOT re-fire mid-conversation under `--continue`
+  respawn. (Bug C — duplicate greeting reply on respawn. The actual
+  fix lives in profiles, not in the gateway, but the regression
+  surface is observable here as "duplicate outbound for the same
+  logical turn" and so the test invariant lives in this file.)
+
+The test file documents which invariants currently have green tests,
+which depend on in-flight PRs to land first, and which are `.skip`'d
+pending the matching fix branch. See the file header for the
+bug-to-PR map.
+
+## Failure-mode history (F1–F4, fixed in earlier #553 PRs)
+
+The v1 spec framed the rewrite around four observed regressions from
+the 2026-04-30 live demo. They are all fixed; the regression tests
+(`tests/real-gateway-f1-ladder-integrity.test.ts`,
+`real-gateway-f2-instant-draft.test.ts`, `real-gateway-f3-late-card.test.ts`,
+`real-gateway-f4-interim-text.test.ts`) stay in place to keep the gaps closed.
+
+| ID  | Symptom                                                                    | Class | Status                                            |
+| --- | -------------------------------------------------------------------------- | ----- | ------------------------------------------------- |
+| F1  | Ladder collapses straight to 👍 (skips 👀 → 🤔 → 🔥)                       | B     | Fixed — `StatusReactionController.finishWithState` flushes pending pre-terminal emoji. |
+| F2  | No instant draft / typing signal — chat sits silent "for ages"             | All   | Fixed — `handleInboundCoalesced` fires 👀 directly on raw arrival before the coalesce buffer. |
+| F3  | Progress card renders late (after turn_end, or never on long turns)        | C     | Fixed under v1 rules with a 5s time-promote in the driver; **superseded by PR 4**, which replaces the gate with `(>=60s) OR (sub-agent)`. |
+| F4  | Pre-tool preamble static — one preamble then silence                       | B     | Regression-guarded only; not reproducible deterministically. The v2 contract sidesteps F4 by tightening the first-answer-text deadline (Class B/C, PR 3). |
+
+The F1/F2/F3/F4 tests remain green throughout the v2 rewrite — they
+encode tighter invariants than the v2 spec relaxes. PR 4's gate
+change does not regress F3 (the F3 long-single-tool case crosses the
+60s threshold).
+
+## Test methodology
+
+- **Time control**: `vi.useFakeTimers()` + `vi.setSystemTime` for
+  deterministic wall-clock assertions. The harness records every
+  outbound `bot.api` call with `Date.now()` at invocation, so all
+  deadlines are reproducibly measurable.
+- **Recorder** (existing): `firstReactionMs`, `progressCardSendMs`,
+  `reactionSequence`, `lastReactionEmoji`, `edits`, `sentTexts`.
+- **Recorder** (PR 1 additions): `expectNoPlaceholderEdits`,
+  `expectNoCardSent`, `firstAnswerTextMs`.
+- **Production wiring**: the harness uses the actual
+  `StatusReactionController`, `createProgressDriver`, and
+  `createInboundCoalescer` from production — not mocks. The bot.api
+  layer below is a recording fake.
+- **Out of scope**: foreman queue, IPC bridge, auth, history. Those
+  do not influence the user-perceived waiting UX.
+
+## CI gate
+
+The harness runs as part of the root vitest suite via `npm test` →
+`vitest run`. PR 1's spec tests are `describe.skip`'d and do not
+fail CI; PRs 2–5 un-skip them as the production code lands.
+
+## Phase 1 / Phase 3 history (legacy)
+
+For posterity:
+
+- **Phase 1** (#547): `tests/waiting-ux.e2e.test.ts` — controller +
+  driver in isolation, hand-written `feedSessionEvent` adapter. F2
+  passed trivially because the harness called `setQueued()`
+  synchronously inside `inbound()`.
+- **Phase 3** (#553 PR 1, original): `tests/real-gateway-harness.ts`
+  composed the production `InboundCoalescer` before the Phase 1
+  controller stack, exposing the real F2 gap (👀 only fired after
+  the coalesce window). F2's fix landed against this harness.
+- **v2 rewrite** (this PR series, also numbered #553): same Phase 3
+  harness, plus three v2 helpers; new spec test file pins the
+  three-class contract.

package/telegram-plugin/draft-stream.ts

@@ -0,0 +1,442 @@
+/**
+ * Edit-in-place streaming for Telegram messages.
+ *
+ * Ports the throttle/flush pattern from openclaw's
+ * src/channels/draft-stream-loop.ts. The loop holds a single `pendingText`
+ * snapshot (NOT a queue — only the latest matters) plus a single in-flight
+ * promise. update(text) either fires immediately if the throttle window
+ * is open, or schedules a setTimeout for the remaining ms. When the
+ * in-flight call resolves, if pendingText changed during flight it loops
+ * once more without waiting.
+ *
+ * This is what makes the experience feel responsive without burning
+ * Telegram's 1-edit-per-second-per-message rate limit. The latest delta
+ * always lands within ~1s, with at most one outstanding API call.
+ *
+ * In our model-driven architecture (no inference hooks), the controller
+ * is driven by the model calling stream_reply(text, done) multiple times
+ * during a long task. First call → sendMessage (or sendMessageDraft in DMs).
+ * Subsequent calls → throttled editMessageText (or sendMessageDraft). done=true
+ * → flush, materialize as a fresh sendMessage (push notification), clear draft.
+ *
+ * Transport selection:
+ *   - previewTransport: "auto" (default) — use draft in DMs only
+ *   - previewTransport: "draft"           — always use draft (if API available)
+ *   - previewTransport: "message"         — always use sendMessage/editMessageText
+ *
+ * Forum topics (message_thread_id set) force message transport because
+ * sendMessageDraft does not support threads. The caller (stream-controller.ts)
+ * handles this by passing previewTransport: "message" for threaded chats.
+ */
+
+import {
+  shouldFallbackFromDraftTransport,
+  allocateDraftId,
+} from './draft-transport.js'
+
+const TELEGRAM_MAX_CHARS = 4096
+const DEFAULT_THROTTLE_MS = 1000
+const MIN_THROTTLE_MS = 250
+
+/**
+ * Send the first message in a stream. Receives the rendered text plus a
+ * thread_id (forum topic) and returns the new Telegram message_id.
+ */
+export type StreamSendFn = (text: string) => Promise<number>
+
+/**
+ * Edit an existing stream message. Receives the message_id and rendered text.
+ */
+export type StreamEditFn = (messageId: number, text: string) => Promise<void>
+
+/**
+ * Optional sendMessageDraft callback. When present and the transport is
+ * "draft", this is called instead of sendMessage/editMessageText.
+ * Signature mirrors Telegram's sendMessageDraft Bot API method.
+ */
+export type StreamDraftFn = (
+  chatId: string,
+  draftId: number,
+  text: string,
+  params?: { message_thread_id?: number },
+) => Promise<unknown>
+
+export interface DraftStreamConfig {
+  /** Throttle window in ms. Floored at 250. Default 1000. */
+  throttleMs?: number
+  /**
+   * Maximum total characters before hard-stopping the stream. Default 4096
+   * (Telegram's limit). When exceeded, future updates are ignored — the
+   * caller should fall back to a fresh sendMessage.
+   */
+  maxChars?: number
+  /**
+   * Optional debounce window applied BEFORE the first send of a stream.
+   * When > 0, the first update() defers the send by idleMs, restarting
+   * the timer on each additional update that arrives during the window.
+   * Useful when the caller bursts several update() calls at turn start
+   * and you'd rather collapse them into a single send than pay the
+   * latency of an immediate first-fire + follow-up edit.
+   *
+   * Default 0 (no pre-send debounce — first update fires immediately).
+   * Only affects the first send; subsequent edits use throttleMs.
+   *
+   * NOTE: This debounce only applies to message transport. Draft transport
+   * fires immediately on the first update because drafts are ephemeral —
+   * the throttle/flush loop already collapses bursts into 1 API call/sec
+   * via throttleMs.
+   */
+  idleMs?: number
+  /**
+   * Transport selector.
+   * - "auto" (default): use draft transport when isPrivateChat=true AND
+   *   sendMessageDraft is provided; otherwise use message transport.
+   * - "draft": always prefer draft (falls back to message if sendMessageDraft absent).
+   * - "message": always use sendMessage/editMessageText.
+   */
+  previewTransport?: 'auto' | 'message' | 'draft'
+  /**
+   * True if the current chat is a private DM. Used by "auto" transport to
+   * decide whether to activate draft. Has no effect when previewTransport
+   * is "draft" or "message".
+   */
+  isPrivateChat?: boolean
+  /**
+   * sendMessageDraft callback. When absent, the stream falls back to
+   * sendMessage/editMessageText regardless of previewTransport.
+   */
+  sendMessageDraft?: StreamDraftFn
+  /**
+   * The Telegram chat id string — required when sendMessageDraft is provided,
+   * so the draft can be cleared on finalize.
+   */
+  chatId?: string
+  /** Optional logger for debugging. Receives one string per event. */
+  log?: (msg: string) => void
+  /** Optional warning logger. Used for transport fallback notices. */
+  warn?: (msg: string) => void
+  /**
+   * If set, the stream is initialized as if a previous send had landed
+   * with this `message_id` — the FIRST update() call invokes `edit`
+   * against this id rather than `send`. Used by callers (notably the
+   * gateway's progress-card emit) that know the anchor message id from
+   * an external source (e.g. the pin manager) and want to guarantee a
+   * subsequent emit edits in place rather than creating a fresh
+   * sendMessage. This closes the "done=true → activeDraftStreams entry
+   * deleted → next emit creates fresh sendMessage" duplicate-message
+   * class (issue #626). The not-found fallback at the edit site
+   * (line ~280: re-send on `MESSAGE_ID_INVALID`) gracefully handles a
+   * stale id — the bad edit fails once, then a fresh send fires.
+   */
+  initialMessageId?: number | null
+}
+
+export interface DraftStreamHandle {
+  /**
+   * Push a new full-text snapshot. The loop holds only the latest. Returns
+   * a promise that resolves once this update has either (a) been sent or
+   * (b) been superseded by a later update.
+   */
+  update(text: string): Promise<void>
+
+  /**
+   * Mark the stream as final. Flushes any pending text and rejects all
+   * future update() calls. Returns a promise that resolves once the final
+   * edit has landed (or the initial send if no edits ever fired).
+   */
+  finalize(): Promise<void>
+
+  /** Returns the captured Telegram message_id, or null if nothing has sent yet. */
+  getMessageId(): number | null
+
+  /** True if finalize() has been called. */
+  isFinal(): boolean
+}
+
+/**
+ * Create a draft stream bound to a specific Telegram chat+thread.
+ *
+ * The first update() call invokes `send` to create the message. All
+ * subsequent calls invoke `edit` against the captured message_id.
+ *
+ * When sendMessageDraft is provided (and transport allows it), intermediate
+ * updates use the draft API instead of sendMessage/editMessageText. On
+ * finalize(), a real sendMessage is sent for push notification, then the
+ * draft is cleared best-effort.
+ */
+export function createDraftStream(
+  send: StreamSendFn,
+  edit: StreamEditFn,
+  config: DraftStreamConfig = {},
+): DraftStreamHandle {
+  const throttleMs = Math.max(MIN_THROTTLE_MS, config.throttleMs ?? DEFAULT_THROTTLE_MS)
+  const maxChars = config.maxChars ?? TELEGRAM_MAX_CHARS
+  const idleMs = Math.max(0, config.idleMs ?? 0)
+  const log = config.log
+  const warn = config.warn
+  const draftApi = config.sendMessageDraft
+  const chatId = config.chatId ?? ''
+
+  // Resolve transport
+  const requestedTransport = config.previewTransport ?? 'auto'
+  const prefersDraft =
+    requestedTransport === 'draft'
+      ? true
+      : requestedTransport === 'message'
+        ? false
+        : (config.isPrivateChat === true) // 'auto': DM only
+
+  // Footgun guard: caller asked for "auto" + provided sendMessageDraft but
+  // forgot isPrivateChat. They almost certainly wanted draft in DMs but will
+  // silently get message transport everywhere. Warn so the bug is visible.
+  if (
+    requestedTransport === 'auto'
+    && draftApi != null
+    && config.isPrivateChat === undefined
+  ) {
+    warn?.('draft-stream: previewTransport="auto" with sendMessageDraft but isPrivateChat undefined — defaulting to message transport')
+  }
+
+  // Use draft transport only if we have the API
+  let usesDraftTransport = prefersDraft && draftApi != null
+  let draftId: number | undefined = usesDraftTransport
+    ? allocateDraftId()
+    : undefined
+
+  if (prefersDraft && !usesDraftTransport) {
+    warn?.('draft-stream: sendMessageDraft unavailable; falling back to sendMessage/editMessageText')
+  }
+
+  let messageId: number | null = config.initialMessageId ?? null
+  let pendingText: string | null = null
+  let lastSentText: string | null = null
+  let lastSentAt = 0
+  let inFlight: Promise<void> | null = null
+  let scheduledTimer: ReturnType<typeof setTimeout> | null = null
+  let final = false
+  let stopped = false
+
+  // Tracks pending update() calls so caller can `await` the next flush
+  const waiters: Array<() => void> = []
+
+  function notifyWaiters(): void {
+    const w = waiters.splice(0)
+    for (const fn of w) {
+      try {
+        fn()
+      } catch { /* ignore waiter errors */ }
+    }
+  }
+
+  async function sendViaDraft(textToSend: string): Promise<boolean> {
+    if (!draftApi || draftId == null) return false
+    try {
+      await draftApi(chatId, draftId, textToSend)
+      log?.(`stream → draft (id: ${draftId}, ${textToSend.length} chars)`)
+      return true
+    } catch (err) {
+      if (shouldFallbackFromDraftTransport(err)) {
+        const msg = err instanceof Error ? err.message : String(err)
+        warn?.(`draft-stream: sendMessageDraft rejected — falling back to sendMessage/editMessageText (${msg})`)
+        usesDraftTransport = false
+        draftId = undefined
+        return false
+      }
+      throw err
+    }
+  }
+
+  async function flush(): Promise<void> {
+    if (stopped) {
+      notifyWaiters()
+      return
+    }
+    if (pendingText == null) {
+      notifyWaiters()
+      return
+    }
+    const textToSend = pendingText
+    pendingText = null
+
+    if (textToSend === lastSentText) {
+      // Nothing actually changed — skip the API call but free waiters
+      notifyWaiters()
+      return
+    }
+
+    if (textToSend.length > maxChars) {
+      log?.(`stream stopped: text exceeds ${maxChars} chars`)
+      stopped = true
+      notifyWaiters()
+      return
+    }
+
+    try {
+      if (usesDraftTransport) {
+        const ok = await sendViaDraft(textToSend)
+        if (!ok) {
+          // Draft failed with a permanent error → fell back to message transport.
+          // Replay this text via message transport.
+          await sendViaMessage(textToSend)
+        }
+      } else {
+        await sendViaMessage(textToSend)
+      }
+      lastSentText = textToSend
+      lastSentAt = Date.now()
+    } catch (err) {
+      const msg = (err as Error).message ?? String(err)
+      if (/\bmessage is not modified\b/i.test(msg)) {
+        lastSentText = textToSend
+        lastSentAt = Date.now()
+        log?.(`stream → not modified (id: ${messageId})`)
+      } else if (
+        /\bmessage to edit not found\b/i.test(msg)
+        || /\bMESSAGE_ID_INVALID\b/i.test(msg)
+      ) {
+        log?.(`stream → message not found (id: ${messageId}), re-sending`)
+        messageId = null
+        lastSentText = null
+        if (pendingText == null) pendingText = textToSend
+      } else {
+        log?.(`stream → edit failed: ${msg}`)
+      }
+    }
+
+    notifyWaiters()
+  }
+
+  async function sendViaMessage(textToSend: string): Promise<void> {
+    if (messageId == null) {
+      messageId = await send(textToSend)
+      log?.(`stream → sent (id: ${messageId}, ${textToSend.length} chars)`)
+    } else {
+      await edit(messageId, textToSend)
+      log?.(`stream → edited (id: ${messageId}, ${textToSend.length} chars)`)
+    }
+  }
+
+  async function flushLoop(): Promise<void> {
+    // Drain any updates that arrived during the in-flight call.
+    while (pendingText != null && !stopped) {
+      await flush()
+    }
+  }
+
+  function schedule(): void {
+    if (scheduledTimer != null) return
+    if (stopped) return
+    const sinceLast = Date.now() - lastSentAt
+    const delay = Math.max(0, throttleMs - sinceLast)
+    scheduledTimer = setTimeout(() => {
+      scheduledTimer = null
+      if (inFlight) {
+        // The in-flight loop will pick up pendingText after it resolves.
+        return
+      }
+      inFlight = flushLoop().finally(() => {
+        inFlight = null
+      })
+    }, delay)
+  }
+
+  return {
+    update(text: string): Promise<void> {
+      if (final || stopped) return Promise.resolve()
+      pendingText = text
+      const waitPromise = new Promise<void>(resolve => {
+        waiters.push(resolve)
+      })
+
+      // Pre-send idle debounce: for the FIRST send of a stream, optionally
+      // defer by idleMs so a burst of update() calls collapses into one
+      // send. Each incoming update resets the timer. Once the initial
+      // send has landed (messageId != null OR draft has fired), this path
+      // is skipped and the regular throttle kicks in.
+      if (idleMs > 0 && messageId == null && !usesDraftTransport && inFlight == null) {
+        if (scheduledTimer != null) clearTimeout(scheduledTimer)
+        scheduledTimer = setTimeout(() => {
+          scheduledTimer = null
+          inFlight = flushLoop().finally(() => { inFlight = null })
+        }, idleMs)
+        return waitPromise
+      }
+
+      // If nothing in flight and the throttle window is open, fire now.
+      if (inFlight == null && Date.now() - lastSentAt >= throttleMs) {
+        inFlight = flushLoop().finally(() => {
+          inFlight = null
+        })
+      } else if (inFlight == null) {
+        schedule()
+      } else {
+        // inFlight is set — the current flushLoop is running. Previous
+        // versions of this code relied on flushLoop's while(pendingText
+        // != null) to pick up the new text, but there's a race: if
+        // update() fires AFTER the while's final (null) check but
+        // BEFORE the flushLoop promise settles, the new pendingText
+        // lands in a shell with no one looking at it, and the waiter
+        // hangs forever. Chain a follow-up flush off the current
+        // flushLoop so the new text is guaranteed to be drained.
+        inFlight.then(() => {
+          if (stopped || pendingText == null) return
+          if (inFlight != null) return // a new flushLoop already started
+          if (Date.now() - lastSentAt >= throttleMs) {
+            inFlight = flushLoop().finally(() => { inFlight = null })
+          } else {
+            schedule()
+          }
+        })
+      }
+      return waitPromise
+    },
+
+    async finalize(): Promise<void> {
+      if (final) return
+      final = true
+      // Drain any pending updates
+      if (scheduledTimer != null) {
+        clearTimeout(scheduledTimer)
+        scheduledTimer = null
+      }
+      if (inFlight) {
+        await inFlight
+      }
+      if (pendingText != null && !stopped) {
+        await flush()
+      }
+
+      // Draft transport: materialize as a real sendMessage for push notification,
+      // then clear the draft best-effort.
+      if (usesDraftTransport && draftApi != null) {
+        const textToMaterialize = lastSentText
+        if (textToMaterialize) {
+          try {
+            messageId = await send(textToMaterialize)
+            log?.(`stream → materialized (id: ${messageId}, ${textToMaterialize.length} chars)`)
+          } catch (err) {
+            warn?.(`draft-stream: materialize sendMessage failed: ${err instanceof Error ? err.message : String(err)}`)
+          }
+          // Clear draft best-effort (cosmetic — Telegram input area cleanup)
+          if (draftId != null) {
+            try {
+              await draftApi(chatId, draftId, '')
+            } catch {
+              // Best-effort — ignore failures
+            }
+          }
+        }
+      }
+
+      log?.(`stream finalized (id: ${messageId})`)
+    },
+
+    getMessageId(): number | null {
+      return messageId
+    },
+
+    isFinal(): boolean {
+      return final
+    },
+  }
+}