switchroom 0.12.18 → 0.12.19

package/telegram-plugin/tests/inbound-delivery-gate.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { decideInboundDelivery } from '../gateway/inbound-delivery-gate.js'
+
+/**
+ * Regression coverage for #1556 — the lawgpt composer wedge.
+ *
+ * Before this gate, the gateway sent every inbound to the bridge
+ * immediately, buffering only when the bridge was offline. A
+ * non-steering message that arrived mid-turn was typed into claude's
+ * TUI composer and stranded when the auto-submit raced
+ * turn-completion. The deterministic invariant the gate enforces:
+ *
+ *   a non-steering inbound is delivered ONLY when no turn is in flight.
+ *
+ * Steering (/steer, /s) is the sole exemption — reaching claude
+ * mid-turn is the entire point of that feature.
+ */
+describe('decideInboundDelivery', () => {
+  it('delivers immediately when claude is idle (no turn in flight)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: false, isSteering: false }),
+    ).toBe('deliver')
+  })
+
+  it('BUFFERS a non-steering message that arrives mid-turn (the wedge fix)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: true, isSteering: false }),
+    ).toBe('buffer-until-idle')
+  })
+
+  it('delivers a steering message mid-turn (steering is intentionally exempt)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: true, isSteering: true }),
+    ).toBe('deliver')
+  })
+
+  it('delivers a steering message when idle (steer with no active turn)', () => {
+    expect(
+      decideInboundDelivery({ turnInFlight: false, isSteering: true }),
+    ).toBe('deliver')
+  })
+
+  it('is total: the ONLY deferral path is mid-turn AND not steering', () => {
+    for (const turnInFlight of [true, false]) {
+      for (const isSteering of [true, false]) {
+        const decision = decideInboundDelivery({ turnInFlight, isSteering })
+        const expectBuffer = turnInFlight && !isSteering
+        expect(decision).toBe(expectBuffer ? 'buffer-until-idle' : 'deliver')
+      }
+    }
+  })
+})

package/telegram-plugin/tests/inbound-spool.test.ts

@@ -0,0 +1,229 @@
+/**
+ * inbound-spool — durable, crash-tolerant inbound spool.
+ *
+ * Pins the determinism guarantee: a buffered inbound survives a
+ * gateway/container restart (it's on the persistent volume), is
+ * replayed un-acked, acked only on confirmed delivery, deduped by a
+ * stable id, and escalated-then-dropped if undeliverable past its
+ * bound — so the "your message is queued" promise is ALWAYS resolved
+ * (delivered or visibly retracted), never silently lost (the
+ * finn/carrie lost-on-restart incident class, 2026-05-19).
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createInboundSpool,
+  spoolId,
+  type InboundSpoolFsSeam,
+} from '../gateway/inbound-spool.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+function msg(over: Partial<InboundMessage> = {}): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'c1',
+    messageId: 1001,
+    user: 'ken',
+    userId: 42,
+    ts: 1000,
+    text: 'hello',
+    meta: {},
+    ...over,
+  } as InboundMessage
+}
+
+/** In-memory fake fs keyed by path. Models append, full rewrite, and
+ *  atomic rename (so the tmp→rename compaction path is exercised). */
+function fakeFs(): InboundSpoolFsSeam & { dump(p?: string): string } {
+  const files = new Map<string, string>()
+  return {
+    appendFileSync: (p, d) => files.set(p, (files.get(p) ?? '') + d),
+    readFileSync: (p) => files.get(p) ?? '',
+    writeFileSync: (p, d) => files.set(p, d),
+    renameSync: (from, to) => {
+      files.set(to, files.get(from) ?? '')
+      files.delete(from)
+    },
+    existsSync: (p) => files.has(p),
+    statSizeSync: (p) => Buffer.byteLength(files.get(p) ?? ''),
+    dump: (p = PATH) => files.get(p) ?? '',
+  }
+}
+
+const PATH = '/state/agent/telegram/inbound-spool.jsonl'
+
+describe('spoolId — stable dedup key', () => {
+  it('real Telegram message → m:chat:msgId', () => {
+    expect(spoolId(msg({ chatId: 'c9', messageId: 55 }))).toBe('m:c9:55')
+  })
+  it('synthetic (messageId 0) → s:chat:source:ts (distinct events do not collapse)', () => {
+    const a = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    const b = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 200 }))
+    expect(a).toBe('s:c1:cron:100')
+    expect(a).not.toBe(b) // different ts = different logical event
+  })
+  it('same logical synthetic retried (same ts) dedups to the same id', () => {
+    const a = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    const b = spoolId(msg({ messageId: 0, meta: { source: 'cron' }, ts: 100 }))
+    expect(a).toBe(b)
+  })
+})
+
+describe('inbound-spool — put / ack / dedup', () => {
+  it('put records a live entry; dedups a re-put of the same id', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    expect(s.put('carrie', msg({ messageId: 7 }))).toBe(true)
+    expect(s.put('carrie', msg({ messageId: 7 }))).toBe(false) // dedup
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()).toHaveLength(1)
+    expect(s.liveEntries()[0].agent).toBe('carrie')
+  })
+
+  it('ack tombstones the entry; ack is idempotent / unknown-id safe', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    const m = msg({ messageId: 7 })
+    s.put('carrie', m)
+    s.ack(m)
+    expect(s.liveCount()).toBe(0)
+    s.ack(m) // idempotent
+    s.ack(msg({ messageId: 999 })) // unknown id, no throw
+    expect(s.liveCount()).toBe(0)
+  })
+
+  it('liveEntries is oldest-first (replay order)', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs })
+    s.put('a', msg({ messageId: 1 }))
+    s.put('a', msg({ messageId: 2 }))
+    s.put('a', msg({ messageId: 3 }))
+    expect(s.liveEntries().map((e) => e.msg.messageId)).toEqual([1, 2, 3])
+  })
+})
+
+describe('inbound-spool — crash-survivable replay (the core guarantee)', () => {
+  it('a fresh spool over an existing file rebuilds live state (survives restart)', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('carrie', msg({ messageId: 7, text: 'the craft message' }))
+    s1.put('carrie', msg({ messageId: 8 }))
+    s1.ack(msg({ messageId: 8 })) // 8 delivered before the "crash"
+    // Simulate gateway/container restart: brand-new spool, SAME file.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1)
+    const live = s2.liveEntries()
+    expect(live[0].msg.messageId).toBe(7)
+    expect(live[0].msg.text).toBe('the craft message') // full payload survived
+    expect(live[0].agent).toBe('carrie')
+  })
+
+  it('tolerates a torn final line (crash mid-append) — skips it, keeps the rest', () => {
+    const fs = fakeFs()
+    const s1 = createInboundSpool({ path: PATH, fs })
+    s1.put('carrie', msg({ messageId: 7 }))
+    // Append a half-written record (no newline, invalid JSON tail).
+    fs.appendFileSync(PATH, '{"t":"put","id":"m:c1:8","agen')
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1) // the torn line is ignored, 7 survives
+    expect(s2.liveEntries()[0].msg.messageId).toBe(7)
+  })
+
+  it('ignores any line that does not pass the shape check', () => {
+    const fs = fakeFs()
+    fs.appendFileSync(PATH, 'not json\n')
+    fs.appendFileSync(PATH, '{"t":"put"}\n') // missing id/msg/agent
+    fs.appendFileSync(PATH, '{"t":"weird","id":"x"}\n')
+    fs.appendFileSync(
+      PATH,
+      JSON.stringify({ t: 'put', id: 'm:c1:7', agent: 'a', firstAt: 1, msg: msg({ messageId: 7 }) }) + '\n',
+    )
+    const s = createInboundSpool({ path: PATH, fs })
+    expect(s.liveCount()).toBe(1)
+    expect(s.liveEntries()[0].msg.messageId).toBe(7)
+  })
+})
+
+describe('inbound-spool — bounded escalation (promise always resolved)', () => {
+  it('escalates+drops only entries older than the bound; younger untouched', () => {
+    const fs = fakeFs()
+    let t = 1_000_000
+    const s = createInboundSpool({
+      path: PATH,
+      fs,
+      now: () => t,
+      escalateAfterMs: 10_000,
+    })
+    s.put('carrie', msg({ messageId: 1 })) // firstAt = 1_000_000
+    t = 1_005_000
+    s.put('carrie', msg({ messageId: 2 })) // firstAt = 1_005_000
+    t = 1_012_000 // msg1 is 12s old (>10s bound), msg2 is 7s old
+    const escalated: number[] = []
+    const n = s.sweepEscalations((e) => escalated.push(e.msg.messageId as number))
+    expect(n).toBe(1)
+    expect(escalated).toEqual([1])
+    expect(s.liveCount()).toBe(1) // msg2 still live
+    expect(s.liveEntries()[0].msg.messageId).toBe(2)
+  })
+
+  it('an escalated id stays dropped across a restart (tombstoned, not replayed)', () => {
+    const fs = fakeFs()
+    let t = 0
+    const s1 = createInboundSpool({ path: PATH, fs, now: () => t, escalateAfterMs: 100 })
+    s1.put('a', msg({ messageId: 1 }))
+    t = 1000
+    expect(s1.sweepEscalations(() => {})).toBe(1)
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(0) // not resurrected on replay
+  })
+})
+
+describe('inbound-spool — robustness', () => {
+  it('a failing appendFileSync does not throw and keeps in-memory live state', () => {
+    const fs = fakeFs()
+    fs.appendFileSync = () => {
+      throw new Error('ENOSPC')
+    }
+    const logs: string[] = []
+    const s = createInboundSpool({ path: PATH, fs, log: (l) => logs.push(l) })
+    expect(() => s.put('a', msg({ messageId: 1 }))).not.toThrow()
+    expect(s.liveCount()).toBe(1) // live delivery still works (degraded durability)
+    expect(logs.join('')).toContain('durability degraded')
+  })
+
+  it('compacts once past the size bound, dropping acked ids', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs, compactAtBytes: 200 })
+    for (let i = 1; i <= 20; i++) {
+      s.put('a', msg({ messageId: i, text: 'x'.repeat(50) }))
+      s.ack(msg({ messageId: i }))
+    }
+    s.put('a', msg({ messageId: 999 }))
+    // After compaction the file holds only the one live id, not the
+    // 20 acked put+ack pairs.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(1)
+    expect(s2.liveEntries()[0].msg.messageId).toBe(999)
+    expect(fs.dump().split('\n').filter(Boolean).length).toBeLessThan(5)
+  })
+
+  it('atomic compaction: a rename crash leaves the ORIGINAL log intact (no loss)', () => {
+    const fs = fakeFs()
+    const s = createInboundSpool({ path: PATH, fs, compactAtBytes: 200 })
+    for (let i = 1; i <= 10; i++) {
+      s.put('a', msg({ messageId: i, text: 'y'.repeat(50) }))
+    }
+    // Simulate a crash AFTER the tmp write but BEFORE/at the rename.
+    fs.renameSync = () => {
+      throw new Error('crash mid-compact')
+    }
+    s.put('a', msg({ messageId: 11, text: 'y'.repeat(50) })) // triggers maybeCompact → rename throws
+    // Original append-only log must still hold every live entry — the
+    // failed compaction is a no-op, never a truncation.
+    const s2 = createInboundSpool({ path: PATH, fs })
+    expect(s2.liveCount()).toBe(11)
+    expect(s2.liveEntries().map((e) => e.msg.messageId)).toEqual([
+      1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+    ])
+  })
+})

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -247,3 +247,69 @@ describe('idleDrainTick — the 3rd drain trigger (finn orphan gap, 2026-05-19)'
     expect(probed).toBe(false) // cheap path: Map.get only, no bridge probe, no log
   })
 })
+
+describe('durable-spool integration (finn/carrie lost-on-restart fix)', () => {
+  function spySpool() {
+    const puts: string[] = []
+    const acks: string[] = []
+    return {
+      puts,
+      acks,
+      spool: {
+        put: (_a: string, m: InboundMessage) => {
+          puts.push(String(m.messageId))
+          return true
+        },
+        ack: (m: InboundMessage) => {
+          acks.push(String(m.messageId))
+        },
+        liveEntries: () => [],
+        sweepEscalations: () => 0,
+        liveCount: () => 0,
+      },
+    }
+  }
+
+  it('every push is durably spooled (chokepoint for all ~10 push sites)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    buf.push('carrie', inbound('user', 8))
+    expect(sp.puts).toEqual(['7', '8'])
+  })
+
+  it('a CONFIRMED delivery acks the spool; a miss does NOT (stays durable)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    // delivery succeeds → spool acked
+    redeliverBufferedInbound(buf, 'carrie', () => true, sp.spool as never)
+    expect(sp.acks).toEqual(['7'])
+
+    // delivery misses → NOT acked, re-buffered + still spooled
+    const sp2 = spySpool()
+    const buf2 = createPendingInboundBuffer({ log: () => {}, spool: sp2.spool as never })
+    buf2.push('carrie', inbound('user', 9))
+    redeliverBufferedInbound(buf2, 'carrie', () => false, sp2.spool as never)
+    expect(sp2.acks).toEqual([]) // never acked on a miss → survives for retry/escalation
+    expect(buf2.depth('carrie')).toBe(1) // re-buffered in memory too
+  })
+
+  it('idleDrainTick threads the spool through (ack only on delivered)', () => {
+    const sp = spySpool()
+    const buf = createPendingInboundBuffer({ log: () => {}, spool: sp.spool as never })
+    buf.push('carrie', inbound('user', 7))
+    idleDrainTick(buf, 'carrie', () => true, () => true, sp.spool as never)
+    expect(sp.acks).toEqual(['7'])
+  })
+
+  it('works with no spool (back-compat: undefined spool is a no-op)', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('carrie', inbound('user', 7))
+    expect(redeliverBufferedInbound(buf, 'carrie', () => true)).toEqual({
+      drained: 1,
+      redelivered: 1,
+      rebuffered: 0,
+    })
+  })
+})