switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/waiting-ux-harness.ts

@@ -1,381 +0,0 @@
-/**
- * Waiting-UX E2E harness — Phase 1 of #545.
- *
- * Wires the production status-reaction controller, progress-card driver,
- * and a recording fake-bot under vitest fake timers. The goal is to make
- * the four observed waiting-UX failure modes catchable in CI by asserting
- * the wall-clock contract that varies by turn class:
- *   A — instant reply (no tools, <2s)
- *   B — short turn (1–3 tools, <15s)
- *   C — long / multi-agent (sub-agents, background workers)
- *
- * The harness simulates the slice of server.ts that determines the
- * user-perceived timing:
- *   inbound update      → setQueued() (👀)        + progressDriver.startTurn()
- *   session 'thinking'  → setThinking() (🤔)
- *   session 'tool_use'  → setTool(name) (🔥/✍/👨‍💻/⚡)
- *   stream_reply        → editMessageText / sendMessage on bot.api
- *   session 'turn_end'  → setDone() (👍)          + driver flush + onTurnComplete
- *
- * Anything not on that path (auth, history, ipc, foreman) is intentionally
- * out of scope — those don't influence the four failures.
- *
- * Time control is via `vi.useFakeTimers()`; tests advance time with
- * `clock.advance(ms)` which delegates to `vi.advanceTimersByTimeAsync`.
- * Every recorded outbound API call is timestamped with the simulated
- * `Date.now()` at the moment of the call.
- */
-
-import { vi, type MockInstance } from 'vitest'
-import { StatusReactionController } from '../status-reactions.js'
-import { createProgressDriver, type ProgressDriver } from '../progress-card-driver.js'
-import type { SessionEvent } from '../session-tail.js'
-
-// ─── Recorder ────────────────────────────────────────────────────────────
-
-export type RecordedKind =
-  | 'sendMessage'
-  | 'editMessageText'
-  | 'setMessageReaction'
-  | 'sendChatAction'
-  | 'deleteMessage'
-  | 'pinChatMessage'
-
-export interface RecordedCall {
-  ts: number
-  kind: RecordedKind
-  chat_id: string
-  message_id?: number
-  payload?: string
-  args: unknown[]
-}
-
-export interface Recorder {
-  calls: RecordedCall[]
-  reactionSequence(): string[]
-  sentTexts(chat_id: string): string[]
-  edits(chat_id: string): RecordedCall[]
-  /**
-   * Detects the progress card sendMessage by payload heuristic
-   * (Working… / ⚙️ / ⏳ glyphs that the production card uses).
-   */
-  progressCardSendMs(chat_id: string): number | null
-  firstReactionMs(chat_id: string): number | null
-  lastReactionEmoji(chat_id: string): string | null
-}
-
-// ─── Clock ───────────────────────────────────────────────────────────────
-
-export interface HarnessClock {
-  now(): number
-  advance(ms: number): Promise<void>
-}
-
-// ─── Fake bot.api with recording ─────────────────────────────────────────
-
-type Method = (...args: unknown[]) => Promise<unknown>
-
-export interface FakeBotApi {
-  sendMessage: MockInstance<Method>
-  editMessageText: MockInstance<Method>
-  setMessageReaction: MockInstance<Method>
-  sendChatAction: MockInstance<Method>
-  deleteMessage: MockInstance<Method>
-  pinChatMessage: MockInstance<Method>
-  unpinChatMessage: MockInstance<Method>
-  editMessageReplyMarkup: MockInstance<Method>
-  getFile: MockInstance<Method>
-}
-
-export interface HarnessHandle {
-  bot: { api: FakeBotApi }
-  clock: HarnessClock
-  recorder: Recorder
-  controller: StatusReactionController
-  driver: ProgressDriver
-  inbound(opts: { chatId: string; messageId: number; text?: string }): void
-  feedSessionEvent(ev: SessionEvent): void
-  /** Convenience for class-A direct stream_reply path. */
-  streamReply(opts: { chat_id: string; text: string; done?: boolean }): Promise<void>
-  finalize(): void
-}
-
-function makeRecorderAndApi(): { recorder: Recorder; api: FakeBotApi } {
-  let nextId = 5000
-  const calls: RecordedCall[] = []
-
-  const sendMessage = vi.fn(async (...args: unknown[]) => {
-    const message_id = nextId++
-    calls.push({
-      ts: Date.now(),
-      kind: 'sendMessage',
-      chat_id: String(args[0]),
-      message_id,
-      payload: String(args[1] ?? ''),
-      args,
-    })
-    return { message_id }
-  }) as unknown as MockInstance<Method>
-
-  const editMessageText = vi.fn(async (...args: unknown[]) => {
-    calls.push({
-      ts: Date.now(),
-      kind: 'editMessageText',
-      chat_id: String(args[0]),
-      message_id: Number(args[1]),
-      payload: String(args[2] ?? ''),
-      args,
-    })
-    return true
-  }) as unknown as MockInstance<Method>
-
-  const setMessageReaction = vi.fn(async (...args: unknown[]) => {
-    const reactions = args[2] as Array<{ emoji?: string }> | undefined
-    const emoji = reactions?.[0]?.emoji
-    calls.push({
-      ts: Date.now(),
-      kind: 'setMessageReaction',
-      chat_id: String(args[0]),
-      message_id: Number(args[1]),
-      payload: emoji,
-      args,
-    })
-    return true
-  }) as unknown as MockInstance<Method>
-
-  const sendChatAction = vi.fn(async (...args: unknown[]) => {
-    calls.push({
-      ts: Date.now(),
-      kind: 'sendChatAction',
-      chat_id: String(args[0]),
-      payload: String(args[1] ?? ''),
-      args,
-    })
-    return true
-  }) as unknown as MockInstance<Method>
-
-  const deleteMessage = vi.fn(async (...args: unknown[]) => {
-    calls.push({
-      ts: Date.now(),
-      kind: 'deleteMessage',
-      chat_id: String(args[0]),
-      message_id: Number(args[1]),
-      args,
-    })
-    return true
-  }) as unknown as MockInstance<Method>
-
-  const pinChatMessage = vi.fn(async (...args: unknown[]) => {
-    calls.push({
-      ts: Date.now(),
-      kind: 'pinChatMessage',
-      chat_id: String(args[0]),
-      message_id: Number(args[1]),
-      args,
-    })
-    return true
-  }) as unknown as MockInstance<Method>
-
-  const unpinChatMessage = vi.fn(async () => true) as unknown as MockInstance<Method>
-  const editMessageReplyMarkup = vi.fn(async () => true) as unknown as MockInstance<Method>
-  const getFile = vi.fn(async () => ({ file_path: 'x' })) as unknown as MockInstance<Method>
-
-  const api: FakeBotApi = {
-    sendMessage,
-    editMessageText,
-    setMessageReaction,
-    sendChatAction,
-    deleteMessage,
-    pinChatMessage,
-    unpinChatMessage,
-    editMessageReplyMarkup,
-    getFile,
-  }
-
-  const isCardPayload = (text: string | undefined): boolean =>
-    text != null &&
-    (text.includes('Working') ||
-      text.includes('⚙') ||
-      text.includes('⏳') ||
-      text.includes('• '))
-
-  const recorder: Recorder = {
-    calls,
-    reactionSequence: () =>
-      calls.filter((c) => c.kind === 'setMessageReaction').map((c) => c.payload ?? ''),
-    sentTexts: (chat_id) =>
-      calls
-        .filter((c) => c.kind === 'sendMessage' && c.chat_id === chat_id)
-        .map((c) => c.payload ?? ''),
-    edits: (chat_id) => calls.filter((c) => c.kind === 'editMessageText' && c.chat_id === chat_id),
-    progressCardSendMs: (chat_id) => {
-      const hit = calls.find(
-        (c) => c.kind === 'sendMessage' && c.chat_id === chat_id && isCardPayload(c.payload),
-      )
-      return hit ? hit.ts : null
-    },
-    firstReactionMs: (chat_id) => {
-      const hit = calls.find((c) => c.kind === 'setMessageReaction' && c.chat_id === chat_id)
-      return hit ? hit.ts : null
-    },
-    lastReactionEmoji: (chat_id) => {
-      const hits = calls.filter((c) => c.kind === 'setMessageReaction' && c.chat_id === chat_id)
-      return hits.length === 0 ? null : (hits[hits.length - 1].payload ?? null)
-    },
-  }
-
-  return { recorder, api }
-}
-
-// ─── Public factory ──────────────────────────────────────────────────────
-
-export interface CreateHarnessOpts {
-  allowedReactions?: Set<string> | null
-  debounceMs?: number
-  driverCoalesceMs?: number
-  driverMinIntervalMs?: number
-  /**
-   * Progress-card initial-delay-ms. Production default is 30s (cards are
-   * suppressed for fast turns). Tests for class B/C should set this small
-   * (e.g. 0–500) so the deferred first emit can fire inside the test.
-   */
-  driverInitialDelayMs?: number
-  /** Heartbeat ms; pass 0 to disable. */
-  driverHeartbeatMs?: number
-}
-
-export function createWaitingUxHarness(opts: CreateHarnessOpts = {}): HarnessHandle {
-  // vi.useFakeTimers() must be called by the test (so afterEach can reset).
-  // The harness assumes fake timers are active.
-  const { recorder, api } = makeRecorderAndApi()
-  const bot = { api }
-
-  let primaryChatId: string | null = null
-  let primaryMessageId: number | null = null
-  let currentChatId: string | null = null
-
-  const controller = new StatusReactionController(
-    async (emoji) => {
-      if (primaryChatId == null || primaryMessageId == null) return
-      await api.setMessageReaction(primaryChatId, primaryMessageId, [
-        { type: 'emoji', emoji },
-      ])
-    },
-    opts.allowedReactions ?? null,
-    {
-      debounceMs: opts.debounceMs ?? 700,
-    },
-  )
-
-  const cardMessageIds = new Map<string, number>()
-
-  async function renderCard(a: { chatId: string; html: string; done: boolean; isFirstEmit: boolean }): Promise<void> {
-    const existing = cardMessageIds.get(a.chatId)
-    if (existing == null) {
-      const result = (await api.sendMessage(a.chatId, a.html, { parse_mode: 'HTML' })) as { message_id: number }
-      cardMessageIds.set(a.chatId, result.message_id)
-    } else {
-      await api.editMessageText(a.chatId, existing, a.html, { parse_mode: 'HTML' })
-    }
-  }
-
-  const driver = createProgressDriver({
-    emit: (a) => {
-      void renderCard(a)
-    },
-    coalesceMs: opts.driverCoalesceMs ?? 400,
-    minIntervalMs: opts.driverMinIntervalMs ?? 500,
-    initialDelayMs: opts.driverInitialDelayMs ?? 60000,
-    heartbeatMs: opts.driverHeartbeatMs,
-  })
-
-  function feedSessionEvent(ev: SessionEvent): void {
-    switch (ev.kind) {
-      case 'enqueue':
-        if (ev.chatId) currentChatId = ev.chatId
-        break
-      case 'thinking':
-        controller.setThinking()
-        break
-      case 'tool_use':
-        if (!isTelegramSurfaceTool(ev.toolName)) {
-          controller.setTool(ev.toolName)
-        }
-        break
-      case 'turn_end':
-        controller.setDone()
-        break
-      default:
-        break
-    }
-    driver.ingest(ev, currentChatId, undefined)
-  }
-
-  function inbound(args: { chatId: string; messageId: number; text?: string }): void {
-    primaryChatId = args.chatId
-    primaryMessageId = args.messageId
-    // 👀 immediately — same line as server.ts:6118.
-    controller.setQueued()
-    // Prime the progress card synchronously, same as server.ts:6147.
-    driver.startTurn({ chatId: args.chatId, userText: args.text ?? '' })
-  }
-
-  const streamMsgs = new Map<string, number>()
-
-  async function streamReply(args: { chat_id: string; text: string; done?: boolean }): Promise<void> {
-    const key = args.chat_id
-    const existingId = streamMsgs.get(key)
-    if (existingId == null) {
-      const r = (await api.sendMessage(args.chat_id, args.text, { parse_mode: 'HTML' })) as { message_id: number }
-      streamMsgs.set(key, r.message_id)
-    } else {
-      await api.editMessageText(args.chat_id, existingId, args.text, { parse_mode: 'HTML' })
-    }
-    if (args.done === true) {
-      controller.setDone()
-    }
-  }
-
-  function finalize(): void {
-    try { driver.dispose?.() } catch { /* ignore */ }
-  }
-
-  const clock: HarnessClock = {
-    now: () => Date.now(),
-    advance: async (ms) => {
-      // vi.advanceTimersByTimeAsync isn't implemented by Bun's vitest shim,
-      // so fall back to the sync variant + microtask flush. Same semantics
-      // for these tests; lets the harness run under both vitest and `bun test`.
-      const viAny = vi as { advanceTimersByTimeAsync?: (ms: number) => Promise<void> }
-      if (typeof viAny.advanceTimersByTimeAsync === 'function') {
-        await viAny.advanceTimersByTimeAsync(ms)
-        return
-      }
-      vi.advanceTimersByTime(ms)
-      for (let i = 0; i < 5; i++) await Promise.resolve()
-    },
-  }
-
-  return {
-    bot,
-    clock,
-    recorder,
-    controller,
-    driver,
-    inbound,
-    feedSessionEvent,
-    streamReply,
-    finalize,
-  }
-}
-
-function isTelegramSurfaceTool(name: string): boolean {
-  const n = name.toLowerCase()
-  return (
-    n.endsWith('__reply') ||
-    n.endsWith('__stream_reply') ||
-    n.endsWith('__edit_message') ||
-    n === 'reply' ||
-    n === 'stream_reply'
-  )
-}

package/telegram-plugin/tests/waiting-ux.e2e.test.ts

@@ -1,233 +0,0 @@
-/**
- * Waiting-UX E2E contract tests — Phase 1 of #545 (RED).
- *
- * These tests assert the deterministic time-sequence contract for the
- * three turn classes specified in #545. They are intentionally RED on
- * `main` — each one catches one of the four observed failure modes from
- * the live demo:
- *
- *   F1. Status reaction collapses straight to 👍 (skips 👀→🤔→🔥).
- *   F2. No instant draft/typing signal — silence "for ages" after inbound.
- *   F3. Progress card renders late.
- *   F4. Pre-tool interim text is static — no refresh on step transitions.
- *
- * Phase 1 scope is tests-only — no production fixes. Once these go green
- * we know the underlying behaviour matches the spec.
- *
- * All time control is via `vi.useFakeTimers()`. The harness records every
- * outbound bot.api call with `Date.now()` at invocation time, so first-
- * paint and ladder assertions are wall-clock deterministic.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { createWaitingUxHarness, type HarnessHandle } from './waiting-ux-harness.js'
-import type { SessionEvent } from '../session-tail.js'
-
-const CHAT = '8248703757'
-const INBOUND_MSG = 100
-
-beforeEach(() => {
-  vi.useFakeTimers()
-})
-
-afterEach(() => {
-  vi.useRealTimers()
-})
-
-// ─── Class A — Instant reply (no tool calls, <2s) ────────────────────────
-
-describe('Class A — instant reply', () => {
-  it('first-paint deadline: 👀 reaction lands within 800ms of inbound (catches F2)', async () => {
-    const h = createWaitingUxHarness()
-    const inboundAt = h.clock.now()
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
-    // Allow microtasks + the controller's queued (immediate, no debounce).
-    await h.clock.advance(50)
-    const firstReaction = h.recorder.firstReactionMs(CHAT)
-    expect(firstReaction).not.toBeNull()
-    expect((firstReaction ?? Infinity) - inboundAt).toBeLessThan(800)
-    expect(h.recorder.reactionSequence()[0]).toBe('👀')
-    h.finalize()
-  })
-
-  it('no progress card is sent for an instant turn (catches F3 / spec class A)', async () => {
-    const h = createWaitingUxHarness({ driverInitialDelayMs: 30_000 })
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
-    // Class A: enqueue → small thinking burst → reply → turn_end, all <2s.
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'hi' })
-    await h.clock.advance(100)
-    h.feedSessionEvent({ kind: 'thinking' })
-    await h.clock.advance(200)
-    await h.streamReply({ chat_id: CHAT, text: 'hello back', done: true })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 1500 })
-    await h.clock.advance(2_000)
-    expect(h.recorder.progressCardSendMs(CHAT)).toBeNull()
-    h.finalize()
-  })
-
-  it('terminates with 👍 and no spurious intermediate states', async () => {
-    const h = createWaitingUxHarness()
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'hi' })
-    await h.clock.advance(50)
-    await h.streamReply({ chat_id: CHAT, text: 'hello back', done: true })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 800 })
-    await h.clock.advance(1_500)
-    expect(h.recorder.lastReactionEmoji(CHAT)).toBe('👍')
-    h.finalize()
-  })
-})
-
-// ─── Class B — short turn (1–3 tools, <15s) ──────────────────────────────
-
-describe('Class B — short turn', () => {
-  it('ladder integrity: 👀 → (🤔 or working glyph) before 👍 — catches F1 (straight-to-👍 collapse)', async () => {
-    const h = createWaitingUxHarness({ debounceMs: 700 })
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'read foo.txt' })
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'read foo.txt' })
-    // 200ms in — model starts thinking
-    await h.clock.advance(200)
-    h.feedSessionEvent({ kind: 'thinking' })
-    // 1s in — Read tool (debounced by 700ms — should still land before turn_end)
-    await h.clock.advance(800)
-    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Read', toolUseId: 't1' })
-    // Wait long enough for the tool reaction to flush past debounce.
-    await h.clock.advance(1_500)
-    h.feedSessionEvent({ kind: 'tool_result', toolUseId: 't1', toolName: 'Read' })
-    await h.streamReply({ chat_id: CHAT, text: 'contents: ...', done: true })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 4_000 })
-    await h.clock.advance(2_000)
-
-    const seq = h.recorder.reactionSequence()
-    // Must start with 👀
-    expect(seq[0]).toBe('👀')
-    // Must NOT collapse straight to 👍 — at least one intermediate before final.
-    expect(seq.length).toBeGreaterThanOrEqual(3)
-    const finalIdx = seq.length - 1
-    expect(seq[finalIdx]).toBe('👍')
-    // Intermediate states must include a thinking/working emoji, not just 👀.
-    const intermediates = seq.slice(1, finalIdx)
-    const hasIntermediate = intermediates.some((e) =>
-      ['🤔', '🤓', '✍', '⚡', '👌', '👨‍💻', '🔥'].includes(e),
-    )
-    expect(hasIntermediate, `ladder collapsed: ${JSON.stringify(seq)}`).toBe(true)
-    h.finalize()
-  })
-
-  it('interim refresh: pre-tool preamble updates ≥1× across step transitions (catches F4)', async () => {
-    const h = createWaitingUxHarness()
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'do thing' })
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'do thing' })
-    // Initial preamble before any tool runs.
-    await h.streamReply({ chat_id: CHAT, text: 'looking…' })
-    await h.clock.advance(500)
-    // Step transition #1 — tool_use lands.
-    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Read', toolUseId: 't1' })
-    await h.clock.advance(500)
-    // Step transition #2 — second different tool category.
-    h.feedSessionEvent({ kind: 'tool_use', toolName: 'WebFetch', toolUseId: 't2' })
-    await h.clock.advance(500)
-    await h.streamReply({ chat_id: CHAT, text: 'final answer', done: true })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 3_000 })
-
-    // Across the two step transitions we must see ≥1 update to the
-    // pre-tool preamble surface (sendMessage or editMessageText for the
-    // active stream). Today's behaviour: a single static preamble then
-    // silence — this assertion catches that.
-    const edits = h.recorder.edits(CHAT)
-    expect(edits.length, 'pre-tool preamble never refreshed').toBeGreaterThanOrEqual(1)
-    h.finalize()
-  })
-})
-
-// ─── Class C — long / multi-agent ────────────────────────────────────────
-
-describe('Class C — long / multi-agent', () => {
-  it('progress card renders early, before turn_end, for a multi-second turn (catches F3)', async () => {
-    const h = createWaitingUxHarness({
-      driverInitialDelayMs: 500, // production tunes this; harness asserts the contract
-      driverCoalesceMs: 100,
-      driverMinIntervalMs: 100,
-    })
-    const inboundAt = h.clock.now()
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'big task' })
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'big task' })
-    await h.clock.advance(200)
-    h.feedSessionEvent({ kind: 'thinking' })
-    await h.clock.advance(300)
-    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash', toolUseId: 't1' })
-    // By 2s, the card MUST be visible — not at turn_end.
-    await h.clock.advance(1_500)
-    const cardAt = h.recorder.progressCardSendMs(CHAT)
-    expect(cardAt, 'progress card never rendered').not.toBeNull()
-    expect((cardAt ?? Infinity) - inboundAt).toBeLessThan(2_500)
-    // Drain the rest of the turn so afterEach doesn't leak timers.
-    h.feedSessionEvent({ kind: 'tool_result', toolUseId: 't1', toolName: 'Bash' })
-    await h.streamReply({ chat_id: CHAT, text: 'done', done: true })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 5_000 })
-    await h.clock.advance(2_000)
-    h.finalize()
-  })
-
-  it('card stays stable until ALL background work hits terminal — Done ≥ last sub-agent terminal', async () => {
-    const h = createWaitingUxHarness({
-      driverInitialDelayMs: 200,
-      driverCoalesceMs: 100,
-      driverMinIntervalMs: 100,
-    })
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'multi-agent' })
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'multi-agent' })
-    await h.clock.advance(300)
-    // Spawn two sub-agents.
-    h.feedSessionEvent({ kind: 'sub_agent_started', agentId: 'a1', firstPromptText: 'a1' })
-    h.feedSessionEvent({ kind: 'sub_agent_started', agentId: 'a2', firstPromptText: 'a2' })
-    await h.clock.advance(1_000)
-    // a1 finishes early.
-    h.feedSessionEvent({ kind: 'sub_agent_turn_end', agentId: 'a1' })
-    const a1TerminalAt = h.clock.now()
-    await h.clock.advance(2_000)
-    // Main turn_end arrives BEFORE a2 finishes — the card must NOT mark
-    // Done yet (spec: stable until all workers terminal).
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 3_000 })
-    await h.clock.advance(500)
-    // a2 finishes last — this is the true terminal.
-    h.feedSessionEvent({ kind: 'sub_agent_turn_end', agentId: 'a2' })
-    const a2TerminalAt = h.clock.now()
-    await h.clock.advance(2_000)
-
-    // Find the card edit/send that marks Done. Production cards
-    // typically include a "Done" / "✅" / "✓" glyph in the final HTML.
-    const cardOps = h.recorder.calls.filter(
-      (c) =>
-        (c.kind === 'sendMessage' || c.kind === 'editMessageText') &&
-        c.chat_id === CHAT &&
-        (c.payload?.includes('Done') === true ||
-          c.payload?.includes('✅') === true ||
-          c.payload?.includes('✓') === true),
-    )
-    expect(cardOps.length, 'card never reached a Done state').toBeGreaterThan(0)
-    const doneAt = cardOps[cardOps.length - 1].ts
-    expect(
-      doneAt,
-      `card Done (${doneAt}) fired before last sub-agent terminal (${a2TerminalAt})`,
-    ).toBeGreaterThanOrEqual(a2TerminalAt)
-    // Sanity: a1 was earlier than a2.
-    expect(a1TerminalAt).toBeLessThan(a2TerminalAt)
-    h.finalize()
-  })
-
-  it('first-paint deadline still ≤800ms even on long turns', async () => {
-    const h = createWaitingUxHarness({ driverInitialDelayMs: 500 })
-    const inboundAt = h.clock.now()
-    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'long' })
-    await h.clock.advance(50)
-    const firstReaction = h.recorder.firstReactionMs(CHAT)
-    expect(firstReaction).not.toBeNull()
-    expect((firstReaction ?? Infinity) - inboundAt).toBeLessThan(800)
-    // Cleanup.
-    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'long' })
-    h.feedSessionEvent({ kind: 'turn_end', durationMs: 100 })
-    await h.clock.advance(2_000)
-    h.finalize()
-  })
-})

package/telegram-plugin/turn-flush-prose-recovery.ts

@@ -1,40 +0,0 @@
-/**
- * Turn-flush prose recovery for #51.
- *
- * The gateway's `currentTurnCapturedText` accumulator gates on
- * `currentSessionChatId != null`, while the progress-card driver's
- * `ingest` uses the `chatId` from the IPC envelope (chatHint). When those
- * two views of "is this turn one we're tracking" disagree — e.g., text
- * arrives before enqueue's chatId is captured, or after a mid-turn reset
- * — the progress card renders the assistant prose as narrative steps but
- * `capturedText` stays empty, so `decideTurnFlush` returns `'empty-text'`
- * and the turn-flush backstop never sends the prose to Telegram. The
- * user sees a step bullet on the card and nothing in their chat.
- *
- * This helper bridges the gap: at turn_end, if the gateway has no
- * captured text, peek the progress-card state and recover the assistant
- * prose from the narrative steps. Pure for testability — the gateway
- * is responsible for actually wiring the recovered text into the flush
- * decision.
- */
-
-import type { ProgressCardState } from './progress-card.js'
-
-/**
- * Returns the joined assistant prose recorded as narrative steps in the
- * progress-card state, trimmed. Empty string when the state has no
- * narratives (or is undefined).
- */
-export function recoverProseFromProgressCard(
-  state: ProgressCardState | undefined,
-): string {
-  if (state == null) return ''
-  // Defensive: older state shapes (e.g. partial persisted state, mocks
-  // in tests) may lack the `narratives` field. Don't throw.
-  if (!Array.isArray(state.narratives)) return ''
-  const parts: string[] = []
-  for (const n of state.narratives) {
-    if (typeof n.text === 'string' && n.text.length > 0) parts.push(n.text)
-  }
-  return parts.join('\n').trim()
-}