switchroom 0.18.32 → 0.19.0

package/telegram-plugin/tests/status-pin-service-message-suppression.test.ts

@@ -1,16 +1,17 @@
 /**
- * Structural test for the `bot.on('message:pinned_message')` handler that
- * suppresses the "pinned a message" service message Telegram inserts when
- * OUR silent status-pin fires.
+ * Structural test for the `message:pinned_message` handler that suppresses the
+ * "pinned a message" service message Telegram inserts when OUR silent status-pin
+ * fires.
  *
- * Why structural: like every other gateway handler, this closure is wired
- * inline against the live `bot` instance and is not exported — a functional
- * invocation would require booting the full grammy runtime against a mocked
- * Bot API. The gateway suite settled on file-level grep assertions for
- * exactly this reason (see `inbound-message-types.test.ts`). The regression
- * we care about: a future hand dropping the handler, dropping the ownership
- * guard (which would let us delete manual/operator pins), or swapping the
- * house deletion wrapper for a raw `bot.api.deleteMessage` (allowlist drift).
+ * As of switchroom#2996 P6 cluster F the handler body lives in the extracted
+ * `gateway/pinned-message-handler.ts` module (unit-tested for real in
+ * `pinned-message-handler.test.ts`); gateway.ts keeps only the thin
+ * `bot.on('message:pinned_message', …)` delegation plus the injected
+ * `deleteServiceMessage` binding that wraps the raw `lockedBot.api.deleteMessage`
+ * in `robustApiCall`. The regressions this structural test still guards: a hand
+ * dropping the delegation, dropping the ownership guard (which would let us
+ * delete manual/operator pins), or moving the raw delete out from under the
+ * robust wrapper (allowlist drift).
  */
 
 import { describe, it, expect } from 'vitest'
@@ -25,66 +26,58 @@ const SRC = readFileSync(
   'utf8',
 )
 
-/**
- * Extract the body of the `bot.on('message:pinned_message', …)` handler:
- * from the `bot.on(` line to the matching outer-scope closing brace.
- */
-function pinnedMessageHandler(): string {
-  const needle = `bot.on('message:pinned_message'`
-  const start = SRC.indexOf(needle)
-  expect(start, `handler ${needle} not found`).toBeGreaterThan(0)
-  const firstBrace = SRC.indexOf('{', start)
-  let depth = 0
-  for (let i = firstBrace; i < SRC.length; i++) {
-    const c = SRC[i]
-    if (c === '{') depth++
-    else if (c === '}') {
-      depth--
-      if (depth === 0) return SRC.slice(start, i + 1)
-    }
-  }
-  throw new Error('could not find end of pinned_message handler')
-}
+const MODULE_SRC = readFileSync(
+  new URL('../gateway/pinned-message-handler.ts', import.meta.url),
+  'utf8',
+)
 
 describe('status-pin service-message suppression', () => {
-  it("registers a bot.on('message:pinned_message') handler", () => {
+  it("registers a bot.on('message:pinned_message') delegation to the extracted handler", () => {
     expect(SRC).toContain(`bot.on('message:pinned_message'`)
+    // The registration is now a thin delegation into the extracted module.
+    expect(SRC).toContain('handlePinnedMessage(ctx, pinnedMessageHandlerDeps)')
   })
 
-  const body = pinnedMessageHandler()
-
   it('guards on ownership via the chat-scoped pinnedMessageIsOurs helper', () => {
     // Must consult our tracked pins — never blindly delete a pin service
     // message (which would nuke manual/operator pins too) — AND it must be
     // chat-scoped (pinnedMessageIsOurs requires chatId + messageId), never a
     // messageId-only match.
-    expect(body).toContain('statusPinState')
-    expect(body).toMatch(/pinned_message\?\.message_id/)
-    expect(body).toContain('pinnedMessageIsOurs(')
+    expect(MODULE_SRC).toContain('deps.statusPinState')
+    expect(MODULE_SRC).toMatch(/pinned_message\?\.message_id/)
+    expect(MODULE_SRC).toContain('pinnedMessageIsOurs(')
     // The chatId computed from the update must be fed to the guard.
-    expect(body).toMatch(/pinnedMessageIsOurs\(trackedPins\(\), chatId, pinnedId\)/)
+    expect(MODULE_SRC).toMatch(/pinnedMessageIsOurs\(trackedPins\(\), chatId, pinnedId\)/)
     // And the tracked entries must carry their chat association.
-    expect(body).toContain('statusPinChatIds.get(pinKey)')
+    expect(MODULE_SRC).toContain('deps.statusPinChatIds.get(pinKey)')
   })
 
   it('bails out when the pinned message is not one of ours', () => {
     // A `return` guard for the non-owned case must exist.
-    expect(body).toMatch(/if \(!isOurs\(\)\) return/)
+    expect(MODULE_SRC).toMatch(/if \(!isOurs\(\)\) return/)
   })
 
   it('deletes the service message through the robust wrapper (not a raw api call)', () => {
-    expect(body).toContain('robustApiCall(')
-    expect(body).toContain('deleteMessage')
-    // The message deleted is the service message itself, not the pinned msg.
-    expect(body).toContain('serviceMsgId')
-    // House verb tag so operators can trace it.
-    expect(body).toContain("verb: 'status-pin.delete-service-message'")
+    // The extracted module carries no raw Bot API site — it calls the injected
+    // `deleteServiceMessage`, which gateway.ts binds through robustApiCall.
+    expect(MODULE_SRC).toContain('deps.deleteServiceMessage(chatId, serviceMsgId)')
+    // The module makes no raw Bot API call outside a comment (the docstring
+    // names the wrapped call as an example). Strip comment lines, then assert
+    // no `lockedBot.api.*(` invocation survives in executable code.
+    const codeOnly = MODULE_SRC.split('\n')
+      .filter(l => !/^\s*(\/\/|\*|\/\*)/.test(l))
+      .join('\n')
+    expect(codeOnly).not.toMatch(/lockedBot\.api\.\w+\(/)
+    // gateway.ts owns the robust wrapper + house verb tag.
+    expect(SRC).toContain('robustApiCall(')
+    expect(SRC).toContain('lockedBot.api.deleteMessage(chatId, serviceMsgId)')
+    expect(SRC).toContain("verb: 'status-pin.delete-service-message'")
   })
 
   it('tolerates the reconcile-store race with a short retry', () => {
     // The service update can arrive before reconcileStatusPin stores the
     // PinState; a single delayed re-check covers that window.
-    expect(body).toContain('setTimeout')
+    expect(MODULE_SRC).toContain('setTimeout')
   })
 })
 
@@ -199,9 +192,9 @@ describe('service-message deletion in supergroups / forum topics', () => {
 
   it('the handler logs a missing-admin-right hint on delete failure (supergroup)', () => {
     // Structural: the catch block names the likely supergroup cause so an
-    // operator isn't left with silent nothing.
+    // operator isn't left with silent nothing. Lives in the extracted module.
     const src = readFileSync(
-      new URL('../gateway/gateway.ts', import.meta.url),
+      new URL('../gateway/pinned-message-handler.ts', import.meta.url),
       'utf8',
     )
     expect(src).toContain('could not delete pin service message')

package/telegram-plugin/tests/stop-command.test.ts

@@ -17,6 +17,13 @@ import { switchroomHelpCommandNames, switchroomHelpText } from '../welcome-text.
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const GATEWAY_SRC = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf8')
+// P7 PR-2 (#2996): the handleInbound stop-keyword intercept block moved into
+// inbound-interceptors.ts (`interceptStopKeyword`). The coalescer bypass stays
+// in gateway.ts. Scrapes anchor on whichever file now owns each literal.
+const INTERCEPTORS_SRC = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'inbound-interceptors.ts'),
+  'utf8',
+)
 
 describe('parseStopKeyword', () => {
   it('matches the exact word stop, case-insensitively', () => {
@@ -177,18 +184,20 @@ describe('gateway wiring — /stop cancels the in-flight turn (#3020)', () => {
     expect(bypassIdx).toBeGreaterThan(0)
     const bypassWin = GATEWAY_SRC.slice(bypassIdx, bypassIdx + 800)
     expect(bypassWin).toContain('parseStopKeyword(text)')
-    // handleInbound keyword block: honest idle reply or halt + confirmation.
-    const kwIdx = GATEWAY_SRC.indexOf("executeHaltNow('stop-keyword')")
+    // interceptStopKeyword block (P7 PR-2, inbound-interceptors.ts): honest
+    // idle reply or halt + confirmation.
+    const kwIdx = INTERCEPTORS_SRC.indexOf("deps.executeHaltNow('stop-keyword')")
     expect(kwIdx).toBeGreaterThan(0)
-    const kwWin = GATEWAY_SRC.slice(kwIdx - 1600, kwIdx + 900)
-    expect(kwWin).toContain('turnInFlightForGate()')
+    const kwWin = INTERCEPTORS_SRC.slice(kwIdx - 1600, kwIdx + 900)
+    expect(kwWin).toContain('deps.turnInFlightForGate()')
     expect(kwWin).toContain('buildStopReply(inFlight, queuedLabels)')
     // Intercepted — never forwarded to the agent as a turn.
-    expect(kwWin).toContain('return')
+    expect(kwWin).toContain('return { handled: true }')
   })
 
   it('the empty-`!` interrupt routes through the same executeHaltNow helper', () => {
-    expect(GATEWAY_SRC).toContain("executeHaltNow('bang-empty')")
+    // P7 PR-3: the `!`-marker intercept moved to inbound-interceptors.ts.
+    expect(INTERCEPTORS_SRC).toContain("deps.executeHaltNow('bang-empty')")
   })
 
   it('/stop with an argument warns and does NOT halt (old container-stop muscle memory)', () => {
@@ -210,12 +219,13 @@ describe('gateway wiring — /stop cancels the in-flight turn (#3020)', () => {
       'parseStopKeyword(text) && downloadImage == null && attachment == null',
     )
     expect(bypassIdx).toBeGreaterThan(0)
-    // handleInbound keyword block: also excludes coalesced extra attachments.
-    const kwIdx = GATEWAY_SRC.indexOf("executeHaltNow('stop-keyword')")
-    const kwWin = GATEWAY_SRC.slice(kwIdx - 2400, kwIdx)
-    expect(kwWin).toContain('downloadImage == null')
-    expect(kwWin).toContain('attachment == null')
-    expect(kwWin).toContain('extraAttachments == null || extraAttachments.length === 0')
+    // interceptStopKeyword block (P7 PR-2): also excludes coalesced extra
+    // attachments (per-message facts arrive as the `p.` params object).
+    const kwIdx = INTERCEPTORS_SRC.indexOf("deps.executeHaltNow('stop-keyword')")
+    const kwWin = INTERCEPTORS_SRC.slice(kwIdx - 2400, kwIdx)
+    expect(kwWin).toContain('p.downloadImage == null')
+    expect(kwWin).toContain('p.attachment == null')
+    expect(kwWin).toContain('p.extraAttachments == null || p.extraAttachments.length === 0')
   })
 })
 

package/telegram-plugin/tests/stream-render-golden.test.ts

@@ -0,0 +1,424 @@
+/**
+ * Golden-transcript harness for the extracted stream/render dispatcher
+ * (#2996 P4-A, plan Amendments 1/5/9/10).
+ *
+ * ── Oracle standard (Amendment 10) ────────────────────────────────────────
+ * gateway.ts cannot be driven in-place from a test runner (`handleSessionEvent`
+ * was unexported; `bot` is assigned only inside the isGatewayMain boot). The
+ * coordinator-accepted oracle is therefore the EXTRACTED-MODULE golden harness
+ * (the merged send-reply-golden precedent): the real `handleSessionEvent` is
+ * driven with synthetic SessionEvent sequences against a fake bot recorder +
+ * the REAL `OutboundDedupCache`, with gateway-scoped closures faked.
+ *
+ * ── The load-bearing case (Amendment 1, BLOCKING) ─────────────────────────
+ * CROSS-SURFACE stream-then-reply dedup spanning BOTH extracted modules on ONE
+ * shared `OutboundDedupCache`: the REAL P4 `handleSessionEvent` turn-flush path
+ * records the delivered answer into the cache, then the REAL P2 `sendReply`
+ * (a DIFFERENT module) checking that SAME instance suppresses a late same-text
+ * reply — zero wire calls. A negative control proves a second cache reinstates
+ * the duplicate. This is the exact duplicate-reply class the shared-singleton
+ * injection (never a re-`new`) exists to kill.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { handleSessionEvent, type StreamRenderDeps } from '../gateway/stream-render.js'
+import {
+  sendReply,
+  type SendReplyGatewayDeps,
+  type SendReplyRequest,
+} from '../gateway/outbound-send-path.js'
+import { OutboundDedupCache } from '../recent-outbound-dedup.js'
+import { FlushedTurnSupersedeRegistry } from '../flushed-turn-supersede.js'
+import { BackstopDeliveryLedger } from '../gateway/backstop-delivery.js'
+import { redact } from '../secret-detect/redact.js'
+import type { CurrentTurn } from '../gateway/gateway.js'
+
+const CHAT = '1001'
+
+// ── fake bot recorder (shared shape with send-reply-golden) ────────────────
+interface RecordedCall {
+  method: string
+  chat_id: string
+  text: string | null
+  opts: Record<string, unknown>
+  reply_markup: unknown
+  message_id?: number
+}
+function makeFakeBot() {
+  const calls: RecordedCall[] = []
+  let nextId = 2000
+  const rec = (method: string, chat_id: string, text: string | null, opts: Record<string, unknown> = {}) => {
+    const id = ++nextId
+    calls.push({ method, chat_id, text, opts, reply_markup: opts.reply_markup ?? null, message_id: id })
+    return { message_id: id }
+  }
+  const api = {
+    sendRichMessage: async (c: string, b: { markdown: string }, o: Record<string, unknown> = {}) => rec('sendRichMessage', c, b.markdown, o),
+    sendMessage: async (c: string, t: string, o: Record<string, unknown> = {}) => rec('sendMessage', c, t, o),
+    editMessageText: async (c: string, m: number, b: unknown, o: Record<string, unknown> = {}) => { rec('editMessageText', c, typeof b === 'string' ? b : (b as { markdown: string }).markdown, o); return {} },
+    deleteMessage: async (c: string, m: number) => { rec('deleteMessage', c, null); return true },
+  }
+  return { api, calls }
+}
+
+// ── a CurrentTurn sufficient for the turn-flush record path ────────────────
+function makeTurn(over: Partial<CurrentTurn> = {}): CurrentTurn {
+  return {
+    turnId: 'turn-flush-1',
+    sessionChatId: CHAT,
+    sessionThreadId: undefined,
+    registryKey: null,
+    sourceMessageId: null,
+    startedAt: Date.now() - 5000,
+    replyCalled: false,
+    lastReplyText: '',
+    answerStream: null,
+    capturedText: ['The composed terminal answer that the model never sent via reply.'],
+    capturedBlockMeta: [false],
+    finalAnswerDelivered: false,
+    finalAnswerSubstantive: false,
+    answerDelivered: false,
+    deliveryOutcome: undefined,
+    orphanedReplyTimeoutId: null,
+    orphanedReplyStreamMsgId: null,
+    activityPendingRender: null,
+    liveness: { recentlyStreaming: () => false, onStreamEvent: () => {}, note: () => {} },
+    ...over,
+  } as unknown as CurrentTurn
+}
+
+// ── the full injected deps, minimal but runtime-faithful fakes ─────────────
+interface StreamHarness {
+  deps: StreamRenderDeps
+  calls: RecordedCall[]
+  dedup: OutboundDedupCache
+  ledger: BackstopDeliveryLedger
+  delivered: string[]
+}
+function makeStreamDeps(opts?: {
+  dedup?: OutboundDedupCache
+  turn?: CurrentTurn | null
+  deliverResult?: { sentIds: number[]; chunkCount: number; delivered: boolean; exhausted: boolean }
+}): StreamHarness {
+  const { api, calls } = makeFakeBot()
+  const dedup = opts?.dedup ?? new OutboundDedupCache()
+  const ledger = new BackstopDeliveryLedger()
+  const delivered: string[] = []
+  let curTurn = opts?.turn ?? null
+  const key = (c: string, t?: number | null) => `${c}:${t ?? 'main'}`
+  const noop = () => {}
+  const fakeEA = {
+    claimOrDowngradePing: (_i: unknown, _s: unknown, _a: unknown, disabled: () => void) => disabled(),
+    markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+    finalizeCard: (fn: () => void) => fn(),
+  }
+  const deps = {
+    // config
+    ANSWER_LANE: { visibleEnabled: false } as unknown,
+    CAPTURED_PROSE_DELIVERY_ENABLED: false,
+    CONTEXT_EXHAUSTION_COOLDOWN_MS: 600000,
+    DELIVERY_CONFIRM_ENABLED: false,
+    FEED_REOPEN_AFTER_ACK_ENABLED: false,
+    HANDBACK_PRETURN_ENABLED: false,
+    HISTORY_ENABLED: false,
+    LIVENESS_TERMINAL_HONESTY: true,
+    OBLIGATION_LEDGER_ENABLED: false,
+    ORPHANED_REPLY_STREAM_WINDOW_MS: 120000,
+    SILENCE_LIVENESS_PRODUCTION: false,
+    STATE_DIR: tmpdir(),
+    TURN_FLUSH_SAFETY_ENABLED: true,
+    TURN_PREVIEW_MAX: 200,
+    // state singletons
+    activeDraftStreams: new Map(),
+    activeStatusReactions: new Map(),
+    activeTurnStartedAt: new Map(),
+    backstopDeliveryLedger: ledger,
+    bot: { api },
+    flushedTurnSupersede: new FlushedTurnSupersedeRegistry(),
+    idleTracker: { noteEvent: noop },
+    lastPtyPreviewByChat: new Map(),
+    obligationLedger: { close: noop, noteTurnEnded: noop },
+    outboundDedup: dedup,
+    pendingCrossTurnGate: new Map(),
+    preambleSuppressor: { dropNow: noop, flushNow: noop, onText: noop, onTool: noop, reset: noop },
+    progressDriver: null,
+    reactionTransitionCounts: new Map(),
+    suppressPtyPreview: new Set(),
+    toolFlightTracker: { inFlightCount: () => 0 },
+    deliveryQueue: {},
+    handbackPreturnSignal: { tryAdopt: () => null },
+    sessionModelSource: { noteTranscriptModel: noop },
+    typingWrapper: { drainAll: noop, onToolResult: noop, onToolUse: noop },
+    robustApiCall: (fn: () => Promise<unknown>) => fn(),
+    swallowingApiCall: async (fn: () => Promise<unknown>) => { try { return await fn() } catch { return undefined } },
+    // volatile accessors
+    getCurrentTurn: () => curTurn,
+    getLastContextExhaustionWarningAt: () => 0,
+    setLastContextExhaustionWarningAt: noop,
+    getPendingPtyPartial: () => null,
+    setPendingPtyPartial: noop,
+    setCurrentTurn: (t: CurrentTurn) => { curTurn = t },
+    // local-closure fakes
+    cardDrainGate: (_t: unknown, _ea: unknown, run: () => void) => run(),
+    clearActivitySummary: noop,
+    clearAnswerReadyFlushTimeout: noop,
+    closeActivityLane: noop,
+    closeProgressLane: noop,
+    completeProgressCardTurn: null,
+    composeTurnActivity: () => null,
+    confirmMemoryLegibility: noop,
+    deliverAnswer: async (a: { text: string }) => {
+      delivered.push(a.text)
+      return opts?.deliverResult ?? { sentIds: [4242], chunkCount: 1, delivered: true, exhausted: false }
+    },
+    deliverCapturedProse: async () => {},
+    drainActivitySummary: async () => {},
+    emissionAuthorityFor: () => fakeEA,
+    emitTurnRecord: noop,
+    endCurrentTurnAtomic: () => null,
+    extractUserPromptPreview: () => null,
+    finalizeStatusReaction: noop,
+    flushPendingNarrativeAtTurnEnd: noop,
+    getPinnedProgressCardMessageId: null,
+    handlePtyPartial: noop,
+    isDmChatId: () => true,
+    isLegitimatelyWorking: () => false,
+    makeNarrativeGate: () => ({ show: noop, stage: noop, resolveOnTool: noop, flushAtTurnEnd: noop }),
+    promoteQueuedStatus: noop,
+    purgeReactionTracking: noop,
+    redactOutboundText: (t: string) => redact(t),
+    rememberRecentTurn: noop,
+    resetAnswerReadyFlushTimeout: noop,
+    resetOrphanedReplyTimeout: noop,
+    resolvePendingNarrativeOnTool: noop,
+    scheduleEarlyLivenessOpen: noop,
+    stagePendingNarrative: noop,
+    startTurnTypingLoop: noop,
+    statusKey: key,
+    streamKey: key,
+    surfaceMemoryLegibility: noop,
+    turnLiveForItsTopic: () => true,
+    turnsDb: null,
+    unpinProgressCardForChat: null,
+  } as unknown as StreamRenderDeps
+  return { deps, calls, dedup, ledger, delivered }
+}
+
+// ── the P2 sendReply harness (same content, sharing the ONE cache) ─────────
+function makeSendReplyDeps(dedup: OutboundDedupCache) {
+  const { api, calls } = makeFakeBot()
+  const key = (c: string, t?: number | null) => `${c}:${t ?? 'main'}`
+  const deps = {
+    outboundDedup: dedup,
+    flushedTurnSupersede: new FlushedTurnSupersedeRegistry(),
+    firstTextReplyLogged: new Set<string>(),
+    suppressPtyPreview: new Set<string>(),
+    activeDraftStreams: new Map(),
+    lastPtyPreviewByChat: new Map(),
+    voiceOnDemandCache: { put: () => {} },
+    voicePreSynthQueue: { enqueue: () => {} },
+    pendingProgress: { clearPending: () => {}, noteOutbound: () => {} },
+    signalTracker: { noteOutbound: () => {}, noteSignal: () => {} },
+    silencePoke: { noteOutbound: () => {} },
+    getCurrentTurn: () => null,
+    getLastActiveTurnChatId: () => undefined,
+    HISTORY_ENABLED: false,
+    TURN_ORIGIN_ROUTING_ENABLED: true,
+    AUTOCLASSIFY_MIDTURN_SHADOW: false,
+    MAX_ATTACHMENT_BYTES: 50 * 1024 * 1024,
+    MAX_CHUNK_LIMIT: 4096,
+    PHOTO_EXTS: new Set(['.jpg', '.png']),
+    lockedBot: { api },
+    robustApiCall: (fn: () => Promise<unknown>) => fn(),
+    swallowingApiCall: async (fn: () => Promise<unknown>) => { try { return await fn() } catch { return undefined } },
+    loadAccess: () => ({ allowFrom: [CHAT], groups: {}, disableLinkPreview: true }),
+    redactOutboundText: (t: string) => redact(t),
+    assertAllowedChat: () => {},
+    assertSendable: () => {},
+    statusKey: key,
+    streamKey: key,
+    resolveReplyOwnerTurn: () => null,
+    findTurnByOriginId: () => null,
+    findTurnByQuotedMessageId: () => null,
+    resolveAnswerThreadWithLog: (_c: string, explicit: number | undefined) => explicit,
+    resolveThreadId: (_c: string, explicit?: string | number | null) => (explicit != null ? Number(explicit) : undefined),
+    getLatestInboundMessageId: () => null,
+    recordOutbound: () => {},
+    emissionAuthorityFor: () => ({
+      claimOrDowngradePing: (_i: unknown, _s: unknown, _a: unknown, disabled: () => void) => disabled(),
+      markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+      finalizeCard: (fn: () => void) => fn(),
+    }),
+    clearActivitySummary: () => {},
+    startTypingLoop: () => {},
+    stopTypingLoop: () => {},
+    logOutbound: () => {},
+    closeObligationOnSubstantiveReply: () => {},
+    finalizeStatusReaction: () => {},
+    releaseTurnBufferGate: () => {},
+    reapQueuedStatus: () => {},
+    noteAgentOutputAt: () => {},
+    rememberAgentButtonMeta: () => {},
+    resolveVoiceOutPlan: () => null,
+    synthesizeVoiceOut: async () => null,
+    publishToTelegraph: async () => null,
+    clearSilentEndState: () => {},
+    emitRuntimeMetric: () => {},
+    shadowEmit: () => {},
+    progressDriver: null,
+  } as unknown as SendReplyGatewayDeps
+  return { deps, calls }
+}
+function req(text: string): SendReplyRequest {
+  return { args: { chat_id: CHAT, text }, turn: null }
+}
+
+// give the turn-flush IIFE (500ms internal setTimeout) time to reach the record
+const settle = () => new Promise((r) => setTimeout(r, 650))
+
+// ── the cases ──────────────────────────────────────────────────────────────
+
+describe('stream-render — turn-flush records into the shared OutboundDedupCache', () => {
+  it('drives the REAL handleSessionEvent turn-flush path to outboundDedup.record', async () => {
+    const turn = makeTurn()
+    const answer = turn.capturedText.join('')
+    const h = makeStreamDeps({ turn })
+    handleSessionEvent(h.deps, { kind: 'turn_end', durationMs: 1200 })
+    await settle()
+    expect(h.delivered).toContain(answer)
+    // the module's OWN record statement (stream-render.ts:1784) ran
+    expect(h.dedup.check(CHAT, undefined, answer, Date.now(), null)).not.toBeNull()
+  })
+})
+
+// ── #3237 HARD GATE: block provenance survives stream-render accumulation ───
+// The whole fix hinges on `ev.lastInMessage` surviving the `case 'text'`
+// accumulation into `turn.capturedBlockMeta` and reaching selectFlushDeliveryText
+// via decideTurnFlush. These drive the REAL handleSessionEvent text path (not a
+// preset capturedText) so the accumulation code actually runs, then assert BOTH
+// the accumulated provenance AND the flush's delivered text. Each case is
+// engineered so the OPPOSITE outcome would result if provenance were lost and
+// the strip fell back to the opener heuristic — proving structure is consulted.
+describe('#3237 — block provenance survives accumulation and reaches the flush strip', () => {
+  function driveTextTurn(blocks: Array<{ text: string; lastInMessage: boolean }>) {
+    const turn = makeTurn({ capturedText: [], capturedBlockMeta: [], answerStream: null })
+    const h = makeStreamDeps({ turn })
+    blocks.forEach((b, i) =>
+      handleSessionEvent(h.deps, {
+        kind: 'text',
+        text: b.text,
+        blockIndex: i,
+        lastInMessage: b.lastInMessage,
+      }),
+    )
+    return { turn, h }
+  }
+
+  it('narration FOLLOWED by a tool_use (lastInMessage=false) → provenance=[true,false], flush strips the preamble', async () => {
+    // "Here are the figures." matches NO opener regex — if provenance were lost
+    // the opener-only strip would KEEP it and deliver the whole blob. Structure
+    // ([true,false]) strips it. Asserting answer-only proves structure was used.
+    const narration = 'Here are the figures you asked about.'
+    const answer = 'All three services are green.'
+    const { turn, h } = driveTextTurn([
+      { text: narration, lastInMessage: false }, // a tool_use followed it in its message
+      { text: answer, lastInMessage: true }, // terminal
+    ])
+    // Provenance survived the accumulation into the parallel array.
+    expect(turn.capturedBlockMeta).toEqual([true, false])
+    handleSessionEvent(h.deps, { kind: 'turn_end', durationMs: 1200 })
+    await settle()
+    expect(h.delivered.join('\n')).toContain(answer)
+    expect(h.delivered.join('\n')).not.toContain('Here are the figures')
+  })
+
+  it('#3237 real answer: two paragraphs, NEITHER followed by a tool_use (lastInMessage=true) → provenance=[false,false], flush keeps BOTH (no truncation)', async () => {
+    // p1 OPENS with "Let me explain…" — the opener strip WOULD drop it if
+    // provenance were lost. Structure ([false,false]) keeps the full answer.
+    const p1 = 'Let me explain the plan in two parts.'
+    const p2 = 'Part two: we ship it behind the existing flag.'
+    const { turn, h } = driveTextTurn([
+      { text: p1, lastInMessage: true },
+      { text: p2, lastInMessage: true },
+    ])
+    expect(turn.capturedBlockMeta).toEqual([false, false])
+    handleSessionEvent(h.deps, { kind: 'turn_end', durationMs: 1200 })
+    await settle()
+    const out = h.delivered.join('\n')
+    expect(out).toContain('Let me explain the plan')
+    expect(out).toContain('Part two')
+  })
+})
+
+describe('cross-surface dedup — ONE OutboundDedupCache across P4 stream + P2 reply (Amendment 1)', () => {
+  it('a P4 turn-flush record suppresses the P2 same-text reply (zero wire calls)', async () => {
+    const dedup = new OutboundDedupCache()
+    const turn = makeTurn()
+    const answer = turn.capturedText.join('')
+    // P4 surface (real handleSessionEvent) records into the shared cache.
+    const h = makeStreamDeps({ dedup, turn })
+    handleSessionEvent(h.deps, { kind: 'turn_end', durationMs: 1200 })
+    await settle()
+    expect(h.dedup.check(CHAT, undefined, answer, Date.now(), null)).not.toBeNull()
+
+    // P2 surface (real sendReply) holding the SAME instance dedups the late reply.
+    const s = makeSendReplyDeps(dedup)
+    const res = await sendReply(s.deps, req(answer))
+    expect(res.content[0]!.text).toBe('sent (deduped — same content sent via earlier path)')
+    expect(s.calls).toHaveLength(0)
+  })
+
+  it('NEGATIVE CONTROL: a SECOND cache reinstates the duplicate reply', async () => {
+    const streamCache = new OutboundDedupCache()
+    const turn = makeTurn()
+    const answer = turn.capturedText.join('')
+    const h = makeStreamDeps({ dedup: streamCache, turn })
+    handleSessionEvent(h.deps, { kind: 'turn_end', durationMs: 1200 })
+    await settle()
+    expect(streamCache.check(CHAT, undefined, answer, Date.now(), null)).not.toBeNull()
+
+    // A DIFFERENT instance (the forbidden re-`new`) never saw the P4 record.
+    const s = makeSendReplyDeps(new OutboundDedupCache())
+    await sendReply(s.deps, req(answer))
+    expect(s.calls.filter((c) => c.method === 'sendRichMessage')).toHaveLength(1)
+  })
+})
+
+describe('structural — the singleton lives once in gateway, never in the modules (Amendment 1)', () => {
+  const gatewaySrc = readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8')
+  const streamSrc = readFileSync(new URL('../gateway/stream-render.ts', import.meta.url), 'utf8')
+  const sendSrc = readFileSync(new URL('../gateway/outbound-send-path.ts', import.meta.url), 'utf8')
+
+  it('gateway constructs EXACTLY ONE OutboundDedupCache; neither extracted module constructs any', () => {
+    expect(gatewaySrc.match(/new OutboundDedupCache\(/g) ?? []).toHaveLength(1)
+    expect(streamSrc.match(/new OutboundDedupCache\(/g) ?? []).toHaveLength(0)
+    expect(sendSrc.match(/new OutboundDedupCache\(/g) ?? []).toHaveLength(0)
+  })
+
+  it('both gateway deps builders inject the SAME outboundDedup binding (never a re-new)', () => {
+    for (const builder of ['function gatewayStreamRenderDeps(', 'function gatewaySendReplyDeps(']) {
+      const after = gatewaySrc.split(builder)[1] ?? ''
+      const body = after.split('\nfunction ')[0]?.split('\nexport ')[0] ?? after
+      expect(body).toMatch(/\n\s{4}outboundDedup,/)
+    }
+  })
+
+  it('handleSessionEvent is a thin wrapper delegating to the extracted module', () => {
+    const after = gatewaySrc.split('function handleSessionEvent(ev: SessionEvent): void {')[1] ?? ''
+    const body = after.split('\n}')[0] ?? after
+    expect(body).toContain('handleSessionEventCore(gatewayStreamRenderDeps(), ev)')
+  })
+
+  it('the module never reads the currentTurn global — only getCurrentTurn() (Amendment 9)', () => {
+    const fnBody = streamSrc.split('export function handleSessionEvent(')[1] ?? ''
+    // No bare `currentTurn` value reads survive outside comments; the live-read
+    // contract routes through the injected accessor.
+    const codeOnly = fnBody
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('//') && !l.trim().startsWith('*'))
+      .join('\n')
+    expect(codeOnly).not.toMatch(/[^.\w]currentTurn\b(?!\s*[:,)])/)
+    expect(codeOnly).toMatch(/getCurrentTurn\(\)/)
+  })
+})