switchroom 0.13.35 → 0.13.37

package/telegram-plugin/tests/pending-work-progress.test.ts

@@ -407,4 +407,138 @@ describe('pending-work-progress', () => {
     expect(cap.edits.filter((e) => e.messageId === 10)).toHaveLength(1)
     expect(cap.edits.filter((e) => e.messageId === 20)).toHaveLength(2)
   })
+
+  // ─── #1760 regression tests ───────────────────────────────────────────
+  //
+  // The "— still working (Nm)" ticker can get stuck forever editing an
+  // old outbound message if the gateway misses the SDK `turn_end` event.
+  // Two layers of defence:
+  //
+  //   1. PRIMARY: the gateway tears down on every `reply: finalized`
+  //      chokepoint via `clearPending(key, 'reply_finalize')` BEFORE
+  //      `noteOutbound` on the next turn's first reply. Verified here by
+  //      simulating a missed-turn_end scenario: the prior turn's ticker
+  //      is activated, then the gateway processes a fresh reply on a NEW
+  //      turn without ever calling `noteTurnEnd` for the prior one. The
+  //      explicit `clearPending('reply_finalize')` call must wipe the
+  //      stale ambient.
+  //
+  //   2. DEFENSE-IN-DEPTH: at tick time, if `isActiveTurnNewerThan`
+  //      returns true (gateway reports a newer turn is active for this
+  //      chat), the ticker self-terminates instead of editing. Bug
+  //      becomes "at most one stale tick" rather than "stuck forever."
+
+  it('#1760 primary: reply_finalize teardown wipes a stale activated ticker', async () => {
+    const cap = setup()
+
+    // Turn 1: dispatch async work, capture an anchor, end the turn.
+    // Ticker activates and fires one edit at +60s.
+    startTurn(KEY)
+    noteAsyncDispatch(KEY)
+    noteOutbound(KEY, { messageId: 100, text: 'kicking off worker' })
+    noteTurnEnd(KEY)
+    cap.now = EDIT_INTERVAL_MS
+    __tickForTests(cap.now)
+    await flush()
+    expect(cap.edits).toHaveLength(1)
+    expect(cap.edits[0]?.messageId).toBe(100)
+
+    // Turn 2 begins WITHOUT a prior `noteTurnEnd` clear (simulating the
+    // #1760 missed-turn_end SDK-event-drop). The gateway's reply-
+    // finalize chokepoint MUST call clearPending('reply_finalize')
+    // BEFORE noteOutbound on the new anchor. After that, the prior
+    // ticker is gone and further ticks (even before any new
+    // noteTurnEnd) edit nothing.
+    clearPending(KEY, 'reply_finalize')
+    noteOutbound(KEY, { messageId: 200, text: 'turn 2 reply' })
+
+    cap.now = EDIT_INTERVAL_MS * 5
+    __tickForTests(cap.now)
+    await flush()
+    // No additional edits — the stale ticker is dead. Note that the new
+    // turn's ticker has not been activated yet (noteTurnEnd not called),
+    // so nothing should fire here either.
+    expect(cap.edits).toHaveLength(1)
+
+    // The 'reply_finalize' clear must surface as a metric so operators
+    // can observe the backstop firing in production.
+    const reasons = cap.metrics
+      .filter((m): m is Extract<PendingProgressMetric, { kind: 'pending_progress_cleared' }> =>
+        m.kind === 'pending_progress_cleared')
+      .map((m) => m.reason)
+    expect(reasons).toContain('reply_finalize')
+  })
+
+  it('#1760 defense-in-depth: ticker self-terminates when isActiveTurnNewerThan is true', async () => {
+    const cap: Capture = { edits: [], metrics: [], now: 0 }
+    __resetAllForTests()
+    // The activatedAt epoch captured by the ticker:
+    const TURN_1_ACTIVATED_AT = 1_000
+    // A NEWER turn starts later, simulating turn-2 racing past the
+    // missed teardown:
+    const TURN_2_STARTED_AT = TURN_1_ACTIVATED_AT + 30_000
+
+    __setDepsForTests({
+      editMessage: async (ctx) => {
+        cap.edits.push(ctx)
+      },
+      emitMetric: (e) => {
+        cap.metrics.push(e)
+      },
+      nowMs: () => cap.now,
+      // Reports a newer turn always-on for this test.
+      isActiveTurnNewerThan: (_key, activatedAt) =>
+        TURN_2_STARTED_AT > activatedAt,
+    })
+
+    // Bootstrap a "prior turn" ticker at TURN_1_ACTIVATED_AT.
+    cap.now = TURN_1_ACTIVATED_AT
+    startTurn(KEY)
+    noteAsyncDispatch(KEY)
+    noteOutbound(KEY, { messageId: 100, text: 'kicking off worker' })
+    noteTurnEnd(KEY)
+    expect(__getStateForTests(KEY)?.activatedAt).toBe(TURN_1_ACTIVATED_AT)
+
+    // Advance past EDIT_INTERVAL_MS so the tick would otherwise fire.
+    cap.now = TURN_1_ACTIVATED_AT + EDIT_INTERVAL_MS + 1_000
+    __tickForTests(cap.now)
+    await flush()
+
+    // No edit fired — the predicate detected a newer active turn and
+    // dropped the ticker.
+    expect(cap.edits).toHaveLength(0)
+    expect(__getStateForTests(KEY)).toBeUndefined()
+
+    const cleared = cap.metrics.find(
+      (m): m is Extract<PendingProgressMetric, { kind: 'pending_progress_cleared' }> =>
+        m.kind === 'pending_progress_cleared',
+    )
+    expect(cleared?.reason).toBe('stale_turn')
+  })
+
+  it('#1760 defense-in-depth: predicate returning false leaves ticker alone', async () => {
+    const cap: Capture = { edits: [], metrics: [], now: 0 }
+    __resetAllForTests()
+    __setDepsForTests({
+      editMessage: async (ctx) => {
+        cap.edits.push(ctx)
+      },
+      emitMetric: (e) => {
+        cap.metrics.push(e)
+      },
+      nowMs: () => cap.now,
+      // No newer turn — the legitimate cross-turn ambient case.
+      isActiveTurnNewerThan: () => false,
+    })
+
+    startTurn(KEY)
+    noteAsyncDispatch(KEY)
+    noteOutbound(KEY, { messageId: 100, text: 'kicking off worker' })
+    noteTurnEnd(KEY)
+
+    cap.now = EDIT_INTERVAL_MS
+    __tickForTests(cap.now)
+    await flush()
+    expect(cap.edits).toHaveLength(1)
+  })
 })

package/telegram-plugin/tests/silent-end-interrupt-stop-integration.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Integration test for the silent-end Stop hook .mjs.
+ *
+ * Spawns the real script as a subprocess with a synthetic transcript
+ * on disk and the Stop event JSON on stdin. Pins the contract that
+ * matters at the hook boundary: stdout JSON shape, exit code,
+ * retry-count side-effect on the state file.
+ *
+ * Complements `silent-end-interrupt-stop-scan.test.ts` (which pins
+ * the pure helper in isolation). This test guards against
+ * regressions in:
+ *   - stdin parsing
+ *   - transcript_path file IO + fail-open on read errors
+ *   - state-file retry-count increment
+ *   - retry-budget exhaustion → allow
+ *   - block-decision stdout shape
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const HOOK_PATH = resolve(
+  __dirname,
+  '..',
+  'hooks',
+  'silent-end-interrupt-stop.mjs',
+)
+
+interface RunResult {
+  status: number | null
+  stdout: string
+  stderr: string
+}
+
+function runHook(input: { event: object; stateDir: string }): RunResult {
+  const r = spawnSync('node', [HOOK_PATH], {
+    input: JSON.stringify(input.event),
+    encoding: 'utf8',
+    timeout: 5000,
+    env: { ...process.env, TELEGRAM_STATE_DIR: input.stateDir },
+  })
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr }
+}
+
+function writeTranscript(dir: string, lines: object[]): string {
+  const p = join(dir, 'transcript.jsonl')
+  writeFileSync(p, lines.map((l) => JSON.stringify(l)).join('\n'), 'utf8')
+  return p
+}
+
+const ENQUEUE = {
+  type: 'queue-operation',
+  operation: 'enqueue',
+  content: '<channel source="switchroom-telegram" chat_id="111" message_id="42">hi</channel>',
+}
+
+function reply(text: string, opts: { disable_notification?: boolean; done?: boolean } = {}) {
+  return {
+    type: 'assistant',
+    message: {
+      content: [
+        {
+          type: 'tool_use',
+          name: 'mcp__switchroom-telegram__reply',
+          input: { text, ...opts },
+        },
+      ],
+    },
+  }
+}
+
+describe('silent-end-interrupt-stop.mjs — integration', () => {
+  let tmp: string
+  let stateDir: string
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'silent-end-hook-'))
+    stateDir = join(tmp, 'state')
+    mkdirSync(stateDir, { recursive: true })
+  })
+
+  afterEach(() => {
+    try { rmSync(tmp, { recursive: true, force: true }) } catch { /* ignore */ }
+  })
+
+  it('allows stop when transcript shows a notification-bearing reply', () => {
+    const transcript = writeTranscript(tmp, [
+      ENQUEUE,
+      reply('ok', { disable_notification: false }),
+    ])
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: transcript },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+    expect(existsSync(join(stateDir, 'silent-end-pending.json'))).toBe(false)
+  })
+
+  it("blocks + writes retryCount=1 when transcript shows ack-only (Ken's repro)", () => {
+    const transcript = writeTranscript(tmp, [
+      ENQUEUE,
+      reply('on it — checking now', { disable_notification: true }),
+      { type: 'assistant', message: { content: [{ type: 'tool_use', name: 'Bash', input: {} }] } },
+      // 2237-char answer as plain text, no reply tool
+      {
+        type: 'assistant',
+        message: { content: [{ type: 'text', text: 'A'.repeat(2237) }] },
+      },
+    ])
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: transcript },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    const out = JSON.parse(r.stdout)
+    expect(out.decision).toBe('block')
+    expect(out.reason).toMatch(/Send your final answer/)
+    expect(out.reason).toMatch(/NO_REPLY/)
+    // Retry-count file was written.
+    const statePath = join(stateDir, 'silent-end-pending.json')
+    expect(existsSync(statePath)).toBe(true)
+    const state = JSON.parse(readFileSync(statePath, 'utf8'))
+    expect(state.retryCount).toBe(1)
+    // Reviewer-flagged regression: the hook's state-file write MUST
+    // include turnKey + chatId derived from the enqueue envelope. Without
+    // these, the gateway's later `recordSilentTurnEnd` write (~175ms after
+    // the hook) sees a turnKey mismatch and resets retryCount to 0,
+    // doubling the effective re-prompt budget. The shape here must match
+    // `chatKey(chatId, threadId)` at telegram-plugin/gateway/chat-key.ts:46.
+    expect(state.chatId).toBe('111')
+    expect(state.turnKey).toBe('111:_')
+  })
+
+  it('preserves retryCount across the hook→gateway write order (reviewer regression)', () => {
+    // Simulates what happens on the gateway side once it runs its own
+    // `writeSilentEndState` ~175ms after the hook: it reads the hook's
+    // file, sees matching turnKey, preserves retryCount. Then the next
+    // `recordSilentTurnEnd` call sees retryCount=1 >= MAX_RETRIES=1 and
+    // returns exhausted — the design budget. Without matching turnKey
+    // this branch never fires on time and the budget doubles.
+    const transcript = writeTranscript(tmp, [
+      ENQUEUE,
+      reply('on it', { disable_notification: true }),
+    ])
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: transcript },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    const statePath = join(stateDir, 'silent-end-pending.json')
+    const state = JSON.parse(readFileSync(statePath, 'utf8'))
+    expect(state.turnKey).toBe('111:_')
+    expect(state.retryCount).toBe(1)
+  })
+
+  it('allows stop when retry budget already exhausted (retryCount >= MAX_RETRIES)', () => {
+    const transcript = writeTranscript(tmp, [
+      ENQUEUE,
+      // Still no final reply, BUT retry already spent — gateway will
+      // post the user-facing fallback so the user isn't left silent.
+      reply('ack', { disable_notification: true }),
+    ])
+    const statePath = join(stateDir, 'silent-end-pending.json')
+    writeFileSync(statePath, JSON.stringify({ retryCount: 1, chatId: '111' }), 'utf8')
+
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: transcript },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+    expect(r.stderr).toMatch(/retry exhausted/)
+    // State unchanged.
+    const state = JSON.parse(readFileSync(statePath, 'utf8'))
+    expect(state.retryCount).toBe(1)
+  })
+
+  it('NO_REPLY in transcript → allow stop, no state file written', () => {
+    const transcript = writeTranscript(tmp, [
+      ENQUEUE,
+      reply('NO_REPLY'),
+    ])
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: transcript },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+    expect(existsSync(join(stateDir, 'silent-end-pending.json'))).toBe(false)
+  })
+
+  it('fail-open when transcript_path missing from event', () => {
+    const r = runHook({
+      event: { session_id: 's1' },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+  })
+
+  it('fail-open when transcript_path does not exist on disk', () => {
+    const r = runHook({
+      event: { session_id: 's1', transcript_path: '/does/not/exist.jsonl' },
+      stateDir,
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+  })
+
+  it('fail-open on malformed stdin', () => {
+    const r = spawnSync('node', [HOOK_PATH], {
+      input: 'this is not JSON',
+      encoding: 'utf8',
+      timeout: 5000,
+      env: { ...process.env, TELEGRAM_STATE_DIR: stateDir },
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+  })
+
+  it('empty stdin → exit 0 immediately', () => {
+    const r = spawnSync('node', [HOOK_PATH], {
+      input: '',
+      encoding: 'utf8',
+      timeout: 5000,
+      env: { ...process.env, TELEGRAM_STATE_DIR: stateDir },
+    })
+    expect(r.status).toBe(0)
+    expect(r.stdout.trim()).toBe('')
+  })
+})

package/telegram-plugin/tests/silent-end-interrupt-stop-scan.test.ts

@@ -0,0 +1,314 @@
+/**
+ * Regression guard for #1775 — the deterministic transcript-scan
+ * replacement of the silent-end Stop hook's signal source.
+ *
+ * Pre-fix the hook depended on a gateway-written state file as the
+ * block/allow signal. The state file was always written ~175ms AFTER
+ * the hook fired (live evidence on clerk 2026-05-25, 12 correlated
+ * samples), so the hook never saw its own turn's signal.
+ *
+ * Post-fix the hook reads `transcript_path` directly and scans the
+ * just-finished turn's tool_use entries for a qualifying reply. This
+ * test suite pins every branch of the new scan logic — the helper is
+ * a pure function (`scanTurnForFinalReply`), so we exercise it with
+ * synthetic JSONL fixtures rather than spawning the .mjs subprocess.
+ *
+ * Each fixture mimics the shapes the live Claude Code transcripts
+ * use (verified against clerk's
+ * `/state/agent/.claude/projects/.../{session}.jsonl` 2026-05-25).
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  scanTurnForFinalReply,
+  isFinalAnswerReply,
+} from '../hooks/silent-end-scan.mjs'
+
+// ── Fixture builders ────────────────────────────────────────────────
+
+const ENQUEUE = JSON.stringify({
+  type: 'queue-operation',
+  operation: 'enqueue',
+  content: '<channel source="switchroom-telegram" chat_id="111" message_id="42">hi</channel>',
+})
+
+function assistantToolUse(name: string, input: Record<string, unknown>, opts: { isSidechain?: boolean } = {}) {
+  const base = {
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', name, input }] },
+  }
+  if (opts.isSidechain) (base as Record<string, unknown>).isSidechain = true
+  return JSON.stringify(base)
+}
+
+function assistantText(text: string) {
+  return JSON.stringify({
+    type: 'assistant',
+    message: { content: [{ type: 'text', text }] },
+  })
+}
+
+function jsonl(...lines: string[]) {
+  return lines.join('\n')
+}
+
+// ── isFinalAnswerReply parity with TS ───────────────────────────────
+
+describe('isFinalAnswerReply (parity with final-answer-detect.ts)', () => {
+  it('done:true → final answer regardless of length/notification', () => {
+    expect(isFinalAnswerReply({ text: '', disableNotification: true, done: true })).toBe(true)
+  })
+
+  it('disable_notification:false → final answer (the notification-bearing case)', () => {
+    expect(isFinalAnswerReply({ text: 'ok', disableNotification: false })).toBe(true)
+  })
+
+  it('length ≥ 200 + disable_notification:true → final answer (substantive backstop)', () => {
+    expect(isFinalAnswerReply({ text: 'a'.repeat(200), disableNotification: true })).toBe(true)
+  })
+
+  it('length 199 + disable_notification:true → interim ack', () => {
+    expect(isFinalAnswerReply({ text: 'a'.repeat(199), disableNotification: true })).toBe(false)
+  })
+})
+
+// ── scanTurnForFinalReply branches ──────────────────────────────────
+
+describe('scanTurnForFinalReply — turn-start anchor', () => {
+  it('empty transcript → unknown (caller must fail-open)', () => {
+    const r = scanTurnForFinalReply('')
+    expect(r.decided).toBe('unknown')
+  })
+
+  it('no enqueue line in transcript → unknown', () => {
+    const text = jsonl(
+      assistantText('hello'),
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ok', disable_notification: false }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('unknown')
+    expect(r.reason).toBe('no-turn-start')
+  })
+
+  it('multiple enqueues → anchors on the LAST one (queued mid-turn semantics)', () => {
+    // First inbound got a long reply BEFORE the second inbound was
+    // queued. Scanning anchors on the last enqueue, so the early
+    // long reply does NOT count.
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', {
+        text: 'a'.repeat(500),
+        disable_notification: false,
+      }),
+      ENQUEUE, // second queued inbound
+      assistantToolUse('mcp__switchroom-telegram__reply', {
+        text: 'ack',
+        disable_notification: true,
+      }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+  })
+})
+
+describe('scanTurnForFinalReply — final-reply detection', () => {
+  it('Ken-2026-05-25 repro: ack + plain text answer → block', () => {
+    // The exact shape from clerk's msg 12227 slip.
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', {
+        text: "On it — checking the Bloomfield statement, then I'll lay out…",
+        disable_notification: true,
+      }),
+      assistantToolUse('Bash', { command: 'ls' }),
+      assistantToolUse('Read', { file_path: '/tmp/x' }),
+      assistantText('That was actually your FY25 NOA, not Bloomfield. ' + 'A'.repeat(2200)),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.reason).toBe('no-final-reply')
+  })
+
+  it('notification-bearing reply → allow', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ok', disable_notification: false }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('stream_reply done:true → allow even with empty text', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__stream_reply', {
+        text: '',
+        done: true,
+        disable_notification: true,
+      }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('allow')
+    expect(r.reason).toBe('final-reply')
+  })
+
+  it('long reply mis-marked disable_notification:true → still allow (≥200 chars backstop)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', {
+        text: 'B'.repeat(500),
+        disable_notification: true,
+      }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('short ack followed by long reply → allow (later qualifies)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'on it', disable_notification: true }),
+      assistantToolUse('Bash', { command: 'ls' }),
+      assistantToolUse('mcp__switchroom-telegram__reply', {
+        text: 'Here is the full answer with notification ' + 'C'.repeat(500),
+        disable_notification: false,
+      }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+})
+
+describe('scanTurnForFinalReply — silent-marker carve-out', () => {
+  it('NO_REPLY → allow', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'NO_REPLY' }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('allow')
+    expect(r.reason).toBe('silent-marker')
+  })
+
+  it('NO_REPLY with trailing punctuation → allow (matches gateway tolerance)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'NO_REPLY.' }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('lowercase no_reply → allow (case-insensitive)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'no_reply' }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('HEARTBEAT_OK → allow (cron-silence carve-out)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'HEARTBEAT_OK' }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+})
+
+describe('scanTurnForFinalReply — non-reply tool_use does NOT satisfy', () => {
+  it('Bash + Read + Agent(sub-agent dispatch) without reply → block', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('Bash', { command: 'ls' }),
+      assistantToolUse('Read', { file_path: '/tmp/x' }),
+      assistantToolUse('Agent', { description: 'sub-agent' }),
+      assistantText('done thinking, but never called reply'),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+  })
+
+  it('isSidechain:true sub-agent reply does NOT count for parent', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse(
+        'mcp__switchroom-telegram__reply',
+        { text: 'sub-agent answer', disable_notification: false },
+        { isSidechain: true },
+      ),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.reason).toBe('no-final-reply')
+  })
+})
+
+describe('scanTurnForFinalReply — envelope-derived turnKey (block result)', () => {
+  it('block carries turnKey/chatId/threadId parsed from the enqueue envelope', () => {
+    const enq = JSON.stringify({
+      type: 'queue-operation',
+      operation: 'enqueue',
+      content: '<channel source="switchroom-telegram" chat_id="abc" message_thread_id="42" message_id="9">hi</channel>',
+    })
+    const text = jsonl(
+      enq,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ack', disable_notification: true }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('block')
+    expect(r.chatId).toBe('abc')
+    expect(r.threadId).toBe(42)
+    expect(r.turnKey).toBe('abc:42')
+  })
+
+  it("DM (no message_thread_id) → turnKey uses '_' sentinel matching chatKey()", () => {
+    // chatKey() at telegram-plugin/gateway/chat-key.ts:46 returns
+    // `${chatId}:_` when threadId is missing/0. This must match.
+    const r = scanTurnForFinalReply(
+      jsonl(ENQUEUE, assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ack', disable_notification: true })),
+    )
+    expect(r.decided).toBe('block')
+    expect(r.turnKey).toBe('111:_')
+    expect(r.chatId).toBe('111')
+    expect(r.threadId).toBeNull()
+  })
+
+  it('allow result does NOT need turnKey (only block path writes the state file)', () => {
+    const text = jsonl(
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ok', disable_notification: false }),
+    )
+    const r = scanTurnForFinalReply(text)
+    expect(r.decided).toBe('allow')
+    expect(r.turnKey).toBeUndefined()
+  })
+})
+
+describe('scanTurnForFinalReply — malformed input tolerance', () => {
+  it('malformed JSON lines interleaved → skipped, decision matches the well-formed ones', () => {
+    const text = jsonl(
+      'this is not json',
+      '{partial',
+      ENQUEUE,
+      'another bad line',
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'ok', disable_notification: false }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('lines starting with non-`{` → skipped quickly (perf guard)', () => {
+    const text = jsonl(
+      '# this is a comment',
+      'random plaintext',
+      ENQUEUE,
+      assistantToolUse('mcp__switchroom-telegram__reply', { text: 'NO_REPLY' }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('allow')
+  })
+
+  it('assistant line with non-array content is tolerated → no crash', () => {
+    const text = jsonl(
+      ENQUEUE,
+      JSON.stringify({ type: 'assistant', message: { content: null } }),
+      JSON.stringify({ type: 'assistant', message: { content: 'a string somehow' } }),
+    )
+    expect(scanTurnForFinalReply(text).decided).toBe('block')
+  })
+})