switchroom 0.18.32 → 0.19.0

package/telegram-plugin/tests/narrative-lane-golden.test.ts

@@ -0,0 +1,458 @@
+/**
+ * Golden harness for the extracted narrative/activity lane
+ * (#2996 P4-B, plan Amendments 1/5/9/10).
+ *
+ * ── Oracle standard (Amendment 10) ────────────────────────────────────────
+ * gateway.ts cannot be driven in-place from a test runner, so the oracle is
+ * the EXTRACTED-MODULE golden harness (the outbound-send-path /
+ * stream-render-golden precedent): the REAL `createNarrativeLane` factory is
+ * driven directly against a fake bot recorder, real leaf modules
+ * (renderActivityFeedWithNested, NarrativeFlushController, narrative-dedup,
+ * feed-open-gate), and fake gateway closures.
+ *
+ * ── What is pinned ────────────────────────────────────────────────────────
+ *   - narrative SHOW → feed card OPEN (sendRichMessage) with the clipped line
+ *   - second SHOW → in-place EDIT of the SAME card (no second bubble)
+ *   - composeTurnActivity: live vs final render (step-count on final only)
+ *   - the narrative-dedup gate: a trailing draft-of-reply is SUPPRESSED at
+ *     turn end; genuine trailing narration is SHOWN
+ *   - clearActivitySummary finalize: terminal EDIT, no delete (default path)
+ *   - THREE-MODULE cross-surface dedup (Amendment 1): the REAL P4-A
+ *     handleSessionEvent turn-flush driven with the REAL P4-B lane wired into
+ *     its deps records into ONE OutboundDedupCache, and the REAL P2 sendReply
+ *     holding the SAME instance suppresses the late same-text reply
+ *   - structural: the lane constructs NO OutboundDedupCache / ledger, never
+ *     reads the `currentTurn` global, and gateway's wrappers delegate lazily
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { createNarrativeLane } from '../gateway/narrative-lane.js'
+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, NarrativeLaneDeps } from '../gateway/gateway.js'
+
+const CHAT = '1001'
+
+// ── fake bot recorder ─────────────────────────────────────────────────────
+interface RecordedCall {
+  method: string
+  chat_id: string
+  text: string | null
+  message_id?: number
+}
+function makeFakeBot() {
+  const calls: RecordedCall[] = []
+  let nextId = 3000
+  const api = {
+    sendRichMessage: async (c: string, b: { markdown: string }) => {
+      const id = ++nextId
+      calls.push({ method: 'sendRichMessage', chat_id: c, text: b.markdown, message_id: id })
+      return { message_id: id }
+    },
+    sendMessage: async (c: string, t: string) => {
+      const id = ++nextId
+      calls.push({ method: 'sendMessage', chat_id: c, text: t, message_id: id })
+      return { message_id: id }
+    },
+    editMessageText: async (c: string, m: number, b: unknown) => {
+      calls.push({
+        method: 'editMessageText', chat_id: c,
+        text: typeof b === 'string' ? b : (b as { markdown: string }).markdown, message_id: m,
+      })
+      return {}
+    },
+    deleteMessage: async (c: string, m: number) => {
+      calls.push({ method: 'deleteMessage', chat_id: c, text: null, message_id: m })
+      return true
+    },
+  }
+  return { api, calls }
+}
+
+// ── a CurrentTurn sufficient for the lane paths ───────────────────────────
+function makeLaneTurn(lane: ReturnType<typeof createNarrativeLane>, over: Partial<CurrentTurn> = {}): CurrentTurn {
+  const turn = {
+    turnId: 'turn-lane-1',
+    sessionChatId: CHAT,
+    sessionThreadId: undefined,
+    sourceMessageId: null,
+    registryKey: null,
+    startedAt: Date.now() - 3000,
+    currentModel: null,
+    totalTokens: 0,
+    labeledToolCount: 0,
+    mirrorLines: [] as string[],
+    foregroundSubAgents: new Map<string, string[]>(),
+    activityPendingRender: null as string | null,
+    activityLastSentRender: null as string | null,
+    activityMessageId: null as number | null,
+    activityInFlight: null as Promise<void> | null,
+    activityEverOpened: false,
+    activityDrainFailures: 0,
+    finalAnswerEverDelivered: false,
+    finalAnswerDelivered: false,
+    replyCalled: false,
+    capturedText: [] as string[],
+    lastReplyText: '',
+    answerStream: null,
+    liveness: { recentlyStreaming: () => false, onStreamEvent: () => {}, note: () => {} },
+    ...over,
+  } as unknown as CurrentTurn
+  ;(turn as { narrativeGate?: unknown }).narrativeGate = lane.makeNarrativeGate(turn)
+  return turn
+}
+
+// ── lane deps (minimal runtime-faithful fakes; real leaf modules imported by
+//    the lane itself) ──────────────────────────────────────────────────────
+function makeLane(opts?: { getCurrentTurn?: () => CurrentTurn | null }) {
+  const { api, calls } = makeFakeBot()
+  const noop = () => {}
+  const fakeEA = {
+    mayDrain: () => true,
+    openOrEditCard: (_p: string, fn: () => void) => fn(),
+    finalizeCard: (fn: () => void) => fn(),
+    markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+  }
+  const deps = {
+    ACTIVITY_CARD_STORE_PATH: `${tmpdir()}/lane-golden-activity-cards.json`,
+    CLEAR_STATUS_ON_COMPLETION: false,
+    FEED_HEARTBEAT_ENABLED: false,
+    FEED_HEARTBEAT_MIN_STALE_MS: 6000,
+    FEED_LIVENESS_OPEN_ENABLED: false,
+    FEED_LIVENESS_OPEN_MS: 5000,
+    PIN_STATUS_WHILE_WORKING: false,
+    POST_ANSWER_LIVENESS_STALE_MS: 90000,
+    STATIC: false,
+    activeDraftStreams: new Map(),
+    activityCardPersistEnabled: false,
+    activityCardStoreFs: { readFileSync: () => '', writeFileSync: noop, mkdirSync: noop, renameSync: noop, unlinkSync: noop },
+    bot: { api },
+    cardDrainGate: (_t: unknown, _ea: unknown, run: () => void) => run(),
+    currentTurnMap: { get: () => null, byKey: new Map() },
+    earlyLivenessOpenTimers: new Map(),
+    emissionAuthorityFor: () => fakeEA,
+    feedOpenGateDeps: () => ({ hasOutboundDeliveredSince: () => false, historyEnabled: false, finalAnswerMinChars: 200 }),
+    getCurrentTurn: opts?.getCurrentTurn ?? (() => null),
+    reconcileStatusPin: noop,
+    robustApiCall: (fn: () => Promise<unknown>) => fn(),
+    statusKey: (c: string, t?: number | null) => `${c}:${t ?? 'main'}`,
+  } as unknown as NarrativeLaneDeps
+  const lane = createNarrativeLane(deps)
+  return { lane, calls }
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 20))
+
+// ── the cases ─────────────────────────────────────────────────────────────
+
+describe('narrative-lane golden — SHOW path opens then edits ONE feed card', () => {
+  it('first SHOW opens the card (sendRichMessage) with the clipped narrative line', async () => {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane)
+    lane.showNarrativeStep(turn, 'Checking the gateway config for stale entries')
+    await turn.activityInFlight
+    const sends = calls.filter((c) => c.method === 'sendRichMessage')
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.text).toContain('Checking the gateway config for stale entries')
+    expect(turn.activityMessageId).toBe(sends[0]!.message_id)
+    expect(turn.activityEverOpened).toBe(true)
+  })
+
+  it('second SHOW edits the SAME card in place — never a second bubble', async () => {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane)
+    lane.showNarrativeStep(turn, 'Step one of the work')
+    await turn.activityInFlight
+    lane.showNarrativeStep(turn, 'Step two of the work')
+    await turn.activityInFlight
+    expect(calls.filter((c) => c.method === 'sendRichMessage')).toHaveLength(1)
+    const edits = calls.filter((c) => c.method === 'editMessageText')
+    expect(edits.length).toBeGreaterThanOrEqual(1)
+    const last = edits[edits.length - 1]!
+    expect(last.message_id).toBe(turn.activityMessageId)
+    expect(last.text).toContain('Step two of the work')
+  })
+
+  it('composeTurnActivity: live render omits the step total; final render carries it', () => {
+    const { lane } = makeLane()
+    const turn = makeLaneTurn(lane, { labeledToolCount: 3 })
+    turn.mirrorLines.push('Read the file', 'Ran the tests', 'Pushed the branch')
+    const live = lane.composeTurnActivity(turn)
+    const final = lane.composeTurnActivity(turn, true)
+    expect(live).toBeTruthy()
+    expect(final).toBeTruthy()
+    expect(final!).toMatch(/3 steps/)
+    expect(live!).not.toMatch(/3 steps/)
+  })
+})
+
+describe('narrative-lane golden — the narrative-dedup gate at turn end', () => {
+  it('genuine trailing narration is SHOWN (lands in the feed card)', async () => {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane)
+    lane.stagePendingNarrative(turn, 'Done - all checks green, wrapping up.')
+    lane.flushPendingNarrativeAtTurnEnd(turn, 'Here is your answer: the fix is deployed.')
+    await turn.activityInFlight
+    const sends = calls.filter((c) => c.method === 'sendRichMessage')
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.text).toContain('Done - all checks green')
+  })
+
+  it('a trailing draft-of-reply is SUPPRESSED (zero card writes)', async () => {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane)
+    const answer = 'The fix is deployed and the tests are green.'
+    lane.stagePendingNarrative(turn, answer)
+    lane.flushPendingNarrativeAtTurnEnd(turn, answer)
+    await settle()
+    expect(calls).toHaveLength(0)
+  })
+})
+
+describe('narrative-lane golden — clearActivitySummary finalize', () => {
+  it('finalizes the open card with a terminal EDIT (default: no delete)', async () => {
+    const { lane, calls } = makeLane()
+    const turn = makeLaneTurn(lane, { labeledToolCount: 1 })
+    lane.showNarrativeStep(turn, 'Doing the work now')
+    await turn.activityInFlight
+    const cardId = turn.activityMessageId
+    expect(cardId).not.toBeNull()
+    lane.clearActivitySummary(turn)
+    await settle()
+    const edits = calls.filter((c) => c.method === 'editMessageText' && c.message_id === cardId)
+    expect(edits.length).toBeGreaterThanOrEqual(1)
+    expect(calls.filter((c) => c.method === 'deleteMessage')).toHaveLength(0)
+    // tracking released so a late render can't resurrect the card
+    expect(turn.activityMessageId).toBeNull()
+  })
+})
+
+// ── THREE-MODULE cross-surface dedup (Amendment 1) ────────────────────────
+// The REAL P4-A handleSessionEvent turn-flush, with the REAL P4-B lane wired
+// into its deps, records the delivered answer into ONE OutboundDedupCache;
+// the REAL P2 sendReply holding the SAME instance then suppresses the late
+// same-text reply. One shared cache across all three extracted modules.
+
+function makeStreamDepsWithRealLane(dedup: OutboundDedupCache, turn: CurrentTurn, lane: ReturnType<typeof createNarrativeLane>) {
+  const { api } = makeFakeBot()
+  const noop = () => {}
+  const delivered: string[] = []
+  const fakeEA = {
+    claimOrDowngradePing: (_i: unknown, _s: unknown, _a: unknown, disabled: () => void) => disabled(),
+    markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+    finalizeCard: (fn: () => void) => fn(),
+    mayDrain: () => true,
+    openOrEditCard: (_p: string, fn: () => void) => fn(),
+  }
+  const deps = {
+    ANSWER_LANE: { visibleEnabled: false },
+    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,
+    activeDraftStreams: new Map(),
+    activeStatusReactions: new Map(),
+    activeTurnStartedAt: new Map(),
+    backstopDeliveryLedger: new BackstopDeliveryLedger(),
+    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 } },
+    getCurrentTurn: () => turn,
+    getLastContextExhaustionWarningAt: () => 0,
+    setLastContextExhaustionWarningAt: noop,
+    getPendingPtyPartial: () => null,
+    setPendingPtyPartial: noop,
+    setCurrentTurn: noop,
+    cardDrainGate: (_t: unknown, _ea: unknown, run: () => void) => run(),
+    // ── the REAL P4-B lane wired in (not fakes) ──
+    clearActivitySummary: lane.clearActivitySummary,
+    closeActivityLane: lane.closeActivityLane,
+    closeProgressLane: lane.closeProgressLane,
+    composeTurnActivity: lane.composeTurnActivity,
+    drainActivitySummary: lane.drainActivitySummary,
+    flushPendingNarrativeAtTurnEnd: lane.flushPendingNarrativeAtTurnEnd,
+    makeNarrativeGate: lane.makeNarrativeGate,
+    resolvePendingNarrativeOnTool: lane.resolvePendingNarrativeOnTool,
+    stagePendingNarrative: lane.stagePendingNarrative,
+    scheduleEarlyLivenessOpen: lane.scheduleEarlyLivenessOpen,
+    // ────────────────────────────────────────────
+    clearAnswerReadyFlushTimeout: noop,
+    completeProgressCardTurn: null,
+    confirmMemoryLegibility: noop,
+    deliverAnswer: async (a: { text: string }) => {
+      delivered.push(a.text)
+      return { sentIds: [4242], chunkCount: 1, delivered: true, exhausted: false }
+    },
+    deliverCapturedProse: async () => {},
+    emissionAuthorityFor: () => fakeEA,
+    emitTurnRecord: noop,
+    endCurrentTurnAtomic: () => null,
+    extractUserPromptPreview: () => null,
+    finalizeStatusReaction: noop,
+    getPinnedProgressCardMessageId: null,
+    handlePtyPartial: noop,
+    isDmChatId: () => true,
+    isLegitimatelyWorking: () => false,
+    promoteQueuedStatus: noop,
+    purgeReactionTracking: noop,
+    redactOutboundText: (t: string) => redact(t),
+    rememberRecentTurn: noop,
+    resetAnswerReadyFlushTimeout: noop,
+    resetOrphanedReplyTimeout: noop,
+    startTurnTypingLoop: noop,
+    statusKey: (c: string, t?: number | null) => `${c}:${t ?? 'main'}`,
+    streamKey: (c: string, t?: number | null) => `${c}:${t ?? 'main'}`,
+    surfaceMemoryLegibility: noop,
+    turnLiveForItsTopic: () => true,
+    turnsDb: null,
+    unpinProgressCardForChat: null,
+  } as unknown as StreamRenderDeps
+  return { deps, delivered }
+}
+
+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 }
+}
+
+describe('THREE-MODULE cross-surface dedup — one OutboundDedupCache across P4-B lane + P4-A stream + P2 reply', () => {
+  it('turn-flush through the REAL stream module (REAL lane wired in) records; the REAL sendReply dedups', async () => {
+    const dedup = new OutboundDedupCache()
+    const { lane } = makeLane()
+    const answer = 'The lane-wired terminal answer the model never sent via reply.'
+    const turn = makeLaneTurn(lane, { capturedText: [answer], turnId: 'turn-3mod' })
+    const { deps } = makeStreamDepsWithRealLane(dedup, turn, lane)
+    handleSessionEvent(deps, { kind: 'turn_end', durationMs: 1200 })
+    await new Promise((r) => setTimeout(r, 650))
+    expect(dedup.check(CHAT, undefined, answer, Date.now(), null)).not.toBeNull()
+
+    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)
+  })
+})
+
+describe('structural — singleton + wrapper discipline (#2996 P4-B)', () => {
+  const gatewaySrc = readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8')
+  const laneSrc = readFileSync(new URL('../gateway/narrative-lane.ts', import.meta.url), 'utf8')
+
+  it('the lane constructs NO OutboundDedupCache and NO BackstopDeliveryLedger', () => {
+    expect(laneSrc.match(/new OutboundDedupCache\(/g) ?? []).toHaveLength(0)
+    expect(laneSrc.match(/new BackstopDeliveryLedger\(/g) ?? []).toHaveLength(0)
+    // gateway still constructs exactly ONE dedup cache (the injected singleton).
+    expect(gatewaySrc.match(/new OutboundDedupCache\(/g) ?? []).toHaveLength(1)
+  })
+
+  it('the lane never reads the currentTurn global — only the injected accessor', () => {
+    const codeOnly = laneSrc
+      .split('\n')
+      .filter((l) => !l.trim().startsWith('//') && !l.trim().startsWith('*'))
+      .join('\n')
+    expect(codeOnly).not.toMatch(/[^.\w]currentTurn\b(?!\s*[:,)])/)
+    expect(codeOnly).toMatch(/getCurrentTurn\(\)/)
+  })
+
+  it('gateway builds the lane LAZILY with the injected deps and delegates via same-name wrappers', () => {
+    expect(gatewaySrc).toContain('narrativeLaneInstance ??= createNarrativeLane(gatewayNarrativeLaneDeps())')
+    for (const fn of ['composeTurnActivity', 'drainActivitySummary', 'clearActivitySummary', 'feedHeartbeatTick', 'flushPendingNarrativeAtTurnEnd']) {
+      expect(gatewaySrc).toMatch(new RegExp(`narrativeLane\\(\\)\\.${fn}\\(`))
+    }
+    // the deps builder injects the live-turn accessor (Amendment 9)
+    const after = gatewaySrc.split('function gatewayNarrativeLaneDeps(')[1] ?? ''
+    const body = after.split('\nexport ')[0] ?? after
+    expect(body).toContain('getCurrentTurn: () => currentTurn')
+  })
+})

package/telegram-plugin/tests/no-reply-bounded-drain.test.ts

@@ -125,9 +125,15 @@ describe('gateway wiring (source-level guards) — the gateway IIFE is too entan
     resolve(__dirname, '..', 'gateway', 'gateway.ts'),
     'utf-8',
   )
+  // #2996 P8 PR-B: the funnel bodies moved verbatim to turn-end.ts; the
+  // body-structure guards read there (gateway keeps delegating wrappers).
+  const turnEndSrc = readFileSync(
+    resolve(__dirname, '..', 'gateway', 'turn-end.ts'),
+    'utf-8',
+  )
 
   it('endCurrentTurnAtomic arms the no-reply drain timer after the serialize-gated purge', () => {
-    const fn = gatewaySrc.split('function endCurrentTurnAtomic')[1]?.split('\nfunction ')[0] ?? ''
+    const fn = turnEndSrc.split('function endCurrentTurnAtomic')[1]?.split('\nfunction ')[0] ?? ''
     expect(fn).toMatch(/purgeReactionTracking\(/)
     expect(fn).toMatch(/armNoReplyDrainTimer\(turn\)/)
     // The arm must come AFTER the purge (the purge attempts the gated
@@ -136,7 +142,7 @@ describe('gateway wiring (source-level guards) — the gateway IIFE is too entan
   })
 
   it('armNoReplyDrainTimer uses the shared predicate + a bounded setTimeout that force-drains', () => {
-    const fn = gatewaySrc.split('function armNoReplyDrainTimer')[1]?.split('\nfunction ')[0] ?? ''
+    const fn = turnEndSrc.split('function armNoReplyDrainTimer')[1]?.split('\nfunction ')[0] ?? ''
     expect(fn).toMatch(/shouldArmNoReplyDrain\(/)
     expect(fn).toMatch(/setTimeout\(/)
     expect(fn).toMatch(/SERIALIZE_NOREPLY_DRAIN_MS/)
@@ -151,6 +157,11 @@ describe('gateway wiring (source-level guards) — the gateway IIFE is too entan
     // The unwedge fallback calls redeliverBufferedInbound directly — it
     // must NOT be gated by the serialize predicate, or a stuck no-reply
     // turn whose bounded timer somehow failed would never recover.
-    expect(gatewaySrc).toMatch(/silence-poke framework-fallback ended wedged turn/)
+    // #2996 P8 PR-C3: the fallback body moved verbatim to liveness-wiring.ts.
+    const livenessSrc = readFileSync(
+      resolve(__dirname, '..', 'gateway', 'liveness-wiring.ts'),
+      'utf-8',
+    )
+    expect(livenessSrc).toMatch(/silence-poke framework-fallback ended wedged turn/)
   })
 })

package/telegram-plugin/tests/pending-card-durability-wiring.test.ts

@@ -30,6 +30,10 @@ const CARD_STORES = read('gateway/approval-card-stores.ts')
 // moved verbatim behind callback-query-handlers.ts; handler-body pins read
 // that module while staging/boot/sweep wiring stays pinned on gateway.ts.
 const CB_HANDLERS = read('gateway/callback-query-handlers.ts')
+// #2996 P5-tail: the agent-facing card-STAGING execute* tool handlers moved
+// verbatim behind card-tool-handlers.ts; their staging pins read that module
+// while the stores/boot/sweep wiring stays pinned on gateway.ts.
+const CARD_TOOL = read('gateway/card-tool-handlers.ts')
 
 function slice(src: string, header: string, span = 3000): string {
   const start = src.indexOf(header)
@@ -62,22 +66,23 @@ describe('pending-card-store wiring', () => {
 
 describe('staging persists card metadata (Defect A)', () => {
   it('vault_request_access stages into the durable store', () => {
-    const fn = slice(GATEWAY, 'async function executeVaultRequestAccess', 6000)
+    const fn = slice(CARD_TOOL, 'async function executeVaultRequestAccess', 6000)
     expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'vault_request_access'/)
   })
 
   it('request_secret stages into the durable store', () => {
-    const fn = slice(GATEWAY, 'async function executeRequestSecret', 3000)
+    const fn = slice(CARD_TOOL, 'async function executeRequestSecret', 3000)
     expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'request_secret'/)
   })
 
   it('mental_model_propose stages into the durable store', () => {
-    const fn = slice(GATEWAY, 'async function executeMentalModelPropose', 6000)
+    // 7000: the factory indent puts the add block ~6.1k chars past the def.
+    const fn = slice(CARD_TOOL, 'async function executeMentalModelPropose', 7000)
     expect(fn).toMatch(/pendingCardStore\.add\(\{[\s\S]*family: 'mental_model_propose'/)
   })
 
   it('vault_request_save stages metadata but NEVER the secret value (hygiene)', () => {
-    const fn = slice(GATEWAY, 'async function executeVaultRequestSave', 6000)
+    const fn = slice(CARD_TOOL, 'async function executeVaultRequestSave', 6000)
     const addBlock = slice(fn, "pendingCardStore.add({", 700)
     expect(addBlock).toMatch(/family: 'vault_request_save'/)
     // The staged secret `value` must NOT be copied into the persisted record.
@@ -127,9 +132,13 @@ describe('resolution clears the durable store (Defect A)', () => {
   })
 
   it('secret request provide/decline remove from the store', () => {
-    // capture (provide → value arrives) removes via armed.stageId
+    // capture (provide → value arrives) removes via armed.stageId — the value
+    // arrival path (captureProvidedSecret) stays in gateway.ts.
     expect(GATEWAY).toMatch(/pendingCardStore\.remove\(armed\.stageId\)/)
-    const decline = slice(GATEWAY, 'async function handleSecretRequestCallback', 3000)
+    // The decline branch moved with handleSecretRequestCallback into
+    // callback-query-handlers.ts (#2996 P5) — pin the body there, mirroring the
+    // handleMentalModelProposeCallback pin below.
+    const decline = slice(CB_HANDLERS, 'async function handleSecretRequestCallback', 3000)
     expect(decline).toMatch(/pendingCardStore\.remove\(stageId\)/)
   })
 
@@ -215,7 +224,7 @@ describe('TTL expiry wakes the parked agent (Defect B)', () => {
 
 describe('vault_request_access copy derives the window from the real TTL', () => {
   it('no hard-coded "10 min" claim; uses VAULT_REQUEST_ACCESS_TTL_MS', () => {
-    const fn = slice(GATEWAY, 'async function executeVaultRequestAccess', 12000)
+    const fn = slice(CARD_TOOL, 'async function executeVaultRequestAccess', 12000)
     expect(fn).not.toMatch(/times out \(10 min\)/)
     expect(fn).toMatch(/Math\.round\(VAULT_REQUEST_ACCESS_TTL_MS \/ 60000\)/)
   })

package/telegram-plugin/tests/per-topic-current-turn.test.ts

@@ -29,6 +29,17 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+// #2996 P4-A: the enqueue turn-ctor SET (`setCurrentTurn(next, statusKey(…))`)
+// and two of the three keyed-liveness comparison sites moved VERBATIM into
+// stream-render.ts with handleSessionEvent. In the extracted module the
+// flag-OFF liveness read routes through the injected accessor
+// (`getCurrentTurn() === turn`) rather than the `currentTurn` module global —
+// same invariant, accessor spelling. These wiring oracles span both files.
+const streamSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'stream-render.ts'), 'utf-8')
+// #2996 P8 PR-C3: the silence-poke fallback body (keyed delete + purgeChatStale
+// self-heal) moved verbatim to liveness-wiring.ts — those oracles read there.
+const livenessSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'liveness-wiring.ts'), 'utf-8')
+const gatewayAndStreamSrc = gatewaySrc + '\n' + streamSrc
 
 // ---------------------------------------------------------------------------
 // (a) SOURCE-READ STRUCTURAL ORACLE
@@ -51,19 +62,27 @@ describe('PR-4e source-read oracle — the wiring the per-topic map depends on',
     const rawAssigns = gatewaySrc.match(/^[^/\n]*\bcurrentTurn = (?!currentTurnMap\.get\(\)|null$)/gm) ?? []
     expect(rawAssigns, `unexpected raw currentTurn assignment(s): ${JSON.stringify(rawAssigns)}`).toEqual([])
 
-    // The turn ctor SET routes through setCurrentTurn with the statusKey.
-    expect(gatewaySrc).toMatch(/setCurrentTurn\(next, statusKey\(ev\.chatId, enqThreadIdNum\)\)/)
+    // The turn ctor SET routes through setCurrentTurn with the statusKey
+    // (now in stream-render.ts's `enqueue` branch — #2996 P4-A).
+    expect(gatewayAndStreamSrc).toMatch(/setCurrentTurn\(next, statusKey\(ev\.chatId, enqThreadIdNum\)\)/)
     // The disconnect-flush clears the WHOLE map (every entry is a ghost).
     expect(gatewaySrc).toMatch(/clearAllCurrentTurns\(\)/)
-    // The silence-poke fallback does a keyed delete for the wedged turn's key.
-    expect(gatewaySrc).toMatch(/endCurrentTurnForKey\(wedgedTurn, fbKey\)/)
+    // The silence-poke fallback does a keyed delete for the wedged turn's key
+    // (#2996 P8 PR-C3: the fallback body lives in liveness-wiring.ts).
+    expect(livenessSrc).toMatch(/endCurrentTurnForKey\(wedgedTurn, fbKey\)/)
   })
 
   it('endCurrentTurnAtomic closes the leak AT ORIGIN — keyed liveness guard + keyed delete', () => {
     // Anchor on the `function ` prefix only — the signature is multi-line
     // (gained an `opts?` param + `number | null` return in the send-honesty
     // work), and `function ` disambiguates the definition from its call sites.
-    const body = gatewaySrc
+    // #2996 P8 PR-B: the funnel body moved verbatim to turn-end.ts (gateway
+    // keeps a thin delegating wrapper) — read the body there.
+    const turnEndSrc = readFileSync(
+      resolve(__dirname, '..', 'gateway', 'turn-end.ts'),
+      'utf-8',
+    )
+    const body = turnEndSrc
       .split('function endCurrentTurnAtomic(')[1]
       ?.split('\n}')[0] ?? ''
     expect(body.length).toBeGreaterThan(50)
@@ -88,8 +107,12 @@ describe('PR-4e source-read oracle — the wiring the per-topic map depends on',
     // the flag, resolve THIS turn by ITS OWN topic key. We assert the keyed
     // form appears the expected number of times AND the literal flag-OFF form is
     // retained (the silence-liveness-wiring oracle requires `currentTurn === turn`).
-    const keyedLiveness = gatewaySrc.match(
-      /EMISSION_AUTHORITY_ENABLED \? turnLiveForItsTopic\(turn\) : currentTurn === turn/g,
+    // #2996 P4-A: two of the three sites moved to stream-render.ts, where the
+    // flag-OFF read is spelled `getCurrentTurn() === turn` (injected accessor);
+    // the one remaining in gateway.ts keeps `currentTurn === turn`. Match either
+    // spelling across both files — the population is still exactly 3.
+    const keyedLiveness = gatewayAndStreamSrc.match(
+      /EMISSION_AUTHORITY_ENABLED \? turnLiveForItsTopic\(turn\) : (?:currentTurn|getCurrentTurn\(\)) === turn/g,
     ) ?? []
     expect(keyedLiveness.length).toBe(3)
   })
@@ -105,7 +128,8 @@ describe('PR-4e source-read oracle — the wiring the per-topic map depends on',
   })
 
   it('the self-heal backstop drops per-topic entries for the swept chat (purgeChatStale)', () => {
-    expect(gatewaySrc).toMatch(/currentTurnMap\.purgeChatStale\(fbChatId,/)
+    // #2996 P8 PR-C3: the self-heal lives in the extracted fallback body.
+    expect(livenessSrc).toMatch(/currentTurnMap\.purgeChatStale\(fbChatId,/)
   })
 })