switchroom 0.18.31 → 0.18.33

package/telegram-plugin/gateway/checklist-message-handler.ts

@@ -0,0 +1,107 @@
+/**
+ * `checklist_tasks_done` / `checklist_tasks_added` service-message forwarding
+ * (switchroom#2996 P6 cluster F).
+ *
+ * Telegram emits these service messages when users tick or add tasks in a
+ * native checklist. They arrive as part of the `message` update type (no extra
+ * `allowed_updates` config needed). We route them to the agent as a new channel
+ * event with kind="checklist_task_changed" so the agent can react to user
+ * actions on a checklist it sent.
+ *
+ * Extracted verbatim from gateway.ts (Amendment 9 — no module-global reads).
+ * The two `bot.on('message:checklist_tasks_*')` registration lines stay in
+ * gateway.ts (order is a load-bearing invariant) and delegate here.
+ */
+
+import type { Context } from 'grammy'
+import type { InboundMessage } from './ipc-protocol.js'
+
+type ChecklistTaskUpdate = {
+  message_checklist?: {
+    title?: string
+    tasks?: Array<{ id?: number; text?: string; is_completed?: boolean }>
+  }
+  checklist_tasks_done?: Array<{ id?: number; user?: { id?: number; username?: string }; done?: boolean }>
+  checklist_tasks_added?: Array<{ id?: number; text?: string; user?: { id?: number; username?: string } }>
+}
+
+export interface ChecklistHandlerDeps {
+  /** Access config — only `allowFrom` is consulted (same gate as inbound). */
+  loadAccess: () => { allowFrom: string[] }
+  /** Broadcast a channel event to connected bridges. */
+  broadcast: (msg: InboundMessage) => void
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+export function handleChecklistUpdate(
+  ctx: Context,
+  kind: 'checklist_tasks_done' | 'checklist_tasks_added',
+  deps: ChecklistHandlerDeps,
+): void {
+  try {
+    const msg = ctx.message as (typeof ctx.message & ChecklistTaskUpdate) | undefined
+    if (!msg) return
+
+    const chat = ctx.chat
+    if (!chat) return
+
+    const chat_id = String(chat.id)
+    const access = deps.loadAccess()
+
+    // Only notify if this chat is allowlisted — same guard as inbound user messages.
+    // Closes #472 finding #13. Pre-fix the `&& access.allowFrom.length > 0`
+    // tail made this fail-OPEN when the allowlist was empty: every chat's
+    // checklist tasks would forward to the agent. Sibling guards (the
+    // inbound-message gate at line ~588 and the operator-event broadcast
+    // at line ~1221) are both fail-closed for empty allowlists. The
+    // empty-allowlist case is the most likely state for a misconfiguration
+    // (e.g. /unpair just ran), so fail-OPEN is the worst default.
+    if (!access.allowFrom.includes(chat_id)) return
+
+    const message_id = String(msg.message_id)
+    const ts = msg.date ?? Math.floor(Date.now() / 1000)
+
+    // Extract task updates depending on service message type
+    const tasksDone = msg.checklist_tasks_done ?? []
+    const tasksAdded = msg.checklist_tasks_added ?? []
+    const allTasks = kind === 'checklist_tasks_done' ? tasksDone : tasksAdded
+
+    // Build per-task channel events and broadcast each to connected bridges.
+    for (const task of allTasks) {
+      const taskId = task.id != null ? String(task.id) : '?'
+      const user = (task.user as { username?: string; id?: number } | undefined)
+      const userName = user?.username ?? (user?.id != null ? String(user.id) : 'unknown')
+      const state = kind === 'checklist_tasks_done'
+        ? ((task as { done?: boolean }).done === false ? 'undone' : 'done')
+        : 'added'
+
+      const inboundMsg: InboundMessage = {
+        type: 'inbound',
+        chatId: chat_id,
+        messageId: Number(message_id),
+        user: userName,
+        userId: user?.id ?? 0,
+        ts,
+        text: `(checklist task ${state}: id=${taskId})`,
+        meta: {
+          chat_id,
+          message_id,
+          kind: 'checklist_task_changed',
+          task_id: taskId,
+          state,
+          user: userName,
+          user_id: user?.id != null ? String(user.id) : '0',
+          ts: new Date(ts * 1000).toISOString(),
+        },
+      }
+      // allow-broadcast: informational checklist task notification, not turn-driving
+      deps.broadcast(inboundMsg)
+      deps.log(
+        `telegram gateway: checklist ${kind}: chat_id=${chat_id} message_id=${message_id} task_id=${taskId} state=${state} user=${userName}\n`,
+      )
+    }
+  } catch (err) {
+    deps.log(`telegram gateway: checklist handler error (${kind}): ${err}\n`)
+  }
+}

package/telegram-plugin/gateway/delivery-confirm-wiring.ts

@@ -0,0 +1,133 @@
+/**
+ * delivery-confirm-wiring.ts — the deliver-until-acked SWEEP wiring
+ * (#2996 P8 PR-C1).
+ *
+ * Extracted VERBATIM from gateway.ts: the 5 s confirm-sweep tick body
+ * (`runDeliveryConfirmSweep`), the strand re-delivery (`redeliverStrandedInbound`)
+ * and the #2787 Mechanism A card-suspension scoper (`sweepSuspendedTargets`).
+ * The gateway keeps thin same-name wrappers and OWNS the `setInterval`
+ * (the P0c rule — a test import must stay side-effect-free).
+ *
+ * DI contract: state stays in gateway.ts (`deliveryQueue`, the pending-card
+ * maps, `pendingInboundBuffer`); volatile handles cross as getters. The idle
+ * gate deliberately reads `getCurrentTurnNull()` — the turn ATOM, not the
+ * machine's eager in-turn state (the documented trap: `turnInFlightForGate`
+ * stays set through a strand until the TTL tick, so it is NOT a usable idle
+ * signal here). Design §3 PR-C1 risk row; harness case 4 pins mid-turn
+ * suppression.
+ *
+ * `trackDelivery` enrolment callsites stay in gateway.ts unchanged — the two
+ * twin-body sites live inside the P7-owned handleInbound window and are P7's
+ * to delete (design §2 PR-C1 note).
+ */
+import type { InboundMessage } from './ipc-protocol.js'
+import type { DeliveryConfirmWiringDeps } from './gateway.js'
+import {
+  trackDelivery,
+  sweep as sweepDeliveryQueue,
+  forgetDelivery,
+  isRedeliverySuspended,
+  type PendingDelivery,
+} from './inbound-delivery-confirm.js'
+import { chatKey } from './chat-key.js'
+
+export function createDeliveryConfirmWiring(deps: DeliveryConfirmWiringDeps) {
+  const {
+    DELIVERY_CONFIRM_ENABLED,
+    DELIVERY_CONFIRM_TIMEOUT_MS,
+    getCurrentTurnNull,
+    sendToAgent,
+    deliveryQueue,
+    pendingInboundBuffer,
+    pendingPermissions,
+    pendingAskUser,
+  } = deps
+
+// Re-deliver stranded inbounds until claude acks (the marko drop-wedge).
+// Every few seconds, re-send any inbound that was handed to claude but never
+// acked by an `enqueue` — it stranded unsubmitted in the composer. Re-clear
+// the composer so the re-sent notification lands on a clean line, then
+// re-send. Reuses the same delivery primitives; the message is never dropped.
+// (Refs ipcServer / pendingInboundBuffer declared below — resolved at fire
+// time, after module init.) unref so the interval never holds the process.
+async function redeliverStrandedInbound(p: PendingDelivery<InboundMessage>): Promise<void> {
+  const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  process.stderr.write(
+    `telegram gateway: inbound strand (no enqueue ack) key=${p.key} — re-clearing composer + re-delivering\n`,
+  )
+  try {
+    const { clearAgentComposer } = await import('../../src/agents/tmux.js')
+    if (selfAgent) clearAgentComposer({ agentName: selfAgent })
+  } catch { /* best-effort; re-deliver regardless */ }
+  const ok = sendToAgent(selfAgent, p.inbound)
+  if (ok) {
+    // Survive an ack that raced the `await import` above: only `enqueue`
+    // clears tracking, so if a concurrent ack removed the entry, re-affirm
+    // it — never drop. Idempotent.
+    if (!deliveryQueue.pending.has(p.key)) {
+      trackDelivery(deliveryQueue, p.key, p.inbound, Date.now(), p.messageId)
+    }
+  } else {
+    // Bridge offline between attempts — hand off to the offline buffer
+    // (bridgeUp drains it) and stop tracking here; the spool owns it now.
+    pendingInboundBuffer.push(selfAgent, p.inbound)
+    forgetDelivery(deliveryQueue, p.key)
+  }
+}
+// #2787 Mechanism A — which chats/topics currently hold a live permission or
+// ask_user card. A pending card is a live interaction for ITS OWN chat, so the
+// confirm sweep must not re-clear the composer + re-send there. But the OLD guard
+// (`pendingPermissions.size > 0 || pendingAskUser.size > 0 → return`) suspended
+// the sweep GLOBALLY: one card parked in a single topic (or in the operator DM,
+// a different chatId entirely) froze re-delivery of every stranded inbound across
+// EVERY topic until that one card resolved. This scopes the suspension to the
+// card's own target. Returns per-topic chatKeys where the topic is known and bare
+// chatIds where it isn't (a card fanned to operator DMs records chatId only, and
+// a whole-chat suspension is the safe conservative fallback there); the callsite
+// tests a delivery entry against both renderings.
+function sweepSuspendedTargets(): { keys: Set<string>; chats: Set<string> } {
+  const keys = new Set<string>()
+  const chats = new Set<string>()
+  for (const p of pendingPermissions.values()) {
+    for (const c of p.cards) {
+      if (c.threadId != null) keys.add(chatKey(c.chatId, c.threadId))
+      else chats.add(c.chatId)
+    }
+    // A permission whose card send hasn't resolved yet (cards still empty) has
+    // no recorded target — suspend nothing for it; the next sweep sees it once
+    // the send resolves, and the currentTurn guard already covers the in-turn
+    // window a fresh permission request lives in.
+  }
+  for (const a of pendingAskUser.values()) {
+    if (a.threadId != null) keys.add(chatKey(a.chatId, a.threadId))
+    else chats.add(a.chatId)
+  }
+  return { keys, chats }
+}
+
+// #2996 P0c/P8 PR-C1: the sweep TICK body (named in PR-A so the harness can
+// drive it) — the GATEWAY still owns the `setInterval` (the P0c gate rule:
+// modules export the tick body; the gateway registers the timer).
+function runDeliveryConfirmSweep(): void {
+  if (!DELIVERY_CONFIRM_ENABLED) return
+  // Re-deliver ONLY when claude is genuinely idle. `currentTurn` is set solely
+  // by the enqueue session-event and nulled at turn-end, so `currentTurn != null`
+  // means a real turn is in flight — re-clearing the composer + re-sending now
+  // would clobber it (the exact mid-turn wedge this queue exists to prevent).
+  // NB: the machine's in-turn state (turnInFlightForGate) is advanced EAGERLY
+  // at delivery and stays set through a strand until the TTL tick, so it is
+  // NOT a usable "idle" signal here.
+  if (!getCurrentTurnNull()) return
+  // #2787 Mechanism A: a pending permission / ask_user card suspends re-delivery
+  // ONLY for its own chat/topic — never globally. Skip just the stranded entries
+  // whose target holds a live card; sweep the rest so unrelated topics keep
+  // getting re-delivered.
+  const suspended = sweepSuspendedTargets()
+  for (const p of sweepDeliveryQueue(deliveryQueue, Date.now(), DELIVERY_CONFIRM_TIMEOUT_MS)) {
+    if (isRedeliverySuspended(p.key, suspended)) continue
+    void redeliverStrandedInbound(p)
+  }
+}
+
+  return { runDeliveryConfirmSweep, redeliverStrandedInbound, sweepSuspendedTargets }
+}

package/telegram-plugin/gateway/disconnect-flush.ts

@@ -37,17 +37,6 @@ export interface DisconnectFlushDeps<Ctrl extends { finalize: (reason?: 'done' |
   activeReactionMsgIds: Map<string, { chatId: string; messageId: number }>
   /** Mirror map: same keys → turn-start timestamps. */
   activeTurnStartedAt: Map<string, number>
-  /** PR3b: keys claude has actually been handed (delivered, not just
-   *  received). Cleared on disconnect for the same reason as
-   *  activeTurnStartedAt — the bridge just died, every turn it
-   *  was handed is dead by definition. */
-  claudeBusyKeys: Set<string>
-  /** #2787: insertion-timestamp map for `claudeBusyKeys`, backing the orphan
-   *  reaper. MUST stay in lockstep with `claudeBusyKeys` at every clear site —
-   *  a stale timestamp surviving a clear makes a later re-marked key look
-   *  >TTL-old and get reaped against a live delivery. Deleted alongside every
-   *  `claudeBusyKeys.delete`/`.clear` below. */
-  claudeBusyKeySince: Map<string, number>
 
   /** Open draft-stream handles keyed by chat:thread:replyId. */
   activeDraftStreams: Map<string, Stream>
@@ -96,8 +85,6 @@ export function flushOnAgentDisconnect<
     activeStatusReactions,
     activeReactionMsgIds,
     activeTurnStartedAt,
-    claudeBusyKeys,
-    claudeBusyKeySince,
     activeDraftStreams,
     clearActiveReactions,
     disposeProgressDriver,
@@ -125,8 +112,6 @@ export function flushOnAgentDisconnect<
     activeStatusReactions.delete(key)
     activeReactionMsgIds.delete(key)
     activeTurnStartedAt.delete(key)
-    claudeBusyKeys.delete(key)
-    claudeBusyKeySince.delete(key) // #2787: keep orphan-TTL map in lockstep
   }
   clearActiveReactions()
 
@@ -146,8 +131,6 @@ export function flushOnAgentDisconnect<
     for (const k of danglingKeys) {
       activeTurnStartedAt.delete(k)
       activeReactionMsgIds.delete(k)
-      claudeBusyKeys.delete(k)
-      claudeBusyKeySince.delete(k) // #2787: keep orphan-TTL map in lockstep
     }
     log(
       `telegram gateway: disconnect-flush swept ${danglingKeys.length} dangling turn key(s) ` +
@@ -156,33 +139,12 @@ export function flushOnAgentDisconnect<
     onDanglingTurnsSwept?.(danglingKeys)
   }
 
-  // PR3b orphan-sweep (#1880 follow-up): claudeBusyKeys can hold keys
-  // that activeTurnStartedAt does NOT — specifically when a synthetic
-  // inbound (cron via onInjectInbound, reaction dispatch, vault
-  // grant-approved / -denied / save-discarded / -failed / -completed,
-  // button-callback) was delivered. Those paths bypass handleInbound's
-  // fresh-turn branch (which is what would set activeTurnStartedAt),
-  // so the sweep loop above wouldn't notice them. Pre-PR3b this was
-  // invisible because the fleet gate read activeTurnStartedAt.size —
-  // synthetic-only turns never registered. PR3b's claudeBusyKeys.add
-  // is the more-accurate "claude is busy on this" gate, which means
-  // a synthetic-delivered turn that dies WITHOUT turn_end leaves an
-  // orphan that the activeTurnStartedAt-keyed sweep can't see.
-  // Cure: clear any leftover busy keys here. Bridge died → every
-  // busy key is dead by definition. Same justification as the
-  // dangling-sweep above for activeTurnStartedAt.
-  if (claudeBusyKeys.size > 0) {
-    const orphanCount = claudeBusyKeys.size
-    const orphanKeys = [...claudeBusyKeys]
-    claudeBusyKeys.clear()
-    // #2787: keep the orphan-TTL map in lockstep with the set it shadows.
-    for (const k of orphanKeys) claudeBusyKeySince.delete(k)
-    log(
-      `telegram gateway: disconnect-flush cleared ${orphanCount} orphan claudeBusyKeys ` +
-      `entr${orphanCount === 1 ? 'y' : 'ies'} (synthetic-inbound deliveries that never turn_ended)` +
-      ` keys=${orphanKeys.join(',')}`,
-    )
-  }
+  // (#2996 P1) The PR3b `claudeBusyKeys` orphan-sweep that lived here was
+  // deleted with the set itself: the delivery machine's `bridgeDown` event
+  // — emitted by the gateway's onClientDisconnected alongside this flush —
+  // resets the machine to bridge_dead, which structurally clears the
+  // turn-in-flight gate for synthetic-delivered turns that died without a
+  // turn_end (the case the sweep existed for).
 
   // Stop coalesce timers that could emit into a finalized draft stream, but
   // preserve chats with pendingCompletion=true — those have background

package/telegram-plugin/gateway/gateway-import-clean.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+/**
+ * #2996 P0e — gateway.ts import-cleanliness.
+ *
+ * Prior phases (P0a/P0b/P0c) could only pin import-cleanliness with AST/source
+ * checks because importing gateway.ts under vitest was *impossible*: the
+ * module-scope `createIpcServer(...)` calls `Bun.listen` at construction, and
+ * `Bun` is undefined under Node/vitest, so a bare `import('./gateway.js')`
+ * threw `ReferenceError: Bun is not defined` before any assertion could run.
+ *
+ * P0e removes the last import-time side effects. This test therefore uses the
+ * thing prior phases could not: an ACTUAL runtime import of gateway.ts as the
+ * oracle for the import-clean half, and deterministic source-pins for the
+ * boot-fires-under-`isGatewayMain` half (which cannot be runtime-exercised
+ * under vitest — the prod boot path needs Bun, a real Bot token, and the
+ * vault, none of which exist here).
+ */
+
+const here = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_SRC = readFileSync(join(here, 'gateway.ts'), 'utf8')
+
+// The process-signal / lifecycle events gateway.ts wires on the prod boot path.
+// Under a vitest import (isGatewayMain === false) it must register NONE of them.
+const GATEWAY_SIGNALS = ['SIGTERM', 'SIGINT', 'beforeExit'] as const
+
+function signalListenerCounts(): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const sig of GATEWAY_SIGNALS) out[sig] = process.listenerCount(sig)
+  return out
+}
+
+describe('gateway.ts import-cleanliness (#2996 P0e)', () => {
+  it('runtime-imports with zero side effects: resolves, no process.exit, no gateway signal handlers', async () => {
+    const before = signalListenerCounts()
+
+    // Any reachable process.exit during import is a hard failure ("no exit
+    // reachable on import"). Throw instead of exiting so the harness survives
+    // and the assertion is legible.
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(((code?: number) => {
+        throw new Error(`process.exit(${code}) was reached during import()`)
+      }) as never)
+
+    // Positive oracle that no UDS server is bound at import: if the gate
+    // regressed and `createIpcServer` ran, it would call this Bun.listen fake.
+    // With the gate intact it is never invoked. (Also proves the import no
+    // longer depends on a real Bun global — it resolves whether or not one
+    // exists.)
+    //
+    // Dual-runner note: this file runs under BOTH vitest (Node) and `bun test`
+    // (the plugin bun suite globs every *.test.ts). Under Node `globalThis.Bun`
+    // is undefined and the fake installs cleanly — that run holds the no-bind
+    // oracle. Under the Bun runtime the `Bun` global is READONLY (assignment
+    // throws "Attempted to assign to readonly property"), so the swap is
+    // best-effort there; the bind oracle is then carried by the vitest run and
+    // the source pins below, while the remaining outcome assertions (resolve /
+    // no exit / no listeners) still run in both runtimes.
+    const listenSpy = vi.fn(() => {
+      throw new Error('Bun.listen was called during import() — an IPC server was bound')
+    })
+    const priorBun = (globalThis as { Bun?: unknown }).Bun
+    let bunSwapped = false
+    try {
+      ;(globalThis as { Bun?: unknown }).Bun = { listen: listenSpy }
+      bunSwapped = true
+    } catch {
+      // Bun runtime — readonly global; see dual-runner note above.
+    }
+
+    let mod: Record<string, unknown>
+    try {
+      mod = (await import('./gateway.js')) as Record<string, unknown>
+    } finally {
+      if (bunSwapped) {
+        if (priorBun === undefined) delete (globalThis as { Bun?: unknown }).Bun
+        else (globalThis as { Bun?: unknown }).Bun = priorBun
+      }
+      exitSpy.mockRestore()
+    }
+
+    // Import resolved (did not throw). Under P0c-and-earlier this line was
+    // unreachable — the import rejected with `Bun is not defined`.
+    expect(mod).toBeTruthy()
+
+    // No IPC server bound (Node run; under Bun the swap is best-effort and the
+    // spy simply stays uninstalled + uncalled).
+    expect(listenSpy).not.toHaveBeenCalled()
+
+    // No exit reachable on import.
+    expect(exitSpy).not.toHaveBeenCalled()
+
+    // No gateway-owned SIGTERM / SIGINT / beforeExit handlers registered.
+    // (vitest owns a baseline uncaughtException/unhandledRejection listener of
+    // its own, so those two are asserted via the delta only.)
+    const after = signalListenerCounts()
+    for (const sig of GATEWAY_SIGNALS) {
+      // Runner-agnostic single-arg expect (bun's expect has no message arg):
+      // encode the signal name in the compared value so a failure is legible.
+      expect(`${sig}:+${after[sig] - before[sig]}`).toBe(`${sig}:+0`)
+    }
+  }, 60_000)
+
+  it('does not add uncaughtException / unhandledRejection handlers on import', async () => {
+    // Distinct from the signal test: gateway.ts registers TWO families of these
+    // (installGlobalErrorHandlers @ ~910 and its own shutdown-routing handlers
+    // @ ~29926/29935). Both call process.exit, both are gated on P0e. Assert the
+    // delta the import contributed is zero (vitest's own baseline is subtracted).
+    const before = {
+      uncaughtException: process.listenerCount('uncaughtException'),
+      unhandledRejection: process.listenerCount('unhandledRejection'),
+    }
+    const mod = await import('./gateway.js')
+    expect(mod).toBeTruthy()
+    const after = {
+      uncaughtException: process.listenerCount('uncaughtException'),
+      unhandledRejection: process.listenerCount('unhandledRejection'),
+    }
+    expect(after.uncaughtException - before.uncaughtException).toBe(0)
+    expect(after.unhandledRejection - before.unhandledRejection).toBe(0)
+  }, 60_000)
+
+  describe('boot wiring is gated on isGatewayMain (source pins — the prod path still fires)', () => {
+    // These pin, deterministically, that each side-effecting construct remains
+    // (a) gated so the import stays clean, and (b) present so the prod boot path
+    // (isGatewayMain === true) still constructs it. They guard against a future
+    // edit silently ungating one of them (re-inflating the import surface) OR
+    // deleting the construction (breaking boot).
+
+    it('IPC server construction is deferred behind isGatewayMain', () => {
+      expect(GATEWAY_SRC).toMatch(/let ipcServer!: IpcServer/)
+      expect(GATEWAY_SRC).toMatch(/if \(isGatewayMain\) ipcServer = createIpcServer\(\{/)
+      // No ungated `const ipcServer = createIpcServer` remains.
+      expect(GATEWAY_SRC).not.toMatch(/const ipcServer[^\n]*= createIpcServer/)
+    })
+
+    it('inbound spool construction is deferred behind isGatewayMain', () => {
+      expect(GATEWAY_SRC).toMatch(
+        /let inboundSpool: ReturnType<typeof createInboundSpool> \| undefined/,
+      )
+      expect(GATEWAY_SRC).toMatch(/if \(isGatewayMain\) inboundSpool = STATIC/)
+      expect(GATEWAY_SRC).not.toMatch(/const inboundSpool = STATIC/)
+    })
+
+    it('global error handlers + beforeExit are gated on isGatewayMain', () => {
+      // installPosthogErrorHandlers must not sit ungated at module scope.
+      expect(GATEWAY_SRC).not.toMatch(/^installPosthogErrorHandlers\(\)/m)
+      expect(GATEWAY_SRC).toMatch(
+        /if \(isGatewayMain\) \{\n {2}installPosthogErrorHandlers\(\)/,
+      )
+    })
+
+    it('signal + crash handlers are gated on isGatewayMain', () => {
+      // No ungated (column-0) process.on wiring survives.
+      expect(GATEWAY_SRC).not.toMatch(/^process\.on\('SIGTERM'/m)
+      expect(GATEWAY_SRC).not.toMatch(/^process\.on\('SIGINT'/m)
+      expect(GATEWAY_SRC).not.toMatch(/^process\.on\('unhandledRejection'/m)
+      expect(GATEWAY_SRC).not.toMatch(/^process\.on\('uncaughtException'/m)
+      // The gateway's beforeExit analytics flush is likewise not at column 0.
+      expect(GATEWAY_SRC).not.toMatch(/^process\.on\('beforeExit'/m)
+    })
+
+    it('startup reaction sweep (module-load IO) is gated on isGatewayMain', () => {
+      expect(GATEWAY_SRC).toMatch(
+        /if \(isGatewayMain\) \{\n {2}const startupAgentDir = resolveAgentDirFromEnv\(\)/,
+      )
+    })
+
+    it('preserves prod construction order: inboundSpool before pendingInboundBuffer before ipcServer', () => {
+      const iSpool = GATEWAY_SRC.indexOf('if (isGatewayMain) inboundSpool = STATIC')
+      const iPending = GATEWAY_SRC.indexOf('const pendingInboundBuffer = createPendingInboundBuffer(')
+      const iIpc = GATEWAY_SRC.indexOf('if (isGatewayMain) ipcServer = createIpcServer({')
+      expect(iSpool).toBeGreaterThan(0)
+      expect(iPending).toBeGreaterThan(0)
+      expect(iIpc).toBeGreaterThan(0)
+      expect(iSpool).toBeLessThan(iPending)
+      expect(iPending).toBeLessThan(iIpc)
+    })
+
+    it('startGateway() remains the single guarded boot invocation', () => {
+      expect(GATEWAY_SRC).toMatch(/if \(isGatewayMain\) void startGateway\(\)/)
+    })
+  })
+})