switchroom 0.18.31 → 0.18.33

package/telegram-plugin/tests/gateway-boot-side-effect-gating.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Import-safety pin for the #2996 P0c move: the remaining module-load side
+ * effects of gateway.ts are gated behind `isGatewayMain` so importing the
+ * module performs NO boot side effects, and the boot sequence is the guarded
+ * `startGateway()` at the bottom of the file.
+ *
+ * WHY this asserts on the parsed SOURCE, not a real `import()`:
+ * the repo's oracle for "pin gateway structure without booting it" is
+ * source-parsing via `ts.createSourceFile` — the same pattern as
+ * gateway-bot-construction-deferral.test.ts (P0b) and
+ * gateway-handler-registration-wiring.test.ts (P0a). (Since P0e, #3318, a
+ * hermetic `await import()` of gateway.ts does complete cleanly; upgrading
+ * this oracle to a real runtime import is possible but deliberately out of
+ * scope here — the source parse stays the pinned pattern.) This test follows
+ * it and asserts OUTCOMES:
+ *
+ *   1. `isGatewayMain` is a module-scope const whose value is the argv[1]
+ *      main-check (true only when this module is the process entrypoint).
+ *   2. The boot sequence is `async function startGateway()`, invoked EXACTLY
+ *      once, and that sole invocation is guarded by `isGatewayMain`. The old
+ *      top-level boot IIFE (`void (async () => …)()`) is gone.
+ *   3. No UNGUARDED module-scope side effect remains: every top-level
+ *      `setInterval` / `setTimeout` / `<x>.startTimer(…)` / `mkdirSync` /
+ *      `runHistoryReaperNow` / `openTurnsDb` / `initHistory` /
+ *      `acquireStartupLock` / `startWebhookIngestServer` /
+ *      `createPollHealthCheck` / `loadObligations` /
+ *      `installPosthogErrorHandlers` / `sweepActiveReactions` /
+ *      `process.on(…)` call, and every module-scope `await`, sits inside an
+ *      `isGatewayMain` guard (an `if (isGatewayMain …)` or an
+ *      `isGatewayMain ? … : …` ternary) — or inside a function body.
+ *
+ * A regression that re-hoists a timer, the startup-lock await, the boot IIFE,
+ * or the turn-registry open back to unguarded module scope fails (3).
+ *
+ * The process signal/error handlers (`process.on('SIGTERM'|'SIGINT'|
+ * 'beforeExit'|'unhandledRejection'|'uncaughtException')`,
+ * `installPosthogErrorHandlers()`) and the startup reaction sweep
+ * (`sweepActiveReactions`) — the "P0d" inventory from the P0c handback — were
+ * gated behind `isGatewayMain` by P0e (#3318, `ab34bb7b`) too; #2996 P0d was
+ * verified already-delivered and closed with no PR (plan Amendment 11). They
+ * ARE in the sentinel set below, so a regression that un-gates any of them
+ * back to bare module scope fails (3) as well.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+function isFunctionLike(n: ts.Node): boolean {
+  return (
+    ts.isFunctionDeclaration(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n) ||
+    ts.isConstructorDeclaration(n) ||
+    ts.isGetAccessorDeclaration(n) ||
+    ts.isSetAccessorDeclaration(n)
+  )
+}
+
+function lineOf(n: ts.Node): number {
+  return sourceFile.getLineAndCharacterOfPosition(n.getStart(sourceFile)).line + 1
+}
+
+// The side-effect sentinels. Each of these, at module scope, MUST be
+// isGatewayMain-guarded: the first block since P0c, the last two — the "P0d"
+// process-wiring inventory, gated by P0e (#3318) — since P0e.
+const CALL_SENTINELS = new Set([
+  'setInterval',
+  'setTimeout',
+  'mkdirSync',
+  'runHistoryReaperNow',
+  'openTurnsDb',
+  'initHistory',
+  'acquireStartupLock',
+  'startWebhookIngestServer',
+  'createPollHealthCheck',
+  'loadObligations',
+  'installPosthogErrorHandlers',
+  'sweepActiveReactions',
+])
+
+function sentinelName(n: ts.Node): string | null {
+  if (ts.isCallExpression(n)) {
+    const e = n.expression
+    if (ts.isIdentifier(e) && CALL_SENTINELS.has(e.text)) return e.text
+    // `<obj>.startTimer(...)` — the silencePoke / pendingProgress timers.
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'startTimer') {
+      return `${e.expression.getText(sourceFile)}.startTimer`
+    }
+    // `process.on(...)` — the P0d signal/error-handler registrations
+    // (SIGTERM / SIGINT / beforeExit / unhandledRejection /
+    // uncaughtException), gated by P0e. Several route through shutdown() →
+    // process.exit, so an unguarded registration makes exit reachable from a
+    // bare import.
+    if (
+      ts.isPropertyAccessExpression(e) &&
+      e.name.text === 'on' &&
+      ts.isIdentifier(e.expression) &&
+      e.expression.text === 'process'
+    ) {
+      return 'process.on'
+    }
+  }
+  if (n.kind === ts.SyntaxKind.AwaitExpression) return 'await'
+  return null
+}
+
+function guardsOnMain(cond: ts.Expression): boolean {
+  return cond.getText(sourceFile).includes('isGatewayMain')
+}
+
+/**
+ * Walk the module top level (never descending into function bodies) collecting
+ * unguarded sentinels. `guarded` becomes true beneath an isGatewayMain
+ * if/ternary branch.
+ */
+function collectUnguarded(): string[] {
+  const findings: string[] = []
+  function walk(node: ts.Node, guarded: boolean): void {
+    if (isFunctionLike(node)) return
+    if (ts.isIfStatement(node) && guardsOnMain(node.expression)) {
+      walk(node.thenStatement, true)
+      if (node.elseStatement) walk(node.elseStatement, guarded)
+      return
+    }
+    if (ts.isConditionalExpression(node) && guardsOnMain(node.condition)) {
+      walk(node.whenTrue, true)
+      walk(node.whenFalse, guarded)
+      return
+    }
+    const s = sentinelName(node)
+    if (s && !guarded) findings.push(`${s}@${lineOf(node)}`)
+    ts.forEachChild(node, c => walk(c, guarded))
+  }
+  for (const stmt of sourceFile.statements) walk(stmt, false)
+  return findings
+}
+
+describe('gateway #2996 P0c: module-load boot side effects are gated behind isGatewayMain', () => {
+  it('declares `isGatewayMain` as a module-scope const with the argv[1] main-check', () => {
+    let found = false
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isVariableStatement(stmt)) continue
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === 'isGatewayMain') {
+          found = true
+          const init = decl.initializer?.getText(sourceFile) ?? ''
+          // Guards on argv[1] ending in the source or the built bundle name.
+          expect(init).toContain('process.argv[1]')
+          expect(init).toContain("endsWith('gateway.ts')")
+          expect(init).toContain("endsWith('gateway.js')")
+        }
+      }
+    }
+    expect(found).toBe(true)
+  })
+
+  it('defines an async `startGateway()` boot function and NO leftover boot IIFE', () => {
+    let startGatewayFn: ts.FunctionDeclaration | undefined
+    for (const stmt of sourceFile.statements) {
+      if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === 'startGateway') {
+        startGatewayFn = stmt
+      }
+    }
+    expect(startGatewayFn).toBeDefined()
+    const isAsync = (startGatewayFn!.modifiers ?? []).some(
+      m => m.kind === ts.SyntaxKind.AsyncKeyword,
+    )
+    expect(isAsync).toBe(true)
+
+    // The old top-level boot IIFE `void (async () => {…})()` must be gone: no
+    // module-scope immediately-invoked async arrow remains.
+    let bootIifes = 0
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isExpressionStatement(stmt)) continue
+      let expr = stmt.expression
+      if (ts.isVoidExpression(expr)) expr = expr.expression
+      if (
+        ts.isCallExpression(expr) &&
+        (ts.isArrowFunction(expr.expression) || ts.isFunctionExpression(expr.expression))
+      ) {
+        const inner = expr.expression
+        const asyncArrow =
+          (inner.modifiers ?? []).some(m => m.kind === ts.SyntaxKind.AsyncKeyword)
+        if (asyncArrow) bootIifes++
+      }
+    }
+    expect(bootIifes).toBe(0)
+  })
+
+  it('invokes startGateway() EXACTLY once, guarded by isGatewayMain', () => {
+    let total = 0
+    let guardedCalls = 0
+    function walk(node: ts.Node, guarded: boolean): void {
+      if (isFunctionLike(node)) return // only the module-scope invocation
+      if (ts.isIfStatement(node) && guardsOnMain(node.expression)) {
+        walk(node.thenStatement, true)
+        if (node.elseStatement) walk(node.elseStatement, guarded)
+        return
+      }
+      if (
+        ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'startGateway'
+      ) {
+        total++
+        if (guarded) guardedCalls++
+      }
+      ts.forEachChild(node, c => walk(c, guarded))
+    }
+    for (const stmt of sourceFile.statements) walk(stmt, false)
+    expect(total).toBe(1)
+    expect(guardedCalls).toBe(1)
+  })
+
+  it('leaves NO unguarded module-scope timer / boot-I/O / startup-lock side effect', () => {
+    // If this fails it prints exactly which sentinel (e.g. `setInterval@1234`,
+    // `await@9750`, `openTurnsDb@1700`) escaped the isGatewayMain guard.
+    expect(collectUnguarded()).toEqual([])
+  })
+
+  it('gates every module-scope timer handle (the 4 reaper/tick consts)', () => {
+    // pendingStateReaper / midSessionCardReaper / _deliveryMachineTick /
+    // _deliveryConfirmSweep are `const X = isGatewayMain ? setInterval(…) :
+    // undefined` — their setInterval must be inside an isGatewayMain ternary.
+    const timerConsts = new Set([
+      'pendingStateReaper',
+      'midSessionCardReaper',
+      '_deliveryMachineTick',
+      '_deliveryConfirmSweep',
+    ])
+    const seen = new Set<string>()
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isVariableStatement(stmt)) continue
+      for (const decl of stmt.declarationList.declarations) {
+        if (
+          ts.isIdentifier(decl.name) &&
+          timerConsts.has(decl.name.text) &&
+          decl.initializer
+        ) {
+          seen.add(decl.name.text)
+          const init = decl.initializer
+          // Must be a conditional whose condition mentions isGatewayMain and
+          // whose truthy branch is the setInterval call.
+          expect(ts.isConditionalExpression(init)).toBe(true)
+          if (ts.isConditionalExpression(init)) {
+            expect(guardsOnMain(init.condition)).toBe(true)
+            expect(init.whenTrue.getText(sourceFile)).toContain('setInterval')
+          }
+        }
+      }
+    }
+    expect([...seen].sort()).toEqual([...timerConsts].sort())
+  })
+})

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

@@ -0,0 +1,150 @@
+/**
+ * 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 today)
+ *   - SWITCHROOM_INBOUND_ROUTER_V2=1 + SWITCHROOM_TURN_END_FUNNEL_V2=1
+ *
+ * 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> }> = [
+  { name: 'both kill switches unset (prod default)', env: {} },
+  {
+    name: 'router-v2 + turn-end-funnel-v2 enabled',
+    env: { SWITCHROOM_INBOUND_ROUTER_V2: '1', SWITCHROOM_TURN_END_FUNNEL_V2: '1' },
+  },
+]
+
+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-bot-construction-deferral.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Import-safety pin for the #2996 P0b move: token materialization + `new Bot`
+ * construction are DEFERRED out of module import into the boot function
+ * `initGatewayBot()`.
+ *
+ * WHY this asserts on the parsed SOURCE, not a real `import()`:
+ * gateway.ts is NOT import-safe under vitest yet — the boot IIFE (`void (async
+ * () => { … })()`) still fires at module evaluation and P0b deliberately does
+ * NOT touch it (that guard is P0c/P0d scope). So a real `await import()` would
+ * still trigger the boot path. The oracle for "how the repo pins gateway
+ * structure without booting it" is source-parsing via `ts.createSourceFile`
+ * (see gateway-handler-registration-wiring.test.ts /
+ * gateway-pending-command-wiring.test.ts). This test follows that pattern and
+ * asserts OUTCOMES about where construction lives:
+ *
+ *   1. Module import (top-level, outside any function body) performs NO
+ *      `new Bot(...)`, NO dynamic import of the materialize-bot-token helper,
+ *      NO `materializeBotToken(...)` call, and has NO reachable `process.exit`
+ *      and NO top-level `await`. i.e. importing gateway.ts constructs no bot,
+ *      reads no token, and cannot exit the process.
+ *   2. `bot` is a deferred module-scope `let` (definite-assignment), NOT a
+ *      `const bot = new Bot(...)`.
+ *   3. The boot function `initGatewayBot()` DOES all of the above: it is an
+ *      async function whose body contains the `new Bot(...)`, the materialize
+ *      dynamic import, the `materializeBotToken(...)` call, and the single
+ *      `registerGatewayHandlers(bot, …)` wiring call.
+ *
+ * A count/handler-theater test would not catch a regression that re-hoists
+ * `new Bot` or the token read back to module scope; these node-location
+ * assertions do.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+const MATERIALIZE_MODULE_HINT = 'materialize-bot-token'
+
+function isFunctionLike(n: ts.Node): boolean {
+  return (
+    ts.isFunctionDeclaration(n) ||
+    ts.isFunctionExpression(n) ||
+    ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n) ||
+    ts.isConstructorDeclaration(n) ||
+    ts.isGetAccessorDeclaration(n) ||
+    ts.isSetAccessorDeclaration(n)
+  )
+}
+
+/**
+ * Walk every node that executes at MODULE SCOPE — i.e. descend through the
+ * source file but STOP at any function-like boundary (function/arrow/method
+ * bodies run later, when called, not at import). A `new Bot` or token read
+ * found here would fire at import; the whole point of P0b is that none do.
+ */
+function walkModuleScope(visitor: (n: ts.Node) => void): void {
+  const recur = (node: ts.Node): void => {
+    ts.forEachChild(node, child => {
+      if (isFunctionLike(child)) return // do not descend into function bodies
+      visitor(child)
+      recur(child)
+    })
+  }
+  recur(sourceFile)
+}
+
+function isNewBot(n: ts.Node): boolean {
+  return ts.isNewExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === 'Bot'
+}
+
+function isMaterializeDynamicImport(n: ts.Node): boolean {
+  // `import('…materialize-bot-token…')`
+  if (!ts.isCallExpression(n)) return false
+  if (n.expression.kind !== ts.SyntaxKind.ImportKeyword) return false
+  const arg = n.arguments[0]
+  return arg != null && ts.isStringLiteralLike(arg) && arg.text.includes(MATERIALIZE_MODULE_HINT)
+}
+
+function isMaterializeBotTokenCall(n: ts.Node): boolean {
+  return ts.isCallExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === 'materializeBotToken'
+}
+
+function isProcessExitCall(n: ts.Node): boolean {
+  return (
+    ts.isCallExpression(n) &&
+    ts.isPropertyAccessExpression(n.expression) &&
+    ts.isIdentifier(n.expression.expression) &&
+    n.expression.expression.text === 'process' &&
+    n.expression.name.text === 'exit'
+  )
+}
+
+function findFunction(name: string): ts.FunctionDeclaration | undefined {
+  for (const s of sourceFile.statements) {
+    if (ts.isFunctionDeclaration(s) && s.name?.text === name) return s
+  }
+  return undefined
+}
+
+/** Count nodes matching a predicate anywhere within a subtree. */
+function countIn(root: ts.Node, pred: (n: ts.Node) => boolean): number {
+  let count = 0
+  const visit = (node: ts.Node): void => {
+    if (pred(node)) count++
+    ts.forEachChild(node, visit)
+  }
+  visit(root)
+  return count
+}
+
+describe('gateway #2996 P0b: token materialization + new Bot are deferred to boot, import is construction-clean', () => {
+  it('constructs NO Bot at module import (no top-level `new Bot`)', () => {
+    let count = 0
+    walkModuleScope(n => {
+      if (isNewBot(n)) count++
+    })
+    expect(count).toBe(0)
+  })
+
+  it('reads NO token at module import (no top-level materialize import or materializeBotToken call)', () => {
+    let dynImports = 0
+    let materializeCalls = 0
+    walkModuleScope(n => {
+      if (isMaterializeDynamicImport(n)) dynImports++
+      if (isMaterializeBotTokenCall(n)) materializeCalls++
+    })
+    expect(dynImports).toBe(0)
+    expect(materializeCalls).toBe(0)
+  })
+
+  it('performs NO token-refusal exit at module import (no top-level process.exit for token materialization)', () => {
+    // NOTE: the pre-existing startup-lock mutex (#…) still has one top-level
+    // process.exit + top-level await — that is P0c/P0d scope, deliberately NOT
+    // touched here. This asserts specifically that the TOKEN-materialization
+    // exit paths (exit(1) on materialize failure / missing token) are gone from
+    // module scope: there is at most the single startup-lock exit, and none of
+    // them sit in a materialize/`new Bot` context (covered by the tests above).
+    let exits = 0
+    walkModuleScope(n => {
+      if (isProcessExitCall(n)) exits++
+    })
+    // The two token-materialization exit(1) sites moved into initGatewayBot;
+    // only the pre-existing startup-lock exit remains at module scope.
+    expect(exits).toBeLessThanOrEqual(1)
+  })
+
+  it('leaves NO module-scope reference to `bot` or `lockedBot` outside their declarations (all consumers deferred)', () => {
+    // Completeness pin: after P0b, the ONLY module-scope occurrences of `bot` /
+    // `lockedBot` are their `let` declarations. Every consumer — the api-tap /
+    // heartbeat wiring, checklist probes, chatLock.wrapBot, the /approvals
+    // registration, the callback-query factory, and registerGatewayHandlers —
+    // must live inside a function (initGatewayBot or a post-boot handler). A
+    // regression that re-hoists any consumer to import scope fails here.
+    const declLines = new Set<number>()
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isVariableStatement(stmt)) continue
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && (decl.name.text === 'bot' || decl.name.text === 'lockedBot')) {
+          declLines.add(sourceFile.getLineAndCharacterOfPosition(decl.name.getStart(sourceFile)).line)
+        }
+      }
+    }
+    const stray: string[] = []
+    walkModuleScope(n => {
+      if (ts.isIdentifier(n) && (n.text === 'bot' || n.text === 'lockedBot')) {
+        const line = sourceFile.getLineAndCharacterOfPosition(n.getStart(sourceFile)).line
+        if (!declLines.has(line)) stray.push(`${n.text}@${line + 1}`)
+      }
+    })
+    expect(stray).toEqual([])
+  })
+
+  it('declares `bot` as a deferred module-scope `let`, not `const bot = new Bot(...)`', () => {
+    let botDecls = 0
+    let botHasInitializer = false
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isVariableStatement(stmt)) continue
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.name.text === 'bot') {
+          botDecls++
+          if (decl.initializer != null) botHasInitializer = true
+          // `let`, not `const`
+          expect(stmt.declarationList.flags & ts.NodeFlags.Const).toBe(0)
+        }
+      }
+    }
+    expect(botDecls).toBe(1)
+    expect(botHasInitializer).toBe(false)
+  })
+
+  it('defines an async initGatewayBot() boot function', () => {
+    const fn = findFunction('initGatewayBot')
+    expect(fn).toBeDefined()
+    const isAsync = (fn!.modifiers ?? []).some(m => m.kind === ts.SyntaxKind.AsyncKeyword)
+    expect(isAsync).toBe(true)
+  })
+
+  it('initGatewayBot() performs the construction: new Bot, token materialization, and the registration wiring call', () => {
+    const fn = findFunction('initGatewayBot')
+    expect(fn?.body).toBeDefined()
+    const body = fn!.body!
+
+    // Exactly one `new Bot(...)` — the single constructed instance.
+    expect(countIn(body, isNewBot)).toBe(1)
+
+    // Token materialization lives here (dynamic import + the resolve call).
+    expect(countIn(body, isMaterializeDynamicImport)).toBe(1)
+    expect(countIn(body, isMaterializeBotTokenCall)).toBe(1)
+
+    // The two P0a-missed import-time bot consumers also moved here (P0b): the
+    // callback-query factory and the /approvals registration.
+    const isNamedCall = (name: string) => (n: ts.Node) =>
+      ts.isCallExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === name
+    expect(countIn(body, isNamedCall('createCallbackQueryHandlers'))).toBe(1)
+    expect(countIn(body, isNamedCall('registerApprovalsCommands'))).toBe(1)
+
+    // The refuse-to-boot exits (process.exit(1)) live here, not at import.
+    expect(countIn(body, isProcessExitCall)).toBeGreaterThanOrEqual(1)
+
+    // The single registerGatewayHandlers(bot, …) wiring call moved here (P0b).
+    let regCalls = 0
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'registerGatewayHandlers'
+      ) {
+        regCalls++
+        expect(node.arguments[0]?.getText(sourceFile)).toBe('bot')
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(body)
+    expect(regCalls).toBe(1)
+  })
+})