switchroom 0.5.0

package/telegram-plugin/tests/pin-event-log.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Tests for the structured pin/unpin event logger — the module that
+ * emits one JSON line per pin API interaction so operators can audit
+ * the pin lifecycle without parsing free-form log text.
+ *
+ * Covers spec `docs/pinned-progress-card-reliability.md` §6.1 and T9.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  logPinEvent,
+  classifyPinError,
+  errorMessage,
+  type PinEvent,
+} from "../pin-event-log.js";
+
+describe("logPinEvent", () => {
+  it("writes one JSON line prefixed with 'pin-event: '", () => {
+    const lines: string[] = [];
+    const ev: PinEvent = {
+      event: "pin",
+      chatId: "100",
+      messageId: 42,
+      turnKey: "100::1",
+      outcome: "ok",
+      durationMs: 123,
+    };
+    logPinEvent(ev, (line) => lines.push(line));
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toMatch(/^pin-event: /);
+    expect(lines[0].endsWith("\n")).toBe(true);
+    const payload = JSON.parse(lines[0].replace(/^pin-event: /, "").trimEnd());
+    expect(payload).toEqual(ev);
+  });
+
+  it("preserves all optional fields that are set", () => {
+    const lines: string[] = [];
+    logPinEvent(
+      {
+        event: "unpin-retry",
+        chatId: "c",
+        messageId: 7,
+        turnKey: "c::2",
+        outcome: "rate-limited",
+        error: "Too Many Requests",
+        durationMs: 1050,
+      },
+      (line) => lines.push(line),
+    );
+    const payload = JSON.parse(lines[0].replace(/^pin-event: /, "").trimEnd());
+    expect(payload.error).toBe("Too Many Requests");
+    expect(payload.outcome).toBe("rate-limited");
+    expect(payload.event).toBe("unpin-retry");
+  });
+
+  it("omits undefined optional fields cleanly", () => {
+    const lines: string[] = [];
+    logPinEvent(
+      {
+        event: "sweep-pin",
+        chatId: "c",
+        outcome: "ok",
+      },
+      (line) => lines.push(line),
+    );
+    const raw = lines[0].replace(/^pin-event: /, "").trimEnd();
+    expect(raw).not.toContain("undefined");
+    const payload = JSON.parse(raw);
+    expect(payload.error).toBeUndefined();
+    expect(payload.messageId).toBeUndefined();
+  });
+});
+
+describe("classifyPinError", () => {
+  it("returns 'rate-limited' for Telegram 429", () => {
+    expect(
+      classifyPinError({ error_code: 429, description: "Too Many Requests: retry after 2" }),
+    ).toBe("rate-limited");
+  });
+
+  it("returns 'forbidden' for Telegram 403", () => {
+    expect(classifyPinError({ error_code: 403, description: "Forbidden: bot was kicked" })).toBe(
+      "forbidden",
+    );
+  });
+
+  it("falls back to message substring match when error_code is absent", () => {
+    expect(classifyPinError(new Error("Bad Request: not enough rights to manage pins"))).toBe(
+      "forbidden",
+    );
+    expect(classifyPinError(new Error("connect ETIMEDOUT 1.2.3.4:443"))).toBe("timeout");
+  });
+
+  it("returns 'fail' for any unrecognised error shape", () => {
+    expect(classifyPinError(new Error("weird unexpected failure"))).toBe("fail");
+    expect(classifyPinError("random string")).toBe("fail");
+    expect(classifyPinError({})).toBe("fail");
+  });
+
+  it("returns 'fail' for null/undefined", () => {
+    expect(classifyPinError(null)).toBe("fail");
+    expect(classifyPinError(undefined)).toBe("fail");
+  });
+});
+
+describe("errorMessage", () => {
+  it("extracts message from Error instance", () => {
+    expect(errorMessage(new Error("boom"))).toBe("boom");
+  });
+
+  it("prefers description over message on grammy-shaped objects", () => {
+    expect(errorMessage({ description: "Telegram says no", message: "generic" })).toBe(
+      "Telegram says no",
+    );
+  });
+
+  it("returns empty string for null", () => {
+    expect(errorMessage(null)).toBe("");
+  });
+
+  it("stringifies unknown shapes", () => {
+    expect(errorMessage(42)).toBe("42");
+  });
+});

package/telegram-plugin/tests/plugin-logger.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, existsSync, rmSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  installPluginLogger,
+  resolveLogPath,
+  _resetForTests,
+} from '../plugin-logger.js'
+
+let tmpDir: string
+let logPath: string
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'plugin-logger-'))
+  logPath = join(tmpDir, 'nested', 'subdir', 'telegram-plugin.log')
+  process.env.SWITCHROOM_TELEGRAM_LOG_PATH = logPath
+  _resetForTests()
+})
+
+afterEach(() => {
+  _resetForTests()
+  delete process.env.SWITCHROOM_TELEGRAM_LOG_PATH
+  try { rmSync(tmpDir, { recursive: true, force: true }) } catch { /* ignore */ }
+})
+
+describe('resolveLogPath', () => {
+  it('uses SWITCHROOM_TELEGRAM_LOG_PATH when set', () => {
+    expect(resolveLogPath({ SWITCHROOM_TELEGRAM_LOG_PATH: '/tmp/custom.log' })).toBe(
+      '/tmp/custom.log',
+    )
+  })
+
+  it('falls back to a path under ~/.switchroom/logs when env is unset', () => {
+    const out = resolveLogPath({})
+    expect(out).toMatch(/\.switchroom\/logs\/telegram-plugin\.log$/)
+  })
+})
+
+describe('installPluginLogger — stderr interception', () => {
+  it('creates the log directory if missing', () => {
+    installPluginLogger()
+    process.stderr.write('telegram channel: boot\n')
+    expect(existsSync(logPath)).toBe(true)
+  })
+
+  it('appends every stderr.write call to the logfile', () => {
+    installPluginLogger()
+    process.stderr.write('telegram channel: line one\n')
+    process.stderr.write('[streaming-metrics] {"kind":"x"}\n')
+    process.stderr.write('stream → edit failed: whatever\n')
+    const contents = readFileSync(logPath, 'utf8')
+    expect(contents).toContain('telegram channel: line one')
+    expect(contents).toContain('[streaming-metrics]')
+    expect(contents).toContain('stream → edit failed')
+  })
+
+  it('forwards to the original stderr (behavior unchanged for other readers)', () => {
+    // We can't easily observe bun's real stderr, but we can verify the
+    // wrapped writer returns a boolean like the original does.
+    installPluginLogger()
+    const result = process.stderr.write('probe\n')
+    expect(typeof result).toBe('boolean')
+  })
+
+  it('uninstall() restores the original writer and stops capturing', () => {
+    const handle = installPluginLogger()
+    process.stderr.write('before\n')
+    handle.uninstall()
+    process.stderr.write('after\n')
+    const contents = readFileSync(logPath, 'utf8')
+    expect(contents).toContain('before')
+    expect(contents).not.toContain('after')
+  })
+
+  it('is idempotent — second install returns the first handle', () => {
+    const a = installPluginLogger()
+    const b = installPluginLogger()
+    expect(b).toBe(a)
+  })
+
+  it('accepts Uint8Array chunks and decodes them to utf8 in the file', () => {
+    installPluginLogger()
+    const encoder = new TextEncoder()
+    process.stderr.write(encoder.encode('binary-path: ok\n'))
+    const contents = readFileSync(logPath, 'utf8')
+    expect(contents).toContain('binary-path: ok')
+  })
+
+  it('swallows filesystem errors and never throws from stderr.write', () => {
+    // Point at an unwritable path (a file that cannot become a directory).
+    process.env.SWITCHROOM_TELEGRAM_LOG_PATH = '/proc/1/cannot-write-here.log'
+    _resetForTests()
+    installPluginLogger()
+    expect(() => process.stderr.write('still ok\n')).not.toThrow()
+  })
+})

package/telegram-plugin/tests/poll-health.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Tests for telegram-plugin/gateway/poll-health.ts (issue #56).
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { createPollHealthCheck } from "../gateway/poll-health.js";
+
+describe("createPollHealthCheck", () => {
+  it("does not call onStall on success", async () => {
+    const onStall = vi.fn().mockResolvedValue(undefined);
+    let tickFn: () => void = () => {};
+    const hc = createPollHealthCheck({
+      ping: async () => undefined,
+      onStall,
+      failureThreshold: 3,
+      setIntervalFn: (fn) => { tickFn = fn; return 1 as unknown as ReturnType<typeof setInterval>; },
+      clearIntervalFn: () => {},
+      log: () => {},
+    });
+    hc.start();
+    for (let i = 0; i < 5; i++) {
+      tickFn();
+      await Promise.resolve();
+    }
+    expect(onStall).not.toHaveBeenCalled();
+    expect(hc.consecutiveFailures()).toBe(0);
+    hc.stop();
+  });
+
+  it("counts consecutive failures and fires onStall at threshold", async () => {
+    const onStall = vi.fn().mockResolvedValue(undefined);
+    let tickFn: () => void = () => {};
+    const hc = createPollHealthCheck({
+      ping: async () => { throw new Error("network down"); },
+      onStall,
+      failureThreshold: 3,
+      setIntervalFn: (fn) => { tickFn = fn; return 1 as unknown as ReturnType<typeof setInterval>; },
+      clearIntervalFn: () => {},
+      log: () => {},
+    });
+    hc.start();
+    tickFn(); await Promise.resolve();
+    tickFn(); await Promise.resolve();
+    tickFn(); await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 10));
+    expect(onStall).toHaveBeenCalledTimes(1);
+  });
+
+  it("resets failure count on a successful ping", async () => {
+    let pingShouldFail = true;
+    let tickFn: () => void = () => {};
+    const hc = createPollHealthCheck({
+      ping: async () => { if (pingShouldFail) throw new Error("oops"); },
+      onStall: async () => {},
+      failureThreshold: 3,
+      setIntervalFn: (fn) => { tickFn = fn; return 1 as unknown as ReturnType<typeof setInterval>; },
+      clearIntervalFn: () => {},
+      log: () => {},
+    });
+    hc.start();
+    tickFn(); await Promise.resolve();
+    tickFn(); await Promise.resolve();
+    expect(hc.consecutiveFailures()).toBeGreaterThan(0);
+    pingShouldFail = false;
+    tickFn(); await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 10));
+    expect(hc.consecutiveFailures()).toBe(0);
+    hc.stop();
+  });
+
+  it("stop() cancels the interval", () => {
+    const onStall = vi.fn();
+    let cleared = false;
+    const hc = createPollHealthCheck({
+      ping: async () => { throw new Error("x"); },
+      onStall,
+      failureThreshold: 1,
+      setIntervalFn: () => 99 as unknown as ReturnType<typeof setInterval>,
+      clearIntervalFn: (id) => { if (id === 99) cleared = true; },
+      log: () => {},
+    });
+    hc.start();
+    hc.stop();
+    expect(cleared).toBe(true);
+  });
+});

package/telegram-plugin/tests/preamble-suppressor.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Unit tests for #549's preamble-suppressor.
+ *
+ * The suppressor is the buffering policy that decides whether assistant
+ * text emitted during a turn is "preamble" (consumed by the next tool's
+ * progress-card narrative) or "answer text" (sent to chat). The bug
+ * #549 was: every text event went to BOTH surfaces because there was no
+ * gate to distinguish preamble from answer.
+ *
+ * Tests inject a synthetic timer so vi.useFakeTimers gives deterministic
+ * windowed behavior.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PreambleSuppressor } from '../gateway/preamble-suppressor.js'
+
+describe('PreambleSuppressor', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  // ─── Core flush-after-window behavior ────────────────────────────────
+
+  it('text with no tool: flushes as answer text after bufferMs', () => {
+    // The agent emits text and ends the turn without any tool. That
+    // text IS the answer; flush to chat after the buffer window.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Hello there!')
+    expect(emits).toEqual([])
+    vi.advanceTimersByTime(149)
+    expect(emits).toEqual([])
+    vi.advanceTimersByTime(2)
+    expect(emits).toEqual(['Hello there!'])
+  })
+
+  it('text-then-non-reply-tool: drops without emitting (the #549 reproducer)', () => {
+    // fails when: a regression makes onTool() flush preamble text to
+    // chat instead of dropping it. Exact bug class #549 was reporting.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Looking it up.')
+    // Tool arrives within the buffer window — this text was preamble.
+    vi.advanceTimersByTime(50)
+    sup.onTool({ isReplyTool: false })
+    // Even after the would-be-flush time elapses, no emission.
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual([])
+    expect(sup.hasPending()).toBe(false)
+  })
+
+  it('text-then-reply-tool: flushes (reply tool is the answer surface)', () => {
+    // The reply / stream_reply tool's text payload IS the answer. If
+    // the agent also emitted plain text just before, that text is
+    // also part of the answer — flush it. (The reply-tool's own dedup
+    // path handles overlap with the stream's payload.)
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Here is what I found:')
+    sup.onTool({ isReplyTool: true })
+    expect(emits).toEqual(['Here is what I found:'])
+  })
+
+  it('multiple text chunks before tool: all dropped together', () => {
+    // The model streams text in chunks. If a tool follows, ALL chunks
+    // were preamble — drop the whole accumulated buffer.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Looking ')
+    sup.onText('it ')
+    sup.onText('up...')
+    vi.advanceTimersByTime(50)
+    sup.onTool({ isReplyTool: false })
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual([])
+  })
+
+  it('multiple text chunks with no tool: flushes all together', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('The answer ')
+    vi.advanceTimersByTime(50)
+    sup.onText('is 42.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['The answer is 42.'])
+  })
+
+  // ─── Multi-segment turn (preamble → tool → answer) ──────────────────
+
+  it('preamble, tool, then answer text: only the answer flushes', () => {
+    // The realistic shape: agent thinks-out-loud ("Looking it up..."),
+    // calls a tool, then emits the actual answer ("Found it: 42.").
+    // Preamble drops; answer flushes.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Looking it up...')
+    sup.onTool({ isReplyTool: false })
+    sup.onText('Found it: 42.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Found it: 42.'])
+  })
+
+  it('cumulative answer text accumulates across multiple non-tool flushes', () => {
+    // If the agent emits text, waits, emits more text (no tool in
+    // between) — both flush as answer text and the cumulative payload
+    // grows. The emit callback receives the cumulative text each time.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Part one. ')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Part one. '])
+    sup.onText('Part two.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Part one. ', 'Part one. Part two.'])
+  })
+
+  // ─── flushNow / dropNow / reset ──────────────────────────────────────
+
+  it('flushNow: forces immediate flush of pending text', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Pending text.')
+    expect(emits).toEqual([])
+    sup.flushNow()
+    expect(emits).toEqual(['Pending text.'])
+    // Idempotent — second flushNow is a no-op (nothing pending).
+    sup.flushNow()
+    expect(emits).toEqual(['Pending text.'])
+  })
+
+  it('dropNow: discards pending text without emitting', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Pending text.')
+    sup.dropNow()
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual([])
+    expect(sup.hasPending()).toBe(false)
+  })
+
+  it('reset: clears cumulative answer text + pending', () => {
+    // Used at fresh-turn enqueue. After reset, the cumulative answer
+    // text is empty — next flush starts the answer payload from scratch.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Turn 1 text.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Turn 1 text.'])
+    expect(sup.currentAnswerText()).toBe('Turn 1 text.')
+
+    sup.reset()
+    expect(sup.currentAnswerText()).toBe('')
+
+    sup.onText('Turn 2 text.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Turn 1 text.', 'Turn 2 text.'])
+  })
+
+  // ─── Edge cases ──────────────────────────────────────────────────────
+
+  it('empty text chunk: no-op, timer not started', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual([])
+    expect(sup.hasPending()).toBe(false)
+  })
+
+  it('flushNow with empty buffer: no emit', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.flushNow()
+    expect(emits).toEqual([])
+  })
+
+  it('chunks arriving inside buffer window reset the timer (debounce-style)', () => {
+    // A second text chunk before the timer fires should EXTEND the
+    // window, not start a separate timer. Otherwise rapid streaming
+    // chunks would flush prematurely as separate answer-text emissions.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('chunk 1 ')
+    vi.advanceTimersByTime(100)
+    sup.onText('chunk 2')
+    vi.advanceTimersByTime(100) // 200ms total since first chunk, but only 100ms since last
+    expect(emits).toEqual([]) // not flushed yet
+    vi.advanceTimersByTime(60)
+    expect(emits).toEqual(['chunk 1 chunk 2'])
+  })
+
+  it('tool then text then tool: middle text dropped (it was preamble for second tool)', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onTool({ isReplyTool: false })   // first tool — nothing pending
+    sup.onText('between tools text')
+    sup.onTool({ isReplyTool: false })   // second tool consumes the text as preamble
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual([])
+  })
+
+  // ─── Cross-turn isolation (regression: dropNow used to leak answerTextOnly) ───
+
+  it('dropNow clears answerTextOnly so next turn does not inherit stale text', () => {
+    // Turn-flush silent-marker / context-exhaust teardown calls dropNow().
+    // If dropNow left `answerTextOnly` populated, the next turn's first
+    // flush would prepend the previous turn's content.
+    //
+    // fails when: dropNow goes back to clearing only the pending buffer.
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({
+      emitAnswer: (t) => emits.push(t),
+      bufferMs: 150,
+    })
+    sup.onText('Turn 1 answer.')
+    vi.advanceTimersByTime(200)
+    expect(emits).toEqual(['Turn 1 answer.'])
+    expect(sup.currentAnswerText()).toBe('Turn 1 answer.')
+
+    // Silent-marker teardown — drop without flushing.
+    sup.dropNow()
+    expect(sup.currentAnswerText()).toBe('')
+
+    // Turn 2 begins. Without the clear, the next flush would emit
+    // "Turn 1 answer.Turn 2 answer." — which is wrong.
+    sup.onText('Turn 2 answer.')
+    vi.advanceTimersByTime(200)
+    expect(emits[emits.length - 1]).toBe('Turn 2 answer.')
+  })
+
+  it('default bufferMs (150) is used when not specified', () => {
+    const emits: string[] = []
+    const sup = new PreambleSuppressor({ emitAnswer: (t) => emits.push(t) })
+    sup.onText('default-window text')
+    vi.advanceTimersByTime(149)
+    expect(emits).toEqual([])
+    vi.advanceTimersByTime(2)
+    expect(emits).toEqual(['default-window text'])
+  })
+})

package/telegram-plugin/tests/progress-card-api-failure-during-deferred.test.ts

@@ -0,0 +1,73 @@
+/**
+ * PR-C2 — reportApiFailure crossing its threshold while a chat is in
+ * `pendingCompletion` state must not corrupt the deferred-completion
+ * resolution path.
+ *
+ * Setup: parent turn_end while a bg sub-agent is still running →
+ * chatState.pendingCompletion=true. Then `maxConsecutive4xx` permanent
+ * 4xx failures arrive (the card is being abandoned locally). We then
+ * resolve the bg sub-agent via sub_agent_turn_end. The driver must:
+ *
+ *   - Fire onTurnComplete exactly once for the originating turnKey.
+ *   - Not double-flush.
+ *
+ * fails when: the terminal-apiFailure branch races with the
+ * pendingCompletion resolution path and either swallows or duplicates
+ * the completion callback.
+ */
+import { describe, it, expect } from 'vitest'
+import { makeHarness, enqueue } from './_progress-card-harness.js'
+
+describe('PR-C2: API failure crossing threshold during pendingCompletion', () => {
+  it('deferred completion still resolves exactly once; no double-flush', () => {
+    const completions: string[] = []
+    const { driver } = makeHarness({
+      minIntervalMs: 0,
+      coalesceMs: 0,
+      heartbeatMs: 999_999, // keep heartbeat from racing the test
+      maxConsecutive4xx: 3,
+      promoteAfterMs: 999_999,
+      onTurnComplete: (s) => completions.push(s.turnKey),
+    })
+    const maps = driver._debugGetMaps!()
+    const CHAT = 'cA'
+
+    driver.ingest(enqueue(CHAT), null)
+    driver.ingest(
+      {
+        kind: 'tool_use',
+        toolName: 'Agent',
+        toolUseId: 'tu1',
+        input: { prompt: 'bg', run_in_background: true },
+      },
+      CHAT,
+    )
+    driver.ingest({ kind: 'sub_agent_started', agentId: 'saBG', firstPromptText: 'bg' }, CHAT)
+    driver.ingest({ kind: 'tool_use', toolName: 'mcp__switchroom-telegram__reply' }, CHAT)
+    driver.recordOutboundDelivered(CHAT)
+    driver.ingest({ kind: 'turn_end', durationMs: 100 }, CHAT)
+
+    expect(maps.chats.size).toBe(1)
+    const turnKey = [...maps.chats.keys()][0]
+    const cs = maps.chats.get(turnKey) as { pendingCompletion: boolean; apiFailures: { terminal: boolean } }
+    expect(cs.pendingCompletion).toBe(true)
+
+    // Hammer reportApiFailure past the threshold (3).
+    for (let i = 0; i < 5; i++) {
+      driver.reportApiFailure(turnKey, {
+        kind: 'permanent_4xx',
+        code: 400,
+        description: 'bad request',
+      })
+    }
+    expect(cs.apiFailures.terminal).toBe(true)
+    // No completion fired yet — bg still running.
+    expect(completions.length).toBe(0)
+
+    // Resolve the bg sub-agent. The originating turn must complete
+    // exactly once.
+    driver.ingest({ kind: 'sub_agent_turn_end', agentId: 'saBG' }, CHAT)
+    expect(completions.length).toBe(1)
+    expect(completions[0]).toBe(turnKey)
+  })
+})