switchroom 0.18.19 → 0.18.21

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/nested-worker-visibility-harness.test.ts

@@ -267,6 +267,26 @@ describe('nested (depth-2+) worker — end-to-end visibility harness', () => {
     expect(lastChild.text).not.toContain('starting…')
     expect(lastChild.text).toContain('index.ts')
 
+    // #3233 — DELIBERATE orchestrator-suppression behaviour. The depth-1
+    // 'depth-1 orchestrator' parent ran ZERO tools of its own: it only
+    // DISPATCHED the nested child. The skeleton first-paint cue (#3231) fires
+    // on every no-growth poll, so a naive implementation gives that pure
+    // orchestrator its OWN persistent "starting…" worker-feed row — redundant
+    // clutter, because the child's row already carries the liveness. The
+    // watcher suppresses the skeleton cue for any entry that has dispatched a
+    // child (parent_agent_id linkage), so the orchestrator NEVER earns a
+    // "starting…" row while its child provides the live signal. This is NOT a
+    // "0 own tools" rule (that would re-break the 205s-blackout incident this
+    // PR fixes — a leaf that blocks on its FIRST tool also has 0 completed
+    // tools and MUST still paint); it keys strictly on the parent/child link.
+    const allFeed = [...h.bot.sent, ...h.bot.edits]
+    const orchestratorStartingRows = allFeed.filter(
+      (m) => m.text.includes('depth-1 orchestrator') && m.text.includes('starting…'),
+    )
+    expect(orchestratorStartingRows.length).toBe(0)
+    // …while the child (a genuine leaf) DID surface real, live tool activity.
+    expect(childMsgs.some((m) => m.text.includes('index.ts'))).toBe(true)
+
     // More tool activity → climbing tool count, still live.
     h.appendWorker('child01', toolUse('t2', 'Bash', { command: 'ls -la /repo' }))
     h.advance(1000)

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

@@ -4,6 +4,7 @@ import {
   normalizeParagraphBreaks,
   normalizePunctuation,
   stripExcessBold,
+  addParagraphSpacers,
   splitMarkdownChunks,
   hardSliceToCap,
   RICH_MESSAGE_MAX_CHARS,
@@ -54,10 +55,10 @@ function referenceNormalize(rawText: string): { text: string; voiceReplaced: num
   return { text, voiceReplaced }
 }
 
-function referenceEffectiveText(text: string, _literalText: boolean): string {
-  // The NBSP paragraph-spacer pass was removed in the #2669 follow-up; both
-  // paths now pass the normalized text through unchanged.
-  return text
+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)
 }
 
 function referenceChunks(

package/telegram-plugin/tests/paragraph-normalizer.test.ts

@@ -12,6 +12,8 @@ import { describe, test, expect } from 'vitest'
 import {
   normalizeParagraphBreaks,
   splitCollapsedInlineBullets,
+  addParagraphSpacers,
+  PARAGRAPH_SPACER,
 } from '../format.js'
 
 describe('normalizeParagraphBreaks', () => {
@@ -431,44 +433,96 @@ describe('splitCollapsedInlineBullets', () => {
 })
 
 // ---------------------------------------------------------------------------
-// Paragraph gap spacing — plain \n\n, no NBSP spacer (#2669 follow-up).
+// addParagraphSpacers — restore a VISIBLE blank line between prose paragraphs.
 //
-// The NBSP paragraph-spacer (addParagraphSpacers / PARAGRAPH_SPACER) was
-// REMOVED: its premise — that the Bot API 10.1 rich GFM renderer collapses a
-// `\n\n` gap TIGHT — is false for the live renderer, which shows a `\n\n` gap
-// as one normal blank line. The spacer therefore injected a spurious SECOND
-// blank line (`\n\n \n\n`) between every paragraph fleet-wide. Paragraph
-// spacing now relies on the plain `\n\n` that normalizeParagraphBreaks already
-// guarantees. These tests pin: multi-paragraph output has exactly one blank
-// line per gap, and no U+00A0 anywhere.
+// The rich GFM renderer (post-#2669) collapses a `\n\n` paragraph gap TIGHT, so
+// multi-paragraph replies render jammed together — the operator-confirmed
+// regression vs the old HTML path (`parse_mode:"HTML"`, `\n\n` → real blank
+// line). addParagraphSpacers wedges a U+00A0 spacer paragraph into each prose
+// `\n\n` gap so the rich renderer shows a visible empty line. Conservative:
+// only between two prose blocks, never adjacent to list/table/code/quote/heading.
 // ---------------------------------------------------------------------------
 
-describe('paragraph gap spacing — single blank line, no NBSP', () => {
-  const NBSP = String.fromCharCode(0xa0)
+describe('addParagraphSpacers', () => {
+  const gap = `\n\n${PARAGRAPH_SPACER}\n\n`
 
-  test('a two-paragraph prose body has exactly one blank-line gap and no NBSP', () => {
-    const out = normalizeParagraphBreaks('Paragraph one.\n\nParagraph two.')
-    expect(out).toBe('Paragraph one.\n\nParagraph two.')
-    expect(out).not.toContain(NBSP)
-    // Exactly one empty line between the two content lines.
-    expect(out.split('\n')).toEqual(['Paragraph one.', '', 'Paragraph two.'])
+  test('the spacer is a single non-breaking space (U+00A0), not an ASCII space', () => {
+    expect(PARAGRAPH_SPACER).toBe(' ')
   })
 
-  test('a three-paragraph body keeps single-blank-line gaps, no NBSP', () => {
-    const out = normalizeParagraphBreaks('One.\n\nTwo.\n\nThree.')
-    expect(out).toBe('One.\n\nTwo.\n\nThree.')
-    expect(out).not.toContain(NBSP)
-    // No gap is a DOUBLE blank line (`\n\n\n`), which the old spacer produced.
-    expect(out).not.toMatch(/\n\n\n/)
+  test('inserts a visible spacer paragraph into a prose `\\n\\n` gap', () => {
+    expect(addParagraphSpacers('Paragraph one.\n\nParagraph two.')).toBe(
+      `Paragraph one.${gap}Paragraph two.`,
+    )
+  })
+
+  test('spaces every gap in a three-paragraph body', () => {
+    expect(addParagraphSpacers('One.\n\nTwo.\n\nThree.')).toBe(
+      `One.${gap}Two.${gap}Three.`,
+    )
+  })
+
+  test('is idempotent — a spaced gap is not doubled on a second pass', () => {
+    const once = addParagraphSpacers('Alpha.\n\nBravo.')
+    expect(addParagraphSpacers(once)).toBe(once)
+  })
+
+  test('leaves a single-`\\n` separation alone (only `\\n\\n` gaps are spaced)', () => {
+    // normalizeParagraphBreaks owns lone-break promotion; this pass only adds a
+    // visible spacer where a genuine blank-line gap already exists.
+    const input = 'Line one.\nLine two.'
+    expect(addParagraphSpacers(input)).toBe(input)
   })
 
-  test('prose->list transition is a single `\n\n` boundary, list interior tight', () => {
-    const out = normalizeParagraphBreaks('Here are the steps.\n\n- first\n- second')
-    expect(out).toBe('Here are the steps.\n\n- first\n- second')
-    expect(out).not.toContain(NBSP)
+  test('spaces prose↔list transitions (uniform block spacing), list interior tight', () => {
+    expect(addParagraphSpacers('Here are the steps.\n\n- first\n- second')).toBe(
+      `Here are the steps.${gap}- first\n- second`,
+    )
+    expect(addParagraphSpacers('- first\n- second\n\nClosing prose after the list.')).toBe(
+      `- first\n- second${gap}Closing prose after the list.`,
+    )
   })
 
-  test('composed prose+list body: one blank line per gap, no NBSP, no double gap', () => {
+  test('spaces a prose→table boundary; table rows stay contiguous', () => {
+    const table = '| a | b |\n| --- | --- |\n| 1 | 2 |'
+    expect(addParagraphSpacers(`Intro.\n\n${table}`)).toBe(`Intro.${gap}${table}`)
+  })
+
+  test('spaces prose↔fence boundaries; fence interior untouched', () => {
+    const input = 'Look here.\n\n```js\nconst a = 1;\n```\n\nDone.'
+    expect(addParagraphSpacers(input)).toBe(
+      `Look here.${gap}\`\`\`js\nconst a = 1;\n\`\`\`${gap}Done.`,
+    )
+  })
+
+  test('spaces heading→anything and blockquote boundaries', () => {
+    expect(addParagraphSpacers('Intro prose.\n\n## Section\n\nBody prose.')).toBe(
+      `Intro prose.${gap}## Section${gap}Body prose.`,
+    )
+    expect(addParagraphSpacers('Said.\n\n> a quote\n\nAfter.')).toBe(
+      `Said.${gap}> a quote${gap}After.`,
+    )
+  })
+
+  test('does NOT space between items of the same loose list / same-kind blocks', () => {
+    const looseList = '- first\n\n- second\n\n- third'
+    expect(addParagraphSpacers(looseList)).toBe(looseList)
+    const quotes = '> one\n\n> two'
+    expect(addParagraphSpacers(quotes)).toBe(quotes)
+  })
+
+  test('never reaches inside a fenced block (interior blank line untouched)', () => {
+    const input = 'Before.\n\n```\nline 1\n\nline 2\n```\n\nAfter.'
+    const out = addParagraphSpacers(input)
+    // The fence interior — including its own blank line — is byte-for-byte intact.
+    expect(out).toContain('```\nline 1\n\nline 2\n```')
+  })
+
+  test('a body with no paragraph gap is returned unchanged', () => {
+    expect(addParagraphSpacers('just one paragraph, no gap')).toBe('just one paragraph, no gap')
+  })
+
+  test('composes after normalizeParagraphBreaks: prose gap spaced, list left tight', () => {
     const input = [
       'Summary of the change.',
       '',
@@ -477,11 +531,12 @@ describe('paragraph gap spacing — single blank line, no NBSP', () => {
       '- adds a normalizer',
       '- lifts the cap',
     ].join('\n')
-    const out = normalizeParagraphBreaks(input)
-    expect(out).toContain('Summary of the change.\n\nIt does two things.')
-    expect(out).toContain('It does two things.\n\n- adds a normalizer\n- lifts the cap')
-    expect(out).not.toContain(NBSP)
-    expect(out).not.toMatch(/\n\n\n/)
+    const out = addParagraphSpacers(normalizeParagraphBreaks(input))
+    // The two prose paragraphs gain a visible spacer between them.
+    expect(out).toContain(`Summary of the change.${gap}It does two things.`)
+    // The prose→list transition gains a spacer too (uniform block spacing),
+    // but the list INTERIOR stays tight.
+    expect(out).toContain(`It does two things.${gap}- adds a normalizer\n- lifts the cap`)
   })
 })
 
@@ -522,12 +577,12 @@ describe('normalizeParagraphBreaks — inline bullet split integration', () => {
  * ragged / oversized gap: CommonMark discards it so it buys no visible space,
  * but it reads as noise in the raw text. Step 1 of normalizeParagraphBreaks now
  * collapses any run of blank lines — including whitespace-only interior lines —
- * to exactly one clean `\n\n`. The collapse is deliberately ASCII-only, so a
- * genuine user-typed U+00A0 line survives (the conservative choice; there is no
- * longer an NBSP paragraph spacer to protect — that pass was removed).
+ * to exactly one clean `\n\n`, WITHOUT ever eating the deliberate U+00A0
+ * paragraph spacer that addParagraphSpacers (#2692) adds later for a visible
+ * gap on the rich-message path.
  */
 describe('normalizeParagraphBreaks — whitespace-only blank-line collapse (Bug 2)', () => {
-  const NBSP = String.fromCharCode(0xa0)
+  const NBSP = ' '
 
   test('a lone-space blank line between paragraphs collapses to a clean `\\n\\n` (real string)', () => {
     const input =
@@ -580,11 +635,14 @@ describe('normalizeParagraphBreaks — whitespace-only blank-line collapse (Bug
     expect(normalizeParagraphBreaks(input)).toBe(input)
   })
 
-  test('a genuine user-typed U+00A0-only line survives (ASCII-only collapse)', () => {
-    // The blank-line collapse is deliberately ASCII-only, so a non-breaking
-    // space a user actually typed on its own line is not silently eaten.
-    const input = 'Alpha para.\n' + NBSP + '\nBravo para.'
-    expect(normalizeParagraphBreaks(input)).toBe(input)
+  test('the deliberate U+00A0 spacer from addParagraphSpacers is preserved (no #2692 regression)', () => {
+    const normalized = normalizeParagraphBreaks('Alpha para.\n\nBravo para.')
+    const spaced = addParagraphSpacers(normalized)
+    // addParagraphSpacers wedges a U+00A0-only line to force a visible gap.
+    expect(spaced).toContain('\n\n' + PARAGRAPH_SPACER + '\n\n')
+    expect(spaced.split('\n')).toContain(NBSP)
+    // And re-running the normalizer must NOT eat that intentional spacer.
+    expect(normalizeParagraphBreaks(spaced)).toBe(spaced)
   })
 
   test('idempotent: collapsing a stray gap twice is stable', () => {

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 ===).