switchroom 0.18.19 → 0.18.21

package/telegram-plugin/tests/subagent-watcher-first-paint-independence.test.ts

@@ -0,0 +1,171 @@
+/**
+ * First-paint independence (#3231) regression.
+ *
+ * LIVE BUG (a57fbf, 2026-07-13): an async foreground sub-agent registered at
+ * 13:17:27, did two Bash calls, then its first tool BLOCKED for ~99s (no JSONL
+ * growth). Its spawning turn ended at 13:17:48 while it kept running, so there
+ * was neither a live parent turn to nest into NOR a worker-feed row to paint —
+ * and because the worker card is driven ONLY by growth-triggered onProgress
+ * cues, NOTHING surfaced. The card did not appear until 13:20:52, 205s after
+ * registration, on the next growth event that happened to route to the feed.
+ *
+ * The watcher's contract fix: a running, non-historical entry must emit a
+ * growth-INDEPENDENT skeleton liveness cue on every no-growth poll — an empty
+ * step line carrying the entry's real current state — so the gateway can paint
+ * (and keep alive) the card from registration onward, regardless of whether the
+ * worker's JSONL is currently growing. The gateway routes it: inert on the
+ * foreground-nest path (empty child), row-creating on the orphan/background
+ * worker-feed path.
+ *
+ * These assert OUTCOMES on the onProgress cue stream with an INJECTED clock.
+ * A skeleton cue is identified by its explicit `skeleton: true` discriminator
+ * (it also carries an empty `latestSummary` and no `progressLine`).
+ *
+ * RED-ON-REGRESSION: before the fix, readSubTail early-returns on a no-growth
+ * poll BEFORE firing any onProgress cue, so ZERO skeleton cues are emitted and
+ * every assertion below fails — reproducing the invisible-card window.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentToolUse(name: string, id: string) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
+}
+
+interface Cue { agentId: string; progressLine?: string; latestSummary: string; elapsedMs: number; skeleton?: boolean }
+
+describe('sub-agent card first-paint independence (#3231)', () => {
+  let tmpRoot = ''
+  const started: Array<ReturnType<typeof startSubagentWatcher>> = []
+
+  afterEach(() => {
+    while (started.length) {
+      try { started.pop()?.stop() } catch { /* ignore */ }
+    }
+    if (tmpRoot) {
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+      tmpRoot = ''
+    }
+  })
+
+  const RESCAN_MS = 1000
+
+  function startWatcher(agentDir: string) {
+    let currentTime = 100_000
+    const cues: Cue[] = []
+    const intervals: Array<{ fn: () => void; ref: number }> = []
+    let nextRef = 1
+    const watcher = startSubagentWatcher({
+      agentDir,
+      onFinish: () => {},
+      onProgress: ({ agentId, progressLine, latestSummary, elapsedMs, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, elapsedMs, skeleton })
+      },
+      stallThresholdMs: 600_000,
+      silentSynthesisStallThresholdMs: 600_000,
+      rescanMs: RESCAN_MS,
+      now: () => currentTime,
+      setInterval: (fn) => { const ref = nextRef++; intervals.push({ fn, ref }); return { ref } },
+      clearInterval: (handle) => {
+        const { ref } = handle as { ref: number }
+        const idx = intervals.findIndex((i) => i.ref === ref)
+        if (idx !== -1) intervals.splice(idx, 1)
+      },
+      setTimeout: () => ({ ref: nextRef++ }),
+      clearTimeout: () => {},
+      log: () => {},
+    })
+    started.push(watcher)
+    return {
+      watcher,
+      cues,
+      poll: () => intervals[0]?.fn(),
+      advance: (ms: number) => { currentTime += ms },
+      now: () => currentTime,
+    }
+  }
+
+  const skeletonCues = (cues: Cue[]): Cue[] =>
+    cues.filter((c) => c.skeleton === true)
+
+  function makeSubagentDir(root: string): string {
+    const agentDir = join(root, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    return agentDir
+  }
+
+  it('emits a growth-independent skeleton cue on the first no-growth poll after registration', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-deadbeef.jsonl')
+
+    // Start the watcher on an empty subagents dir, THEN the worker spawns — the
+    // real async Agent-tool path (the JSONL appears post-boot, so the entry is
+    // live/non-historical, not a boot-time rediscovery). Only its prompt is on
+    // disk, no assistant output yet (it is "thinking"): the pre-content window
+    // the user stares at.
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // Next poll: the JSONL has NOT grown. Pre-fix, readSubTail early-returns and
+    // NO cue fires — the card is invisible. Post-fix, a skeleton cue surfaces so
+    // the gateway can paint the card without waiting for the worker's output.
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    const skel = skeletonCues(h.cues)
+    expect(skel.length, 'a skeleton cue must fire on a no-growth poll').toBeGreaterThanOrEqual(1)
+    // Tight bound vs the ~205s live behaviour: first cue is within a couple polls
+    // of registration, NOT minutes.
+    expect(skel[0].elapsedMs).toBeLessThanOrEqual(2 * RESCAN_MS)
+  })
+
+  it('keeps surfacing skeleton cues while a worker is silent after an early tool burst (blocked first tool)', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-silent-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-a57fbf00.jsonl')
+
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Debug delegation regression')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // The worker does two quick Bash calls (the a57fbf shape) …
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+    h.advance(RESCAN_MS)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b2')))
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    // … then its tool BLOCKS: no JSONL growth for a long stretch (~30 polls).
+    // The card must NOT go dark — a skeleton cue must fire on essentially every
+    // no-growth poll so the feed row is created/kept-alive and the heartbeat can
+    // climb the elapsed. Pre-fix, zero cues fire across the entire silent window.
+    const before = h.cues.length
+    for (let i = 0; i < 30; i++) {
+      h.advance(RESCAN_MS)
+      h.poll()
+    }
+    const duringSilence = h.cues.slice(before)
+    const skel = duringSilence.filter((c) => c.skeleton === true)
+    expect(skel.length, 'silent worker must keep emitting skeleton cues').toBeGreaterThanOrEqual(20)
+    // No skeleton cue ever fabricates content — the step line stays empty.
+    for (const c of skel) expect(c.latestSummary).toBe('')
+  })
+})

package/telegram-plugin/tests/subagent-watcher-narrative-early-paint.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Residual A regression: a worker / sub-agent's OPENING narration must paint
+ * EARLY on its card (~the next poll after PENDING_NARRATIVE_FLUSH_MS) WITHOUT
+ * waiting for the worker's first tool — the same time-box the main-agent card
+ * got in #3227, applied uniformly to the poll-driven worker/sub-agent path via
+ * the SHARED NarrativeFlushController kernel driven by the injected poll clock.
+ *
+ * These assert OUTCOMES on the onProgress cue stream (the worker card is
+ * replace-on-write via onProgress), driven by an INJECTED clock so the timing
+ * is deterministic:
+ *   - a parked opening narration fires a narrative cue after the flush window
+ *     with NO tool event (RED if the early-paint tick is removed);
+ *   - it fires at more than one entry (depth-generic — the registry is flat, so
+ *     every sub-agent/worker/nested sub-worker is a WorkerEntry and the gate is
+ *     per-entry);
+ *   - the early-painted block is NOT re-fired (no double-print) and does not
+ *     leave a stale duplicate when the first real tool step lands after it;
+ *   - a tool arriving WITHIN the window still resolves the block exactly once
+ *     (no early-paint + resolve double).
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+import { PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentAssistantText(text: string) {
+  return { type: 'assistant', message: { content: [{ type: 'text', text }] } }
+}
+function subAgentToolUse(name: string, id: string) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
+}
+
+interface Cue { progressLine?: string; latestSummary: string; skeleton?: boolean }
+
+describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
+  let tmpRoot = ''
+  const started: Array<ReturnType<typeof startSubagentWatcher>> = []
+
+  afterEach(() => {
+    while (started.length) {
+      try { started.pop()?.stop() } catch { /* ignore */ }
+    }
+    if (tmpRoot) {
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+      tmpRoot = ''
+    }
+  })
+
+  /** Watcher over a real tmpdir with an INJECTED, manually-advanced clock. */
+  function startWatcher(agentDir: string) {
+    let currentTime = 100_000
+    const cues: Array<{ agentId: string } & Cue> = []
+    const intervals: Array<{ fn: () => void; ref: number }> = []
+    let nextRef = 1
+    const watcher = startSubagentWatcher({
+      agentDir,
+      onFinish: () => {},
+      onProgress: ({ agentId, progressLine, latestSummary, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, skeleton })
+      },
+      stallThresholdMs: 600_000,
+      silentSynthesisStallThresholdMs: 600_000,
+      rescanMs: 1000,
+      now: () => currentTime,
+      setInterval: (fn) => { const ref = nextRef++; intervals.push({ fn, ref }); return { ref } },
+      clearInterval: (handle) => {
+        const { ref } = handle as { ref: number }
+        const idx = intervals.findIndex((i) => i.ref === ref)
+        if (idx !== -1) intervals.splice(idx, 1)
+      },
+      setTimeout: () => ({ ref: nextRef++ }),
+      clearTimeout: () => {},
+      log: () => {},
+    })
+    started.push(watcher)
+    return {
+      watcher,
+      cues,
+      poll: () => intervals[0]?.fn(),
+      advance: (ms: number) => { currentTime += ms },
+    }
+  }
+
+  function narrativeCues(cues: Cue[]): string[] {
+    // Narrative cues carry NO progressLine; tool-label cues do. Skeleton
+    // liveness cues (#3231) also carry no progressLine but an empty summary —
+    // exclude them here so this counts only real narrative content.
+    return cues.filter((c) => !c.skeleton && c.progressLine == null).map((c) => c.latestSummary)
+  }
+
+  it('paints a parked opening narration after the flush window with NO tool event', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-early-paint-'))
+    const agentDir = join(tmpRoot, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    const h = startWatcher(agentDir)
+    h.poll() // register + promote to live
+
+    // Opening narration arrives; the worker then "thinks" (no tool yet).
+    appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('On it — pulling the logs first.')))
+    h.poll() // parks the block, arms the early-paint timer — NO cue yet
+    expect(narrativeCues(h.cues), 'parked block must not paint before the window').toHaveLength(0)
+
+    // Advance past the flush window and poll again — STILL no new jsonl event.
+    h.advance(PENDING_NARRATIVE_FLUSH_MS + 50)
+    h.poll()
+
+    const narr = narrativeCues(h.cues)
+    expect(narr, 'opening narration must early-paint without a tool').toHaveLength(1)
+    expect(narr[0]).toContain('pulling the logs')
+  })
+
+  it('does NOT paint before the flush window elapses', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-early-paint-nofire-'))
+    const agentDir = join(tmpRoot, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    const h = startWatcher(agentDir)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('On it — pulling the logs first.')))
+    h.poll()
+
+    // Advance LESS than the window — the tick must not fire yet.
+    h.advance(PENDING_NARRATIVE_FLUSH_MS - 50)
+    h.poll()
+    expect(narrativeCues(h.cues), 'must not paint before the window').toHaveLength(0)
+  })
+
+  it('is depth-generic: two independent entries each early-paint their opening narration', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-early-paint-depth-'))
+    const agentDir = join(tmpRoot, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    // Two entries stand in for two nesting levels: the registry is FLAT, so a
+    // top worker and a nested depth-2 sub-worker are both plain WorkerEntry
+    // rows and take the identical per-entry gate — this proves the mechanism
+    // is depth-generic (it operates on the generic node, not a fixed level).
+    const aPath = join(subagentsDir, 'agent-aaaa0000.jsonl')
+    const bPath = join(subagentsDir, 'agent-bbbb1111.jsonl')
+    writeFileSync(aPath, buildJSONL(subAgentUserMsg('Level 1 task')))
+    writeFileSync(bPath, buildJSONL(subAgentUserMsg('Level 2 task')))
+    const h = startWatcher(agentDir)
+    h.poll()
+    appendFileSync(aPath, buildJSONL(subAgentAssistantText('Worker A: reading the config.')))
+    appendFileSync(bPath, buildJSONL(subAgentAssistantText('Worker B: cloning the repo.')))
+    h.poll()
+    expect(narrativeCues(h.cues)).toHaveLength(0)
+
+    h.advance(PENDING_NARRATIVE_FLUSH_MS + 50)
+    h.poll()
+
+    const aCues = h.cues.filter((c) => c.agentId === 'aaaa0000' && c.progressLine == null)
+    const bCues = h.cues.filter((c) => c.agentId === 'bbbb1111' && c.progressLine == null)
+    expect(aCues.map((c) => c.latestSummary).join(' ')).toContain('reading the config')
+    expect(bCues.map((c) => c.latestSummary).join(' ')).toContain('cloning the repo')
+  })
+
+  it('does not double-print: an early-painted block is not re-shown when the first real tool lands', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-early-paint-nodup-'))
+    const agentDir = join(tmpRoot, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    const h = startWatcher(agentDir)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('On it — pulling the logs first.')))
+    h.poll()
+    h.advance(PENDING_NARRATIVE_FLUSH_MS + 50)
+    h.poll() // early-paint fires (1 narrative cue)
+    expect(narrativeCues(h.cues)).toHaveLength(1)
+
+    // Now the worker's first real tool lands. The parked block was already
+    // consumed by the timer → it must NOT re-fire as a narrative cue, and the
+    // tool-label cue is a SEPARATE step (no stale duplicate narration).
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+    h.advance(10)
+    h.poll()
+
+    expect(narrativeCues(h.cues), 'narration must not be re-shown').toHaveLength(1)
+    const toolCues = h.cues.filter((c) => c.progressLine != null)
+    expect(toolCues.length, 'the tool step fires as its own cue').toBeGreaterThanOrEqual(1)
+  })
+
+  it('a tool arriving WITHIN the window resolves the block exactly once (no early-paint + resolve double)', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-early-paint-within-'))
+    const agentDir = join(tmpRoot, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    const h = startWatcher(agentDir)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentAssistantText('On it — let me find the repo.')))
+    h.poll()
+    // Tool lands well within the window → resolve shows it once; timer never fires.
+    h.advance(50)
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+    h.poll()
+    // Advance past the window: the (already-consumed) block must not re-paint.
+    h.advance(PENDING_NARRATIVE_FLUSH_MS + 50)
+    h.poll()
+    expect(narrativeCues(h.cues), 'resolved narration shows exactly once').toHaveLength(1)
+  })
+})

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

@@ -584,9 +584,10 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
           // Narrative ticks carry NO progressLine (tool ticks do); record them.
-          if (progressLine == null) narrativeCues.push(latestSummary)
+          // Skeleton liveness cues (#3231) are not narrative — exclude them.
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo path')))
@@ -614,8 +615,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -647,8 +648,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          allCues.push({ progressLine, latestSummary })
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton) allCues.push({ progressLine, latestSummary })
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -698,8 +699,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
@@ -728,8 +729,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
@@ -761,8 +762,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))

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

@@ -19,6 +19,8 @@ import {
   repairEscapedWhitespace,
   escapeMarkdown,
   splitMarkdownChunks,
+  addParagraphSpacers,
+  PARAGRAPH_SPACER,
   RICH_MESSAGE_MAX_CHARS,
 } from '../format.js'
 
@@ -185,56 +187,67 @@ describe('splitMarkdownChunks', () => {
   })
 
   // -------------------------------------------------------------------------
-  // Chunk-boundary blank-line hygiene. Paragraph gaps are now plain `\n\n`
-  // (the NBSP spacer was removed in the #2669 follow-up). When a cut lands in
-  // a gap, the boundary must not leave a chunk that opens or ends with a bare
-  // blank line, and no visible content may be dropped.
+  // Chunk-boundary spacer hygiene. addParagraphSpacers injects a
+  // `\n\n${PARAGRAPH_SPACER}\n\n` gap between prose paragraphs. When a cut
+  // lands inside that gap, the boundary must not leave a chunk that opens or
+  // ends with a bare U+00A0 spacer line (a stray blank bubble line).
   // -------------------------------------------------------------------------
 
-  test('no chunk starts or ends with a bare blank line at a `\\n\\n` gap cut', () => {
+  test('no chunk starts or ends with a bare U+00A0 spacer line (reviewer repro)', () => {
+    // The exact reviewer repro: a spacer gap straddling a small cap.
     const A = 'Alpha sentence one'
     const B = 'Bravo sentence two'
-    const text = `${A}.\n\n${B}.`
-    const chunks = splitMarkdownChunks(text, 33)
+    const spaced = addParagraphSpacers(`${A}.\n\n${B}.`)
+    const chunks = splitMarkdownChunks(spaced, 33)
     expect(chunks.length).toBeGreaterThan(1)
-    const blankOnly = /^[ \t]*$/
+    const spacerOnly = new RegExp(`^[ \\t]*${PARAGRAPH_SPACER}[ \\t]*$`)
     for (const c of chunks) {
       const lines = c.split('\n')
-      expect(blankOnly.test(lines[0])).toBe(false)
-      expect(blankOnly.test(lines[lines.length - 1])).toBe(false)
+      expect(spacerOnly.test(lines[0])).toBe(false)
+      expect(spacerOnly.test(lines[lines.length - 1])).toBe(false)
     }
   })
 
   test('visible paragraph content survives the boundary (no text dropped)', () => {
     const A = 'Alpha sentence one'
     const B = 'Bravo sentence two'
-    const text = `${A}.\n\n${B}.`
-    const chunks = splitMarkdownChunks(text, 33)
+    const spaced = addParagraphSpacers(`${A}.\n\n${B}.`)
+    const chunks = splitMarkdownChunks(spaced, 33)
     const rejoined = chunks.join('\n')
     expect(rejoined).toContain(`${A}.`)
     expect(rejoined).toContain(`${B}.`)
   })
 
-  test('blank-line-boundary strip is robust across several gaps and small caps', () => {
+  test('spacer-boundary strip is robust across several gaps and small caps', () => {
     const paras = Array.from({ length: 6 }, (_, i) => `Paragraph ${i} body text here.`)
-    const text = paras.join('\n\n')
-    const blankOnly = /^[ \t]*$/
+    const spaced = addParagraphSpacers(paras.join('\n\n'))
+    const spacerOnly = new RegExp(`^[ \\t]*${PARAGRAPH_SPACER}[ \\t]*$`)
     for (const cap of [20, 31, 40, 64]) {
-      const chunks = splitMarkdownChunks(text, cap)
+      const chunks = splitMarkdownChunks(spaced, cap)
       for (const c of chunks) {
         const lines = c.split('\n')
-        expect(blankOnly.test(lines[0])).toBe(false)
-        expect(blankOnly.test(lines[lines.length - 1])).toBe(false)
+        expect(spacerOnly.test(lines[0])).toBe(false)
+        expect(spacerOnly.test(lines[lines.length - 1])).toBe(false)
       }
-      // No visible word is dropped: concatenating the chunks' non-blank tokens
-      // reproduces the original word sequence. (Word-level, not line-level,
-      // because a small cap may split mid-word — the chunker's normal
-      // space-boundary behaviour.)
-      const words = (s: string): string[] => s.split(/\s+/).filter((w) => w.length > 0)
+      // No visible word is dropped: concatenating the chunks' non-blank,
+      // non-spacer tokens reproduces the original word sequence. (Word-level,
+      // not line-level, because a small cap may split mid-word — that's the
+      // chunker's normal space-boundary behaviour, orthogonal to spacers.)
+      const words = (s: string): string[] =>
+        s.split(/\s+/).filter((w) => w.length > 0 && w !== PARAGRAPH_SPACER)
       expect(words(chunks.join(' '))).toEqual(words(paras.join(' ')))
     }
   })
 
+  test('a boundary with NO spacer is unaffected (legacy ^\\n+ behaviour preserved)', () => {
+    const text = Array.from({ length: 10 }, (_, i) => `plain line ${i}`).join('\n\n')
+    const chunks = splitMarkdownChunks(text, 40)
+    // No spacer was ever present, so no chunk gains/loses anything beyond the
+    // normal leading-newline strip; content is preserved.
+    const rejoined = chunks.join('\n').replace(/\n+/g, '\n')
+    expect(rejoined).toBe(text.replace(/\n+/g, '\n'))
+  })
+
   // -------------------------------------------------------------------------
   // Entity-aware chunking (#finding-3): a cut must never bisect an inline
   // span (`**bold**`, `` `code` ``, `_italic_`, `[label](href)`), which would

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -31,7 +31,9 @@ import {
   normalizeParagraphBreaks,
   normalizePunctuation,
   stripExcessBold,
+  addParagraphSpacers,
   splitMarkdownChunks,
+  PARAGRAPH_SPACER,
   RICH_MESSAGE_MAX_CHARS,
 } from '../format.js'
 
@@ -128,9 +130,7 @@ describe('decideTurnFlush — prose+trailing-sentinel is suppressed, not leaked
 // the real gateway turn-flush render pipeline (post-#2669 rich-markdown path):
 //   decideTurnFlush -> join('\n\n')
 //   -> repairEscapedWhitespace -> normalizeParagraphBreaks
-//   -> splitMarkdownChunks -> sendRichMessage
-// (no paragraph-spacer pass — the NBSP spacer was removed in the #2669
-//  follow-up; gaps are plain `\n\n`, one visible blank line)
+//   -> addParagraphSpacers -> splitMarkdownChunks -> sendRichMessage
 // so it pins the end-to-end fix, not just the pure decision. The corpus is a
 // REAL captured-transcript shape (three separate content[i].text blocks, one
 // stored UNTRIMMED with a trailing '\n' exactly as session-tail.ts pushes
@@ -156,7 +156,8 @@ describe('#2798 turn-flush block separation — real multi-block transcript shap
     const d = decideTurnFlush({ chatId: '12345', replyCalled: false, capturedText: blocks })
     expect(d.kind).toBe('flush')
     const joined = (d as { kind: 'flush'; text: string }).text
-    return normalizeParagraphBreaks(repairEscapedWhitespace(joined))
+    const normalized = normalizeParagraphBreaks(repairEscapedWhitespace(joined))
+    return addParagraphSpacers(normalized)
   }
 
   it('separates whole blocks with a visible paragraph gap, not a wall-of-text', () => {
@@ -166,29 +167,32 @@ describe('#2798 turn-flush block separation — real multi-block transcript shap
     expect(out).toContain('The `auth` handler looks correct')
     expect(out).toContain('Want me to open a PR')
     // The wall-of-text failure mode glues two blocks one '\n' apart. Assert the
-    // boundary carries a real paragraph break (plain `\n\n`, one blank line —
-    // no NBSP spacer), and NOT a single-newline join.
-    expect(out).toContain('flagged.\n\nThe `auth`')
+    // boundary carries a real paragraph break with the injected visible spacer
+    // line (#2692 rich-path spacer), and NOT a single-newline join.
+    expect(out).toContain(`\n\n${PARAGRAPH_SPACER}\n\n`)
     expect(out).not.toContain('flagged.\nThe `auth`')
-    // No U+00A0 anywhere.
-    expect(out).not.toContain(String.fromCharCode(0xa0))
+    // A spacer sits specifically between block 1 and block 2.
+    const b1 = out.indexOf('flagged.')
+    const b2 = out.indexOf('The `auth` handler')
+    expect(out.slice(b1, b2)).toContain(PARAGRAPH_SPACER)
   })
 
   it('collapses the untrimmed-trailing-newline stack — no 3+ newline run reaches the wire', () => {
     const out = renderLikeTurnFlush(realBlocks)
     // Block 2's trailing '\n' + the '\n\n' join = 3 newlines; normalize
-    // collapses 3+ runs to '\n\n', so no doubled/stacked blank run survives.
+    // collapses 3+ runs to '\n\n' and addParagraphSpacers wedges exactly one
+    // spacer, so no doubled/stacked blank run survives.
     expect(out).not.toMatch(/\n{3,}/)
-    // One blank-line gap per block transition: 3 blocks → 2 gaps.
-    const gapCount = (out.match(/\n\n/g) ?? []).length
-    expect(gapCount).toBe(2)
+    // One spacer per block transition: 3 blocks → 2 gaps → 2 spacers.
+    const spacerCount = out.split(PARAGRAPH_SPACER).length - 1
+    expect(spacerCount).toBe(2)
   })
 
   it('the whole separated answer stays in one rich chunk here (well under 32768)', () => {
     const out = renderLikeTurnFlush(realBlocks)
     const chunks = splitMarkdownChunks(out, RICH_MESSAGE_MAX_CHARS)
     expect(chunks.length).toBe(1)
-    expect(chunks[0]).toContain('\n\n')
+    expect(chunks[0]).toContain(PARAGRAPH_SPACER)
   })
 
   it('still SUPPRESSES a real transcript that deliberately terminates with a bare NO_REPLY (#2053 guard intact)', () => {
@@ -224,9 +228,9 @@ describe('#2798 turn-flush block separation — real multi-block transcript shap
 // runs (gateway executeReply):
 //   repairEscapedWhitespace -> normalizeParagraphBreaks -> redactOutboundText
 //   -> stripExcessBold(normalizePunctuation) -> scrubVoice
-// (no send-side paragraph-spacer pass — removed in the #2669 follow-up).
+//   -> addParagraphSpacers (send side)
 // The original #2798 change gave turn-flush the paragraph steps + redact +
-// scrub but OMITTED `stripExcessBold(normalizePunctuation(...))`.
+// scrub + spacers but OMITTED `stripExcessBold(normalizePunctuation(...))`.
 // This suite reconstructs the deterministic format chain of BOTH paths (the
 // runtime-only redact + voice-scrub steps are literally the same calls on both
 // paths and are out of scope here) and pins that turn-flush now matches reply
@@ -308,7 +312,7 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   function formatChain(text: string): string {
     let t = normalizeParagraphBreaks(repairEscapedWhitespace(text))
     t = stripExcessBold(normalizePunctuation(t))
-    return t
+    return addParagraphSpacers(t)
   }
 
   const input =