switchroom 0.5.0

package/telegram-plugin/tests/progress-card-driver-eviction.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Regression: TTL eviction of internal dedup maps must NOT depend on the
+ * heartbeat tick. The heartbeat stops whenever `chats.size === 0`, so any
+ * eviction inside it leaves `seenEnqueueMsgIds` and `pendingSyncEchoes` to
+ * grow unbounded across idle periods. Outer-base-key entries
+ * (`chatRunningSubagents`, `baseTurnSeqs`) likewise need an explicit
+ * cleanup hook on chat-close because nothing else ever drops them.
+ *
+ * Fix shape: an inline throttled `maybeEvict(now)` runs at the top of
+ * every public ingress, and `completeTurnFully` calls
+ * `cleanupBaseKeyIfUnused` after `chats.delete`.
+ */
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import type { SessionEvent } from '../session-tail.js'
+
+let nextMsgId = 9000
+
+function harness() {
+  let now = 1000
+  const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+  let nextRef = 0
+  const emits: Array<{ chatId: string; threadId?: string; turnKey: string; html: string; done: boolean }> = []
+
+  const driver = createProgressDriver({
+    emit: (a) => emits.push(a),
+    minIntervalMs: 0,
+    coalesceMs: 0,
+    initialDelayMs: 0,
+    heartbeatMs: 5000,
+    now: () => now,
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const target = (handle as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === target)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+  })
+
+  const advance = (ms: number): void => {
+    now += ms
+    for (;;) {
+      timers.sort((a, b) => a.fireAt - b.fireAt)
+      const next = timers[0]
+      if (!next || next.fireAt > now) break
+      if (next.repeat != null) {
+        next.fireAt += next.repeat
+        next.fn()
+      } else {
+        timers.shift()
+        next.fn()
+      }
+    }
+  }
+
+  return { driver, emits, advance, getNow: () => now }
+}
+
+function enqueue(chatId: string, threadId?: string): SessionEvent {
+  return {
+    kind: 'enqueue',
+    chatId,
+    messageId: String(nextMsgId++),
+    threadId: threadId ?? null,
+    rawContent: `<channel chat_id="${chatId}">hi</channel>`,
+  }
+}
+
+describe('progress-card-driver: TTL eviction off the heartbeat', () => {
+  it('seenEnqueueMsgIds and pendingSyncEchoes stay bounded across idle periods (chats.size==0)', () => {
+    const { driver, advance } = harness()
+    const maps = driver._debugGetMaps!()
+
+    // Drive 20 turn enqueue->complete cycles, advancing past the 60s TTL
+    // between cycles. Critically, chats.size returns to 0 between cycles,
+    // so the heartbeat stops — exposing the leak the fix targets.
+    for (let i = 0; i < 20; i++) {
+      driver.ingest(enqueue('chatA'), null)
+      driver.ingest({ kind: 'turn_end', durationMs: 100 }, 'chatA')
+      // Advance well past both TTLs (60s for messageIds, 30s for echoes)
+      // and past the eviction throttle (30s) so the next ingest evicts.
+      advance(65_000)
+      expect(maps.chats.size).toBe(0)
+    }
+
+    // After 20 cycles spread across >20 minutes of fake time, both dedup
+    // maps must be tiny — they should never accumulate stale entries.
+    expect(maps.seenEnqueueMsgIds.size).toBeLessThanOrEqual(1)
+    expect(maps.pendingSyncEchoes.size).toBeLessThanOrEqual(1)
+  })
+
+  it('chatRunningSubagents and baseTurnSeqs drop their base-key on full chat close', () => {
+    const { driver, advance } = harness()
+    const maps = driver._debugGetMaps!()
+
+    for (let i = 0; i < 20; i++) {
+      driver.ingest(enqueue('chatA'), null)
+      driver.ingest({ kind: 'sub_agent_started', agentId: `agent-${i}`, firstPromptText: 'x' }, 'chatA')
+      driver.ingest({ kind: 'sub_agent_turn_end', agentId: `agent-${i}`, durationMs: 50 }, 'chatA')
+      driver.ingest({ kind: 'turn_end', durationMs: 100 }, 'chatA')
+      advance(65_000)
+      // Between turns, no chat is alive — outer base-key entries must be
+      // gone too.
+      expect(maps.chats.size).toBe(0)
+      expect(maps.chatRunningSubagents.size).toBe(0)
+      expect(maps.baseTurnSeqs.size).toBe(0)
+    }
+  })
+
+  it('two chats sharing a baseKey: closing one does NOT delete the shared outer key', () => {
+    // baseKey collapses (chatId, threadId) pairs with no thread to a single
+    // string. Two threads on the same chat share a base only if they have
+    // the same threadId; two distinct chatIds always have distinct bases.
+    // Within a single chat, multiple concurrent turn-keys share the same
+    // base — closing one of them must NOT prematurely drop the outer key
+    // while the other turn is still alive.
+    const { driver } = harness()
+    const maps = driver._debugGetMaps!()
+
+    // Start turn 1 on chatA — synthesises an enqueue and creates the card.
+    driver.startTurn({ chatId: 'chatA', userText: 'first' })
+    expect(maps.chats.size).toBe(1)
+    expect(maps.baseTurnSeqs.get('chatA')).toBeGreaterThanOrEqual(1)
+
+    // A second startTurn on the same chat force-closes turn 1 and creates
+    // turn 2 — there is exactly one chat live again, but baseTurnSeqs has
+    // ticked to 2. That outer entry must remain because turn 2 is alive.
+    driver.startTurn({ chatId: 'chatA', userText: 'second' })
+    expect(maps.chats.size).toBe(1)
+    const seqAfter = maps.baseTurnSeqs.get('chatA')
+    expect(seqAfter).toBeGreaterThanOrEqual(2)
+
+    // End turn 2 → chats empty → base-key cleanup must run.
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, 'chatA')
+    expect(maps.chats.size).toBe(0)
+    expect(maps.baseTurnSeqs.has('chatA')).toBe(false)
+    expect(maps.chatRunningSubagents.has('chatA')).toBe(false)
+  })
+
+  it('two distinct chats: closing one does NOT touch the other base-key', () => {
+    // The driver routes turn_end via `currentTurnKey`, not `chatIdMaybe` —
+    // a quirk of the session-tail single-stream design. To close a specific
+    // chat from a test we use `forceCompleteTurn`, which is the path the
+    // gateway invokes for explicit per-chat fan-out.
+    const { driver } = harness()
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('chatA'), null)
+    driver.ingest(enqueue('chatB'), null)
+    expect(maps.chats.size).toBe(2)
+    expect(maps.baseTurnSeqs.has('chatA')).toBe(true)
+    expect(maps.baseTurnSeqs.has('chatB')).toBe(true)
+
+    // Close A only — must not touch chatB's base-key.
+    driver.forceCompleteTurn({ chatId: 'chatA' })
+    expect(maps.baseTurnSeqs.has('chatA')).toBe(false)
+    expect(maps.baseTurnSeqs.has('chatB')).toBe(true)
+
+    // Now close B.
+    driver.forceCompleteTurn({ chatId: 'chatB' })
+    expect(maps.baseTurnSeqs.has('chatB')).toBe(false)
+    expect(maps.chats.size).toBe(0)
+  })
+
+  it('PR-C2 follow-up: bg-subagent-carry guard — chatRunningSubagents inner map survives turn_end while a sub-agent is still in flight', () => {
+    // When parent turn_end fires but a sub-agent is still running, the
+    // chatState enters pendingCompletion and the per-base
+    // `chatRunningSubagents` inner map MUST NOT be cleaned up — the
+    // next turn's enqueue will clone it back into the new fleet
+    // (issue #334 / #64). Cleanup on close is gated on the inner map
+    // being empty.
+    const { driver } = harness()
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('chatA'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use', toolName: 'Agent', toolUseId: 'tu1',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      'chatA',
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg' }, 'chatA')
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, 'chatA')
+    driver.recordOutboundDelivered('chatA')
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, 'chatA')
+
+    // Pending — chats.size==1 (originating bg-pending state survives).
+    expect(maps.chats.size).toBe(1)
+    // Critical: the running-subagents inner map for 'chatA' must still
+    // contain saBG. If cleanupBaseKeyIfUnused regressed and ran here,
+    // the next turn would lose the bg carry.
+    expect(maps.chatRunningSubagents.get('chatA')?.has('saBG')).toBe(true)
+
+    // Resolve the bg sub-agent; now full close should also drain the
+    // sync registry inner map.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, 'chatA')
+    expect(maps.chats.size).toBe(0)
+    expect(maps.chatRunningSubagents.has('chatA')).toBe(false)
+  })
+})

package/telegram-plugin/tests/progress-card-driver-fleet-shadow.test.ts

@@ -0,0 +1,123 @@
+/**
+ * P0 of #662 — invariant test that the driver's `fleet` shadow Map
+ * stays in lockstep with the legacy `chatState.subAgents` map across a
+ * full sub-agent lifecycle.
+ *
+ * We drive the real driver via createProgressDriver (no Telegram bot
+ * required — the emit callback just records calls) and feed a complete
+ * lifecycle: started → 3× tool_use → tool_result(isError=true) →
+ * turn_end. After every event we assert:
+ *   - cardinality matches between fleet and subAgents
+ *   - on terminal turn_end: status='failed' (errorSeen accumulated)
+ *   - originatingTurnKey was snapshotted from currentTurnKey
+ *   - lastTool reflects the most recent tool_use's sanitised arg
+ */
+
+import { describe, it, expect } from 'vitest'
+import { createProgressDriver } from '../progress-card-driver.js'
+import type { SessionEvent } from '../session-tail.js'
+
+function harness() {
+  let now = 1000
+  const timers: Array<{ fireAt: number; fn: () => void; ref: number; repeat?: number }> = []
+  let nextRef = 0
+  const driver = createProgressDriver({
+    emit: () => {},
+    minIntervalMs: 500,
+    coalesceMs: 400,
+    initialDelayMs: 0,
+    promoteAfterMs: 999_999,
+    now: () => now,
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref })
+      return { ref }
+    },
+    clearTimeout: (h) => {
+      const ref = (h as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      timers.push({ fireAt: now + ms, fn, ref, repeat: ms })
+      return { ref }
+    },
+    clearInterval: (h) => {
+      const ref = (h as { ref: number }).ref
+      const idx = timers.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timers.splice(idx, 1)
+    },
+  })
+  return { driver, advance: (ms: number) => { now += ms } }
+}
+
+const enqueue = (chatId: string): SessionEvent => ({
+  kind: 'enqueue',
+  chatId,
+  messageId: '1',
+  threadId: null,
+  rawContent: `<channel chat_id="${chatId}">go</channel>`,
+})
+
+describe('driver fleet-state shadow', () => {
+  it('shadow Map stays in lockstep with chatState.subAgents through a failed sub-agent lifecycle', () => {
+    const { driver } = harness()
+    const CHAT = 'c1'
+    driver.ingest(enqueue(CHAT), null)
+
+    const events: SessionEvent[] = [
+      { kind: 'sub_agent_started', agentId: 'sa1', firstPromptText: 'do work', subagentType: 'worker' },
+      { kind: 'sub_agent_tool_use', agentId: 'sa1', toolUseId: 't1', toolName: 'Read', input: { file_path: '/etc/secrets/k.key' } },
+      { kind: 'sub_agent_tool_use', agentId: 'sa1', toolUseId: 't2', toolName: 'Bash', input: { command: 'ls' } },
+      { kind: 'sub_agent_tool_use', agentId: 'sa1', toolUseId: 't3', toolName: 'Edit', input: { file_path: '/tmp/x.ts' } },
+      { kind: 'sub_agent_tool_result', agentId: 'sa1', toolUseId: 't3', isError: true, errorText: 'boom' },
+    ]
+
+    for (const ev of events) {
+      driver.ingest(ev, CHAT)
+      const state = driver.peek(CHAT)
+      const fleet = driver.peekFleet(CHAT)
+      expect(state).toBeDefined()
+      expect(fleet).toBeDefined()
+      // Cardinality invariant — every sub-agent in the legacy map has a
+      // shadow entry, and vice versa.
+      expect(fleet!.size).toBe(state!.subAgents.size)
+      for (const id of state!.subAgents.keys()) {
+        expect(fleet!.has(id)).toBe(true)
+      }
+    }
+
+    // Pre-turn-end: fleet member exists, status still running, errorSeen true.
+    const midFleet = driver.peekFleet(CHAT)!
+    const midMember = midFleet.get('sa1')!
+    expect(midMember.status).toBe('running')
+    expect(midMember.errorSeen).toBe(true)
+    expect(midMember.toolCount).toBe(3)
+    expect(midMember.lastTool).toEqual({ name: 'Edit', sanitisedArg: 'x.ts' })
+    expect(midMember.role).toBe('worker') // from subagentType fallback
+    // Snapshotted from currentTurnKey at sub_agent_started.
+    expect(midMember.originatingTurnKey).toMatch(/^c1:/)
+
+    // Now end the sub-agent's turn — fleet member should flip to failed.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'sa1' }, CHAT)
+    const finalFleet = driver.peekFleet(CHAT)!
+    const finalMember = finalFleet.get('sa1')!
+    expect(finalMember.status).toBe('failed')
+    expect(finalMember.terminalAt).not.toBeNull()
+  })
+
+  it('uses description as role when present', () => {
+    const { driver } = harness()
+    driver.ingest(enqueue('c2'), null)
+    // session-tail's sub_agent_started doesn't carry description directly,
+    // but the watcher path supplies subagentType — verify the fallback chain
+    // works when neither is set: first 20 chars of firstPromptText.
+    driver.ingest(
+      { kind: 'sub_agent_started', agentId: 'sa2', firstPromptText: 'investigate the auth bug end-to-end' },
+      'c2',
+    )
+    const m = driver.peekFleet('c2')!.get('sa2')!
+    expect(m.role).toBe('investigate the auth')
+  })
+})

package/telegram-plugin/tests/progress-card-driver-force-complete-parent-done.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Regression: forceCompleteTurn must set `parentTurnEndAt` so the heartbeat's
+ * `parentDone` branch lights up and the elapsed counter keeps ticking through
+ * `subAgentTickIntervalMs` while sub-agents are still running.
+ *
+ * Bug shape (#686, fixed in #687): forceCompleteTurn reduced `turn_end` but
+ * never set `parentTurnEndAt`. The heartbeat's `parentDone` was therefore
+ * always false during the deferred-unpin window, the elapsed-ticker bypass
+ * never engaged, and the rendered card froze on its last emit until the
+ * sub-agents finished.
+ *
+ * Test shape: spawn a sub-agent, call forceCompleteTurn, then advance fake
+ * time across several heartbeat ticks. The "Done" header (parentDone branch
+ * of the renderer) MUST appear and elapsed time MUST keep advancing in the
+ * emitted HTML.
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('progress-card-driver: forceCompleteTurn unfreezes elapsed-ticker', () => {
+  it('parentDone engages and elapsed advances after forceCompleteTurn while a sub-agent is still running', () => {
+    const { driver, emits, advance } = makeHarness({
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      heartbeatMs: 1_000,
+    })
+    const CHAT = 'chatF'
+
+    driver.ingest(enqueue(CHAT), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg work', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg work' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+
+    // External completion signal (e.g. stream_reply done=true). Sub-agent
+    // is still running, so the chatState enters pendingCompletion and the
+    // heartbeat keeps the card alive.
+    driver.forceCompleteTurn({ chatId: CHAT })
+
+    // The flush triggered by forceCompleteTurn itself produces an emit
+    // with the parentDone-branch ("Done") header.
+    const emitsAfterForce = emits.length
+    expect(emitsAfterForce).toBeGreaterThan(0)
+    const renderedAtForce = emits[emitsAfterForce - 1].html
+    // The renderer surfaces "Background" once parentDone=true and a bg
+    // sub-agent is still running; if the bug regresses (parentTurnEndAt
+    // stays null), parentDone is false and we'd see "Working".
+    expect(renderedAtForce).toMatch(/Background/)
+    expect(renderedAtForce).not.toMatch(/Working/)
+
+    // Advance well past the elapsed-ticker interval to prove the
+    // heartbeat keeps emitting fresh elapsed values rather than freezing
+    // on the last emit. Several ticks should produce at least one extra
+    // emit with different rendered HTML.
+    advance(15_000)
+    const tailEmits = emits.slice(emitsAfterForce)
+    expect(tailEmits.length).toBeGreaterThan(0)
+    // At least one post-force emit must differ from the force-emit HTML —
+    // proving the elapsed counter advanced rather than freezing.
+    const advanced = tailEmits.some((e) => e.html !== renderedAtForce)
+    expect(advanced).toBe(true)
+
+    // Resolve the sub-agent and assert the deferred completion fires.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, CHAT)
+    const finalEmit = emits[emits.length - 1]
+    expect(finalEmit.done).toBe(true)
+  })
+})

package/telegram-plugin/tests/progress-card-edit-timestamps-budget.test.ts

@@ -0,0 +1,62 @@
+/**
+ * PR-C2 — `editTimestamps` sliding-window cleanup must keep the array
+ * bounded under sustained burst.
+ *
+ * The driver maintains a per-turn array of recent emit timestamps and
+ * uses its length within the trailing 60s to flip "hot" mode (longer
+ * coalesce window). The cleanup is `while (arr[0] < cutoff) arr.shift()`,
+ * which only fires when `recordEdit` or `isBudgetHot` is called. If
+ * that cleanup ever regresses, the array would grow unbounded across a
+ * long-running turn.
+ *
+ * fails when: the `arr.shift()` cleanup is removed from `recordEdit` or
+ * `isBudgetHot`, OR the cutoff window is widened beyond 60s without a
+ * matching upper bound.
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('PR-C2: editTimestamps stays bounded under sustained emit burst', () => {
+  it('after 100 emits spread across 5 minutes, the per-turn array holds <= ~window-worth', () => {
+    // Use very low coalesce so each ingest can drive an emit. Keep the
+    // turn open for the whole burst.
+    const { driver, advance } = makeHarness({
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      heartbeatMs: 999_999, // never auto-fire heartbeat
+      promoteAfterMs: 999_999,
+    })
+    const maps = driver._debugGetMaps!()
+
+    driver.ingest(enqueue('cA'), null)
+
+    // Drive 100 events spaced 3s apart — so the trailing 60s only ever
+    // contains ~21 timestamps. With a working sliding-window cleanup the
+    // array should stay bounded near that figure.
+    for (let i = 0; i < 100; i++) {
+      driver.ingest(
+        {
+          kind: 'tool_use',
+          toolName: 'Read',
+          toolUseId: `tu${i}`,
+          input: { file_path: `/tmp/${i}.txt` },
+        },
+        'cA',
+      )
+      advance(3000)
+    }
+
+    // Find the per-turn timestamp array. The key is the active turnKey;
+    // there's only one turn so we can pick it.
+    const sizes = [...maps.editTimestamps.values()].map((a) => a.length)
+    expect(sizes.length).toBeGreaterThan(0)
+    const max = Math.max(...sizes)
+    // 60s window / 3s spacing = 20 entries. Allow tight slack (<= 22)
+    // for one or two boundary timestamps recorded by the harness's
+    // setup (initial enqueue, etc.) — anything looser fails to catch
+    // off-by-N regressions in the sliding-window cleanup.
+    expect(max).toBeLessThanOrEqual(22)
+    // And critically, NOT 100+ — that would mean cleanup never ran.
+    expect(max).toBeLessThan(100)
+  })
+})

package/telegram-plugin/tests/progress-card-memory-bounds.test.ts

@@ -0,0 +1,84 @@
+/**
+ * PR-C2 — end-to-end memory bounds: drive 100 turn cycles and assert
+ * every internal Map remains bounded.
+ *
+ * Companion to PR-B's targeted eviction test, which drove only 20
+ * cycles and asserted on `seenEnqueueMsgIds` / `pendingSyncEchoes`.
+ * This larger run is a regression net for "everything else" — if a
+ * future refactor forgets to evict any new map keyed by chat/turn,
+ * the size invariant blows up here even when the PR-B test still
+ * passes.
+ *
+ * fails when: any of the per-chat/per-turn Maps in `_debugGetMaps`
+ * grows linearly with turn count (e.g. cleanup is removed from
+ * completeTurnFully, or a new Map is added without an eviction hook).
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('PR-C2: end-to-end memory bounds across 100 turn cycles', () => {
+  it('all _debugGetMaps Maps stay bounded', () => {
+    const { driver, advance } = makeHarness({
+      heartbeatMs: 5_000,
+      promoteAfterMs: 999_999,
+    })
+    const maps = driver._debugGetMaps!()
+
+    for (let i = 0; i < 100; i++) {
+      driver.ingest(enqueue('chatA'), null)
+      driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, 'chatA')
+      driver.recordOutboundDelivered('chatA')
+      driver.ingest({ kind: 'turn_end', durationMs: 50 }, 'chatA')
+      // Advance well past TTLs (60s) and the eviction throttle (~30s).
+      advance(65_000)
+    }
+
+    expect(maps.chats.size).toBe(0)
+    expect(maps.chatRunningSubagents.size).toBe(0)
+    expect(maps.baseTurnSeqs.size).toBe(0)
+    // The dedup maps may keep at most one straggler from the final turn.
+    expect(maps.seenEnqueueMsgIds.size).toBeLessThanOrEqual(1)
+    expect(maps.pendingSyncEchoes.size).toBeLessThanOrEqual(1)
+    // editTimestamps is per-turnKey; cleared on completeTurnFully.
+    expect(maps.editTimestamps.size).toBeLessThanOrEqual(1)
+  })
+
+  it('with a long-lived bg sub-agent across cycles, only the originating turnKey persists', () => {
+    const { driver, advance } = makeHarness({
+      heartbeatMs: 5_000,
+      promoteAfterMs: 999_999,
+    })
+    const maps = driver._debugGetMaps!()
+
+    // One bg sub-agent that NEVER finishes; 50 surrounding turns close cleanly.
+    driver.ingest(enqueue('chatA'), null)
+    driver.ingest(
+      {
+        kind: 'tool_use', toolName: 'Agent', toolUseId: 'tu1',
+        input: { prompt: 'forever-bg', run_in_background: true },
+      },
+      'chatA',
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'forever-bg' }, 'chatA')
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, 'chatA')
+    driver.recordOutboundDelivered('chatA')
+    driver.ingest({ kind: 'turn_end', durationMs: 50 }, 'chatA')
+
+    for (let i = 0; i < 50; i++) {
+      driver.ingest(enqueue('chatA'), null)
+      driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, 'chatA')
+      driver.recordOutboundDelivered('chatA')
+      driver.ingest({ kind: 'turn_end', durationMs: 50 }, 'chatA')
+      advance(65_000)
+    }
+
+    // After 50 clean surrounding turns each followed by `advance(65_000)`
+    // (well past TTL + eviction throttle), every chatState — including
+    // the originating one whose bg sub-agent never finished — has been
+    // rolled forward and evicted. Empty is the correct steady state, not
+    // the "≤ 2" the original PR shipped. What this test really proves
+    // is that `chats` doesn't grow with cycle count.
+    expect(maps.chats.size).toBe(0)
+    expect(maps.baseTurnSeqs.size).toBeLessThanOrEqual(1)
+  })
+})