switchroom 0.7.15 → 0.10.0

package/telegram-plugin/progress-card-driver.ts

@@ -1,2886 +0,0 @@
-/**
- * Driver that owns per-chat progress-card state and controls when to emit
- * an `update` call to the outer world (typically a handleStreamReply or a
- * test spy).
- *
- * Cadence rules:
- *   - Fire IMMEDIATELY on state transitions (tool start, tool end, stage
- *     change, enqueue). This is the key anti-flicker property — each event
- *     renders exactly once at the moment of semantic change.
- *   - Coalesce bursts: if multiple events land within `coalesceMs`, only
- *     the last render actually fires (a single setTimeout collapses them).
- *   - Hard floor: never emit faster than `minIntervalMs` to respect
- *     Telegram's editMessageText rate budget.
- *
- * Pure in-process state. No IO; the outer `emit` callback does the send.
- */
-
-import type { SessionEvent } from './session-tail.js'
-import {
-  hasAnyRunningSubAgent,
-  initialState,
-  reduce,
-  render,
-  type ProgressCardState,
-  type TaskNum,
-  type SubAgentState,
-} from './progress-card.js'
-import { isTelegramReplyTool } from './tool-names.js'
-import { emitCardEvent } from './card-event-log.js'
-import { createHash } from 'crypto'
-import {
-  applyCapped as fleetApplyCapped,
-  applyToolResult as fleetApplyToolResult,
-  applyToolUse as fleetApplyToolUse,
-  applyTurnEnd as fleetApplyTurnEnd,
-  createFleetMember,
-  hasLiveBackground,
-  markStuck as fleetMarkStuck,
-  roleFromDispatch,
-  type FleetMember,
-} from './fleet-state.js'
-
-/**
- * Classification of a Telegram API error for failure-escalation purposes.
- *
- * - `permanent_4xx`: 4xx error that won't resolve itself (message deleted,
- *   bot blocked, etc.). After K consecutive such failures the card is marked
- *   terminal and all further edits are suppressed.
- * - `transient`: network/5xx error — retryable; does NOT count toward the
- *   permanent-failure threshold.
- * - `benign`: "message is not modified" — the edit had no effect because the
- *   text was already identical. Not a failure at all; counter must not advance.
- */
-export type ApiFailureKind = 'permanent_4xx' | 'transient' | 'benign'
-
-/**
- * Reason a per-chat card is being closed. Used by the unified
- * `closePerChat` helper to drive the small set of behavioural deltas
- * between paths (sub-agent force-close, stalled-render flag).
- *
- *   - 'turn-end' : normal completion — no in-flight sub-agents.
- *   - 'zombie'   : abandonment via heartbeat maxIdle ceiling or
- *                  new-enqueue force-close.
- *   - 'stalled'  : Gap-8 deferred-completion timeout expired.
- */
-export type CloseReason = 'turn-end' | 'zombie' | 'stalled'
-
-/**
- * Failure descriptor reported back to the driver after an async emit fails.
- * The outer layer (server.ts) inspects the raw Telegram error and classifies
- * it before calling `reportApiFailure`.
- */
-export interface ApiFailureInfo {
-  /** HTTP-level error code from Telegram (400, 403, 404, 500, …). */
-  code: number
-  /** Telegram's `description` field, e.g. "Forbidden: bot was blocked by the user". */
-  description: string
-  kind: ApiFailureKind
-}
-
-export interface ProgressDriverConfig {
-  /**
-   * Emit rendered HTML for the given chat+thread. Caller owns the send.
-   *
-   * `isFirstEmit` is true exactly once per turn — on the very first flush
-   * that creates the Telegram message. The caller can use this signal to
-   * pin the new message: after this call resolves, the message_id will be
-   * available in the caller's draft-stream handle.
-   *
-   * `replyToMessageId` is set only on the first emit (when `isFirstEmit`
-   * is true) and only when the turn was started with a source message_id
-   * (via `startTurn({ replyToMessageId })`). The caller should pass this
-   * as `reply_parameters` on the initial `sendMessage` so the progress
-   * card is a tappable reply to the user's original message. Edits
-   * (subsequent emits) must NOT carry reply_parameters — Telegram rejects
-   * it on editMessageText.
-   */
-  emit: (args: {
-    chatId: string
-    threadId?: string
-    /** Unique key for this turn (chatId:threadId:seq). Use for pin/unpin tracking. */
-    turnKey: string
-    html: string
-    done: boolean
-    /** True only on the first flush for this turn (message creation). */
-    isFirstEmit: boolean
-    /**
-     * Set on the first emit only (isFirstEmit=true) when the turn was
-     * started via startTurn({ replyToMessageId }). Pass as
-     * reply_parameters.message_id on the initial sendMessage.
-     */
-    replyToMessageId?: number
-    /**
-     * Per-agent card identity. Absent for parent-card emits (the
-     * gateway treats absence as the parent sentinel `__parent__`).
-     * Retained for caller compatibility post-P4 cutover; the two-zone
-     * renderer no longer emits per-sub-agent cards.
-     */
-    agentId?: string
-  }) => void
-  /**
-   * Optional callback fired once per turn immediately after the final
-   * render on `turn_end`. Receives a compact, one-line plain-text
-   * summary suitable for the session-handoff continuity line. The outer
-   * layer typically pipes this into `writeLastTurnSummary(agentDir, …)`
-   * so that a session restart can show "↩️ Picked up — <summary>"
-   * even if the Stop-hook summarizer didn't run.
-   */
-  onTurnEnd?: (summary: string) => void
-  /**
-   * Fired once per turn when `turn_end` is processed, with full chat
-   * context. Use this for per-chat post-completion work: unpin the card,
-   * send a completion summary to the main chat, etc.
-   *
-   * Fires BEFORE the per-chat state is deleted, so `summary` is still
-   * accessible. The caller must NOT re-enter the driver from this callback.
-   */
-  onTurnComplete?: (args: {
-    chatId: string
-    threadId?: string
-    /** Unique key for this turn (chatId:threadId:seq). Use for pin/unpin tracking. */
-    turnKey: string
-    summary: string
-    taskIndex: number
-    taskTotal: number
-  }) => void
-  /**
-   * Fired when a turn ends with no reply sent (silentEnd=true). The outer
-   * layer can write a state file so the Stop hook can block the session and
-   * re-prompt the agent. The callback returns `{ suppressed: true }` when the
-   * retry is allowed (retryCount was 0) — in that case the driver will
-   * re-render the final card WITHOUT the "🙊 Ended without reply" warning so
-   * the user doesn't see a false-positive before the retry lands.
-   *
-   * On the second silent-end (retryCount exhausted) the callback returns
-   * `{ suppressed: false }` and the warning card renders as normal.
-   *
-   * Not fired for autonomous turns (wasAutonomous=true) — those intentionally
-   * produce no user-visible reply.
-   */
-  onSilentEnd?: (args: {
-    chatId: string
-    threadId?: string
-    turnKey: string
-  }) => { suppressed: boolean } | void
-  /** Min ms between edits for a given chat+thread. Default 500. */
-  minIntervalMs?: number
-  /** Coalesce window — burst events within this land as one render. Default 400. */
-  coalesceMs?: number
-  /** `Date.now` override for tests. */
-  now?: () => number
-  /** `setTimeout` override for tests. */
-  setTimeout?: (fn: () => void, ms: number) => { ref: unknown }
-  clearTimeout?: (ref: unknown) => void
-  /** `setInterval` override for tests (used by the heartbeat). */
-  setInterval?: (fn: () => void, ms: number) => { ref: unknown }
-  clearInterval?: (ref: unknown) => void
-  /**
-   * Heartbeat cadence for the no-events-flowing re-render. When a turn
-   * has settled into a long-running tool call (e.g. a sub-agent that
-   * emits no session-JSONL events for minutes), the elapsed-time counter
-   * in the card header never visibly ticks because no event fires a
-   * re-render. The heartbeat forces a flush every `heartbeatMs` while
-   * any chat has a running turn. Default 5000. Set to 0 to disable.
-   */
-  heartbeatMs?: number
-  /**
-   * Multi-agent rate-limit guardrail (design §4.4). Telegram caps edits
-   * at ~20/min/chat. With N parallel sub-agents emitting bursty events
-   * the default 400ms coalesce + 500ms floor can exceed the cap. When
-   * we observe more than `editBudgetThreshold` edits in the trailing
-   * 60s for a chat, the coalesce window expands to `editBudgetCoalesceMs`
-   * until the rate drops back. Heartbeat is also suppressed while the
-   * budget is hot.
-   *
-   * Defaults: threshold=18, coalesce window when hot=3000ms.
-   */
-  editBudgetThreshold?: number
-  editBudgetCoalesceMs?: number
-  /**
-   * Zombie-card ceiling. If a chat's `lastEventAt` is older than this
-   * many ms, the heartbeat loop force-closes the card (flush done,
-   * onTurnComplete, delete from chats). This is the backstop for cards
-   * orphaned by a missed `turn_end` line or an enqueue echo-drop that
-   * routed events to a different card — without it, the heartbeat
-   * would re-render a stale card forever (50+ minute ghost cards).
-   *
-   * Default 30 minutes. Set to 0 to disable entirely (not recommended
-   * outside tests).
-   */
-  maxIdleMs?: number
-  /**
-   * Suppress the progress card for fast turns. The first emit is
-   * deferred by this many ms after startTurn. If `turn_end` arrives
-   * before the timer fires (and isFirstEmit is still true), no card
-   * is ever shown — the user only sees the final reply.
-   *
-   * The card can be promoted out of suppression early when a sub-agent
-   * starts (see `promoteOnSubAgent`) — long-running tool work and
-   * background dispatches stay visible without waiting the full delay.
-   *
-   * Default 45000 (45 seconds, #842). Set to 0 to disable.
-   */
-  initialDelayMs?: number
-  /**
-   * First-render delay (ms) override for explicit background sub-agent
-   * dispatches (#842). When the agent calls
-   * `Agent({ run_in_background: true })`, the card is promoted out of
-   * the suppression window using this delay instead of `initialDelayMs`.
-   * Default 0 (immediate render — backgrounded work should be visible
-   * right away).
-   *
-   * Implementation: at `tool_use` ingest time the driver detects the
-   * background flag (existing `cs.backgroundParentToolUseIds` book-
-   * keeping). If `initialDelayMsBackground` is 0 the card promotes
-   * immediately via `promoteFirstEmit`. If positive, the deferred timer
-   * is rescheduled to fire that many ms from turn start (or now, if
-   * already past) — but only when shorter than what's currently
-   * scheduled. Never lengthens an in-flight delay.
-   */
-  initialDelayMsBackground?: number
-  /**
-   * Promote the first emit immediately when a sub-agent transitions to
-   * running during the suppression window, when the watcher fires
-   * `onSubAgentStall`, or when `startTurn` carries over running
-   * sub-agents from a prior turn (#334 carry-over). The card jumps
-   * straight to visible instead of waiting for `initialDelayMs`.
-   *
-   * Fast-turn suppression (`turn_end` before the card has emitted) is
-   * unchanged — it short-circuits in `flush()` regardless of this flag.
-   *
-   * Default true. Set to false to disable promotion entirely (the card
-   * will only appear after `initialDelayMs` elapses, even when sub-agents
-   * are dispatched mid-turn).
-   */
-  promoteOnSubAgent?: boolean
-  /**
-   * Promote the card out of initial-delay suppression once the agent has
-   * issued this many parent-side tool calls in the suppression window.
-   * Closes #478 — the user sees no progress card for the first 30s of a
-   * substantial turn that does parent-side work (Read/Grep/Bash/Edit)
-   * but never dispatches a sub-agent.
-   *
-   * Symmetric to `promoteOnSubAgent`. **Default 0 (disabled, #553 PR 4):**
-   * under the v2 contract tools alone never trigger the card — only
-   * sub-agents or `elapsed >= 60s`. Values of 0 or non-finite (Infinity)
-   * are treated as "never promote on tool count". Set to a positive
-   * integer (e.g. 3) to opt back in to the pre-v2 behaviour.
-   *
-   * Fast-turn suppression in `flush()` is unchanged — if the turn
-   * ends before promotion, the card still skips the emit.
-   */
-  promoteOnParentToolCount?: number
-  /**
-   * Time-based first-emit promotion (#553 F3): if the turn has been
-   * running this long with no tool/sub-agent that already triggered
-   * promotion, force the card to emit. Without this, single- or two-
-   * tool turns that take 5–30s never cross any existing promotion
-   * threshold and the card stays suppressed until `initialDelayMs`,
-   * at which point fast-turn-suppression cancels it on `turn_end`.
-   *
-   * Symmetric to `promoteOnParentToolCount`: pure additive promotion,
-   * never delays an emit that would otherwise fire. Fast-turn
-   * suppression in `flush()` is unchanged — sub-`promoteAfterMs` turns
-   * still skip the card.
-   *
-   * **Default 0 (disabled, #553 PR 4).** The PR #570 5s time-promote was
-   * a stop-gap when `initialDelayMs` defaulted to 30s; with the new
-   * 60s `initialDelayMs` and the sub-agent promote intact, time-based
-   * promotion is no longer needed. `ensureTimePromoteScheduled` no-ops
-   * when this is 0 so the timer never schedules. Set to a positive
-   * value to opt back in to the pre-v2 behaviour.
-   */
-  promoteAfterMs?: number
-  /**
-   * Number of consecutive 4xx Telegram API failures on card edits before
-   * the card is marked terminal and all further edits are suppressed for
-   * this turn. Transient (5xx/network) errors and "message is not modified"
-   * do NOT count toward this threshold. A single success resets the counter.
-   *
-   * Default 3. Set to 0 to disable the escalation mechanism entirely.
-   */
-  maxConsecutive4xx?: number
-  /**
-   * Gap 3 (orphan promotion): how long a `PendingAgentSpawn` must be
-   * outstanding before the heartbeat promotes it to a synthesised
-   * sub-agent row (state='running'). Gives the sub-agent JSONL watcher a
-   * chance to deliver the real `sub_agent_started` event first.
-   *
-   * Default 5000 (5 seconds). Set to 0 to disable promotion entirely.
-   */
-  orphanPromotionMs?: number
-  /**
-   * Gap 4 (cold-JSONL detection): when a running sub-agent's last event
-   * is older than this threshold, the heartbeat synthesises a
-   * `sub_agent_turn_end` for it so the deferred-completion path can
-   * proceed (avoids the card staying pinned forever on a dead watcher).
-   *
-   * Default 30000 (30 seconds). Set to 0 to disable the synthetic close.
-   */
-  coldSubAgentThresholdMs?: number
-  /**
-   * Gap 8 (decoupled render and unpin): after `turn_end` arrives while
-   * sub-agents are still running, this is the maximum ms to wait before
-   * force-closing the card with a "stalled — forced close" header and
-   * calling `onTurnComplete`. This is separate from `maxIdleMs` (which
-   * watches for absence of ALL events) — this timeout starts specifically
-   * on parent `turn_end` and fires regardless of sub-agent activity.
-   *
-   * Default 180000 (3 minutes). Set to 0 to disable.
-   */
-  deferredCompletionTimeoutMs?: number
-  /**
-   * Fix #314 — elapsed-ticker interval for silent sub-agent gaps.
-   *
-   * While at least one sub-agent is in `state='running'`, the parent card
-   * only re-renders when an event changes the HTML (tool start/end, stage
-   * change). During silent stretches between tool calls the elapsed counter
-   * freezes — the diff guard suppresses edits when only the timestamp
-   * advances. This interval forces a render (bypassing that guard) every N ms
-   * so the elapsed counter visibly ticks even when the sub-agent is quietly
-   * thinking or waiting for I/O.
-   *
-   * 10 s was chosen as a balance: short enough that the counter advances
-   * at human-perceptible speed (users notice a 15+ second freeze), long
-   * enough to stay well under Telegram's ~20 edits/minute budget even when
-   * multiple cards are active in parallel.
-   *
-   * Default 10000. Set to 0 to disable the elapsed-ticker path entirely.
-   */
-  subAgentTickIntervalMs?: number
-}
-
-/**
- * Issue #399: Sync the per-chat running-sub-agent registry after any state
- * transition that may have moved agents to a terminal state.
- *
- * Factored out from the inline block inside `ingest` so it can be called
- * from three paths that can transition agents to done/failed without going
- * through the normal ingest post-reduce step:
- *   1. ingest post-reduce (existing call site, refactored)
- *   2. cold-jsonl-synth path (Gap-4, heartbeat)
- *   3. closeZombie direct mutation path
- *   4. deferred-completion-timeout force-close (Gap-8, heartbeat)
- */
-export function syncChatRunningSubagents(
-  prev: ProgressCardState,
-  next: ProgressCardState,
-  cBaseKey: string,
-  chatRunningSubagents: Map<string, Map<string, SubAgentState>>,
-): { newRunningAppeared: boolean } {
-  if (prev.subAgents === next.subAgents) return { newRunningAppeared: false }
-  let newRunningAppeared = false
-  // Check for new or newly-running entries (sub_agent_started path).
-  for (const [agentId, sa] of next.subAgents) {
-    if (sa.state === 'running') {
-      const prevSa = prev.subAgents.get(agentId)
-      if (prevSa == null || prevSa.state !== 'running') {
-        // Newly running — register in chat-scoped registry.
-        let chatMap = chatRunningSubagents.get(cBaseKey)
-        if (chatMap == null) {
-          chatMap = new Map<string, SubAgentState>()
-          chatRunningSubagents.set(cBaseKey, chatMap)
-        }
-        chatMap.set(agentId, sa)
-        newRunningAppeared = true
-      }
-    } else if (sa.state === 'done' || sa.state === 'failed') {
-      // Terminal state — remove from chat registry if present.
-      chatRunningSubagents.get(cBaseKey)?.delete(agentId)
-    }
-  }
-  // Also handle entries that were removed from subAgents entirely
-  // (shouldn't happen normally but be defensive).
-  for (const agentId of prev.subAgents.keys()) {
-    if (!next.subAgents.has(agentId)) {
-      chatRunningSubagents.get(cBaseKey)?.delete(agentId)
-    }
-  }
-  return { newRunningAppeared }
-}
-
-/**
- * Compact one-line summary of a completed turn for the handoff sidecar.
- * Shape: `"<tool-count> tool[s], <duration> — <user-request>"`.
- * Falls back gracefully when fields are missing (empty items → "no tools";
- * no userRequest → just the stats prefix).
- */
-export function summariseTurn(state: ProgressCardState, now: number): string {
-  const toolCount = state.items.length
-  const toolLabel = toolCount === 1 ? '1 tool' : `${toolCount} tools`
-  const durSec = Math.max(0, Math.floor((now - state.turnStartedAt) / 1000))
-  const dur =
-    durSec >= 60
-      ? `${Math.floor(durSec / 60)}:${(durSec % 60).toString().padStart(2, '0')}`
-      : `${durSec}s`
-  const stats = toolCount === 0 ? `no tools, ${dur}` : `${toolLabel}, ${dur}`
-  const req = state.userRequest?.trim()
-  return req ? `${stats} — ${req}` : stats
-}
-
-interface PerChatState {
-  chatId: string
-  threadId?: string
-  /** Unique key for this turn: `chatId:threadId:seq`. Used as the chats-map key. */
-  turnKey: string
-  /** 1-based index of this card among all cards created for this chat:thread in this session. */
-  taskIndex: number
-  /** Total cards created for this chat:thread so far (snapshot at card creation). */
-  taskTotal: number
-  state: ProgressCardState
-  lastEmittedAt: number
-  lastEmittedHtml: string | null
-  pendingTimer: unknown
-  /** True until the very first flush fires for this turn. Cleared after first emit. */
-  isFirstEmit: boolean
-  /** Timer for the deferred first emit (initial-delay suppression). */
-  deferredFirstEmitTimer: unknown
-  /**
-   * #842: per-chat first-emit delay budget in ms. Initialised to
-   * `config.initialDelayMs`; lowered to `config.initialDelayMsBackground`
-   * the first time the parent dispatches an Agent/Task with
-   * `run_in_background: true`. Never increases. flush() reads this
-   * (instead of the closure-level `initialDelayMs`) when scheduling the
-   * deferred first-emit timer so the background bypass takes effect on
-   * the next scheduling pass.
-   */
-  effectiveInitialDelayMs: number
-  /**
-   * F3 fix (#553): timer for the time-based first-emit promotion.
-   * Scheduled on the first ingest event; fires after `promoteAfterMs`
-   * to force-promote turns that don't trip parent-tool-count or
-   * sub-agent thresholds (e.g. one long Bash). Cleared on
-   * `promoteFirstEmit` or turn end.
-   */
-  timePromoteTimer: unknown
-  /**
-   * The Telegram message_id of the user's original inbound message that
-   * triggered this turn. Set via startTurn({ replyToMessageId }). Passed
-   * as reply_parameters on the FIRST sendMessage only — edits must not
-   * carry it (Telegram rejects reply_parameters on editMessageText).
-   */
-  replyToMessageId?: number
-  /**
-   * Wall-clock ms of the last real session event routed to this card.
-   * Distinct from `lastEmittedAt`: the heartbeat ticks `lastEmittedAt`
-   * every cycle, but `lastEventAt` only advances when an actual event
-   * (enqueue, tool_use, tool_result, turn_end, sub_agent_*) lands on
-   * this chat state. The heartbeat uses it as a zombie ceiling — a
-   * card whose `lastEventAt` is older than `maxIdleMs` has been
-   * orphaned (turn_end missed by the session-tail, or an enqueue
-   * echo-drop routed events to a different card) and is force-closed
-   * so it can't tick forever.
-   */
-  lastEventAt: number
-  /**
-   * True once the parent turn has ended (via `turn_end` or
-   * `forceCompleteTurn`) BUT one or more sub-agents were still running
-   * at that moment. The card stays alive and keeps ticking so the
-   * running sub-agents remain visible. When the last running sub-agent
-   * transitions to done (via `sub_agent_turn_end` or parent's Agent
-   * `tool_result`), completion callbacks finally fire and the card is
-   * closed. Guards against duplicate completion firing (both turn_end
-   * and forceCompleteTurn can legitimately arrive).
-   */
-  pendingCompletion: boolean
-  /**
-   * Set to true the moment completion callbacks have fired, whether
-   * immediately (no in-flight sub-agents at turn_end) or deferred
-   * (after last sub-agent finished). Guards against double-firing if
-   * multiple completion signals race.
-   */
-  completionFired: boolean
-  /**
-   * Set to true when an external code path has assumed ownership of
-   * the pinned card message (e.g. turn-flush rewriting the card with
-   * the user-facing answer — see #654). Once true, `flush()`
-   * short-circuits at the top so the driver never edits the card
-   * again for this turn. The external owner is responsible for
-   * issuing the final edit/unpin via pinMgr.
-   */
-  cardTakenOver: boolean
-  /**
-   * Tracks consecutive Telegram 4xx failures on card edits. Once
-   * `terminal` is true, flush() and the heartbeat tick skip all edits
-   * for this card (message deleted / bot blocked / stale message_id).
-   *
-   * Resets automatically when a fresh turn starts (new PerChatState).
-   */
-  apiFailures: {
-    consecutive4xx: number
-    lastError: { code: number; description: string; timestamp: number } | null
-    terminal: boolean
-  }
-  /**
-   * Issue #132: did the agent call `reply` or `stream_reply` (under any
-   * MCP server-key prefix) at least once during this turn?
-   *
-   * Set true on the first matching `tool_use` event observed by `ingest()`.
-   * When the turn ends with this still false, the card renders the
-   * "🙊 Ended without reply" silent-end variant instead of "✅ Done" so the
-   * user can tell the difference between "agent acknowledged with text"
-   * and "agent ran tools and went mute". Resets implicitly with each new
-   * `PerChatState` (one per turn).
-   */
-  replyToolCalled: boolean
-  /**
-   * Issue #137: how many outbound replies actually landed in the chat
-   * this turn? Bumped by `ProgressDriver.recordOutboundDelivered()` from
-   * the gateway's executeReply / executeStreamReply success paths.
-   *
-   * Combined with `replyToolCalled` at turn-end, this distinguishes:
-   *   - both false              → silent-end (#132, "Ended without reply")
-   *   - replyToolCalled only    → reply attempted but never delivered
-   *                               (#137 — render a degraded variant
-   *                               distinct from silent-end so the user
-   *                               knows the agent TRIED)
-   *   - delivered>0             → real success
-   */
-  outboundDeliveredCount: number
-  /**
-   * Issue #259: true when the turn was started by an autonomous wakeup
-   * sentinel (`<<autonomous-loop>>` or `<<autonomous-loop-dynamic>>`).
-   * When set, the "🙊 Ended without reply" silent-end warning is
-   * suppressed — autonomous turns intentionally produce no user-visible
-   * reply and ending without one is entirely expected.
-   */
-  wasAutonomous: boolean
-  /**
-   * Set by prepareSilentEndSuppression when onSilentEnd returns
-   * { suppressed: true }. Causes flush() to render the final card without
-   * the "🙊 Ended without reply" header so no false-positive appears before
-   * the retry reply lands.
-   */
-  silentEndSuppressed: boolean
-  /**
-   * Idempotent guard for prepareSilentEndSuppression — ensures the
-   * onSilentEnd callback (which writes the Stop-hook state file) only
-   * fires once per turn even if multiple sites call into the helper.
-   */
-  silentEndPrepared: boolean
-  /**
-   * Gap 8 (decoupled render and unpin): set to the timestamp when parent
-   * `turn_end` landed while sub-agents were still running. Used by the
-   * heartbeat to enforce `deferredCompletionTimeoutMs`. Null until
-   * parent turn_end with in-flight sub-agents is observed.
-   */
-  parentTurnEndAt: number | null
-  /**
-   * Gap 8: true once the parent-done render (✅ Done header with sub-agents
-   * still visible) has been emitted. Prevents re-rendering the ✅ Done
-   * frame on every sub-agent event while deferred.
-   */
-  parentDoneRendered: boolean
-  /**
-   * Gap 3 (orphan promotion): set of toolUseIds from `pendingAgentSpawns`
-   * that have already been promoted to synthetic sub-agent rows. Guards
-   * against re-promotion on successive heartbeat ticks and against
-   * double-registration if a real `sub_agent_started` arrives later.
-   */
-  promotedSpawnIds: Set<string>
-  /**
-   * P0 of #662 — shadow fleet map updated alongside `state.subAgents` at
-   * every sub_agent_* event. Coexists with the legacy map; P1/P2/P3 build
-   * the v2 two-zone status card on this without disturbing the existing
-   * renderer. See fleet-state.ts for the pure transitions.
-   */
-  fleet: Map<string, FleetMember>
-  /**
-   * P2 of #662 — set of parent toolUseIds whose Agent/Task tool_use was
-   * dispatched with `input.run_in_background === true`. When the
-   * matching `sub_agent_started` correlates and writes
-   * `parentToolUseId` into the freshly-created subagent state, the
-   * fleet reducer flips that member's `status` from `running` to
-   * `background`. Entry stays around for the life of the turn so a
-   * reverse-race adoption (sub_agent_started arriving before tool_use)
-   * still matches.
-   */
-  backgroundParentToolUseIds: Set<string>
-  /**
-   * P2 of #662 / fixes #64 — set true when `completeTurnFully` was
-   * called but at least one fleet member was still in `status:
-   * 'background'` and not terminal. The chats-map entry is preserved
-   * (instead of deleted) and the original card stays pinned so updates
-   * can continue to land. When the last live background member reaches
-   * a terminal status, `finalizeBackgroundCarryIfReady` triggers the
-   * deferred completion.
-   */
-  backgroundCarry: boolean
-}
-
-export interface ProgressDriver {
-  /** Feed a session-tail event. Fires emit() as the cadence allows. */
-  ingest(event: SessionEvent, chatId: string | null, threadId?: string): void
-  /**
-   * Stop internal timers and clear driver state. Idempotent.
-   *
-   * When called with `{ preservePending: true }`, chats with
-   * `pendingCompletion === true` are preserved so their heartbeat and
-   * deferred-completion timeout continue firing after a bridge disconnect.
-   * Coalesce timers (`pendingTimer`, `deferredFirstEmitTimer`) on those
-   * preserved chats ARE cleared — they cannot safely emit into a finalized
-   * draft stream. Chats WITHOUT `pendingCompletion` are fully removed.
-   * The heartbeat is only stopped if no `pendingCompletion` chats remain.
-   *
-   * When called with no args or `{ preservePending: false }`, the existing
-   * wipe-everything behavior is retained for back-compat.
-   */
-  dispose?(opts?: { preservePending?: boolean }): void
-  /**
-   * Begin a new turn synchronously — called from the inbound-message
-   * handler the instant a user's message clears the gate, BEFORE any
-   * session-tail event arrives. Creates a fresh progress card state; the
-   * first visible render is gated by `initialDelayMs` (default 60s) so
-   * turns that finish before the delay produce no card at all and the
-   * user only sees the final reply.
-   *
-   * If a card is already active for this chat, it is force-closed (done=true,
-   * onTurnComplete fired) before the new card is created. Each call always
-   * produces an independent card with its own pin lifecycle.
-   */
-  startTurn(args: { chatId: string; threadId?: string; userText: string; replyToMessageId?: number }): void
-  /**
-   * External completion hook — authoritative turn-finished signal from
-   * outside the session-tail path. Intended for `stream_reply(done=true)`
-   * so the final-answer arrival acts with equal authority to a session-tail
-   * `turn_end` event. Idempotent: first caller wins, subsequent callers
-   * on the same chat+thread find no active card and no-op.
-   *
-   * Closes any active card for (chatId, threadId):
-   *   - cancels the deferred-first-emit timer (fast-turn suppression)
-   *   - synthesizes a `turn_end` through the reducer
-   *   - fires onTurnEnd + onTurnComplete
-   *   - clears chats map + bookkeeping
-   *
-   * If the deferred first emit hasn't landed yet (fast turn), `flush` sees
-   * `forceDone=true` on a still-`isFirstEmit=true` state and suppresses
-   * the emit entirely — no ghost card. If the card already emitted, the
-   * normal flush+unpin path runs via onTurnComplete.
-   */
-  forceCompleteTurn(args: { chatId: string; threadId?: string }): void
-  /**
-   * #654 deterministic double-message fix. Hand off ownership of the
-   * pinned progress card for an active turn so an external code path
-   * (specifically the turn-flush backstop in gateway.ts) can rewrite
-   * the card message with the user-facing answer instead of issuing a
-   * fresh sendMessage that lands as a second Telegram message.
-   *
-   * Effects:
-   *   - cancels the deferred-first-emit timer if pending (no late
-   *     card emission can race the takeover)
-   *   - sets `cardTakenOver = true` — `flush()` short-circuits at the
-   *     top, so no further edits go out from the driver for this turn
-   *   - sets `completionFired = true` — guards against double-firing
-   *     `completeTurnFully` if a deferred-completion path also runs
-   *
-   * Returns:
-   *   - `wasEmitted`: true iff the card has already been published to
-   *     Telegram (i.e. the deferred-emit timer fired or pinning has
-   *     occurred). Caller can use this to decide between editMessageText
-   *     vs sendMessage.
-   *   - `turnKey`: the active turn's full key (chatId:threadId?:seq)
-   *     so the caller can look up the pinned messageId via pinMgr.
-   *     Null only when no active card exists for (chatId, threadId).
-   *
-   * Idempotent — safe to call multiple times for the same turn; the
-   * second call returns the same shape with timer-cancellation already
-   * complete.
-   */
-  takeOverCard(args: { chatId: string; threadId?: string }): {
-    wasEmitted: boolean
-    turnKey: string | null
-  }
-  /** Current state for a chat (for tests / inspection). */
-  peek(chatId: string, threadId?: string): ProgressCardState | undefined
-  /**
-   * P0 of #662 — fetch the shadow fleet map for a chat. Used by tests
-   * and (eventually) by the v2 renderer. Same lookup semantics as
-   * `peek`. Returns undefined when no active card exists.
-   */
-  peekFleet(chatId: string, threadId?: string): Map<string, FleetMember> | undefined
-  /**
-   * P2 of #662 — debug/test hook returning every live PerChatState's
-   * fleet keyed by turnKey. Used by cross-turn background tests to
-   * verify routing landed on the originating turn rather than the
-   * currently-active one. Not part of the production driver contract.
-   */
-  peekAllFleets(): Array<{ turnKey: string; chatId: string | null; fleet: Map<string, FleetMember> }>
-  /**
-   * True when the driver is still managing an active card for this chat+
-   * thread — either a normal turn or a deferred-completion turn waiting on
-   * in-flight sub-agents. Used by the gateway's `closeProgressLane`
-   * backstop to avoid tearing down the draft stream while the driver is
-   * still going to emit into it. Without this guard, parent turn_end
-   * closes the stream, sub-agent tool_use events fire fresh emits, and
-   * each emit creates a new `sendMessage` on Telegram (= new push
-   * notification) instead of editing the pinned card.
-   */
-  hasActiveCard(chatId: string, threadId?: string): boolean
-  /**
-   * Issue #305 Option A — push a sub-agent narrative line into the
-   * pinned progress card's row body for `agentId` (jsonl_agent_id).
-   * Replace-on-each-call. Caller (gateway) is responsible for truncating
-   * `text` to the 200-char card cap before invocation.
-   *
-   * Returns:
-   *   - `{ ok: true }` when the narrative was applied + flush triggered.
-   *   - `{ ok: false, reason: 'no_active_card' }` if no card is tracked
-   *     for (chatId, threadId) or its turn already completionFired.
-   *   - `{ ok: false, reason: 'unknown_agent' }` if the card is active
-   *     but does not yet contain a sub-agent for `agentId` (likely a
-   *     race with sub-agent watcher's jsonl_agent_id backfill — caller
-   *     should fall through to the message-send path).
-   *
-   * Never throws.
-   */
-  recordSubAgentNarrative(args: {
-    chatId: string
-    threadId?: string
-    agentId: string
-    text: string
-  }): { ok: true } | { ok: false; reason: 'no_active_card' | 'unknown_agent' }
-  /**
-   * Report a Telegram API failure back to the driver after an async emit
-   * fails. The outer layer (server.ts catch handler) classifies the raw
-   * error and calls this so the driver can track consecutive 4xx failures
-   * and mark the card terminal when the threshold is reached.
-   *
-   * Rules:
-   *   - `benign` (message is not modified) — ignored; counter unchanged.
-   *   - `transient` (5xx, network) — logged at debug; counter unchanged.
-   *   - `permanent_4xx` — counter incremented; terminal=true after K hits.
-   *
-   * Idempotent after terminal=true.
-   */
-  reportApiFailure(turnKey: string, failure: ApiFailureInfo): void
-  /**
-   * Report a successful Telegram API call for a card. Resets the
-   * consecutive-4xx counter so a single success after a transient failure
-   * doesn't leave the counter elevated. Call from the `.then()` handler
-   * of the async emit in server.ts.
-   */
-  reportApiSuccess(turnKey: string): void
-  /**
-   * Issue #137: bump the per-turn outbound-delivered counter for the
-   * card matching (chatId, threadId). Called from the gateway's reply
-   * success paths (executeReply, executeStreamReply) AFTER the
-   * `bot.api.sendMessage` resolved. If no card is active for that
-   * chat+thread, the call is a silent no-op (boot banners and other
-   * system messages don't tick the counter).
-   */
-  recordOutboundDelivered(chatId: string, threadId?: string): void
-  /**
-   * Option C — watcher stall callback. Called by the sub-agent watcher
-   * (via config.onStall) when a running sub-agent's JSONL goes silent for
-   * longer than `stallThresholdMs`. Updates the sub-agent's `lastEventAt`
-   * to trigger the elapsed-ticker so the progress card re-renders with a
-   * visible ⚠️ stall indicator, even when the bridge has disconnected.
-   *
-   * No-op if no card is currently tracking this `agentId`.
-   */
-  onSubAgentStall(agentId: string, idleMs: number, description: string): void
-  /**
-   * Symmetric to `onSubAgentStall`. Fires when the watcher observes
-   * JSONL activity returning for a previously-stalled sub-agent. Forces
-   * a re-render so the ⚠ Stalled badge clears immediately, instead of
-   * waiting on the next heartbeat tick (which the diff-guard might
-   * suppress if no chat-level state otherwise changed). The render
-   * itself reads the now-current `sa.lastEventAt` (already bumped by
-   * the standard event path), so this method is purely a render-trigger.
-   *
-   * No-op if no card is currently tracking this `agentId`.
-   */
-  onSubAgentUnstall(agentId: string, description: string): void
-  /**
-   * Test-only accessor exposing the driver's internal Maps so unit tests
-   * can assert TTL eviction and outer-base-key cleanup actually drop
-   * entries. Not part of the supported runtime API — gated behind the
-   * leading-underscore name.
-   */
-  _debugGetMaps?(): {
-    chats: Map<string, unknown>
-    seenEnqueueMsgIds: Map<string, number>
-    pendingSyncEchoes: Map<string, number>
-    chatRunningSubagents: Map<string, Map<string, unknown>>
-    baseTurnSeqs: Map<string, number>
-    editTimestamps: Map<string, number[]>
-  }
-}
-
-export function createProgressDriver(config: ProgressDriverConfig): ProgressDriver {
-  const minIntervalMs = config.minIntervalMs ?? 500
-  const coalesceMs = config.coalesceMs ?? 400
-  const now = config.now ?? (() => Date.now())
-  const setT =
-    config.setTimeout ??
-    ((fn, ms) => {
-      const h = setTimeout(fn, ms)
-      return { ref: h }
-    })
-  const clearT =
-    config.clearTimeout ??
-    ((ref) => {
-      const handle = (ref as { ref: ReturnType<typeof setTimeout> }).ref
-      clearTimeout(handle)
-    })
-  const setI =
-    config.setInterval ??
-    ((fn, ms) => {
-      const h = setInterval(fn, ms)
-      return { ref: h }
-    })
-  const clearI =
-    config.clearInterval ??
-    ((ref) => {
-      const handle = (ref as { ref: ReturnType<typeof setInterval> }).ref
-      clearInterval(handle)
-    })
-  const heartbeatMs = config.heartbeatMs ?? 5000
-  const editBudgetThreshold = config.editBudgetThreshold ?? 18
-  const editBudgetCoalesceMs = config.editBudgetCoalesceMs ?? 3000
-  const maxIdleMs = config.maxIdleMs ?? 30 * 60_000
-  // v2 card-gate (#553 PR 4 / #842): card visibility is `(elapsed >= 45s)
-  // OR (any sub-agent appeared) OR (explicit background dispatch)`.
-  // Tools alone never trigger the card.
-  //   - initialDelayMs: 45s (was 60s, #842) — pushes the time-based gate
-  //     to the spec value. The lower threshold means more turns flash a
-  //     card; the explicit-background bypass below offsets that for the
-  //     "fire-and-forget" case where the user always wants to see the
-  //     card immediately.
-  //   - initialDelayMsBackground: 0 (#842) — explicit
-  //     `Agent({run_in_background:true})` dispatches promote the card
-  //     immediately. Lets backgrounded work be visible right away
-  //     without waiting for any other promotion path.
-  //   - promoteOnParentToolCount: 0 (was 3) — disabled. The check below
-  //     treats 0 (and Infinity) as "never promote on tool count".
-  //   - promoteAfterMs: 0 (was 5_000) — disabled. ensureTimePromoteScheduled
-  //     no-ops when this is 0, so the timer never schedules. The PR #570
-  //     time-promote was a stop-gap when initialDelayMs was 30s; with
-  //     initialDelayMs=45s and the sub-agent promote intact, it is no
-  //     longer needed.
-  //   - promoteOnSubAgent: true (unchanged) — sub-agents/background workers
-  //     break the suppression immediately.
-  const initialDelayMs = config.initialDelayMs ?? 45_000
-  const initialDelayMsBackground = config.initialDelayMsBackground ?? 0
-  const promoteOnSubAgent = config.promoteOnSubAgent ?? true
-  const promoteOnParentToolCount = config.promoteOnParentToolCount ?? 0
-  const promoteAfterMs = config.promoteAfterMs ?? 0
-  const maxConsecutive4xx = config.maxConsecutive4xx ?? 3
-  const orphanPromotionMs = config.orphanPromotionMs ?? 5_000
-  const coldSubAgentThresholdMs = config.coldSubAgentThresholdMs ?? 30_000
-  const deferredCompletionTimeoutMs = config.deferredCompletionTimeoutMs ?? 3 * 60_000
-  const subAgentTickIntervalMs = config.subAgentTickIntervalMs ?? 10_000
-  // Per-chat sliding 60s window of recent emit timestamps. When the
-  // window holds more than `editBudgetThreshold` entries we're "hot"
-  // and coalesce more aggressively.
-  const editTimestamps = new Map<string, number[]>()
-  function recordEdit(k: string): void {
-    const arr = editTimestamps.get(k) ?? []
-    arr.push(now())
-    // Drop entries older than 60s.
-    const cutoff = now() - 60_000
-    while (arr.length > 0 && arr[0] < cutoff) arr.shift()
-    editTimestamps.set(k, arr)
-  }
-  function isBudgetHot(k: string): boolean {
-    const arr = editTimestamps.get(k)
-    if (!arr) return false
-    const cutoff = now() - 60_000
-    while (arr.length > 0 && arr[0] < cutoff) arr.shift()
-    return arr.length >= editBudgetThreshold
-  }
-
-  const chats = new Map<string, PerChatState>()
-
-  // Issue #334: per-chat registry of sub-agents that are still running.
-  // Keyed by baseKey(chatId, threadId) → Map<agentId, SubAgentState>.
-  // When a sub-agent starts it's added; when it reaches a terminal state
-  // (done/failed) it's removed. On a new turn for the same chat, any
-  // entries here are cloned into the new PerChatState's subAgents so the
-  // new turn's progress card shows still-running background sub-agents
-  // from the prior turn.
-  const chatRunningSubagents = new Map<string, Map<string, SubAgentState>>()
-
-  // Per-chat turn sequence counters. Key = baseKey(chatId, threadId).
-  // Each new startTurn increments the counter; the value is the NEXT seq
-  // to allocate (so current total = value - 1 once at least one was allocated).
-  const baseTurnSeqs = new Map<string, number>()
-  // Tracks base keys of turns started via isSync (startTurn). When the
-  // corresponding non-sync session-tail echo arrives, it's dropped and
-  // the entry is consumed. This prevents orphan cards when a fast turn
-  // completes before the session-tail fires its enqueue echo — Guard 1
-  // misses it because currentTurnKey is already null, but this guard
-  // catches the echo regardless of turn lifecycle state.
-  const pendingSyncEchoes = new Map<string, number>()
-  // MessageId-based dedup: tracks recently seen enqueue messageIds so
-  // that repeated delivery of the same user message (from session
-  // restarts, reconnects, or JSONL rotation) is dropped even after
-  // Guard 2's one-shot marker has been consumed. Keyed by
-  // `base:messageId` → timestamp. Entries expire after 60s.
-  const seenEnqueueMsgIds = new Map<string, number>()
-
-  /** Allocate a new turn slot for chatId:threadId. Returns the unique turnKey and 1-based index. */
-  function allocateTurnSlot(chatId: string, threadId?: string): { turnKey: string; index: number; total: number } {
-    const base = baseKey(chatId, threadId)
-    const seq = (baseTurnSeqs.get(base) ?? 0) + 1
-    baseTurnSeqs.set(base, seq)
-    return { turnKey: `${base}:${seq}`, index: seq, total: seq }
-  }
-
-  // Track the last enqueued turn key so non-enqueue session events (tool_use,
-  // tool_result, turn_end) which arrive with chatIdMaybe=null from the
-  // session-tail supervisor still route to the correct card.
-  let currentChatId: string | null = null
-  let currentThreadId: string | undefined
-  /** Full turn key (chatId:threadId:seq) for the currently active turn. */
-  let currentTurnKey: string | null = null
-  let heartbeatHandle: { ref: unknown } | null = null
-  // Throttled inline TTL eviction for `seenEnqueueMsgIds` and
-  // `pendingSyncEchoes`. Previously eviction lived inside the heartbeat tick,
-  // but the heartbeat stops when `chats.size === 0`, leaving these maps to
-  // grow unbounded across idle periods. The inline path runs at the top of
-  // every public ingress (ingest / startTurn) but is rate-limited to once
-  // every `evictThrottleMs` so it stays effectively free in the hot path.
-  let lastEvictedAt = 0
-  const evictThrottleMs = 30_000
-  // Tracks the last elapsed-seconds bucket we emitted for each chat so
-  // the heartbeat can coalesce — if the HTML hasn't changed AND the
-  // header elapsed counter (rounded to the heartbeat cadence) would
-  // still render identically, skip the edit.
-  const lastHeartbeatBucket = new Map<string, number>()
-  // Fix #314: tracks the last sub-agent elapsed-tick bucket per turn.
-  // Works exactly like `lastHeartbeatBucket` but uses `subAgentTickIntervalMs`
-  // as the bucket width. When the bucket advances AND at least one sub-agent
-  // is running, the heartbeat forces an emit even when the HTML hash is
-  // unchanged. Bucket-based (not timestamp-based) so the comparison is stable
-  // even when multiple heartbeat ticks fire at the same `now()` value during
-  // a fake-clock advance in tests.
-  const lastSubAgentTickBucket = new Map<string, number>()
-
-  /**
-   * Fire completion callbacks + delete chatState + tidy bookkeeping.
-   * Idempotent via `completionFired`. Does not touch the reducer or
-   * flush — the caller is responsible for putting the state into its
-   * final shape before invoking this.
-   *
-   * Shared by three completion paths:
-   *   - Normal turn_end with no in-flight sub-agents
-   *   - Deferred completion (last sub-agent finishes after parent turn_end)
-   *   - Abandonment (closeZombie for maxIdle / enqueue-force-close)
-   */
-  /**
-   * Prepare silent-end suppression BEFORE the final flush.
-   *
-   * Must run before the outer `flush(cs, true)` at every site that calls
-   * `completeTurnFully`, so the render at that flush already knows whether
-   * to suppress the "🙊 Ended without reply" header. If we relied on
-   * `completeTurnFully` to set the flag and re-flush, the outer flush would
-   * already have queued a warning-card edit/send to Telegram — and in the
-   * worst case (the first edit finalizes before the second arrives) the
-   * user sees both the warning AND the corrected card as separate messages.
-   *
-   * Idempotent — `silentEndPrepared` guards against re-firing the
-   * `onSilentEnd` callback (which writes a state file the Stop hook reads).
-   */
-  function prepareSilentEndSuppression(cs: PerChatState): void {
-    if (cs.silentEndPrepared) return
-    cs.silentEndPrepared = true
-    // #371 fix: when stream_reply(done=true) lands as the final tool call,
-    // the Stop hook can fire before session-tail observes the matching
-    // tool_use event. Pre-fix replyToolCalled stayed false long enough for
-    // isSilentEnd to read true → the silent-end retry kicks in → the user
-    // sees a duplicate reply.
-    //
-    // outboundDeliveredCount is bumped synchronously by
-    // recordOutboundDelivered() inside the stream_reply MCP handler when
-    // the API call returns successfully — it doesn't depend on the
-    // session-tail event landing. Consulting it here closes the race.
-    const isSilentEnd =
-      !cs.replyToolCalled
-      && cs.outboundDeliveredCount === 0
-      && !cs.wasAutonomous
-    if (!isSilentEnd || !config.onSilentEnd) return
-    try {
-      const result = config.onSilentEnd({ chatId: cs.chatId, threadId: cs.threadId, turnKey: cs.turnKey })
-      if (result?.suppressed === true) {
-        cs.silentEndSuppressed = true
-      }
-    } catch {
-      /* never let the callback break the completion path */
-    }
-  }
-
-  function beginTurnEnd(target: PerChatState, durationMs: number): void {
-    target.parentTurnEndAt = now()
-    target.state = reduce(target.state, { kind: 'turn_end', durationMs }, now())
-  }
-
-  function completeTurnFully(cs: PerChatState): void {
-    if (cs.completionFired) return
-    cs.completionFired = true
-    // Defensive: if a caller forgot to call prepareSilentEndSuppression
-    // before its flush, run it now so the onSilentEnd callback still fires
-    // (the Stop hook still gets the state file). The flag is already set
-    // for any caller that did call it (idempotent guard).
-    prepareSilentEndSuppression(cs)
-    const taskNum = taskNumFor(cs)
-    const summary = summariseTurn(cs.state, now())
-    if (config.onTurnEnd) {
-      try {
-        config.onTurnEnd(summary)
-      } catch {
-        /* never let a summary write break the stream */
-      }
-    }
-    if (config.onTurnComplete) {
-      process.stderr.write(`telegram gateway: progress-card: onTurnComplete firing turnKey=${cs.turnKey}\n`)
-      emitCardEvent({
-        agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-        chatId: cs.chatId ?? '',
-        turnKey: cs.turnKey,
-        event: 'finalized',
-        reason: 'onTurnComplete',
-      })
-      try {
-        config.onTurnComplete({
-          chatId: cs.chatId,
-          threadId: cs.threadId,
-          turnKey: cs.turnKey,
-          summary,
-          taskIndex: taskNum.index,
-          taskTotal: taskNum.total,
-        })
-      } catch {
-        /* never let completion callback break the stream */
-      }
-    }
-    if (cs.pendingTimer != null) {
-      clearT(cs.pendingTimer)
-      cs.pendingTimer = null
-    }
-    if (cs.deferredFirstEmitTimer != null) {
-      clearT(cs.deferredFirstEmitTimer)
-      cs.deferredFirstEmitTimer = null
-    }
-    if (cs.timePromoteTimer != null) {
-      clearT(cs.timePromoteTimer)
-      cs.timePromoteTimer = null
-    }
-    chats.delete(cs.turnKey)
-    lastHeartbeatBucket.delete(cs.turnKey)
-    lastSubAgentTickBucket.delete(cs.turnKey)
-    editTimestamps.delete(cs.turnKey)
-    // Drop the outer base-key entries if no other chat shares the same base.
-    // Covers all 3 close paths since they all funnel through here:
-    // completeTurnFully (turn_end), closeZombie (abandonment), and the
-    // stalled-close branch in the heartbeat. Prevents unbounded growth of
-    // `chatRunningSubagents` / `baseTurnSeqs` across idle periods.
-    cleanupBaseKeyIfUnused(baseKey(cs.chatId, cs.threadId), parseTurnSeq(cs.turnKey))
-    if (currentTurnKey === cs.turnKey) {
-      currentChatId = null
-      currentThreadId = undefined
-      currentTurnKey = null
-    }
-    if (chats.size === 0) stopHeartbeat()
-  }
-
-  /**
-   * Post-ingest check: if the turn is in `pendingCompletion` state and
-   * no sub-agents are still in-flight, fire completion. Called after
-   * every reducer dispatch that could transition a sub-agent to done
-   * (sub_agent_turn_end, parent Agent tool_result, etc.).
-   */
-  function maybeCompleteDeferredTurn(cs: PerChatState): void {
-    if (!cs.pendingCompletion) return
-    // Gate on ANY running sub-agent (correlated OR orphan). Orphans from
-    // `Agent({run_in_background:true})` only deregister via their own
-    // `sub_agent_turn_end` — the card must stay pinned until then so the
-    // user sees the background work. Closes #87. Historical ghost-pin
-    // risk (#31/#43) is bounded by `closeZombie` on new enqueue +
-    // `maxIdleMs` heartbeat ceiling.
-    // Also gate on fleet background members: a bg sub-agent that hasn't
-    // yet emitted any events will be absent from state.subAgents but
-    // present in fleet with status:'background'. Without this gate the
-    // deferred completion would fire immediately and close the card.
-    // Fixes #713 and #709.
-    if (hasAnyRunningSubAgent(cs.state)) return
-    if (hasLiveBackground(cs.fleet)) return
-    process.stderr.write(`telegram gateway: progress-card: deferred completion firing turnKey=${cs.turnKey} (last sub-agent finished)\n`)
-    emitCardEvent({
-      agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-      chatId: cs.chatId ?? '',
-      turnKey: cs.turnKey,
-      event: 'force-completed',
-      reason: 'deferred-completion: last sub-agent finished',
-    })
-    // Route through the unified close path (turn-end reason) so the
-    // prelude (silentEnd suppression, final flush, tail cleanup) matches
-    // every other completion site.
-    closePerChat(cs, 'turn-end')
-  }
-
-  /**
-   * Unified per-chat close path. Called by every site that finalises a
-   * card so the prelude (timer cleanup, sub-agent force-close where the
-   * reason demands it, silentEnd preparation, final flush) is applied
-   * consistently. The cleanup tail (chats.delete, baseKey cleanup,
-   * heartbeat-stop-if-last) lives in `completeTurnFully` and runs at the
-   * end of every reason path.
-   *
-   * Reasons:
-   *   - 'turn-end'  : normal completion (parent turn_end fired with no
-   *                   in-flight sub-agents, or the deferred-completion
-   *                   gate cleared). Sub-agents are NOT force-closed
-   *                   because by definition none are running.
-   *   - 'zombie'    : abandonment (heartbeat maxIdle ceiling, or new
-   *                   enqueue force-closing the previous card). Force-
-   *                   closes running sub-agents because we are giving
-   *                   up on them. Preserves `pendingSyncEchoes` because
-   *                   the echo for the previous turn may still arrive.
-   *   - 'stalled'   : Gap-8 deferred-completion timeout expired. Force-
-   *                   closes running sub-agents and passes
-   *                   `stalledClose=true` to flush so the renderer shows
-   *                   "⚠️ Stalled — forced close".
-   *
-   * Must not re-enter ingest.
-   */
-  function closePerChat(cs: PerChatState, reason: CloseReason): void {
-    // Clear pending coalesce timer for every reason — we are about to
-    // emit the final render synchronously.
-    if (cs.pendingTimer != null) {
-      clearT(cs.pendingTimer)
-      cs.pendingTimer = null
-    }
-
-    if (reason === 'zombie' || reason === 'stalled') {
-      // Both reasons synthesise a turn_end (zombie) or have already had
-      // one fire (stalled — parentTurnEndAt is set) and then explicitly
-      // close every running sub-agent so the render accounts for all
-      // work. zombie: reduce now; stalled: reducer already saw turn_end.
-      if (reason === 'zombie') {
-        const durationMs = Math.max(0, now() - cs.state.turnStartedAt)
-        cs.state = reduce(cs.state, { kind: 'turn_end', durationMs }, now())
-      }
-      if (hasAnyRunningSubAgent(cs.state)) {
-        const prevStateForSync = cs.state
-        const closed = new Map(cs.state.subAgents)
-        const nowMs = now()
-        for (const [k, sa] of closed) {
-          if (sa.state === 'running') {
-            closed.set(k, { ...sa, state: 'done', finishedAt: nowMs, pendingPreamble: null })
-          }
-        }
-        cs.state = { ...cs.state, subAgents: closed }
-        // Issue #399: sync the chat-scoped running-sub-agent registry so
-        // stale entries don't carry into the next turn's progress card.
-        syncChatRunningSubagents(
-          prevStateForSync,
-          cs.state,
-          baseKey(cs.chatId, cs.threadId),
-          chatRunningSubagents,
-        )
-      }
-    }
-
-    // Set silentEndSuppressed BEFORE the outer flush so the rendered
-    // card already excludes the "🙊 Ended without reply" header when a
-    // retry is queued. Otherwise the outer flush would queue a warning-
-    // card edit and a follow-up correction edit could race.
-    prepareSilentEndSuppression(cs)
-    // zombie passes stalledClose=false — we abandoned the card but did
-    // NOT exceed the deferred-completion timeout. Promoting it to
-    // stalled would mis-render the close header.
-    flush(cs, /*forceDone*/ true, /*stalledClose*/ reason === 'stalled')
-    completeTurnFully(cs)
-    // Note: zombie deliberately preserves `pendingSyncEchoes` because
-    // the echo for the closed turn may still arrive after close. The
-    // dedup map's TTL eviction (maybeEvict) will reap it eventually.
-  }
-
-  /**
-   * Backwards-compatible alias for the zombie close path. Retained as a
-   * thin wrapper so call sites read clearly ("close the zombie") without
-   * needing to know about the reason taxonomy.
-   */
-  function closeZombie(cs: PerChatState): void {
-    closePerChat(cs, 'zombie')
-  }
-
-  /**
-   * TTL-evict stale entries from the messageId-dedup map and the sync-echo
-   * marker map. Same TTLs as the (now-removed) heartbeat eviction:
-   *   - `seenEnqueueMsgIds`: 60s (matches the dedup window in `ingest`).
-   *   - `pendingSyncEchoes`: 30s (matches the consumer in `ingest`).
-   */
-  function evictStaleDedup(nowMs: number): void {
-    const t60 = nowMs - 60_000
-    for (const [k, ts] of seenEnqueueMsgIds) {
-      if (ts <= t60) seenEnqueueMsgIds.delete(k)
-    }
-    const t30 = nowMs - 30_000
-    for (const [k, ts] of pendingSyncEchoes) {
-      if (ts <= t30) pendingSyncEchoes.delete(k)
-    }
-  }
-
-  /**
-   * Throttled wrapper. Cheap when not due — a single timestamp compare and
-   * branch. Called at the top of every public ingress so eviction runs
-   * regardless of whether any chats are currently live.
-   */
-  function maybeEvict(nowMs: number): void {
-    if (nowMs - lastEvictedAt < evictThrottleMs) return
-    lastEvictedAt = nowMs
-    evictStaleDedup(nowMs)
-  }
-
-  /**
-   * Best-effort outer-base-key cleanup, called after a chat is removed from
-   * the `chats` map. Only drops entries that are *safe* to drop:
-   *
-   *   - `chatRunningSubagents[base]`: deleted iff (a) no surviving chat
-   *     shares the same base AND (b) the inner map is empty. Background
-   *     sub-agents intentionally outlive their parent turn (cross-turn
-   *     carry-over for `Agent({run_in_background:true})`), so we never
-   *     drop a non-empty inner map — that would erase the next turn's
-   *     seed list. The empty-map case is the unbounded-growth path the
-   *     caller cares about: a chat that ran but never spawned anything
-   *     still got a `Map` allocated (or, more importantly, the entry
-   *     remains after natural sub-agent completion).
-   *
-   *   - `baseTurnSeqs[base]`: deleted iff no surviving chat shares the
-   *     same base AND no in-flight enqueue has just allocated a new turn
-   *     for this base via `allocateTurnSlot` (signalled by
-   *     `currentTurnKey` whose prefix matches `base`). The latter guard
-   *     matters because the new-enqueue path runs
-   *     `allocateTurnSlot -> closeZombie(old)` before registering the
-   *     new chat in `chats`; a naive delete here would clobber the
-   *     just-allocated seq, causing the next allocation to reset to 1
-   *     and collide with the still-live new turn.
-   */
-  function cleanupBaseKeyIfUnused(base: string, closingTurnSeq?: number): void {
-    for (const cs of chats.values()) {
-      if (baseKey(cs.chatId, cs.threadId) === base) return
-    }
-    const inner = chatRunningSubagents.get(base)
-    if (inner == null || inner.size === 0) {
-      chatRunningSubagents.delete(base)
-    }
-    // Skip `baseTurnSeqs` cleanup if `allocateTurnSlot` has just bumped the
-    // seq past the turn we are closing. That happens in the new-enqueue
-    // path: `allocateTurnSlot` runs BEFORE `closeZombie(old)` and BEFORE
-    // the new PerChatState is registered in `chats`, so the new turn is
-    // invisible to the iteration above. Detecting that via the seq diff
-    // avoids clobbering the just-allocated counter (would reset numbering
-    // to 1 and cause turnKey collisions with the still-live new turn).
-    const currentSeq = baseTurnSeqs.get(base)
-    if (
-      currentSeq != null
-      && closingTurnSeq != null
-      && currentSeq > closingTurnSeq
-    ) {
-      return
-    }
-    baseTurnSeqs.delete(base)
-  }
-
-  /** Parse the trailing `:N` from a turnKey. Returns undefined if absent. */
-  function parseTurnSeq(turnKey: string): number | undefined {
-    const idx = turnKey.lastIndexOf(':')
-    if (idx < 0) return undefined
-    const n = Number(turnKey.slice(idx + 1))
-    return Number.isFinite(n) ? n : undefined
-  }
-
-  function startHeartbeatIfNeeded(): void {
-    if (heartbeatMs <= 0) return
-    if (heartbeatHandle != null) return
-    if (chats.size === 0) return
-    heartbeatHandle = setI(() => {
-      // Force a re-render for any chat with an open turn so the header
-      // elapsed time and per-item `(dur)` tick visibly — even when no
-      // session-JSONL events have arrived for a while (common while a
-      // sub-agent is running). Coalesce: only actually emit if either
-      // the rendered HTML changed or the elapsed-time bucket
-      // (rounded to the heartbeat period) advanced.
-      //
-      // Zombie ceiling: collect any card whose last real event is
-      // older than maxIdleMs and force-close it after the iteration.
-      // Deferring the close keeps Map iteration safe and lets us batch
-      // the cleanup.
-      const zombies: PerChatState[] = []
-      // Gap 3: pendingAgentSpawns that need orphan promotion this tick.
-      const orphanPromotions: PerChatState[] = []
-      // Gap 4: running sub-agents whose JSONL watcher appears cold.
-      const coldSubAgents: Array<{ cs: PerChatState; agentId: string }> = []
-      // Gap 8: cards where the deferred-completion timeout has expired.
-      const stalledCards: PerChatState[] = []
-      for (const [, cs] of chats) {
-        // P3 of #662 — per-member stuck escalation runs FIRST, before any
-        // skip gate. This is pure data plumbing on the fleet shadow map;
-        // it must happen even when the chat is in the initial-delay window
-        // or budget-hot (the renderer's job is gated by those conditions
-        // separately). markStuck is idempotent and a no-op for non-running
-        // members, so running it every tick is cheap.
-        {
-          const fleet = cs.fleet
-          if (fleet.size > 0) {
-            const tNow = now()
-            for (const [agentId, m] of fleet) {
-              const next = fleetMarkStuck(m, tNow, 60_000)
-              if (next !== m) fleet.set(agentId, next)
-            }
-          }
-        }
-
-        // Skip only when TRULY done. During the deferred-completion
-        // window (parent turn_end fired but sub-agents — correlated or
-        // orphan — are still running), reducer stage is 'done' but the
-        // card is still alive. Keeping the heartbeat ticking lets per-row
-        // elapsed times advance visibly; otherwise the card looks frozen
-        // ("card went dead" bug). Same gate as the defer paths so the
-        // heartbeat lifetime tracks the pin lifetime exactly.
-        if (cs.state.stage === 'done' && !hasAnyRunningSubAgent(cs.state)) continue
-        // Skip heartbeat for terminal cards — the Telegram message is gone
-        // (deleted / bot blocked). No edits should be attempted.
-        if (cs.apiFailures.terminal) continue
-        // Don't heartbeat a card that's still in the initial delay window.
-        if (cs.isFirstEmit && cs.deferredFirstEmitTimer !== DELAY_ELAPSED) continue
-        if (maxIdleMs > 0 && now() - cs.lastEventAt > maxIdleMs) {
-          zombies.push(cs)
-          continue
-        }
-
-        // Gap 3 — orphan promotion: if any PendingAgentSpawn has been
-        // waiting longer than orphanPromotionMs without a matching
-        // sub_agent_started, promote it to a synthesised sub-agent row so
-        // the work is at least visible on the card.
-        if (orphanPromotionMs > 0 && cs.state.pendingAgentSpawns.size > 0) {
-          for (const [toolUseId, pending] of cs.state.pendingAgentSpawns) {
-            if (!cs.promotedSpawnIds.has(toolUseId) && now() - pending.startedAt >= orphanPromotionMs) {
-              orphanPromotions.push(cs)
-              break
-            }
-          }
-        }
-
-        // Gap 4 — cold-JSONL detection: if a running sub-agent hasn't
-        // emitted an event for coldSubAgentThresholdMs, synthesise a
-        // sub_agent_turn_end so the deferred-completion path can proceed.
-        if (coldSubAgentThresholdMs > 0 && cs.pendingCompletion) {
-          for (const [agentId, sa] of cs.state.subAgents) {
-            if (sa.state === 'running' && sa.lastEventAt != null && now() - sa.lastEventAt >= coldSubAgentThresholdMs) {
-              coldSubAgents.push({ cs, agentId })
-            }
-          }
-        }
-
-        // Gap 8 — deferred-completion timeout: if the parent turn_end fired
-        // but sub-agents never finished within deferredCompletionTimeoutMs,
-        // force-close with a "stalled" header.
-        if (
-          deferredCompletionTimeoutMs > 0
-          && cs.parentTurnEndAt != null
-          && now() - cs.parentTurnEndAt >= deferredCompletionTimeoutMs
-        ) {
-          stalledCards.push(cs)
-          continue
-        }
-
-        // Fix #314 — elapsed-ticker bucket: compute BEFORE the budget-hot
-        // skip so the ticker can override the skip when the elapsed counter
-        // would otherwise freeze. A bursty sub-agent (many tool calls) makes
-        // the chat hot, which suppresses the heartbeat — but the user still
-        // expects elapsed time to advance visibly. The ticker provides a hard
-        // floor every `subAgentTickIntervalMs` so the UI never looks dead for
-        // longer than that, even when a sub-agent is grinding through tools.
-        const subAgentRunning = subAgentTickIntervalMs > 0 && hasAnyRunningSubAgent(cs.state)
-        const subAgentBucket = subAgentTickIntervalMs > 0 ? Math.floor(now() / subAgentTickIntervalMs) : 0
-        const prevSubAgentBucket = lastSubAgentTickBucket.get(cs.turnKey)
-        const elapsedTickDue = subAgentRunning && subAgentBucket !== prevSubAgentBucket
-
-        // Skip heartbeat while the chat is hot — sub-agent bursts are
-        // already producing edits, the elapsed counter is ticking from
-        // those, and an extra heartbeat edit just spends budget. (Design
-        // §4.4: "heartbeat respects budget too".) EXCEPTION: when the
-        // elapsed-ticker is due, push one render through to keep elapsed
-        // visibly advancing — this is the floor that fixes #314.
-        if (isBudgetHot(cs.turnKey) && !elapsedTickDue) continue
-        if (elapsedTickDue) {
-          lastSubAgentTickBucket.set(cs.turnKey, subAgentBucket)
-        }
-        const stuckMs = Math.max(0, now() - cs.lastEventAt)
-        // Issue #132: silentEnd only matters once the parent turn is in
-        // `stage='done'` AND no sub-agents are still running. While work
-        // is in flight, "no reply yet" is normal; the card stays in
-        // "Working…". The renderer applies the same gate, so passing the
-        // unconditional flag here is safe.
-        // Issue #259: suppress for autonomous wakeup turns (no reply is expected).
-        // silentEndSuppressed: set when a retry is queued (first silent-end) so
-        // the heartbeat renders "✅ Done" instead of "🙊 Ended without reply".
-        const silentEnd = !cs.replyToolCalled && !cs.wasAutonomous && !cs.silentEndSuppressed
-        // Issue #137: agent called reply/stream_reply (replyToolCalled=true)
-        // but the actual outbound never landed (recordOutboundDelivered was
-        // never called for this card). Distinct from silentEnd because the
-        // agent TRIED — the failure is in the delivery layer, not the model.
-        const replyNotDelivered = cs.replyToolCalled && cs.outboundDeliveredCount === 0
-        // Gap 8: pass parentDone to renderer during the deferred-unpin window.
-        const parentDone = cs.parentTurnEndAt != null && hasAnyRunningSubAgent(cs.state)
-        const html = render(cs.state, now(), undefined, { stuckMs, silentEnd, replyNotDelivered, parentDone }, undefined, cs.fleet)
-        const bucket = Math.floor(now() / heartbeatMs)
-        const prevBucket = lastHeartbeatBucket.get(cs.turnKey)
-
-        // Fix #314 — elapsed-ticker bypass for the html-unchanged guard. When
-        // the elapsed-ticker is due, push the emit through even if html and
-        // heartbeat-bucket are both unchanged. Combined with the budget-hot
-        // bypass above, this guarantees the elapsed counter advances at most
-        // `subAgentTickIntervalMs` apart while a sub-agent is running.
-        if (html === cs.lastEmittedHtml && bucket === prevBucket && !elapsedTickDue) continue
-
-        lastHeartbeatBucket.set(cs.turnKey, bucket)
-        cs.lastEmittedHtml = html
-        cs.lastEmittedAt = now()
-        recordEdit(cs.turnKey)
-        config.emit({
-          chatId: cs.chatId,
-          threadId: cs.threadId,
-          turnKey: cs.turnKey,
-          html,
-          done: false,
-          isFirstEmit: false,
-        })
-      }
-      for (const cs of zombies) closeZombie(cs)
-
-      // Gap 3: promote stale PendingAgentSpawns to synthetic sub-agent rows.
-      for (const cs of orphanPromotions) {
-        for (const [toolUseId, pending] of cs.state.pendingAgentSpawns) {
-          if (cs.promotedSpawnIds.has(toolUseId)) continue
-          if (now() - pending.startedAt < orphanPromotionMs) continue
-          cs.promotedSpawnIds.add(toolUseId)
-          const syntheticId = `orphan-${toolUseId}`
-          process.stderr.write(
-            `telegram gateway: progress-card: orphan-promotion toolUseId=${toolUseId} syntheticId=${syntheticId} description="${pending.description}" (Gap 3 #313)\n`,
-          )
-          // Synthesise a sub_agent_started event — drives the reducer's
-          // existing sub_agent_started path (adds to subAgents, removes
-          // from pendingAgentSpawns, links checklist item via spawnedAgentId).
-          cs.state = reduce(cs.state, {
-            kind: 'sub_agent_started',
-            agentId: syntheticId,
-            firstPromptText: pending.promptText,
-          }, now())
-          cs.lastEventAt = now()
-          flush(cs, false)
-        }
-      }
-
-      // Gap 4: synthesise sub_agent_turn_end for cold-JSONL sub-agents.
-      for (const { cs, agentId } of coldSubAgents) {
-        process.stderr.write(
-          `telegram gateway: progress-card: cold-jsonl-synth-turn-end agentId=${agentId} turnKey=${cs.turnKey} (Gap 4 #313)\n`,
-        )
-        const prevStateGap4 = cs.state
-        cs.state = reduce(cs.state, { kind: 'sub_agent_turn_end', agentId }, now())
-        // Issue #399: sync the chat-scoped running-sub-agent registry so the
-        // cold-synth terminal transition doesn't leave a stale entry that would
-        // carry over into the next turn's progress card.
-        syncChatRunningSubagents(
-          prevStateGap4,
-          cs.state,
-          baseKey(cs.chatId, cs.threadId),
-          chatRunningSubagents,
-        )
-        cs.lastEventAt = now()
-        maybeCompleteDeferredTurn(cs)
-        if (!cs.completionFired) flush(cs, false)
-      }
-
-      // Gap 8: force-close cards whose deferred-completion timeout has expired.
-      // The unified `closePerChat('stalled')` path applies the same prelude
-      // (sub-agent sync, prepareSilentEndSuppression) and renders the
-      // "⚠️ Stalled — forced close" header via stalledClose=true.
-      for (const cs of stalledCards) {
-        process.stderr.write(
-          `telegram gateway: progress-card: deferred-completion-timeout-expired turnKey=${cs.turnKey} deferredCompletionTimeoutMs=${deferredCompletionTimeoutMs} (Gap 8 #313)\n`,
-        )
-        closePerChat(cs, 'stalled')
-      }
-      // Dedup-map TTL eviction has moved to `maybeEvict` (called from
-      // every public ingress). Keeping it here was unsafe because the
-      // heartbeat stops when `chats.size === 0`, which let
-      // `seenEnqueueMsgIds` / `pendingSyncEchoes` grow unbounded across
-      // idle periods.
-      //
-      // If every chat has ended, stop the heartbeat to avoid an
-      // always-on timer.
-      if (chats.size === 0) stopHeartbeat()
-    }, heartbeatMs)
-  }
-
-  function stopHeartbeat(): void {
-    if (heartbeatHandle == null) return
-    clearI(heartbeatHandle)
-    heartbeatHandle = null
-  }
-
-  /** Base key for a chat:thread (no turn seq). Used as prefix for turn keys. */
-  function baseKey(chatId: string, threadId?: string): string {
-    return threadId != null ? `${chatId}:${threadId}` : chatId
-  }
-
-  /**
-   * Return the N/M task counter for a card. Index and total are derived
-   * from the currently ACTIVE cards for this chat:thread — NOT the
-   * session-cumulative baseTurnSeqs counter. Using the cumulative counter
-   * causes "(11/11)" to appear after 11 sequential turns, which reads as
-   * "task 11 of 11" (confusingly final-looking) rather than conveying
-   * parallel concurrency. The N/M suffix is only meaningful when 2+ cards
-   * are simultaneously active; for sequential turns it should be absent.
-   */
-  function taskNumFor(chatState: PerChatState): TaskNum {
-    const base = baseKey(chatState.chatId, chatState.threadId)
-    // Count only currently active cards for this chat:thread so that
-    // sequential turns always return total=1 (counter hidden) and only
-    // parallel active turns (2+ simultaneous cards) show "(N/M)".
-    let activeCount = 0
-    let activeIndex = 1
-    for (const [, cs] of chats) {
-      if (baseKey(cs.chatId, cs.threadId) === base) {
-        activeCount++
-        if (cs.turnKey === chatState.turnKey) activeIndex = activeCount
-      }
-    }
-    return { index: activeIndex, total: activeCount }
-  }
-
-  const DELAY_ELAPSED = 'elapsed'
-  function flush(chatState: PerChatState, forceDone: boolean, stalledClose = false): void {
-    // If this card has hit the permanent-failure threshold, don't attempt
-    // any more edits. Avoids log spam and pointless retries for deleted
-    // messages / blocked bots.
-    if (chatState.apiFailures.terminal) return
-    // External takeover (e.g. turn-flush rewriting the card with the
-    // user-facing answer text — see #654). Once handed off, the driver
-    // must never issue another edit for this card; the new owner has
-    // full control of the message until they call pinMgr.completeTurn.
-    if (chatState.cardTakenOver) return
-    // Suppress the card entirely if the turn ends before the initial
-    // delay has elapsed — no point flashing a "Working…" card for a
-    // turn that completed in under initialDelayMs.
-    const effectiveDelayMs = chatState.effectiveInitialDelayMs
-    if (chatState.isFirstEmit && effectiveDelayMs > 0 && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED) {
-      if (forceDone || chatState.state.stage === 'done') {
-        // Turn ended before the card was ever shown — suppress it.
-        if (chatState.deferredFirstEmitTimer != null) {
-          clearT(chatState.deferredFirstEmitTimer)
-          chatState.deferredFirstEmitTimer = null
-        }
-        process.stderr.write(`telegram gateway: progress-card: fast-turn suppression turnKey=${chatState.turnKey} (turn ended before initialDelayMs=${effectiveDelayMs}ms)\n`)
-        emitCardEvent({
-          agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-          chatId: chatState.chatId ?? '',
-          turnKey: chatState.turnKey,
-          event: 'suppressed',
-          reason: `fast-turn: ended before initialDelayMs=${effectiveDelayMs}`,
-        })
-        return
-      }
-      // Defer the first emit — schedule it for the per-chat budget from
-      // turn start if not already scheduled. Uses
-      // `chatState.effectiveInitialDelayMs` so the #842 background-
-      // dispatch bypass (which lowers this number on tool_use) takes
-      // effect on the very next flush.
-      if (chatState.deferredFirstEmitTimer == null) {
-        const capturedTurnKey = chatState.turnKey
-        // Schedule from turn start, not from now — multiple flush
-        // attempts during the buffering window must not push the
-        // first-emit clock back.
-        const elapsed = chatState.state.turnStartedAt > 0
-          ? Math.max(0, now() - chatState.state.turnStartedAt)
-          : 0
-        const remaining = Math.max(0, effectiveDelayMs - elapsed)
-        process.stderr.write(`telegram gateway: progress-card: scheduled initial-delay timer turnKey=${capturedTurnKey} delay=${remaining}ms budget=${effectiveDelayMs}ms\n`)
-        chatState.deferredFirstEmitTimer = setT(() => {
-          if (!chats.has(capturedTurnKey)) return
-          chatState.deferredFirstEmitTimer = DELAY_ELAPSED
-          process.stderr.write(`telegram gateway: progress-card: initial-delay timer fired turnKey=${capturedTurnKey}\n`)
-          flush(chatState, false)
-        }, remaining)
-      }
-      return
-    }
-    const taskNum = taskNumFor(chatState)
-    const stuckMs = Math.max(0, now() - chatState.lastEventAt)
-    // Issue #259: autonomous wakeup turns never produce a reply by design —
-    // suppress the silent-end warning so the card renders "✅ Done" instead
-    // of "🙊 Ended without reply" when ScheduleWakeup / CronCreate fires.
-    // silentEndSuppressed is set by completeTurnFully when onSilentEnd returns
-    // { suppressed: true } — used to re-render the final card without the
-    // warning after a retry is queued, preventing a false-positive flash.
-    const silentEnd =
-      !chatState.replyToolCalled && !chatState.wasAutonomous && !chatState.silentEndSuppressed
-    const replyNotDelivered =
-      chatState.replyToolCalled && chatState.outboundDeliveredCount === 0
-    // Gap 8: during the deferred-unpin window (parent turn_end fired but
-    // sub-agents still running), show ✅ Done in the parent header immediately.
-    const parentDone = chatState.parentTurnEndAt != null && hasAnyRunningSubAgent(chatState.state)
-    const html = render(
-      chatState.state,
-      now(),
-      taskNum.total > 1 ? taskNum : undefined,
-      { stuckMs, silentEnd, replyNotDelivered, parentDone, stalledClose },
-      undefined,
-      chatState.fleet,
-    )
-    // Issue #81 diagnostic: which checklist branch is the renderer taking?
-    // The card prefers `narratives` (human preambles) over `items` (raw
-    // tool counts). When prose lands without narratives we want to know
-    // why — log the available state at the decision boundary.
-    //
-    // Fires on the first emit AND on any forced-done flush (terminal
-    // state via completeTurnFully / closeZombie / maybeCompleteDeferredTurn)
-    // — both are useful inflection points for understanding what the card
-    // looked like when it transitioned.
-    if (forceDone || chatState.lastEmittedHtml == null /* first emit or terminal flush */) {
-      const s = chatState.state
-      const branch = s.narratives.length > 0
-        ? 'narratives'
-        : s.items.length > 0
-          ? 'tool-count-fallback'
-          : 'empty'
-      process.stderr.write(
-        `progress-card.diag: render branch=${branch} chatId=${chatState.chatId} turnKey=${chatState.turnKey} ` +
-        `narratives=${s.narratives.length} items=${s.items.length} latestText_len=${s.latestText?.length ?? 0} ` +
-        `subagents=${s.subAgents.size} pendingPreamble=${s.pendingPreamble ? 'yes' : 'no'} forceDone=${forceDone}\n`,
-      )
-    }
-    if (html === chatState.lastEmittedHtml && !forceDone) return
-    chatState.lastEmittedHtml = html
-    chatState.lastEmittedAt = now()
-    recordEdit(chatState.turnKey)
-    const isFirst = chatState.isFirstEmit
-    chatState.isFirstEmit = false
-    // Notification-spam fix (2026-04-23): never emit done=true while the
-    // card is still waiting on in-flight sub-agents. The reducer sets
-    // `stage='done'` the moment parent turn_end lands, so a naive
-    // `done: stage==='done'` passes done=true on every subsequent sub-
-    // agent event. handleStreamReply finalizes + deletes the draft
-    // stream after every done=true call, so the NEXT emit creates a
-    // fresh sendMessage — which Telegram delivers as a new push
-    // notification. Ken observed ~13 identical "✅ Done" notifications
-    // while two parallel review sub-agents were grinding.
-    //
-    // Safe to gate on `hasAnyRunningSubAgent`: the completion paths
-    // (`completeTurnFully` / `closeZombie` / `maybeCompleteDeferredTurn`)
-    // either (a) ran when no sub-agents are running or (b) explicitly
-    // marked every running sub-agent as done in the reducer state BEFORE
-    // the final flush. Including orphans here keeps `done=true` suppressed
-    // while a background dispatch is still active (closes #87).
-    const terminal =
-      (forceDone || chatState.state.stage === 'done')
-      && !hasAnyRunningSubAgent(chatState.state)
-    config.emit({
-      chatId: chatState.chatId,
-      threadId: chatState.threadId,
-      turnKey: chatState.turnKey,
-      html,
-      done: terminal,
-      isFirstEmit: isFirst,
-      // Thread the source message_id through on the first emit only so
-      // the caller can pass it as reply_parameters on the initial
-      // sendMessage. Edits (isFirstEmit=false) must NOT carry it.
-      ...(isFirst && chatState.replyToMessageId != null
-        ? { replyToMessageId: chatState.replyToMessageId }
-        : {}),
-    })
-    // #card-audit-log: structured lifecycle entry for retroactive audit.
-    // Mirrors the existing free-text traces but is grep-able by turnKey.
-    emitCardEvent({
-      agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-      chatId: chatState.chatId ?? '',
-      turnKey: chatState.turnKey,
-      event: isFirst ? 'rendered' : (terminal ? 'finalized' : 'edited'),
-      reason: terminal ? 'flush-terminal' : (isFirst ? 'flush-first' : 'flush-edit'),
-      htmlHash: html.length > 0
-        ? createHash('sha1').update(html).digest('hex').slice(0, 12)
-        : undefined,
-    })
-  }
-
-  /**
-   * Promote a card out of the initial-delay suppression window early.
-   * Idempotent — short-circuits if the card has already emitted, the
-   * delay has already elapsed, or the card is terminal.
-   *
-   * Sets `deferredFirstEmitTimer = DELAY_ELAPSED` so the very next
-   * `flush()` call bypasses the suppression branch and emits a real
-   * card render. Cancels any in-flight deferred timer to prevent a
-   * second emit when the original `initialDelayMs` clock would have
-   * fired. Calls `flush()` directly so the card surfaces immediately.
-   *
-   * Used by:
-   *   - sub-agent state diff in `ingest()` when a sub-agent transitions
-   *     to running during the suppression window
-   *   - the enqueue branch when carriedOver running sub-agents seed the
-   *     fresh PerChatState (#334 cross-turn carry-over)
-   *   - `onSubAgentStall()` when a watcher reports a stalled sub-agent
-   *     before the card has emitted
-   */
-  function promoteFirstEmit(cs: PerChatState, reason: string): void {
-    if (!cs.isFirstEmit) return
-    if (cs.deferredFirstEmitTimer === DELAY_ELAPSED) return
-    if (cs.apiFailures.terminal) return
-    if (cs.deferredFirstEmitTimer != null) {
-      clearT(cs.deferredFirstEmitTimer)
-    }
-    if (cs.timePromoteTimer != null) {
-      clearT(cs.timePromoteTimer)
-      cs.timePromoteTimer = null
-    }
-    cs.deferredFirstEmitTimer = DELAY_ELAPSED
-    process.stderr.write(
-      `telegram gateway: progress-card: promoteFirstEmit turnKey=${cs.turnKey} reason=${reason}\n`,
-    )
-    flush(cs, /*forceDone*/ false)
-  }
-
-  /**
-   * F3 fix (#553): schedule a one-shot timer that force-promotes the
-   * card after `promoteAfterMs` if no other promotion path has fired
-   * by then. Idempotent — safe to call repeatedly. The timer is
-   * cleared by `promoteFirstEmit` (so the existing promotion paths
-   * still win when they fire first) and at turn end.
-   *
-   * Without this proactive timer, a long single-tool turn (e.g. one
-   * 10s Bash) never crosses any existing promotion threshold and
-   * the card stays suppressed until `initialDelayMs` (30s by
-   * default). Fast-turn-suppression then cancels it on `turn_end`.
-   */
-  function ensureTimePromoteScheduled(cs: PerChatState): void {
-    if (!cs.isFirstEmit) return
-    if (cs.deferredFirstEmitTimer === DELAY_ELAPSED) return
-    if (cs.apiFailures.terminal) return
-    if (cs.timePromoteTimer != null) return
-    if (promoteAfterMs <= 0) return
-    const elapsed = now() - cs.state.turnStartedAt
-    const remaining = Math.max(0, promoteAfterMs - elapsed)
-    const capturedTurnKey = cs.turnKey
-    cs.timePromoteTimer = setT(() => {
-      if (!chats.has(capturedTurnKey)) return
-      const cs2 = chats.get(capturedTurnKey)!
-      cs2.timePromoteTimer = null
-      // Idempotency belt-and-braces: promoteFirstEmit no-ops if already
-      // promoted by another path between scheduling and firing.
-      promoteFirstEmit(cs2, `time_${promoteAfterMs}ms`)
-    }, remaining)
-  }
-
-  /**
-   * True if `a` and `b` differ in any field that actually appears in the
-   * rendered card (items, stage, userRequest, latestText). Internal
-   * bookkeeping fields like `thinking` that don't reach render() don't
-   * count — we don't want to waste a Telegram edit on them.
-   */
-  function visibleDiff(a: ProgressCardState, b: ProgressCardState): boolean {
-    if (a.stage !== b.stage) return true
-    if (a.userRequest !== b.userRequest) return true
-    if (a.latestText !== b.latestText) return true
-    if (a.items.length !== b.items.length) return true
-    for (let i = 0; i < a.items.length; i++) {
-      if (a.items[i].state !== b.items[i].state) return true
-      if (a.items[i].tool !== b.items[i].tool) return true
-      // Multi-agent: spawnedAgentId attached on correlation matters for
-      // the [Main] line's 🤖 vs ✅ glyph (PR 3 renderer).
-      if (a.items[i].spawnedAgentId !== b.items[i].spawnedAgentId) return true
-    }
-    // Multi-agent: any change in sub-agent shape or per-sub-agent state
-    // is user-visible. Cheap O(N) scan; N is the sub-agent count, which
-    // is bounded by how many parallel Agent calls one turn makes (~4–12
-    // in practice).
-    if (a.subAgents.size !== b.subAgents.size) return true
-    for (const [k, sa] of a.subAgents) {
-      const sb = b.subAgents.get(k)
-      if (!sb) return true
-      if (sa.state !== sb.state) return true
-      if (sa.toolCount !== sb.toolCount) return true
-      if (sa.description !== sb.description) return true
-      if (sa.parentToolUseId !== sb.parentToolUseId) return true
-      if (sa.nestedSpawnCount !== sb.nestedSpawnCount) return true
-      if ((sa.currentTool?.toolUseId ?? null) !== (sb.currentTool?.toolUseId ?? null)) return true
-      if (sa.currentNarrative !== sb.currentNarrative) return true
-    }
-    return false
-  }
-
-  // P0 of #662 — shadow fleet maintenance. Mutates cs.fleet in place
-  // by replacing entries with new immutable FleetMember objects from the
-  // pure transition functions in fleet-state.ts.
-  function updateFleetForEvent(cs: PerChatState, event: SessionEvent): void {
-    switch (event.kind) {
-      case 'tool_use': {
-        // P2 of #662 — capture the run_in_background flag from parent
-        // Agent/Task dispatches. The flag is keyed by parentToolUseId
-        // so the matching sub_agent_started (which gets the same id
-        // wired in via the reducer's pendingAgentSpawns adoption) can
-        // look it up when creating the fleet member.
-        if (
-          (event.toolName === 'Agent' || event.toolName === 'Task') &&
-          event.toolUseId &&
-          event.input?.run_in_background === true
-        ) {
-          cs.backgroundParentToolUseIds.add(event.toolUseId)
-        }
-        return
-      }
-      case 'sub_agent_started': {
-        // Idempotent — late duplicates of the same agentId keep the
-        // original startedAt + originatingTurnKey snapshot.
-        if (cs.fleet.has(event.agentId)) return
-        const role = roleFromDispatch(undefined, event.subagentType, event.firstPromptText)
-        // P2: derive background status from the parent dispatch flag.
-        // The reducer at progress-card.ts:706 already correlated the
-        // matching pendingAgentSpawn and wrote parentToolUseId into the
-        // fresh subagent state — read it back here so the fleet reflects
-        // the dispatch's run_in_background flag.
-        const parentToolUseId = cs.state.subAgents.get(event.agentId)?.parentToolUseId ?? null
-        const isBackground =
-          parentToolUseId != null && cs.backgroundParentToolUseIds.has(parentToolUseId)
-        const member = createFleetMember({
-          agentId: event.agentId,
-          role,
-          startedAt: now(),
-          originatingTurnKey: currentTurnKey ?? cs.turnKey,
-          isBackgroundDispatch: isBackground,
-        })
-        cs.fleet.set(event.agentId, isBackground ? { ...member, status: 'background' } : member)
-        return
-      }
-      case 'sub_agent_tool_use': {
-        const m = cs.fleet.get(event.agentId)
-        if (m == null) return
-        cs.fleet.set(event.agentId, fleetApplyToolUse(m, event.toolName, event.input, now()))
-        return
-      }
-      case 'sub_agent_tool_result': {
-        const m = cs.fleet.get(event.agentId)
-        if (m == null) return
-        cs.fleet.set(event.agentId, fleetApplyToolResult(m, event.isError))
-        return
-      }
-      case 'sub_agent_turn_end': {
-        const m = cs.fleet.get(event.agentId)
-        if (m == null) return
-        cs.fleet.set(event.agentId, fleetApplyTurnEnd(m, now()))
-        return
-      }
-      case 'sub_agent_capped': {
-        // The sub-agent transcript was truncated mid-flight: >= threshold
-        // tool_uses with no terminal record. Transition the fleet member to
-        // `capped` so the progress card shows a terminal "capped" row instead
-        // of hanging "running" indefinitely. Also drive the legacy reducer via
-        // sub_agent_turn_end so the subAgents map stays consistent.
-        const m = cs.fleet.get(event.agentId)
-        if (m != null) {
-          cs.fleet.set(event.agentId, fleetApplyCapped(m, now()))
-        }
-        // Mirror into the legacy reducer so render() sees the agent as done.
-        cs.state = reduce(cs.state, { kind: 'sub_agent_turn_end', agentId: event.agentId }, now())
-        return
-      }
-      default:
-        return
-    }
-  }
-
-  // Cardinality reconciler: the legacy state.subAgents map can grow
-  // through paths the fleet shadow doesn't know about (parent Agent
-  // tool_use synthesised correlations, heartbeat orphan promotions,
-  // cross-turn carry-over). Mirror those into fleet so the invariant
-  // that `fleet` is a superset-or-equal of `subAgents` (by key) holds.
-  function reconcileFleetWithSubAgents(cs: PerChatState): void {
-    for (const [agentId, sa] of cs.state.subAgents) {
-      if (!cs.fleet.has(agentId)) {
-        // P0 follow-up (#662 reviewer items 1+2): preserve `startedAt`
-        // from the legacy SubAgentState when present so the synthesised
-        // carry-over entry doesn't reset the clock and immediately mask
-        // a stuck condition. `originatingTurnKey` has no legacy
-        // counterpart — fall back to the current/active turn.
-        const startedAt = sa.startedAt > 0 ? sa.startedAt : now()
-        const isBg =
-          sa.parentToolUseId != null &&
-          cs.backgroundParentToolUseIds.has(sa.parentToolUseId)
-        cs.fleet.set(
-          agentId,
-          createFleetMember({
-            agentId,
-            role: sa.description ?? 'agent',
-            startedAt,
-            originatingTurnKey: currentTurnKey ?? cs.turnKey,
-            isBackgroundDispatch: isBg,
-          }),
-        )
-      }
-    }
-    // Drop fleet entries the legacy map no longer tracks (rare — only
-    // when a parent tool_result correlation prunes a sub-agent before
-    // any sub_agent_turn_end arrived).
-    for (const agentId of [...cs.fleet.keys()]) {
-      if (!cs.state.subAgents.has(agentId)) {
-        cs.fleet.delete(agentId)
-      }
-    }
-  }
-
-  return {
-    ingest(event, chatIdMaybe, threadId) {
-      // Throttled inline TTL sweep — see `maybeEvict` for rationale.
-      maybeEvict(now())
-      // An `enqueue` event carries its own chatId (extracted from the XML
-      // channel wrapper). Everything else falls back to the caller-provided
-      // chatIdMaybe, which the session-tail supervisor tracks.
-      let chatId = chatIdMaybe
-      if (event.kind === 'enqueue') {
-        chatId = event.chatId
-        threadId = event.threadId ?? undefined
-
-        // Skip enqueue events with no chatId. These come from non-channel
-        // turns (e.g. terminal input) forwarded by the bridge's session-tail.
-        // Creating a card with chatId=null spams "chat null is not allowlisted"
-        // on every emit attempt and produces a ghost card that occupies
-        // currentTurnKey, potentially interfering with real card routing.
-        if (chatId == null || chatId === '') return
-
-        // A session-tail enqueue (isSync not set) arriving while a card is
-        // already live for the same chat+thread is an echo of a sync
-        // startTurn() call — drop it. startTurn owns the turn lifecycle for
-        // non-steering messages; if we fell through we'd orphan the pinned
-        // card and spawn a second "Working…" message that takes over all
-        // the updates while the original stays stuck at 0ms.
-        if (!event.isSync) {
-          // Guard 0 (messageId dedup): if we've already seen an enqueue
-          // with this messageId for this chat+thread, drop it. Session
-          // restarts can produce multiple echoes of the same user message
-          // (each restart re-processes the queue, writing a fresh enqueue
-          // to a new JSONL). Guard 2 only catches the first; this guard
-          // catches all subsequent duplicates by messageId.
-          if (event.messageId != null) {
-            const base = baseKey(chatId, threadId ?? undefined)
-            const dedupKey = `${base}:${event.messageId}`
-            const seenAt = seenEnqueueMsgIds.get(dedupKey)
-            if (seenAt != null && now() - seenAt < 60_000) {
-              return
-            }
-            seenEnqueueMsgIds.set(dedupKey, now())
-          }
-
-          // Guard 1: active card exists for this chat+thread.
-          // P2 of #662 / fixes #64 — except when the active card is a
-          // background-carry state (turn ended, fleet still has live bg
-          // members). The new enqueue is a real follow-up turn that must
-          // create a fresh PerChatState; the bg carry stays alive in
-          // parallel under its own turnKey.
-          if (currentTurnKey != null) {
-            const existing = chats.get(currentTurnKey)
-            if (
-              existing != null &&
-              existing.chatId === chatId &&
-              existing.threadId === threadId &&
-              !hasLiveBackground(existing.fleet)
-            ) {
-              return
-            }
-          }
-          // Guard 2: this enqueue is the session-tail echo of a sync
-          // startTurn() call. Drop it and consume the marker. Without
-          // this, fast turns that complete before the echo arrives would
-          // pass Guard 1 (currentTurnKey already null) and spawn an
-          // orphan card.
-          const base = baseKey(chatId, threadId ?? undefined)
-          const syncStart = pendingSyncEchoes.get(base)
-          if (syncStart != null && now() - syncStart < 30_000) {
-            pendingSyncEchoes.delete(base)
-            return
-          }
-        }
-
-        // Allocate a new turn slot FIRST — this increments baseTurnSeqs so
-        // that taskNumFor() on the old card will see the correct total (N+1)
-        // when we render its final "done" frame below.
-        const slot = allocateTurnSlot(chatId, threadId)
-
-        // If an existing card is still active for this chat, force-close it
-        // so it gets properly done/unpinned before the new card takes over.
-        // Also close ghost cards (chatId is null/empty) — these come from
-        // non-channel session-tail events that slipped through before the
-        // null guard above was added, or from a race.
-        //
-        // Route through closeZombie so any still-running sub-agents on
-        // the old card are explicitly marked done (abandoned) and the
-        // shared completion sequence fires exactly once. This is the
-        // correct path for "new turn replacing old" even when the old
-        // turn was in pendingCompletion state (background sub-agent
-        // hadn't reported done yet).
-        // P2 of #662 / fixes #64 — if the in-flight turn has live
-        // background fleet members, do NOT closeZombie it. Detach it
-        // from currentTurnKey instead so the new turn takes over the
-        // active slot while turn A's PerChatState stays alive in `chats`
-        // to receive cross-turn sub_agent_* events. Mark it with
-        // backgroundCarry so completion fires once the last live bg
-        // member reaches terminal status.
-        let bgCarryActive = false
-        if (currentTurnKey != null) {
-          const existing = chats.get(currentTurnKey)
-          if (existing != null && (existing.chatId === chatId || !existing.chatId)) {
-            if (hasLiveBackground(existing.fleet)) {
-              existing.backgroundCarry = true
-              bgCarryActive = true
-              process.stderr.write(
-                `telegram gateway: progress-card: bg-carry preserving turnKey=${existing.turnKey} (live background fleet members) on new enqueue\n`,
-              )
-            } else {
-              closeZombie(existing)
-            }
-          }
-        }
-        currentChatId = chatId
-        currentThreadId = threadId
-        currentTurnKey = slot.turnKey
-
-        // Issue #334: seed the new turn's subAgents from any still-running
-        // background sub-agents dispatched in a prior turn for this chat.
-        const initialTurnState = reduce(initialState(), event, now())
-        const cBaseKey = baseKey(chatId, threadId)
-        // P2 of #662 — when bg carry is active, the originating PerChatState
-        // still owns the running sub-agents. Don't re-seed turn B with them
-        // (would duplicate the fleet entries and cause turn B to defer its
-        // own completion waiting for sub-agents that don't belong to it).
-        const carriedOver = bgCarryActive ? undefined : chatRunningSubagents.get(cBaseKey)
-        const seededState: ProgressCardState = (carriedOver != null && carriedOver.size > 0)
-          ? {
-              ...initialTurnState,
-              subAgents: new Map<string, SubAgentState>(
-                [...carriedOver.entries()].map(([id, sa]) => [id, { ...sa }]),
-              ),
-            }
-          : initialTurnState
-
-        const chatState: PerChatState = {
-          chatId,
-          threadId,
-          turnKey: slot.turnKey,
-          taskIndex: slot.index,
-          taskTotal: slot.total,
-          state: seededState,
-          lastEmittedAt: 0,
-          lastEmittedHtml: null,
-          pendingTimer: null,
-          isFirstEmit: true,
-          deferredFirstEmitTimer: null,
-          effectiveInitialDelayMs: initialDelayMs,
-          timePromoteTimer: null,
-          lastEventAt: now(),
-          pendingCompletion: false,
-          completionFired: false,
-          cardTakenOver: false,
-          apiFailures: { consecutive4xx: 0, lastError: null, terminal: false },
-          replyToolCalled: false,
-          outboundDeliveredCount: 0,
-          wasAutonomous: false,
-          silentEndSuppressed: false,
-          silentEndPrepared: false,
-          parentTurnEndAt: null,
-          parentDoneRendered: false,
-          promotedSpawnIds: new Set(),
-          fleet: new Map<string, FleetMember>(),
-          backgroundParentToolUseIds: new Set<string>(),
-          backgroundCarry: false,
-        }
-        chats.set(slot.turnKey, chatState)
-        if (event.isSync) {
-          pendingSyncEchoes.set(baseKey(chatId, threadId), now())
-        }
-        startHeartbeatIfNeeded()
-        // #334 cross-turn carry-over: a fresh PerChatState seeded with
-        // running sub-agents from a prior turn already has visible work
-        // to surface. Skip suppression and emit immediately. The diff-
-        // based promote in the reducer block above misses this case
-        // because the carried-over sub-agents were copied during
-        // `initialState()` reduction — there is no prev→next transition
-        // for it to detect.
-        //
-        // Defensive: post-#401, `closeZombie` syncs the chat-scoped
-        // registry on every parent-replacement enqueue, so carriedOver
-        // is empty in the common path. Keeping the hook means future
-        // regressions in the sync path (or a code path that bypasses
-        // closeZombie) still produce a visible card instead of a
-        // silently-suppressed turn.
-        if (promoteOnSubAgent && carriedOver != null && carriedOver.size > 0) {
-          promoteFirstEmit(chatState, 'carried_over_subagents')
-        } else {
-          flush(chatState, /*forceDone*/ false)
-        }
-        return
-      } else if (chatId == null) {
-        // Non-enqueue event with no explicit chat: fall back to the
-        // most recently enqueued chat for this driver.
-        chatId = currentChatId
-        threadId = threadId ?? currentThreadId
-      }
-      if (chatId == null) return
-
-      // P2 of #662 / fixes #64 — sub_agent_* events for an agentId whose
-      // fleet member lives on a non-current PerChatState (background
-      // carry) must route to the originating turn, not currentTurnKey.
-      // Without this, a background sub-agent that emits tool_use after
-      // its parent turn ended (and a new turn took over) would either
-      // be dropped or update the wrong turn's card.
-      let chatState: PerChatState | undefined
-      if (
-        (event.kind === 'sub_agent_tool_use' ||
-          event.kind === 'sub_agent_tool_result' ||
-          event.kind === 'sub_agent_turn_end' ||
-          event.kind === 'sub_agent_capped' ||
-          event.kind === 'sub_agent_started') &&
-        'agentId' in event
-      ) {
-        const agentId = (event as { agentId: string }).agentId
-        for (const candidate of chats.values()) {
-          if (candidate.chatId !== chatId) continue
-          if (candidate.fleet.has(agentId)) {
-            chatState = candidate
-            break
-          }
-        }
-      }
-
-      // Route to the current active turn key. Drop late events for a turn
-      // that already ended — without this, a stray tool_result after turn_end
-      // would resurrect the card. currentTurnKey is cleared on turn_end.
-      if (chatState == null) {
-        const k = currentTurnKey
-        if (k == null) {
-          if (event.kind.startsWith('sub_agent_')) {
-            process.stderr.write(
-              `telegram gateway: progress-card: late-sub-agent-event-dropped kind=${event.kind} agentId=${'agentId' in event ? (event as { agentId: string }).agentId : 'n/a'} chatId=${chatId}\n`,
-            )
-          }
-          return
-        }
-        chatState = chats.get(k)
-        if (chatState == null) return
-      }
-
-      const prev = chatState.state
-      chatState.state = reduce(chatState.state, event, now())
-      chatState.lastEventAt = now()
-
-      // P0 of #662 — shadow fleet map. Mirror sub_agent_* events into
-      // the parallel FleetMember map using the pure transitions from
-      // fleet-state.ts. Legacy state.subAgents is unchanged; P1/P2/P3
-      // build on `fleet` without touching the existing renderer.
-      updateFleetForEvent(chatState, event)
-      // Reconcile shadow with legacy map: any sub-agent that appears in
-      // state.subAgents (e.g. via parent-tool-result correlation, the
-      // heartbeat orphan-promotion path, or carry-over) but is missing
-      // from fleet gets a synthetic FleetMember so the cardinality
-      // invariant holds. Conversely, drop fleet entries that legacy
-      // dropped (these are already terminal in the watcher's view).
-      reconcileFleetWithSubAgents(chatState)
-      const stageChanged = chatState.state.stage !== prev.stage
-      const visibleChanged = visibleDiff(prev, chatState.state)
-
-      // Issue #334/#399: mirror sub-agent state changes into the chat-scoped
-      // running-sub-agent registry so new turns can seed from it.
-      // We diff prev.subAgents vs chatState.state.subAgents to catch all
-      // mutation paths: sub_agent_started, sub_agent_turn_end, and parent
-      // tool_result (which can finalize a sub-agent via parentToolUseId).
-      // Factored into syncChatRunningSubagents (issue #399) so closeZombie
-      // and the heartbeat's cold-jsonl-synth path can call the same logic.
-      // Returns `newRunningAppeared` so the caller can promote the card
-      // out of initial-delay suppression on a fresh sub-agent transition.
-      const { newRunningAppeared: newRunningSubAgentAppeared } = syncChatRunningSubagents(
-        prev,
-        chatState.state,
-        baseKey(chatState.chatId, chatState.threadId),
-        chatRunningSubagents,
-      )
-
-      // Promote the card out of initial-delay suppression as soon as a
-      // sub-agent transitions to running. Long-running sub-agent dispatches
-      // are exactly the case where the user wants to see what's happening
-      // — waiting the full `initialDelayMs` before showing the card means
-      // 30s of staring at a frozen draft bubble. Diff-based detection
-      // (rather than gating on a specific event kind) catches every path
-      // that reaches `running`: real `sub_agent_started`, heartbeat orphan
-      // promotion, and parent-tool-result correlation.
-      if (
-        newRunningSubAgentAppeared
-        && promoteOnSubAgent
-        && chatState.isFirstEmit
-        && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED
-        && !chatState.apiFailures.terminal
-      ) {
-        promoteFirstEmit(chatState, 'sub_agent_started')
-      }
-
-      // #842: explicit background dispatch bypass. When the parent calls
-      // `Agent({ run_in_background: true })`, swap the active delay
-      // budget over to `initialDelayMsBackground` instead of the longer
-      // `initialDelayMs`. Detection: an Agent/Task tool_use whose
-      // `event.input.run_in_background === true` (the same flag
-      // `updateFleetForEvent` uses to populate
-      // `cs.backgroundParentToolUseIds` for fleet membership).
-      //
-      // - `initialDelayMsBackground === 0` (default) → promote now.
-      // - `initialDelayMsBackground > 0` → set
-      //   `cs.effectiveInitialDelayMs` so the next flush() schedules
-      //   (or reschedules) the deferred timer at the lower budget.
-      //   Never lengthens an existing budget.
-      if (
-        event.kind === 'tool_use'
-        && (event.toolName === 'Agent' || event.toolName === 'Task')
-        && event.toolUseId != null
-        && event.input?.run_in_background === true
-        && chatState.isFirstEmit
-        && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED
-        && !chatState.apiFailures.terminal
-      ) {
-        if (initialDelayMsBackground <= 0) {
-          promoteFirstEmit(chatState, 'background_dispatch')
-        } else if (initialDelayMsBackground < chatState.effectiveInitialDelayMs) {
-          chatState.effectiveInitialDelayMs = initialDelayMsBackground
-          // If a longer-budget timer is already scheduled, cancel and
-          // reschedule against the new budget. Compute the remaining
-          // gap from turn start; if we're already past it, promote.
-          if (chatState.deferredFirstEmitTimer != null) {
-            const elapsed = now() - chatState.state.turnStartedAt
-            const remaining = initialDelayMsBackground - elapsed
-            clearT(chatState.deferredFirstEmitTimer)
-            if (remaining <= 0) {
-              chatState.deferredFirstEmitTimer = null
-              promoteFirstEmit(chatState, 'background_dispatch_elapsed')
-            } else {
-              const capturedTurnKey = chatState.turnKey
-              process.stderr.write(
-                `telegram gateway: progress-card: rescheduled initial-delay timer turnKey=${capturedTurnKey} delay=${remaining}ms reason=background_dispatch\n`,
-              )
-              chatState.deferredFirstEmitTimer = setT(() => {
-                if (!chats.has(capturedTurnKey)) return
-                chatState.deferredFirstEmitTimer = DELAY_ELAPSED
-                process.stderr.write(
-                  `telegram gateway: progress-card: initial-delay timer fired turnKey=${capturedTurnKey} reason=background_dispatch\n`,
-                )
-                flush(chatState, false)
-              }, remaining)
-            }
-          }
-        }
-      }
-
-      // #478 / #553 PR 4: promote the card when the agent has issued
-      // enough parent-side tool calls during the suppression window.
-      // Disabled by default in v2 (promoteOnParentToolCount=0 / Infinity)
-      // — under the v2 contract tools alone never trigger the card. The
-      // check is preserved as a config knob for callers that want the
-      // old behaviour, but values of 0 or non-finite (Infinity) are
-      // treated as "never promote on tool count".
-      if (
-        promoteOnParentToolCount > 0
-        && Number.isFinite(promoteOnParentToolCount)
-        && chatState.isFirstEmit
-        && chatState.deferredFirstEmitTimer !== DELAY_ELAPSED
-        && !chatState.apiFailures.terminal
-        && chatState.state.items.length >= promoteOnParentToolCount
-      ) {
-        promoteFirstEmit(chatState, `parent_tool_count_${chatState.state.items.length}`)
-      }
-
-      // F3 fix (#553): schedule the time-based promotion timer on
-      // every ingest event (idempotent — only the first call schedules;
-      // subsequent calls are no-ops). Without this, a long single-tool
-      // turn never crossed parent_tool_count or sub_agent thresholds
-      // and the card stayed suppressed until initialDelayMs (30s).
-      ensureTimePromoteScheduled(chatState)
-
-      // Issue #132: track whether the agent has called `reply` or
-      // `stream_reply` at least once this turn so the renderer can
-      // distinguish "Done with reply" from "Done without reply" at
-      // turn_end. Tool-use intent is the right granularity here — if
-      // the call landed but failed mid-API, the model sees the error
-      // in tool_result and may retry, which still flips this true.
-      // Only false → true; never reset mid-turn.
-      if (
-        !chatState.replyToolCalled
-        && event.kind === 'tool_use'
-        && isTelegramReplyTool(event.toolName)
-      ) {
-        chatState.replyToolCalled = true
-      }
-
-      // Issue #81 diagnostic: when a 'text' event lands, did the reducer
-      // recognize it as a narrative step? If narratives.length didn't grow,
-      // the card's "human-readable preamble" path can't render and the
-      // tool-count fallback wins. The log lets us correlate "user typed
-      // status?" telemetry with the missing narrative path.
-      //
-      // Gated behind PROGRESS_CARD_DIAG=1 because this fires on every
-      // assistant text event — a long verbose turn could produce dozens
-      // of lines per minute. The render-branch and prose-recovery diags
-      // (~2x and ~1x per turn respectively) stay always-on. Flip the env
-      // var on a one-off agent restart to capture data, then turn it off.
-      if (event.kind === 'text' && process.env.PROGRESS_CARD_DIAG === '1') {
-        const before = prev.narratives.length
-        const after = chatState.state.narratives.length
-        const last = chatState.state.narratives[after - 1]
-        const preview = last?.text ? last.text.slice(0, 60).replace(/\n/g, ' ') : ''
-        const took = before === after ? 'discarded' : 'captured'
-        process.stderr.write(
-          `progress-card.diag: text-event ${took} chatId=${chatState.chatId} turnKey=${chatState.turnKey} ` +
-          `narratives_before=${before} narratives_after=${after} text_len=${event.text.length} preview=${JSON.stringify(preview)}\n`,
-        )
-      }
-
-      // Cancel any pending coalesce timer — we'll either fire now or
-      // reschedule.
-      if (chatState.pendingTimer != null) {
-        clearT(chatState.pendingTimer)
-        chatState.pendingTimer = null
-      }
-
-      // Fire immediately on terminal state — no coalesce delay when the
-      // turn finishes. The user sees the final card the instant turn_end
-      // lands. (Note: `enqueue` events are handled upstream by startTurn,
-      // not ingested here, so the prior `event.kind === 'enqueue'` check
-      // was dead code per the SessionEvent union.)
-      if (event.kind === 'turn_end' || stageChanged) {
-        if (event.kind === 'turn_end') {
-          process.stderr.write(`telegram gateway: progress-card: turn_end flush chatId=${chatState.chatId} threadId=${chatState.threadId ?? '-'} turnKey=${chatState.turnKey}\n`)
-          // Only fire silent-end prep when we're actually about to complete —
-          // i.e. no sub-agents still running. The sub-agent defer path
-          // returns below and prep will run later via maybeCompleteDeferredTurn.
-          if (!hasAnyRunningSubAgent(chatState.state)) {
-            prepareSilentEndSuppression(chatState)
-          }
-        }
-        if (event.kind === 'turn_end' && hasAnyRunningSubAgent(chatState.state)) {
-          // Gap 8: parent turn_end with sub-agents still running — render
-          // done=true immediately (card shows ✅ Done) then defer unpin.
-          // Set parentTurnEndAt BEFORE flush so flush()'s parentDone
-          // computation picks it up on this very call.
-          chatState.parentTurnEndAt = now()
-        }
-        flush(chatState, /*forceDone*/ event.kind === 'turn_end')
-        if (event.kind === 'turn_end') {
-          // Gate on BOTH the legacy subAgents map AND the fleet's background
-          // members. Background sub-agents (dispatched with run_in_background:true)
-          // are tagged in cs.fleet with status:'background' by updateFleetForEvent
-          // at sub_agent_started time. If the parent turn_end fires before the
-          // background sub-agent has produced any events, state.subAgents may
-          // still be empty for that agent — hasAnyRunningSubAgent alone would
-          // miss it and close the card prematurely. Fixes #713 and #709.
-          if (hasAnyRunningSubAgent(chatState.state) || hasLiveBackground(chatState.fleet)) {
-            // Parent turn ended but at least one sub-agent is still running.
-            // Keep the card alive so the sub-agent work stays visible; defer
-            // completion until the last running sub-agent reports done via
-            // its own sub_agent_turn_end (or the parent Agent tool_result).
-            // Closes #87: orphans from `Agent({run_in_background:true})` now
-            // gate the defer too, so background dispatches stay visible past
-            // parent turn-end. Safety nets: `closeZombie` on new enqueue +
-            // the `maxIdleMs` heartbeat ceiling bound the bad case (orphan
-            // never reports done).
-            chatState.pendingCompletion = true
-            const correlated: string[] = []
-            const orphans: string[] = []
-            const background: string[] = []
-            for (const [k, sa] of chatState.state.subAgents) {
-              if (sa.state === 'running') {
-                if (sa.parentToolUseId != null) correlated.push(k)
-                else orphans.push(k)
-              }
-            }
-            for (const [k, m] of chatState.fleet) {
-              if (m.status === 'background' && m.terminalAt == null) background.push(k)
-            }
-            process.stderr.write(`telegram gateway: progress-card: turn_end deferred turnKey=${chatState.turnKey} reason=in-flight-sub-agents correlated=${correlated.length} orphans=${orphans.length} background=${background.length} correlatedAgentIds=[${correlated.join(',')}] orphanAgentIds=[${orphans.join(',')}] backgroundAgentIds=[${background.join(',')}]\n`)
-            emitCardEvent({
-              agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-              chatId: chatState.chatId ?? '',
-              turnKey: chatState.turnKey,
-              event: 'deferred',
-              reason: `turn_end: in-flight-sub-agents correlated=${correlated.length} orphans=${orphans.length} background=${background.length}`,
-              subagents: [...correlated, ...orphans, ...background],
-            })
-            return
-          }
-          closePerChat(chatState, 'turn-end')
-        }
-        return
-      }
-
-      // Post-reduce deferred-completion check: if this event transitioned
-      // the last in-flight sub-agent to done (sub_agent_turn_end, parent
-      // Agent tool_result), fire completion now.
-      maybeCompleteDeferredTurn(chatState)
-
-      // If this event didn't change anything user-visible (e.g. a
-      // `thinking` flag toggle that isn't rendered), don't schedule a
-      // flush. Prevents emit noise from events that only mutate internal
-      // state, and avoids spurious edits driven by ticking elapsed time
-      // in the header.
-      if (!visibleChanged) return
-
-      // Otherwise: respect the min-interval floor. If we just emitted,
-      // defer to at least minIntervalMs after the last emit. Also always
-      // coalesce bursts — even a burst that runs past minIntervalMs gets
-      // at most one flush per coalesce window.
-      //
-      // Multi-agent rate-limit: if the chat has emitted >threshold edits
-      // in the last 60s, expand the coalesce window to
-      // editBudgetCoalesceMs (default 3s) so the Telegram 20/min cap is
-      // never exceeded by sub-agent bursts.
-      const sinceLast = now() - chatState.lastEmittedAt
-      const effectiveCoalesce = isBudgetHot(chatState.turnKey) ? editBudgetCoalesceMs : coalesceMs
-      const delay = Math.max(effectiveCoalesce, minIntervalMs - sinceLast, 0)
-      const capturedTurnKey = chatState.turnKey
-      chatState.pendingTimer = setT(() => {
-        // Defensive: if the chat was deleted between schedule and fire
-        // (e.g. a turn_end racing with an async boundary added later),
-        // don't resurrect it with a stale flush.
-        if (!chats.has(capturedTurnKey)) return
-        chatState!.pendingTimer = null
-        flush(chatState!, /*forceDone*/ false)
-      }, delay)
-    },
-
-    startTurn({ chatId, threadId, userText, replyToMessageId }) {
-      // Synthesize an enqueue event and run it through the normal ingest
-      // path. This guarantees we share all the flush/cadence/teardown
-      // semantics with session-tail-driven enqueues.
-      //
-      // Each call creates a NEW card — if a card is already active for
-      // this chat it is force-closed first so it gets properly done/unpinned.
-      const raw = `<channel source="switchroom-telegram" chat_id="${chatId}"${threadId != null ? ` message_thread_id="${threadId}"` : ''}>${userText}</channel>`
-      this.ingest(
-        {
-          kind: 'enqueue',
-          chatId,
-          messageId: null,
-          threadId: threadId ?? null,
-          rawContent: raw,
-          isSync: true,
-        },
-        chatId,
-        threadId,
-      )
-      // Stash the source message_id and autonomous flag on the newly-created
-      // PerChatState so flush() can use them. Do this AFTER ingest() so the
-      // new PerChatState entry is in chats.
-      if (currentTurnKey != null) {
-        const cs = chats.get(currentTurnKey)
-        if (cs != null && cs.chatId === chatId) {
-          if (replyToMessageId != null) {
-            cs.replyToMessageId = replyToMessageId
-          }
-          // Issue #259: autonomous wakeup turns (ScheduleWakeup / CronCreate
-          // sentinel) never produce a user-visible reply by design. Suppress
-          // the "🙊 Ended without reply" warning for these turns.
-          if (userText.startsWith('<<autonomous-loop')) {
-            cs.wasAutonomous = true
-          }
-        }
-      }
-    },
-
-    forceCompleteTurn({ chatId, threadId }) {
-      // Find active chatState for this chat:thread. Prefer the one pointed
-      // at by currentTurnKey; fall back to any state matching the chat key.
-      let target: PerChatState | undefined
-      if (currentTurnKey != null) {
-        const cs = chats.get(currentTurnKey)
-        if (cs != null && cs.chatId === chatId && cs.threadId === threadId) {
-          target = cs
-        }
-      }
-      if (target == null) {
-        for (const cs of chats.values()) {
-          if (cs.chatId === chatId && cs.threadId === threadId) {
-            target = cs
-            break
-          }
-        }
-      }
-      if (target == null) {
-        // No active card for this chat+thread — either the turn already
-        // completed via another path, or no turn is in flight. Idempotent
-        // no-op.
-        return
-      }
-      // Simulate the normal turn_end path so in-flight sub-agents keep
-      // their card surface. If sub-agents are running, this sets
-      // pendingCompletion and defers; if not, it closes immediately.
-      // stream_reply(done=true) signals "user's answer landed", not
-      // "all background work finished" — we must not abandon still-
-      // running sub-agents just because the final reply was sent.
-      if (target.completionFired) return
-      process.stderr.write(`telegram gateway: progress-card: forceCompleteTurn turnKey=${target.turnKey} (external completion signal, e.g. stream_reply done=true)\n`)
-      emitCardEvent({
-        agent: process.env.SWITCHROOM_AGENT_NAME ?? '',
-        chatId: target.chatId ?? '',
-        turnKey: target.turnKey,
-        event: 'force-completed',
-        reason: 'external completion signal (stream_reply done=true)',
-      })
-      const durationMs = Math.max(0, now() - target.state.turnStartedAt)
-      beginTurnEnd(target, durationMs)
-      target.lastEventAt = now()
-      flush(target, /*forceDone*/ true)
-      if (hasAnyRunningSubAgent(target.state)) {
-        target.pendingCompletion = true
-        const correlated: string[] = []
-        const orphans: string[] = []
-        for (const [k, sa] of target.state.subAgents) {
-          if (sa.state === 'running') {
-            if (sa.parentToolUseId != null) correlated.push(k)
-            else orphans.push(k)
-          }
-        }
-        process.stderr.write(`telegram gateway: progress-card: forceCompleteTurn deferred turnKey=${target.turnKey} reason=in-flight-sub-agents correlated=${correlated.length} orphans=${orphans.length} correlatedAgentIds=[${correlated.join(',')}] orphanAgentIds=[${orphans.join(',')}]\n`)
-        return
-      }
-      closePerChat(target, 'turn-end')
-    },
-
-    takeOverCard({ chatId, threadId }) {
-      // Mirror the (chatId, threadId) lookup used by forceCompleteTurn
-      // — prefer the currentTurnKey-pinned target so concurrent fresh
-      // turns can't get clobbered.
-      let target: PerChatState | undefined
-      if (currentTurnKey != null) {
-        const cs = chats.get(currentTurnKey)
-        if (cs != null && cs.chatId === chatId && cs.threadId === threadId) {
-          target = cs
-        }
-      }
-      if (target == null) {
-        for (const cs of chats.values()) {
-          if (cs.chatId === chatId && cs.threadId === threadId) {
-            target = cs
-            break
-          }
-        }
-      }
-      if (target == null) return { wasEmitted: false, turnKey: null }
-
-      // Cancel any pending deferred-first-emit timer so no card emits
-      // late, AFTER the external owner takes over. If the timer has
-      // already fired (DELAY_ELAPSED sentinel), nothing to clear.
-      if (target.deferredFirstEmitTimer != null && target.deferredFirstEmitTimer !== DELAY_ELAPSED) {
-        clearT(target.deferredFirstEmitTimer)
-        target.deferredFirstEmitTimer = null
-      }
-      // The card has been emitted iff the deferred-emit timer fired
-      // (driver's own indicator) or `isFirstEmit === false` (an emit
-      // path other than the deferred one already ran).
-      const wasEmitted =
-        target.deferredFirstEmitTimer === DELAY_ELAPSED || !target.isFirstEmit
-
-      target.cardTakenOver = true
-      target.completionFired = true
-
-      process.stderr.write(
-        `telegram gateway: progress-card: takeOverCard turnKey=${target.turnKey} wasEmitted=${wasEmitted}\n`,
-      )
-      return { wasEmitted, turnKey: target.turnKey }
-    },
-
-    /**
-     * P2 of #662 — debug/test hook returning every live PerChatState's
-     * fleet keyed by turnKey. Used by cross-turn background tests to
-     * verify routing landed on the originating turn rather than the
-     * currently-active one. Not part of the production driver contract.
-     */
-    peekAllFleets() {
-      const out: Array<{ turnKey: string; chatId: string | null; fleet: Map<string, FleetMember> }> = []
-      for (const cs of chats.values()) {
-        out.push({ turnKey: cs.turnKey, chatId: cs.chatId, fleet: cs.fleet })
-      }
-      return out
-    },
-
-    peekFleet(chatId, threadId) {
-      if (currentTurnKey != null) {
-        const cs = chats.get(currentTurnKey)
-        if (cs != null && cs.chatId === chatId && cs.threadId === threadId) {
-          return cs.fleet
-        }
-      }
-      for (const cs of chats.values()) {
-        if (cs.chatId === chatId && cs.threadId === threadId) return cs.fleet
-      }
-      return undefined
-    },
-
-    peek(chatId, threadId) {
-      // Return the current active turn state for this chat:thread.
-      if (currentTurnKey != null) {
-        const cs = chats.get(currentTurnKey)
-        if (cs != null && cs.chatId === chatId && cs.threadId === threadId) {
-          return cs.state
-        }
-      }
-      // Fallback: find any active card for this chatId (threadId match optional).
-      for (const cs of chats.values()) {
-        if (cs.chatId === chatId && cs.threadId === threadId) return cs.state
-      }
-      return undefined
-    },
-
-    hasActiveCard(chatId, threadId) {
-      for (const cs of chats.values()) {
-        if (
-          cs.chatId === chatId
-          && cs.threadId === threadId
-          && !cs.completionFired
-        ) {
-          return true
-        }
-      }
-      return false
-    },
-
-    recordSubAgentNarrative({ chatId, threadId, agentId, text }) {
-      // Locate the active card for (chatId, threadId). Mirrors
-      // hasActiveCard's iteration since `chats` is keyed by turnKey.
-      let cs: PerChatState | null = null
-      for (const candidate of chats.values()) {
-        if (
-          candidate.chatId === chatId
-          && candidate.threadId === threadId
-          && !candidate.completionFired
-        ) {
-          cs = candidate
-          break
-        }
-      }
-      if (cs == null) {
-        return { ok: false, reason: 'no_active_card' }
-      }
-      // Sub-agents are keyed by jsonl_agent_id in the reducer state.
-      if (!cs.state.subAgents.has(agentId)) {
-        return { ok: false, reason: 'unknown_agent' }
-      }
-      // Dispatch through the same reduce path used by ingest().
-      cs.state = reduce(
-        cs.state,
-        { kind: 'sub_agent_narrative', agentId, text },
-        now(),
-      )
-      // Force re-render even though milestoneVersion didn't bump.
-      flush(cs, false)
-      return { ok: true }
-    },
-
-    reportApiFailure(turnKey, failure) {
-      const cs = chats.get(turnKey)
-      if (cs == null) return // turn already completed — ignore
-      if (cs.apiFailures.terminal) return // already terminal — no-op
-
-      if (failure.kind === 'benign') {
-        // "message is not modified" — not a real failure; don't touch counter.
-        return
-      }
-      if (failure.kind === 'transient') {
-        // Network/5xx — retryable by the outer layer; don't escalate.
-        process.stderr.write(
-          `telegram gateway: progress-card: transient API error turnKey=${turnKey} code=${failure.code} (${failure.description}) — will retry\n`,
-        )
-        return
-      }
-
-      // permanent_4xx
-      cs.apiFailures.consecutive4xx++
-      cs.apiFailures.lastError = {
-        code: failure.code,
-        description: failure.description,
-        timestamp: now(),
-      }
-
-      if (maxConsecutive4xx > 0 && cs.apiFailures.consecutive4xx >= maxConsecutive4xx) {
-        cs.apiFailures.terminal = true
-        process.stderr.write(
-          `telegram gateway: progress-card: card edit giving 4xx, abandoning locally` +
-          ` (chat=${cs.chatId}, turnKey=${turnKey}, code=${failure.code}, desc="${failure.description}")\n`,
-        )
-      } else {
-        process.stderr.write(
-          `telegram gateway: progress-card: card edit 4xx (${cs.apiFailures.consecutive4xx}/${maxConsecutive4xx})` +
-          ` turnKey=${turnKey} code=${failure.code} (${failure.description})\n`,
-        )
-      }
-    },
-
-    reportApiSuccess(turnKey) {
-      const cs = chats.get(turnKey)
-      if (cs == null) return
-      if (cs.apiFailures.consecutive4xx > 0) {
-        cs.apiFailures.consecutive4xx = 0
-      }
-    },
-
-    recordOutboundDelivered(chatId, threadId) {
-      // Issue #137: walk the active chats and find the entry matching the
-      // outbound destination. We can't index by chatId alone — multiple
-      // turns may queue against the same chat — so iterate. The map is
-      // small (one entry per active turn) so the linear scan is fine.
-      for (const cs of chats.values()) {
-        if (cs.chatId === chatId && cs.threadId === threadId) {
-          cs.outboundDeliveredCount += 1
-          return
-        }
-      }
-      // No active card → outbound was likely a system message (boot
-      // banner, restart ack, etc.) and isn't part of any agent turn.
-      // Silent no-op.
-    },
-
-    dispose(opts?: { preservePending?: boolean }) {
-      if (opts?.preservePending === true) {
-        // Selective dispose: preserve chats with pendingCompletion=true so
-        // their heartbeat and deferred-completion timeout continue firing
-        // after a bridge disconnect. This is the fix for the regression
-        // introduced in commit 4c0186d where dispose() wiped all in-flight
-        // card state on every bridge disconnect (stdio-MCP per-call lifecycle).
-        let hasPending = false
-        for (const [turnKey, cs] of chats) {
-          // Always clear coalesce timers — they could emit into a finalized
-          // draft stream and spawn duplicate messages.
-          if (cs.pendingTimer != null) {
-            clearT(cs.pendingTimer)
-            cs.pendingTimer = null
-          }
-          if (cs.deferredFirstEmitTimer != null) {
-            clearT(cs.deferredFirstEmitTimer)
-            cs.deferredFirstEmitTimer = null
-          }
-          if (cs.pendingCompletion) {
-            // Keep this chat alive — it has running background sub-agents
-            // that will continue emitting events and need the heartbeat.
-            hasPending = true
-          } else {
-            // No pending completion — clear this chat (existing behavior).
-            chats.delete(turnKey)
-          }
-        }
-        // Only stop the heartbeat if nothing is pending; if any chat is still
-        // alive, the heartbeat is exactly what drives future re-renders.
-        if (!hasPending) {
-          stopHeartbeat()
-        }
-        // Reset currentChatId/currentTurnKey only if they no longer map to
-        // a surviving pendingCompletion chat.
-        if (currentTurnKey != null && !chats.has(currentTurnKey)) {
-          currentChatId = null
-          currentThreadId = undefined
-          currentTurnKey = null
-        }
-        pendingSyncEchoes.clear()
-        seenEnqueueMsgIds.clear()
-      } else {
-        // Back-compat: wipe everything (original behavior).
-        stopHeartbeat()
-        for (const cs of chats.values()) {
-          if (cs.pendingTimer != null) {
-            clearT(cs.pendingTimer)
-            cs.pendingTimer = null
-          }
-          if (cs.deferredFirstEmitTimer != null) {
-            clearT(cs.deferredFirstEmitTimer)
-            cs.deferredFirstEmitTimer = null
-          }
-        }
-        chats.clear()
-        currentChatId = null
-        currentThreadId = undefined
-        currentTurnKey = null
-        pendingSyncEchoes.clear()
-        seenEnqueueMsgIds.clear()
-      }
-    },
-
-    onSubAgentStall(agentId: string, _idleMs: number, _description: string) {
-      // Option C: watcher detected a stall for this sub-agent. Find which
-      // chat state is tracking it and force an elapsed-tick re-render so the
-      // ⚠️ stall indicator becomes visible even when no events are flowing.
-      for (const cs of chats.values()) {
-        if (!cs.state.subAgents.has(agentId)) continue
-        const sa = cs.state.subAgents.get(agentId)!
-        if (sa.state !== 'running') continue
-        // Leave sa.lastEventAt unchanged — the render computes the ⚠️
-        // stall badge from (now - sa.lastEventAt) >= SUBAGENT_STALL_MS,
-        // so the stale value is exactly what makes the badge appear.
-        // All we need to do here is force a re-render so the user sees it.
-        //
-        // If the card is still suppressed (no first emit yet), the user
-        // has nothing on screen — the stall warning needs to be visible
-        // immediately. Promote out of the initial-delay window before
-        // forcing the heartbeat tick.
-        if (
-          promoteOnSubAgent
-          && cs.isFirstEmit
-          && cs.deferredFirstEmitTimer !== DELAY_ELAPSED
-          && !cs.apiFailures.terminal
-        ) {
-          promoteFirstEmit(cs, 'sub_agent_stall')
-        }
-        // Force the next heartbeat tick to emit by clearing the diff-guard
-        // buckets for this turnKey. Note: this clears the chat-level and
-        // sub-agent-tick buckets — distinct from cs.lastEventAt (chat-level,
-        // drives stuckMs) which is left untouched.
-        lastHeartbeatBucket.delete(cs.turnKey)
-        lastSubAgentTickBucket.delete(cs.turnKey)
-        // If the heartbeat isn't running (it would have been kept alive by
-        // preserve-pending, but check defensively), start it.
-        if (chats.size > 0) startHeartbeatIfNeeded()
-        break
-      }
-    },
-
-    onSubAgentUnstall(agentId: string, _description: string) {
-      // Symmetric to onSubAgentStall: watcher saw JSONL activity return.
-      // The standard event path has already bumped sa.lastEventAt and
-      // (for tool events) flipped fleet member status stuck→running via
-      // applyToolUse. All this method needs to do is force a re-render
-      // so the ⚠ badge clears immediately — the diff-guard can otherwise
-      // suppress the heartbeat for several seconds if no chat-level
-      // state changed, which manifests as the badge lingering even
-      // though the underlying state is fresh.
-      for (const cs of chats.values()) {
-        if (!cs.state.subAgents.has(agentId)) continue
-        const sa = cs.state.subAgents.get(agentId)!
-        if (sa.state !== 'running') continue
-        lastHeartbeatBucket.delete(cs.turnKey)
-        lastSubAgentTickBucket.delete(cs.turnKey)
-        if (chats.size > 0) startHeartbeatIfNeeded()
-        break
-      }
-    },
-
-    /**
-     * Test-only accessor. Returns the live internal Maps so tests can
-     * assert TTL eviction and outer-base-key cleanup actually drop
-     * entries. Not part of the supported API — naming reflects that.
-     */
-    _debugGetMaps() {
-      return {
-        chats,
-        seenEnqueueMsgIds,
-        pendingSyncEchoes,
-        chatRunningSubagents,
-        baseTurnSeqs,
-        editTimestamps,
-      }
-    },
-  }
-}