switchroom 0.7.15 → 0.10.0

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

@@ -0,0 +1,316 @@
+/**
+ * Tests for SubagentWatcher's post-stall terminal-synthesis path
+ * (RFC §Bug 6 — background `Agent` dispatches in some Claude Code
+ * versions write a JSONL that never ends with `system + turn_duration`,
+ * so the canonical `sub_agent_turn_end` event never fires). Locks the
+ * contract that:
+ *
+ *  1. After `silentStallTerminalMs` past the stall notification, the
+ *     watcher synthesises terminal: flips `entry.state = 'done'`, fires
+ *     `onStallTerminal`, fires the existing `onFinish` audit surface.
+ *  2. Synthesis is idempotent: each entry triggers it at most once per
+ *     lifetime (no repeat fires on every poll tick once the window
+ *     elapses).
+ *  3. A pre-window unstall (JSONL activity resumes) clears `stalledAt`
+ *     and prevents synthesis. A subsequent re-stall starts the clock
+ *     from scratch.
+ *  4. Synthesis is suppressed for entries whose state is already `done`
+ *     or `failed` — only `running + stallNotified` entries qualify.
+ */
+
+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 subAgentTurnEnd() {
+  return { type: 'system', subtype: 'turn_duration', duration_ms: 1234 }
+}
+
+interface Harness {
+  stallCalls: Array<{ agentId: string; idleMs: number }>
+  stallTerminalCalls: Array<{ agentId: string; description: string }>
+  finishCalls: Array<{ agentId: string; outcome: string }>
+  unstallCalls: Array<{ agentId: string }>
+  logs: string[]
+  advance: (ms: number) => void
+  watcher: ReturnType<typeof startSubagentWatcher>
+  fileContents: Map<string, Buffer>
+  jsonlPath: string
+  appendActivity: () => void
+}
+
+function makeHarness(opts: {
+  agentId?: string
+  stallThresholdMs?: number
+  silentStallTerminalMs?: number
+  rescanMs?: number
+} = {}): Harness {
+  const {
+    agentId = 'bug6-agent',
+    stallThresholdMs = 60_000,
+    silentStallTerminalMs = 300_000,
+    rescanMs = 500,
+  } = opts
+
+  let currentTime = 1000
+  const stallCalls: Array<{ agentId: string; idleMs: number }> = []
+  const stallTerminalCalls: Array<{ agentId: string; description: string }> = []
+  const finishCalls: Array<{ agentId: string; outcome: string }> = []
+  const unstallCalls: Array<{ agentId: 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`
+
+  const fileContents = new Map<string, Buffer>()
+  fileContents.set(
+    jsonlPath,
+    Buffer.from(buildJSONL(subAgentUserMsg('bg task')), 'utf-8'),
+  )
+
+  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
+      if (fileContents.has(ps)) return true
+      return false
+    }) 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) return [`agent-${agentId}.jsonl`]
+      return []
+    }) as unknown as typeof fs.readdirSync,
+    statSync: ((p: fs.PathLike) => ({ size: fileContents.get(String(p))?.length ?? 0 }) 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 }> = []
+  let nextRef = 1
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    stallThresholdMs,
+    silentSynthesisStallThresholdMs: stallThresholdMs,
+    silentStallTerminalMs,
+    rescanMs,
+    sendNotification: () => {},
+    onStall: (id, idleMs) => stallCalls.push({ agentId: id, idleMs }),
+    onUnstall: (id) => unstallCalls.push({ agentId: id }),
+    onStallTerminal: (id, desc) => stallTerminalCalls.push({ agentId: id, description: desc }),
+    onFinish: ({ agentId: id, outcome }) => finishCalls.push({ agentId: id, outcome }),
+    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)
+    },
+    fs: mockFs,
+    log: (msg) => logs.push(msg),
+  })
+
+  const advance = (ms: number): void => {
+    currentTime += ms
+    for (;;) {
+      intervals.sort((a, b) => a.fireAt - b.fireAt)
+      const next = intervals[0]
+      if (!next || next.fireAt > currentTime) break
+      next.fireAt += next.ms
+      next.fn()
+    }
+  }
+
+  const appendActivity = (): void => {
+    // Append a `text` line so the watcher sees the JSONL grow and
+    // flips the entry out of "stalled" via the unstall path.
+    const cur = fileContents.get(jsonlPath) ?? Buffer.alloc(0)
+    const more = buildJSONL({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'still working' }] },
+    })
+    fileContents.set(jsonlPath, Buffer.concat([cur, Buffer.from(more, 'utf-8')]))
+  }
+
+  return {
+    stallCalls,
+    stallTerminalCalls,
+    finishCalls,
+    unstallCalls,
+    logs,
+    advance,
+    watcher,
+    fileContents,
+    jsonlPath,
+    appendActivity,
+  }
+}
+
+// Files present at boot are flagged historical=true and stall+synth
+// detection is suppressed for those (don't flood chat on restart).
+// Tests flip the flag to simulate a post-boot discovery — same pattern
+// as the existing stall-notification tests.
+function unmarkHistorical(harness: Harness, agentId: string): void {
+  const entry = harness.watcher.getRegistry().get(agentId)
+  if (entry) entry.historical = false
+}
+
+describe('subagent-watcher post-stall terminal synthesis (RFC §Bug 6)', () => {
+  it('synthesises terminal after silentStallTerminalMs past stall notification', () => {
+    const agentId = 'bug6-synth-1'
+    const h = makeHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 300_000,
+      rescanMs: 500,
+    })
+
+    h.advance(500) // register
+    unmarkHistorical(h, agentId)
+    h.advance(62_000) // stall fires
+    expect(h.stallCalls).toHaveLength(1)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    expect(h.finishCalls).toHaveLength(0)
+
+    // Advance to JUST BEFORE the post-stall window closes — synth must
+    // not fire yet.
+    h.advance(299_000)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    expect(h.finishCalls).toHaveLength(0)
+
+    // Cross the threshold — synthesis fires exactly once.
+    h.advance(2_000)
+    expect(h.stallTerminalCalls).toHaveLength(1)
+    expect(h.stallTerminalCalls[0].agentId).toBe(agentId)
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].agentId).toBe(agentId)
+    // The synthesised path uses outcome 'completed' so downstream
+    // consumers treat it the same as a real `sub_agent_turn_end` —
+    // the audit log entry distinguishes via the `synthesis` log line.
+    expect(h.finishCalls[0].outcome).toBe('completed')
+  })
+
+  it('is idempotent — does not re-fire on subsequent poll ticks', () => {
+    const agentId = 'bug6-synth-idempotent'
+    const h = makeHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 60_000,
+      rescanMs: 500,
+    })
+
+    h.advance(500)
+    unmarkHistorical(h, agentId)
+    h.advance(62_000)
+    h.advance(62_000) // synth fires
+    expect(h.stallTerminalCalls).toHaveLength(1)
+
+    // Many more polls past the window — synth must not re-fire.
+    h.advance(60_000)
+    h.advance(60_000)
+    h.advance(60_000)
+    expect(h.stallTerminalCalls).toHaveLength(1)
+    expect(h.finishCalls).toHaveLength(1)
+  })
+
+  it('a pre-window unstall resets the synthesis clock', () => {
+    const agentId = 'bug6-synth-unstall'
+    const h = makeHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 60_000,
+      rescanMs: 500,
+    })
+
+    h.advance(500)
+    unmarkHistorical(h, agentId)
+    h.advance(62_000) // stall fires
+    expect(h.stallCalls).toHaveLength(1)
+
+    // 30s into the post-stall window — append activity so the watcher
+    // sees JSONL growth and fires onUnstall.
+    h.advance(30_000)
+    h.appendActivity()
+    h.advance(1_000) // next poll reads the new bytes, fires onUnstall
+    expect(h.unstallCalls).toHaveLength(1)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+
+    // Advance another 60s past unstall — would have synthesised if the
+    // clock hadn't reset. It should not.
+    h.advance(60_000)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    expect(h.finishCalls).toHaveLength(0)
+  })
+
+  it('does NOT synthesise when an explicit sub_agent_turn_end lands inside the window', () => {
+    const agentId = 'bug6-synth-explicit-end'
+    const h = makeHarness({
+      agentId,
+      stallThresholdMs: 60_000,
+      silentStallTerminalMs: 300_000,
+      rescanMs: 500,
+    })
+
+    h.advance(500)
+    unmarkHistorical(h, agentId)
+    h.advance(62_000) // stall fires
+    expect(h.stallCalls).toHaveLength(1)
+
+    // 100s into the post-stall window the worker writes its terminal
+    // JSONL line — the watcher's existing turn_end path flips state to
+    // 'done' and fires onFinish with outcome='completed'. The synth
+    // path then sees state !== 'running' and skips.
+    h.advance(100_000)
+    const cur = h.fileContents.get(h.jsonlPath) ?? Buffer.alloc(0)
+    h.fileContents.set(
+      h.jsonlPath,
+      Buffer.concat([cur, Buffer.from(buildJSONL(subAgentTurnEnd()), 'utf-8')]),
+    )
+    h.advance(1_000)
+    expect(h.finishCalls).toHaveLength(1)
+    expect(h.finishCalls[0].outcome).toBe('completed')
+
+    // Cross the synth threshold — synth must NOT fire (the explicit
+    // path already terminated the entry).
+    h.advance(300_000)
+    expect(h.stallTerminalCalls).toHaveLength(0)
+    expect(h.finishCalls).toHaveLength(1) // unchanged
+  })
+})

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

@@ -879,4 +879,267 @@ describe('startSubagentWatcher', () => {
       h.watcher.stop()
     })
   })
+
+  // ─── Issue #1116 regressions ─────────────────────────────────────────────
+
+  describe('issue #1116 — project-dir slug filter (Bug A)', () => {
+    /**
+     * Claude Code keys its `.claude/projects/<slug>/` dirs off the cwd it
+     * was launched in. Over time an agent's home can accumulate stale
+     * project dirs from prior boots (or from a sibling agent that briefly
+     * shared the home via a wayward `CLAUDE_PROJECT_DIR`). Pre-#1116 the
+     * watcher enumerated every project dir under `<agentDir>/.claude/projects/`
+     * and registered any `agent-*.jsonl` it found, which produced phantom
+     * registry entries whose backing files vanish on the next session-cleanup
+     * tick (ENOENT spam + false stall notifications, per the issue's
+     * smoking-gun log).
+     *
+     * The fix: when `agentCwd` is supplied, the watcher restricts
+     * enumeration to the project dir whose slug matches
+     * `sanitizeCwdToProjectName(agentCwd)`. Foreign-slug shadow dirs are
+     * skipped entirely.
+     */
+
+    let tmpRoot = ''
+    const startedWatchers: Array<{ stop(): void }> = []
+
+    beforeEach(() => {
+      tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-watcher-1116-slug-'))
+    })
+
+    afterEach(() => {
+      while (startedWatchers.length) {
+        try { startedWatchers.pop()?.stop() } catch { /* ignore */ }
+      }
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+    })
+
+    function startWatcherSync(opts: { agentDir: string; agentCwd?: string }): {
+      notifications: string[]
+      logs: string[]
+      poll: () => void
+      watcher: ReturnType<typeof startSubagentWatcher>
+    } {
+      const notifications: string[] = []
+      const logs: string[] = []
+      const intervals: Array<{ fn: () => void; ref: number }> = []
+      const timeouts: Array<{ fn: () => void; ref: number }> = []
+      let nextRef = 1
+      const watcher = startSubagentWatcher({
+        agentDir: opts.agentDir,
+        ...(opts.agentCwd !== undefined ? { agentCwd: opts.agentCwd } : {}),
+        sendNotification: (text) => notifications.push(text),
+        stallThresholdMs: 60_000,
+        rescanMs: 500,
+        now: () => Date.now(),
+        setInterval: (fn) => {
+          const ref = nextRef++
+          intervals.push({ fn, ref })
+          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) => {
+          const ref = nextRef++
+          timeouts.push({ fn, 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)
+        },
+        log: (msg) => logs.push(msg),
+      })
+      startedWatchers.push(watcher)
+      return {
+        notifications,
+        logs,
+        poll: () => intervals[0]?.fn(),
+        watcher,
+      }
+    }
+
+    it('skips foreign-slug project dirs when agentCwd is provided', () => {
+      // Layout: an agent whose real cwd is /home/test/agent-own. Its
+      // home contains BOTH its own project dir (-home-test-agent-own)
+      // AND a stale foreign one (-home-test-agent-foreign) left over
+      // from a prior boot. Each contains a sub-agent JSONL with a
+      // distinct agentId.
+      const agentDir = join(tmpRoot, 'agent')
+      const agentCwd = '/home/test/agent-own'
+      const ownSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-own', 'sess-A', 'subagents')
+      const foreignSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-foreign', 'sess-B', 'subagents')
+      mkdirSync(ownSubagents, { recursive: true })
+      mkdirSync(foreignSubagents, { recursive: true })
+      writeFileSync(
+        join(ownSubagents, 'agent-ownworker.jsonl'),
+        buildJSONL(subAgentUserMsg('legit work')),
+      )
+      writeFileSync(
+        join(foreignSubagents, 'agent-foreignworker.jsonl'),
+        buildJSONL(subAgentUserMsg('stale shadow')),
+      )
+
+      const h = startWatcherSync({ agentDir, agentCwd })
+      h.poll()
+
+      const reg = h.watcher.getRegistry()
+      expect(reg.has('ownworker')).toBe(true)
+      expect(reg.has('foreignworker')).toBe(false)
+    })
+
+    it('does NOT emit "read error" ENOENT for foreign-slug files that vanish mid-scan', () => {
+      // Simulates the smoking-gun log line from the issue. Foreign-slug
+      // JSONL is deleted from disk before the watcher's first readSubTail.
+      // With the slug filter in place the foreign agent is never even
+      // registered, so no ENOENT log line is emitted.
+      const agentDir = join(tmpRoot, 'agent')
+      const agentCwd = '/home/test/agent-own'
+      const ownSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-own', 'sess-A', 'subagents')
+      const foreignSubagents = join(agentDir, '.claude', 'projects', '-home-test-agent-foreign', 'sess-B', 'subagents')
+      mkdirSync(ownSubagents, { recursive: true })
+      mkdirSync(foreignSubagents, { recursive: true })
+      writeFileSync(
+        join(ownSubagents, 'agent-ownworker.jsonl'),
+        buildJSONL(subAgentUserMsg('legit work')),
+      )
+      const foreignJsonl = join(foreignSubagents, 'agent-foreignworker.jsonl')
+      writeFileSync(foreignJsonl, buildJSONL(subAgentUserMsg('about to vanish')))
+
+      const h = startWatcherSync({ agentDir, agentCwd })
+      // Reap the foreign file the way Claude Code's session cleanup
+      // would, *before* the first poll runs.
+      rmSync(foreignJsonl)
+      h.poll()
+
+      // Polls should not produce a "read error … ENOENT" log line.
+      const enoentLogs = h.logs.filter((l) => l.includes('read error') && l.includes('ENOENT'))
+      expect(enoentLogs).toHaveLength(0)
+      // And the foreign agent must not be registered.
+      expect(h.watcher.getRegistry().has('foreignworker')).toBe(false)
+    })
+  })
+
+  describe('issue #1116 — terminal cleanup must not re-fire completion (Bug B)', () => {
+    /**
+     * Pre-#1116: after `TERMINAL_CLEANUP_GRACE_MS` (30s) elapsed,
+     * `cleanupTerminalAgent` deleted the agentId from `registry` and
+     * the JSONL path from `knownFiles`. The JSONL itself stayed on disk
+     * (Claude Code keeps the file). The next `rescanSubagentDirs` poll
+     * found the JSONL absent from `knownFiles`, re-added it, called
+     * `registerAgent` with a fresh `completionNotified=false` entry,
+     * read the terminal `turn_duration` line again, and fired a SECOND
+     * `✓ Worker done` notification. This loops every grace-window
+     * (~30s); for the operator it manifests as the same handful of
+     * sub-agents announcing completion every ~6 min indefinitely.
+     */
+
+    let tmpRoot = ''
+    const startedWatchers: Array<{ stop(): void }> = []
+
+    beforeEach(() => {
+      tmpRoot = mkdtempSync(join(tmpdir(), 'switchroom-watcher-1116-rerun-'))
+    })
+
+    afterEach(() => {
+      while (startedWatchers.length) {
+        try { startedWatchers.pop()?.stop() } catch { /* ignore */ }
+      }
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+    })
+
+    it('does NOT re-fire "Worker done" after terminal cleanup grace expires and rescan rediscovers the JSONL', () => {
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'sess-A', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-loopme.jsonl')
+
+      // Boot with an empty subagents dir, then write a post-boot JSONL so
+      // the agent is registered non-historical (otherwise the historical
+      // shortcut suppresses the completion notification entirely).
+      const notifications: string[] = []
+      const intervals: Array<{ fn: () => void; ref: number }> = []
+      const timeouts: Array<{ fn: () => void; ref: number }> = []
+      let nextRef = 1
+      const watcher = startSubagentWatcher({
+        agentDir,
+        sendNotification: (text) => notifications.push(text),
+        stallThresholdMs: 60_000,
+        rescanMs: 500,
+        now: () => Date.now(),
+        setInterval: (fn) => {
+          const ref = nextRef++
+          intervals.push({ fn, ref })
+          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) => {
+          const ref = nextRef++
+          timeouts.push({ fn, 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)
+        },
+        log: () => {},
+      })
+      startedWatchers.push(watcher)
+
+      const poll = () => intervals[0]?.fn()
+      const fireScheduledCleanups = () => {
+        let fired = 0
+        while (timeouts.length) {
+          const next = timeouts.shift()!
+          next.fn()
+          fired++
+        }
+        return fired
+      }
+
+      // Step 1: post-boot, write an in-flight JSONL → poll registers it.
+      writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+      poll()
+      expect(watcher.getRegistry().has('loopme')).toBe(true)
+      expect(watcher.getRegistry().get('loopme')?.historical).toBe(false)
+
+      // Step 2: append turn_duration → poll → state=done → "Worker done" fires.
+      appendFileSync(jsonlPath, buildJSONL(subAgentTurnDuration()))
+      poll()
+      const firstRoundNotifs = notifications.filter((n) => n.includes('Worker done'))
+      expect(firstRoundNotifs).toHaveLength(1)
+
+      // Step 3: fire the terminal-cleanup grace timer (drains the
+      // scheduled cleanup). Registry entry should be gone.
+      const fired = fireScheduledCleanups()
+      expect(fired).toBeGreaterThan(0)
+      expect(watcher.getRegistry().has('loopme')).toBe(false)
+
+      // Step 4: the JSONL is STILL on disk — Claude Code doesn't delete
+      // it after the sub-agent finishes. The next poll re-scans the dir
+      // and finds the file. Pre-fix: re-registers the agent and fires a
+      // SECOND "Worker done". Post-fix: re-discovery is a no-op for
+      // an agentId we've already announced as terminal.
+      poll()
+      const afterRescanNotifs = notifications.filter((n) => n.includes('Worker done'))
+      expect(
+        afterRescanNotifs.length,
+        `Expected exactly 1 "Worker done" notification, got ${afterRescanNotifs.length}: ${JSON.stringify(afterRescanNotifs)}`,
+      ).toBe(1)
+
+      // And another poll for good measure — still exactly one.
+      poll()
+      poll()
+      expect(notifications.filter((n) => n.includes('Worker done'))).toHaveLength(1)
+    })
+  })
 })

package/telegram-plugin/tests/turn-signal-tracker.test.ts

@@ -2,8 +2,10 @@ import { describe, it, expect, beforeEach } from 'vitest'
 import {
   reset,
   noteSignal,
+  noteOutbound,
   getLongestGap,
   getLastSignalAt,
+  getOutboundMetrics,
   clear,
   __resetAllForTests,
 } from '../turn-signal-tracker.js'
@@ -105,3 +107,82 @@ describe('turn-signal-tracker', () => {
     expect(getLongestGap(k)).toBe(0)
   })
 })
+
+describe('turn-signal-tracker — outbound metrics (#1122)', () => {
+  it('a turn with zero outbound messages reports ttfoMs=null, count=0, gap=0', () => {
+    reset('k', 1000)
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBeNull()
+    expect(m.outboundCount).toBe(0)
+    expect(m.longestOutboundGapMs).toBe(0)
+  })
+
+  it('first noteOutbound() records TTFO = (now - turnStartedAt)', () => {
+    reset('k', 1000)
+    noteOutbound('k', 1750)
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBe(750)
+    expect(m.outboundCount).toBe(1)
+    expect(m.longestOutboundGapMs).toBe(0) // single message — no gap yet
+  })
+
+  it('multiple outbound messages compute the longest gap between them', () => {
+    reset('k', 0)
+    noteOutbound('k', 100)   // ttfo=100, no gap
+    noteOutbound('k', 200)   // gap=100
+    noteOutbound('k', 1700)  // gap=1500 (longest)
+    noteOutbound('k', 1800)  // gap=100
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBe(100)
+    expect(m.outboundCount).toBe(4)
+    expect(m.longestOutboundGapMs).toBe(1500)
+  })
+
+  it('noteOutbound() on an unknown key is a no-op', () => {
+    noteOutbound('untracked', 1000)
+    const m = getOutboundMetrics('untracked')
+    expect(m.ttfoMs).toBeNull()
+    expect(m.outboundCount).toBe(0)
+  })
+
+  it('reset() clears outbound state from prior turn', () => {
+    reset('k', 0)
+    noteOutbound('k', 100)
+    noteOutbound('k', 5000) // big gap
+    reset('k', 10000) // new turn
+    noteOutbound('k', 10100)
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBe(100)
+    expect(m.outboundCount).toBe(1)
+    expect(m.longestOutboundGapMs).toBe(0)
+  })
+
+  it('clear() wipes outbound state too', () => {
+    reset('k', 0)
+    noteOutbound('k', 100)
+    clear('k')
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBeNull()
+    expect(m.outboundCount).toBe(0)
+  })
+
+  it('outbound and signal counters track independently', () => {
+    reset('k', 0)
+    // Many signals (status reaction churn) but only one outbound
+    noteSignal('k', 100)
+    noteSignal('k', 500)
+    noteSignal('k', 2500)
+    noteOutbound('k', 3000) // first outbound, ttfo=3000
+    const m = getOutboundMetrics('k')
+    expect(m.ttfoMs).toBe(3000)
+    expect(m.outboundCount).toBe(1)
+    // Signal-gap reflects ALL signals (including reactions)
+    expect(getLongestGap('k')).toBeGreaterThanOrEqual(1000)
+  })
+
+  it('TTFO = 0 when first outbound fires at exact turn-start tick', () => {
+    reset('k', 5000)
+    noteOutbound('k', 5000)
+    expect(getOutboundMetrics('k').ttfoMs).toBe(0)
+  })
+})