switchroom 0.19.16 → 0.19.18

package/telegram-plugin/silence-poke.ts

@@ -193,6 +193,8 @@ export interface MidTurnFloorContext {
 export type SilencePokeMetric =
   | { kind: 'silence_fallback_sent'; key: string; fallback_kind: 'working' | 'thinking'; silence_ms: number }
   | { kind: 'mid_turn_floor'; key: string; silence_ms: number; forced: boolean; decision: 'fire' | string }
+  /** #3552 — per-turn state dropped because its turn is provably over. */
+  | { kind: 'silence_poke_orphan_reaped'; key: string; silence_ms: number }
 
 export interface SilencePokeDeps {
   /** Called when the 300s fallback fires. Caller sends the user-visible
@@ -239,6 +241,30 @@ export interface SilencePokeDeps {
    * combines both. Returns null when there is no live turn for `key`.
    */
   floorState?: (key: string) => { role: LoopRole; finalAnswerDelivered: boolean } | null
+  /**
+   * #3552 — orphan-state reaper predicate. Returns true while `key` still has a
+   * LIVE turn behind it, false once the turn is provably over.
+   *
+   * Why: `startTurn(key)` arms per-turn state that only `endTurn(key)` drops,
+   * and several turn-end paths never reach an `endTurn` call — a bridge death
+   * (`disconnect-flush`), a keyed teardown that bypasses the `turn_end` handler,
+   * or any future path that nulls the turn without the cleanup tail. The state
+   * then survives its turn and sits in the Map until the 300s fallback fires
+   * against a dead key, is recognised as a late fire, logs
+   * `turn_ended_cleanly_during_window` and only THEN calls `endTurn`. Measured:
+   * 504 such skips vs 110 real fires in 14 days (switchroom#3552).
+   *
+   * Wiring this callback moves that cleanup from "300s later, at fire time" to
+   * "the next poll tick", deterministically and independent of which path ended
+   * the turn. The predicate MUST be the same one the fallback's late-fire guard
+   * uses (`activeTurnStartedAt` empty AND no current turn) so a turn that has
+   * merely released its buffer gate mid-turn — the normal post-final-answer
+   * state, where silence-poke must keep watching — is never reaped.
+   *
+   * Optional: when absent (test harnesses) the reaper is off and behaviour is
+   * exactly as before.
+   */
+  isTurnLive?: (key: string) => boolean
 }
 
 const state = new Map<string, SilencePokeState>()
@@ -505,6 +531,105 @@ export function formatFrameworkFallbackText(
   return null
 }
 
+/**
+ * #3551 — inputs to the silence-fallback TEARDOWN NOTICE decision.
+ *
+ * Distinct from `formatFrameworkFallbackText`, which answers "is anything
+ * happening worth narrating?" (and, since the stall-notice was retired,
+ * answers `null` on every branch but `blockedOnApproval`). This one answers a
+ * different, terminal question: "the framework is about to END this live turn
+ * — does the user need to be told?"
+ */
+export interface FallbackTeardownNoticeInput {
+  /** This fire is genuinely tearing down a live turn for THIS chat/thread.
+   *  False on the multi-chat case where the current turn belongs elsewhere, or
+   *  when there was no turn left to end. */
+  tearsDownLiveTurn: boolean
+  /** Loop role of the turn being torn down; null when unknown. */
+  role: LoopRole | null
+  /** A final answer already landed on this turn. */
+  finalAnswerDelivered: boolean
+  /** This fire ALREADY DELIVERED a LOUD, user-addressed message about why
+   *  nothing is happening — in practice the approval re-ping ("waiting for your
+   *  approval — tap Approve or Deny"). Never stack a second message on that.
+   *
+   *  #3551 L1: deliberately NARROWER than "some text went out". The other text
+   *  this fire can emit is `formatUpdateStatusLine`, a SILENT status surface
+   *  about an unrelated in-flight `update_apply` that says nothing about this
+   *  turn ending — a user who asked a question during an update and got killed
+   *  anyway is exactly the case this notice exists for, so that line must NOT
+   *  suppress it.
+   *  #3551 L2: means DELIVERED, not "attempted". The caller's send is wrapped in
+   *  a log-only try/catch, so a throwing re-ping must not buy silence. */
+  userAddressedTextDelivered: boolean
+  /** The obligation ledger is on, so the killed turn's unanswered inbound will
+   *  be re-presented. Governs the tail sentence — never claim a re-ask that
+   *  cannot happen. */
+  representWillFollow: boolean
+  silenceMs: number
+}
+
+export type FallbackTeardownNoticeDecision =
+  | {
+      send: false
+      reason:
+        | 'user-addressed-text-delivered'
+        | 'no-live-turn-torn-down'
+        | 'non-user-turn'
+        | 'answer-already-delivered'
+    }
+  | { send: true; text: string }
+
+/**
+ * #3551 — decide whether a silence-poke fire that ENDS a live turn must say so.
+ *
+ * The bug this closes: on the non-approval branch the 300s fallback delivered
+ * NO text (`formatFrameworkFallbackText` returns null) while still tearing the
+ * turn down and redelivering buffered inbound. From the user's seat: five
+ * minutes of nothing, then the agent inexplicably restarting the same request,
+ * with no signal that the framework — not the agent — made that happen.
+ * Measured: 110 fires / 14 days, p50 silence 302s, ~9h of dead air.
+ *
+ * The fix is NOT to stop killing the turn. The teardown is the fallback's one
+ * genuinely load-bearing job (`#1122`: without it every later inbound queues
+ * behind a dead turn forever), and removing it would trade a silent turn for a
+ * permanently wedged conversation. The fix is to make the kill OBSERVABLE.
+ *
+ * This is deliberately NOT a re-introduction of the retired stall notice, and
+ * the gates below are what keep it that way:
+ *   - `userAddressedTextDelivered` — never stack on a delivered approval
+ *     re-ping. Narrow by design: a SILENT, unrelated update-status line does
+ *     not buy silence here (#3551 L1), and an approval re-ping that threw on
+ *     send does not either (#3551 L2).
+ *   - `tearsDownLiveTurn` — a late-fire against an already-dead key says nothing.
+ *   - `role !== 'user'` — a cron/system turn's silence is legitimate; nobody is
+ *     waiting, so its teardown is housekeeping, not news.
+ *   - `finalAnswerDelivered` — the user already has their answer; ending the
+ *     residual housekeeping turn is invisible to them and needs no notice.
+ * What remains is exactly one case: a HUMAN asked something, got nothing for
+ * N minutes, and the framework just ended that attempt. That is a terminal
+ * event, fired at most once per turn (the caller drops the key immediately
+ * after), not a cadence-based progress ping — the thing
+ * `reference/rfcs/conversational-pacing.md` § Anti-patterns bans.
+ */
+export function decideFallbackTeardownNotice(
+  input: FallbackTeardownNoticeInput,
+): FallbackTeardownNoticeDecision {
+  if (input.userAddressedTextDelivered)
+    return { send: false, reason: 'user-addressed-text-delivered' }
+  if (!input.tearsDownLiveTurn) return { send: false, reason: 'no-live-turn-torn-down' }
+  if (input.role !== 'user') return { send: false, reason: 'non-user-turn' }
+  if (input.finalAnswerDelivered) return { send: false, reason: 'answer-already-delivered' }
+  const minutes = Math.max(1, Math.round(input.silenceMs / 60_000))
+  const tail = input.representWillFollow
+    ? 'Your message is still tracked and is being re-asked now.'
+    : 'Your message was not answered — please re-send it.'
+  return {
+    send: true,
+    text: `⚠️ no output for ${minutes} min — the framework ended that stalled turn. ${tail}`,
+  }
+}
+
 /**
  * #2995 — the LONGEST-running in-flight tool for a turn key, or null when
  * none is tracked. Read-only accessor over `inFlightTools` for the
@@ -603,6 +728,19 @@ function tick(now: number): void {
     const silence = now - zeroAt
     if (silence < 0) continue
 
+    // #3552 — orphan reap. Drop per-turn state the moment its turn is provably
+    // over, instead of leaving it armed until the 300s fallback fires against a
+    // dead key and disarms it as a "late fire". Deterministic and path-agnostic:
+    // it does not matter WHICH turn-end path forgot to call `endTurn`, the state
+    // cannot outlive the turn by more than one poll interval. Same predicate as
+    // the fallback's late-fire guard, so a mid-turn buffer-gate release (the
+    // normal post-final-answer state, turn still live) is never reaped.
+    if (activeDeps.isTurnLive != null && !activeDeps.isTurnLive(key)) {
+      state.delete(key)
+      activeDeps.emitMetric({ kind: 'silence_poke_orphan_reaped', key, silence_ms: silence })
+      continue
+    }
+
     // #2527 — the early, quiet mid-turn liveness beat (below the fallback
     // window). Evaluated every tick; fires at most once per turn.
     tryMidTurnFloor(key, s, now, false)

package/telegram-plugin/tests/boot-probe-drift.test.ts

@@ -0,0 +1,152 @@
+/**
+ * KEN-130 — boot-card drift probe. Outcome-asserting: a staled stamped
+ * surface or a host-written drift report produces a degraded probe row
+ * naming the surfaces; a clean agent dir stays ok (silent-when-healthy —
+ * ok probes never render a boot-card row).
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { probeDrift } from '../gateway/boot-probes.js'
+import {
+  CLAUDE_MD_YOURS_MARKER,
+  computeConfigHash,
+  computeStampFilesFromDisk,
+  writeGenerationStamp,
+} from '../../src/agents/generation-stamp.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'boot-drift-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+function seedAndStamp(): void {
+  writeFileSync(join(dir, 'start.sh'), '#!/bin/bash\necho hi\n')
+  writeFileSync(
+    join(dir, 'CLAUDE.md'),
+    `# Agent\nmanaged\n\n${CLAUDE_MD_YOURS_MARKER}\n\nyours\n`,
+  )
+  writeFileSync(join(dir, '.mcp.json'), '{"mcpServers":{}}\n')
+  writeGenerationStamp(dir, {
+    switchroomVersion: '1.0.0',
+    configHash: computeConfigHash({ model: 'opus' }),
+    files: computeStampFilesFromDisk(dir),
+  })
+}
+
+describe('probeDrift', () => {
+  it('clean agent dir with stamp → ok (no boot-card row)', async () => {
+    seedAndStamp()
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+
+  it('no stamp and no report (fresh agent / pre-KEN-130) → ok', async () => {
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+
+  it('tampered start.sh → degraded row naming start.sh with a next step', async () => {
+    seedAndStamp()
+    writeFileSync(join(dir, 'start.sh'), '#!/bin/bash\nTAMPERED\n')
+    const r = await probeDrift(dir, { agentName: 'bot' })
+    expect(r.status).toBe('degraded')
+    expect(r.detail).toContain('start.sh')
+    expect(r.nextStep).toContain('switchroom apply')
+    expect(r.nextStep).toContain('reconcile bot')
+  })
+
+  it('operator edit BELOW the CLAUDE.md marker → still ok', async () => {
+    seedAndStamp()
+    writeFileSync(
+      join(dir, 'CLAUDE.md'),
+      `# Agent\nmanaged\n\n${CLAUDE_MD_YOURS_MARKER}\n\ncompletely new operator prose\n`,
+    )
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+
+  it('host drift report findings surface on the row (with age when stale)', async () => {
+    seedAndStamp()
+    // Backdate the stamp so the report post-dates the last apply (a
+    // report older than the stamp is legitimately suppressed — see the
+    // superseded-by-apply test below).
+    writeGenerationStamp(dir, {
+      generatedAt: new Date(Date.now() - 3 * 86_400_000).toISOString(),
+      switchroomVersion: '1.0.0',
+      configHash: computeConfigHash({ model: 'opus' }),
+      files: computeStampFilesFromDisk(dir),
+    })
+    const twoDaysAgo = new Date(Date.now() - 2 * 86_400_000).toISOString()
+    writeFileSync(
+      join(dir, '.switchroom-drift.json'),
+      JSON.stringify({
+        version: 1,
+        generatedAt: twoDaysAgo,
+        findings: [
+          { surface: 'compose', detail: 'deployed compose differs' },
+          { surface: 'hook-scripts', detail: 'image scripts stale' },
+        ],
+      }),
+    )
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('degraded')
+    expect(r.detail).toContain('compose')
+    expect(r.detail).toContain('hook-scripts')
+    expect(r.detail).toContain('ago') // stale-report age annotation
+  })
+
+  it('report older than the stamp (apply healed it) → ok, findings suppressed', async () => {
+    // Doctor found drift, then the operator ran `switchroom apply` — the
+    // reconcile rewrote the stamp but NOT the doctor report. A freshly
+    // applied fleet must be silent; the stale report is superseded.
+    writeFileSync(
+      join(dir, '.switchroom-drift.json'),
+      JSON.stringify({
+        version: 1,
+        generatedAt: new Date(Date.now() - 3_600_000).toISOString(),
+        findings: [{ surface: 'compose', detail: 'was drifted before apply' }],
+      }),
+    )
+    seedAndStamp() // stamp written AFTER the report
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+
+  it('report newer than the stamp still surfaces (drift found after apply)', async () => {
+    seedAndStamp()
+    writeFileSync(
+      join(dir, '.switchroom-drift.json'),
+      JSON.stringify({
+        version: 1,
+        generatedAt: new Date(Date.now() + 1000).toISOString(),
+        findings: [{ surface: 'hook-scripts', detail: 'image scripts stale' }],
+      }),
+    )
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('degraded')
+    expect(r.detail).toContain('hook-scripts')
+  })
+
+  it('empty host report (doctor ran clean) → ok', async () => {
+    seedAndStamp()
+    writeFileSync(
+      join(dir, '.switchroom-drift.json'),
+      JSON.stringify({ version: 1, generatedAt: new Date().toISOString(), findings: [] }),
+    )
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+
+  it('corrupt report is ignored, never degrades the boot card', async () => {
+    seedAndStamp()
+    writeFileSync(join(dir, '.switchroom-drift.json'), 'not json at all')
+    const r = await probeDrift(dir)
+    expect(r.status).toBe('ok')
+  })
+})

package/telegram-plugin/tests/gateway-disconnect-flush.test.ts

@@ -282,3 +282,35 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
     expect(deps.activeTurnStartedAt.size).toBe(0)
   })
 })
+
+describe('#3552 — onTurnKeyEnded disarms per-turn timers on bridge death', () => {
+  it('reports EVERY torn-down turn key, from both the controller loop and the dangling sweep', () => {
+    const { deps } = makeDeps('clerk')
+    // A third key that the controller loop does not cover — it only lives in
+    // activeTurnStartedAt (finalize already ran on the canonical reply path),
+    // so it is picked up by the dangling sweep.
+    deps.activeTurnStartedAt.set('chat3:thr3:msg3', 300)
+    const ended: string[] = []
+
+    flushOnAgentDisconnect({ ...deps, onTurnKeyEnded: (k: string) => ended.push(k) })
+
+    // Outcome: no turn key survives the flush without being reported, so no
+    // silence-poke state can outlive the dead bridge's turns.
+    expect(new Set(ended)).toEqual(
+      new Set(['chat1:thr1:msg1', 'chat2:thr2:msg2', 'chat3:thr3:msg3']),
+    )
+    expect(deps.activeTurnStartedAt.size).toBe(0)
+  })
+
+  it('is never called for an anonymous disconnect (no turns were owned)', () => {
+    const { deps } = makeDeps(null)
+    const ended: string[] = []
+    flushOnAgentDisconnect({ ...deps, onTurnKeyEnded: (k: string) => ended.push(k) })
+    expect(ended).toEqual([])
+  })
+
+  it('omitting onTurnKeyEnded is safe (optional callback)', () => {
+    const { deps } = makeDeps('clerk')
+    expect(() => flushOnAgentDisconnect(deps)).not.toThrow()
+  })
+})

package/telegram-plugin/tests/handback-preturn-signal.test.ts

@@ -333,6 +333,68 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.openCard).toHaveBeenCalledTimes(1)
   })
 
+  // ── #3544 ──────────────────────────────────────────────────────────────
+  // The 30 s orphan reap used to call `stopTypingLoop` unconditionally. That
+  // loop is keyed on (chat, thread), NOT on this seam's entry — so a handback
+  // turn still composing at 30 s had its indicator killed mid-turn, and nothing
+  // re-armed it. Outcome assertion: chat actions are still landing at 45 s.
+  it('#3544 — the orphan reap keeps typing alive when a real turn is live on the key (still emitting at 45s)', async () => {
+    vi.useFakeTimers()
+    try {
+      const liveKeys = new Set<string>()
+      const h = makeHarness({ hasLiveTurn: (k) => liveKeys.has(k) })
+      h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatH', messageId: 900 }))
+      await h.sched.advance(700) // debounce fires: typing armed, card painted
+      expect(h.typing.activeCount()).toBe(1)
+
+      // The handback's turn mints and is composing (a long one — worker results
+      // to read, a reply to write).
+      liveKeys.add('chatH:_')
+      const beforeReap = h.sendChatAction.mock.calls.length
+
+      await h.sched.advance(30_000) // the age-based orphan reap fires
+      // Pre-#3544 this was 0 and the chat went dark for the rest of the turn.
+      expect(h.typing.activeCount()).toBe(1)
+
+      // …and it is genuinely still EMITTING (not merely registered) at 45 s.
+      vi.advanceTimersByTime(15_000) // 15 s of the loop's 4 s refresh
+      expect(h.sendChatAction.mock.calls.length).toBeGreaterThan(beforeReap + 2)
+      expect(h.sendChatAction).toHaveBeenLastCalledWith('chatH', null)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('#3544 — the orphan reap still stops typing when NO turn is live (no leaked interval)', async () => {
+    const h = makeHarness({ hasLiveTurn: () => false })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatI', messageId: 901 }))
+    await h.sched.advance(700)
+    expect(h.typing.activeCount()).toBe(1)
+    await h.sched.advance(30_000)
+    expect(h.typing.activeCount()).toBe(0)
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  it('#3544 — handleReaped keeps typing alive for a live turn, stops it otherwise', async () => {
+    const liveKeys = new Set<string>()
+    const h = makeHarness({ hasLiveTurn: (k) => liveKeys.has(k) })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatJ', messageId: 902 }))
+    await h.sched.advance(700)
+    const syntheticKey = [...h.records.keys()][0]!
+    expect(syntheticKey.startsWith(PRETURN_TURNKEY_PREFIX)).toBe(true)
+    liveKeys.add('chatJ:_')
+    h.signal.handleReaped(syntheticKey)
+    expect(h.typing.activeCount()).toBe(1) // live turn owns the stop
+    expect(h.signal.pendingCount()).toBe(0) // entry still dropped
+
+    // Same hook with no live turn DOES stop the loop.
+    const h2 = makeHarness({ hasLiveTurn: () => false })
+    h2.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatK', messageId: 903 }))
+    await h2.sched.advance(700)
+    h2.signal.handleReaped([...h2.records.keys()][0]!)
+    expect(h2.typing.activeCount()).toBe(0)
+  })
+
   it('skips the emit when the adopting turn already settled before the debounce fires', async () => {
     const settled = new Set<string>()
     const h = makeHarness({ isTurnSettled: (k) => settled.has(k) })

package/telegram-plugin/tests/helpers/liveness-wiring-fixture.ts

@@ -0,0 +1,178 @@
+/**
+ * Test fixture for the REAL `buildSilencePokeOptions` wiring (#3575 review B3).
+ *
+ * The two highest-blast-radius pieces of `liveness-wiring.ts` — the `isTurnLive`
+ * reaper predicate and the `onFrameworkFallback` teardown + notice — had NO
+ * executing coverage: `buildSilencePokeOptions` has exactly one caller (the
+ * gateway's module-load `startTimer`) and no test imported it, so the suite
+ * either stubbed the predicate or asserted regexes against the function's own
+ * SOURCE TEXT. A hand-retyped copy of a predicate cannot detect divergence, and
+ * a source regex passes even if the handler is never invoked.
+ *
+ * `buildSilencePokeOptions` is a pure function of its deps object (its only
+ * gateway import is `import type`), so the whole options object CAN be built in
+ * a unit test. This fixture supplies the collaborators the fallback actually
+ * touches, with spies on the two observable effects (`sendSilenceText`,
+ * `endCurrentTurnForKey`).
+ */
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { buildSilencePokeOptions } from '../../gateway/liveness-wiring.js'
+
+type Deps = Parameters<typeof buildSilencePokeOptions>[0]
+
+export interface SentText {
+  chatId: string
+  threadId: number | null
+  text: string
+  silent: boolean
+}
+
+export interface LivenessFixture {
+  deps: Deps
+  sent: SentText[]
+  endedKeys: string[]
+  /** The gateway's `activeTurnStartedAt` map, writable by the test. */
+  activeTurnStartedAt: Map<string, number>
+  /** Swap the "current turn" the wiring reads. */
+  setCurrentTurn: (t: unknown) => void
+  /**
+   * Start a turn FOR A TOPIC KEY. With a `turnMap` supplied (the flag-ON
+   * `CurrentTurnMap`), this is the gateway's `setCurrentTurn(turn, key)`: it
+   * writes the per-topic entry AND flips the most-recent-set mirror. Without
+   * one, it degrades to the flag-OFF singleton assignment.
+   */
+  setCurrentTurnForKey: (key: string, t: unknown) => void
+  /** Open obligation ids the per-turn `representWillFollow` lookup consults. */
+  openObligations: Set<string>
+}
+
+/**
+ * The subset of the REAL `CurrentTurnMap` (gateway/current-turn-map.ts) the
+ * liveness wiring touches. #3580 tests pass a genuine instance, re-imported
+ * under `SWITCHROOM_EMISSION_AUTHORITY=1` via the module's read-once seam, so
+ * the flag-ON mirror-vs-keyed semantics under test are the production ones and
+ * not a hand-retyped model of them.
+ */
+export interface TurnMapLike {
+  get(key?: string): unknown
+  set(turn: never, key: string): void
+  isLiveForKey(turn: never, key: string): boolean
+  endTurnForKey(turn: never, key: string): boolean
+  purgeChatStale(chatId: string, isStale?: (key: string) => boolean): string[]
+}
+
+export function statusKeyForTests(chatId: string, threadId: number | null | undefined): string {
+  return `${chatId}:${threadId ?? '_'}`
+}
+
+/** Minimal but REAL-shaped CurrentTurn for the fields the fallback reads. */
+export function makeTurn(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    sessionChatId: '-100999',
+    sessionThreadId: undefined,
+    turnId: '-100999#42',
+    registryKey: null,
+    role: 'user',
+    finalAnswerDelivered: false,
+    capturedText: [],
+    lastAssistantMsgId: null,
+    lastAssistantDone: false,
+    toolCallCount: 0,
+    ...over,
+  }
+}
+
+export function makeLivenessFixture(
+  over: Partial<Record<string, unknown>> = {},
+  turnMap?: TurnMapLike,
+): LivenessFixture {
+  const sent: SentText[] = []
+  const endedKeys: string[] = []
+  const activeTurnStartedAt = new Map<string, number>()
+  const openObligations = new Set<string>()
+  let currentTurn: unknown = null
+
+  // Mirrors gateway.ts's `gatewayLivenessWiringDeps()` exactly. Without a
+  // `turnMap` the fixture models the flag-OFF gateway, where `currentTurnMap`
+  // holds only the singleton and the keyed read `currentTurnMap.get(key)`
+  // returns it — hence `getCurrentTurnForKey` ignoring the key here is the
+  // production flag-OFF behaviour, not a shortcut. With a `turnMap` it is the
+  // real keyed store and every accessor delegates to it.
+  const turnMapDeps = turnMap == null
+    ? {
+        getCurrentTurn: () => currentTurn,
+        getCurrentTurnForKey: (_key: string) => currentTurn,
+        currentTurnMap: { purgeChatStale: () => {} },
+        turnLiveForItsTopic: () => true,
+        endCurrentTurnForKey: (_turn: unknown, key: string) => {
+          endedKeys.push(key)
+          currentTurn = null
+          return true
+        },
+      }
+    : {
+        getCurrentTurn: () => turnMap.get() ?? null,
+        getCurrentTurnForKey: (key: string) => turnMap.get(key) ?? null,
+        currentTurnMap: turnMap,
+        turnLiveForItsTopic: (turn: { sessionChatId: string; sessionThreadId?: number | null }) =>
+          turnMap.isLiveForKey(
+            turn as never,
+            statusKeyForTests(turn.sessionChatId, turn.sessionThreadId),
+          ),
+        endCurrentTurnForKey: (turn: unknown, key: string) => {
+          endedKeys.push(key)
+          return turnMap.endTurnForKey(turn as never, key)
+        },
+      }
+
+  const deps = {
+    SILENCE_FALLBACK_MS: 300_000,
+    SILENCE_FALLBACK_HARD_MS: 900_000,
+    SILENCE_FLOOR_MS: 90_000,
+    SILENCE_DEFER_INFLIGHT_TOOLS: false,
+    isObligationOpenForTurn: (originTurnId: string | null): boolean =>
+      originTurnId != null && openObligations.has(originTurnId),
+    TURN_PREVIEW_MAX: 200,
+    STATE_DIR: mkdtempSync(join(tmpdir(), 'liveness-wiring-')),
+    isLegitimatelyWorking: () => false,
+    ...turnMapDeps,
+    getInFlightUpdate: () => null,
+    getTurnsDb: () => null,
+    getInboundSpool: () => undefined,
+    sendToAgent: () => true,
+    sendSilenceText: async (chatId: string, threadId: number | null, text: string, silent: boolean) => {
+      sent.push({ chatId, threadId, text, silent })
+    },
+    getMyAgentName: () => 'test-agent',
+    statusKey: statusKeyForTests,
+    activeTurnStartedAt,
+    activeStatusReactions: new Map(),
+    lastPtyPreviewByChat: new Map(),
+    preambleSuppressor: { dropNow: () => {} },
+    purgeReactionTracking: () => {},
+    getPendingInboundBuffer: () => ({ drain: () => [] }),
+    trackRedeliveredInbound: () => {},
+    closeActivityLane: () => {},
+    closeProgressLane: () => {},
+    hangRestart: null,
+    ...over,
+  } as unknown as Deps
+
+  return {
+    deps,
+    sent,
+    endedKeys,
+    activeTurnStartedAt,
+    setCurrentTurn: (t: unknown) => {
+      if (turnMap != null) throw new Error('use setCurrentTurnForKey with a keyed turnMap')
+      currentTurn = t
+    },
+    setCurrentTurnForKey: (key: string, t: unknown) => {
+      if (turnMap == null) { currentTurn = t; return }
+      turnMap.set(t as never, key)
+    },
+    openObligations,
+  }
+}