switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/reaction-trigger.test.ts

@@ -0,0 +1,397 @@
+/**
+ * Unit tests for the reaction-trigger primitives (#1074).
+ *
+ * Covers the synchronous predicate, the per-chat hour cap, the
+ * debounce buffer's single/collapse/batch behaviours, and the inbound
+ * text/meta builders. The integration test that exercises the full
+ * gateway handler lives in `reaction-trigger.gateway.test.ts`.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  BATCH_INLINE_LIMIT,
+  DebounceBuffer,
+  HourCap,
+  REACTIONS_DEFAULTS,
+  buildReactionInboundMeta,
+  buildReactionInboundText,
+  evaluateTriggerCandidate,
+  isGroupChat,
+  resolveReactionsConfig,
+  truncatePreview,
+  type PendingReaction,
+  type ReactionBatch,
+  type ReactionsResolvedConfig,
+} from '../gateway/reaction-trigger.ts'
+
+// Helper — minimal candidate factory.
+function candidate(
+  over: Partial<Parameters<typeof evaluateTriggerCandidate>[1]> = {},
+): Parameters<typeof evaluateTriggerCandidate>[1] {
+  return {
+    chatId: 123,
+    messageId: 42,
+    emoji: '👎',
+    action: 'add',
+    botAuthored: true,
+    ...over,
+  }
+}
+
+const FULL_CFG: ReactionsResolvedConfig = REACTIONS_DEFAULTS
+
+describe('resolveReactionsConfig', () => {
+  it('returns built-in defaults for undefined / null input', () => {
+    expect(resolveReactionsConfig(undefined)).toBe(REACTIONS_DEFAULTS)
+    expect(resolveReactionsConfig(null)).toBe(REACTIONS_DEFAULTS)
+  })
+
+  it('falls through to defaults for missing fields', () => {
+    const r = resolveReactionsConfig({ debounce_ms: 5000 })
+    expect(r.debounceMs).toBe(5000)
+    expect(r.enabled).toBe(REACTIONS_DEFAULTS.enabled)
+    expect(r.perHourCap).toBe(REACTIONS_DEFAULTS.perHourCap)
+    expect(r.triggerEmojis).toBe(REACTIONS_DEFAULTS.triggerEmojis)
+  })
+
+  it('REPLACES trigger_emojis (not unions)', () => {
+    const r = resolveReactionsConfig({ trigger_emojis: ['🔥'] })
+    expect([...r.triggerEmojis]).toEqual(['🔥'])
+    // 👎 (a default) should NOT be present.
+    expect(r.triggerEmojis.has('👎')).toBe(false)
+  })
+
+  it('supports trigger_emojis: [] as the empty allowlist', () => {
+    const r = resolveReactionsConfig({ trigger_emojis: [] })
+    expect(r.triggerEmojis.size).toBe(0)
+  })
+
+  it('defaults match the locked design (Ken approved 2026-05-12)', () => {
+    expect(REACTIONS_DEFAULTS.enabled).toBe(true)
+    expect(REACTIONS_DEFAULTS.debounceMs).toBe(30_000)
+    expect(REACTIONS_DEFAULTS.perHourCap).toBe(10)
+    expect(REACTIONS_DEFAULTS.groupAdminOnly).toBe(true)
+    expect([...REACTIONS_DEFAULTS.triggerEmojis].sort()).toEqual(
+      ['👍', '👎', '✅', '❌'].sort(),
+    )
+  })
+})
+
+describe('evaluateTriggerCandidate', () => {
+  it('accepts a bot-authored 👎 (default allowlist)', () => {
+    expect(evaluateTriggerCandidate(FULL_CFG, candidate())).toEqual({ ok: true })
+  })
+
+  it('rejects when enabled=false (master switch)', () => {
+    const cfg = resolveReactionsConfig({ enabled: false })
+    expect(evaluateTriggerCandidate(cfg, candidate())).toEqual({
+      ok: false,
+      reason: 'disabled',
+    })
+  })
+
+  it('rejects reactions on user-authored messages (no trigger)', () => {
+    expect(evaluateTriggerCandidate(FULL_CFG, candidate({ botAuthored: false }))).toEqual({
+      ok: false,
+      reason: 'not_bot_authored',
+    })
+  })
+
+  it('rejects emoji not in the allowlist (e.g. ❤️ on a bot reply)', () => {
+    expect(evaluateTriggerCandidate(FULL_CFG, candidate({ emoji: '❤️' }))).toEqual({
+      ok: false,
+      reason: 'emoji_not_in_allowlist',
+    })
+  })
+
+  it('rejects null emoji (custom emoji / non-emoji reaction)', () => {
+    expect(evaluateTriggerCandidate(FULL_CFG, candidate({ emoji: null }))).toEqual({
+      ok: false,
+      reason: 'no_emoji',
+    })
+  })
+
+  it('accepts each default-allowlist emoji', () => {
+    for (const e of ['👎', '❌', '👍', '✅']) {
+      expect(evaluateTriggerCandidate(FULL_CFG, candidate({ emoji: e }))).toEqual({
+        ok: true,
+      })
+    }
+  })
+
+  it('narrowed allowlist rejects previously-accepted emojis', () => {
+    const cfg = resolveReactionsConfig({ trigger_emojis: ['👎'] })
+    expect(evaluateTriggerCandidate(cfg, candidate({ emoji: '👍' }))).toEqual({
+      ok: false,
+      reason: 'emoji_not_in_allowlist',
+    })
+    expect(evaluateTriggerCandidate(cfg, candidate({ emoji: '👎' }))).toEqual({
+      ok: true,
+    })
+  })
+
+  it('empty-allowlist effectively disables triggering without enabled=false', () => {
+    const cfg = resolveReactionsConfig({ trigger_emojis: [] })
+    expect(evaluateTriggerCandidate(cfg, candidate({ emoji: '👎' }))).toEqual({
+      ok: false,
+      reason: 'emoji_not_in_allowlist',
+    })
+  })
+})
+
+describe('isGroupChat', () => {
+  it('treats negative chat ids as groups (Bot API convention)', () => {
+    expect(isGroupChat(-100123)).toBe(true)
+    expect(isGroupChat(-1)).toBe(true)
+  })
+  it('treats positive chat ids as DMs', () => {
+    expect(isGroupChat(987654)).toBe(false)
+    expect(isGroupChat(1)).toBe(false)
+  })
+})
+
+describe('HourCap', () => {
+  it('admits up to `cap` events then refuses, scoped per chat', () => {
+    const cap = new HourCap(3)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(false)
+    expect(cap.tryConsume('A')).toBe(false)
+    // Different chat — independent budget.
+    expect(cap.tryConsume('B')).toBe(true)
+  })
+
+  it('cap=0 always refuses', () => {
+    const cap = new HourCap(0)
+    expect(cap.tryConsume('A')).toBe(false)
+    expect(cap.tryConsume('A')).toBe(false)
+  })
+
+  it('rolls forward after the 1-hour window passes', () => {
+    let now = 1_000_000
+    const cap = new HourCap(2, () => now)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(false)
+    // Roll past the hour window.
+    now += 60 * 60 * 1000 + 1
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(true)
+    expect(cap.tryConsume('A')).toBe(false)
+  })
+
+  it('reports a trailing-hour count via size()', () => {
+    let now = 0
+    const cap = new HourCap(5, () => now)
+    cap.tryConsume('A')
+    cap.tryConsume('A')
+    expect(cap.size('A')).toBe(2)
+    now += 60 * 60 * 1000 + 1
+    expect(cap.size('A')).toBe(0)
+  })
+})
+
+describe('DebounceBuffer', () => {
+  // Fake scheduler — exposes timers so the test drives the clock.
+  function makeScheduler(): {
+    schedule: (fn: () => void, ms: number) => { id: number; fn: () => void; ms: number }
+    cancel: (h: { id: number }) => void
+    flushAll: () => void
+    pending: { id: number; fn: () => void; ms: number }[]
+    nextId: number
+  } {
+    let nextId = 1
+    const pending: { id: number; fn: () => void; ms: number }[] = []
+    return {
+      schedule(fn: () => void, ms: number) {
+        const h = { id: nextId++, fn, ms }
+        pending.push(h)
+        return h
+      },
+      cancel(h: { id: number }) {
+        const i = pending.findIndex((p) => p.id === h.id)
+        if (i >= 0) pending.splice(i, 1)
+      },
+      flushAll() {
+        // Snapshot then drain — running fn() may enqueue more.
+        const snap = pending.splice(0)
+        for (const p of snap) p.fn()
+      },
+      pending,
+      nextId,
+    }
+  }
+
+  function pending(over: Partial<PendingReaction> = {}): PendingReaction {
+    return {
+      targetMessageId: 7,
+      emoji: '👎',
+      action: 'add',
+      ts: 0,
+      preview: 'hello',
+      userId: 99,
+      user: 'tester',
+      ...over,
+    }
+  }
+
+  it('single enqueue fires the sink with batched=false after window', () => {
+    const sched = makeScheduler()
+    const batches: ReactionBatch[] = []
+    const buf = new DebounceBuffer(30_000, (b) => batches.push(b), {
+      schedule: sched.schedule as never,
+      cancel: sched.cancel as never,
+    })
+    buf.enqueue(123, pending({ emoji: '👎', targetMessageId: 1 }))
+    expect(batches.length).toBe(0)
+    sched.flushAll()
+    expect(batches.length).toBe(1)
+    expect(batches[0]!.batched).toBe(false)
+    expect(batches[0]!.reactions.length).toBe(1)
+    expect(batches[0]!.reactions[0]!.emoji).toBe('👎')
+  })
+
+  it('two enqueues within window collapse into batched=true with 2 entries', () => {
+    const sched = makeScheduler()
+    const batches: ReactionBatch[] = []
+    const buf = new DebounceBuffer(30_000, (b) => batches.push(b), {
+      schedule: sched.schedule as never,
+      cancel: sched.cancel as never,
+    })
+    buf.enqueue(123, pending({ emoji: '👎', targetMessageId: 1 }))
+    buf.enqueue(123, pending({ emoji: '✅', targetMessageId: 2 }))
+    expect(batches.length).toBe(0)
+    sched.flushAll()
+    expect(batches.length).toBe(1)
+    expect(batches[0]!.batched).toBe(true)
+    expect(batches[0]!.reactions.length).toBe(2)
+  })
+
+  it('separate chats do not collapse into each other', () => {
+    const sched = makeScheduler()
+    const batches: ReactionBatch[] = []
+    const buf = new DebounceBuffer(30_000, (b) => batches.push(b), {
+      schedule: sched.schedule as never,
+      cancel: sched.cancel as never,
+    })
+    buf.enqueue(123, pending({ targetMessageId: 1 }))
+    buf.enqueue(456, pending({ targetMessageId: 2 }))
+    sched.flushAll()
+    expect(batches.length).toBe(2)
+    expect(batches.map((b) => b.chatId).sort()).toEqual([123, 456])
+  })
+
+  it('manual flush() before timer is a no-op double-flush', () => {
+    const sched = makeScheduler()
+    const batches: ReactionBatch[] = []
+    const buf = new DebounceBuffer(30_000, (b) => batches.push(b), {
+      schedule: sched.schedule as never,
+      cancel: sched.cancel as never,
+    })
+    buf.enqueue(123, pending())
+    buf.flush(123)
+    expect(batches.length).toBe(1)
+    // No pending timer is left to fire.
+    sched.flushAll()
+    expect(batches.length).toBe(1)
+  })
+
+  it('caps unbounded growth — extra entries past maxPending are dropped', () => {
+    const sched = makeScheduler()
+    const batches: ReactionBatch[] = []
+    const buf = new DebounceBuffer(
+      30_000,
+      (b) => batches.push(b),
+      {
+        schedule: sched.schedule as never,
+        cancel: sched.cancel as never,
+        maxPending: 3,
+      },
+    )
+    for (let i = 0; i < 10; i++) buf.enqueue(123, pending({ targetMessageId: i }))
+    sched.flushAll()
+    expect(batches.length).toBe(1)
+    expect(batches[0]!.reactions.length).toBe(3)
+  })
+})
+
+describe('truncatePreview', () => {
+  it('returns "" for null / undefined / ""', () => {
+    expect(truncatePreview(null)).toBe('')
+    expect(truncatePreview(undefined)).toBe('')
+    expect(truncatePreview('')).toBe('')
+  })
+  it('returns short strings unchanged', () => {
+    expect(truncatePreview('hi')).toBe('hi')
+  })
+  it('truncates with ellipsis past 200 chars', () => {
+    const s = 'x'.repeat(500)
+    const out = truncatePreview(s)
+    expect(out.length).toBe(200)
+    expect(out.endsWith('…')).toBe(true)
+  })
+})
+
+describe('buildReactionInboundText / Meta', () => {
+  function batchOf(reactions: PendingReaction[]): ReactionBatch {
+    return { chatId: 1, reactions, batched: reactions.length > 1 }
+  }
+  function p(emoji: string, mid: number, preview = 'hi'): PendingReaction {
+    return {
+      targetMessageId: mid, emoji, action: 'add', ts: 0,
+      preview, userId: 1, user: 'u',
+    }
+  }
+
+  it('single produces a <channel source="reaction"> envelope', () => {
+    const text = buildReactionInboundText(batchOf([p('👎', 42, 'the bot said something')]))
+    expect(text).toContain('<channel source="reaction"')
+    expect(text).toContain('emoji="👎"')
+    expect(text).toContain('action="add"')
+    expect(text).toContain('target_message_id="42"')
+    expect(text).toContain('the bot said something')
+    expect(text.endsWith('</channel>')).toBe(true)
+  })
+
+  it('single meta carries the discriminators', () => {
+    const meta = buildReactionInboundMeta(batchOf([p('👍', 7, 'ok')]))
+    expect(meta.source).toBe('reaction')
+    expect(meta.batched).toBe('false')
+    expect(meta.count).toBe('1')
+    expect(meta.reaction_emoji).toBe('👍')
+    expect(meta.target_message_id).toBe('7')
+    expect(meta.target_message_preview).toBe('ok')
+  })
+
+  it('batched lists each reaction inline up to the limit + "+N more"', () => {
+    const reactions = Array.from({ length: BATCH_INLINE_LIMIT + 3 }, (_, i) =>
+      p('👎', i + 1, `m${i + 1}`),
+    )
+    const text = buildReactionInboundText(batchOf(reactions))
+    expect(text).toContain('batched="true"')
+    expect(text).toContain(`count="${reactions.length}"`)
+    expect(text).toContain('+3 more')
+    // Inline-listed first N entries.
+    expect(text).toContain('on msg 1')
+    expect(text).toContain(`on msg ${BATCH_INLINE_LIMIT}`)
+    // Past-limit entries are NOT inlined (only count is propagated).
+    expect(text).not.toContain(`on msg ${BATCH_INLINE_LIMIT + 1}`)
+  })
+
+  it('escapes < and > in preview body and emoji attr', () => {
+    const text = buildReactionInboundText(
+      batchOf([p('👎', 1, '<script>alert(1)</script>')]),
+    )
+    expect(text).not.toContain('<script>')
+    expect(text).toContain('&lt;script&gt;')
+  })
+
+  it('persistence path is unchanged — buildReactionInboundText is pure', () => {
+    // Smoke check that the function does not throw / mutate inputs.
+    const b = batchOf([p('👍', 1)])
+    Object.freeze(b)
+    Object.freeze(b.reactions)
+    expect(() => buildReactionInboundText(b)).not.toThrow()
+  })
+})

package/telegram-plugin/tests/retry-api-call.test.ts

@@ -10,7 +10,12 @@
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { GrammyError } from 'grammy'
-import { createRetryApiCall, type RetryObserver } from '../retry-api-call.js'
+import {
+  createRetryApiCall,
+  createSwallowingRetryApiCall,
+  retryWithThreadFallback,
+  type RetryObserver,
+} from '../retry-api-call.js'
 import { errors, makeGrammyError } from './fake-bot-api.js'
 
 // vitest's vi.advanceTimersByTimeAsync isn't implemented by Bun's test runner.
@@ -285,3 +290,149 @@ describe('retryApiCall', () => {
     })
   })
 })
+
+// #1075 — coverage for the swallow + thread-fallback helpers that wrap
+// the retry policy for the six previously-unwrapped outbound surfaces.
+describe('createSwallowingRetryApiCall (#1075)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('resolves to the underlying value on success', async () => {
+    const retry = createRetryApiCall()
+    const swallow = createSwallowingRetryApiCall(retry)
+    const fn = vi.fn<() => Promise<string>>().mockResolvedValue('ok')
+    const result = await swallow(fn)
+    expect(result).toBe('ok')
+  })
+
+  it('returns undefined and logs when THREAD_NOT_FOUND fires', async () => {
+    const retry = createRetryApiCall()
+    const log = vi.fn()
+    const swallow = createSwallowingRetryApiCall(retry, log)
+    const fn = vi.fn<() => Promise<void>>().mockRejectedValueOnce(errors.threadNotFound())
+    const result = await swallow(fn, { threadId: 42, chat_id: 'c', verb: 'test.send' })
+    expect(result).toBeUndefined()
+    expect(log).toHaveBeenCalledWith(expect.stringMatching(/test\.send.*THREAD_NOT_FOUND/))
+    expect(fn).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns undefined and logs on 403 forbidden', async () => {
+    const retry = createRetryApiCall()
+    const log = vi.fn()
+    const swallow = createSwallowingRetryApiCall(retry, log)
+    const fn = vi.fn<() => Promise<void>>().mockRejectedValueOnce(errors.forbidden())
+    const result = await swallow(fn, { chat_id: 'c', verb: 'forbidden.send' })
+    expect(result).toBeUndefined()
+    expect(log).toHaveBeenCalled()
+  })
+
+  it('returns undefined on benign not-modified (passes through retry semantics)', async () => {
+    const retry = createRetryApiCall()
+    const swallow = createSwallowingRetryApiCall(retry)
+    const fn = vi
+      .fn<() => Promise<void>>()
+      .mockRejectedValueOnce(errors.badRequest('Bad Request: message is not modified'))
+    const result = await swallow(fn)
+    // retry already swallows benign 400s to undefined, so swallowing wrapper
+    // resolves to undefined cleanly with NO error log fired.
+    expect(result).toBeUndefined()
+  })
+})
+
+describe('retryWithThreadFallback (#1075)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('resolves on success with threadId passed through', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<{ message_id: number }>>()
+      .mockResolvedValue({ message_id: 1 })
+    const result = await retryWithThreadFallback(retry, send, {
+      threadId: 42,
+      chat_id: 'c',
+      verb: 'fallback.test',
+    })
+    expect(result.message_id).toBe(1)
+    expect(send).toHaveBeenCalledWith(42)
+  })
+
+  it('drops the thread id and retries once on THREAD_NOT_FOUND', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<{ message_id: number }>>()
+      .mockRejectedValueOnce(errors.threadNotFound())
+      .mockResolvedValueOnce({ message_id: 2 })
+    const result = await retryWithThreadFallback(retry, send, {
+      threadId: 42,
+      chat_id: 'c',
+    })
+    expect(result.message_id).toBe(2)
+    expect(send).toHaveBeenCalledTimes(2)
+    expect(send.mock.calls[0][0]).toBe(42)
+    // Fallback call must drop the thread id.
+    expect(send.mock.calls[1][0]).toBeUndefined()
+  })
+
+  it('propagates non-thread-not-found errors without retry', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<{ message_id: number }>>()
+      .mockRejectedValueOnce(errors.forbidden())
+    await expect(
+      retryWithThreadFallback(retry, send, { threadId: 42, chat_id: 'c' }),
+    ).rejects.toMatchObject({ error_code: 403 })
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+
+  it('handles delete on a thread-bearing message (THREAD_NOT_FOUND coverage for delete)', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<boolean>>()
+      .mockRejectedValueOnce(errors.threadNotFound())
+      .mockResolvedValueOnce(true)
+    const result = await retryWithThreadFallback(retry, send, {
+      threadId: 99,
+      chat_id: 'c',
+      verb: 'deleteMessage',
+    })
+    expect(result).toBe(true)
+    expect(send).toHaveBeenCalledTimes(2)
+  })
+
+  it('handles pin on a thread-bearing message', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<boolean>>()
+      .mockRejectedValueOnce(errors.threadNotFound())
+      .mockResolvedValueOnce(true)
+    const result = await retryWithThreadFallback(retry, send, {
+      threadId: 7,
+      chat_id: 'c',
+      verb: 'pinChatMessage',
+    })
+    expect(result).toBe(true)
+  })
+
+  it('handles edit on a thread-bearing message', async () => {
+    const retry = createRetryApiCall()
+    const send = vi
+      .fn<(tid: number | undefined) => Promise<boolean>>()
+      .mockRejectedValueOnce(errors.threadNotFound())
+      .mockResolvedValueOnce(true)
+    const result = await retryWithThreadFallback(retry, send, {
+      threadId: 7,
+      chat_id: 'c',
+      verb: 'editMessageText',
+    })
+    expect(result).toBe(true)
+  })
+})

package/telegram-plugin/tests/runtime-metrics.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  emitRuntimeMetric,
+  __setRuntimeMetricsPathForTests,
+  __getRuntimeMetricsPathForTests,
+  __isJsonlEnabledForTests,
+} from '../runtime-metrics.js'
+
+let tmpDir: string
+let metricsPath: string
+const ORIGINAL_TELEMETRY = process.env.SWITCHROOM_TELEMETRY_DISABLED
+const ORIGINAL_JSONL_DISABLED = process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'runtime-metrics-test-'))
+  metricsPath = join(tmpDir, 'runtime-metrics.jsonl')
+  __setRuntimeMetricsPathForTests(metricsPath)
+  // Disable PostHog for unit tests — we only want to exercise the JSONL sink.
+  // Real PostHog wiring is covered indirectly by analytics-posthog itself.
+  process.env.SWITCHROOM_TELEMETRY_DISABLED = '1'
+  delete process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED
+})
+
+afterEach(() => {
+  __setRuntimeMetricsPathForTests(null)
+  rmSync(tmpDir, { recursive: true, force: true })
+  if (ORIGINAL_TELEMETRY != null) process.env.SWITCHROOM_TELEMETRY_DISABLED = ORIGINAL_TELEMETRY
+  else delete process.env.SWITCHROOM_TELEMETRY_DISABLED
+  if (ORIGINAL_JSONL_DISABLED != null) process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED = ORIGINAL_JSONL_DISABLED
+  else delete process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED
+})
+
+describe('runtime-metrics — JSONL sink', () => {
+  it('writes one JSON line per event', () => {
+    emitRuntimeMetric({
+      kind: 'inbound_status_query',
+      chat_id: '123',
+      message_id: 42,
+      thread_id: null,
+      text_length: 7,
+      prior_turn_in_flight: true,
+      seconds_since_turn_start: 12,
+    })
+    emitRuntimeMetric({
+      kind: 'turn_started',
+      chat_id: '123',
+      message_id: 43,
+      thread_id: null,
+      inbound_classified_as_status_query: false,
+    })
+    const raw = readFileSync(metricsPath, 'utf-8')
+    const lines = raw.trim().split('\n')
+    expect(lines).toHaveLength(2)
+    const first = JSON.parse(lines[0]!)
+    expect(first.kind).toBe('inbound_status_query')
+    expect(first.chat_id).toBe('123')
+    expect(first.message_id).toBe(42)
+    expect(first.text_length).toBe(7)
+    expect(typeof first.ts).toBe('number')
+  })
+
+  it('turn_ended carries TTFO + outbound gap fields', () => {
+    emitRuntimeMetric({
+      kind: 'turn_ended',
+      chat_id: 'c1',
+      thread_id: 7,
+      duration_ms: 8400,
+      ttfo_ms: 1200,
+      outbound_count: 3,
+      longest_silent_gap_ms: 5500,
+      ended_via: 'reply',
+    })
+    const raw = readFileSync(metricsPath, 'utf-8')
+    const parsed = JSON.parse(raw.trim())
+    expect(parsed.kind).toBe('turn_ended')
+    expect(parsed.ttfo_ms).toBe(1200)
+    expect(parsed.outbound_count).toBe(3)
+    expect(parsed.longest_silent_gap_ms).toBe(5500)
+    expect(parsed.ended_via).toBe('reply')
+  })
+
+  it('appends — does not overwrite — across calls', () => {
+    for (let i = 0; i < 5; i++) {
+      emitRuntimeMetric({
+        kind: 'turn_started',
+        chat_id: 'c1',
+        message_id: i,
+        thread_id: null,
+        inbound_classified_as_status_query: false,
+      })
+    }
+    const raw = readFileSync(metricsPath, 'utf-8')
+    const lines = raw.trim().split('\n')
+    expect(lines).toHaveLength(5)
+  })
+
+  it('creates the parent directory if missing', () => {
+    const nested = join(tmpDir, 'a', 'b', 'c', 'runtime-metrics.jsonl')
+    __setRuntimeMetricsPathForTests(nested)
+    emitRuntimeMetric({
+      kind: 'turn_started',
+      chat_id: 'c1',
+      message_id: 1,
+      thread_id: null,
+      inbound_classified_as_status_query: false,
+    })
+    expect(existsSync(nested)).toBe(true)
+  })
+
+  it('SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED=1 skips the JSONL write', () => {
+    process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED = '1'
+    expect(__isJsonlEnabledForTests()).toBe(false)
+    emitRuntimeMetric({
+      kind: 'turn_started',
+      chat_id: 'c1',
+      message_id: 1,
+      thread_id: null,
+      inbound_classified_as_status_query: false,
+    })
+    expect(existsSync(metricsPath)).toBe(false)
+  })
+
+  it('resolves SWITCHROOM_RUNTIME_METRICS_PATH override', () => {
+    const overridePath = join(tmpDir, 'override.jsonl')
+    __setRuntimeMetricsPathForTests(overridePath)
+    expect(__getRuntimeMetricsPathForTests()).toBe(overridePath)
+  })
+
+  it('emit never throws even if all sinks are disabled', () => {
+    process.env.SWITCHROOM_RUNTIME_METRICS_JSONL_DISABLED = '1'
+    process.env.SWITCHROOM_TELEMETRY_DISABLED = '1'
+    expect(() => {
+      emitRuntimeMetric({
+        kind: 'turn_started',
+        chat_id: 'c1',
+        message_id: 1,
+        thread_id: null,
+        inbound_classified_as_status_query: false,
+      })
+    }).not.toThrow()
+  })
+})