switchroom 0.18.31 → 0.18.33

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -261,22 +261,37 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
     new URL('../gateway/gateway.ts', import.meta.url),
     'utf8',
   )
+  // #2996 P4-A: the turn_flush backstop (redact → normalize → scrub on
+  // `capturedText`) moved VERBATIM into stream-render.ts with
+  // handleSessionEvent. The reply path's identical `...(text))` wrapper lives
+  // in outbound-send-path.ts (`normalizeOutboundBody`, #2996 P2). Parity is
+  // pinned across the two extracted homes.
+  const streamSrc = readFileSync(
+    new URL('../gateway/stream-render.ts', import.meta.url),
+    'utf8',
+  )
+  const replyModuleSrc = readFileSync(
+    new URL('../gateway/outbound-send-path.ts', import.meta.url),
+    'utf8',
+  )
 
   it('reply path: normalizes AFTER redact and BEFORE the voice scrub', () => {
     // #2996: the reply-path entry pipeline moved into outbound-send-path.ts
     // (`normalizeOutboundBody`). The reply path delegates to it via
     // `normalizeOutboundBody(rawText, 'reply', redactOutboundText)`; the
     // redact→normalize→scrub ordering is now pinned in the module source.
-    const replyDelegates = gatewaySrc.indexOf(
-      `normalizeOutboundBody(rawText, 'reply', redactOutboundText)`,
-      gatewaySrc.indexOf('async function executeReply('),
-    )
-    expect(replyDelegates).toBeGreaterThan(0)
-
     const moduleSrc = readFileSync(
       new URL('../gateway/outbound-send-path.ts', import.meta.url),
       'utf8',
     )
+    // #2996 P2: the reply orchestration itself now lives in the module
+    // (`sendReply`); the delegation line is pinned there.
+    const replyDelegates = moduleSrc.indexOf(
+      `normalizeOutboundBody(rawText, 'reply', redactOutboundText)`,
+      moduleSrc.indexOf('export async function sendReply('),
+    )
+    expect(replyDelegates).toBeGreaterThan(0)
+
     const start = moduleSrc.indexOf('export function normalizeOutboundBody(')
     const redactIdx = moduleSrc.indexOf('redact(text, site)', start)
     const normIdx = moduleSrc.indexOf('stripExcessBold(normalizePunctuation(text))', start)
@@ -288,13 +303,13 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   })
 
   it('turn-flush backstop: applies the SAME normalization in the SAME slot (REDS if the line is removed)', () => {
-    const redactIdx = gatewaySrc.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
+    const redactIdx = streamSrc.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
     // The normalization call the reply path uses, verbatim, on the turn_flush
     // variable. This indexOf is what returns -1 (→ assertion fails) if the
     // `stripExcessBold(normalizePunctuation(capturedText))` line is deleted
     // from the turn_flush branch.
-    const normIdx = gatewaySrc.indexOf('stripExcessBold(normalizePunctuation(capturedText))', redactIdx)
-    const scrubIdx = gatewaySrc.indexOf('scrubVoice(capturedText)', redactIdx)
+    const normIdx = streamSrc.indexOf('stripExcessBold(normalizePunctuation(capturedText))', redactIdx)
+    const scrubIdx = streamSrc.indexOf('scrubVoice(capturedText)', redactIdx)
     expect(redactIdx).toBeGreaterThan(0)
     expect(normIdx).toBeGreaterThan(redactIdx) // normalize AFTER the turn_flush redact
     expect(scrubIdx).toBeGreaterThan(normIdx) // ...and BEFORE the voice scrub — mirrors reply
@@ -303,8 +318,8 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   it('both send sites share the identical `stripExcessBold(normalizePunctuation(` wrapper', () => {
     // Parity, structurally: the exact normalization wrapper the reply path uses
     // is the one the turn_flush branch uses — same call, not a lookalike.
-    expect(gatewaySrc).toContain('stripExcessBold(normalizePunctuation(text))')
-    expect(gatewaySrc).toContain('stripExcessBold(normalizePunctuation(capturedText))')
+    expect(replyModuleSrc).toContain('stripExcessBold(normalizePunctuation(text))')
+    expect(streamSrc).toContain('stripExcessBold(normalizePunctuation(capturedText))')
   })
 
   // Behavioural coverage (kept from the original suite): reconstruct the
@@ -676,3 +691,168 @@ describe('selectFlushDeliveryText — deliver the terminal answer, strip only na
     }
   })
 })
+
+// ── #3237: STRUCTURAL block-provenance discriminator ───────────────────────
+// The opener heuristic cannot tell a narration preamble from a real answer
+// paragraph that merely opens with "Let me explain…". The structural flag
+// (`followedByToolUse`, = `!lastInMessage`) can: a narration preamble is
+// followed by a tool_use in its message; a terminal answer paragraph is not.
+describe('selectFlushDeliveryText — structural provenance (followedByToolUse) #3237', () => {
+  // The exact real-answer shape from #3237: a genuine two-paragraph answer
+  // whose FIRST block opens with a narration phrase, written as plain text with
+  // NO tool calls (the model forgot the reply tool → flush path). Structure
+  // says neither block was followed by a tool_use, so nothing is narration.
+  const p1 =
+    'Let me explain how the flush path works: it fires at turn_end when the ' +
+    'model never called the reply tool, joining the captured assistant text ' +
+    'blocks with a paragraph break so the answer renders with real separation.'
+  const p2 =
+    'The terminal block is always delivered, so the answer is never fully ' +
+    'lost — but the opening paragraph could be dropped by the opener-only strip.'
+
+  it('#3237 regression: a real 2-paragraph answer opening with "Let me explain…" is NOT truncated when structure says neither block was followed by a tool_use', () => {
+    // With NO structural signal (legacy string[]) the opener strip DROPS p1.
+    expect(selectFlushDeliveryText([p1, p2])).toBe(p2) // documents the bug
+    // With structure present ([false,false]) the full answer is delivered.
+    const out = selectFlushDeliveryText([p1, p2], [false, false])
+    expect(out).toBe(`${p1}\n\n${p2}`)
+    expect(out).toContain('Let me explain how the flush path works')
+  })
+
+  it('duplicate-reply fix preserved: a narration block FOLLOWED by a tool_use is stripped, terminal answer delivered', () => {
+    const narration = 'Let me pull the numbers together before I answer.'
+    const realAnswer = 'Revenue was 4.2M, up 12% year over year.'
+    // followedByToolUse[0]=true (the model drafted then acted), [1]=false (terminal).
+    const out = selectFlushDeliveryText([narration, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Let me pull the numbers')
+  })
+
+  it('structure alone drives the strip — a preamble the opener regex would MISS is still stripped when it was followed by a tool_use', () => {
+    // "Here are the figures" matches no NARRATION_OPENER, but a tool_use
+    // followed it → structural narration → stripped.
+    const preamble = 'Here are the figures you asked about.'
+    const realAnswer = 'The three services are all green.'
+    const out = selectFlushDeliveryText([preamble, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Here are the figures')
+  })
+
+  it('structure WINS over the opener heuristic — a "Let me…" opener NOT followed by a tool_use is kept (never truncated)', () => {
+    const first = 'Let me walk you through the three steps in order.'
+    const second = 'Step one is to branch off fresh main.'
+    // Opener-only would strip `first`; structure ([false,false]) keeps it.
+    expect(selectFlushDeliveryText([first, second], [false, false])).toBe(
+      `${first}\n\n${second}`,
+    )
+  })
+
+  it('per-block fallback: an UNDEFINED entry falls back to the opener heuristic for that block only', () => {
+    const narration = 'Let me check that.'
+    const realAnswer = 'Done — all green.'
+    // meta[0] undefined → fall back to isNarrationBlock("Let me check that.") = true → stripped.
+    const out = selectFlushDeliveryText([narration, realAnswer], [undefined, false])
+    expect(out).toBe(realAnswer)
+  })
+
+  it('flag-absent back-compat: omitting the meta array reproduces today\'s opener-strip EXACTLY', () => {
+    // Every legacy case behaves identically with no meta argument.
+    expect(selectFlushDeliveryText(['Let me check.', 'the answer'])).toBe('the answer')
+    expect(selectFlushDeliveryText(['Checking now…', 'The build is green.'])).toBe(
+      'The build is green.',
+    )
+    expect(selectFlushDeliveryText([p1, p2])).toBe(p2) // opener strip drops p1
+    const first = 'B'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS + 5)
+    const last = 'C'.repeat(FLUSH_SUBSTANTIVE_MIN_CHARS + 5)
+    expect(selectFlushDeliveryText([first, last])).toBe(`${first}\n\n${last}`)
+  })
+
+  it('meta stays ALIGNED across the empty-block filter (zip-before-filter)', () => {
+    // An empty block between narration and answer must not shift the meta index.
+    const narration = 'Let me look that up.'
+    const realAnswer = 'The value is 42.'
+    // blocks[1] is empty (dropped); meta must still map [narration→true, ''→_, answer→false].
+    const out = selectFlushDeliveryText([narration, '   ', realAnswer], [true, false, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Let me look that up')
+  })
+
+  it('cross-message shape: narration (msg1, tool_use after) + answer (msg2, terminal) → narration stripped', () => {
+    // lastInMessage semantics are per-message; a narration that is the last text
+    // of msg1 but has a tool_use after it in msg1 is followedByToolUse=true.
+    const narration = 'Let me search the codebase for the symbol.'
+    const realAnswer = 'It is defined in session-tail.ts.'
+    const out = selectFlushDeliveryText([narration, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+  })
+
+  it('decideTurnFlush plumbs capturedBlockMeta through to the strip (#3237 end-to-end)', () => {
+    // Real-answer case: structure keeps both paragraphs.
+    const keep = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: [p1, p2],
+      capturedBlockMeta: [false, false],
+    })
+    expect(keep.kind).toBe('flush')
+    if (keep.kind === 'flush') expect(keep.text).toBe(`${p1}\n\n${p2}`)
+
+    // Narration case: structure strips the preamble.
+    const strip = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: ['Let me pull the numbers.', 'Revenue was 4.2M.'],
+      capturedBlockMeta: [true, false],
+    })
+    expect(strip.kind).toBe('flush')
+    if (strip.kind === 'flush') expect(strip.text).toBe('Revenue was 4.2M.')
+  })
+
+  // Regression for the post-#3338 review finding: a SUBSTANTIAL real-content
+  // block (≥ FLUSH_SUBSTANTIVE_MIN_CHARS, NOT narration-shaped) that happens to
+  // be followed by a tool_use must be KEPT — the model can write a real answer
+  // paragraph, then call a memory/verify tool, then a short wrap-up. Trusting
+  // followedByToolUse ALONE (the pre-fix behaviour) dropped the real answer and
+  // delivered only the wrap-up. The structural strip is gated by the substantive
+  // floor, so the substantial block survives.
+  it('substantial real-content block followed by a tool_use is KEPT (structural flag gated by the substantive floor)', () => {
+    const realAnswer =
+      'The migration completed cleanly across all five shards: each shard was ' +
+      'drained, the schema applied under an advisory lock, and traffic cut back ' +
+      'over with zero dropped requests. The new index brought the p99 query time ' +
+      'down from 840ms to 60ms, and the old columns are now safe to remove in ' +
+      'the next release once the read path is confirmed off them entirely.'
+    expect(realAnswer.length).toBeGreaterThanOrEqual(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    // Not narration-shaped: no first-person "about to do X" opener, no
+    // trailing ellipsis/colon — so only the structural flag could strip it.
+    const wrapUp = 'Saved that to memory.'
+    // meta[0]=true (a memory tool_use followed the real answer), [1]=false.
+    const out = selectFlushDeliveryText([realAnswer, wrapUp], [true, false])
+    expect(out).toBe(`${realAnswer}\n\n${wrapUp}`)
+    expect(out).toContain('The migration completed cleanly')
+
+    // End-to-end through decideTurnFlush.
+    const decision = decideTurnFlush({
+      chatId: 'chat1',
+      replyCalled: false,
+      capturedText: [realAnswer, wrapUp],
+      capturedBlockMeta: [true, false],
+    })
+    expect(decision.kind).toBe('flush')
+    if (decision.kind === 'flush') {
+      expect(decision.text).toBe(`${realAnswer}\n\n${wrapUp}`)
+    }
+  })
+
+  // A SHORT block followed by a tool_use is still stripped via the length floor
+  // (the pre-#3237 "short preamble the opener misses" behaviour is preserved):
+  // it is below FLUSH_SUBSTANTIVE_MIN_CHARS, so the gated strip still fires.
+  it('short block followed by a tool_use is still stripped (length-floor branch of the gate)', () => {
+    const shortPreamble = 'Here are the figures you asked about.'
+    expect(shortPreamble.length).toBeLessThan(FLUSH_SUBSTANTIVE_MIN_CHARS)
+    const realAnswer = 'The three services are all green.'
+    const out = selectFlushDeliveryText([shortPreamble, realAnswer], [true, false])
+    expect(out).toBe(realAnswer)
+    expect(out).not.toContain('Here are the figures')
+  })
+})

package/telegram-plugin/tests/turn-flush-suppression-wiring.test.ts

@@ -0,0 +1,117 @@
+/**
+ * S1/S2/S4 WIRING (fable red-team 2026-07-17, fixed in #3299 @ a6e09dfb).
+ *
+ * The behavioural suite `turn-flush-suppression.test.ts` proves the scoped
+ * suppression predicate in isolation, and `answer-ready-flush.test.ts` proves
+ * the quiescence controller's reset/re-arm semantics — but neither says
+ * whether the GATEWAY actually calls them, or what it does with the answer.
+ * That decision-vs-delivery gap is exactly how the original S1 bug shipped:
+ * every routine was individually correct while the gateway's call site
+ * counted ANY chat-wide outbound and then CLOSED the obligation, silently
+ * dropping the user's real answer.
+ *
+ * gateway.ts is a side-effecting IIFE that cannot be imported in a unit test
+ * (same constraint as activity-card-wiring.test.ts /
+ * silence-liveness-wiring.test.ts), so these are STRUCTURAL assertions that
+ * pin the load-bearing call sites. They COMPLEMENT the behavioural suites —
+ * the outcomes are proven at routine level; this guards the wiring those
+ * routines depend on. Each test names the regression it would catch.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8')
+// #2996 P4-A: the turn-flush / turn_end / `thinking`-arm code moved VERBATIM
+// into stream-render.ts with handleSessionEvent. Windows that used to live in
+// the gateway switch are grepped from the extracted module now.
+const streamSrc = readFileSync(resolve(__dirname, '..', 'gateway', 'stream-render.ts'), 'utf-8')
+const gatewayAndStreamSrc = gatewaySrc + '\n' + streamSrc
+
+function between(src: string, startMarker: string, endMarker: string): string {
+  const after = src.split(startMarker)[1] ?? ''
+  return after.split(endMarker)[0] ?? ''
+}
+
+/** Strip // comment lines so prose quoting the OLD (buggy) shape can't
+ *  satisfy — or trip — an assertion about the CODE. */
+function codeOnly(src: string): string {
+  return src
+    .split('\n')
+    .filter((l) => !l.trim().startsWith('//'))
+    .filter((l) => !l.trim().startsWith('*') && !l.trim().startsWith('/*'))
+    .join('\n')
+}
+
+describe('S1 wiring — turn-flush suppression call site', () => {
+  // The whole suppression branch: predicate call through the end of the
+  // `if (suppress)` early-return.
+  const branch = between(
+    streamSrc,
+    'const { shouldSuppressTurnFlush }',
+    '// #3276 guard 5',
+  )
+
+  it('the gateway asks the SCOPED predicate, not a chat-wide outbound count', () => {
+    expect(branch.length).toBeGreaterThan(100)
+    const code = codeOnly(branch)
+    // The oracle is the thread/length-scoped history query…
+    expect(code).toMatch(/hasSubstantiveOutbound:\s*hasOutboundDeliveredSince/)
+    // …with an EXPLICIT null thread for chat-root turns (undefined would
+    // match rows in ANY topic and re-open the cross-topic false positive)…
+    expect(code).toMatch(/threadId:\s*backstopThreadId\s*\?\?\s*null/)
+    // …and the captured answer's length driving the substantive floor.
+    expect(code).toMatch(/answerLength:\s*capturedText\.length/)
+    // The OLD chat-wide predicate must never come back anywhere in the branch.
+    expect(code).not.toMatch(/getRecentOutboundCount/)
+  })
+
+  it('suppression leaves the obligation OPEN (noteTurnEnded) — never closes it', () => {
+    const code = codeOnly(branch)
+    // A false-positive suppression must stay recoverable: the sweep/liveness
+    // floor arbitrates. Closing here made the drop PERMANENT (the S1 bug).
+    expect(code).toMatch(/obligationLedger\.noteTurnEnded\(turn\.turnId/)
+    expect(code).not.toMatch(/obligationLedger\.close\(/)
+  })
+
+  it('the old predicate is gone from the whole gateway turn-flush path', () => {
+    // getRecentOutboundCount must not be consulted anywhere in gateway.ts —
+    // any reintroduction re-opens the chat-wide suppression class.
+    expect(codeOnly(gatewayAndStreamSrc)).not.toMatch(/getRecentOutboundCount/)
+  })
+})
+
+describe('S2 wiring — thinking events re-arm the answer-ready quiescence flush', () => {
+  it("the 'thinking' event arm calls resetAnswerReadyFlushTimeout()", () => {
+    // Without this, "prose → >1s thinking pause → trailing NO_REPLY" lets the
+    // quiescence timer fire mid-pause and deliver a turn the model intended
+    // silent. Scope to the thinking case arm only.
+    const arm = between(streamSrc, "case 'thinking': {", "case 'tool_use': {")
+    expect(arm.length).toBeGreaterThan(50)
+    expect(codeOnly(arm)).toMatch(/resetAnswerReadyFlushTimeout\(\)/)
+  })
+})
+
+describe('S4 wiring — flushed answers quote-anchor to the inbound they answer', () => {
+  it('deliverAnswer anchors the FIRST chunk with reply_parameters + allow_sending_without_reply', () => {
+    const sendChunk = between(
+      gatewaySrc,
+      'const sendChunk = async (chunkIndex: number',
+      'buildSendOpts:',
+    )
+    expect(sendChunk.length).toBeGreaterThan(50)
+    const code = codeOnly(sendChunk)
+    // First chunk only, and only when the turn has an inbound to anchor to.
+    expect(code).toMatch(/chunkIndex === 0 && args\.replyToMessageId != null/)
+    // allow_sending_without_reply keeps the send alive if the user deleted
+    // their message — without it the whole flush would fail on a dangling id.
+    expect(code).toMatch(/allow_sending_without_reply:\s*true/)
+    expect(code).toMatch(/reply_parameters/)
+  })
+
+  it('the turn-flush call site passes the turn’s inbound id (bare for synthesized turns)', () => {
+    // The anchor must be the message this TURN answers — turn.sourceMessageId
+    // is null for cron/handback turns, which therefore still send bare.
+    expect(codeOnly(gatewayAndStreamSrc)).toMatch(/replyToMessageId:\s*turn\.sourceMessageId/)
+  })
+})

package/telegram-plugin/tests/vault-approval-posture.test.ts

@@ -48,7 +48,10 @@ import { resolveVaultApprovalPosture } from '../vault-approval-posture.js'
 const gatewaySrc =
   readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
   '\n' +
-  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8') +
+  '\n' +
+  // P7 PR-8 (#2996): vault pending-op intercept moved to inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, '..', 'gateway', 'inbound-interceptors.ts'), 'utf-8')
 
 function sliceAccessApproveBlock(): string {
   const fn =
@@ -102,7 +105,10 @@ describe('handleVaultRequestAccessCallback — posture branch', () => {
     expect(approveBlock).toMatch(/passphrase-for-access-approve/)
     // Pinned: the queued-drain path passes the typed passphrase via
     // the new attestation shape `{ kind: 'passphrase', passphrase }`.
-    expect(gatewaySrc).toMatch(/performVaultAccessApproval\(ctx, stagedAccess, item\.stageId, item\.senderId, \{ kind: ['"]passphrase['"], passphrase \}\)/)
+    // P7 PR-8: the queued-drain call site moved into interceptVault
+    // (inbound-interceptors.ts) — ctx is `p.ctx` and the handler resolves via
+    // the lazy deps accessor. Same attestation shape pinned.
+    expect(gatewaySrc).toMatch(/performVaultAccessApproval\((?:p\.)?ctx, stagedAccess, item\.stageId, item\.senderId, \{ kind: ['"]passphrase['"], passphrase \}\)/)
   })
 })
 

package/telegram-plugin/tests/vault-grant-inbound-builders.test.ts

@@ -414,8 +414,8 @@ describe('approve vs deny shape invariants', () => {
 // grant/save-outcome inbound must carry that topic so the resumed turn's
 // reply lands back in it — not General. The carrier is two-fold and BOTH
 // halves are load-bearing:
-//   - top-level `threadId` → the gateway's per-topic busy-key / deliver-
-//     until-acked keying (markClaudeBusyForInbound reads it).
+//   - top-level `threadId` → the gateway's per-topic deliver-until-acked
+//     keying (chatKeyForInbound reads it).
 //   - `meta.message_thread_id` (stringified) → rendered into the
 //     `<channel message_thread_id="…">` XML, which session-tail's
 //     parseChannelMeta re-extracts to set currentTurn.sessionThreadId, which

package/telegram-plugin/tests/vault-grant-union.test.ts

@@ -29,7 +29,10 @@ import { resolve } from "node:path";
 const gatewaySrc =
   readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
   "\n" +
-  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8") +
+  "\n" +
+  // P7 PR-8 (#2996): vault pending-op intercept moved to inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, "..", "gateway", "inbound-interceptors.ts"), "utf-8");
 
 function extractPerformBlock(): string {
   const start = gatewaySrc.indexOf("async function performVaultAccessApproval");

package/telegram-plugin/tests/vault-key-regex-allows-slash.test.ts

@@ -28,13 +28,21 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 // #2996 Phase 5: the callback-query handler families moved verbatim to
-// gateway/callback-query-handlers.ts; these pins read the gateway source
-// COMBINED with that module so the wiring assertions keep covering the
-// same runtime source text.
+// gateway/callback-query-handlers.ts, and the agent-facing card-STAGING
+// execute* tool handlers (vault_request_save & co) moved verbatim to
+// gateway/card-tool-handlers.ts (#2996 P5-tail); these pins read the gateway
+// source COMBINED with those modules so the wiring assertions keep covering
+// the same runtime source text.
 const gatewaySrc =
   readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
   "\n" +
-  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8") +
+  "\n" +
+  readFileSync(resolve(__dirname, "..", "gateway", "card-tool-handlers.ts"), "utf-8") +
+  "\n" +
+  // P7 PR-8 (#2996): the vault pending-op intercept (incl. the rename-staged-
+  // key validation) moved verbatim into gateway/inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, "..", "gateway", "inbound-interceptors.ts"), "utf-8");
 
 /** The exported regex literal — what the gateway actually validates against. */
 function extractVaultKeyRegex(): RegExp {
@@ -49,7 +57,10 @@ function extractVaultKeyRegex(): RegExp {
 }
 
 /** Either inline literal with `/`, OR a reference to VAULT_KEY_REGEX. */
-const ACCEPTS_SLASH = /\[A-Za-z0-9_(\/|\\\/|\.)+-\]|VAULT_KEY_REGEX/;
+// `vaultKeyRegex` is the InboundInterceptorDeps field gateway.ts binds to the
+// shared VAULT_KEY_REGEX constant (P7 PR-8) — same runtime regex, new name at
+// the moved call site.
+const ACCEPTS_SLASH = /\[A-Za-z0-9_(\/|\\\/|\.)+-\]|VAULT_KEY_REGEX|vaultKeyRegex/;
 
 describe("vault-key regex accepts canonical slash-namespaced keys (#1047)", () => {
   it("vault_request_save validation includes '/' in the charclass", () => {

package/telegram-plugin/tests/vault-request-access-tool.test.ts

@@ -24,13 +24,16 @@ const bridgeSrc = readFileSync(
   'utf-8',
 )
 // #2996 Phase 5: the callback-query handler families moved verbatim to
-// gateway/callback-query-handlers.ts; these pins read the gateway source
-// COMBINED with that module so the wiring assertions keep covering the
-// same runtime source text.
+// gateway/callback-query-handlers.ts, and the agent-facing card-STAGING
+// execute* tool handlers moved verbatim to gateway/card-tool-handlers.ts
+// (#2996 P5-tail); these pins read the gateway source COMBINED with those
+// modules so the wiring assertions keep covering the same runtime source text.
 const gatewaySrc =
   readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
   '\n' +
-  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8') +
+  '\n' +
+  readFileSync(resolve(__dirname, '..', 'gateway', 'card-tool-handlers.ts'), 'utf-8')
 
 describe('vault_request_access (#1012)', () => {
   it('bridge advertises the tool to MCP clients', () => {
@@ -64,7 +67,9 @@ describe('vault_request_access (#1012)', () => {
   it('gateway routes vault_request_access in executeToolCall', () => {
     // fails when: the switch arm is dropped. Tool would be accepted
     // by ALLOWED_TOOLS but fall through to the `unknown tool` branch.
-    expect(gatewaySrc).toMatch(/case\s+'vault_request_access':\s*\n\s*return\s+executeVaultRequestAccess/)
+    // #2996 P5-tail: the dispatcher arm now routes through the extracted
+    // card-tool-handlers factory instance.
+    expect(gatewaySrc).toMatch(/case\s+'vault_request_access':\s*\n\s*return\s+cardToolHandlers\.executeVaultRequestAccess/)
   })
 
   it('gateway dispatches vra: callback prefix', () => {

package/telegram-plugin/tests/vault-request-access-unlock-resume.test.ts

@@ -29,7 +29,10 @@ import { resolve } from 'node:path'
 const gatewaySrc =
   readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
   '\n' +
-  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8') +
+  '\n' +
+  // P7 PR-8 (#2996): vault pending-op intercept moved to inbound-interceptors.ts.
+  readFileSync(resolve(__dirname, '..', 'gateway', 'inbound-interceptors.ts'), 'utf-8')
 
 describe('vault_request_access — tap-to-unlock-and-approve UX', () => {
   it('declares the passphrase-for-access-approve PendingVaultOp variant', () => {

package/telegram-plugin/tests/vault-subcommands.test.ts

@@ -30,7 +30,12 @@ import { join, dirname } from 'node:path'
 const __dir = dirname(fileURLToPath(import.meta.url))
 const pluginDir = join(__dir, '..')
 
-const gatewaySrc = readFileSync(join(pluginDir, 'gateway', 'gateway.ts'), 'utf8')
+const gatewaySrc =
+  readFileSync(join(pluginDir, 'gateway', 'gateway.ts'), 'utf8') +
+  '\n' +
+  // P7 PR-8 (#2996): the vault pending-op intercept (incl. the unlock branch)
+  // moved verbatim into gateway/inbound-interceptors.ts (interceptVault).
+  readFileSync(join(pluginDir, 'gateway', 'inbound-interceptors.ts'), 'utf8')
 
 // ─── helpers ─────────────────────────────────────────────────────────────────
 

package/telegram-plugin/tests/voice-message-handler.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Outcome pins for the voice inbound handler extracted from gateway.ts
+ * (switchroom#2996 P6 cluster E). Drives the engine-selection + transcription
+ * fallback branch against injected access / host-capability / transcribe
+ * surfaces + a mock coalescing dispatch. Asserts the EXACT envelope forwarded
+ * to handleInboundCoalesced for each path (local/cloud transcript, caption
+ * prefix, disabled, and every fallback to the legacy "(voice message)").
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { handleVoiceMessage, type VoiceHandlerDeps } from '../gateway/voice-message-handler.js'
+
+const VOICE_META = { kind: 'voice', file_id: 'v1', size: 100, mime: 'audio/ogg' }
+
+function makeDeps(over: Partial<VoiceHandlerDeps> = {}) {
+  const handleInboundCoalesced = vi.fn(async () => {})
+  const deps: VoiceHandlerDeps = {
+    loadAccess: () => ({ voice_in: { enabled: true, provider: 'openai', api_key: 'k', language: 'en' } }),
+    loadHostCapabilities: () => null,
+    maybeTranscribeVoiceLocal: vi.fn(async () => 'LOCAL TEXT'),
+    maybeTranscribeVoice: vi.fn(async () => 'CLOUD TEXT'),
+    handleInboundCoalesced,
+    ...over,
+  }
+  return { deps, handleInboundCoalesced }
+}
+
+function ctxWith(caption?: string): any {
+  return { message: { voice: { file_id: 'v1', file_size: 100, mime_type: 'audio/ogg' }, caption }, chat: { id: 42 } }
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  delete process.env.SWITCHROOM_VOICE_ENGINE
+})
+
+describe('handleVoiceMessage — cloud path', () => {
+  it('transcribes via cloud and forwards a [voice transcript] envelope', async () => {
+    delete process.env.SWITCHROOM_VOICE_ENGINE
+    const { deps, handleInboundCoalesced } = makeDeps()
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(deps.maybeTranscribeVoice).toHaveBeenCalledWith('v1', 'audio/ogg', 'en', 'k')
+    expect(deps.maybeTranscribeVoiceLocal).not.toHaveBeenCalled()
+    expect(handleInboundCoalesced).toHaveBeenCalledWith(
+      expect.anything(), '[voice transcript] CLOUD TEXT', undefined, VOICE_META,
+    )
+  })
+
+  it('prefixes the caption to the transcript when present', async () => {
+    const { deps, handleInboundCoalesced } = makeDeps()
+    await handleVoiceMessage(ctxWith('note:'), deps)
+    expect(handleInboundCoalesced.mock.calls[0][1]).toBe('note:\n\n[voice transcript] CLOUD TEXT')
+  })
+})
+
+describe('handleVoiceMessage — local path', () => {
+  it('routes to the local sidecar when the engine env is local', async () => {
+    process.env.SWITCHROOM_VOICE_ENGINE = 'local'
+    // voice_in.provider need not be openai for the local path.
+    const { deps, handleInboundCoalesced } = makeDeps({
+      loadAccess: () => ({ voice_in: { enabled: true, language: 'de' } }),
+    })
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(deps.maybeTranscribeVoiceLocal).toHaveBeenCalledWith('v1', 'audio/ogg', 'de')
+    expect(deps.maybeTranscribeVoice).not.toHaveBeenCalled()
+    expect(handleInboundCoalesced.mock.calls[0][1]).toBe('[voice transcript] LOCAL TEXT')
+  })
+
+  it('reads the engine from host-capabilities when env is unset', async () => {
+    delete process.env.SWITCHROOM_VOICE_ENGINE
+    const { deps } = makeDeps({
+      loadAccess: () => ({ voice_in: { enabled: true } }),
+      loadHostCapabilities: () => ({ voice: { engine: 'local' } }),
+    })
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(deps.maybeTranscribeVoiceLocal).toHaveBeenCalled()
+  })
+})
+
+describe('handleVoiceMessage — fallbacks to the legacy envelope', () => {
+  it('falls back when voice_in is disabled', async () => {
+    const { deps, handleInboundCoalesced } = makeDeps({ loadAccess: () => ({}) })
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(deps.maybeTranscribeVoice).not.toHaveBeenCalled()
+    expect(handleInboundCoalesced).toHaveBeenCalledWith(
+      expect.anything(), '(voice message)', undefined, VOICE_META,
+    )
+  })
+
+  it('falls back to the legacy envelope on transcription failure', async () => {
+    const { deps, handleInboundCoalesced } = makeDeps({ maybeTranscribeVoice: vi.fn(async () => null) })
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(handleInboundCoalesced).toHaveBeenCalledWith(
+      expect.anything(), '(voice message)', undefined, VOICE_META,
+    )
+  })
+
+  it('uses the caption as the legacy envelope when present', async () => {
+    const { deps, handleInboundCoalesced } = makeDeps({ loadAccess: () => ({}) })
+    await handleVoiceMessage(ctxWith('hi there'), deps)
+    expect(handleInboundCoalesced.mock.calls[0][1]).toBe('hi there')
+  })
+
+  it('does not use the cloud path when provider is not openai', async () => {
+    delete process.env.SWITCHROOM_VOICE_ENGINE
+    const { deps } = makeDeps({ loadAccess: () => ({ voice_in: { enabled: true } }) })
+    await handleVoiceMessage(ctxWith(), deps)
+    expect(deps.maybeTranscribeVoice).not.toHaveBeenCalled()
+    expect(deps.maybeTranscribeVoiceLocal).not.toHaveBeenCalled()
+  })
+})