switchroom 0.18.19 → 0.18.21

package/telegram-plugin/tests/answer-ready-flush.test.ts

@@ -0,0 +1,343 @@
+/**
+ * PR A — answer-ready quiescence flush (late-delivery fix).
+ *
+ * The gateway delivers a toolless terminal-text answer either on claude's
+ * (unreliable) `turn_duration`/turn_end, or — when that never lands — on the
+ * orphaned-reply backstop, which the answer text itself keeps re-arming across
+ * a ~150 s window. PR A adds a DETERMINISTIC ~1 s quiescence flush.
+ *
+ * Two layers of coverage:
+ *   1. The pure predicate `shouldArmAnswerReadyFlush` (which calls the REAL
+ *      `decideTurnFlush` classifier + a REAL `ToolFlightTracker`).
+ *   2. An INTEGRATION harness that drives the REAL orchestration —
+ *      `AnswerReadyFlushController` (the exact arm / debounce / rollover-guard /
+ *      fire-time-re-verify / disarm code the gateway runs, extracted so it is
+ *      testable, mirroring how `turn-end-gate-backstop.test.ts` drives the real
+ *      `withTurnEndGateBackstop`). The harness supplies a faithful gateway world
+ *      (a mutable `currentTurn`, a real `ToolFlightTracker`, and an
+ *      `endCurrentTurnAtomic` that — like the real one — disarms via
+ *      `controller.clear(turn)` and NULLS the atom) plus a send-sink that models
+ *      `handleSessionEvent({turn_end})` short-circuiting on a null atom.
+ *
+ * The oracle asserts OUTCOMES on real code: the flush fires at the ~1 s debounce
+ * (not ~150 s), re-arms per text chunk, and delivers EXACTLY ONCE across both
+ * turn_end race orderings. It is designed to go RED if the controller's
+ * rollover guard, fire-time re-verify, or disarm were removed (see the
+ * red-when-removed proofs in the handback).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  shouldArmAnswerReadyFlush,
+  resolveAnswerReadyFlushMs,
+  ANSWER_READY_FLUSH_MS,
+  AnswerReadyFlushController,
+  type AnswerReadyArmInput,
+  type FlushTimerHandle,
+} from '../answer-ready-flush.js'
+import { ToolFlightTracker } from '../gateway/interrupt-defer.js'
+
+const CHAT = '12345'
+const WINDOW = 1000
+// The orphaned-reply backstop's real dead-wait ceiling — the wall-clock the
+// flush must beat. Used to prove the flush fires ~1 s, not ~150 s.
+const BACKSTOP_MS = 150_000
+
+function armInput(over: Partial<AnswerReadyArmInput> = {}): AnswerReadyArmInput {
+  return {
+    flush: {
+      chatId: CHAT,
+      replyCalled: false,
+      capturedText: ['Here is the composed final answer to your question.'],
+      flushEnabled: true,
+    },
+    inFlightToolCount: 0,
+    hasPendingAsyncDispatch: false,
+    flushWindowMs: WINDOW,
+    ...over,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure predicate: shouldArmAnswerReadyFlush (real decideTurnFlush classifier)
+// ---------------------------------------------------------------------------
+
+describe('shouldArmAnswerReadyFlush (arm/fire predicate)', () => {
+  it('arms on a genuine composed terminal answer that is quiescent', () => {
+    expect(shouldArmAnswerReadyFlush(armInput())).toBe(true)
+  })
+
+  it('does NOT arm while a tool is in flight (not quiescent)', () => {
+    expect(shouldArmAnswerReadyFlush(armInput({ inFlightToolCount: 1 }))).toBe(false)
+  })
+
+  it('does NOT arm while a background/async dispatch is pending', () => {
+    expect(shouldArmAnswerReadyFlush(armInput({ hasPendingAsyncDispatch: true }))).toBe(false)
+  })
+
+  it('does NOT arm once the reply tool has served the turn (reply-called)', () => {
+    expect(
+      shouldArmAnswerReadyFlush(armInput({ flush: { chatId: CHAT, replyCalled: true, capturedText: ['x'], flushEnabled: true } })),
+    ).toBe(false)
+  })
+
+  it('does NOT arm on a genuine NO_REPLY turn (silent marker → no spurious flush)', () => {
+    expect(
+      shouldArmAnswerReadyFlush(armInput({ flush: { chatId: CHAT, replyCalled: false, capturedText: ['NO_REPLY'], flushEnabled: true } })),
+    ).toBe(false)
+  })
+
+  it('does NOT arm on an empty terminal turn (nothing to send)', () => {
+    expect(
+      shouldArmAnswerReadyFlush(armInput({ flush: { chatId: CHAT, replyCalled: false, capturedText: [], flushEnabled: true } })),
+    ).toBe(false)
+  })
+
+  it('does NOT arm on prose that ends with a trailing silent marker', () => {
+    expect(
+      shouldArmAnswerReadyFlush(
+        armInput({ flush: { chatId: CHAT, replyCalled: false, capturedText: ['Some prose the model wrote.', 'NO_REPLY'], flushEnabled: true } }),
+      ),
+    ).toBe(false)
+  })
+
+  it('does NOT arm for a system/sub-agent turn (no inbound chat)', () => {
+    expect(
+      shouldArmAnswerReadyFlush(armInput({ flush: { chatId: null, replyCalled: false, capturedText: ['answer'], flushEnabled: true } })),
+    ).toBe(false)
+  })
+
+  it('does NOT arm when the kill-switch disables the flush (window <= 0)', () => {
+    expect(shouldArmAnswerReadyFlush(armInput({ flushWindowMs: 0 }))).toBe(false)
+    expect(shouldArmAnswerReadyFlush(armInput({ flushWindowMs: -1 }))).toBe(false)
+  })
+
+  it('does NOT arm when the turn-flush safety flag is off', () => {
+    expect(
+      shouldArmAnswerReadyFlush(armInput({ flush: { chatId: CHAT, replyCalled: false, capturedText: ['answer'], flushEnabled: false } })),
+    ).toBe(false)
+  })
+})
+
+describe('resolveAnswerReadyFlushMs', () => {
+  it('defaults to ANSWER_READY_FLUSH_MS when unset', () => {
+    expect(resolveAnswerReadyFlushMs({})).toBe(ANSWER_READY_FLUSH_MS)
+    expect(resolveAnswerReadyFlushMs({ SWITCHROOM_ANSWER_READY_FLUSH_MS: '' })).toBe(ANSWER_READY_FLUSH_MS)
+  })
+
+  it('parses a positive override', () => {
+    expect(resolveAnswerReadyFlushMs({ SWITCHROOM_ANSWER_READY_FLUSH_MS: '1500' })).toBe(1500)
+  })
+
+  it('treats 0 (and negatives) as the kill-switch → disabled (0)', () => {
+    expect(resolveAnswerReadyFlushMs({ SWITCHROOM_ANSWER_READY_FLUSH_MS: '0' })).toBe(0)
+    expect(resolveAnswerReadyFlushMs({ SWITCHROOM_ANSWER_READY_FLUSH_MS: '-5' })).toBe(0)
+  })
+
+  it('fails safe to the default on an unparseable value', () => {
+    expect(resolveAnswerReadyFlushMs({ SWITCHROOM_ANSWER_READY_FLUSH_MS: 'nonsense' })).toBe(ANSWER_READY_FLUSH_MS)
+  })
+
+  it('ANSWER_READY_FLUSH_MS is ~1 s ("immediate")', () => {
+    expect(ANSWER_READY_FLUSH_MS).toBe(1000)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Integration harness — drives the REAL AnswerReadyFlushController. Only the
+// gateway world (currentTurn storage, the send sink, endCurrentTurnAtomic) is
+// modeled; the arm / debounce / rollover-guard / fire-time-re-verify / disarm
+// is the controller's REAL code. Mirrors turn-end-gate-backstop.test.ts driving
+// the real withTurnEndGateBackstop.
+// ---------------------------------------------------------------------------
+
+interface FakeTurn {
+  capturedText: string[]
+  replyCalled: boolean
+  answerReadyFlushTimeoutId: FlushTimerHandle | null
+}
+
+/**
+ * A faithful gateway world around the REAL controller. `sends` / `records`
+ * count what actually reached the user / turns.jsonl. `endCurrentTurnAtomic`
+ * mirrors the real one: it DISARMS via `controller.clear(turn)` and NULLS the
+ * atom. `dispatchTurnEnd` mirrors `handleSessionEvent({turn_end})`: it
+ * short-circuits when the atom is already gone (the exactly-once guarantee),
+ * else delivers once and runs `endCurrentTurnAtomic`.
+ */
+class GatewayWorld {
+  currentTurn: FakeTurn | null
+  flight = new ToolFlightTracker()
+  pendingAsync = false
+  sends = 0
+  records = 0
+  window = WINDOW
+  readonly controller: AnswerReadyFlushController<FakeTurn>
+
+  constructor() {
+    this.currentTurn = { capturedText: [], replyCalled: false, answerReadyFlushTimeoutId: null }
+    this.controller = new AnswerReadyFlushController<FakeTurn>({
+      getCurrentTurn: () => this.currentTurn,
+      getArmInput: (turn) => ({
+        flush: { chatId: CHAT, replyCalled: turn.replyCalled, capturedText: turn.capturedText, flushEnabled: true },
+        inFlightToolCount: this.flight.inFlightCount(),
+        hasPendingAsyncDispatch: this.pendingAsync,
+        flushWindowMs: this.window,
+      }),
+      getTimerHandle: (turn) => turn.answerReadyFlushTimeoutId,
+      setTimerHandle: (turn, handle) => {
+        turn.answerReadyFlushTimeoutId = handle
+      },
+      // The controller's single delivery action routes into the world's
+      // turn_end dispatch — exactly as the gateway's onFlush dispatches a
+      // synthetic turn_end into handleSessionEvent.
+      onFlush: () => this.dispatchTurnEnd(),
+    })
+  }
+
+  /** = endCurrentTurnAtomic: DISARM (real controller.clear) + NULL the atom. */
+  private endCurrentTurnAtomic(turn: FakeTurn): void {
+    this.controller.clear(turn) // ← the load-bearing disarm (gateway.ts:~4818)
+    this.records++
+    this.currentTurn = null // ← the load-bearing atom-null (#1067)
+  }
+
+  /** = handleSessionEvent({turn_end}). A null atom short-circuits (no second
+   *  send); otherwise deliver once and tear the turn down. */
+  dispatchTurnEnd(): void {
+    const turn = this.currentTurn
+    if (turn == null) return // atom already gone → exactly-once
+    this.sends++
+    this.endCurrentTurnAtomic(turn)
+  }
+
+  /** = case 'text': push the chunk, then (re)arm via the REAL controller. */
+  onText(chunk: string): void {
+    if (this.currentTurn != null) this.currentTurn.capturedText.push(chunk)
+    this.controller.reset()
+  }
+
+  /** = case 'tool_use' / 'tool_label': disarm (real controller.clear) then track. */
+  onToolUse(id: string): void {
+    this.controller.clear(this.currentTurn)
+    this.flight.onEvent({ kind: 'tool_use', toolUseId: id })
+  }
+
+  onToolResult(id: string): void {
+    this.flight.onEvent({ kind: 'tool_result', toolUseId: id })
+  }
+}
+
+describe('answer-ready quiescence flush — real controller integration', () => {
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('flushes the composed answer at the ~1 s debounce, NOT at the ~150 s backstop', () => {
+    const w = new GatewayWorld()
+    w.onText('The composed final answer.')
+    // Nothing before the debounce elapses.
+    vi.advanceTimersByTime(WINDOW - 1)
+    expect(w.sends).toBe(0)
+    // Fires deterministically at the debounce.
+    vi.advanceTimersByTime(1)
+    expect(w.sends).toBe(1)
+    expect(w.records).toBe(1) // exactly one turns.jsonl record
+    // And it did NOT wait for the multi-minute backstop.
+    expect(vi.getTimerCount()).toBe(0)
+    vi.advanceTimersByTime(BACKSTOP_MS)
+    expect(w.sends).toBe(1) // still exactly one — proves it beat ~150 s
+  })
+
+  it('each text chunk re-arms the debounce (only fires 1 s after the LAST chunk)', () => {
+    const w = new GatewayWorld()
+    w.onText('Part one. ')
+    vi.advanceTimersByTime(500)
+    expect(w.sends).toBe(0)
+    w.onText('Part two — the rest of the answer.') // re-arms
+    vi.advanceTimersByTime(999)
+    expect(w.sends).toBe(0) // debounce reset by the 2nd chunk
+    vi.advanceTimersByTime(1)
+    expect(w.sends).toBe(1)
+  })
+
+  it('EXACTLY-ONCE (a): quiescence flush, THEN a real turn_end → still one send', () => {
+    const w = new GatewayWorld()
+    w.onText('Answer text.')
+    vi.advanceTimersByTime(WINDOW)
+    expect(w.sends).toBe(1) // quiescence flushed + nulled the atom
+    // The real turn_end finally lands — it must short-circuit on the null atom.
+    // (Goes red if the atom-null in endCurrentTurnAtomic were removed.)
+    w.dispatchTurnEnd()
+    expect(w.sends).toBe(1)
+    expect(w.records).toBe(1)
+  })
+
+  it('EXACTLY-ONCE (b): a real turn_end BEFORE the debounce disarms the pending flush', () => {
+    const w = new GatewayWorld()
+    w.onText('Answer text.')
+    vi.advanceTimersByTime(WINDOW - 100)
+    // turn_end arrives first → delivers once and (via controller.clear in
+    // endCurrentTurnAtomic) cancels the pending flush timer.
+    // (Goes red if controller.clear no longer cleared the timer.)
+    w.dispatchTurnEnd()
+    expect(w.sends).toBe(1)
+    expect(vi.getTimerCount()).toBe(0) // the pending quiescence timer was cleared
+    vi.advanceTimersByTime(BACKSTOP_MS)
+    expect(w.sends).toBe(1) // the stale timer never fired a second send
+    expect(w.records).toBe(1)
+  })
+
+  it('does NOT flush while a tool call is in flight (only on genuine quiescence)', () => {
+    const w = new GatewayWorld()
+    w.onText('Interim thought before a tool.')
+    // A tool starts within the window → disarm.
+    vi.advanceTimersByTime(400)
+    w.onToolUse('bash_1')
+    vi.advanceTimersByTime(BACKSTOP_MS)
+    expect(w.sends).toBe(0) // never fired while (and after) the tool was open
+    expect(vi.getTimerCount()).toBe(0)
+  })
+
+  it('re-arms and flushes once the tool completes and new answer text settles', () => {
+    const w = new GatewayWorld()
+    w.onText('Working on it.')
+    w.onToolUse('bash_1') // disarm
+    vi.advanceTimersByTime(2000)
+    expect(w.sends).toBe(0)
+    w.onToolResult('bash_1') // tool done → quiescent again
+    w.onText(' Here is the final composed answer.') // new text re-arms
+    vi.advanceTimersByTime(WINDOW)
+    expect(w.sends).toBe(1)
+  })
+
+  it('fire-time re-verify: a tool in flight at expiry cancels the flush even if disarm was missed', () => {
+    const w = new GatewayWorld()
+    w.onText('Answer text.')
+    // Simulate a missed explicit disarm: a tool becomes in-flight directly,
+    // WITHOUT going through onToolUse (which would clear the timer).
+    w.flight.onEvent({ kind: 'tool_use', toolUseId: 'sneaky' })
+    vi.advanceTimersByTime(WINDOW)
+    // (Goes red if the controller's fire-time re-verification were removed.)
+    expect(w.sends).toBe(0)
+  })
+
+  it('rollover guard: a superseded turn does not fire against a fresh atom', () => {
+    const w = new GatewayWorld()
+    const armed = w.currentTurn!
+    w.onText('Answer for turn A.') // arms A's timer
+    // A new turn swaps in before the debounce (turn rollover).
+    w.currentTurn = { capturedText: ['Turn B is still working'], replyCalled: false, answerReadyFlushTimeoutId: null }
+    expect(w.currentTurn).not.toBe(armed)
+    vi.advanceTimersByTime(WINDOW)
+    // (Goes red if the controller's rollover guard `live !== armedTurn` were removed.)
+    expect(w.sends).toBe(0)
+  })
+
+  it('a NO_REPLY turn never arms, so it flushes nothing (records no_reply upstream)', () => {
+    const w = new GatewayWorld()
+    w.onText('NO_REPLY')
+    vi.advanceTimersByTime(BACKSTOP_MS)
+    expect(w.sends).toBe(0)
+    expect(vi.getTimerCount()).toBe(0)
+  })
+})

package/telegram-plugin/tests/cron-inject-idle-clock.test.ts

@@ -0,0 +1,54 @@
+/**
+ * #3114 — a cron fire must NOT warm the MAIN session's idle-clear clock.
+ *
+ * Root cause (confirmed live): `onInjectInbound` stamped the main idle clock
+ * UNCONDITIONALLY at inject time. A cron cadence shorter than
+ * `idle_clear_after` re-armed the timer on every fire, so idle-clear was
+ * permanently suppressed for any agent with a frequent scheduled task —
+ * including cheap-cron fires routed to the derived `<agent>-cron` bridge,
+ * whose session events never reach the main clock at all.
+ *
+ * This covers the pure identity predicate `isCronInjectFire` — which inject
+ * fires warm the main clock. It did not exist on main → import fails there.
+ *
+ * The gateway WIRING (that `onInjectInbound` gates the stamp on
+ * `!isCronInjectFire(...)`, that a cron cadence shorter than the window no
+ * longer re-arms the clock, and that a human inbound still warms it) is now
+ * covered BEHAVIOURALLY in `idle-clear.test.ts` — the
+ * `IdleTracker #3114` block drives the REAL predicate + the REAL `IdleTracker`
+ * through the exact gateway rule. #3115 extracted the idle bookkeeping into an
+ * importable object, so that block replaces the brittle source-text wiring pin
+ * this file used to carry (a regression in the real stamp logic now fails a
+ * behavioural assertion, not just a string-match over gateway.ts).
+ */
+
+import { describe, it, expect } from 'vitest'
+import { isCronInjectFire } from '../gateway/cron-session.js'
+
+describe('#3114 isCronInjectFire — which inject fires warm the main idle clock', () => {
+  it('a cheap-cron fire (routed to the derived <agent>-cron bridge) does NOT warm the clock', () => {
+    // Tier-1: scheduler tags meta.session='cron' → resolveInjectTarget sends it
+    // to `<agent>-cron`; its session events are dropped for the cron identity.
+    expect(isCronInjectFire({ session: 'cron', source: 'cron' })).toBe(true)
+    expect(isCronInjectFire({ session: 'cron' })).toBe(true)
+  })
+
+  it('a Tier-2 (main-session) cron fire does NOT warm the clock at inject time', () => {
+    // Tier-2 lands on the main bridge but is still a scheduled fire — the
+    // inject-time stamp is suppressed (its real turn stamps via session events;
+    // that is the documented residual, not the inject-time path).
+    expect(isCronInjectFire({ source: 'cron' })).toBe(true)
+  })
+
+  it('a genuine operator/session inject (reaction, vault grant, resume) DOES warm the clock', () => {
+    expect(isCronInjectFire({ source: 'reaction' })).toBe(false)
+    expect(isCronInjectFire({ source: 'vault_grant_approved' })).toBe(false)
+    expect(isCronInjectFire({ source: 'resume' })).toBe(false)
+  })
+
+  it('a bare / manual inject with no cron marker DOES warm the clock', () => {
+    expect(isCronInjectFire(undefined)).toBe(false)
+    expect(isCronInjectFire({})).toBe(false)
+    expect(isCronInjectFire({ prompt_key: 'x' })).toBe(false)
+  })
+})

package/telegram-plugin/tests/emission-authority-facade.test.ts

@@ -370,13 +370,15 @@ describe('the drain sites route through the façade with producers preserved ver
 
   it('every routed drain site guards the single-flight via ea.mayDrain(turn), not a bare activityInFlight read', () => {
     const mayDrainGuards = [...gatewaySrc.matchAll(/if \(ea\.mayDrain\(turn\)\)/g)]
-    // narrative + 2 liveness + tool + 2 sub-agent + 1 post-answer bg-liveness
-    // (Fix 2) = 7. The Phase-1 0-label climb (deterministic-turn-liveness.md)
-    // consults the SAME guard, but its `if (deps.mayDrain())` lives in the
-    // extracted tick body (feed-heartbeat-climb.ts) with `() => ea.mayDrain(turn)`
-    // injected at the gateway call site — pinned by
-    // feed-heartbeat-liveness-open.test.ts + silent-turn-climb-transport.test.ts.
-    expect(mayDrainGuards).toHaveLength(7)
+    // narrative SHOW + narrative RETRACT (timer-flush early-paint retract,
+    // narrative-flush.ts) + 2 liveness + tool + 2 sub-agent + 1 post-answer
+    // bg-liveness (Fix 2) = 8. The Phase-1 0-label climb
+    // (deterministic-turn-liveness.md) consults the SAME guard, but its
+    // `if (deps.mayDrain())` lives in the extracted tick body
+    // (feed-heartbeat-climb.ts) with `() => ea.mayDrain(turn)` injected at the
+    // gateway call site — pinned by feed-heartbeat-liveness-open.test.ts +
+    // silent-turn-climb-transport.test.ts.
+    expect(mayDrainGuards).toHaveLength(8)
     expect(gatewaySrc).toMatch(/mayDrain:\s*\(\)\s*=>\s*ea\.mayDrain\(turn\)/)
   })
 })
@@ -498,11 +500,12 @@ describe('mayDrainCardNow — PR-4d card-drain gate (pure read; gateway holds th
   })
 
   it('the card-drain sites each route their guarded block through cardDrainGate (single-flight gate stays byte-identical)', () => {
-    // Option A: the 7 `if (ea.mayDrain(turn))` guards + drainActivitySummary
+    // Option A: the 8 `if (ea.mayDrain(turn))` guards + drainActivitySummary
     // thunks stay byte-identical, wrapped by the centralized helper.
-    // 6 original + 1 new post-answer background-agent liveness drain (Fix 2).
+    // 6 original + 1 post-answer background-agent liveness drain (Fix 2) + 1
+    // narrative-retract drain (timer-flush early-paint retract, narrative-flush.ts).
     const wraps = [...gatewaySrc.matchAll(/cardDrainGate\(turn, ea, \(\) => \{/g)]
-    expect(wraps).toHaveLength(7)
+    expect(wraps).toHaveLength(8)
     // The Phase-1 0-label climb (deterministic-turn-liveness.md) routes through
     // the SAME helper via an injected thunk — its call lives in the extracted
     // tick body (feed-heartbeat-climb.ts), wired at the gateway call site as

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

@@ -1,10 +1,12 @@
 /**
  * Tests for the fleet-wide consistent-formatting bundle:
  *
- *   1. paragraph gap spacing — a plain `\n\n` (one blank line) at EVERY block
+ *   1. addParagraphSpacers — a visible U+00A0 spacer line at EVERY block
  *      transition (paragraph→list, list→paragraph, heading→anything,
- *      blockquote/table boundaries), never a double blank line and never an
- *      NBSP spacer (the old spacer pass was removed in the #2669 follow-up).
+ *      blockquote/table boundaries), idempotent and double-gap-proof; list/
+ *      table interiors stay tight. Restored after the #3208 F1 misfire — the
+ *      rich GFM renderer renders a bare `\n\n` gap TIGHT, so the spacer is what
+ *      produces the visible paragraph gap.
  *   2. normalizePunctuation — em/en dashes → comma/hyphen, leading `•`/`·`
  *      list markers → `- `, on code-masked text, idempotent; link hrefs are
  *      protected from dash rewriting.
@@ -13,13 +15,17 @@
  */
 import { describe, test, expect } from 'vitest'
 import {
+  addParagraphSpacers,
   normalizeParagraphBreaks,
   normalizePunctuation,
   stripExcessBold,
   splitMarkdownChunks,
   hardenCardBreaks,
+  PARAGRAPH_SPACER,
 } from '../format.js'
 
+const SP = PARAGRAPH_SPACER // U+00A0
+
 describe('hardenCardBreaks — deterministic card line-break hardener', () => {
   test('promotes lone field breaks to GFM hard breaks (the blob fix)', () => {
     const out = hardenCardBreaks('Agent: assistant\nAuth: Max\nStatus: running')
@@ -98,60 +104,74 @@ describe('hardenCardBreaks — deterministic card line-break hardener', () => {
   })
 })
 
-describe('paragraph gap spacing — plain single blank line, no NBSP', () => {
-  const NBSP = String.fromCharCode(0xa0)
-
-  test('prose→prose gap is one blank line, no NBSP', () => {
-    const out = normalizeParagraphBreaks('Alpha.\n\nBravo.')
-    expect(out).toBe('Alpha.\n\nBravo.')
-    expect(out).not.toContain(NBSP)
+describe('addParagraphSpacers — uniform block spacing', () => {
+  test('still spaces prose→prose (existing behaviour)', () => {
+    const out = addParagraphSpacers('Alpha.\n\nBravo.')
+    expect(out).toBe(`Alpha.\n\n${SP}\n\nBravo.`)
   })
 
-  test('paragraph→list transition is a single `\\n\\n` boundary', () => {
-    expect(normalizeParagraphBreaks('Intro.\n\n- one\n- two')).toBe('Intro.\n\n- one\n- two')
+  test('spaces paragraph→list transition', () => {
+    const out = addParagraphSpacers('Intro.\n\n- one\n- two')
+    expect(out).toBe(`Intro.\n\n${SP}\n\n- one\n- two`)
   })
 
-  test('list→paragraph transition is a single `\\n\\n` boundary', () => {
-    expect(normalizeParagraphBreaks('- one\n- two\n\nOutro.')).toBe('- one\n- two\n\nOutro.')
+  test('spaces list→paragraph transition', () => {
+    const out = addParagraphSpacers('- one\n- two\n\nOutro.')
+    expect(out).toBe(`- one\n- two\n\n${SP}\n\nOutro.`)
   })
 
-  test('heading→anything is a single `\\n\\n` boundary', () => {
-    expect(normalizeParagraphBreaks('# Title\n\nBody.')).toBe('# Title\n\nBody.')
-    expect(normalizeParagraphBreaks('# Title\n\n- a\n- b')).toBe('# Title\n\n- a\n- b')
+  test('spaces heading→anything', () => {
+    expect(addParagraphSpacers('# Title\n\nBody.')).toBe(`# Title\n\n${SP}\n\nBody.`)
+    expect(addParagraphSpacers('# Title\n\n- a\n- b')).toBe(`# Title\n\n${SP}\n\n- a\n- b`)
   })
 
-  test('blockquote and table boundaries are single `\\n\\n`', () => {
-    expect(normalizeParagraphBreaks('> quoted\n\nProse.')).toBe('> quoted\n\nProse.')
+  test('spaces blockquote and table boundaries', () => {
+    expect(addParagraphSpacers('> quoted\n\nProse.')).toBe(`> quoted\n\n${SP}\n\nProse.`)
     const table = '| a | b |\n| --- | --- |\n| 1 | 2 |'
-    expect(normalizeParagraphBreaks(`Prose.\n\n${table}`)).toBe(`Prose.\n\n${table}`)
-    expect(normalizeParagraphBreaks(`${table}\n\nProse.`)).toBe(`${table}\n\nProse.`)
+    expect(addParagraphSpacers(`Prose.\n\n${table}`)).toBe(`Prose.\n\n${SP}\n\n${table}`)
+    expect(addParagraphSpacers(`${table}\n\nProse.`)).toBe(`${table}\n\n${SP}\n\nProse.`)
+  })
+
+  test('does NOT space between items of the same loose list', () => {
+    const input = '- one\n\n- two\n\n- three'
+    expect(addParagraphSpacers(input)).toBe(input)
+  })
+
+  test('does NOT space inside a tight list or table interior (single \\n)', () => {
+    const list = 'Intro.\n\n- a\n- b\n- c'
+    expect(addParagraphSpacers(list)).toBe(`Intro.\n\n${SP}\n\n- a\n- b\n- c`)
+    const table = '| a |\n| --- |\n| 1 |\n| 2 |'
+    expect(addParagraphSpacers(table)).toBe(table)
+  })
+
+  test('idempotent across every transition kind', () => {
+    const input = '# H\n\nProse one.\n\n- a\n- b\n\nProse two.\n\n> quote'
+    const once = addParagraphSpacers(input)
+    expect(addParagraphSpacers(once)).toBe(once)
   })
 
   test('never touches code fences', () => {
     const input = '```\nA\n\nB\n```\n\n```\nC\n```'
-    expect(normalizeParagraphBreaks(input)).toBe(input)
+    expect(addParagraphSpacers(input)).toBe(input)
   })
 
-  test('full pipeline: mixed prose+list message gets single-blank-line gaps, no NBSP, no double gap', () => {
-    const raw = 'Summary line.\n\n- item one\n- item two\n\nClosing prose.'
-    const out = normalizeParagraphBreaks(raw)
-    expect(out).toBe('Summary line.\n\n- item one\n- item two\n\nClosing prose.')
-    expect(out).not.toContain(NBSP)
-    expect(out).not.toMatch(/\n\n\n/)
+  test('full pipeline: mixed prose+list+heading message gets uniform gaps', () => {
+    const raw = 'Summary line.\n- item one\n- item two\nClosing prose.'
+    const out = addParagraphSpacers(normalizeParagraphBreaks(raw))
+    // Every block transition carries exactly one visible spacer line.
+    expect(out).toBe(
+      `Summary line.\n\n${SP}\n\n- item one\n- item two\n\n${SP}\n\nClosing prose.`,
+    )
   })
 
-  test('chunk-boundary interaction: a cut in a `\\n\\n` gap leaves clean chunks (no stray blank lines)', () => {
+  test('chunk-boundary interaction: a cut in a spacer gap strips the spacer', () => {
     const a = 'A'.repeat(60)
     const b = 'B'.repeat(60)
-    const text = `${a}\n\n${b}`
+    const text = `${a}\n\n${SP}\n\n${b}`
     const chunks = splitMarkdownChunks(text, 80)
     expect(chunks.length).toBe(2)
     expect(chunks[0]).toBe(a)
     expect(chunks[1]).toBe(b)
-    // Neither chunk opens or ends with a stray blank line.
-    for (const c of chunks) {
-      expect(c).toBe(c.replace(/^\n+|\n+$/g, ''))
-    }
   })
 })
 

package/telegram-plugin/tests/formatting-parse-regression.test.ts

@@ -17,10 +17,9 @@
  *       fixture intended (bold/italic/code/pre/link at the right inner text).
  *
  * The pipeline mirrors `telegram-plugin/gateway/gateway.ts`:
- *   repairEscapedWhitespace -> normalizeParagraphBreaks -> splitMarkdownChunks.
- *   (No paragraph-spacer pass — the NBSP spacer was removed in the #2669
- *   follow-up; gaps are plain `\n\n`. Card-surface fixtures also apply
- *   `normalizeDashes` first — that is where F1's voice scrub lives.)
+ *   repairEscapedWhitespace -> normalizeParagraphBreaks -> addParagraphSpacers
+ *   -> splitMarkdownChunks. (Card-surface fixtures also apply `normalizeDashes`
+ *   first — that is where F1's voice scrub lives.)
  *
  * This suite is TEST-ONLY. It changes no production formatting behaviour. If a
  * fixture ever fails signal (a), it means the formatter emits markdown Telegram
@@ -31,6 +30,7 @@ import { describe, test, expect } from 'vitest'
 import {
   repairEscapedWhitespace,
   normalizeParagraphBreaks,
+  addParagraphSpacers,
   splitMarkdownChunks,
   RICH_MESSAGE_MAX_CHARS,
 } from '../format.js'
@@ -57,7 +57,8 @@ function transform(input: string, opts: { cardSurfaceScrub?: boolean; cap?: numb
 } {
   let text = input
   if (opts.cardSurfaceScrub) text = normalizeDashes(text)
-  const body = normalizeParagraphBreaks(repairEscapedWhitespace(text))
+  text = normalizeParagraphBreaks(repairEscapedWhitespace(text))
+  const body = addParagraphSpacers(text)
   const chunks = splitMarkdownChunks(body, opts.cap ?? RICH_MESSAGE_MAX_CHARS)
   return { chunks, body }
 }

package/telegram-plugin/tests/formatting-torture-set.ts

@@ -7,7 +7,7 @@
  * The `input` is the raw text as a model/card surface would author it — the
  * regression test runs it through the SAME outbound transform pipeline the
  * gateway uses (repairEscapedWhitespace -> normalizeParagraphBreaks ->
- * splitMarkdownChunks) and then asserts:
+ * addParagraphSpacers -> splitMarkdownChunks) and then asserts:
  *
  *   (a) every emitted chunk is parse-accept valid (no rich-path 400), and
  *   (b) the concatenated output parses into `expect` (entity structure).