switchroom 0.13.55 → 0.13.57

package/telegram-plugin/gateway/gateway.ts

@@ -53,6 +53,7 @@ import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
+import { deriveIntentSurface } from '../tool-intent-surface.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -80,6 +81,7 @@ import { classifyInbound } from '../inbound-classifier.js'
 import * as silencePoke from '../silence-poke.js'
 import * as pendingProgress from '../pending-work-progress.js'
 import { writeSilentEndState, clearSilentEndState, recordUndeliveredTurnEnd } from '../silent-end.js'
+import { markAckSent, clearAckSent } from '../ack-flag.js'
 import { isFinalAnswerReply } from '../final-answer-detect.js'
 import { createAnswerStream, type AnswerStreamHandle } from '../answer-stream.js'
 import { type SessionEvent } from '../session-tail.js'
@@ -1290,6 +1292,15 @@ type CurrentTurn = {
   // Phase 1 of #332: count of tool_use events in the current turn, for
   // the tool_call_count column in the turns registry.
   toolCallCount: number
+  // Tool-intent surface (the human-feel UX follow-up to #1921's
+  // PreToolUse gate). When the model emits its first non-reply tool_use
+  // of a turn AND no outbound has happened yet, the gateway lifts the
+  // tool's already-formed intent (name + input → `toolLabel()`) into a
+  // user-visible "<i>running</i>: ls -la /var/log" message. One-shot
+  // per turn — subsequent tool_use events stay quiet so a multi-tool
+  // turn doesn't spam. The model never has to call reply just to ack;
+  // its own intent stream IS the ack source.
+  intentSurfaceFired: boolean
   // Issue #195 — answer-lane streaming. Lazily created on the first text
   // event of a turn (once enough text has accumulated, the stream itself
   // gates on minInitialChars). Materialized and cleared at turn_end.
@@ -3321,6 +3332,43 @@ silencePoke.startTimer({
     // Re-emit through the unified runtime-metrics fan-out (PostHog + JSONL).
     emitRuntimeMetric(event)
   },
+  onAwarenessPing: async (ctx) => {
+    // Early framework-owned awareness signal (~60s) so the user never
+    // faces a silent chat while the model is busy / held / thinking.
+    // Distinct from the 300s onFrameworkFallback: fires earlier, sends
+    // a SILENT message (disable_notification: true — ambient liveness,
+    // not a device buzz), and is bounded to ONE per turn by the silence-
+    // poke module's `awarenessPingFired` flag. Reuses
+    // `formatFrameworkFallbackText` so the wording stays consistent and
+    // in-flight tools are named when known. If the model has been
+    // silent long enough to cross 300s, the heavier framework_fallback
+    // escalates with a notification.
+    //
+    // Late-fire guard mirrors the framework_fallback handler: skip if
+    // the turn ended cleanly between the silence-poke arming and this
+    // timer-fired handler so we don't talk over a clean response.
+    if (activeTurnStartedAt.get(ctx.key) == null && currentTurn == null) {
+      return
+    }
+    const text = silencePoke.formatFrameworkFallbackText(
+      ctx.fallbackKind,
+      ctx.silenceMs,
+      ctx.inFlightTools,
+    )
+    try {
+      await robustApiCall(
+        () => bot.api.sendMessage(ctx.chatId, text, {
+          ...(ctx.threadId != null ? { message_thread_id: ctx.threadId } : {}),
+          disable_notification: true,
+        }),
+        { chat_id: ctx.chatId, ...(ctx.threadId != null ? { threadId: ctx.threadId } : {}) },
+      )
+    } catch (err) {
+      process.stderr.write(
+        `silence-poke awareness-ping sendMessage failed chat=${ctx.chatId} thread=${ctx.threadId}: ${err}\n`,
+      )
+    }
+  },
   onFrameworkFallback: async (ctx) => {
     // Late-fire short-circuit (2026-05-23 audit finding). The fallback
     // can race a clean turn-end: the model's actual reply lands inside
@@ -3429,7 +3477,18 @@ silencePoke.startTimer({
         longest_silent_gap_ms: outboundMetrics.longestOutboundGapMs,
         ended_via: 'framework_fallback',
       })
-      signalTracker.clear(fbKey)
+      // #1892-follow-up: do NOT clear signalTracker state here. When the
+      // model recovers post-fallback (the framework's user-visible
+      // "still working" message is the load-bearing unwedge primitive —
+      // see `project_silence_poke_broken_and_cross_turn_fix`), its late
+      // reply calls fire `signalTracker.noteOutbound(fbKey, ...)`. If
+      // state is already cleared, that's a silent no-op and the late
+      // reply is invisible to outbound_count + ttfo metrics — the
+      // canonical session-end path (silent-marker line 7407 or normal
+      // turn-end line 7502) emits turn_ended a second time, reading
+      // the empty state and reporting outbound_count=0 even though
+      // replies landed. Defer clear to the canonical paths so
+      // post-fallback recoveries are correctly counted.
     }
     // Stamp the turn-DB end row as `timeout` so the wedged turn doesn't
     // stay open until a SIGTERM/restart relabels it (false-negative for
@@ -4896,6 +4955,16 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // silence-poke clock so the next poke is measured from this send.
   signalTracker.noteOutbound(statusKey(chat_id, threadId), Date.now())
   silencePoke.noteOutbound(statusKey(chat_id, threadId), Date.now())
+  // Ack-first gate (`reference/conversational-pacing.md` beat 1):
+  // touch the state-dir flag so the ack-first-pretool hook lets
+  // subsequent non-reply tool calls through this turn. Cleared at
+  // turn_started. Best-effort — a write failure shouldn't break
+  // reply, and the hook is kill-switched anyway.
+  try {
+    markAckSent()
+  } catch (err) {
+    process.stderr.write(`telegram gateway: markAckSent failed: ${err}\n`)
+  }
   // #1741 — only clear silent-end state on a plausibly-final reply.
   // An interim ack (disable_notification:true, short text, no done)
   // must NOT clear the state file; otherwise a turn that ends with
@@ -5491,6 +5560,13 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       const sKey = statusKey(streamChatId, streamThreadId)
       signalTracker.noteOutbound(sKey, Date.now())
       silencePoke.noteOutbound(sKey, Date.now())
+      // Ack-first gate: stream_reply's first emit also unlocks subsequent
+      // tool calls. See ack-flag.ts + ack-first-pretool.ts.
+      try {
+        markAckSent()
+      } catch (err) {
+        process.stderr.write(`telegram gateway: markAckSent (stream_reply) failed: ${err}\n`)
+      }
       // #1741 — see executeReply for the rationale: only a plausibly-
       // final stream_reply clears the silent-end state. An interim
       // ack via stream_reply must NOT clear; the Stop hook needs
@@ -6725,6 +6801,14 @@ function handleSessionEvent(ev: SessionEvent): void {
           statusKey(ev.chatId, enqThreadId),
           'handback',
         )
+        // Ack-first gate (`reference/conversational-pacing.md` beat 1):
+        // wipe the prior turn's `ack-sent.flag` so the ack-first-
+        // pretool hook re-arms for this fresh turn. Centralised HERE
+        // (not in handleInbound) because `enqueue` is the single
+        // canonical fresh-turn atom — fires for real inbounds, cron
+        // fires, subagent-handback channel wakes, vault-grant resumes,
+        // and restart markers alike. Best-effort — see ack-flag.ts.
+        clearAckSent()
       }
       if (ev.chatId) {
         // Issue #195: if a previous turn left an answer-lane stream open
@@ -6758,6 +6842,7 @@ function handleSessionEvent(ev: SessionEvent): void {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
+          intentSurfaceFired: false,
           answerStream: null,
           isDm: isDmChatId(ev.chatId),
         }
@@ -6875,6 +6960,66 @@ function handleSessionEvent(ev: SessionEvent): void {
           turn.orphanedReplyTimeoutId = null
         }
       }
+      // Tool-intent surface — companion to the PreToolUse ack-first gate
+      // (#1921). On the FIRST non-reply tool_use of a turn AND only when
+      // no outbound has happened yet, the gateway lifts the model's tool
+      // intent (name + input → `toolLabel()`) into a brief framework-voice
+      // status: `<i>running:</i> ls -la /var/log`. The model never has to
+      // call reply just to ack — its own intent stream IS the ack. The
+      // gate continues to fire IN PARALLEL: if it produces a model-voice
+      // ack first (`replyCalled=true`), the surface stays quiet by the
+      // condition below. One-shot per turn.
+      if (
+        !turn.replyCalled
+        && !turn.intentSurfaceFired
+        && !isTelegramSurfaceTool(name)
+      ) {
+        turn.intentSurfaceFired = true
+        // `ev.input` is the canonical SessionEvent property
+        // (`telegram-plugin/session-tail.ts:95`). All other tool_use
+        // sites in this file use `ev.input` — keep that consistent.
+        const surface = deriveIntentSurface(name, ev.input, ev.precomputedLabel)
+        if (surface.text != null) {
+          // Mark the ack-flag synchronously BEFORE the async send so a
+          // PreToolUse ack-first hook (#1921) firing concurrently for this
+          // same tool call sees the flag already present and allows the
+          // tool through. The Telegram send is fire-and-forget; failure
+          // is logged but does not block the model.
+          try {
+            markAckSent()
+          } catch (err) {
+            process.stderr.write(`telegram gateway: intent-surface markAckSent failed: ${err}\n`)
+          }
+          const surfaceChat = turn.sessionChatId
+          const surfaceThread = turn.sessionThreadId
+          const surfaceText = surface.text
+          void (async () => {
+            try {
+              await robustApiCall(
+                () => bot.api.sendMessage(surfaceChat, surfaceText, {
+                  ...(surfaceThread != null ? { message_thread_id: surfaceThread } : {}),
+                  parse_mode: 'HTML',
+                  // Framework-narrating beat — silent, ambient, not a
+                  // device buzz. The user is meant to glance and know
+                  // the model is alive + on-task.
+                  disable_notification: true,
+                }),
+                { chat_id: surfaceChat, ...(surfaceThread != null ? { threadId: surfaceThread } : {}), verb: 'intent-surface' },
+              )
+              // Deliberately NOT calling signalTracker.noteOutbound /
+              // silencePoke.noteOutbound here — framework-owned
+              // ambient messages are not model-author outbounds, so
+              // they should not reset the TTFO clock or short-circuit
+              // the silence-poke ladder. Mirrors the sibling
+              // `onAwarenessPing` handler (silence-poke.ts:169
+              // contract: "Caller must NOT call back into noteOutbound
+              // for this — it's a framework-sourced message").
+            } catch (err) {
+              process.stderr.write(`telegram gateway: intent-surface send failed: ${err}\n`)
+            }
+          })()
+        }
+      }
       if (!ctrl) return
       if (isTelegramSurfaceTool(name)) return
       ctrl.setTool(name)
@@ -8985,6 +9130,11 @@ async function handleInbound(
         // the framework can nudge the model if it goes quiet past the
         // soft / firm thresholds.
         silencePoke.startTurn(statusKey(chat_id, messageThreadId), Date.now())
+        // Ack-first gate clear is centralised in handleSessionEvent's
+        // `enqueue` branch — that fires for EVERY fresh turn atom
+        // (real inbound, cron, subagent-handback, vault-grant wake,
+        // restart marker) so cron/handback turns also re-arm the gate.
+        // See the call site under `case 'enqueue'` (~line 6794).
         // #1445 cross-turn pending-async ambient. A new turn starting
         // (user inbound, synthesised wake, or handback channel) is the
         // signal that the model is about to re-engage — clear any

package/telegram-plugin/runtime-metrics.ts

@@ -104,6 +104,23 @@ export type RuntimeMetricEvent =
       fallback_kind: 'working' | 'thinking'
       silence_ms: number
     }
+  /**
+   * Awareness ping (~60s, default): framework-owned user-visible
+   * "still working… / still thinking…" message sent BEFORE the 300s
+   * fallback so the user never faces a silent chat for the full 5
+   * minutes. Silent (no device ping); one-shot per turn; suppressed
+   * by any outbound or sub-agent dispatch. A high rate is the
+   * diagnostic signal that frequent silences exist (held-inbound,
+   * extended-thinking, slow startup), and the rate of the heavier
+   * silence_fallback_sent that still follows tells us how many of
+   * those escalate all the way to 5 min.
+   */
+  | {
+      kind: 'awareness_ping_sent'
+      key: string
+      fallback_kind: 'working' | 'thinking'
+      silence_ms: number
+    }
   /**
    * #1445 cross-turn pending-async ambient lifecycle. `started` fires
    * when a turn ends with a captured anchor AND a pending Agent/Task/

package/telegram-plugin/silence-poke.ts

@@ -80,6 +80,13 @@ export interface SilencePokeState {
    *  the ack nudge is specifically about the *first* outbound, so it
    *  never re-arms even after the model later goes quiet again. */
   ackPokeFired: boolean
+  /** True once the early awareness-ping has fired this turn. One-shot:
+   *  the user only needs one "we know it's slow" cue before the heavier
+   *  300s fallback escalates. Independent of the ack-poke (which targets
+   *  the model via piggyback) — awareness-ping targets the user directly
+   *  via Telegram, so it lands even during pure-thinking or held-inbound
+   *  silences when no tool_result is available to piggyback on. */
+  awarenessPingFired: boolean
   /** Wall-clock ms of last poke fire — used for poke-success latency. */
   lastPokeFiredAt: number | null
   /** #1292: in-flight tool calls keyed by toolUseId. Populated by
@@ -101,6 +108,14 @@ export interface ThresholdsMs {
    *  75s `soft` threshold, which measures silence-since-last-outbound
    *  and is the wrong instrument for "you never said hello." */
   ack: number
+  /** Awareness ping: if NO outbound has landed this many ms after turn
+   *  start, send a framework-owned user-visible "still working…" status
+   *  message directly via Telegram. Sits between the model-targeted ack
+   *  poke (10s) and the 300s framework_fallback. Lands even during pure
+   *  extended-thinking or held-inbound silences when no tool_result is
+   *  available to piggyback the model-targeted pokes onto. One-shot per
+   *  turn — the 300s fallback handles further escalation if still silent. */
+  awarenessPing: number
   soft: number
   firm: number
   fallback: number
@@ -112,6 +127,7 @@ export interface ThresholdsMs {
 
 export const DEFAULT_THRESHOLDS: ThresholdsMs = {
   ack: 10_000,
+  awarenessPing: 60_000,
   soft: 75_000,
   firm: 180_000,
   fallback: 300_000,
@@ -145,6 +161,7 @@ export type SilencePokeMetric =
   | { kind: 'silence_poke_fired'; key: string; level: PokeLevel; silence_ms: number; subagent_wait: boolean }
   | { kind: 'silence_poke_succeeded'; key: string; level: PokeLevel; latency_ms: number }
   | { kind: 'silence_fallback_sent'; key: string; fallback_kind: 'working' | 'thinking'; silence_ms: number }
+  | { kind: 'awareness_ping_sent'; key: string; fallback_kind: 'working' | 'thinking'; silence_ms: number }
 
 export interface SilencePokeDeps {
   /** Called when the 300s fallback fires. Caller sends the user-visible
@@ -153,6 +170,12 @@ export interface SilencePokeDeps {
    *  not a model-sourced one, and we want pokes to continue (well, no,
    *  fallbackFired ensures only one per turn anyway). */
   onFrameworkFallback: (ctx: FrameworkFallbackContext) => Promise<void> | void
+  /** Called when the awareness ping fires (default 60s). Caller sends
+   *  a user-visible "still working…" message — silent (no device ping),
+   *  framework-owned, one-shot per turn. Reuses the same context shape
+   *  as onFrameworkFallback so the gateway can reuse `formatFrameworkFallbackText`
+   *  and the in-flight-tool enrichment. */
+  onAwarenessPing: (ctx: FrameworkFallbackContext) => Promise<void> | void
   /** Telemetry sink for poke events. */
   emitMetric: (event: SilencePokeMetric) => void
   /** Threshold overrides (tests). */
@@ -188,6 +211,7 @@ export function startTurn(key: string, now: number): void {
     lastThinkingAt: null,
     fallbackFired: false,
     ackPokeFired: false,
+    awarenessPingFired: false,
     lastPokeFiredAt: null,
     inFlightTools: new Map(),
   })
@@ -485,6 +509,64 @@ function tick(now: number): void {
       continue
     }
 
+    // Awareness ping — framework-owned user-visible status BEFORE the
+    // 300s heavy fallback. Lands at ~60s even when the model is in pure
+    // extended-thinking or the inbound is held (#1892 follow-up), since
+    // it's delivered directly via the gateway → Telegram, not
+    // piggybacked on tool_result. One-shot per turn; suppressed if any
+    // outbound has happened. The 300s fallback is unchanged and
+    // escalates further if silence persists.
+    //
+    // Independent of pokesFired so soft/firm/fallback still escalate on
+    // their own schedule. Independent of ackPokeFired so a long-running
+    // turn that already received the ack-poke (then went silent again)
+    // still gets the user-facing awareness ping.
+    if (
+      !s.awarenessPingFired
+      && s.lastOutboundAt == null
+      && !s.subagentDispatchActive
+      && silence >= thresholds.awarenessPing
+    ) {
+      s.awarenessPingFired = true
+      const { chatId, threadId } = parseKey(key)
+      const recentThinking = s.lastThinkingAt != null
+        && (now - s.lastThinkingAt) < 30_000
+      const fallbackKind: 'working' | 'thinking' = recentThinking ? 'thinking' : 'working'
+      const inFlightTools: ToolSnapshot[] = Array.from(s.inFlightTools.values())
+        .sort((a, b) => a.startedAt - b.startedAt)
+        .map(t => ({
+          name: t.name,
+          label: t.label,
+          durationMs: now - t.startedAt,
+        }))
+      activeDeps.emitMetric({
+        kind: 'awareness_ping_sent',
+        key,
+        fallback_kind: fallbackKind,
+        silence_ms: silence,
+      })
+      try {
+        const ret = activeDeps.onAwarenessPing({
+          key,
+          chatId,
+          threadId,
+          fallbackKind,
+          silenceMs: silence,
+          inFlightTools,
+        })
+        if (ret != null && typeof (ret as Promise<unknown>).then === 'function') {
+          ;(ret as Promise<unknown>).catch(err => {
+            process.stderr.write(`silence-poke: awareness-ping handler rejected: ${err}\n`)
+          })
+        }
+      } catch (err) {
+        process.stderr.write(`silence-poke: awareness-ping handler threw: ${err}\n`)
+      }
+      // Don't `continue` — soft/firm/fallback can still arm in the same tick
+      // if their thresholds have also been crossed. Awareness-ping is a
+      // sibling signal, not part of the ladder.
+    }
+
     if (s.pokesFired === 0 && silence >= softThreshold) {
       s.pokeArmed = { level: 'soft' }
       s.pokesFired = 1

package/telegram-plugin/tests/ack-flag.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { markAckSent, clearAckSent, ACK_SENT_MARKER } from "../ack-flag.js";
+
+describe("ack-flag — gateway-side state file for ack-first hook", () => {
+  let stateDir: string;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), "ack-flag-"));
+    prevEnv = process.env.TELEGRAM_STATE_DIR;
+    process.env.TELEGRAM_STATE_DIR = stateDir;
+  });
+
+  afterEach(() => {
+    if (prevEnv != null) process.env.TELEGRAM_STATE_DIR = prevEnv;
+    else delete process.env.TELEGRAM_STATE_DIR;
+    rmSync(stateDir, { recursive: true, force: true });
+  });
+
+  it("markAckSent creates the marker file", () => {
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("markAckSent is idempotent (second call is a no-op)", () => {
+    markAckSent();
+    expect(() => markAckSent()).not.toThrow();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("clearAckSent removes the marker file", () => {
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+    clearAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+  });
+
+  it("clearAckSent is idempotent (works when marker doesn't exist)", () => {
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    expect(() => clearAckSent()).not.toThrow();
+  });
+
+  it("round-trip: mark → clear → mark cycles work across turns", () => {
+    // turn 1
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+    // turn end / next turn start
+    clearAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(false);
+    // turn 2 first reply
+    markAckSent();
+    expect(existsSync(join(stateDir, ACK_SENT_MARKER))).toBe(true);
+  });
+
+  it("noop when TELEGRAM_STATE_DIR is unset (best-effort)", () => {
+    delete process.env.TELEGRAM_STATE_DIR;
+    expect(() => markAckSent()).not.toThrow();
+    expect(() => clearAckSent()).not.toThrow();
+  });
+});

package/telegram-plugin/tests/post-fallback-outbound-count.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  reset,
+  noteOutbound,
+  getOutboundMetrics,
+  clear,
+  __resetAllForTests,
+} from '../turn-signal-tracker.js'
+
+/**
+ * switchroom#1892-follow-up — regression guard for the post-fallback
+ * outbound under-count.
+ *
+ * Scenario reproduced from clerk's 2026-05-27 wedge:
+ *   1. Turn starts (signalTracker.reset)
+ *   2. Model goes silent for 300s — silence-poke ladder fires, then
+ *      framework_fallback fires + emits turn_ended with outbound_count=0
+ *   3. Model recovers — sends 2 late reply tool calls → executeReply
+ *      calls signalTracker.noteOutbound
+ *   4. Canonical silent-marker turn-end path runs → reads metrics
+ *      again → emits final turn_ended
+ *
+ * Pre-fix (b6cd7e5...): framework_fallback called signalTracker.clear
+ * after emitting its turn_ended. Late noteOutbound calls hit cleared
+ * state and no-op. Silent-marker path re-read the empty default and
+ * reported outbound_count=0 again — late replies invisible to KPIs.
+ *
+ * Post-fix: framework_fallback no longer clears; only the canonical
+ * paths do. Late replies accumulate; the canonical turn_ended carries
+ * the correct count.
+ */
+beforeEach(() => {
+  __resetAllForTests()
+})
+
+describe('signal-tracker survives framework-fallback for late-reply accounting (#1892)', () => {
+  it('late noteOutbound after fallback (without clear) increments outbound_count', () => {
+    const key = 'chat:thread'
+    const turnStart = 1_000_000
+    reset(key, turnStart)
+
+    // Simulate framework_fallback at +300s — emits turn_ended with
+    // outbound_count=0 but DOES NOT clear (the fix).
+    const beforeFallback = getOutboundMetrics(key)
+    expect(beforeFallback.outboundCount).toBe(0)
+    expect(beforeFallback.ttfoMs).toBeNull()
+
+    // Model recovers post-fallback and sends two late replies.
+    noteOutbound(key, turnStart + 312_000) // first late reply at +312s
+    noteOutbound(key, turnStart + 358_000) // second late reply at +358s
+
+    // Canonical silent-marker turn-end reads metrics again and clears.
+    const afterRecovery = getOutboundMetrics(key)
+    expect(afterRecovery.outboundCount).toBe(2)
+    expect(afterRecovery.ttfoMs).toBe(312_000)
+
+    clear(key)
+    expect(getOutboundMetrics(key).outboundCount).toBe(0)
+  })
+
+  it('regression guard: clearing state mid-turn would silently lose late outbounds', () => {
+    // The buggy pre-fix sequence — kept here as the inverse case so a
+    // future change that re-introduces clear-at-fallback fails this
+    // test loudly with the late-reply count going to zero.
+    const key = 'chat:thread'
+    reset(key, 1_000_000)
+    clear(key) // simulates the pre-fix framework_fallback clear
+
+    noteOutbound(key, 1_000_312_000) // late reply after the bogus clear
+    noteOutbound(key, 1_000_358_000)
+
+    const metrics = getOutboundMetrics(key)
+    // This is the pre-fix bug: late replies are invisible because
+    // noteOutbound is a no-op when state is missing.
+    expect(metrics.outboundCount).toBe(0)
+    expect(metrics.ttfoMs).toBeNull()
+  })
+})