switchroom 0.18.31 → 0.18.33

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/obligation-ledger.test.ts

@@ -620,3 +620,43 @@ describe("ObligationLedger — escalation suppression predicate (Fix 4)", () =>
     expect(snapshots[1]).toEqual([]);
   });
 });
+
+// #3282 — the durable captured-answer snapshot attaches to the OPEN obligation
+// so a partial backstop delivery is resumed (tail only) rather than regenerated.
+describe("ObligationLedger — noteCapturedDelivery (#3282)", () => {
+  function input(id: string, openedAt: number) {
+    return { originTurnId: id, chatId: "-100123", threadId: 3, messageId: 1, text: "q", openedAt };
+  }
+  const snap = { chunks: ["c0", "c1"], chunkStates: [{ index: 0, messageIds: [10], confirmed: true }] };
+
+  it("attaches the snapshot to an OPEN obligation and persists it", () => {
+    const snapshots: Obligation[][] = [];
+    const L = new ObligationLedger(2, { onChange: (s) => snapshots.push(s) });
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteCapturedDelivery("c:3#1", snap);
+    expect(L.list()[0]!.capturedDelivery).toEqual(snap);
+    // The mutation persisted (onChange fired again after open).
+    expect(snapshots.at(-1)![0]!.capturedDelivery).toEqual(snap);
+  });
+
+  it("is a no-op for an obligation that is not open (a delivered turn has none to resume)", () => {
+    const L = new ObligationLedger(2);
+    L.noteCapturedDelivery("c:3#missing", snap); // never opened
+    expect(L.isOpen("c:3#missing")).toBe(false);
+  });
+
+  it("ignores an EMPTY snapshot (nothing to resume)", () => {
+    const L = new ObligationLedger(2);
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteCapturedDelivery("c:3#1", { chunks: [], chunkStates: [] });
+    expect(L.list()[0]!.capturedDelivery).toBeUndefined();
+  });
+
+  it("close drops the snapshot with the obligation (bounded lifetime, A6)", () => {
+    const L = new ObligationLedger(2);
+    L.openIfAbsent(input("c:3#1", 1000));
+    L.noteCapturedDelivery("c:3#1", snap);
+    expect(L.close("c:3#1")).toBe(true);
+    expect(L.isOpen("c:3#1")).toBe(false);
+  });
+});

package/telegram-plugin/tests/obligation-store.test.ts

@@ -118,6 +118,49 @@ describe("obligation-store", () => {
     expect(loaded[0]!.representCount).toBe(1);
   });
 
+  it("round-trips a valid capturedDelivery snapshot through persist → load (#3282)", () => {
+    const { fs } = memFs();
+    const capturedDelivery = {
+      chunks: ["c0", "c1"],
+      chunkStates: [
+        { index: 0, messageIds: [10], confirmed: true },
+        { index: 1, messageIds: [11, 12], confirmed: false },
+      ],
+    };
+    persistObligations(PATH, fs, [ob("c:3#715", { capturedDelivery })]);
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0]!.capturedDelivery).toEqual(capturedDelivery);
+  });
+
+  it("STRIPS a malformed capturedDelivery (fail-open to fresh-generation represent) (#3282)", () => {
+    // A partial write / forward-incompatible shape must not crash the resume: the
+    // row survives (obligation preserved), the bad blob is dropped.
+    const bad = {
+      v: 1,
+      obligations: [
+        { ...ob("c:3#715"), capturedDelivery: { chunks: "not-an-array", chunkStates: [] } },
+        { ...ob("c:3#716"), capturedDelivery: { chunks: ["c0"], chunkStates: [{ index: 0 }] } },
+      ],
+    };
+    const { fs } = memFs({ [PATH]: JSON.stringify(bad) });
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded.map((o) => o.originTurnId)).toEqual(["c:3#715", "c:3#716"]);
+    expect(loaded[0]!.capturedDelivery).toBeUndefined();
+    expect(loaded[1]!.capturedDelivery).toBeUndefined();
+  });
+
+  it("STRIPS an empty-chunks capturedDelivery (nothing to resume → fresh-gen, bounded) (#3282)", () => {
+    const bad = {
+      v: 1,
+      obligations: [{ ...ob("c:3#715"), capturedDelivery: { chunks: [], chunkStates: [] } }],
+    };
+    const { fs } = memFs({ [PATH]: JSON.stringify(bad) });
+    const loaded = loadObligations(PATH, fs);
+    expect(loaded).toHaveLength(1);
+    expect(loaded[0]!.capturedDelivery).toBeUndefined();
+  });
+
   it("never throws on a write failure — degrades to in-memory (logs)", () => {
     const logs: string[] = [];
     const fs: ObligationStoreFsSeam = {

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\)/)
   })
 
@@ -143,7 +152,8 @@ describe('resolution clears the durable store (Defect A)', () => {
 
 describe('TTL expiry wakes the parked agent (Defect B)', () => {
   it('the periodic reaper runs the approval-card expiry sweep inside try/catch', () => {
-    const reaper = slice(GATEWAY, 'const pendingStateReaper = setInterval', 12000)
+    // Anchor tolerates the #2996 P0c `isGatewayMain ? setInterval(...)` boot gate.
+    const reaper = slice(GATEWAY, 'const pendingStateReaper = ', 12000)
     // The sweep call must be guarded like the sibling sweepStaleTurnActiveMarker:
     // an escaped throw inside this setInterval callback reaches uncaughtException
     // and takes the whole gateway down.
@@ -214,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\)/)
   })