switchroom 0.18.11 → 0.18.12

package/telegram-plugin/tests/permission-card-routing.test.ts

@@ -46,6 +46,24 @@ function onPermissionRequestBody(): string {
   return rest.slice(0, end)
 }
 
+/**
+ * Slice the body of `postPermissionCard` — THE card emitter.
+ *
+ * The send used to be inlined in `onPermissionRequest`. The #3084 follow-up
+ * extracted it here so it has two callers (the initial delivery, and the
+ * reaper's re-delivery of a card held through a flood ban). The routing
+ * contract these tests pin is unchanged; it just lives one function over, and
+ * now BOTH delivery paths inherit it — which is the point of the extraction.
+ */
+function postPermissionCardBody(): string {
+  const start = GATEWAY_SRC.indexOf('function postPermissionCard(')
+  expect(start).toBeGreaterThan(-1)
+  const rest = GATEWAY_SRC.slice(start)
+  const end = rest.indexOf('\nfunction ', 1)
+  expect(end).toBeGreaterThan(-1)
+  return rest.slice(0, end)
+}
+
 describe('permission card routing', () => {
   it('the shared target helper exists', () => {
     expect(
@@ -53,19 +71,26 @@ describe('permission card routing', () => {
     ).toBe(true)
   })
 
-  it('the initial card emitter routes via resolvePermissionCardTargets()', () => {
-    expect(onPermissionRequestBody()).toContain('resolvePermissionCardTargets()')
+  it('the card emitter routes via resolvePermissionCardTargets()', () => {
+    expect(postPermissionCardBody()).toContain('resolvePermissionCardTargets()')
   })
 
-  it('the initial card emitter no longer iterates access.allowFrom directly (the bug shape)', () => {
+  it('the card emitter no longer iterates access.allowFrom directly (the bug shape)', () => {
     // The raw fan-out loop is what sent supergroup cards to operator DMs.
-    expect(onPermissionRequestBody()).not.toMatch(
+    expect(postPermissionCardBody()).not.toMatch(
       /for\s*\(\s*const\s+chat_id\s+of\s+access\.allowFrom\s*\)/,
     )
   })
 
   it('the card send is wrapped in retryWithThreadFallback (stale-topic → thread-less, not a silent drop)', () => {
-    expect(onPermissionRequestBody()).toContain('retryWithThreadFallback')
+    expect(postPermissionCardBody()).toContain('retryWithThreadFallback')
+  })
+
+  it('the initial permission request still delivers through that one emitter', () => {
+    // Guards the extraction itself: onPermissionRequest must not regrow its own
+    // send path and drift from the re-delivery path.
+    expect(onPermissionRequestBody()).toContain('postPermissionCard(requestId, pendEntry)')
+    expect(onPermissionRequestBody()).not.toContain('retryWithThreadFallback')
   })
 
   it('the resume message uses the SAME helper, so card + resume cannot drift', () => {

package/telegram-plugin/tests/permission-no-repeat-wiring.test.ts

@@ -45,15 +45,15 @@ describe('no-repeat-on-timeout wiring', () => {
     // when Bug 2 added per-tool TTL + the timed-out keyboard-strip to this
     // block — the signature-record line now sits further down but the wiring
     // is intact.
-    const sweep = slice(GATEWAY, 'for (const [k, v] of pendingPermissions)', 3200)
+    const sweep = slice(GATEWAY, 'sweepPermissionTtl({', 5000)
     expect(sweep).toContain('timeoutDenyMessage(')
     expect(sweep).toContain('permissionTimeoutSignatures.set(')
   })
 
   it('the TTL auto-deny strips the timed-out card keyboard (Bug 2)', () => {
-    const sweep = slice(GATEWAY, 'for (const [k, v] of pendingPermissions)', 3200)
+    const sweep = slice(GATEWAY, 'sweepPermissionTtl({', 5000)
     // Per-tool TTL + keyboard-strip are both wired into the sweep.
-    expect(sweep).toContain('ttlForTool(')
+    expect(sweep).toContain('ttlForTool')
     expect(sweep).toContain('stripTimedOutPermissionCards(')
   })
 
@@ -91,14 +91,15 @@ describe('inbound gate holds while approval card is outstanding (#2841)', () =>
   // first interim reply. Without this, a new inbound delivered in that window
   // displaces the approval context and orphans the pending MCP call.
   it('turnInFlightForGate includes pendingPermissions.size > 0 on the legacy path', () => {
-    // span 1500: the function has a ~800-char comment block before the code lines.
-    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 1500)
+    // span 2600: the function gained a ~1100-char note (#3084 follow-up) documenting
+    // the one case with no timeout valve — a HELD approval.
+    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2600)
     // Both paths (legacy claudeBusyKeys + machine-authoritative) must include the check.
     expect(fn).toMatch(/claudeBusyKeys\.size\s*>\s*0\s*\|\|\s*hasPendingApproval/)
   })
 
   it('turnInFlightForGate includes pendingPermissions.size > 0 on the machine path', () => {
-    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 1600)
+    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2700)
     // probeGateParity(...) || hasPendingApproval — the inner arg contains its own
     // parens (isMachineInTurn()), so match the two tokens independently.
     expect(fn).toContain('probeGateParity(')
@@ -106,7 +107,7 @@ describe('inbound gate holds while approval card is outstanding (#2841)', () =>
   })
 
   it('hasPendingApproval reads pendingPermissions.size', () => {
-    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 1500)
+    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2600)
     expect(fn).toMatch(/pendingPermissions\.size\s*>\s*0/)
   })
 })

package/telegram-plugin/tests/permission-rearm-wiring.test.ts

@@ -163,7 +163,7 @@ describe('gateway boot-sweep grace period', () => {
 
 describe('re-armed pending card re-holds the inbound gate (#2840)', () => {
   it('turnInFlightForGate counts pending approvals', () => {
-    const gate = slice(GATEWAY, 'function turnInFlightForGate()', 1200)
+    const gate = slice(GATEWAY, 'function turnInFlightForGate()', 2400)
     expect(gate).toMatch(/pendingPermissions\.size > 0/)
   })
   it('re-arm restores a pendingPermissions entry → gate held automatically', () => {

package/telegram-plugin/tests/pre-approval-check.test.ts

@@ -0,0 +1,148 @@
+/**
+ * #2975 Stage 2 — gateway-side read-only pre-approval predicate.
+ *
+ * `isDiffPreApproved` is what the gateway answers a hostd `check_pre_approved`
+ * query with. It MUST:
+ *   - return true ONLY for a byte-exact registered (agent, diff) pair
+ *     (mental-model proposal OR "🔁 Always allow" correlation);
+ *   - be forge-resistant: a diff differing by ONE byte from the registered one
+ *     is NOT pre-approved;
+ *   - NEVER mutate the correlation store (the single-use auto-resolve delete
+ *     stays on the real request_config_approval — a peek can't consume consent).
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { createHash } from "node:crypto";
+import {
+  isDiffPreApproved,
+  type PreApprovalCheckDeps,
+} from "../gateway/pre-approval-check.js";
+
+const AGENT = "klanker";
+const MM_DIFF =
+  "--- a/switchroom.yaml\n+++ b/switchroom.yaml\n@@ -1 +1,2 @@\n+  mental_models: [x]\n";
+const ALLOW_RULE = "Bash";
+const ALLOW_DIFF =
+  "--- a/switchroom.yaml\n+++ b/switchroom.yaml\n@@ -1 +1,2 @@\n+      - Bash\n";
+
+function mmKey(agent: string, diff: string): string {
+  return `${agent}::${createHash("sha256").update(diff).digest("hex")}`;
+}
+
+/** A Map-backed store exposing only sweep()+get(), plus spies to prove no
+ *  mutation happened (the ReadonlyCorrelationStore type has no delete/set, so
+ *  a mutating edit wouldn't even typecheck — these spies double-check sweep). */
+function makeStore(entries: Record<string, { unifiedDiff: string }>) {
+  const map = new Map(Object.entries(entries));
+  const sweep = vi.fn((_now: number) => {
+    /* no expiry in these tests */
+  });
+  return {
+    store: {
+      sweep,
+      get: (k: string) => map.get(k),
+    },
+    map,
+    sweep,
+  };
+}
+
+function makeDeps(overrides: {
+  alwaysAllow?: Record<string, { unifiedDiff: string }>;
+  mentalModel?: Record<string, { unifiedDiff: string }>;
+}): {
+  deps: PreApprovalCheckDeps;
+  aaMap: Map<string, { unifiedDiff: string }>;
+  mmMap: Map<string, { unifiedDiff: string }>;
+} {
+  const aa = makeStore(overrides.alwaysAllow ?? {});
+  const mm = makeStore(overrides.mentalModel ?? {});
+  const deps: PreApprovalCheckDeps = {
+    alwaysAllow: aa.store,
+    mentalModel: mm.store,
+    // Only recognise the ALLOW_RULE token when it appears as an added line.
+    extractAddedAllowRule: (diff) =>
+      diff.includes(`+      - ${ALLOW_RULE}`) ? ALLOW_RULE : null,
+    mentalModelCorrelationKey: mmKey,
+  };
+  return { deps, aaMap: aa.map, mmMap: mm.map };
+}
+
+describe("isDiffPreApproved — mental-model correlation", () => {
+  it("true for a byte-exact registered (agent, diff) pair", () => {
+    const { deps } = makeDeps({
+      mentalModel: { [mmKey(AGENT, MM_DIFF)]: { unifiedDiff: MM_DIFF } },
+    });
+    expect(isDiffPreApproved(AGENT, MM_DIFF, deps)).toBe(true);
+  });
+
+  it("false (forge-resistant) for a diff differing by one byte", () => {
+    const { deps } = makeDeps({
+      mentalModel: { [mmKey(AGENT, MM_DIFF)]: { unifiedDiff: MM_DIFF } },
+    });
+    // The key is derived from the tampered diff → no entry at that key; and even
+    // if an attacker could guess the key, the stored unifiedDiff wouldn't match.
+    expect(isDiffPreApproved(AGENT, MM_DIFF + " ", deps)).toBe(false);
+  });
+
+  it("false for a matching diff under a DIFFERENT agent name", () => {
+    const { deps } = makeDeps({
+      mentalModel: { [mmKey(AGENT, MM_DIFF)]: { unifiedDiff: MM_DIFF } },
+    });
+    expect(isDiffPreApproved("someone-else", MM_DIFF, deps)).toBe(false);
+  });
+
+  it("false when nothing is registered", () => {
+    const { deps } = makeDeps({});
+    expect(isDiffPreApproved(AGENT, MM_DIFF, deps)).toBe(false);
+  });
+});
+
+describe("isDiffPreApproved — always-allow correlation", () => {
+  it("true for a byte-exact registered always-allow diff", () => {
+    const { deps } = makeDeps({
+      alwaysAllow: {
+        [`${AGENT}::${ALLOW_RULE}`]: { unifiedDiff: ALLOW_DIFF },
+      },
+    });
+    expect(isDiffPreApproved(AGENT, ALLOW_DIFF, deps)).toBe(true);
+  });
+
+  it("false when the added rule token matches but the diff bytes differ (forge)", () => {
+    const { deps } = makeDeps({
+      alwaysAllow: {
+        [`${AGENT}::${ALLOW_RULE}`]: { unifiedDiff: ALLOW_DIFF },
+      },
+    });
+    // Same rule token, but the diff smuggles an extra byte → byte-match fails.
+    expect(isDiffPreApproved(AGENT, ALLOW_DIFF + "\n", deps)).toBe(false);
+  });
+});
+
+describe("isDiffPreApproved — read-only invariant", () => {
+  it("never mutates either correlation store on a match", () => {
+    const { deps, mmMap } = makeDeps({
+      mentalModel: { [mmKey(AGENT, MM_DIFF)]: { unifiedDiff: MM_DIFF } },
+    });
+    const sizeBefore = mmMap.size;
+    expect(isDiffPreApproved(AGENT, MM_DIFF, deps)).toBe(true);
+    // The matched correlation is STILL present — a peek cannot consume the
+    // single-use consent the real request_config_approval will spend later.
+    expect(mmMap.size).toBe(sizeBefore);
+    expect(mmMap.has(mmKey(AGENT, MM_DIFF))).toBe(true);
+    // A second identical query still answers true (idempotent, no consumption).
+    expect(isDiffPreApproved(AGENT, MM_DIFF, deps)).toBe(true);
+  });
+
+  it("never mutates the store on a miss", () => {
+    const { deps, aaMap, mmMap } = makeDeps({
+      alwaysAllow: {
+        [`${AGENT}::${ALLOW_RULE}`]: { unifiedDiff: ALLOW_DIFF },
+      },
+      mentalModel: { [mmKey(AGENT, MM_DIFF)]: { unifiedDiff: MM_DIFF } },
+    });
+    expect(isDiffPreApproved(AGENT, "totally-unrelated-diff", deps)).toBe(false);
+    expect(aaMap.size).toBe(1);
+    expect(mmMap.size).toBe(1);
+  });
+});

package/telegram-plugin/tests/queued-card-store.test.ts

@@ -0,0 +1,232 @@
+/**
+ * queued-card-store.test.ts — outcome-based tests for the queued-status /
+ * busy-ack card restart-survivability fix (#3002).
+ *
+ * PRE-FIX PROOF: before this change, no persistence existed for the
+ * `queuedStatusMsgIds` Map at all — `../gateway/queued-card-store.js` did not
+ * exist, so `import` itself failed at collection time and every test below
+ * failed on today's (pre-fix) base — there was no seam to test.
+ *
+ * This file exercises the REAL exported store + boot-reaper functions (not a
+ * structural grep), mirroring `activity-card-store.test.ts`'s in-memory fs seam
+ * convention, proving the exact outcome contract:
+ *   (a) card post persists a record;
+ *   (b) in-process reap clears it;
+ *   (c) a boot reaper against a leftover record performs EXACTLY ONE Telegram
+ *       delete and empties the store;
+ *   (d) a second boot performs ZERO deletes;
+ *   (e) a corrupt state file never crashes boot and is dropped without a delete;
+ *   (f) a delete failure never crashes the reaper and still clears the row.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  loadQueuedCards,
+  persistQueuedCards,
+  writeQueuedCardRecord,
+  clearQueuedCardRecord,
+  runQueuedCardBootReaper,
+  type QueuedCardRecord,
+  type QueuedCardStoreFsSeam,
+} from '../gateway/queued-card-store.js'
+
+/** In-memory fs seam with an atomic rename — same convention as
+ *  activity-card-store.test.ts's memFs, so the tmp→rename crash-safety
+ *  contract is exercised without touching real disk. */
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed))
+  const calls: string[] = []
+  const fs: QueuedCardStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`)
+      return files.get(p)!
+    },
+    writeFileSync: (p, d) => {
+      calls.push(`write:${p}`)
+      files.set(p, d)
+    },
+    renameSync: (a, b) => {
+      calls.push(`rename:${a}->${b}`)
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`)
+      files.set(b, files.get(a)!)
+      files.delete(a)
+    },
+    existsSync: (p) => files.has(p),
+  }
+  return { fs, files, calls }
+}
+
+const PATH = '/state/agent/telegram/queued-cards-pending.json'
+
+function card(over: Partial<QueuedCardRecord> = {}): QueuedCardRecord {
+  return {
+    key: '-100123:42',
+    chatId: '-100123',
+    threadId: 42,
+    messageId: 715,
+    ...over,
+  }
+}
+
+describe('queued-card-store — persistence primitives', () => {
+  it('loads [] when no file exists (fresh boot)', () => {
+    const { fs } = memFs()
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('(a) card post → state persisted (round-trips a written record)', () => {
+    const { fs } = memFs()
+    const record = card()
+    writeQueuedCardRecord(PATH, fs, record)
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]).toEqual(record)
+  })
+
+  it('round-trips a DM card (threadId null)', () => {
+    const { fs } = memFs()
+    const record = card({ key: '-100123:', threadId: null })
+    writeQueuedCardRecord(PATH, fs, record)
+    expect(loadQueuedCards(PATH, fs)[0]).toEqual(record)
+  })
+
+  it('a fresh post for the same topic replaces (upserts) the stale row, not appends', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 900 }))
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.messageId).toBe(900)
+  })
+
+  it('keeps rows for distinct keys (different topics) side by side', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:42', messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:43', messageId: 716 }))
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(2)
+  })
+
+  it('(b) in-process reap → state cleared', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card())
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(1)
+    clearQueuedCardRecord(PATH, fs, '-100123:42')
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('clearing an absent/mismatched key is a no-op (never throws)', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:99' }))
+    clearQueuedCardRecord(PATH, fs, '-100123:42')
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(1)
+  })
+
+  it('reap-race guard: clear scoped to messageId leaves a fresh live card intact', () => {
+    const { fs } = memFs()
+    // A live turn posted a NEW card (msg 900) under the same key while a stale
+    // reap tries to clear the OLD one (msg 715) — the new row must survive.
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 900 }))
+    clearQueuedCardRecord(PATH, fs, '-100123:42', 715)
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.messageId).toBe(900)
+  })
+
+  it('writes via tmp + atomic rename (crash-safe)', () => {
+    const { fs, calls } = memFs()
+    persistQueuedCards(PATH, fs, [card()])
+    expect(calls).toEqual([`write:${PATH}.tmp`, `rename:${PATH}.tmp->${PATH}`])
+  })
+
+  it('(e) corrupt state file: boot survives, loads as [] (fail-open, never throws)', () => {
+    const { fs } = memFs({ [PATH]: '{not json' })
+    expect(() => loadQueuedCards(PATH, fs)).not.toThrow()
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('fail-open: wrong envelope version / malformed shape loads as []', () => {
+    const { fs: f1 } = memFs({ [PATH]: JSON.stringify({ v: 2, cards: [card()] }) })
+    expect(loadQueuedCards(PATH, f1)).toEqual([])
+    const { fs: f2 } = memFs({ [PATH]: JSON.stringify({ v: 1, cards: 'nope' }) })
+    expect(loadQueuedCards(PATH, f2)).toEqual([])
+    const { fs: f3 } = memFs({ [PATH]: JSON.stringify({ v: 1, cards: [{ key: '' }] }) })
+    expect(loadQueuedCards(PATH, f3)).toEqual([])
+  })
+})
+
+describe('queued-card-store — boot reaper (reap-on-boot, delete is the terminal)', () => {
+  it('(c) deletes each persisted card EXACTLY ONCE and empties the store', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:42', messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:43', messageId: 716 }))
+    const deletes: number[] = []
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async (r) => {
+        deletes.push(r.messageId)
+        return { message_id: r.messageId }
+      },
+    })
+    expect(res).toEqual({ deleted: 2, total: 2 })
+    expect(deletes.sort()).toEqual([715, 716])
+    // Store is emptied — the stale cards can never be re-reaped.
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('(d) a SECOND boot performs ZERO deletes (store already drained)', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card())
+    await runQueuedCardBootReaper({ path: PATH, fs, deleteCard: async () => ({}) })
+    const deletes: number[] = []
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async (r) => {
+        deletes.push(r.messageId)
+        return {}
+      },
+    })
+    expect(res).toEqual({ deleted: 0, total: 0 })
+    expect(deletes).toEqual([])
+  })
+
+  it('deletes the record BEFORE the delete call (idempotency guard — no double-delete on crash)', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    let storeAtDeleteTime: QueuedCardRecord[] | null = null
+    await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async () => {
+        // At the moment the Telegram delete runs, the row is already gone from
+        // disk — a crash here or a concurrent second boot cannot re-issue it.
+        storeAtDeleteTime = loadQueuedCards(PATH, fs)
+        return {}
+      },
+    })
+    expect(storeAtDeleteTime).toEqual([])
+  })
+
+  it('(f) a delete FAILURE never crashes the reaper and still clears the row (best-effort, tolerate "not found")', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async () => {
+        throw new Error('Bad Request: message to delete not found')
+      },
+      log: () => {},
+    })
+    // Not counted as deleted, but the row is dropped (delete-first) so it can't
+    // wedge every future boot.
+    expect(res).toEqual({ deleted: 0, total: 1 })
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('empty store: reaper is a no-op', async () => {
+    const { fs } = memFs()
+    const res = await runQueuedCardBootReaper({ path: PATH, fs, deleteCard: async () => ({}) })
+    expect(res).toEqual({ deleted: 0, total: 0 })
+  })
+})

package/telegram-plugin/tests/reaction-flush-turn-gated.test.ts

@@ -0,0 +1,100 @@
+/**
+ * #2094 finding 3 — reaction-flush uses the #1556 turn gate.
+ *
+ * THE BUG: flushReactionBatch delivered its synthetic reaction inbound with a
+ * bare `ipcServer.sendToAgent` + busy-mark, buffering ONLY on a bridge-offline
+ * miss. It never ran the #1556 decideInboundDelivery gate. So a reaction that
+ * landed WHILE a turn was in flight fired the MCP channel notification mid-turn
+ * — the unmodified CLI typed it into its TUI composer and the auto-submit raced
+ * turn-completion, re-creating the composer wedge.
+ *
+ * THE FIX: route the flush through deliverResumeSyntheticOrBuffer, the shared
+ * helper that consults the gate (mid-turn → buffer-until-idle, flushed by the
+ * turn-complete hook + idle-drain timer; idle → deliver now; buffer only on a
+ * genuine miss).
+ *
+ * gateway.ts is a large side-effecting module that can't be imported into a
+ * unit test, so this file pins (a) the gate decision for a reaction inbound's
+ * shape via the pure gate + a modeled buffer/drain, and (b) that
+ * flushReactionBatch wires the turn-safe helper structurally — the same
+ * strategy button-tap-turn-gated.test.ts uses.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decideInboundDelivery } from '../gateway/inbound-delivery-gate.js'
+import { planBufferedRedelivery } from '../gateway/pending-inbound-buffer.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+// A reaction inbound as flushReactionBatch builds it: synthetic messageId (ts),
+// never steering, never an interrupt — the exact inputs the shared helper
+// (deliverResumeSyntheticOrBuffer) passes to the gate.
+function reactionInbound(ts: number): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'c1',
+    messageId: ts,
+    user: 'u',
+    userId: 42,
+    ts,
+    text: `[user reacted 👍 to your message]`,
+    meta: { chat_id: 'c1', count: '1' },
+  }
+}
+
+describe('reaction flush uses the turn-gate (mid-turn → buffer)', () => {
+  it('buffers a reaction that lands mid-turn, delivers when idle, never mid-turn', () => {
+    const shape = { isSteering: false as const, isInterrupt: false as const }
+    // Reaction lands WHILE a turn is in flight → HELD, not sent (the wedge the
+    // raw sendToAgent used to cause).
+    expect(decideInboundDelivery({ ...shape, turnInFlight: true })).toBe(
+      'buffer-until-idle',
+    )
+    // Reaction lands at an idle prompt → delivered immediately.
+    expect(decideInboundDelivery({ ...shape, turnInFlight: false })).toBe(
+      'deliver',
+    )
+  })
+
+  it('a mid-turn-buffered reaction drains as a fresh turn after turn end', () => {
+    // Model the buffer→drain: the reaction was held mid-turn; on turn-complete
+    // the buffer is planned for redelivery and the reaction lands cleanly as
+    // its own turn (never merged away / dropped).
+    const plan = planBufferedRedelivery([reactionInbound(1000)])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.text).toBe('[user reacted 👍 to your message]')
+  })
+})
+
+describe('flushReactionBatch wires the turn-safe helper', () => {
+  const start = gatewaySrc.indexOf('function flushReactionBatch(batch: ReactionBatch)')
+  // Bound the body by the next top-level declaration (the message_reaction
+  // handler block).
+  const body = gatewaySrc.slice(
+    start,
+    gatewaySrc.indexOf("bot.on('message_reaction'", start),
+  )
+
+  it('exists', () => {
+    expect(start, 'flushReactionBatch missing').toBeGreaterThan(0)
+  })
+
+  it('delivers via deliverResumeSyntheticOrBuffer, not a raw ungated sendToAgent', () => {
+    expect(body).toMatch(/deliverResumeSyntheticOrBuffer\(agentName, inbound\)/)
+    // The regressed path — a raw ungated send of the reaction inbound + an
+    // out-of-helper busy-mark — is gone.
+    expect(body).not.toMatch(/ipcServer\.sendToAgent\(agentName, inbound\)/)
+    expect(body).not.toMatch(/markClaudeBusyForInbound\(inbound\)/)
+  })
+
+  it('no longer open-codes the buffer-on-failure push (the helper owns it)', () => {
+    // The #1150 buffer-on-failure guarantee now lives inside
+    // deliverResumeSyntheticOrBuffer, so the flush body must not push directly.
+    expect(body).not.toMatch(/pendingInboundBuffer\.push\(/)
+  })
+})