switchroom 0.12.22 → 0.12.24

package/telegram-plugin/gateway/gateway.ts

@@ -254,6 +254,13 @@ import { purgeStaleTurnsForChat } from './turn-state-purge.js'
 import { decideInboundDelivery } from './inbound-delivery-gate.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import { chatKey, chatKeyWithSuffix } from './chat-key.js'
+// Phase 2b PR 2 — shadow mode. Each event-site below calls shadowEmit()
+// to record what the InboundDeliveryStateMachine PREDICTS the gateway
+// should do. Behavior unchanged in this PR — the imperative code below
+// still runs everything. PR 3 will cut over to executing the machine's
+// effects.
+import { shadowEmit } from './inbound-delivery-machine-shadow.js'
+import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
@@ -1265,6 +1272,13 @@ function streamKey(chatId: string, threadId?: number | null): string {
 }
 
 function purgeReactionTracking(key: string): void {
+  // Phase 2b shadow: turn end. The key was registered via setTurnStarted
+  // when the inbound arrived; purge is the canonical turn-end signal.
+  // outboundEmitted is approximated `true` here — refined in PR 3 to read
+  // from the per-turn `replyCalled` flag on `currentTurn`. Conservative
+  // shadow approximation is safe (only affects machine's lastOutboundAt
+  // tracking; can't drive incorrect behavior in shadow mode).
+  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted: true })
   const msgInfo = activeReactionMsgIds.get(key)
   activeStatusReactions.delete(key)
   activeReactionMsgIds.delete(key)
@@ -3182,6 +3196,8 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientRegistered(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge registered — agent=${client.agentName}\n`)
+    // Phase 2b shadow: bridge up.
+    shadowEmit({ kind: 'bridgeUp', at: Date.now() })
     client.send({ type: 'status', status: 'agent_connected' })
 
     // #1150: drain any synthetic inbounds queued for this agent while
@@ -3307,6 +3323,8 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientDisconnected(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge disconnected — agent=${client.agentName}\n`)
+    // Phase 2b shadow: bridge down.
+    shadowEmit({ kind: 'bridgeDown', at: Date.now() })
 
     // Scope the flush to clients that actually registered as an agent.
     // Anonymous one-shot connections (e.g. recall.py's legacy
@@ -6637,6 +6655,23 @@ async function handleInbound(
   // network RTT) but not a user-perceived end-to-end measurement.
   const inboundReceivedAt = Date.now()
 
+  // Phase 2b shadow: inbound arrival. Emit BEFORE the snapshot/gate
+  // logic so the machine sees the event at the same point in time the
+  // imperative code would. The machine internally handles fresh-turn
+  // vs mid-turn — its decision will be visible in the gw-trace shadow
+  // line emitted to stderr.
+  const _shadowKey = statusKey(ctx.chat?.id != null ? String(ctx.chat.id) : '0', ctx.message?.message_thread_id) as _ChatKey
+  shadowEmit({
+    kind: 'inbound',
+    key: _shadowKey,
+    msg: {
+      msgId: ctx.message?.message_id ?? 0,
+      isSteering: false, // refined in PR 3 — for now shadow conservatively classifies as non-steering
+      payload: null,
+    },
+    at: Date.now(),
+  })
+
   // #1556 self-blocking fix (v0.12.22): snapshot the live turn-state
   // BEFORE the fresh-turn branch (line ~7357) sets activeTurnStartedAt
   // for THIS inbound. The #1556 delivery gate further down asks "is a

package/telegram-plugin/gateway/inbound-delivery-machine-shadow.ts

@@ -0,0 +1,117 @@
+/**
+ * InboundDeliveryStateMachine — SHADOW MODE wiring (Phase 2b PR 2).
+ *
+ * Per RFC `docs/rfcs/inbound-delivery-state-machine.md` Phase 2b PR 2:
+ * the state machine runs ALONGSIDE the existing imperative gateway
+ * code, recording predicted effects to a structured trace. Behavior
+ * is unchanged — every existing code path still executes the actual
+ * I/O. This module's job:
+ *
+ *   1. Own the module-scope machine state.
+ *   2. Expose `shadowEmit(event)` that runs `transition()` + logs the
+ *      predicted effects via `gw-trace shadow ...` stderr lines.
+ *   3. Provide test hooks for resetting + inspecting state.
+ *
+ * After PR 2 bakes on the fleet for 24+ hours, PR 3 will wire the
+ * effects to drive ACTUAL behavior (the cutover), at which point the
+ * imperative paths get deleted in PR 4.
+ *
+ * Telemetry approach: each `shadowEmit` writes a single stderr line
+ * with the event kind + emitted effect kinds. Operators can then:
+ *
+ *   docker exec switchroom-<agent> sh -lc 'grep "gw-trace shadow" \
+ *     /var/log/switchroom/gateway-supervisor.log | tail -50'
+ *
+ * to see what the state machine PREDICTS the gateway should do for
+ * each event. Comparing against the actual log lines (`pending-inbound-
+ * buffer: agent=X buffered ...` etc.) is the validation that the
+ * machine is bit-identical with reality.
+ *
+ * Toggle off via `SWITCHROOM_DELIVERY_MACHINE_SHADOW=0` — a kill
+ * switch for the case where the shadow emits prove problematic
+ * (e.g., trace volume too high). The default is ON.
+ */
+
+import {
+  type Effect,
+  type Event,
+  type State,
+  initialState,
+  transition,
+} from './inbound-delivery-machine.js'
+
+let state: State = initialState()
+const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_SHADOW !== '0'
+
+/**
+ * Run an event through the state machine in shadow mode. The machine
+ * state advances, the predicted effects are LOGGED, but no I/O fires.
+ *
+ * Returns the effects for callers that want to inspect them inline
+ * (e.g., the eventual PR 3 cutover will replace the return-and-ignore
+ * pattern here with return-and-execute).
+ */
+export function shadowEmit(event: Event): readonly Effect[] {
+  if (!enabled) return []
+  // Shadow mode MUST NEVER break the gateway. The state machine is
+  // pure (no I/O, no async) and property-tested over 5000 schedules,
+  // so transition() won't throw on well-formed input. But event
+  // construction at the call site could mis-shape inputs; the
+  // try/catch is belt-and-braces so a shadow bug never wedges a real
+  // turn. The catch logs and bails — the imperative gateway code
+  // below the emit point still runs.
+  try {
+    const result = transition(state, event)
+    state = result.state
+
+    // Single structured stderr line per event — grep-friendly and
+    // low volume (one line per gateway event, not per effect). The
+    // format matches gateway.ts's existing `tg-post method=...` shape
+    // so log aggregation can pick it up without a new parser.
+    const effectKinds = result.effects.map((e) => e.kind).join(',')
+    const eventDetail = formatEventDetail(event)
+    process.stderr.write(
+      `gw-trace shadow event=${event.kind}${eventDetail} effects=[${effectKinds}] global=${state.global.kind} perKeySize=${state.perKey.size}\n`,
+    )
+    return result.effects
+  } catch (err) {
+    process.stderr.write(
+      `gw-trace shadow ERROR event=${event.kind} err=${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return []
+  }
+}
+
+/** Compact event detail for the trace line — keeps the line one-line. */
+function formatEventDetail(event: Event): string {
+  switch (event.kind) {
+    case 'inbound':
+      return ` key=${event.key} msg=${event.msg.msgId} steer=${event.msg.isSteering}`
+    case 'turnStart':
+    case 'turnEnd':
+      return ` key=${event.key}${event.kind === 'turnEnd' ? ` outbound=${event.outboundEmitted}` : ''}`
+    case 'permVerdict':
+      return ` req=${event.verdict.requestId} behavior=${event.verdict.behavior}`
+    case 'modelOutbound':
+      return ` key=${event.key}`
+    case 'bridgeUp':
+    case 'bridgeDown':
+    case 'tick':
+      return ''
+  }
+}
+
+/** Test hook: reset state to the initial empty machine. */
+export function __shadowResetForTests(): void {
+  state = initialState()
+}
+
+/** Test hook: read the current shadow state. */
+export function __shadowGetStateForTests(): State {
+  return state
+}
+
+/** Test hook: check if shadow mode is enabled (mirrors the env-var). */
+export function __shadowEnabledForTests(): boolean {
+  return enabled
+}

package/telegram-plugin/gateway/inbound-delivery-machine.ts

@@ -0,0 +1,435 @@
+/**
+ * InboundDeliveryStateMachine — pure transition function for the
+ * gateway's inbound→bridge→outbound pipeline.
+ *
+ * Per `docs/rfcs/inbound-delivery-state-machine.md` (RFC merged in
+ * PR #1576): the gateway's delivery state was implicit and scattered
+ * across 8+ pieces of mutable state. The wedge cluster of 2026-05-19
+ * (9 PRs in 36h all patching variants of "inbound stranded → 5-min
+ * silence-poke fallback") and the v0.12.22 self-blocking gate bug
+ * (#1573, symptom-level) shared one root cause: no model anywhere in
+ * the codebase said "given these inputs, what should the gateway do."
+ *
+ * This module IS that model.
+ *
+ * ## Contract
+ *
+ *   transition(state, event) → { state', effects[] }
+ *
+ * Pure. No I/O. No timers. No mutation of inputs. The gateway
+ * dispatcher receives `{ state', effects[] }` and EXECUTES the
+ * effects against the real bridge/buffer/spool/Telegram. The
+ * machine never touches those directly.
+ *
+ * Property-tested by 5 invariants (see
+ * `tests/inbound-delivery-machine.test.ts`):
+ *
+ *   #1 — Every `inbound` event is delivered XOR persisted
+ *   #2 — Every `setTurnStarted(key)` paired with `clearTurnStarted(key)`
+ *        before the next end-of-life event for that key
+ *   #3 — Per-chat sibling-key cleanup on `turnEnd`
+ *   #4 — `permVerdict` delivered iff bridge alive; else persisted +
+ *        re-delivered on next `bridgeUp`
+ *   #5 — Spurious-fallback suppression (no `firePoke('fallback')` if
+ *        the model produced an outbound for this key in the last 60s)
+ *
+ * ## Scope of this PR
+ *
+ * This is PR 1 of the 3-PR cutover (per RFC). The module is exported
+ * but NOT WIRED into `gateway.ts`. PR 2 will swap the gateway's
+ * imperative paths to dispatch through this machine. PR 3 will
+ * delete the now-redundant primitives.
+ *
+ * Zero production behavior change in this PR. The property test is
+ * the only gate.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// Branded types — chat-key namespace
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical chat-thread key. Use the existing `chatKey()` helper from
+ * `./chat-key.ts` to construct one — that helper collapses
+ * 0/null/undefined thread IDs to the same token (#1564 sibling-key
+ * canonicalization). The state machine treats `ChatKey` as opaque.
+ */
+export type ChatKey = string & { readonly __brand: 'ChatKey' }
+
+// ─────────────────────────────────────────────────────────────────────
+// State
+// ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Global delivery state. Mirrors the existing `currentTurn` singleton
+ * but explicit. The gateway has ONE bridge connection (single claude
+ * process per agent container), so global state is the right model.
+ */
+export type GlobalState =
+  | { kind: 'bridge_dead' }
+  | { kind: 'bridge_alive_idle' }
+  | { kind: 'bridge_alive_in_turn'; activeTurn: ChatKey }
+
+/**
+ * Per-key state. Lifts the scattered `activeTurnStartedAt` Map and
+ * silence-poke's per-key `lastOutboundAt` tracking into ONE place.
+ *
+ * `turnStartedAt`: when this chat's current turn began (null = no
+ * turn active for this key). Mirrors the existing
+ * `activeTurnStartedAt[key]` value.
+ *
+ * `lastOutboundAt`: when the model last produced an outbound for
+ * this key. CARRIES ACROSS TURNS — this is invariant #5's data: even
+ * if a new turn starts (overlapping turns case from the
+ * 2026-05-20 mid-turn silence wedge), the model's recent outbound is
+ * preserved so a spurious fallback fire is suppressed.
+ */
+export interface PerKeyState {
+  readonly turnStartedAt: number | null
+  readonly lastOutboundAt: number | null
+}
+
+export interface State {
+  readonly global: GlobalState
+  readonly perKey: ReadonlyMap<ChatKey, PerKeyState>
+}
+
+export function initialState(): State {
+  return {
+    global: { kind: 'bridge_dead' },
+    perKey: new Map(),
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Events
+// ─────────────────────────────────────────────────────────────────────
+
+export interface InboundMessage {
+  readonly msgId: number
+  readonly isSteering: boolean
+  readonly payload: unknown
+}
+
+export interface PermissionVerdict {
+  readonly requestId: string
+  readonly behavior: 'allow' | 'deny' | 'allow_once' | 'allow_always'
+  readonly payload: unknown
+}
+
+export interface SpooledInbound {
+  readonly key: ChatKey
+  readonly msg: InboundMessage
+}
+
+export type Event =
+  | { kind: 'bridgeUp'; at: number }
+  | { kind: 'bridgeDown'; at: number }
+  | { kind: 'turnStart'; key: ChatKey; at: number }
+  | { kind: 'turnEnd'; key: ChatKey; at: number; outboundEmitted: boolean }
+  | { kind: 'inbound'; key: ChatKey; msg: InboundMessage; at: number }
+  | { kind: 'permVerdict'; verdict: PermissionVerdict; at: number }
+  | { kind: 'modelOutbound'; key: ChatKey; at: number }
+  | { kind: 'tick'; now: number }
+
+// ─────────────────────────────────────────────────────────────────────
+// Effects (returned, not performed)
+// ─────────────────────────────────────────────────────────────────────
+
+export type Effect =
+  | { kind: 'deliverToBridge'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'bufferInbound'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'persistInbound'; key: ChatKey; msg: InboundMessage }
+  | { kind: 'drainBuffer' }
+  | { kind: 'setTurnStarted'; key: ChatKey; at: number }
+  | { kind: 'clearTurnStarted'; key: ChatKey }
+  | { kind: 'noteOutbound'; key: ChatKey; at: number }
+  | { kind: 'firePoke'; key: ChatKey; level: 'soft' | 'firm' | 'fallback' }
+  | { kind: 'deliverPermVerdict'; verdict: PermissionVerdict }
+  | { kind: 'persistPermVerdict'; verdict: PermissionVerdict }
+  | { kind: 'redeliverPersistedPermVerdicts' }
+  | { kind: 'logTrace'; stage: string; key?: ChatKey; metadata?: Readonly<Record<string, unknown>> }
+
+// ─────────────────────────────────────────────────────────────────────
+// Tunable timings (match the production silence-poke ladder for now;
+// the RFC includes a recommendation to tighten these in a follow-up,
+// but parity-first for the PR-2 cutover).
+// ─────────────────────────────────────────────────────────────────────
+
+export const TURN_TTL_MS = 300_000 // 5 min — silence-poke fallback threshold
+export const SOFT_POKE_MS = 75_000
+export const FIRM_POKE_MS = 180_000
+export const OUTBOUND_RECENT_MS = 60_000 // invariant #5 suppression window
+
+// ─────────────────────────────────────────────────────────────────────
+// Transition function
+// ─────────────────────────────────────────────────────────────────────
+
+export interface Transition {
+  readonly state: State
+  readonly effects: readonly Effect[]
+}
+
+function emptyPerKey(): PerKeyState {
+  return { turnStartedAt: null, lastOutboundAt: null }
+}
+
+function updatePerKey(
+  state: State,
+  key: ChatKey,
+  update: (prior: PerKeyState) => PerKeyState,
+): State {
+  const prior = state.perKey.get(key) ?? emptyPerKey()
+  const next = update(prior)
+  const m = new Map(state.perKey)
+  // Empty entries (both fields null) are pruned to keep the map tight
+  // — invariant #2's test reads the map size and we don't want stale
+  // empty entries inflating it.
+  if (next.turnStartedAt == null && next.lastOutboundAt == null) {
+    m.delete(key)
+  } else {
+    m.set(key, next)
+  }
+  return { ...state, perKey: m }
+}
+
+function chatIdOfKey(key: ChatKey): string {
+  // ChatKey shape is `${chatId}:${threadOrUnderscore}`. Splitting on
+  // the FIRST colon gives the chatId — robust to threads/suffixes.
+  const idx = key.indexOf(':')
+  return idx === -1 ? key : key.slice(0, idx)
+}
+
+/**
+ * Sweep all sibling keys for a chatId — Invariant #3. After the last
+ * turnEnd for a chatId, no sibling thread keys should remain.
+ *
+ * Effect: emits `clearTurnStarted` for every sibling key still
+ * holding `turnStartedAt != null`. Returns updated state.
+ *
+ * The state machine's invariant is enforced because we PROACTIVELY
+ * purge siblings on turnEnd. The production sibling-key sweep
+ * (#1564's `purgeStaleTurnsForChat`) becomes redundant.
+ */
+function sweepSiblings(
+  state: State,
+  chatId: string,
+  exceptKey: ChatKey,
+): { state: State; effects: Effect[] } {
+  const effects: Effect[] = []
+  let next = state
+  for (const [k, v] of state.perKey) {
+    if (k === exceptKey) continue
+    if (chatIdOfKey(k) !== chatId) continue
+    if (v.turnStartedAt == null) continue
+    effects.push({ kind: 'clearTurnStarted', key: k })
+    next = updatePerKey(next, k, (p) => ({ ...p, turnStartedAt: null }))
+  }
+  return { state: next, effects }
+}
+
+export function transition(state: State, event: Event): Transition {
+  switch (event.kind) {
+    case 'bridgeUp': {
+      if (state.global.kind !== 'bridge_dead') {
+        // Idempotent: a second bridgeUp is a no-op.
+        return { state, effects: [{ kind: 'logTrace', stage: 'bridgeUp_redundant' }] }
+      }
+      return {
+        state: { ...state, global: { kind: 'bridge_alive_idle' } },
+        effects: [
+          { kind: 'redeliverPersistedPermVerdicts' },
+          { kind: 'drainBuffer' },
+          { kind: 'logTrace', stage: 'bridge_recover' },
+        ],
+      }
+    }
+
+    case 'bridgeDown': {
+      // Keep perKey state intact — the next bridgeUp + turnEnd will
+      // resolve naturally. Clearing turn state on bridge flap was the
+      // wedge-cluster's "drain on disconnect" footgun.
+      return {
+        state: { ...state, global: { kind: 'bridge_dead' } },
+        effects: [{ kind: 'logTrace', stage: 'bridge_flap' }],
+      }
+    }
+
+    case 'inbound': {
+      const isSteering = event.msg.isSteering
+      const inTurn = state.global.kind === 'bridge_alive_in_turn'
+      const alive = state.global.kind !== 'bridge_dead'
+
+      if (!alive) {
+        return {
+          state,
+          effects: [
+            { kind: 'bufferInbound', key: event.key, msg: event.msg },
+            { kind: 'persistInbound', key: event.key, msg: event.msg },
+            { kind: 'logTrace', stage: 'inbound_bridge_dead_buffer', key: event.key },
+          ],
+        }
+      }
+
+      if (inTurn && !isSteering) {
+        // Mid-turn non-steering inbound: buffer (the #1556 contract).
+        return {
+          state,
+          effects: [
+            { kind: 'bufferInbound', key: event.key, msg: event.msg },
+            { kind: 'persistInbound', key: event.key, msg: event.msg },
+            { kind: 'logTrace', stage: 'inbound_held_mid_turn', key: event.key, metadata: { msgId: event.msg.msgId } },
+          ],
+        }
+      }
+
+      // Alive + (idle OR steering): deliver immediately.
+      // Steering messages reach claude mid-turn intentionally; they
+      // do NOT start a new turn (existing turn continues).
+      if (isSteering) {
+        return {
+          state,
+          effects: [
+            { kind: 'deliverToBridge', key: event.key, msg: event.msg },
+            { kind: 'logTrace', stage: 'steer_delivered_mid_turn', key: event.key },
+          ],
+        }
+      }
+
+      // Fresh turn: state transitions to in_turn(key), perKey
+      // turnStartedAt is set, message delivered.
+      const next: State = {
+        global: { kind: 'bridge_alive_in_turn', activeTurn: event.key },
+        perKey: state.perKey,
+      }
+      return {
+        state: updatePerKey(next, event.key, (p) => ({ ...p, turnStartedAt: event.at })),
+        effects: [
+          { kind: 'setTurnStarted', key: event.key, at: event.at },
+          { kind: 'deliverToBridge', key: event.key, msg: event.msg },
+          { kind: 'logTrace', stage: 'fresh_turn_deliver', key: event.key, metadata: { msgId: event.msg.msgId } },
+        ],
+      }
+    }
+
+    case 'turnStart': {
+      // External signal that a turn has begun (e.g. session_event
+      // from bridge). Distinct from the implicit turn-start in
+      // `inbound`: a turn can begin without a fresh inbound (cron
+      // injection, scheduled fire).
+      const next: State = state.global.kind === 'bridge_alive_in_turn'
+        ? state
+        : { ...state, global: { kind: 'bridge_alive_in_turn', activeTurn: event.key } }
+      return {
+        state: updatePerKey(next, event.key, (p) => ({ ...p, turnStartedAt: event.at })),
+        effects: [
+          { kind: 'setTurnStarted', key: event.key, at: event.at },
+          { kind: 'logTrace', stage: 'turn_start', key: event.key },
+        ],
+      }
+    }
+
+    case 'turnEnd': {
+      // Clear turn state for the ending key AND sweep siblings
+      // (invariant #3). Transition global to idle if the ending turn
+      // was the active one.
+      const chatId = chatIdOfKey(event.key)
+      const stateAfterClear = updatePerKey(state, event.key, (p) => ({
+        turnStartedAt: null,
+        lastOutboundAt: event.outboundEmitted ? event.at : p.lastOutboundAt,
+      }))
+      const sweep = sweepSiblings(stateAfterClear, chatId, event.key)
+      const wasActive = state.global.kind === 'bridge_alive_in_turn' && state.global.activeTurn === event.key
+      const next: State = wasActive
+        ? { ...sweep.state, global: { kind: 'bridge_alive_idle' } }
+        : sweep.state
+      const effects: Effect[] = [
+        { kind: 'clearTurnStarted', key: event.key },
+        ...sweep.effects,
+      ]
+      if (event.outboundEmitted) {
+        effects.push({ kind: 'noteOutbound', key: event.key, at: event.at })
+      }
+      effects.push({ kind: 'drainBuffer' })
+      effects.push({ kind: 'logTrace', stage: 'turn_complete', key: event.key, metadata: { outboundEmitted: event.outboundEmitted } })
+      return { state: next, effects }
+    }
+
+    case 'modelOutbound': {
+      // Updates lastOutboundAt for the key. Does NOT change global
+      // state. This is invariant #5's data: it carries across turn
+      // boundaries so a spurious fallback can be suppressed.
+      return {
+        state: updatePerKey(state, event.key, (p) => ({ ...p, lastOutboundAt: event.at })),
+        effects: [
+          { kind: 'noteOutbound', key: event.key, at: event.at },
+        ],
+      }
+    }
+
+    case 'permVerdict': {
+      const alive = state.global.kind !== 'bridge_dead'
+      if (alive) {
+        return {
+          state,
+          effects: [
+            { kind: 'deliverPermVerdict', verdict: event.verdict },
+            { kind: 'logTrace', stage: 'perm_verdict_delivered' },
+          ],
+        }
+      }
+      return {
+        state,
+        effects: [
+          { kind: 'persistPermVerdict', verdict: event.verdict },
+          { kind: 'logTrace', stage: 'perm_verdict_persisted' },
+        ],
+      }
+    }
+
+    case 'tick': {
+      // Scan perKey for stale turns. For each entry with a non-null
+      // turnStartedAt where `now - turnStartedAt > TURN_TTL_MS`:
+      //   - Check lastOutboundAt: if it's null OR more than
+      //     OUTBOUND_RECENT_MS old, fire the fallback poke + clear.
+      //   - Otherwise suppress (invariant #5).
+      const effects: Effect[] = []
+      let next = state
+      for (const [k, v] of state.perKey) {
+        if (v.turnStartedAt == null) continue
+        const age = event.now - v.turnStartedAt
+        if (age <= TURN_TTL_MS) {
+          // Not yet stale enough for fallback. Soft/firm pokes are
+          // not modeled here yet — they're advisory, the gateway
+          // emits them; the state machine governs the fallback gate.
+          continue
+        }
+        // Stale enough for fallback. Check the suppression window.
+        const recentOutbound =
+          v.lastOutboundAt != null && (event.now - v.lastOutboundAt) < OUTBOUND_RECENT_MS
+        if (recentOutbound) {
+          // Invariant #5: model recently broke silence; suppress fire.
+          effects.push({ kind: 'logTrace', stage: 'fallback_suppressed', key: k, metadata: { recentOutboundMs: event.now - (v.lastOutboundAt ?? 0) } })
+          continue
+        }
+        // Fire the fallback + clear the turn.
+        effects.push({ kind: 'firePoke', key: k, level: 'fallback' })
+        effects.push({ kind: 'clearTurnStarted', key: k })
+        next = updatePerKey(next, k, (p) => ({ ...p, turnStartedAt: null }))
+        // If this was the active turn globally, drop to idle.
+        if (next.global.kind === 'bridge_alive_in_turn' && next.global.activeTurn === k) {
+          next = { ...next, global: { kind: 'bridge_alive_idle' } }
+        }
+      }
+      return { state: next, effects }
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Test-only helpers — mirror silence-poke.ts's __XForTests idiom
+// ─────────────────────────────────────────────────────────────────────
+
+export function __chatIdOfKeyForTests(key: ChatKey): string {
+  return chatIdOfKey(key)
+}