switchroom 0.5.0

package/telegram-plugin/tests/progress-card-close-paths-converge.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Refactor regression: every per-chat close site must end in the SAME
+ * post-conditions on the driver's internal state. Pre-refactor, three
+ * code paths (turn_end → completeTurnFully, heartbeat zombie ceiling →
+ * closeZombie, Gap-8 deferred-completion timeout → inline) reproduced
+ * the cleanup tail by hand and diverged on edge cases. The refactor
+ * funnels them all through `closePerChat(reason)` so the only remaining
+ * deltas are:
+ *
+ *   - 'turn-end': no sub-agent force-close (none are running).
+ *   - 'zombie'  : force-close running sub-agents; preserve
+ *                 pendingSyncEchoes (echo may still arrive).
+ *   - 'stalled' : force-close running sub-agents; flush(stalledClose=true).
+ *
+ * This test drives all three reasons against a fresh driver instance
+ * and asserts the convergent post-conditions. It is the load-bearing
+ * test for the unified close path — if it fails, the refactor regressed.
+ */
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import type { SessionEvent } from '../session-tail.js'
+
+let nextMsgId = 7000
+
+function harness(opts?: { maxIdleMs?: number; deferredCompletionTimeoutMs?: number }) {
+  let now = 1000
+  const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+  let nextRef = 0
+  const emits: Array<{ chatId: string; threadId?: string; turnKey: string; html: string; done: boolean }> = []
+
+  const driver = createProgressDriver({
+    emit: (a) => emits.push(a),
+    minIntervalMs: 0,
+    coalesceMs: 0,
+    initialDelayMs: 0,
+    heartbeatMs: 1_000,
+    maxIdleMs: opts?.maxIdleMs ?? 30_000,
+    deferredCompletionTimeoutMs: opts?.deferredCompletionTimeoutMs ?? 10_000,
+    now: () => now,
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+  })
+
+  const advance = (ms: number): void => {
+    now += ms
+    for (;;) {
+      timers.sort((a, b) => a.fireAt - b.fireAt)
+      const next = timers[0]
+      if (!next || next.fireAt > now) break
+      if (next.repeat != null) {
+        next.fireAt += next.repeat
+        next.fn()
+      } else {
+        timers.shift()
+        next.fn()
+      }
+    }
+  }
+
+  return { driver, emits, advance, getNow: () => now }
+}
+
+function enqueue(chatId: string): SessionEvent {
+  return {
+    kind: 'enqueue',
+    chatId,
+    messageId: String(nextMsgId++),
+    threadId: null,
+    rawContent: `<channel chat_id="${chatId}">go</channel>`,
+  }
+}
+
+describe('progress-card-driver: all close paths converge on identical final state', () => {
+  it("'turn-end' path: chats empty, baseTurnSeqs cleaned, heartbeat stopped", () => {
+    const { driver } = harness()
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('cA'), null)
+    expect(maps.chats.size).toBe(1)
+    expect(maps.baseTurnSeqs.has('cA')).toBe(true)
+
+    driver.ingest({ kind: 'turn_end', durationMs: 50 }, 'cA')
+
+    expect(maps.chats.size).toBe(0)
+    expect(maps.baseTurnSeqs.has('cA')).toBe(false)
+    expect(maps.chatRunningSubagents.has('cA')).toBe(false)
+  })
+
+  it("'zombie' path (heartbeat maxIdle ceiling): same convergence + pendingSyncEchoes preserved", () => {
+    const { driver, advance } = harness({ maxIdleMs: 5_000 })
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('cA'), null)
+    expect(maps.chats.size).toBe(1)
+
+    // Seed a pending sync-echo so we can assert the zombie path leaves it
+    // in place (the echo may still arrive after close).
+    maps.pendingSyncEchoes.set('cA:fake', 1000)
+
+    // Idle past maxIdleMs so the heartbeat reclassifies the card as zombie.
+    advance(20_000)
+
+    expect(maps.chats.size).toBe(0)
+    expect(maps.baseTurnSeqs.has('cA')).toBe(false)
+    expect(maps.chatRunningSubagents.has('cA')).toBe(false)
+    // CRITICAL invariant: zombie close must NOT clear pendingSyncEchoes.
+    // The dedup map's TTL eviction (maybeEvict) reaps it later.
+    expect(maps.pendingSyncEchoes.has('cA:fake')).toBe(true)
+  })
+
+  it("'zombie' path also force-closes running sub-agents (sync registry drained)", () => {
+    const { driver, advance } = harness({ maxIdleMs: 5_000 })
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('cA'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'sa1', firstPromptText: 'work' }, 'cA')
+    expect(maps.chats.size).toBe(1)
+
+    // Idle past maxIdleMs without ever reporting sub_agent_turn_end.
+    advance(20_000)
+
+    expect(maps.chats.size).toBe(0)
+    // Issue #399: sync registry must be drained even when sub-agents
+    // never reported their own turn_end.
+    expect(maps.chatRunningSubagents.has('cA')).toBe(false)
+  })
+
+  it("'stalled' path (Gap-8 deferred-completion timeout): same convergence", () => {
+    const { driver, advance } = harness({
+      maxIdleMs: 999_999, // disable zombie ceiling so we hit the stalled branch
+      deferredCompletionTimeoutMs: 5_000,
+    })
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('cA'), null)
+    // Spawn a background sub-agent so parent turn_end defers instead of
+    // closing immediately.
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      'cA',
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'sa1', firstPromptText: 'bg' }, 'cA')
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, 'cA')
+    // After parent turn_end: card alive in pendingCompletion.
+    expect(maps.chats.size).toBe(1)
+
+    // Sub-agent never reports done; advance past the deferred timeout so
+    // the heartbeat's stalled-cards branch fires.
+    advance(15_000)
+
+    expect(maps.chats.size).toBe(0)
+    expect(maps.baseTurnSeqs.has('cA')).toBe(false)
+    expect(maps.chatRunningSubagents.has('cA')).toBe(false)
+  })
+
+  it('all three paths fire onTurnComplete callback exactly once', () => {
+    // The completion callback is the externally-visible side-effect that
+    // gates everything downstream (Stop hook, summary writer). Every
+    // close path must fire it; the unified path makes that automatic
+    // because the cleanup tail in completeTurnFully gates on
+    // completionFired.
+    const calls: string[] = []
+    const opts = {
+      onTurnComplete: (a: { turnKey: string }) => {
+        calls.push(a.turnKey)
+      },
+    }
+    let now = 1000
+    const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+    let nextRef = 0
+    const driver = createProgressDriver({
+      emit: () => {},
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      initialDelayMs: 0,
+      heartbeatMs: 1_000,
+      maxIdleMs: 5_000,
+      deferredCompletionTimeoutMs: 5_000,
+      now: () => now,
+      setTimeout: (fn, ms) => {
+        const ref = nextRef++
+        timers.push({ fireAt: now + ms, fn, ref })
+        return { ref }
+      },
+      clearTimeout: (h) => {
+        const ref = (h as { ref: number }).ref
+        const idx = timers.findIndex((t) => t.ref === ref)
+        if (idx !== -1) timers.splice(idx, 1)
+      },
+      setInterval: (fn, ms) => {
+        const ref = nextRef++
+        timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+        return { ref }
+      },
+      clearInterval: (h) => {
+        const ref = (h as { ref: number }).ref
+        const idx = timers.findIndex((t) => t.ref === ref)
+        if (idx !== -1) timers.splice(idx, 1)
+      },
+      ...opts,
+    })
+    const advance = (ms: number): void => {
+      now += ms
+      for (;;) {
+        timers.sort((a, b) => a.fireAt - b.fireAt)
+        const next = timers[0]
+        if (!next || next.fireAt > now) break
+        if (next.repeat != null) {
+          next.fireAt += next.repeat
+          next.fn()
+        } else {
+          timers.shift()
+          next.fn()
+        }
+      }
+    }
+
+    // turn-end
+    driver.ingest(enqueue('cA'), null)
+    driver.ingest({ kind: 'turn_end', durationMs: 10 }, 'cA')
+    // zombie
+    driver.ingest(enqueue('cB'), null)
+    advance(20_000)
+    // stalled (after time has advanced to satisfy the deferred timeout)
+    driver.ingest(enqueue('cC'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      'cC',
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'sa', firstPromptText: 'bg' }, 'cC')
+    driver.ingest({ kind: 'turn_end', durationMs: 10 }, 'cC')
+    advance(20_000)
+
+    // Each chat got exactly one completion callback.
+    const byChat = new Map<string, number>()
+    for (const tk of calls) {
+      const chat = tk.split(':')[0]
+      byChat.set(chat, (byChat.get(chat) ?? 0) + 1)
+    }
+    expect(byChat.get('cA')).toBe(1)
+    expect(byChat.get('cB')).toBe(1)
+    expect(byChat.get('cC')).toBe(1)
+  })
+})

package/telegram-plugin/tests/progress-card-cross-turn.test.ts

@@ -0,0 +1,258 @@
+/**
+ * Tests for issue #334 — cross-turn sub-agent visibility.
+ *
+ * A background sub-agent dispatched in turn N (via Agent({run_in_background:true}))
+ * must remain visible on the new progress card that appears when turn N+1 starts.
+ */
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import type { SessionEvent } from '../session-tail.js'
+
+let nextMsgId = 100
+
+function harness(
+  initialDelayMs = 0,
+  opts: { coldSubAgentThresholdMs?: number; heartbeatMs?: number } = {},
+) {
+  let now = 1000
+  const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+  let nextRef = 0
+  const emits: Array<{ chatId: string; threadId?: string; turnKey: string; html: string; done: boolean }> = []
+
+  const driver = createProgressDriver({
+    emit: (a) => emits.push(a),
+    minIntervalMs: 0,
+    coalesceMs: 0,
+    initialDelayMs,
+    coldSubAgentThresholdMs: opts.coldSubAgentThresholdMs,
+    heartbeatMs: opts.heartbeatMs,
+    now: () => now,
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+  })
+
+  const advance = (ms: number): void => {
+    now += ms
+    for (;;) {
+      timers.sort((a, b) => a.fireAt - b.fireAt)
+      const next = timers[0]
+      if (!next || next.fireAt > now) break
+      if (next.repeat != null) {
+        next.fireAt += next.repeat
+        next.fn()
+      } else {
+        timers.shift()
+        next.fn()
+      }
+    }
+  }
+
+  return { driver, emits, advance }
+}
+
+function enqueue(chatId: string, text = 'hi'): SessionEvent {
+  return {
+    kind: 'enqueue',
+    chatId,
+    messageId: String(nextMsgId++),
+    threadId: null,
+    rawContent: `<channel chat_id="${chatId}">${text}</channel>`,
+  }
+}
+
+describe('cross-turn sub-agent visibility (#334)', () => {
+  it('Test 1: closeZombie on turn-1 force-close removes sub-agent from registry (fix #399)', () => {
+    // When turn 2 starts while turn 1 has a pending background sub-agent,
+    // the ingest enqueue path calls closeZombie on turn 1's card. closeZombie
+    // explicitly abandons all running sub-agents (marks them done for display),
+    // and — after fix #399 — also removes them from chatRunningSubagents.
+    // Therefore turn 2 starts clean (no carry-over of abandoned agents).
+    const { driver } = harness()
+
+    // Turn 1: dispatch a background sub-agent, then turn ends.
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'bg-agent', firstPromptText: 'do work' }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // Turn 2 starts — triggers closeZombie on turn 1 → removes bg-agent from registry.
+    driver.startTurn({ chatId: 'c1', userText: 'new prompt' })
+
+    const turn2State = driver.peek('c1', undefined)
+    expect(turn2State).toBeDefined()
+    // bg-agent was abandoned by closeZombie; it must NOT carry over into turn 2.
+    expect(turn2State!.subAgents.has('bg-agent')).toBe(false)
+  })
+
+  it('Test 2: sub-agent finishing naturally before new turn does not appear on turn 2', () => {
+    // When a sub-agent finishes via sub_agent_turn_end (natural completion),
+    // it is removed from chatRunningSubagents by the ingest sync (fix #399
+    // also keeps this path correct). Turn 2 starts clean.
+    const { driver } = harness()
+
+    // Turn 1: dispatch background sub-agent.
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'bg-agent', firstPromptText: 'do work' }, 'c1')
+    // Sub-agent finishes naturally before turn 2 starts.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'bg-agent', durationMs: 5000 }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // Turn 2 starts.
+    driver.startTurn({ chatId: 'c1', userText: 'next prompt' })
+
+    const turn2State = driver.peek('c1', undefined)
+    expect(turn2State).toBeDefined()
+    // bg-agent finished before turn 2 — must NOT appear.
+    expect(turn2State!.subAgents.has('bg-agent')).toBe(false)
+  })
+
+  it('Test 3: foreground sub-agent (completes mid-turn 1) does NOT appear on turn 2', () => {
+    const { driver } = harness()
+
+    // Turn 1: foreground sub-agent — starts and finishes before turn ends.
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'fg-agent', firstPromptText: 'quick task' }, 'c1')
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'fg-agent', durationMs: 200 }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 800 }, 'c1')
+
+    // Turn 2 starts.
+    driver.startTurn({ chatId: 'c1', userText: 'next prompt' })
+
+    const turn2State = driver.peek('c1', undefined)
+    expect(turn2State).toBeDefined()
+    // Foreground sub-agent completed in turn 1 — must NOT bleed into turn 2.
+    expect(turn2State!.subAgents.has('fg-agent')).toBe(false)
+  })
+
+  it('multiple background sub-agents: closeZombie removes all from registry (fix #399)', () => {
+    // When closeZombie abandons all running sub-agents, they are all removed
+    // from chatRunningSubagents. Turn 2 starts with an empty sub-agent map.
+    const { driver } = harness()
+
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'bg1', firstPromptText: 'task 1' }, 'c1')
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'bg2', firstPromptText: 'task 2' }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // New turn triggers closeZombie → all running agents marked done → removed from registry.
+    driver.startTurn({ chatId: 'c1', userText: 'turn 2' })
+
+    const state = driver.peek('c1', undefined)
+    // Both abandoned agents must NOT carry over.
+    expect(state!.subAgents.has('bg1')).toBe(false)
+    expect(state!.subAgents.has('bg2')).toBe(false)
+  })
+
+  it('different chats do not cross-contaminate', () => {
+    const { driver } = harness()
+
+    // Chat A has a background sub-agent.
+    driver.ingest(enqueue('chatA'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'agentA', firstPromptText: 'A' }, 'chatA')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'chatA')
+
+    // Chat B starts a new turn (no sub-agents in chat B).
+    driver.startTurn({ chatId: 'chatB', userText: 'hello' })
+
+    const stateB = driver.peek('chatB', undefined)
+    expect(stateB!.subAgents.has('agentA')).toBe(false)
+    expect(stateB!.subAgents.size).toBe(0)
+  })
+
+  it('cold-jsonl-synth path syncs registry: turn 2 does NOT inherit cold-synth-terminated agent (fix #399)', () => {
+    // Forensic case from the live klanker bug: sub-agent ada7c3d07c28158f5
+    // hit its turn limit mid-tool-call and never wrote system.turn_duration.
+    // The cold-jsonl-synth heartbeat path (Gap 4 #313) marks it done
+    // synthetically. BEFORE fix #399 the registry was never synced from
+    // this path, so the agent appeared as a phantom on every subsequent
+    // turn's card. AFTER fix #399 the registry is synced and turn 2 is clean.
+    const { driver, advance } = harness(0, { coldSubAgentThresholdMs: 30_000, heartbeatMs: 5_000 })
+
+    // Turn 1: dispatch background sub-agent, parent turn ends → pendingCompletion=true
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'cold-agent', firstPromptText: 'long task' }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // Sub-agent goes cold (no events for > coldSubAgentThresholdMs).
+    // Heartbeat ticks fire repeatedly; once lastEventAt is older than the
+    // threshold, the cold-jsonl-synth path runs and synthesises sub_agent_turn_end.
+    advance(35_000)
+
+    // Turn 2 starts in the same chat. WITHOUT #399's fix, cold-agent would
+    // re-seed into turn 2's PerChatState.subAgents (the bug). WITH the fix,
+    // syncChatRunningSubagents fired from the cold-synth path and removed it.
+    driver.startTurn({ chatId: 'c1', userText: 'turn 2' })
+
+    const turn2State = driver.peek('c1', undefined)
+    expect(turn2State).toBeDefined()
+    expect(turn2State!.subAgents.has('cold-agent')).toBe(false)
+  })
+
+  it('counter-test: still-running background sub-agent DOES carry over (preserves #334)', () => {
+    // The carry-over feature from #334 must continue to work for legitimate
+    // still-running sub-agents. If syncChatRunningSubagents over-removes,
+    // this test catches the regression. Asserts:
+    //   1. A bg sub-agent that started in turn 1 and never went terminal
+    //   2. After turn 2 starts (closeZombie fires on turn 1's card), the
+    //      sub-agent is correctly REMOVED (closeZombie marks it done)
+    // Since closeZombie is the post-turn-1 cleanup path, "still running
+    // across turns" actually means "running while turn 1 is in pendingCompletion
+    // BEFORE turn 2 enqueues". The carry-over visibility happens during the
+    // pendingCompletion window — verified here by peeking BEFORE turn 2.
+    const { driver } = harness()
+
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'still-running', firstPromptText: 'long task' }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // During pendingCompletion the sub-agent is visible on the card.
+    const duringPending = driver.peek('c1', undefined)
+    expect(duringPending).toBeDefined()
+    expect(duringPending!.subAgents.has('still-running')).toBe(true)
+    expect(duringPending!.subAgents.get('still-running')?.state).toBe('running')
+  })
+
+  it('sub-agent finishes naturally between turns: turn 3 starts clean', () => {
+    // Verifies that a sub-agent finishing via sub_agent_turn_end (natural
+    // completion via the ingest path) is removed from chatRunningSubagents
+    // so subsequent turns do not see it.
+    const { driver } = harness()
+
+    // Turn 1: background sub-agent dispatched.
+    driver.ingest(enqueue('c1'), null)
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'bg1', firstPromptText: 'shared?' }, 'c1')
+    driver.ingest({ kind: 'turn_end', durationMs: 500 }, 'c1')
+
+    // Sub-agent finishes naturally BEFORE turn 2 starts.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'bg1', durationMs: 3000 }, 'c1')
+
+    // Turn 2 starts — bg1 already finished, so registry is empty.
+    driver.startTurn({ chatId: 'c1', userText: 'turn 2' })
+    expect(driver.peek('c1', undefined)!.subAgents.has('bg1')).toBe(false)
+
+    driver.ingest({ kind: 'turn_end', durationMs: 1000 }, 'c1')
+
+    // Turn 3: the finished sub-agent must NOT appear.
+    driver.startTurn({ chatId: 'c1', userText: 'turn 3' })
+    const stateT3 = driver.peek('c1', undefined)
+    expect(stateT3).toBeDefined()
+    expect(stateT3!.subAgents.has('bg1')).toBe(false)
+  })
+})

package/telegram-plugin/tests/progress-card-dispose-preservepending.test.ts

@@ -0,0 +1,81 @@
+/**
+ * PR-C2 — `dispose({ preservePending: true })` must NOT remove chats
+ * whose `pendingCompletion === true`.
+ *
+ * Regression: commit 4c0186d introduced a dispose() that wiped all
+ * in-flight card state on every bridge disconnect. The selective
+ * dispose path was added to keep cards with running background
+ * sub-agents alive across the disconnect/reconnect cycle.
+ *
+ * fails when: dispose's preservePending branch unconditionally clears
+ * `chats`, OR forgets to leave the heartbeat running while a pending
+ * chat survives.
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('PR-C2: dispose({ preservePending: true })', () => {
+  it('chat with pendingCompletion survives dispose; heartbeat-driven completion still fires after a "reconnect"', () => {
+    const completions: string[] = []
+    const { driver, advance } = makeHarness({
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      heartbeatMs: 1_000,
+      maxIdleMs: 999_999,
+      deferredCompletionTimeoutMs: 5_000,
+      promoteAfterMs: 999_999,
+      onTurnComplete: (s) => completions.push(s.turnKey),
+    })
+    const maps = driver._debugGetMaps!()
+    const CHAT = 'cA'
+
+    // Set up a turn with a background sub-agent so parent turn_end
+    // produces pendingCompletion=true.
+    driver.ingest(enqueue(CHAT), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, CHAT)
+
+    // Confirm pendingCompletion shape.
+    expect(maps.chats.size).toBe(1)
+    const csBefore = [...maps.chats.values()][0] as { pendingCompletion: boolean }
+    expect(csBefore.pendingCompletion).toBe(true)
+
+    // Bridge disconnect: dispose preserving pending.
+    driver.dispose!({ preservePending: true })
+
+    // Chat must survive.
+    expect(maps.chats.size).toBe(1)
+    const csAfter = [...maps.chats.values()][0] as { pendingCompletion: boolean }
+    expect(csAfter.pendingCompletion).toBe(true)
+
+    // Now simulate "bridge reconnect" — nothing to do at the driver level
+    // for that, but the heartbeat must still be wired so the deferred
+    // completion timeout eventually fires.
+    advance(15_000)
+
+    // Stalled-cards heartbeat branch should have closed the chat by now.
+    expect(maps.chats.size).toBe(0)
+    expect(completions.length).toBe(1)
+  })
+
+  it('chats WITHOUT pendingCompletion are dropped by preservePending dispose', () => {
+    const { driver } = makeHarness()
+    const maps = driver._debugGetMaps!()
+    driver.ingest(enqueue('cActive'), null)
+    expect(maps.chats.size).toBe(1)
+
+    driver.dispose!({ preservePending: true })
+    expect(maps.chats.size).toBe(0)
+  })
+})

package/telegram-plugin/tests/progress-card-draft-flag.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Pin the wiring for #354's PROGRESS_CARD_DRAFT_TRANSPORT env flag.
+ *
+ * Two regressions this guards against:
+ *
+ *   1. The flag drifting silently — someone refactors the progress-
+ *      card emit and forgets to thread isPrivateChat / sendMessageDraft
+ *      when the flag is on. Result: the card stays on the legacy edit
+ *      path even though the operator opted in.
+ *
+ *   2. The flag turning on by default before the spike unknowns are
+ *      validated. Default-OFF is load-bearing: until we know drafts
+ *      can be pinned and survive bot crashes, the legacy path is the
+ *      safe one.
+ *
+ * Source-level pinning rather than behavioural — the gateway emit
+ * lives inside the bot startup wiring and is hard to drive in
+ * isolation. The contract here is the literal env-var check + the
+ * fact that draft deps are conditional on it.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('progress-card draft transport flag (#354)', () => {
+  it('is gated behind PROGRESS_CARD_DRAFT_TRANSPORT=1 (default OFF)', () => {
+    // The flag check must be an explicit `=== '1'` not a truthy check
+    // — `process.env.X === '1'` is the project convention, and a
+    // truthy check would mis-fire on `=0` or `=false`.
+    expect(gatewaySrc).toMatch(
+      /process\.env\.PROGRESS_CARD_DRAFT_TRANSPORT\s*===\s*['"]1['"]/,
+    )
+  })
+
+  it('only enables draft when the chat is a DM (no threads, isDmChatId)', () => {
+    // Drafts don't support forum topics. The flag-check block must
+    // gate on isDmChatId(chatId) and threadId == null — otherwise a
+    // forum-topic message would be sent via draft and Telegram would
+    // reject with DRAFT_CHAT_UNSUPPORTED.
+    const block = extractDraftBlock(gatewaySrc)
+    expect(block).toMatch(/isDmChatId\(chatId\)/)
+    expect(block).toMatch(/threadId\s*==\s*null/)
+  })
+
+  it('passes both isPrivateChat AND sendMessageDraft when eligible', () => {
+    // Without sendMessageDraft, stream-reply-handler resolves transport
+    // to 'message' (line 432: `isForumTopic || deps.sendMessageDraft == null`).
+    // Both deps must be threaded together for the draft path to fire.
+    const block = extractDraftBlock(gatewaySrc)
+    expect(block).toMatch(/isPrivateChat:\s*true/)
+    expect(block).toMatch(/sendMessageDraft:\s*sendMessageDraftFn/)
+  })
+
+  it('documents the spike unknowns from #354 inline so an operator can validate', () => {
+    // The flag exists because pinning + crash behavior are unverified.
+    // The block comment must call out both so a future contributor
+    // doesn't flip the default to ON without doing the spike first.
+    const block = extractDraftBlock(gatewaySrc)
+    expect(block.toLowerCase()).toMatch(/pin/)
+    expect(block.toLowerCase()).toMatch(/spike|unknown/)
+  })
+})
+
+/** Pull the #354 spike block out of gateway.ts for source-level assertions. */
+function extractDraftBlock(src: string): string {
+  // The block starts at the spike comment marker and ends at the next
+  // `handleStreamReply(` invocation. Big enough to span the gate +
+  // the conditional draft-deps spread.
+  const start = src.indexOf('// #354 spike')
+  expect(start, '#354 spike block not found in gateway.ts').toBeGreaterThan(0)
+  const end = src.indexOf(').then', start)
+  expect(end, '#354 spike block end not found').toBeGreaterThan(start)
+  return src.slice(start, end)
+}