switchroom 0.18.32 → 0.19.0

package/telegram-plugin/tests/gateway-boot-smoke.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Runtime boot-smoke pin (finding M-1, full-stack adversarial review).
+ *
+ * The source-parse pin `gateway-boot-side-effect-gating.test.ts` proves the
+ * module-load side effects are `isGatewayMain`-guarded, but it NEVER actually
+ * boots the gateway — so it is structurally blind to a temporal-dead-zone
+ * ReferenceError inside a guarded builder. That exact class shipped on main:
+ * PR-C3 (#3392) made `gatewayLivenessWiringDeps()` eagerly read
+ * `pendingInboundBuffer` (a `const` declared ~200 lines LATER than the
+ * module-load `silencePoke.startTimer(...)` call that invokes the builder),
+ * crash-looping every real gateway boot with
+ *   `uncaughtException: ReferenceError: Cannot access 'pendingInboundBuffer'
+ *    before initialization`
+ * right after the boot lock — while CI stayed green because `isGatewayMain`
+ * is false under vitest (argv[1] is the runner).
+ *
+ * This test closes that blind spot the only way a source parse can't: it
+ * SPAWNS `bun telegram-plugin/gateway/gateway.ts` as the process entrypoint
+ * (so `isGatewayMain` is TRUE and every guarded module-load side effect
+ * actually runs), in a hermetic TELEGRAM_STATE_DIR with a fake bot token, and
+ * asserts the gateway reaches a POST-module-eval stderr marker
+ * (`ipc — listening`, emitted when `createIpcServer` binds its UDS at
+ * gateway.ts ~10454, well past the TDZ site) with NO
+ * `uncaughtException: ReferenceError` on the way. The 401-Unauthorized the
+ * fake token later triggers happens INSIDE `startGateway()` — after module
+ * eval — so it never precedes the marker and is not a boot-order failure.
+ *
+ * Parameterized over the two kill-switch postures so a future eager-read
+ * introduced on either the router-v2 or turn-end-funnel-v2 path is also
+ * caught:
+ *   - both flags unset (production default — now BOTH v2 ON after the flip)
+ *   - SWITCHROOM_INBOUND_ROUTER_V2=1 + SWITCHROOM_TURN_END_FUNNEL_V2=1
+ *   - both flags =0 (the escape-hatch legacy v1 posture — kept so the legacy
+ *     module-eval paths stay boot-smoked until the legacy delete)
+ *
+ * Bun is the prod + CI gateway runtime (`bun test` is a required check), so
+ * spawning it here is CI-native, not CI-hostile.
+ *
+ * VERIFIED to red on pre-fix main: reverting the getter fix in the working
+ * tree makes both parameterizations fail — the child dies on the ReferenceError
+ * and never emits the marker (mutation evidence in the PR body).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { spawn } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+
+// The marker is emitted synchronously by createIpcServer() at gateway.ts
+// (~10454), which is AFTER the module-load silence-poke wiring (~9653) that
+// held the TDZ read. Reaching it proves module eval cleared the crash site.
+const POST_EVAL_MARKER = 'ipc — listening'
+// A fake bot token: valid Bot API shape (<digits>:<35 chars>) so grammy's
+// constructor accepts it; the 401 only lands later during startGateway().
+const FAKE_BOT_TOKEN = '123456:' + 'A'.repeat(35)
+const BOOT_TIMEOUT_MS = 45_000
+
+interface BootResult {
+  reachedMarker: boolean
+  sawReferenceError: boolean
+  stderr: string
+}
+
+function bootGateway(extraEnv: Record<string, string>): Promise<BootResult> {
+  return new Promise<BootResult>((resolvePromise, rejectPromise) => {
+    const stateDir = mkdtempSync(join(tmpdir(), 'gw-boot-smoke-'))
+    const child = spawn('bun', [GATEWAY_PATH], {
+      env: {
+        ...process.env,
+        TELEGRAM_STATE_DIR: stateDir,
+        SWITCHROOM_GATEWAY_PID_FILE: join(stateDir, 'gateway.pid.json'),
+        TELEGRAM_BOT_TOKEN: FAKE_BOT_TOKEN,
+        SWITCHROOM_AGENT_NAME: 'boot-smoke',
+        // Scrub the two kill switches to a known-OFF baseline so the
+        // "unset" posture is genuinely unset even if the CI shell exports
+        // them; the "enabled" posture re-sets them via extraEnv below.
+        SWITCHROOM_INBOUND_ROUTER_V2: '',
+        SWITCHROOM_TURN_END_FUNNEL_V2: '',
+        ...extraEnv,
+      },
+      stdio: ['ignore', 'ignore', 'pipe'],
+    })
+
+    let stderr = ''
+    let settled = false
+    const finish = (): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { child.kill('SIGKILL') } catch { /* already gone */ }
+      try { rmSync(stateDir, { recursive: true, force: true }) } catch { /* best-effort */ }
+      resolvePromise({
+        reachedMarker: stderr.includes(POST_EVAL_MARKER),
+        sawReferenceError: /uncaughtException:\s*ReferenceError/.test(stderr),
+        stderr,
+      })
+    }
+
+    const timer = setTimeout(finish, BOOT_TIMEOUT_MS)
+
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderr += chunk.toString()
+      // As soon as we see the marker OR a boot-order ReferenceError, we have
+      // our verdict — no need to keep the child alive.
+      if (stderr.includes(POST_EVAL_MARKER) || /uncaughtException:\s*ReferenceError/.test(stderr)) {
+        finish()
+      }
+    })
+    child.on('error', (err) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { rmSync(stateDir, { recursive: true, force: true }) } catch { /* best-effort */ }
+      rejectPromise(err)
+    })
+    // If the process exits before the marker (e.g. the TDZ crash aborts the
+    // process), resolve with whatever we captured so the assertion can fail
+    // with the real stderr.
+    child.on('exit', finish)
+  })
+}
+
+const POSTURES: Array<{ name: string; env: Record<string, string> }> = [
+  // Flags unset is now the DEFAULT-ON posture (both `!== '0'`) after the
+  // v0.18.33 canary flip — the v2 router + v2 turn-end funnel are live.
+  { name: 'both kill switches unset (prod default — now BOTH v2 ON)', env: {} },
+  {
+    name: 'router-v2 + turn-end-funnel-v2 explicitly enabled',
+    env: { SWITCHROOM_INBOUND_ROUTER_V2: '1', SWITCHROOM_TURN_END_FUNNEL_V2: '1' },
+  },
+  {
+    // Explicit legacy posture: with both flags defaulting ON, the only way to
+    // boot-smoke the legacy (v1) module-eval paths is the `=0` escape hatch.
+    name: 'both kill switches disabled (=0 escape hatch — legacy v1 paths)',
+    env: { SWITCHROOM_INBOUND_ROUTER_V2: '0', SWITCHROOM_TURN_END_FUNNEL_V2: '0' },
+  },
+]
+
+describe('gateway boot-smoke (M-1): real bun boot reaches post-module-eval marker with no TDZ ReferenceError', () => {
+  it.each(POSTURES)('boots cleanly with %s', async ({ env }) => {
+    const result = await bootGateway(env)
+    // The load-bearing assertion: no temporal-dead-zone crash during module
+    // eval. If this reds, the stderr tail names the offending binding.
+    expect(
+      result.sawReferenceError,
+      `gateway boot emitted a ReferenceError before module eval finished:\n${result.stderr.slice(-2000)}`,
+    ).toBe(false)
+    // And it actually got past the TDZ site to the IPC-listening marker.
+    expect(
+      result.reachedMarker,
+      `gateway boot never reached "${POST_EVAL_MARKER}"; stderr tail:\n${result.stderr.slice(-2000)}`,
+    ).toBe(true)
+  }, BOOT_TIMEOUT_MS + 15_000)
+})

package/telegram-plugin/tests/gateway-handler-registration-wiring.test.ts

@@ -53,15 +53,11 @@ const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
  */
 const GOLDEN_REGISTRATIONS: readonly string[] = [
   'use',
-  'command:start',
-  'command:help',
-  'command:status',
-  'command:agents',
+  'helper:registerStartInfoCommands',
   'command:inject',
   'command:compact',
   'command:clear',
-  'command:model',
-  'command:effort',
+  'helper:registerModelEffortCommands',
   'command:agentstart',
   'command:agentstop',
   'command:stop',
@@ -122,7 +118,7 @@ const GOLDEN_REGISTRATIONS: readonly string[] = [
  * every `message:*` handler (grammY no-double-handling; see
  * catch-all-unhandled-message.test.ts) and before `message_reaction`.
  */
-const HELPER_REGISTRARS = new Set(['registerOpsInfoCommands', 'installUnhandledMessageCatchAll'])
+const HELPER_REGISTRARS = new Set(['registerOpsInfoCommands', 'registerStartInfoCommands', 'registerModelEffortCommands', 'installUnhandledMessageCatchAll'])
 
 const sourceFile = ts.createSourceFile(
   GATEWAY_PATH,

package/telegram-plugin/tests/gateway-loopback-paste-redact.test.ts

@@ -3,42 +3,50 @@ import { readFileSync } from 'node:fs'
 
 /**
  * Structural integration test for the loopback-paste fail-safe redaction in
- * the gateway's inbound handler (security audit #3084, F2/F3).
+ * the inbound intercept gauntlet (security audit #3084, F2/F3).
  *
- * Why structural: gateway/gateway.ts does not export its inbound handler, so a
- * pure-functional invocation would require end-to-end harnessing of
- * Bot/Grammy/Context. The decision predicate (shouldConsumeLoopbackPaste, incl.
+ * Why structural: the decision predicate (shouldConsumeLoopbackPaste, incl.
  * the malformed-paste fail-safe) is exhaustively unit-tested in
  * `auth-loopback-relay.test.ts`, and the redaction primitive
  * (redactAuthCodeMessage) in `auth-code-redact.test.ts`. What's left to assert
- * here is that the gateway actually WIRES a fail-safe so a code-bearing paste
- * that is malformed, or arrives just after the intercept TTL, or has no active
- * flow, is redacted + dropped rather than forwarded to the agent.
+ * here is that the intercept path actually WIRES a fail-safe so a code-bearing
+ * paste that is malformed, or arrives just after the intercept TTL, or has no
+ * active flow, is redacted + dropped rather than forwarded to the agent.
  *
- * The invariants:
+ * P7 PR-6 (#2996): the intercept body (pending-flow branch + fail-safe tail)
+ * moved verbatim into gateway/inbound-interceptors.ts
+ * (`interceptLoopbackRelay`); gateway.ts keeps the ordered delegation. The
+ * invariants are unchanged — only the file that owns each literal moved:
  *   1. The stale (TTL-expired) loopback branch does NOT let the paste fall
- *      through to the agent — it flows into the fail-safe below.
- *   2. A fail-safe `if (shouldConsumeLoopbackPaste(text))` block exists that
- *      redacts (redactAuthCodeMessage) and returns, sitting AFTER the
- *      pending-flow branch but BEFORE the generic auth-code / agent-forward
- *      handlers.
+ *      through to the agent — it flows into the fail-safe below it.
+ *   2. A fail-safe `if (shouldConsumeLoopbackPaste(p.text))` block exists that
+ *      redacts (deps.redactAuthCode → redactAuthCodeMessage) and returns
+ *      handled, sitting AFTER the pending-flow branch; the gateway invokes the
+ *      loopback intercept BEFORE the generic auth-code / reauth intercept.
  */
 describe('gateway loopback-paste fail-safe redaction — structural wiring', () => {
-  const src = readFileSync(
+  const gatewaySrc = readFileSync(
     new URL('../gateway/gateway.ts', import.meta.url),
     'utf8',
   )
+  const interceptorsSrc = readFileSync(
+    new URL('../gateway/inbound-interceptors.ts', import.meta.url),
+    'utf8',
+  )
 
-  it('imports the consume predicate + redaction helper', () => {
-    expect(src).toMatch(/shouldConsumeLoopbackPaste/)
-    expect(src).toMatch(/redactAuthCodeMessage/)
+  it('wires the consume predicate + redaction helper', () => {
+    // The intercept module owns the predicate; the gateway binds the
+    // redaction closure (deps.redactAuthCode → redactAuthCodeMessage).
+    expect(interceptorsSrc).toMatch(/shouldConsumeLoopbackPaste/)
+    expect(gatewaySrc).toMatch(/redactAuthCodeMessage/)
+    expect(gatewaySrc).toMatch(/interceptLoopbackRelay\(/)
   })
 
   it('has a fail-safe redact-and-return block guarded by shouldConsumeLoopbackPaste', () => {
-    // Isolate the fail-safe block: `if (shouldConsumeLoopbackPaste(text)) { ... }`
+    // Isolate the fail-safe block: `if (shouldConsumeLoopbackPaste(p.text)) { ... }`
     // that is NOT part of the `pendingLoop && ...` pending-flow branch.
-    const failSafe = src.match(
-      /if \(shouldConsumeLoopbackPaste\(text\)\) \{[\s\S]{0,600}?\n {2}\}/g,
+    const failSafe = interceptorsSrc.match(
+      /if \(shouldConsumeLoopbackPaste\(p\.text\)\) \{[\s\S]{0,700}?\n {2}\}/g,
     )
     expect(failSafe).not.toBeNull()
     // The standalone fail-safe (the one NOT preceded by `pendingLoop &&`).
@@ -46,21 +54,28 @@ describe('gateway loopback-paste fail-safe redaction — structural wiring', ()
       (b) => !b.startsWith('if (pendingLoop'),
     )
     expect(standalone).toBeDefined()
-    expect(standalone!).toMatch(/redactAuthCodeMessage/)
-    expect(standalone!).toMatch(/return/)
+    expect(standalone!).toMatch(/deps\.redactAuthCode/)
+    expect(standalone!).toMatch(/return \{ handled: true \}/)
   })
 
   it('the stale loopback branch falls through to the fail-safe (does not forward)', () => {
-    // The stale-path comment must reference the fail-safe, and the fail-safe
-    // block must appear AFTER the pending-loop branch and BEFORE the generic
-    // auth-code intercept (`pendingReauthFlows`).
-    const failSafeIdx = src.indexOf(
+    // The fail-safe block must appear AFTER the pending-loop branch inside the
+    // intercept module; and the gateway must invoke the loopback intercept
+    // BEFORE the generic auth-code intercept (`pendingReauthFlows`).
+    const failSafeIdx = interceptorsSrc.indexOf(
       'Fail-safe redaction (security audit #3084, F2/F3)',
     )
-    const pendingLoopIdx = src.indexOf('const pendingLoop = pendingLoopbackFlows.get')
-    const reauthIdx = src.indexOf('const pendingReauth = pendingReauthFlows.get')
+    const pendingLoopIdx = interceptorsSrc.indexOf(
+      'const pendingLoop = pendingLoopbackFlows.get',
+    )
     expect(failSafeIdx).toBeGreaterThan(-1)
     expect(failSafeIdx).toBeGreaterThan(pendingLoopIdx)
-    expect(reauthIdx).toBeGreaterThan(failSafeIdx)
+
+    const loopbackCallIdx = gatewaySrc.indexOf('interceptLoopbackRelay(')
+    // P7 PR-7: the reauth intercept body also moved; its gateway call site is
+    // the ordering anchor.
+    const reauthIdx = gatewaySrc.indexOf('interceptReauth(')
+    expect(loopbackCallIdx).toBeGreaterThan(-1)
+    expect(reauthIdx).toBeGreaterThan(loopbackCallIdx)
   })
 })

package/telegram-plugin/tests/gateway-outbound-redact.test.ts

@@ -29,6 +29,12 @@ describe('gateway outbound secret-scrub — structural wiring', () => {
     new URL('../gateway/outbound-send-path.ts', import.meta.url),
     'utf8',
   )
+  // #2996 P4-A: the turn-flush backstop scrub lives in handleSessionEvent,
+  // which moved VERBATIM to stream-render.ts.
+  const streamSrc = readFileSync(
+    new URL('../gateway/stream-render.ts', import.meta.url),
+    'utf8',
+  )
 
   it('imports the shared redactor', () => {
     expect(src).toMatch(/import \{ redact \} from '\.\.\/secret-detect\/redact\.js'/)
@@ -66,8 +72,8 @@ describe('gateway outbound secret-scrub — structural wiring', () => {
   it('turn-flush backstop: scrubs the model terminal prose before send', () => {
     // Turn-flush delivers the model's answer when it skipped reply/stream_reply
     // — arbitrary agent free-text that hits the wire + stderr preview.
-    const redactIdx = src.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
-    const scrubSiteIdx = src.indexOf(`site: 'turn_flush'`)
+    const redactIdx = streamSrc.indexOf(`redactOutboundText(capturedText, 'turn_flush')`)
+    const scrubSiteIdx = streamSrc.indexOf(`site: 'turn_flush'`)
     expect(redactIdx).toBeGreaterThan(0)
     expect(scrubSiteIdx).toBeGreaterThan(redactIdx) // mask BEFORE the voice scrub + send
   })

package/telegram-plugin/tests/gateway-request-secret.test.ts

@@ -15,6 +15,10 @@ import { readFileSync } from 'node:fs'
  */
 describe('request_secret — gateway wiring', () => {
   const gw = readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8')
+  // executeRequestSecret moved verbatim to card-tool-handlers.ts (#2996 P5-tail);
+  // the handler-body pins below read that module. The dispatch case + the
+  // secure-capture path (captureProvidedSecret / handleInbound) stay in gateway.ts.
+  const cardTool = readFileSync(new URL('../gateway/card-tool-handlers.ts', import.meta.url), 'utf8')
   const bridge = readFileSync(new URL('../bridge/bridge.ts', import.meta.url), 'utf8')
 
   it('declares the MCP tool with required {chat_id,key} and NO value arg', () => {
@@ -30,7 +34,7 @@ describe('request_secret — gateway wiring', () => {
 
   it('is allow-listed and dispatched', () => {
     expect(gw).toMatch(/'request_secret',\n/)
-    expect(gw).toMatch(/case 'request_secret':\s*\n\s*return executeRequestSecret\(args\)/)
+    expect(gw).toMatch(/case 'request_secret':\s*\n\s*return cardToolHandlers\.executeRequestSecret\(args\)/)
   })
 
   it('routes the vsp: callback', () => {
@@ -71,8 +75,8 @@ describe('request_secret — gateway wiring', () => {
   })
 
   it('dedupes to one open request per (chat,key)', () => {
-    const idx = gw.indexOf('async function executeRequestSecret(')
-    const body = gw.slice(idx, idx + 1800)
+    const idx = cardTool.indexOf('async function executeRequestSecret(')
+    const body = cardTool.slice(idx, idx + 1800)
     expect(body).toMatch(/p\.chat_id === chat_id && p\.key === key/)
   })
 })

package/telegram-plugin/tests/gateway-secret-detect.test.ts

@@ -26,10 +26,12 @@ import { readFileSync } from 'node:fs'
  * rather than live.
  */
 describe('gateway secret-detect intercept — structural wiring', () => {
-  const src = readFileSync(
-    new URL('../gateway/gateway.ts', import.meta.url),
-    'utf8',
-  )
+  const src =
+    readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8') +
+    '\n' +
+    // P7 PR-8 (#2996): the vault pending-op intercept (incl. the deferred-
+    // secret passphrase branch) moved into gateway/inbound-interceptors.ts.
+    readFileSync(new URL('../gateway/inbound-interceptors.ts', import.meta.url), 'utf8')
 
   it('imports the pipeline + staging modules', () => {
     expect(src).toMatch(/from '\.\.\/secret-detect\/pipeline\.js'/)
@@ -54,7 +56,9 @@ describe('gateway secret-detect intercept — structural wiring', () => {
   })
 
   it('runPipeline call sits BEFORE recordInbound() and ipcServer.broadcast(inboundMsg)', () => {
-    const pipelineIdx = src.indexOf('runPipeline({')
+    // P7 PR-9: runPipeline lives in interceptSecretDetectPipeline; the
+    // gateway CALL SITE is the ordering anchor against the sinks.
+    const pipelineIdx = src.indexOf('await interceptSecretDetectPipeline(')
     const recordIdx = src.indexOf('recordInbound(', pipelineIdx)
     const broadcastIdx = src.indexOf('ipcServer.broadcast(inboundMsg)', pipelineIdx)
     expect(pipelineIdx).toBeGreaterThan(0)
@@ -74,7 +78,7 @@ describe('gateway secret-detect intercept — structural wiring', () => {
     // swallowed. See
     // tests/secret-detect-delete-must-surface-failures.test.ts for
     // the full contract pin.
-    expect(tail).toMatch(/deleteSensitiveMessage\(chat_id, msgId, 'detected secret'\)/)
+    expect(tail).toMatch(/deleteSensitiveMessage\((?:p\.)?chat_id, (?:p\.)?msgId, 'detected secret'\)/)
     // Tells the user what was captured (masked).
     expect(tail).toMatch(/captured \$\{pipeRes\.stored\.length\} secret/)
     // Surfaces the masked form (s.masked is computed via maskToken in the pipeline).
@@ -102,7 +106,7 @@ describe('gateway secret-detect intercept — structural wiring', () => {
     //    migrated to deleteSensitiveMessage so failures surface to the
     //    operator via in-chat warning. See
     //    tests/secret-detect-delete-must-surface-failures.test.ts.
-    expect(tail).toMatch(/deleteSensitiveMessage\(chat_id, msgId, 'detected secret'\)/)
+    expect(tail).toMatch(/deleteSensitiveMessage\((?:p\.)?chat_id, (?:p\.)?msgId, 'detected secret'\)/)
     // 4. The new inline keyboard helper is used in lieu of the legacy
     //    plain-text "run /vault list" warning.
     expect(tail).toMatch(/buildDeferredSecretKeyboard\(/)
@@ -134,9 +138,15 @@ describe('gateway secret-detect intercept — structural wiring', () => {
     // pre-staging body, not a precise offset — it has grown before (#3020's
     // stop-keyword block pushed it past the old 30k) and may grow again;
     // bump it when new early-return branches land above the staging block.
-    const handleInboundIdx = src.indexOf('async function handleInbound(')
-    const tail = src.slice(handleInboundIdx, handleInboundIdx + 50000)
+    // P7 PR-9: the parser moved to interceptSecretStagingCommand
+    // (inbound-interceptors.ts), still invoked from handleInbound's
+    // inbound-text path (same allowFrom gating) — anchor on the function.
+    const stagingFnIdx = src.indexOf('export async function interceptSecretStagingCommand(')
+    expect(stagingFnIdx).toBeGreaterThan(0)
+    const tail = src.slice(stagingFnIdx, stagingFnIdx + 6000)
     expect(tail).toMatch(/\(stash\|ignore\|rename\|forget\)/)
-    expect(tail).toMatch(/secretStaging\.latestForChat\(chat_id\)/)
+    expect(tail).toMatch(/secretStaging\.latestForChat\((?:p\.)?chat_id\)/)
+    // And handleInbound must actually delegate to it.
+    expect(src).toMatch(/await interceptSecretStagingCommand\(/)
   })
 })

package/telegram-plugin/tests/gateway-session-model-relaunch.test.ts

@@ -122,9 +122,15 @@ describe('gateway: the live callback dispatcher routes every switch tap to the h
   })
 
   it('the typed dispatcher relays the handler reply directly (no recordTypedModelSwitch)', () => {
-    const idx = GATEWAY_SRC.indexOf('const reply = await handleModelCommand(parsed, deps)')
+    // #2996 P6: the typed /model handler moved to bot-commands-model-effort.ts
+    // (registerModelEffortCommands); scrape the extracted module instead.
+    const MODULE_SRC = readFileSync(
+      resolve(__dirname, '..', 'gateway', 'bot-commands-model-effort.ts'),
+      'utf8',
+    )
+    const idx = MODULE_SRC.indexOf('const reply = await handleModelCommand(parsed, cmdDeps)')
     expect(idx).toBeGreaterThan(0)
-    const win = GATEWAY_SRC.slice(idx, idx + 400)
+    const win = MODULE_SRC.slice(idx, idx + 400)
     expect(win).not.toContain('recordTypedModelSwitch')
     expect(win).toContain('switchroomReply(ctx, reply.text')
   })

package/telegram-plugin/tests/inbound-emit-after-intercepts.test.ts

@@ -28,6 +28,10 @@ import { dirname, resolve } from 'node:path'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const GATEWAY_SRC = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf8')
+// P8 PR-D: the isSteering classification body moved verbatim to
+// turn-start-surfaces.ts; the gateway call site (armTurnStartSurfaces) is the
+// ordering anchor now.
+const TURN_START_SRC = readFileSync(resolve(__dirname, '..', 'gateway', 'turn-start-surfaces.ts'), 'utf8')
 
 /** Byte offset of the sole `shadowEmit({ kind: 'inbound' ... })` call. */
 function inboundEmitOffset(): number {
@@ -50,21 +54,28 @@ describe('gateway: inbound machine-emit is deferred past the intercepts', () =>
     const emitIdx = inboundEmitOffset()
     // The permission-reply intercept is one of the early-return paths that
     // must NOT drive the machine into a turn.
-    const permIdx = GATEWAY_SRC.indexOf('const permMatch = PERMISSION_REPLY_RE.exec(text)')
+    // P7 PR-4: the intercept body moved to inbound-interceptors.ts; the
+    // gateway call site is the ordering anchor now.
+    const permIdx = GATEWAY_SRC.indexOf('interceptPermissionReply({ text, chat_id, msgId }')
     expect(permIdx).toBeGreaterThan(0)
     expect(emitIdx).toBeGreaterThan(permIdx)
   })
 
   it('emits AFTER the `/auth add` paste-back intercept', () => {
     const emitIdx = inboundEmitOffset()
-    const authIdx = GATEWAY_SRC.indexOf('pendingAuthAddFlows.get(interceptKey)')
+    // P7 PR-5: the intercept body moved to inbound-interceptors.ts; the
+    // gateway call site is the ordering anchor now.
+    const authIdx = GATEWAY_SRC.indexOf('interceptAuthAdd(')
     expect(authIdx).toBeGreaterThan(0)
     expect(emitIdx).toBeGreaterThan(authIdx)
   })
 
   it('emits AFTER isSteering is classified, and passes the real value (not a hardcoded false)', () => {
     const emitIdx = inboundEmitOffset()
-    const steerIdx = GATEWAY_SRC.indexOf('isSteering = priorTurnInFlight && isSteerPrefix')
+    // P8 PR-D: classification lives in turn-start-surfaces.ts; the gateway
+    // ordering anchor is the armTurnStartSurfaces call that computes it.
+    expect(TURN_START_SRC).toContain('isSteering = priorTurnInFlight && isSteerPrefix')
+    const steerIdx = GATEWAY_SRC.indexOf('turnStartSurfaces().armTurnStartSurfaces({')
     expect(steerIdx).toBeGreaterThan(0)
     expect(emitIdx).toBeGreaterThan(steerIdx)
     // The emit's msg object must forward the live `isSteering` binding, so a

package/telegram-plugin/tests/inbound-message-types.test.ts

@@ -39,30 +39,62 @@ const SRC = readFileSync(
   'utf8',
 )
 
+// The media-envelope handlers were extracted out of gateway.ts into their own
+// module (switchroom#2996 P6 cluster A). gateway.ts keeps the `bot.on(…)`
+// registration lines (their order is a load-bearing invariant) but each now
+// delegates to a `handle<Kind>Message(ctx, mediaEnvelopeDeps)` function that
+// lives here. The structural assertions below still need to see the real
+// handler body, so we resolve a delegation to the extracted source.
+const MEDIA_SRC = readFileSync(
+  new URL('../gateway/media-message-handlers.ts', import.meta.url),
+  'utf8',
+)
+
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
 /**
- * Extract the body of a `bot.on('message:<kind>', …)` handler. Returns
- * the substring from the `bot.on(` line up to the matching closing
- * `})` at the outer scope. Good enough for grepping — not a full
- * AST parse.
+ * Return the substring of `src` starting at `header` up to the matching
+ * closing brace of the block it opens. Naive depth count of {/} from the
+ * first `{` — good enough for grepping, not a full AST parse.
  */
-function handlerBody(kind: string): string {
-  const needle = `bot.on('message:${kind}'`
-  const start = SRC.indexOf(needle)
-  expect(start, `handler bot.on('message:${kind}') not found`).toBeGreaterThan(0)
-  // Find the matching close — naive depth count of {/} from the first `{`.
-  const firstBrace = SRC.indexOf('{', start)
+function braceBlock(src: string, header: string, label: string): string {
+  const start = src.indexOf(header)
+  expect(start, `${label} not found`).toBeGreaterThan(0)
+  const firstBrace = src.indexOf('{', start)
   let depth = 0
-  for (let i = firstBrace; i < SRC.length; i++) {
-    const c = SRC[i]
+  for (let i = firstBrace; i < src.length; i++) {
+    const c = src[i]
     if (c === '{') depth++
     else if (c === '}') {
       depth--
-      if (depth === 0) return SRC.slice(start, i + 1)
+      if (depth === 0) return src.slice(start, i + 1)
     }
   }
-  throw new Error(`could not find end of handler ${kind}`)
+  throw new Error(`could not find end of ${label}`)
+}
+
+/**
+ * Extract the body of a `bot.on('message:<kind>', …)` handler. If the
+ * registration delegates to an extracted `handle<Kind>Message(ctx,
+ * mediaEnvelopeDeps)` function, the returned body is that function's source
+ * (from media-message-handlers.ts). Otherwise it is the inline gateway.ts
+ * handler block. Either way callers see the real handler logic.
+ */
+function handlerBody(kind: string): string {
+  const needle = `bot.on('message:${kind}'`
+  const start = SRC.indexOf(needle)
+  expect(start, `handler bot.on('message:${kind}') not found`).toBeGreaterThan(0)
+  const lineEnd = SRC.indexOf('\n', start)
+  const regLine = SRC.slice(start, lineEnd < 0 ? SRC.length : lineEnd)
+  const delegate = regLine.match(/(handle\w+Message)\(ctx,\s*mediaEnvelopeDeps\)/)
+  if (delegate) {
+    return braceBlock(
+      MEDIA_SRC,
+      `export async function ${delegate[1]}(`,
+      `extracted handler ${delegate[1]}`,
+    )
+  }
+  return braceBlock(SRC, needle, `handler ${kind}`)
 }
 
 // ─── Registration completeness ───────────────────────────────────────────
@@ -108,7 +140,9 @@ describe('inbound message-type handlers: forwarding decisions', () => {
     it(`${kind} forwards via handleInbound and logs to stderr`, () => {
       const body = handlerBody(kind)
       expect(body).toMatch(/handleInbound\(ctx,/)
-      expect(body).toMatch(/process\.stderr\.write/)
+      // Logs the event — directly (inline handlers) or via the injected
+      // `deps.log` stderr sink (extracted media-envelope handlers).
+      expect(body).toMatch(/process\.stderr\.write|deps\.log\(/)
       // Must not divert to the ack-only path — that would silently
       // hide the payload from the agent.
       expect(body).not.toMatch(/handleAckOnly\(/)
@@ -148,7 +182,9 @@ describe('inbound message-type handlers: ack-only decisions', () => {
     it(`${kind} uses handleAckOnly (no forward to agent)`, () => {
       const body = handlerBody(kind)
       expect(body).toMatch(/handleAckOnly\(/)
-      expect(body).toMatch(/process\.stderr\.write/)
+      // Logs the event — directly (inline handlers) or via the injected
+      // `deps.log` stderr sink (extracted media-envelope handlers).
+      expect(body).toMatch(/process\.stderr\.write|deps\.log\(/)
       // Ack-only must NOT call handleInbound — the whole point is
       // we don't bother the agent for these.
       expect(body).not.toMatch(/handleInbound\(/)