switchroom 0.18.8 → 0.18.9

package/telegram-plugin/tests/inbound-delivery-dispatch-equivalence.test.ts

@@ -0,0 +1,348 @@
+/**
+ * Machine→dispatcher coverage + self-consistency harness for the
+ * inbound-delivery state-machine cutover (#2794 / #2996 Phase 1).
+ *
+ * SCOPE — what this file proves, and what it deliberately does NOT:
+ *
+ * It drives realistic event schedules (the same shapes the gateway's
+ * `shadowEmit` call sites feed the machine — bridge flap, fresh turn,
+ * mid-turn buffering, steering, turn-end drain, permission verdicts
+ * across a bridge outage, stale-turn fallback) through the PURE
+ * `transition()` function, collects the returned effect sequence, then
+ * replays that sequence through the REAL `dispatchEffects()` against a
+ * recording fake-deps object. It asserts:
+ *
+ *   1. Every effect kind the machine can emit is handled by the
+ *      dispatcher (no silent no-op, no `unwired`/`not-yet-cutover` gap).
+ *   2. The observable side-effects fire in the machine's returned order.
+ *   3. Invariant #1 at the dispatch layer: an inbound is delivered XOR
+ *      (buffered AND persisted) — never both, never neither.
+ *
+ * It does NOT invoke the imperative twins (`markClaudeBusyForInbound`,
+ * the legacy `turnInFlightForGate` claudeBusyKeys branch,
+ * `dispatchPermissionVerdict`, the silence-poke ladder), so it is NOT a
+ * proof that machine path and imperative path produce identical I/O.
+ * Twin-equivalence evidence for PR4 (twin deletion) must come from the
+ * live shadow trace + gate-parity-probe bake per the RFC's cutover
+ * protocol — do NOT cite this file as that proof.
+ *
+ * What it DOES gate: if a future edit adds an effect kind the
+ * dispatcher doesn't execute, the "no unhandled effect" assertion fails
+ * loudly — keeping PR3c's live call-site flip a one-liner.
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  transition,
+  initialState,
+  type Effect,
+  type Event,
+  type State,
+  type ChatKey,
+  type InboundMessage as MachineInbound,
+} from '../gateway/inbound-delivery-machine'
+import {
+  dispatchEffects,
+  type DispatchCtx,
+} from '../gateway/inbound-delivery-machine-dispatch'
+import { createPendingInboundBuffer } from '../gateway/pending-inbound-buffer'
+import { createPendingPermissionBuffer } from '../gateway/pending-permission-decisions'
+
+// ── Recording fake deps ──────────────────────────────────────────────
+// Records every observable dispatcher action in call order so the test
+// can assert the effect→I/O mapping and its ordering.
+
+interface Recorder {
+  ctx: DispatchCtx
+  ops: string[]
+}
+
+function makeRecorder(): Recorder {
+  const ops: string[] = []
+  const inbound = createPendingInboundBuffer()
+  const perm = createPendingPermissionBuffer()
+  const client = {
+    id: 'c1',
+    agentName: 'test-agent',
+    send: (m: unknown) => {
+      const msg = m as { type?: string; id?: string; requestId?: string }
+      if (msg.type === 'permission_decision') ops.push(`send:perm:${msg.requestId}`)
+      else ops.push(`send:inbound:${msg.id}`)
+    },
+  }
+  const spoolPuts: string[] = []
+  const ctx: DispatchCtx = {
+    selfAgent: 'test-agent',
+    ipcServer: { sendToAgent: () => true } as never,
+    pendingInboundBuffer: inbound,
+    inboundSpool: {
+      put: (_agent: string, m: { id?: string }) => {
+        spoolPuts.push(m.id ?? '?')
+        ops.push(`persist:${m.id}`)
+        return true
+      },
+      ack: () => {},
+      liveEntries: () => [],
+    } as never,
+    pendingPermissionBuffer: perm,
+    client: client as never,
+    log: () => {},
+    onUserInboundDelivered: (m) => ops.push(`enrol:${(m as { id?: string }).id}`),
+    onSetTurnStarted: (key, at) => ops.push(`setTurn:${key}:${at}`),
+    onClearTurnStarted: (key) => ops.push(`clearTurn:${key}`),
+    onNoteOutbound: (key) => ops.push(`noteOutbound:${key}`),
+    onFirePoke: (key, level) => ops.push(`poke:${key}:${level}`),
+  }
+  // bufferInbound goes through the real buffer; record via a wrapper.
+  const origPush = inbound.push.bind(inbound)
+  ;(inbound as { push: typeof inbound.push }).push = (agent, m) => {
+    ops.push(`buffer:${(m as { id?: string }).id}`)
+    return origPush(agent, m)
+  }
+  return { ctx, ops }
+}
+
+// A logging deps object that records the raw effect kinds a dispatch
+// pass would execute, so we can assert "no unhandled effect kind".
+function makeEffectKindProbe(): { ctx: DispatchCtx; seen: string[] } {
+  const seen: string[] = []
+  const ctx: DispatchCtx = {
+    selfAgent: 'test-agent',
+    ipcServer: { sendToAgent: () => true } as never,
+    pendingInboundBuffer: createPendingInboundBuffer(),
+    inboundSpool: { put: () => true, ack: () => {}, liveEntries: () => [] } as never,
+    pendingPermissionBuffer: createPendingPermissionBuffer(),
+    client: { id: 'c1', agentName: 'test-agent', send: () => {} } as never,
+    log: (line: string) => {
+      // The dispatcher must NEVER leave an effect unhandled. Two gap
+      // markers exist in the code; both are failures for a live cutover.
+      if (line.includes('not-yet-cutover') || line.includes('unwired')) {
+        seen.push(`GAP:${line.trim()}`)
+      }
+    },
+    onSetTurnStarted: () => {},
+    onClearTurnStarted: () => {},
+    onNoteOutbound: () => {},
+    onFirePoke: () => {},
+  }
+  return { ctx, seen }
+}
+
+// ── Event-schedule fixtures (mirror gateway shadowEmit call sites) ────
+
+const K = (chat: string, thread?: string): ChatKey => `${chat}:${thread ?? '_'}` as ChatKey
+const inMsg = (id: number, steer = false): MachineInbound => ({
+  msgId: id,
+  isSteering: steer,
+  payload: { type: 'inbound', id: `m${id}`, chat_id: '1', text: `t${id}`, meta: { source: 'telegram' } },
+})
+// Real user inbound — NO meta.source. This is the primary live case:
+// shouldTrackDelivery (inbound-delivery-confirm.ts) only tracks
+// no-source messages, so fixtures that all carry a source would mask a
+// broken enrolment guard (the exact HIGH found in review of PR #3006).
+const userMsg = (id: number): MachineInbound => ({
+  msgId: id,
+  isSteering: false,
+  payload: { type: 'inbound', id: `m${id}`, chat_id: '1', text: `t${id}`, meta: {} },
+})
+const verdict = (r: string) => ({
+  requestId: r,
+  behavior: 'allow' as const,
+  payload: { type: 'permission_decision', requestId: r, behavior: 'allow', updatedInput: {}, timestamp: 0 },
+})
+
+/** Named schedules that exercise every transition branch. */
+const SCHEDULES: Record<string, Event[]> = {
+  fresh_turn_then_end: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 },
+    { kind: 'turnEnd', key: K('1'), at: 20, outboundEmitted: true },
+  ],
+  mid_turn_buffer: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(2), at: 15 }, // buffered
+    { kind: 'turnEnd', key: K('1'), at: 20, outboundEmitted: true },
+  ],
+  steering_mid_turn: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(2, true), at: 15 }, // steer → deliver
+  ],
+  bridge_dead_buffer_then_recover: [
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 }, // bridge dead → buffer+persist
+    { kind: 'bridgeUp', at: 20 }, // drain
+  ],
+  perm_verdict_alive: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'permVerdict', verdict: verdict('rA'), at: 5 },
+  ],
+  perm_verdict_dead_then_recover: [
+    { kind: 'permVerdict', verdict: verdict('rB'), at: 5 }, // dead → persist
+    { kind: 'bridgeUp', at: 10 }, // redeliver
+  ],
+  stale_turn_fallback: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 },
+    { kind: 'tick', now: 10 + 300_001 }, // past TURN_TTL, no outbound → firePoke
+  ],
+  fresh_turn_user_no_source: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: userMsg(1), at: 10 }, // real user inbound, no meta.source
+  ],
+  overlapping_turn_no_spurious_fallback: [
+    { kind: 'bridgeUp', at: 0 },
+    { kind: 'inbound', key: K('1'), msg: inMsg(1), at: 10 },
+    { kind: 'modelOutbound', key: K('1'), at: 10 + 300_000 }, // recent outbound
+    { kind: 'tick', now: 10 + 300_001 }, // suppressed by invariant #5
+  ],
+}
+
+// Run a schedule through the machine, returning the concatenated effect
+// stream in machine order.
+function runMachine(events: Event[]): { effects: Effect[]; finalState: State } {
+  let state = initialState()
+  const effects: Effect[] = []
+  for (const ev of events) {
+    const r = transition(state, ev)
+    state = r.state
+    effects.push(...r.effects)
+  }
+  return { effects, finalState: state }
+}
+
+describe('dispatch-equivalence: machine effects → dispatcher I/O', () => {
+  for (const [name, events] of Object.entries(SCHEDULES)) {
+    it(`'${name}': every emitted effect is handled by the dispatcher (no gap)`, () => {
+      const { effects } = runMachine(events)
+      const { ctx, seen } = makeEffectKindProbe()
+      dispatchEffects(effects, ctx)
+      expect(seen).toEqual([]) // no not-yet-cutover / unwired markers
+    })
+  }
+
+  it('fresh_turn_then_end replays in machine order: setTurn → send → noteOutbound/clearTurn', () => {
+    const { effects } = runMachine(SCHEDULES.fresh_turn_then_end)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    // setTurnStarted precedes the deliver (downstream observer must see
+    // the turn marker up first), and turn-end clears + notes outbound.
+    expect(ops[0]).toBe('setTurn:1:_:10')
+    expect(ops[1]).toBe('send:inbound:m1')
+    expect(ops).toContain('clearTurn:1:_')
+    expect(ops).toContain('noteOutbound:1:_')
+    expect(ops.indexOf('setTurn:1:_:10')).toBeLessThan(ops.indexOf('send:inbound:m1'))
+  })
+
+  it('mid_turn_buffer: the second inbound is buffered+persisted, never delivered', () => {
+    const { effects } = runMachine(SCHEDULES.mid_turn_buffer)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    // m1 delivered (fresh turn), m2 buffered+persisted (mid-turn).
+    expect(ops).toContain('send:inbound:m1')
+    expect(ops).toContain('buffer:m2')
+    expect(ops).toContain('persist:m2')
+    // Invariant #1 at the dispatch layer: buffer implies persist, same msg.
+    expect(ops.filter((o) => o === 'buffer:m2')).toHaveLength(1)
+    expect(ops.filter((o) => o === 'persist:m2')).toHaveLength(1)
+    // m2 is NOT delivered at receipt-time; if it is redelivered at all
+    // it happens via the turn-end drainBuffer, i.e. strictly AFTER the
+    // turn was cleared — never as an in-turn delivery.
+    const m2SendIdx = ops.indexOf('send:inbound:m2')
+    if (m2SendIdx !== -1) {
+      expect(m2SendIdx).toBeGreaterThan(ops.indexOf('clearTurn:1:_'))
+    }
+    expect(ops.indexOf('buffer:m2')).toBeLessThan(ops.indexOf('clearTurn:1:_'))
+  })
+
+  it('steering_mid_turn: a steer message is delivered mid-turn, not buffered', () => {
+    const { effects } = runMachine(SCHEDULES.steering_mid_turn)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    expect(ops).toContain('send:inbound:m1')
+    expect(ops).toContain('send:inbound:m2')
+    expect(ops).not.toContain('buffer:m2')
+  })
+
+  it('bridge_dead_buffer_then_recover: buffer+persist while dead, drain on recover', () => {
+    const { effects } = runMachine(SCHEDULES.bridge_dead_buffer_then_recover)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    // Buffered+persisted while dead; the drainBuffer effect at bridgeUp
+    // redelivers from the buffer → the recorded buffer push then a send.
+    expect(ops).toContain('buffer:m1')
+    expect(ops).toContain('persist:m1')
+    expect(ops).toContain('send:inbound:m1') // redelivered by drainBuffer
+  })
+
+  it('perm_verdict_alive: verdict delivered straight to the bridge', () => {
+    const { effects } = runMachine(SCHEDULES.perm_verdict_alive)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    expect(ops).toContain('send:perm:rA')
+  })
+
+  it('perm_verdict_dead_then_recover: persisted while dead, redelivered on bridgeUp', () => {
+    const { effects } = runMachine(SCHEDULES.perm_verdict_dead_then_recover)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    // Persisted while dead (no direct send at persist time), then the
+    // redeliverPersistedPermVerdicts effect at bridgeUp sends it.
+    expect(ops).toContain('send:perm:rB')
+  })
+
+  it('stale_turn_fallback: fires the fallback poke + clears the turn', () => {
+    const { effects } = runMachine(SCHEDULES.stale_turn_fallback)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    expect(ops).toContain('poke:1:_:fallback')
+    expect(ops).toContain('clearTurn:1:_')
+  })
+
+  it('fresh_turn_user_no_source: a real user inbound (no meta.source) is delivered AND enrolled in the deliver-until-acked sweep', () => {
+    const { effects } = runMachine(SCHEDULES.fresh_turn_user_no_source)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    expect(ops).toContain('send:inbound:m1')
+    // The enrolment callback MUST fire for no-source user inbounds —
+    // shouldTrackDelivery inside the gateway callback is the gate, not
+    // a dispatcher-side meta.source pre-filter (review HIGH, PR #3006).
+    expect(ops).toContain('enrol:m1')
+  })
+
+  it('overlapping_turn_no_spurious_fallback: recent outbound suppresses the poke', () => {
+    const { effects } = runMachine(SCHEDULES.overlapping_turn_no_spurious_fallback)
+    const { ctx, ops } = makeRecorder()
+    dispatchEffects(effects, ctx)
+    // Invariant #5: the model broke silence within OUTBOUND_RECENT_MS,
+    // so NO fallback poke fires.
+    expect(ops.some((o) => o.startsWith('poke:'))).toBe(false)
+  })
+})
+
+describe('dispatch-equivalence: effect-kind coverage', () => {
+  it('the union of all schedule effects covers every machine effect kind that maps to I/O', () => {
+    const allKinds = new Set<string>()
+    for (const events of Object.values(SCHEDULES)) {
+      for (const e of runMachine(events).effects) allKinds.add(e.kind)
+    }
+    // Every kind produced by the fixtures must be one the dispatcher
+    // executes. logTrace is pure telemetry; the rest are I/O.
+    const expected = [
+      'deliverToBridge',
+      'bufferInbound',
+      'persistInbound',
+      'drainBuffer',
+      'setTurnStarted',
+      'clearTurnStarted',
+      'noteOutbound',
+      'firePoke',
+      'deliverPermVerdict',
+      'persistPermVerdict',
+      'redeliverPersistedPermVerdicts',
+    ]
+    for (const kind of expected) {
+      expect(allKinds.has(kind)).toBe(true)
+    }
+  })
+})

package/telegram-plugin/tests/inbound-delivery-machine-dispatch.test.ts

@@ -22,7 +22,7 @@ import {
 import type { DispatchCtx } from '../gateway/inbound-delivery-machine-dispatch'
 import { createPendingInboundBuffer } from '../gateway/pending-inbound-buffer'
 import { createPendingPermissionBuffer } from '../gateway/pending-permission-decisions'
-import type { Effect } from '../gateway/inbound-delivery-machine'
+import { createInboundSpool } from '../gateway/inbound-spool'
 
 function makeCtx(overrides?: Partial<DispatchCtx>): {
   ctx: DispatchCtx
@@ -184,57 +184,146 @@ describe('dispatchEffects — kill switch', () => {
   })
 })
 
-describe('dispatchOne — not-yet-cutover effects log without throwing', () => {
-  const notYet: Effect['kind'][] = [
-    'deliverToBridge',
-    'bufferInbound',
-    'persistInbound',
-    'setTurnStarted',
-    'clearTurnStarted',
-    'noteOutbound',
-    'firePoke',
-    'deliverPermVerdict',
-    'persistPermVerdict',
-  ]
-
-  for (const kind of notYet) {
-    it(`'${kind}' logs not-yet-cutover and does NOT touch primitives`, () => {
-      const { ctx, sendToAgent, clientSend, logs } = makeCtx()
-      // Construct a minimal valid effect for each kind. Most carry a
-      // payload that the dispatcher ignores in this PR.
-      const effect = synthesizeNotYetCutoverEffect(kind)
-      expect(() => __dispatchOneForTests(effect, ctx)).not.toThrow()
-      expect(sendToAgent).not.toHaveBeenCalled()
-      expect(clientSend).not.toHaveBeenCalled()
-      expect(logs.some((l) => l.includes(`not-yet-cutover effect=${kind}`))).toBe(true)
-    })
-  }
+describe('dispatchEffects — inbound-routing effects (PR3c wiring)', () => {
+  const k = 'c1:_' as never
+  const ipcMsg = { type: 'inbound' as const, id: 'm1', chat_id: '1', text: 'hi', meta: { source: 'telegram' } }
+
+  it('deliverToBridge sends the payload to the client', () => {
+    const { ctx, clientSend } = makeCtx()
+    __dispatchOneForTests({ kind: 'deliverToBridge', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx)
+    expect(clientSend).toHaveBeenCalledTimes(1)
+    expect(clientSend).toHaveBeenCalledWith(ipcMsg)
+  })
+
+  it('deliverToBridge falls back to ipcServer.sendToAgent with no client', () => {
+    const { ctx, sendToAgent } = makeCtx({ client: undefined })
+    __dispatchOneForTests({ kind: 'deliverToBridge', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx)
+    expect(sendToAgent).toHaveBeenCalledWith('test-agent', ipcMsg)
+  })
+
+  it('deliverToBridge enrols in the deliver-until-acked sweep', () => {
+    const onUserInboundDelivered = vi.fn()
+    const { ctx } = makeCtx({ onUserInboundDelivered })
+    __dispatchOneForTests({ kind: 'deliverToBridge', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx)
+    expect(onUserInboundDelivered).toHaveBeenCalledWith(ipcMsg)
+  })
+
+  it('deliverToBridge DOES pass the enrolment callback for a real user inbound (NO meta.source)', () => {
+    // The primary live case: real user messages carry NO meta.source,
+    // and they are exactly the messages shouldTrackDelivery tracks. A
+    // dispatcher-side pre-filter on meta.source would skip them (the
+    // review HIGH on PR #3006) — the callback must fire unconditionally
+    // and self-gate inside the gateway.
+    const noSourceMsg = { type: 'inbound' as const, id: 'u1', chat_id: '1', text: 'hi', meta: {} }
+    const onUserInboundDelivered = vi.fn()
+    const { ctx, clientSend } = makeCtx({ onUserInboundDelivered })
+    __dispatchOneForTests({ kind: 'deliverToBridge', key: k, msg: { msgId: 2, isSteering: false, payload: noSourceMsg } }, ctx)
+    expect(clientSend).toHaveBeenCalledWith(noSourceMsg)
+    expect(onUserInboundDelivered).toHaveBeenCalledWith(noSourceMsg)
+  })
+
+  it('bufferInbound pushes onto the pending inbound buffer', () => {
+    const { ctx, inbound, clientSend } = makeCtx()
+    __dispatchOneForTests({ kind: 'bufferInbound', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx)
+    expect(inbound.depth('test-agent')).toBe(1)
+    expect(clientSend).not.toHaveBeenCalled()
+  })
+
+  it('persistInbound puts to the spool when one is attached', () => {
+    const put = vi.fn(() => true)
+    const { ctx } = makeCtx({ inboundSpool: { put } as never })
+    __dispatchOneForTests({ kind: 'persistInbound', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx)
+    expect(put).toHaveBeenCalledWith('test-agent', ipcMsg)
+  })
+
+  it('persistInbound is a safe no-op when no spool is attached', () => {
+    const { ctx } = makeCtx({ inboundSpool: null })
+    expect(() =>
+      __dispatchOneForTests({ kind: 'persistInbound', key: k, msg: { msgId: 1, isSteering: false, payload: ipcMsg } }, ctx),
+    ).not.toThrow()
+  })
+
+  it('bufferInbound + persistInbound with a spool attached to the buffer does NOT double-spool (idempotent by spoolId)', () => {
+    // The machine emits bufferInbound AND persistInbound as a pair for a
+    // mid-turn / bridge-dead inbound. When the ctx's buffer is
+    // constructed with the SAME durable spool (the production wiring),
+    // buffer.push already spools — so the paired persistInbound's
+    // spool.put must dedupe by spoolId, leaving exactly ONE live entry.
+    const spoolPath = '/state/agent/telegram/inbound-spool.jsonl'
+    const files = new Map<string, string>()
+    const fs = {
+      appendFileSync: (p: string, d: string) => files.set(p, (files.get(p) ?? '') + d),
+      readFileSync: (p: string) => files.get(p) ?? '',
+      writeFileSync: (p: string, d: string) => files.set(p, d),
+      renameSync: (from: string, to: string) => {
+        files.set(to, files.get(from) ?? '')
+        files.delete(from)
+      },
+      existsSync: (p: string) => files.has(p),
+      statSizeSync: (p: string) => Buffer.byteLength(files.get(p) ?? ''),
+    }
+    const spool = createInboundSpool({ path: spoolPath, fs, log: () => {} })
+    const buffer = createPendingInboundBuffer({ spool, log: () => {} })
+    const { ctx } = makeCtx({ pendingInboundBuffer: buffer, inboundSpool: spool })
+    // Spool-identifiable message shape (spoolId reads chatId/messageId).
+    const durableMsg = {
+      type: 'inbound' as const,
+      chatId: 'c1',
+      messageId: 77,
+      user: 'u',
+      userId: 1,
+      ts: 1000,
+      text: 'hold me',
+      meta: {},
+    }
+    __dispatchOneForTests({ kind: 'bufferInbound', key: k, msg: { msgId: 77, isSteering: false, payload: durableMsg } }, ctx)
+    __dispatchOneForTests({ kind: 'persistInbound', key: k, msg: { msgId: 77, isSteering: false, payload: durableMsg } }, ctx)
+    expect(buffer.depth('test-agent')).toBe(1)
+    expect(spool.liveCount()).toBe(1) // no double-spool
+  })
+})
+
+describe('dispatchEffects — perm-verdict effects', () => {
+  const permEv = { type: 'permission_decision' as const, requestId: 'r1', behavior: 'allow' as const, updatedInput: {}, timestamp: 0 }
+
+  it('deliverPermVerdict sends the payload to the client', () => {
+    const { ctx, clientSend } = makeCtx()
+    __dispatchOneForTests({ kind: 'deliverPermVerdict', verdict: { requestId: 'r1', behavior: 'allow', payload: permEv } }, ctx)
+    expect(clientSend).toHaveBeenCalledWith(permEv)
+  })
+
+  it('persistPermVerdict pushes onto the pending permission buffer', () => {
+    const { ctx, perm, clientSend } = makeCtx()
+    __dispatchOneForTests({ kind: 'persistPermVerdict', verdict: { requestId: 'r1', behavior: 'allow', payload: permEv } }, ctx)
+    expect(clientSend).not.toHaveBeenCalled()
+    expect(perm.drain('test-agent')).toEqual([permEv])
+  })
 })
 
-function synthesizeNotYetCutoverEffect(kind: Effect['kind']): Effect {
+describe('dispatchEffects — turn/poke callbacks', () => {
   const k = 'c1:_' as never
-  const msg = { msgId: 1, isSteering: false, payload: null } as never
-  const verdict = { requestId: 'r', behavior: 'allow' as const, payload: null } as never
-  switch (kind) {
-    case 'deliverToBridge':
-      return { kind, key: k, msg }
-    case 'bufferInbound':
-      return { kind, key: k, msg }
-    case 'persistInbound':
-      return { kind, key: k, msg }
-    case 'setTurnStarted':
-      return { kind, key: k, at: 0 }
-    case 'clearTurnStarted':
-      return { kind, key: k }
-    case 'noteOutbound':
-      return { kind, key: k, at: 0 }
-    case 'firePoke':
-      return { kind, key: k, level: 'fallback' }
-    case 'deliverPermVerdict':
-      return { kind, verdict }
-    case 'persistPermVerdict':
-      return { kind, verdict }
-    default:
-      throw new Error(`unreachable: ${kind}`)
-  }
-}
+
+  it('setTurnStarted / clearTurnStarted / noteOutbound / firePoke fire their callbacks', () => {
+    const onSetTurnStarted = vi.fn()
+    const onClearTurnStarted = vi.fn()
+    const onNoteOutbound = vi.fn()
+    const onFirePoke = vi.fn()
+    const { ctx } = makeCtx({ onSetTurnStarted, onClearTurnStarted, onNoteOutbound, onFirePoke })
+    __dispatchOneForTests({ kind: 'setTurnStarted', key: k, at: 7 }, ctx)
+    __dispatchOneForTests({ kind: 'clearTurnStarted', key: k }, ctx)
+    __dispatchOneForTests({ kind: 'noteOutbound', key: k, at: 9 }, ctx)
+    __dispatchOneForTests({ kind: 'firePoke', key: k, level: 'fallback' }, ctx)
+    expect(onSetTurnStarted).toHaveBeenCalledWith(k, 7)
+    expect(onClearTurnStarted).toHaveBeenCalledWith(k)
+    expect(onNoteOutbound).toHaveBeenCalledWith(k, 9)
+    expect(onFirePoke).toHaveBeenCalledWith(k, 'fallback')
+  })
+
+  it('logs an `unwired` trace (never silently no-ops) when a callback is absent', () => {
+    const { ctx, logs } = makeCtx()
+    __dispatchOneForTests({ kind: 'setTurnStarted', key: k, at: 0 }, ctx)
+    __dispatchOneForTests({ kind: 'firePoke', key: k, level: 'soft' }, ctx)
+    expect(logs.some((l) => l.includes('unwired effect=setTurnStarted'))).toBe(true)
+    expect(logs.some((l) => l.includes('unwired effect=firePoke'))).toBe(true)
+  })
+})

package/telegram-plugin/tests/mental-model-propose-callback-gate.test.ts

@@ -19,7 +19,14 @@ import { describe, expect, it } from 'vitest'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-const gatewaySrc = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), '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.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
+  '\n' +
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
 
 function proposeCallbackBlock(): string {
   return (