switchroom 0.18.31 → 0.18.33

package/telegram-plugin/tests/subagent-watcher-boot-skip-dead.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Boot-reconcile perf regression: at boot the subagent-watcher must NOT do the
+ * full initial `readSubTail` (a whole-transcript parse + per-record sqlite
+ * liveness/backfill round-trips) for provably-dead prior-session workers.
+ *
+ * Production incident (2026-07-19): on a busy 24/7 agent ~1177 dead `running`
+ * JSONLs (last written days-to-weeks ago) each got the full register → whole-
+ * file read → liveness/backfill → staleness → FSWatcher-decision treatment on
+ * every boot. On a slow disk that O(filesize) work delayed the gateway
+ * answering Telegram by ~7 minutes after each restart, so the agent looked
+ * dead. The staleness verdict (`last write > inflightPromoteMaxAgeMs`) was
+ * already reached, but only AFTER the expensive read.
+ *
+ * The fix replaces the full read for a stale-by-mtime historical entry with a
+ * BOUNDED TAIL PROBE. Outcomes asserted here (not code paths):
+ *   1. running-at-boot-stale (no turn_end): registered historical, NO watcher,
+ *      NOT swept (nothing terminal to sweep), and the disk read is bounded to
+ *      the tail window even for a huge file (never a byte-0 whole-transcript
+ *      read).
+ *   2. done-at-boot-stale (turn_end present): still reaches terminal cleanup —
+ *      `onTerminalCleanup` fires after the grace window so the worker-feed row
+ *      is swept (the regression the coordinator caught: a done-at-boot orphan
+ *      must NOT be silently left as a ghost feed row).
+ *   3. fresh in-flight-at-boot: takes the full path — its JSONL IS read from
+ *      byte 0 and it DOES get a per-file FSWatcher (no over-pruning).
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type * as fs from 'fs'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+interface FakeWatcher { path: string; close: ReturnType<typeof vi.fn> }
+interface ReadCall { position: number; length: number }
+
+const AGENT_DIR = '/home/user/.switchroom/agents/myagent'
+const PROJECTS = `${AGENT_DIR}/.claude/projects`
+const PROJECT = `${PROJECTS}/proj`
+const SESSION = `${PROJECT}/sess`
+const SUBAGENTS = `${SESSION}/subagents`
+const NOW = 100_000_000
+
+const turnEndLine = () => JSON.stringify({ type: 'system', subtype: 'turn_duration', duration_ms: 100 })
+const toolUseLine = () =>
+  JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 't1', name: 'Read', input: {} }] } })
+
+/**
+ * Harness with per-path read tracking (position + length of every readSync, the
+ * proxy for "how much of the transcript did boot read") and FSWatcher tracking.
+ * `reportedSize` can far exceed the synthetic tail content, so a test can assert
+ * that only the tail window — not the whole (huge) file — was read.
+ */
+function makeHarness(opts: {
+  fileName: string
+  ageMs: number
+  reportedSize: number
+  /** Synthetic bytes returned when the file is read (represents its tail). */
+  tail: Buffer
+}) {
+  const jsonl = `${SUBAGENTS}/${opts.fileName}`
+  const reads: ReadCall[] = []
+  const watchers: FakeWatcher[] = []
+  const timeouts: Array<{ fn: () => void; fireAt: number; ref: number }> = []
+  const terminalCleanups: string[] = []
+  let currentTime = NOW
+  let nextRef = 1
+
+  const mockFs = {
+    existsSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      return ps === PROJECTS || ps === PROJECT || ps === SESSION || ps === SUBAGENTS || ps === jsonl
+    }) as typeof fs.existsSync,
+    readdirSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === PROJECTS) return ['proj']
+      if (ps === PROJECT) return ['sess']
+      if (ps === SESSION) return ['subagents']
+      if (ps === SUBAGENTS) return [opts.fileName]
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) => {
+      if (String(p) !== jsonl) return { size: 0, mtimeMs: currentTime } as fs.Stats
+      return { size: opts.reportedSize, mtimeMs: currentTime - opts.ageMs } as fs.Stats
+    }) as typeof fs.statSync,
+    openSync: (() => 7) as unknown as typeof fs.openSync,
+    closeSync: (() => undefined) as typeof fs.closeSync,
+    readSync: ((
+      _fd: number, buf: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null,
+    ): number => {
+      reads.push({ position: position ?? 0, length })
+      const src = opts.tail.subarray(0, Math.min(length, opts.tail.length))
+      src.copy(buf as Buffer, offset)
+      return src.length
+    }) as unknown as typeof fs.readSync,
+    watch: ((p: fs.PathLike) => {
+      const w: FakeWatcher = { path: String(p), close: vi.fn() }
+      watchers.push(w)
+      return w as unknown as fs.FSWatcher
+    }) as unknown as typeof fs.watch,
+  }
+
+  const watcher = startSubagentWatcher({
+    agentDir: AGENT_DIR,
+    fs: mockFs,
+    now: () => currentTime,
+    setInterval: () => ({ ref: 0 }),
+    clearInterval: () => {},
+    setTimeout: (fn: () => void, ms: number) => {
+      const ref = nextRef++
+      timeouts.push({ fn, fireAt: currentTime + ms, ref })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = timeouts.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timeouts.splice(idx, 1)
+    },
+    onTerminalCleanup: (agentId: string) => { terminalCleanups.push(agentId) },
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      timeouts.sort((a, b) => a.fireAt - b.fireAt)
+      const next = timeouts[0]
+      if (!next || next.fireAt > currentTime) break
+      timeouts.shift()
+      next.fn()
+    }
+  }
+
+  return {
+    watcher,
+    reads,
+    advance,
+    terminalCleanups,
+    jsonl,
+    fileWatchers: () => watchers.filter((w) => w.path === jsonl),
+  }
+}
+
+describe('subagent-watcher boot reconcile: skip full read for dead prior-session workers', () => {
+  it('running-at-boot-stale: historical, no watcher, bounded tail read (not whole transcript), not swept', () => {
+    const agentId = 'deadrunning'
+    // A huge (50 MB) JSONL last written 3 days ago whose tail has NO turn_end.
+    const tail = Buffer.from(`${toolUseLine()}\n${toolUseLine()}\n${toolUseLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 3 * 24 * 3600_000,
+      reportedSize: 50_000_000,
+      tail,
+    })
+
+    const entry = h.watcher.getRegistry().get(agentId)
+    expect(entry?.historical).toBe(true)
+    expect(entry?.state).toBe('running')             // never promoted, never done
+    expect(h.fileWatchers()).toHaveLength(0)          // no FD leak for a dead worker
+    expect(h.terminalCleanups).not.toContain(agentId) // nothing terminal to sweep
+
+    // The disk read was BOUNDED to the tail window — the 50 MB file was NEVER
+    // read from byte 0 (that whole-transcript read is the ~7-min boot cost).
+    expect(h.reads.length).toBeGreaterThan(0)
+    for (const r of h.reads) {
+      expect(r.position).toBeGreaterThan(0)           // tail offset, not byte 0
+      expect(r.length).toBeLessThanOrEqual(512 * 1024)
+    }
+
+    h.watcher.stop()
+  })
+
+  it('done-at-boot-stale: still reaches terminal cleanup (onTerminalCleanup fires → feed row swept)', () => {
+    const agentId = 'deaddone'
+    // A stale JSONL whose tail ends in a turn_duration line → done at boot.
+    const tail = Buffer.from(`${toolUseLine()}\n${turnEndLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 3 * 24 * 3600_000,
+      reportedSize: 50_000_000,
+      tail,
+    })
+
+    const entry = h.watcher.getRegistry().get(agentId)
+    expect(entry?.historical).toBe(true)
+    expect(entry?.state).toBe('done')                 // detected terminal via the probe
+    expect(h.fileWatchers()).toHaveLength(0)           // no watcher for a done-at-boot worker
+    expect(h.terminalCleanups).toHaveLength(0)         // not yet — waits out the grace window
+
+    // Fire the scheduled terminal cleanup (30s grace) → onTerminalCleanup so the
+    // gateway sweeps the ghost feed row. THIS is the regression guard.
+    h.advance(30_000)
+    expect(h.terminalCleanups).toContain(agentId)
+
+    // Still bounded — the probe read only the tail, never the whole 50 MB file.
+    for (const r of h.reads) {
+      expect(r.position).toBeGreaterThan(0)
+      expect(r.length).toBeLessThanOrEqual(512 * 1024)
+    }
+
+    h.watcher.stop()
+  })
+
+  it('fresh in-flight-at-boot: full path — read from byte 0 and given an FSWatcher (no over-pruning)', () => {
+    const agentId = 'liveone'
+    const tail = Buffer.from(`${toolUseLine()}\n`, 'utf-8')
+    const h = makeHarness({
+      fileName: `agent-${agentId}.jsonl`,
+      ageMs: 30_000,                                  // 30s old — inside the freshness window
+      reportedSize: tail.length,
+      tail,
+    })
+
+    // Full path: the JSONL is read from byte 0 (the whole transcript) and a
+    // per-file FSWatcher is opened so live transitions are observed.
+    expect(h.reads.some((r) => r.position === 0)).toBe(true)
+    expect(h.fileWatchers()).toHaveLength(1)
+
+    h.watcher.stop()
+  })
+})

package/telegram-plugin/tests/subagent-watcher-resume-reregister.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Tests for SubagentWatcher re-registration after a SendMessage resume
+ * (issue #3315).
+ *
+ * A background worker that completes normally (a REAL `sub_agent_turn_end`)
+ * is swept out of the registry by `cleanupTerminalAgent`, which records the
+ * agent id in `terminatedAgentIds` so a rescan of the still-present JSONL
+ * doesn't re-register and re-fire a duplicate handback (issue #1116 Bug B).
+ *
+ * But a SendMessage-resume reuses the SAME `agent-<id>.jsonl`, appending a
+ * NEW turn to it. Pre-fix the `terminatedAgentIds` guard suppressed that file
+ * forever regardless of growth, so the resumed worker was never tracked again:
+ * no FSWatcher, no `onProgress`, no progress card — the exact UX failure the
+ * card exists to prevent (operator: "I don't see any progress cards, anything
+ * happening??").
+ *
+ * This suite pins BOTH directions of the deterministic size-based mechanism:
+ *
+ *  (a) terminal cleanup → resume (JSONL grows past the terminal size) ⇒ the
+ *      watcher re-registers the agent as a LIVE worker and emits progress
+ *      cues again. The re-registration reads only the NEW turn — it does NOT
+ *      replay the already-handed-back completed turn (no duplicate onFinish
+ *      until the resumed turn genuinely ends).
+ *  (b) terminal cleanup with NO resume (JSONL static) ⇒ the agent stays
+ *      cleaned up: no re-registration, no duplicate onFinish, no leaked card.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+import * as fs from 'fs'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentToolUse(name: string, id: string, input: Record<string, unknown> = {}) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input }] } }
+}
+function subAgentTurnEnd() {
+  return { type: 'system', subtype: 'turn_duration', duration_ms: 1234 }
+}
+
+const RESCAN_MS = 500
+const CLEANUP_GRACE_MS = 30_000 // TERMINAL_CLEANUP_GRACE_MS in subagent-watcher.ts
+
+interface ProgressCall {
+  agentId: string
+  skeleton: boolean
+  progressLine?: string
+  toolCount: number
+}
+
+function makeHarness(opts: { agentId?: string } = {}) {
+  const { agentId = 'resume-agent' } = opts
+
+  let currentTime = 1000
+  const progressCalls: ProgressCall[] = []
+  const finishCalls: Array<{ agentId: string; outcome: string }> = []
+  const terminalCleanupCalls: string[] = []
+  const resumeCalls: Array<{ agentId: string; description: string }> = []
+  const logs: string[] = []
+
+  const agentDir = '/home/user/.switchroom/agents/myagent'
+  const sessionId = 'mock-session'
+  const projectsRoot = `${agentDir}/.claude/projects`
+  const projectDir = `${projectsRoot}/mock-cwd`
+  const sessionDir = `${projectDir}/${sessionId}`
+  const subagentsDir = `${sessionDir}/subagents`
+  const jsonlPath = `${subagentsDir}/agent-${agentId}.jsonl`
+
+  // The agent JSONL is NOT present at construction, so the boot scan registers
+  // nothing and the file — when it later appears — registers post-boot as a
+  // LIVE (non-historical) worker, exactly like a freshly-dispatched one.
+  const fileContents = new Map<string, Buffer>()
+
+  let lastOpenedPath: string | null = null
+  const mockFs = {
+    existsSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot || ps === projectDir || ps === sessionDir || ps === subagentsDir) return true
+      return fileContents.has(ps)
+    }) as typeof fs.existsSync,
+    readdirSync: ((p: fs.PathLike) => {
+      const ps = String(p)
+      if (ps === projectsRoot) return ['mock-cwd']
+      if (ps === projectDir) return [sessionId]
+      if (ps === sessionDir) return ['subagents']
+      if (ps === subagentsDir) {
+        // Dynamic: list the agent-*.jsonl files currently present on "disk".
+        const names: string[] = []
+        for (const key of fileContents.keys()) {
+          if (key.startsWith(subagentsDir + '/agent-') && key.endsWith('.jsonl')) {
+            names.push(key.slice(subagentsDir.length + 1))
+          }
+        }
+        return names
+      }
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) =>
+      ({ size: fileContents.get(String(p))?.length ?? 0, mtimeMs: currentTime }) as fs.Stats) as typeof fs.statSync,
+    openSync: ((p: fs.PathLike) => {
+      lastOpenedPath = String(p)
+      return 42
+    }) as unknown as typeof fs.openSync,
+    closeSync: (() => { lastOpenedPath = null }) as typeof fs.closeSync,
+    readSync: ((
+      _fd: number,
+      buf: NodeJS.ArrayBufferView,
+      offset: number,
+      length: number,
+      position: number | null,
+    ): number => {
+      const content = lastOpenedPath != null ? fileContents.get(lastOpenedPath) : undefined
+      if (!content) return 0
+      const pos = position ?? 0
+      const src = content.slice(pos, pos + length)
+      ;(src as Buffer).copy(buf as Buffer, offset)
+      return src.length
+    }) as unknown as typeof fs.readSync,
+    watch: (() => ({ close: vi.fn() }) as unknown as fs.FSWatcher) as unknown as typeof fs.watch,
+  }
+
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  const timeouts: Array<{ fn: () => void; ref: number; fireAt: number }> = []
+  let nextRef = 1
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    rescanMs: RESCAN_MS,
+    onProgress: ({ agentId: id, skeleton, progressLine, toolCount }) =>
+      progressCalls.push({ agentId: id, skeleton: skeleton === true, progressLine, toolCount }),
+    onFinish: ({ agentId: id, outcome }) => finishCalls.push({ agentId: id, outcome }),
+    onTerminalCleanup: (id) => terminalCleanupCalls.push(id),
+    onResume: (id, description) => resumeCalls.push({ agentId: id, description }),
+    now: () => currentTime,
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = intervals.findIndex((i) => i.ref === ref)
+      if (idx !== -1) intervals.splice(idx, 1)
+    },
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timeouts.push({ fn, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = timeouts.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timeouts.splice(idx, 1)
+    },
+    fs: mockFs,
+    log: (msg) => logs.push(msg),
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      intervals.sort((a, b) => a.fireAt - b.fireAt)
+      timeouts.sort((a, b) => a.fireAt - b.fireAt)
+      const nextI = intervals[0]
+      const nextT = timeouts[0]
+      const iReady = nextI && nextI.fireAt <= currentTime
+      const tReady = nextT && nextT.fireAt <= currentTime
+      if (!iReady && !tReady) break
+      if (tReady && (!iReady || nextT!.fireAt <= nextI!.fireAt)) {
+        timeouts.shift()
+        nextT!.fn()
+      } else {
+        nextI!.fireAt += nextI!.ms
+        nextI!.fn()
+      }
+    }
+  }
+
+  const setFile = (content: string): void => {
+    fileContents.set(jsonlPath, Buffer.from(content, 'utf-8'))
+  }
+  const append = (content: string): void => {
+    const cur = fileContents.get(jsonlPath) ?? Buffer.alloc(0)
+    fileContents.set(jsonlPath, Buffer.concat([cur, Buffer.from(content, 'utf-8')]))
+  }
+
+  return {
+    agentId,
+    progressCalls,
+    finishCalls,
+    terminalCleanupCalls,
+    resumeCalls,
+    logs,
+    advance,
+    watcher,
+    setFile,
+    append,
+  }
+}
+
+describe('subagent-watcher resume re-registration (issue #3315)', () => {
+  it('(a) re-registers a terminal-then-resumed worker so its progress card resumes', () => {
+    const agentId = 'resume-live'
+    const h = makeHarness({ agentId })
+
+    // A worker is dispatched post-boot: its JSONL appears with a running turn.
+    h.setFile(buildJSONL(subAgentUserMsg('bg task'), subAgentToolUse('Bash', 't1')))
+    h.advance(RESCAN_MS) // rescan discovers the file → LIVE registration
+
+    const registered = h.watcher.getRegistry().get(agentId)
+    expect(registered).toBeDefined()
+    expect(registered!.state).toBe('running')
+    expect(registered!.historical).toBe(false)
+
+    // It completes normally with a REAL turn_end.
+    h.append(buildJSONL(subAgentTurnEnd()))
+    h.advance(RESCAN_MS) // poll reads turn_end → done → onFinish(completed)
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('completed')
+
+    // Grace elapses → the entry is swept out of the registry.
+    h.advance(CLEANUP_GRACE_MS)
+    expect(h.watcher.getRegistry().has(agentId)).toBe(false)
+    expect(h.terminalCleanupCalls).toContain(agentId)
+
+    const progressBeforeResume = h.progressCalls.length
+
+    // SendMessage resume: Claude Code appends a NEW turn to the SAME JSONL.
+    h.append(buildJSONL(
+      subAgentUserMsg('follow-up question'),
+      subAgentToolUse('Read', 't2', { file_path: '/tmp/x' }),
+    ))
+    h.advance(RESCAN_MS) // rescan sees growth past terminal size → re-register
+
+    // The worker is tracked again — live, running, non-historical.
+    const revived = h.watcher.getRegistry().get(agentId)
+    expect(revived).toBeDefined()
+    expect(revived!.state).toBe('running')
+    expect(revived!.historical).toBe(false)
+    expect(h.logs.some((l) => l.includes('resumed after terminal cleanup') && l.includes(agentId))).toBe(true)
+
+    // Issue #3373: onResume fired exactly once for the resumed worker, BEFORE
+    // registration re-fires onProgress — this is what clears the feed's terminal
+    // `finalized` latch so the resumed cues re-surface a card instead of being
+    // swallowed. (The feed-side re-surface behaviour is covered in
+    // worker-activity-feed.test.ts.)
+    expect(h.resumeCalls.filter((c) => c.agentId === agentId)).toHaveLength(1)
+
+    // Progress cues resume (the card updates again) — the user-visible fix.
+    expect(h.progressCalls.length).toBeGreaterThan(progressBeforeResume)
+    expect(h.progressCalls.slice(progressBeforeResume).some((c) => c.agentId === agentId)).toBe(true)
+
+    // The completed turn was NOT replayed — no duplicate onFinish fired on
+    // re-registration (the old turn_end sits before the resume cursor).
+    expect(h.finishCalls).toHaveLength(1)
+
+    // When the resumed turn genuinely ends, onFinish fires again for the new
+    // turn — the resumed work gets its own handback.
+    h.append(buildJSONL(subAgentTurnEnd()))
+    h.advance(RESCAN_MS)
+    expect(h.finishCalls).toHaveLength(2)
+    expect(h.finishCalls[1].outcome).toBe('completed')
+
+    h.watcher.stop()
+  })
+
+  it('(b) a terminal worker that is NOT resumed stays cleaned up (no re-register, no duplicate handback)', () => {
+    const agentId = 'stay-clean'
+    const h = makeHarness({ agentId })
+
+    h.setFile(buildJSONL(subAgentUserMsg('bg task'), subAgentToolUse('Bash', 't1')))
+    h.advance(RESCAN_MS)
+    expect(h.watcher.getRegistry().has(agentId)).toBe(true)
+
+    h.append(buildJSONL(subAgentTurnEnd()))
+    h.advance(RESCAN_MS)
+    expect(h.finishCalls).toHaveLength(1)
+
+    h.advance(CLEANUP_GRACE_MS) // sweep
+    expect(h.watcher.getRegistry().has(agentId)).toBe(false)
+    const finishAfterCleanup = h.finishCalls.length
+    const progressAfterCleanup = h.progressCalls.length
+
+    // The JSONL stays on disk, static (Claude Code leaves it), and the worker
+    // is never resumed. Many rescans must NOT re-register it or re-fire the
+    // handback (issue #1116 Bug B guard preserved) — the reverse-bug direction.
+    for (let i = 0; i < 20; i++) h.advance(RESCAN_MS)
+
+    expect(h.watcher.getRegistry().has(agentId)).toBe(false)
+    expect(h.finishCalls).toHaveLength(finishAfterCleanup) // no duplicate
+    expect(h.progressCalls).toHaveLength(progressAfterCleanup) // no card churn
+    // Cleanup fired exactly once — no leaked/duplicated terminal sweep.
+    expect(h.terminalCleanupCalls.filter((id) => id === agentId)).toHaveLength(1)
+    // Issue #3373 anti-zombie: a genuinely-finished worker that never grew past
+    // its terminal boundary must NEVER fire onResume — otherwise the feed's
+    // finalized latch would be cleared and a dead worker could zombie-resurface.
+    expect(h.resumeCalls.filter((c) => c.agentId === agentId)).toHaveLength(0)
+
+    h.watcher.stop()
+  })
+})

package/telegram-plugin/tests/subagent-watcher-resurrection.test.ts

@@ -395,4 +395,36 @@ describe('subagent-watcher card resurrection (issue #3023)', () => {
     h.advance(500)
     expect(h.resurrectCalls).toHaveLength(1)
   })
+
+  it('(f) a false finish resumed after cleanup grace is owned by resurrection, not the #3315 resume path', () => {
+    // Non-interference guard (issue #3315 × #3023): once the terminal-cleanup
+    // grace has elapsed, a falsely-finalised worker's id sits in BOTH
+    // `terminatedAgentIds` (the #3315 resume-detection map) AND
+    // `falseFinishTracker`. Its JSONL resuming must be handled by the
+    // resurrection path (bounded-chain + onResurrect semantics), NOT
+    // double-handled by the scanSubagentsDir resume branch. The branch defers
+    // when a false-finish record exists.
+    const agentId = 'false-finish-post-grace'
+    const h = makeHarness({ agentId })
+
+    h.advance(500)
+    unmarkHistorical(h, agentId)
+
+    driveToFalseFinish(h, agentId)
+    // Let the 30s terminal-cleanup grace elapse so the entry is swept — its id
+    // is now in BOTH terminatedAgentIds and falseFinishTracker.
+    h.advance(30_000)
+    expect(h.watcher.getRegistry().has(agentId)).toBe(false)
+
+    // JSONL resumes growing.
+    h.appendActivity()
+    h.advance(500)
+
+    // Resurrected exactly once via the #3023 path...
+    expect(h.resurrectCalls).toHaveLength(1)
+    expect(h.watcher.getRegistry().get(agentId)?.state).toBe('running')
+    // ...and NOT re-registered by the #3315 resume branch (its log marker is
+    // absent — the branch deferred because a false-finish record existed).
+    expect(h.logs.some((l) => l.includes('resumed after terminal cleanup'))).toBe(false)
+  })
 })

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -647,6 +647,36 @@ describe('startSubagentWatcher', () => {
       h.poll()
       // The draft is staged, not yet resolved — no cue yet.
       // The very next event is a reply tool with matching text → SUPPRESS.
+      // #3231: feed the PREFIXED prod wire shape (mcp__…__stream_reply), the
+      // form real jsonl actually carries. Before the isReplyTool fix a bare
+      // REPLY_TOOLS.has() missed this and the draft was WRONGLY surfaced.
+      appendFileSync(jsonlPath, buildJSONL({
+        type: 'assistant',
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
+      }))
+      h.poll()
+      expect(narrativeCues.length).toBe(0)
+    })
+
+    it('narrative gate: a draft-then-reply sub_agent_text is SUPPRESSED with a BARE reply tool name too (#3231)', () => {
+      // Symmetric with the prefixed case above: bare 'stream_reply' can still
+      // arrive from non-MCP sources, so isReplyTool must match it as well.
+      const narrativeCues: string[] = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+      const h = startWatcherSync({
+        agentDir,
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
+        },
+      })
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo path')))
+      h.poll()
+      const answer = 'The repo is at /home/user/code/switchroom.'
+      appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText(answer)))
+      h.poll()
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
         message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
@@ -786,10 +816,11 @@ describe('startSubagentWatcher', () => {
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
       h.poll()
       const answer = 'The fix touches three files and adds a unit test for the double-Done case.'
-      // Final tool of the turn is stream_reply carrying the answer.
+      // Final tool of the turn is stream_reply carrying the answer. #3231: use
+      // the PREFIXED prod wire shape so lastReplyText capture (isReplyTool) fires.
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
-        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
       }))
       h.poll()
       // Trailing text block (separate message) that drafts the delivered answer.
@@ -819,9 +850,10 @@ describe('startSubagentWatcher', () => {
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
       h.poll()
       const answer = 'The fix touches three files and adds a unit test for the double-Done case.'
+      // #3231: prefixed prod wire shape.
       appendFileSync(jsonlPath, buildJSONL({
         type: 'assistant',
-        message: { content: [{ type: 'tool_use', name: 'stream_reply', id: 'r1', input: { text: answer } }] },
+        message: { content: [{ type: 'tool_use', name: 'mcp__switchroom-telegram__stream_reply', id: 'r1', input: { text: answer } }] },
       }))
       h.poll()
       appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('Done — cleaning up the worktree now.')))

package/telegram-plugin/tests/turn-end-gate-backstop.test.ts

@@ -4,10 +4,10 @@
  * Outcome contract: if a pre-purge op in the turn_end handler body THROWS
  * before the canonical purge (endCurrentTurnAtomic → purgeReactionTracking)
  * runs, the guarded finally must still clear this turn's gate state
- * (activeTurnStartedAt + the mirrored claudeBusyKeys) so the #1556 inbound
- * gate re-opens for the next inbound. On the happy path — where the body
- * clears the key itself — the backstop must be a no-op (no double purge), and
- * the original error must always propagate.
+ * (activeTurnStartedAt; the purge also emits the machine turnEnd) so the
+ * #1556 inbound gate re-opens for the next inbound. On the happy path —
+ * where the body clears the key itself — the backstop must be a no-op (no
+ * double purge), and the original error must always propagate.
  */
 import { describe, it, expect } from 'vitest'
 import { withTurnEndGateBackstop } from '../gateway/turn-end-gate-backstop.js'
@@ -22,19 +22,16 @@ function statusKey(chatId: string, threadId?: number): string {
 }
 
 /** Mirror of the production gate state + a purge that clears it, as
- * purgeReactionTracking does (activeTurnStartedAt.delete + claudeBusyKeys
- * drain for the key). */
+ * purgeReactionTracking does (activeTurnStartedAt.delete for the key). */
 function freshGate(turn: Turn) {
   const key = statusKey(turn.sessionChatId, turn.sessionThreadId)
   const activeTurnStartedAt = new Map<string, number>([[key, Date.now()]])
-  const claudeBusyKeys = new Set<string>([key])
   const purgeCalls: Array<{ key: string; endingTurn: Turn | undefined }> = []
   const purge = (k: string, endingTurn: Turn | undefined) => {
     purgeCalls.push({ key: k, endingTurn })
     activeTurnStartedAt.delete(k)
-    claudeBusyKeys.delete(k)
   }
-  return { key, activeTurnStartedAt, claudeBusyKeys, purge, purgeCalls }
+  return { key, activeTurnStartedAt, purge, purgeCalls }
 }
 
 function deps(gate: ReturnType<typeof freshGate>) {
@@ -58,10 +55,9 @@ describe('withTurnEndGateBackstop (#2094 finding 1)', () => {
       }, deps(gate)),
     ).toThrow('redactOutboundText blew up')
 
-    // Outcome: gate is OPEN again — both maps cleared, so the #1556 inbound
-    // gate no longer wedges the next inbound.
+    // Outcome: gate is OPEN again — the turn map is cleared, so the #1556
+    // inbound gate no longer wedges the next inbound.
     expect(gate.activeTurnStartedAt.has(gate.key)).toBe(false)
-    expect(gate.claudeBusyKeys.has(gate.key)).toBe(false)
     // The backstop fired exactly once, forwarding the ending turn.
     expect(gate.purgeCalls).toEqual([{ key: gate.key, endingTurn: turn }])
   })