switchroom 0.18.18 → 0.18.20

package/telegram-plugin/tests/narrative-flush.test.ts

@@ -0,0 +1,213 @@
+/**
+ * narrative-flush.test.ts — the time-boxed narrative early-paint kernel.
+ *
+ * Pins the deterministic behaviour of NarrativeFlushController (narrative-flush.ts):
+ * the timer half of the JSONL-text-narrative primitive. Drives the REAL kernel with
+ * a fake scheduler + effect spies (no real timers, no gateway I/O) so every
+ * assertion is an outcome, not a code-path.
+ *
+ * Coverage maps 1:1 to the fix's correctness requirements:
+ *   1. Early paint — a parked block SHOWs when the timer fires and NO lookahead
+ *      followed (RED on pre-fix: pre-fix never armed a timer, so `show` only ever
+ *      fired on the next event — here it fires with no lookahead at all).
+ *   2. Fast tool — a tool_use lookahead before the timer fires SHOWs exactly once
+ *      and cancels the timer (no double-paint).
+ *   3. Anti-double-print, deferred path — a parked block that drafts the reply is
+ *      SUPPRESSED (never shown) when the reply lands before the timer.
+ *   4. Anti-double-print, TIMER path — a block the timer already painted that
+ *      later proves to draft the reply is RETRACTED (the guarantee holds even when
+ *      the timer paints ahead of the reply).
+ *   5. Leak safety — turn_end and teardown disarm the timer; a stale fire is inert.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { NarrativeFlushController } from '../narrative-flush.js'
+
+const FLUSH_MS = 250
+
+/** Deterministic stand-in for the real `unref`'d setTimeout wiring. */
+class FakeScheduler {
+  private fn: (() => void) | null = null
+  armCount = 0
+  disarmCount = 0
+  lastMs: number | null = null
+
+  arm(fn: () => void, ms: number): void {
+    // Real scheduler cancels any prior armed callback first (at-most-one).
+    this.fn = fn
+    this.lastMs = ms
+    this.armCount++
+  }
+  disarm(): void {
+    if (this.fn != null) this.disarmCount++
+    this.fn = null
+  }
+  /** Simulate the real timer elapsing. No-op once disarmed (mirrors clearTimeout). */
+  fire(): void {
+    const fn = this.fn
+    this.fn = null // a real one-shot timer is spent after firing
+    fn?.()
+  }
+  get isArmed(): boolean {
+    return this.fn != null
+  }
+}
+
+function makeController() {
+  const show = vi.fn<[string], void>()
+  const retractShown = vi.fn<[string], void>()
+  const scheduler = new FakeScheduler()
+  const ctrl = new NarrativeFlushController({ show, retractShown }, scheduler, FLUSH_MS)
+  return { ctrl, show, retractShown, scheduler }
+}
+
+describe('early paint — parked narration surfaces on the timer with no lookahead', () => {
+  it('does NOT paint on stage alone, then paints exactly once when the timer fires', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('On it, pulling the logs…')
+
+    // Pre-fix behaviour: nothing shown yet (deferred one lookahead step).
+    expect(show).not.toHaveBeenCalled()
+    // The fix ARMS a timer for exactly this case.
+    expect(scheduler.isArmed).toBe(true)
+    expect(scheduler.lastMs).toBe(FLUSH_MS)
+
+    scheduler.fire() // the agent thought past the window before its first tool
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith('On it, pulling the logs…')
+  })
+})
+
+describe('fast tool — a lookahead before the window cancels the timer, paints once', () => {
+  it('SHOWs the working preamble once and disarms; a later stale fire is inert', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('Let me check the build…')
+    expect(scheduler.isArmed).toBe(true)
+
+    ctrl.resolveOnTool('Bash', { command: 'npm test' }) // real tool → SHOW
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith('Let me check the build…')
+    expect(scheduler.isArmed).toBe(false) // timer cancelled
+    expect(scheduler.disarmCount).toBeGreaterThan(0)
+
+    scheduler.fire() // stale — must not double-paint
+    expect(show).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('anti-double-print (deferred path) — a draft-then-send reply is suppressed', () => {
+  it('never SHOWs a parked block that drafts the reply landing before the timer', () => {
+    const { ctrl, show, retractShown, scheduler } = makeController()
+    const answer = 'The build is green — all 412 tests pass.'
+    ctrl.stage(answer) // the model drafting its answer just before reply()
+
+    ctrl.resolveOnTool('reply', { text: answer }) // draft-then-send → SUPPRESS
+    expect(show).not.toHaveBeenCalled()
+    expect(retractShown).not.toHaveBeenCalled() // nothing was shown to retract
+    expect(scheduler.isArmed).toBe(false)
+  })
+
+  it('SHOWs a working preamble whose text DIFFERS from the reply', () => {
+    const { ctrl, show } = makeController()
+    ctrl.stage('Looking into it…')
+    ctrl.resolveOnTool('reply', { text: 'The answer is 42.' })
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith('Looking into it…')
+  })
+})
+
+describe('anti-double-print (TIMER path) — a timer-painted draft is retracted', () => {
+  it('RETRACTS a block the timer already painted when the reply proves it a draft', () => {
+    const { ctrl, show, retractShown, scheduler } = makeController()
+    const answer = 'Done — deployed v0.16.51 to production, health checks green.'
+    ctrl.stage(answer)
+
+    scheduler.fire() // timer paints it EARLY (the reply hadn't arrived yet)
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith(answer)
+
+    // The reply finally lands and IS that block → must be retracted, not left
+    // on the card to double-print against the canonical reply.
+    ctrl.resolveOnTool('stream_reply', { text: answer })
+    expect(retractShown).toHaveBeenCalledTimes(1)
+    expect(retractShown).toHaveBeenCalledWith(answer)
+    expect(show).toHaveBeenCalledTimes(1) // not re-shown
+  })
+
+  it('does NOT retract a timer-painted block when the reply differs (genuine narration)', () => {
+    const { ctrl, show, retractShown, scheduler } = makeController()
+    ctrl.stage('Still working — compiling the worker…')
+    scheduler.fire()
+    ctrl.resolveOnTool('reply', { text: 'Here are your results: …' })
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(retractShown).not.toHaveBeenCalled()
+  })
+
+  it('retracts a timer-painted draft even when the reply only lands at turn_end', () => {
+    const { ctrl, show, retractShown, scheduler } = makeController()
+    const answer = 'All set — the migration ran cleanly.'
+    ctrl.stage(answer)
+    scheduler.fire()
+    ctrl.flushAtTurnEnd(answer) // reply delivered; trailing block is its draft
+    expect(retractShown).toHaveBeenCalledTimes(1)
+    expect(retractShown).toHaveBeenCalledWith(answer)
+    expect(show).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('turn_end — trailing narration is shown or suppressed, timer disarmed', () => {
+  it('SHOWs genuine trailing narration and disarms the timer', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('Done — all green.')
+    ctrl.flushAtTurnEnd('') // no reply delivered → genuine trailing narration
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith('Done — all green.')
+    expect(scheduler.isArmed).toBe(false)
+  })
+
+  it('SUPPRESSes a trailing block that drafts the delivered answer', () => {
+    const { ctrl, show } = makeController()
+    const answer = 'The total came to $1,240.50 across the three invoices.'
+    ctrl.stage(answer)
+    ctrl.flushAtTurnEnd(answer)
+    expect(show).not.toHaveBeenCalled()
+  })
+})
+
+describe('leak safety — teardown and turn_end can never leave a live timer', () => {
+  it('teardown disarms; a stale fire after teardown is inert', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('Working…')
+    expect(scheduler.isArmed).toBe(true)
+
+    ctrl.teardown()
+    expect(scheduler.isArmed).toBe(false)
+    expect(scheduler.disarmCount).toBeGreaterThan(0)
+
+    scheduler.fire() // must not paint against a torn-down turn
+    expect(show).not.toHaveBeenCalled()
+  })
+
+  it('flushAtTurnEnd disarms the timer so it cannot fire post-turn', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('Half-done…')
+    ctrl.flushAtTurnEnd('') // shows it, and disarms
+    show.mockClear()
+    scheduler.fire() // stale
+    expect(show).not.toHaveBeenCalled()
+  })
+
+  it('re-staging cancels the prior block’s timer (at-most-one armed)', () => {
+    const { ctrl, show, scheduler } = makeController()
+    ctrl.stage('first line…')
+    ctrl.stage('second line…') // the new block is the lookahead for the first
+    // The first (pure narration) is shown immediately by the stage lookahead.
+    expect(show).toHaveBeenCalledTimes(1)
+    expect(show).toHaveBeenCalledWith('first line…')
+    // Exactly one live timer remains (for the second block).
+    expect(scheduler.isArmed).toBe(true)
+    scheduler.fire()
+    expect(show).toHaveBeenCalledTimes(2)
+    expect(show).toHaveBeenLastCalledWith('second line…')
+  })
+})

package/telegram-plugin/tests/narrative-splice-before-finalize.test.ts

@@ -0,0 +1,167 @@
+/**
+ * narrative-splice-before-finalize.test.ts — the gateway-level anti-double-print
+ * guarantee for the TIMER early-paint path.
+ *
+ * ## What this proves
+ * The kernel unit tests (narrative-flush.test.ts) prove the controller EMITS a
+ * RETRACT effect. They do NOT prove the load-bearing gateway wiring: that the
+ * RETRACT effect splices `mirrorLines` synchronously BEFORE the finalize render
+ * (`clearActivitySummary` → `composeTurnActivity(final)`) reads that same array,
+ * so a narration the timer painted early and that turned out to draft the reply
+ * appears ZERO times in the finalized card.
+ *
+ * This test reconstructs the gateway's OWN effect wiring 1:1 with
+ * `makeNarrativeGate` (gateway.ts): a shared `mirrorLines` array, a `show`
+ * effect that mirrors `showNarrativeStep`'s core
+ * (`appendActivityLabel(mirrorLines, clipNarrative(text))`), and a `retractShown`
+ * effect that mirrors `retractNarrativeLine`'s core (splice the
+ * `lastIndexOf(clipNarrative(text))` entry). The finalize render reads the SAME
+ * live array. It drives the REAL `NarrativeFlushController`, the REAL render
+ * helpers, and a REAL `setTimeout`-based scheduler under fake timers — every
+ * assertion is an outcome.
+ *
+ * ## Red-on-regression
+ *   - If the RETRACT effect were removed / made a no-op, the timer-painted line
+ *     stays in `mirrorLines` and the finalize render contains it → RED.
+ *   - If the finalize render were reordered to read a snapshot taken BEFORE the
+ *     retract splice (the "splice-after-finalize" reordering), the snapshot still
+ *     holds the line → RED. (Modeled here by taking the finalize snapshot AFTER
+ *     `resolveOnTool`, exactly as the gateway sequences retract-then-finalize.)
+ *
+ * ## Honest limits
+ * gateway.ts does NOT export `showNarrativeStep` / `retractNarrativeLine` /
+ * `composeTurnActivity` / `clearActivitySummary`, so this test cannot invoke
+ * those private functions directly — it reconstructs their effect bodies against
+ * the real shared helpers. It therefore locks the CONTRACT (splice-before-read,
+ * clipped-line matching, retract-empties-cleanly) but would not catch a future
+ * edit that diverges the gateway's private effect bodies from this reconstruction
+ * without also updating this test. The kernel test covers the controller; this
+ * test covers the mirrorLines splice/finalize contract they compose into.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { NarrativeFlushController } from '../narrative-flush.js'
+import {
+  clipNarrative,
+  appendActivityLabel,
+  renderActivityFeedWithNested,
+} from '../tool-activity-summary.js'
+
+const FLUSH_MS = 250
+
+/** Count non-overlapping occurrences of `needle` in `haystack`. */
+function occurrences(haystack: string, needle: string): number {
+  if (needle.length === 0) return 0
+  let count = 0
+  let from = 0
+  for (;;) {
+    const at = haystack.indexOf(needle, from)
+    if (at === -1) return count
+    count++
+    from = at + needle.length
+  }
+}
+
+describe('gateway wiring: retract splices mirrorLines BEFORE finalize reads it', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  /**
+   * Build the SAME effect wiring `makeNarrativeGate` builds, over a shared
+   * `mirrorLines` array, with a real setTimeout scheduler (mirrors the gateway's
+   * `unref`'d setTimeout wiring).
+   */
+  function wireGate() {
+    const mirrorLines: string[] = []
+    let handle: ReturnType<typeof setTimeout> | null = null
+    const controller = new NarrativeFlushController(
+      {
+        // showNarrativeStep core: append the clipped narrative as a feed line.
+        show: (text) => {
+          appendActivityLabel(mirrorLines, clipNarrative(text))
+        },
+        // retractNarrativeLine core: splice the clipped line out of mirrorLines.
+        retractShown: (text) => {
+          const clipped = clipNarrative(text)
+          const idx = mirrorLines.lastIndexOf(clipped)
+          if (idx === -1) return
+          mirrorLines.splice(idx, 1)
+        },
+      },
+      {
+        arm: (fn, ms) => {
+          if (handle != null) clearTimeout(handle)
+          handle = setTimeout(fn, ms)
+          handle.unref?.()
+        },
+        disarm: () => {
+          if (handle != null) {
+            clearTimeout(handle)
+            handle = null
+          }
+        },
+      },
+      FLUSH_MS,
+    )
+    // composeTurnActivity(final) core: render the SAME live mirrorLines array.
+    const finalize = () => renderActivityFeedWithNested(mirrorLines, [], true)
+    return { controller, mirrorLines, finalize }
+  }
+
+  it('early-painted narration that drafts the reply appears ZERO times in the finalized card', () => {
+    const { controller, mirrorLines, finalize } = wireGate()
+    const narration = 'The migration completed and all 40 rows were backfilled cleanly.'
+    const reply = 'The migration completed and all 40 rows were backfilled cleanly.'
+    const clipped = clipNarrative(narration)
+
+    // 1. Stage the opening narration (parked, timer armed).
+    controller.stage(narration)
+
+    // 2. Fire the early-paint timer → SHOW paints the line into mirrorLines.
+    vi.advanceTimersByTime(FLUSH_MS)
+    expect(mirrorLines).toContain(clipped)
+    // Sanity: before retract, a finalize WOULD have shown the line (proves the
+    // assertion below is meaningful, not vacuously passing on an empty feed).
+    expect(occurrences(finalize() ?? '', clipped)).toBe(1)
+
+    // 3. Deliver the matching reply (draft-then-send) → RETRACT splices the line.
+    controller.resolveOnTool('reply', { text: reply })
+
+    // 4. Finalize reads the SAME (now-spliced) array → line appears ZERO times.
+    const finalRender = finalize()
+    expect(occurrences(finalRender ?? '', clipped)).toBe(0)
+  })
+
+  it('a genuinely different early-painted narration survives finalize exactly once (no over-retract)', () => {
+    const { controller, mirrorLines, finalize } = wireGate()
+    const narration = 'Running the integration suite against staging'
+    const reply = 'All checks passed — deployed to production.'
+    const clipped = clipNarrative(narration)
+
+    controller.stage(narration)
+    vi.advanceTimersByTime(FLUSH_MS)
+    controller.resolveOnTool('reply', { text: reply })
+
+    // Not a draft of the reply → NOT retracted → present exactly once.
+    expect(mirrorLines).toContain(clipped)
+    expect(occurrences(finalize() ?? '', clipped)).toBe(1)
+  })
+
+  it('retract that empties the feed collapses composeTurnActivity to null (interim-ack anti-blank guard input)', () => {
+    // Documents the LOW cosmetic case: when the ONLY feed line is retracted, the
+    // live re-render collapses to null and the guard leaves the stale line up
+    // until the next event. Here we assert the *finalize* is clean (no double
+    // print) even though the interim live render would be null.
+    const { controller, mirrorLines, finalize } = wireGate()
+    const narration = 'Drafting the summary of the deploy'
+    const reply = 'Drafting the summary of the deploy'
+    controller.stage(narration)
+    vi.advanceTimersByTime(FLUSH_MS)
+    controller.resolveOnTool('reply', { text: reply })
+    expect(mirrorLines).toHaveLength(0)
+    // Empty feed → renderActivityFeedWithNested returns null (the anti-blank
+    // guard's null input). The finalized card carries the narration ZERO times.
+    const finalRender = finalize()
+    expect(finalRender == null || occurrences(finalRender, clipNarrative(narration)) === 0).toBe(true)
+  })
+})

package/telegram-plugin/tests/outbound-send-path.test.ts

@@ -56,6 +56,8 @@ function referenceNormalize(rawText: string): { text: string; voiceReplaced: num
 }
 
 function referenceEffectiveText(text: string, literalText: boolean): string {
+  // Rich path injects the idempotent U+00A0 paragraph spacer (#2692, restored
+  // after the #3208 F1 misfire); the literal path stays byte-exact.
   return literalText ? text : addParagraphSpacers(text)
 }
 

package/telegram-plugin/tests/paragraph-spacer-golden.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Durable anchor for the restored idempotent paragraph spacer (revert of
+ * #3208 F1). Two guarantees the fleet depends on:
+ *
+ *   1. GOLDEN — the EXACT outbound byte string for a representative message
+ *      (bold header + two prose paragraphs + a `- ` list + a fenced code
+ *      block + closing prose) is pinned, BOTH after the `addParagraphSpacers`
+ *      pass AND after the in-repo IR renderer (`render/`) re-parses and
+ *      re-renders it. Any future change to paragraph spacing must CONSCIOUSLY
+ *      update this fixture — it can't drift silently. The wire byte string is
+ *      byte-identical to the spacer-pass output, proving the U+00A0 spacer
+ *      survives the live rich-render path (`SWITCHROOM_RICH_RENDER` default-on).
+ *
+ *   2. IDEMPOTENCY — the pass inserts EXACTLY ONE spacer per prose gap and can
+ *      never stack a second: running it twice equals running it once, and a
+ *      gap that already carries a spacer (or an extra blank line, or an
+ *      ASCII-space-only line) is normalised to the single canonical spacer,
+ *      not doubled. The "naive re-add" control below shows WHY the guard is
+ *      load-bearing: a non-canonicalising spacer pass (insert on every `\n\n`)
+ *      double-gaps on the second run — exactly the #3208 symptom. That control
+ *      asserts the naive output DIVERGES, so this test would fail if the real
+ *      pass ever lost its idempotency guard.
+ *
+ * Context: #3208 F1 deleted the spacer wholesale on the false premise that the
+ * Bot API 10.1 rich GFM renderer shows a bare `\n\n` gap as a visible blank
+ * line. Live evidence says the opposite — `\n\n` renders TIGHT, only the
+ * U+00A0 spacer produces a visible gap — so removal reintroduced the
+ * "paragraphs jammed together" symptom #2692 originally fixed. The correct fix
+ * for F1's real-but-narrow double-gap was to make the spacer idempotent (this),
+ * not to delete it.
+ */
+import { describe, test, expect } from 'vitest'
+import {
+  addParagraphSpacers,
+  normalizeParagraphBreaks,
+  PARAGRAPH_SPACER,
+} from '../format.js'
+import { renderOutbound, renderOutboundChunks } from '../render/rich-render.js'
+
+const SP = PARAGRAPH_SPACER // U+00A0
+
+// A representative multi-construct message: a **bold** header, two prose
+// paragraphs, a `- ` list, a fenced code block, and closing prose.
+const REPRESENTATIVE = [
+  '**Status report**',
+  '',
+  'First paragraph of prose explaining the situation in some detail.',
+  '',
+  'Second paragraph that continues the explanation across a gap.',
+  '',
+  '- first bullet item',
+  '- second bullet item',
+  '',
+  '```js',
+  'const x = 1',
+  '```',
+  '',
+  'Closing prose after the code block.',
+].join('\n')
+
+// The EXACT expected outbound byte string. Every DISTINCT-block boundary
+// carries exactly one U+00A0 spacer line; the list interior stays tight and the
+// fenced block is byte-for-byte verbatim. Update this fixture ONLY with a
+// conscious decision to change paragraph spacing.
+const GOLDEN =
+  `**Status report**\n\n${SP}\n\n` +
+  `First paragraph of prose explaining the situation in some detail.\n\n${SP}\n\n` +
+  `Second paragraph that continues the explanation across a gap.\n\n${SP}\n\n` +
+  `- first bullet item\n- second bullet item\n\n${SP}\n\n` +
+  '```js\nconst x = 1\n```' +
+  `\n\n${SP}\n\n` +
+  'Closing prose after the code block.'
+
+describe('paragraph spacer — golden outbound byte string', () => {
+  test('addParagraphSpacers output matches the golden fixture exactly', () => {
+    const eff = addParagraphSpacers(normalizeParagraphBreaks(REPRESENTATIVE))
+    expect(eff).toBe(GOLDEN)
+  })
+
+  test('the golden survives the single-piece IR renderer byte-for-byte', () => {
+    // The renderer (default-on) re-parses and re-renders; a U+00A0-only line is
+    // a genuine paragraph that round-trips intact, so the visible gap reaches
+    // Telegram. (An ASCII-space-only line, by contrast, would be collapsed.)
+    // This is the sub-cap single-piece case (`renderOutbound`); the live-path
+    // assertion below proves the same through the ACTUAL send transform.
+    const wire = renderOutbound(GOLDEN).text
+    expect(wire).toBe(GOLDEN)
+  })
+
+  test('the golden reaches the wire through the LIVE send path (renderOutboundChunks) byte-for-byte', () => {
+    // The live send path (stream-controller.ts) uses `renderOutboundChunks`, not
+    // the single-piece `renderOutbound`. For a sub-cap body it returns exactly
+    // one `markdown` piece; the joined piece text must preserve the U+00A0
+    // spacer byte-for-byte, so the visible paragraph gaps reach Telegram on the
+    // real path — not merely in the single-piece renderer. This is the load-
+    // bearing anchor against a third flip of the paragraph-spacing behaviour.
+    const pieces = renderOutboundChunks(GOLDEN)
+    expect(pieces).toHaveLength(1) // sub-cap → single deliverable piece
+    expect(pieces[0].mode).toBe('markdown')
+    const joined = pieces.map((p) => p.text).join('')
+    expect(joined).toBe(GOLDEN)
+    // The U+00A0 spacer is present and never doubled at any boundary.
+    expect(joined).toContain(`\n\n${SP}\n\n`)
+    expect(joined).not.toContain(`${SP}\n\n${SP}`)
+  })
+
+  // Multi-chunk boundary safety (a body that exceeds the cap and splits, with no
+  // spacer stranded or duplicated at a chunk boundary) is covered by
+  // telegram-format.test.ts → 'no chunk starts or ends with a bare U+00A0
+  // spacer line (reviewer repro)' and 'spacer-boundary strip is robust across
+  // several gaps and small caps'. Not duplicated here.
+})
+
+describe('paragraph spacer — idempotency guard', () => {
+  test('running the pass twice equals running it once', () => {
+    const once = addParagraphSpacers(normalizeParagraphBreaks(REPRESENTATIVE))
+    const twice = addParagraphSpacers(once)
+    expect(twice).toBe(once)
+  })
+
+  test('a gap that already carries a spacer is not double-spaced', () => {
+    const already = `Alpha.\n\n${SP}\n\nBravo.`
+    expect(addParagraphSpacers(already)).toBe(already)
+    // No gap ever grows a SECOND spacer line.
+    expect(addParagraphSpacers(already)).not.toContain(`${SP}\n\n${SP}`)
+  })
+
+  test('a stray extra blank line / ASCII-space line is normalised, never stacked', () => {
+    // Triple newline, and an ASCII-space-only spacer line, both canonicalise to
+    // the single U+00A0 spacer — not to a spacer PLUS an extra blank.
+    expect(addParagraphSpacers('Alpha.\n\n\nBravo.')).toBe(`Alpha.\n\n${SP}\n\nBravo.`)
+    expect(addParagraphSpacers('Alpha.\n\n \n\nBravo.')).toBe(`Alpha.\n\n${SP}\n\nBravo.`)
+  })
+
+  test('CONTROL: a naive non-canonicalising spacer pass double-gaps on re-run (proves the guard is load-bearing)', () => {
+    // A naive implementation inserts a spacer at EVERY `\n\n` with no guard.
+    // First run is fine; the SECOND run sees the spacer's own `\n\n` gaps and
+    // wedges more spacers, stacking blank lines — the #3208 double-gap. This
+    // control asserts the naive pass DIVERGES from idempotency, so if the real
+    // addParagraphSpacers ever regressed to naive behaviour the idempotency
+    // test above would start failing rather than silently passing.
+    const naive = (t: string): string => t.replace(/\n\n/g, `\n\n${SP}\n\n`)
+    const once = naive('Alpha.\n\nBravo.')
+    const twice = naive(once)
+    expect(twice).not.toBe(once)
+    // And the real pass does NOT behave like the naive one on re-run.
+    const realOnce = addParagraphSpacers('Alpha.\n\nBravo.')
+    expect(addParagraphSpacers(realOnce)).toBe(realOnce)
+  })
+})

package/telegram-plugin/tests/per-topic-current-turn.test.ts

@@ -60,8 +60,11 @@ describe('PR-4e source-read oracle — the wiring the per-topic map depends on',
   })
 
   it('endCurrentTurnAtomic closes the leak AT ORIGIN — keyed liveness guard + keyed delete', () => {
+    // Anchor on the `function ` prefix only — the signature is multi-line
+    // (gained an `opts?` param + `number | null` return in the send-honesty
+    // work), and `function ` disambiguates the definition from its call sites.
     const body = gatewaySrc
-      .split('function endCurrentTurnAtomic(turn: CurrentTurn): void {')[1]
+      .split('function endCurrentTurnAtomic(')[1]
       ?.split('\n}')[0] ?? ''
     expect(body.length).toBeGreaterThan(50)
     // Guard is the keyed liveness check (NOT a bare singleton ===).