switchroom 0.5.0

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

@@ -0,0 +1,381 @@
+/**
+ * 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

@@ -0,0 +1,233 @@
+/**
+ * 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()
+  })
+})