switchroom 0.5.0

package/telegram-plugin/tool-labels.ts

@@ -0,0 +1,330 @@
+/**
+ * Human-readable labels for tool_use events on the progress card.
+ *
+ * Each function takes the tool's `input` object (as Claude Code records it
+ * in the session JSONL) and returns a short suffix to append to the tool
+ * name, e.g. `toolLabel('Read', { file_path: '/abs/foo.ts' })` → `'foo.ts'`.
+ *
+ * Goals:
+ *   - Short enough to fit on one Telegram line without wrapping on mobile
+ *   - Recognisable — paths shown as basename only; commands truncated at
+ *     ~40 chars / first newline; queries quoted; hostnames for URLs
+ *   - Safe: all outputs pass through the renderer's HTML escape, and
+ *     inputs that look malformed fall back to empty string
+ *
+ * Keep this file tiny and dependency-free — it's in the hot path of
+ * every render.
+ */
+
+const MAX_LABEL_CHARS = 60
+const MAX_BASH_CHARS = 40
+/**
+ * Cap for human-readable `description` fields (Bash, fallback). Set
+ * larger than MAX_BASH_CHARS because descriptions are agent-authored
+ * English prose intended for humans — letting them wrap a couple of
+ * mobile lines is fine; aggressive truncation hides intent.
+ */
+const MAX_DESCRIPTION_CHARS = 160
+
+/**
+ * Basename of a path — just the trailing segment. `/a/b/c.ts` → `c.ts`.
+ * We used to shorten to "project/last-two-segments" but user feedback
+ * asked for a cleaner look in the checklist; the path's directory rarely
+ * adds useful information when the user is watching tool calls scroll by.
+ */
+function basename(p: string): string {
+  if (!p) return ''
+  const parts = p.split('/').filter(Boolean)
+  return parts.length > 0 ? parts[parts.length - 1] : p
+}
+
+/**
+ * Shorten a Grep `path` argument. Prefer "<parent>/<dir>/" form for
+ * directories so the hint is recognisable (e.g. "src/" rather than just
+ * "src" is ambiguous vs. a file). Returns the basename for files.
+ */
+function shortenGrepPath(p: string): string {
+  if (!p) return 'repo'
+  const hadTrailingSlash = /\/+$/.test(p)
+  const trimmed = p.replace(/\/+$/, '')
+  const parts = trimmed.split('/').filter(Boolean)
+  if (parts.length === 0) return 'repo'
+  const last = parts[parts.length - 1]
+  if (hadTrailingSlash) return `${last}/`
+  // Dotfiles like `.env`, `.gitignore`, `.npmrc` — a leading dot with no
+  // further dot — are files, not directories. The old heuristic ("no dot
+  // → dir") mislabeled them as directories.
+  if (last.startsWith('.') && !last.slice(1).includes('.')) return last
+  // Otherwise: no extension → treat as a directory hint.
+  if (!last.includes('.')) return `${last}/`
+  return last
+}
+
+/**
+ * Extract a hostname from a URL. Falls back to the original string on
+ * malformed input.
+ */
+function hostFromUrl(u: string): string {
+  if (!u) return ''
+  try {
+    return new URL(u).host
+  } catch {
+    // Not a valid URL — just return the raw input, truncated.
+    return truncate(u)
+  }
+}
+
+function truncate(s: string, n = MAX_LABEL_CHARS): string {
+  if (s.length <= n) return s
+  return s.slice(0, n - 1) + '…'
+}
+
+/**
+ * Strip HTML tags from a preview string. MCP tools like `stream_reply`
+ * accept Telegram-HTML text as input; when we use that text as a label
+ * preview, the raw `<b>`/`<i>`/etc. markers would pass through
+ * `escapeHtml` in the renderer and show up as visible `<b>` on screen.
+ * Dropping tags here keeps the preview human-readable.
+ *
+ * Requires an ASCII letter (or `/`) immediately after `<` so comparison
+ * operators in plain-text queries (`"find x < 5 and y > 3"`) survive
+ * unmolested. A naive `/<[^>]+>/g` would otherwise eat everything
+ * between the two brackets.
+ */
+function stripHtml(s: string): string {
+  return s.replace(/<\/?[a-zA-Z][^>]*>/g, '')
+}
+
+function firstLine(s: string): string {
+  const idx = s.indexOf('\n')
+  return idx === -1 ? s : s.slice(0, idx)
+}
+
+/**
+ * Return true when the label produced by `toolLabel(tool, input)` came
+ * from a human-authored `description` field rather than a raw fallback
+ * (filename, command string, hostname, etc.). The progress card uses this
+ * flag to suppress the tool-name prefix — "Check commit state" reads
+ * better than "Bash Check commit state".
+ *
+ * Rules:
+ *   - Bash / BashOutput → true when `input.description` is a non-empty string
+ *   - Task / Agent     → true when `input.description` is a non-empty string
+ *   - All other tools  → false (keep the "ToolName label" concat)
+ *
+ * WebFetch and WebSearch are intentionally left as false because the
+ * tool name provides important context ("WebFetch example.com" makes more
+ * sense than just "example.com").
+ */
+export function isHumanDescription(
+  tool: string,
+  input?: Record<string, unknown>,
+): boolean {
+  if (!input || typeof input !== 'object') return false
+  const description =
+    typeof input['description'] === 'string' ? input['description'] : undefined
+  switch (tool) {
+    case 'Bash':
+    case 'BashOutput':
+    case 'Task':
+    case 'Agent':
+      return typeof description === 'string' && description.trim().length > 0
+    default:
+      return false
+  }
+}
+
+/**
+ * Return a display suffix for `tool` given its `input`, without the tool
+ * name itself. Caller renders `${tool} ${suffix}` (space-separated; no
+ * colon) — the checklist format the progress card uses.
+ *
+ * The optional `preamble` is the most recent short `text` content block
+ * the model emitted just before this `tool_use` in the same assistant
+ * message — the model's natural "I'll check foo.ts" narration. For the
+ * file/search tools (Read/Write/Edit/Grep/Glob/NotebookEdit) we prefer
+ * that prose over the filename/pattern fallback when it's short enough
+ * to fit on one mobile line (single-line, ≤160 chars). Multi-line or
+ * longer text is treated as a narrative step, not a per-tool preamble,
+ * and the fallback label wins. Bash/BashOutput prefer their own
+ * `input.description` first but fall back to preamble when it's absent
+ * (then the raw command). Task/Agent ignore preamble entirely — their
+ * `input.description` / `subagent_type` is always set by the harness.
+ */
+export function toolLabel(
+  tool: string,
+  input?: Record<string, unknown>,
+  preamble?: string,
+): string {
+  if (!input || typeof input !== 'object') return ''
+  const str = (k: string): string | undefined =>
+    typeof input[k] === 'string' ? (input[k] as string) : undefined
+
+  const preambleLabel = (): string | null => {
+    if (!preamble) return null
+    if (preamble.includes('\n')) return null
+    const trimmed = preamble.trim()
+    if (!trimmed) return null
+    if (trimmed.length > MAX_DESCRIPTION_CHARS) return null
+    return trimmed
+  }
+
+  switch (tool) {
+    case 'Read':
+    case 'Write':
+    case 'NotebookEdit':
+    case 'Edit': {
+      const pre = preambleLabel()
+      if (pre) return pre
+      return truncate(basename(str('file_path') ?? ''))
+    }
+
+    case 'Bash':
+    case 'BashOutput': {
+      // Priority order (highest to lowest):
+      // 1. input.description — agent-authored, human-readable phrase
+      // 2. preamble — model's preceding text narration ("Checking the logs")
+      //    (same single-line + length gate as file tools)
+      // 3. raw command, truncated to MAX_BASH_CHARS
+      const description = str('description')
+      if (description) return truncate(firstLine(description), MAX_DESCRIPTION_CHARS)
+      const pre = preambleLabel()
+      if (pre) return pre
+      const cmd = str('command') ?? str('bash_id') ?? ''
+      return truncate(firstLine(cmd), MAX_BASH_CHARS)
+    }
+
+    case 'KillShell':
+      return truncate(str('shell_id') ?? '')
+
+    case 'Glob': {
+      const pre = preambleLabel()
+      if (pre) return pre
+      return truncate(str('pattern') ?? '')
+    }
+
+    case 'Grep': {
+      const pre = preambleLabel()
+      if (pre) return pre
+      const pat = str('pattern') ?? ''
+      if (!pat) return ''
+      const path = str('path')
+      const where = shortenGrepPath(path ?? '')
+      return truncate(`"${pat}" (in ${where})`)
+    }
+
+    case 'WebFetch':
+      return truncate(hostFromUrl(str('url') ?? ''))
+
+    case 'WebSearch': {
+      const q = str('query') ?? ''
+      return q ? truncate(`"${q}"`) : ''
+    }
+
+    case 'Task':
+    case 'Agent': {
+      const desc = str('description') ?? str('subagent_type') ?? ''
+      return truncate(desc)
+    }
+
+    case 'TodoWrite':
+    case 'TaskCreate':
+    case 'TaskUpdate':
+    case 'TaskList':
+    case 'TaskGet':
+    case 'TaskStop':
+    case 'TaskOutput':
+      return ''
+
+    case 'Skill':
+      return truncate(str('skill') ?? '')
+
+    case 'SlashCommand':
+      return truncate(str('command') ?? '')
+
+    case 'ToolSearch': {
+      const q = str('query') ?? ''
+      if (!q) return ''
+      // "select:Foo,Bar" — the model is loading schemas for named tools.
+      // Strip the prefix and show just the names so the checklist reads
+      // "ToolSearch Loading schema: Foo, Bar" rather than echoing the raw
+      // colon-delimited string.
+      const selectMatch = q.match(/^\s*select\s*:\s*(.+)$/i)
+      if (selectMatch) {
+        const names = selectMatch[1]
+          .split(',')
+          .map((n) => n.trim())
+          .filter((n) => n.length > 0)
+          .join(', ')
+        return truncate(`Loading schema: ${names}`)
+      }
+      return truncate(`Searching tools: ${q}`)
+    }
+
+    default:
+      // MCP tools (`mcp__<server>__<action>`) share a single prefix and a
+      // handful of common shapes. Dispatch them here before the generic
+      // key-sweep fallback, which would otherwise echo raw query strings.
+      if (tool.startsWith('mcp__')) {
+        const description = str('description')
+        if (description) return truncate(firstLine(stripHtml(description)), MAX_DESCRIPTION_CHARS)
+        const label = mcpBaseLabel(tool)
+        const query = str('query') ?? str('text') ?? str('name')
+        if (label && query) {
+          // Reserve room for the " (…)" wrapping so the total label stays
+          // under MAX_LABEL_CHARS. 4 chars of framing: " (" + "…" + ")".
+          const budget = Math.max(8, MAX_LABEL_CHARS - label.length - 4)
+          const preview = truncate(firstLine(stripHtml(query)), budget)
+          return `${label} (${preview})`
+        }
+        if (label) return truncate(label)
+        // No derivable base label — fall through to the generic sweep.
+      }
+
+      // Unknown tool — try common keys in priority order. `description`
+      // is checked first because it's the agent's human-readable summary
+      // (when present) and beats raw command/path strings.
+      for (const k of ['description', 'file_path', 'path', 'url', 'query', 'pattern', 'command']) {
+        const v = str(k)
+        if (v != null && v.length > 0) {
+          if (k === 'file_path' || k === 'path') return truncate(basename(v))
+          if (k === 'url') return truncate(hostFromUrl(v))
+          if (k === 'description') return truncate(firstLine(v), MAX_DESCRIPTION_CHARS)
+          return truncate(firstLine(v))
+        }
+      }
+      return ''
+  }
+}
+
+/**
+ * Derive a "<Server>: <action>" label from an `mcp__<server>__<action>`
+ * tool name. Returns the empty string when the name doesn't match the
+ * expected shape so callers can fall back to the generic sweep.
+ *
+ * Servers sometimes ship with noisy machine names (e.g.
+ * `switchroom-telegram`) — we map a small allowlist to friendlier
+ * labels, and otherwise capitalise the first letter and keep the rest
+ * verbatim so unknown servers still render cleanly.
+ */
+function mcpBaseLabel(tool: string): string {
+  if (!tool.startsWith('mcp__')) return ''
+  const parts = tool.slice('mcp__'.length).split('__')
+  if (parts.length < 2) return ''
+  const rawServer = parts[0]
+  // Action may itself contain `__` in theory; preserve anything after
+  // the first separator verbatim. In practice actions are single tokens
+  // like `recall` or `stream_reply`.
+  const action = parts.slice(1).join('__')
+  if (!rawServer || !action) return ''
+  return `${prettifyServer(rawServer)}: ${action}`
+}
+
+function prettifyServer(name: string): string {
+  const LABELS: Record<string, string> = {
+    'switchroom-telegram': 'Telegram',
+  }
+  if (LABELS[name]) return LABELS[name]
+  if (!name) return name
+  return name.charAt(0).toUpperCase() + name.slice(1)
+}

package/telegram-plugin/tool-names.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP tool-name classification helpers.
+ *
+ * Claude Code prefixes every MCP tool name with `mcp__<server-key>__` where
+ * `<server-key>` is whatever name the host's `.mcp.json` used to register
+ * this plugin. The key is user-chosen and historical agents still use
+ * `clerk-telegram` while new installs use `switchroom-telegram` (and forks
+ * may pick yet other names). Matching a single hardcoded prefix would
+ * silently break the orphaned-reply backstop and status-reaction
+ * suppression for anyone whose config didn't match — which is how bug
+ * #TG-IDLE-LEAK regressed on 2026-04-14.
+ *
+ * Extracted from server.ts so the classification can be unit-tested
+ * without importing the whole MCP-server module (which executes
+ * side-effects at import: Bot creation, env-var validation, etc).
+ */
+
+const TELEGRAM_TOOL_PREFIX_RE = /^mcp__[^_].*?telegram__/
+
+function stripPrefix(toolName: string): string | null {
+  if (!TELEGRAM_TOOL_PREFIX_RE.test(toolName)) return null
+  return toolName.replace(TELEGRAM_TOOL_PREFIX_RE, '')
+}
+
+/**
+ * True if `toolName` is this plugin's `reply` or `stream_reply` tool
+ * published under ANY registration key (`clerk-telegram`,
+ * `switchroom-telegram`, a custom fork, …). Used by the session-tail
+ * handler to set `currentTurnReplyCalled` — when this returns false for
+ * a real reply call, turn_end mistakenly runs the orphaned-reply
+ * backstop and duplicates the message.
+ */
+export function isTelegramReplyTool(toolName: string): boolean {
+  const suffix = stripPrefix(toolName)
+  return suffix === 'reply' || suffix === 'stream_reply'
+}
+
+/**
+ * True if `toolName` is any Telegram surface tool whose own handler
+ * owns the status-reaction lifecycle for the turn (reply, stream_reply,
+ * edit_message, react). The session-tail skips driving a tool reaction
+ * for these — the handler itself will fire `setDone()` when the API
+ * call completes.
+ */
+export function isTelegramSurfaceTool(toolName: string): boolean {
+  const suffix = stripPrefix(toolName)
+  return (
+    suffix === 'reply'
+    || suffix === 'stream_reply'
+    || suffix === 'edit_message'
+    || suffix === 'react'
+  )
+}

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

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

package/telegram-plugin/turn-flush-safety.ts

@@ -0,0 +1,109 @@
+/**
+ * Turn-end flush safety net.
+ *
+ * Purpose: if a Claude turn ends without the model calling the `reply` or
+ * `stream_reply` tool, we still want the user to see the model's final
+ * assistant text in Telegram. The live Telegram-plugin gateway tracks the
+ * current turn's state (chatId, whether the reply tool was called, and the
+ * captured assistant text). At turn_end we call `decideTurnFlush` to decide
+ * whether to deterministically flush that captured text via the normal
+ * outbound send path.
+ *
+ * The decision is pure — the caller is responsible for actually sending.
+ * Keeping the policy in one unit-testable function is the whole point:
+ * the suppress cases (silent-reply markers, empty text, sub-agent turns,
+ * system-initiated turns with no inbound user message, the feature flag)
+ * are easy to audit and extend.
+ *
+ * The feature flag `SWITCHROOM_TG_TURN_FLUSH_SAFETY` is enabled by default
+ * and can be set to `0` / `false` / `off` to disable without a rebuild.
+ */
+
+const SILENT_MARKERS = new Set(['NO_REPLY', 'HEARTBEAT_OK'])
+// Small buffer so `NO_REPLY.` with a stray period still counts as silent.
+const SILENT_MARKER_MAX_LEN = Math.max(
+  ...Array.from(SILENT_MARKERS, m => m.length),
+) + 2
+
+/**
+ * Exact-match (case-insensitive, whitespace-trimmed) check for the silent
+ * reply sentinels NO_REPLY and HEARTBEAT_OK. Mirrors server.ts
+ * `isSilentReplyMarker` intentionally — keeping a local copy avoids a
+ * circular-import dependency on server.ts (which has heavy top-level
+ * side effects).
+ *
+ * Trailing-punctuation tolerance: a single trailing non-alphanumeric character
+ * (e.g. `NO_REPLY.`) is stripped before matching so accidental punctuation
+ * from model output doesn't prevent suppression. Substring matches (e.g.
+ * `the agent suggested NO_REPLY earlier`) are still rejected because the
+ * length guard rejects anything longer than SILENT_MARKER_MAX_LEN.
+ */
+export function isSilentFlushMarker(text: string | undefined): boolean {
+  if (typeof text !== 'string') return false
+  let trimmed = text.trim()
+  if (trimmed.length === 0) return false
+  if (trimmed.length > SILENT_MARKER_MAX_LEN) return false
+  // Strip a single trailing non-word character to handle "NO_REPLY." etc.
+  if (trimmed.length > 0 && /\W$/.test(trimmed)) {
+    trimmed = trimmed.slice(0, -1)
+  }
+  return SILENT_MARKERS.has(trimmed.toUpperCase())
+}
+
+export type FlushDecision =
+  | { kind: 'flush'; text: string }
+  | { kind: 'skip'; reason: FlushSkipReason }
+
+export type FlushSkipReason =
+  | 'flag-disabled'
+  | 'reply-called'
+  | 'no-inbound-chat'
+  | 'empty-text'
+  | 'silent-marker'
+
+export interface FlushDecisionInput {
+  /** Inbound chat the turn was servicing. `null` means system-initiated /
+   * sub-agent — never flush those, they have their own outbound lifecycle. */
+  chatId: string | null
+  /** True when the model called `reply` / `stream_reply` at least once for
+   * this turn. */
+  replyCalled: boolean
+  /** Raw text content blocks accumulated from assistant events across the
+   * turn. Joined + trimmed internally. */
+  capturedText: string[]
+  /** Feature flag — defaults to true. Pass `false` to force skip everywhere. */
+  flushEnabled?: boolean
+}
+
+/**
+ * Pure decision: should the gateway deterministically send the model's
+ * captured assistant text at turn_end? Returns `{kind: 'flush', text}` with
+ * the joined text when yes, otherwise `{kind: 'skip', reason}`.
+ *
+ * Ordering of checks is deliberate: cheapest/strongest first so logs
+ * attribute a skip to the most specific cause.
+ */
+export function decideTurnFlush(input: FlushDecisionInput): FlushDecision {
+  const flushEnabled = input.flushEnabled !== false
+  if (!flushEnabled) return { kind: 'skip', reason: 'flag-disabled' }
+  if (input.replyCalled) return { kind: 'skip', reason: 'reply-called' }
+  if (input.chatId == null) return { kind: 'skip', reason: 'no-inbound-chat' }
+  const joined = input.capturedText.join('\n').trim()
+  if (joined.length === 0) return { kind: 'skip', reason: 'empty-text' }
+  if (isSilentFlushMarker(joined)) return { kind: 'skip', reason: 'silent-marker' }
+  return { kind: 'flush', text: joined }
+}
+
+/**
+ * Resolve the feature-flag env var. Default: enabled. Set
+ * SWITCHROOM_TG_TURN_FLUSH_SAFETY to `0`, `false`, `off`, or `no` to disable.
+ */
+export function isTurnFlushSafetyEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const raw = env.SWITCHROOM_TG_TURN_FLUSH_SAFETY
+  if (raw == null) return true
+  const v = raw.trim().toLowerCase()
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false
+  return true
+}

package/telegram-plugin/turn-signal-tracker.ts

@@ -0,0 +1,79 @@
+/**
+ * Per-turn silent-gap tracker for streaming observability.
+ *
+ * Tracks the longest contiguous interval within a turn where no user-visible
+ * signal was sent. Signals include: progress-card edits, status-reaction
+ * transitions, answer-lane updates, and fresh sendMessage calls.
+ *
+ * Keyed by chatId+threadId so concurrent turns in different chats don't
+ * collide. Designed to be fully standalone (no grammy/bot dependency) so
+ * it's testable with deterministic time injection via vi.useFakeTimers().
+ *
+ * Usage:
+ *   signalTracker.reset(key, now)       // at turn start
+ *   signalTracker.noteSignal(key, now)  // on every user-visible signal
+ *   signalTracker.getLongestGap(key)    // at turn_end
+ *   signalTracker.clear(key)            // after emitting (cleanup)
+ */
+
+export interface TurnSignalState {
+  /** The time the current gap started (i.e., the last signal time). */
+  lastSignalAt: number
+  /** The longest gap observed so far (ms). */
+  longestGapMs: number
+}
+
+/**
+ * Module-scoped map: `"chatId:threadId"` → state. Using a module-level map
+ * keeps the tracker lightweight and avoids passing state through every
+ * call-site while remaining mockable in tests via the exported functions.
+ */
+const state = new Map<string, TurnSignalState>()
+
+/**
+ * Begin tracking a new turn. Records `now` as the initial signal time and
+ * resets the gap accumulator. Call at the start of each fresh turn.
+ */
+export function reset(key: string, now: number): void {
+  state.set(key, { lastSignalAt: now, longestGapMs: 0 })
+}
+
+/**
+ * Record a user-visible signal. Measures the gap since the last signal and
+ * updates `longestGapMs` if this gap is larger.
+ */
+export function noteSignal(key: string, now: number): void {
+  const entry = state.get(key)
+  if (entry == null) return
+  const gap = now - entry.lastSignalAt
+  if (gap > entry.longestGapMs) entry.longestGapMs = gap
+  entry.lastSignalAt = now
+}
+
+/**
+ * Returns the longest gap observed during the current turn (ms).
+ * Returns 0 if no tracking state exists for this key.
+ */
+export function getLongestGap(key: string): number {
+  return state.get(key)?.longestGapMs ?? 0
+}
+
+/**
+ * Returns the last signal time for this key, or undefined if not tracked.
+ * Useful for computing a trailing gap at turn_end before calling clear().
+ */
+export function getLastSignalAt(key: string): number | undefined {
+  return state.get(key)?.lastSignalAt
+}
+
+/**
+ * Remove state for this key. Call after emitting the turn_signal_gap metric.
+ */
+export function clear(key: string): void {
+  state.delete(key)
+}
+
+/** Exposed for tests — clears all tracked state. */
+export function __resetAllForTests(): void {
+  state.clear()
+}