switchroom 0.21.7 → 0.21.9

package/telegram-plugin/tests/pending-inbound-buffer.test.ts

@@ -7,7 +7,8 @@
  */
 
 import { describe, it, expect } from 'vitest'
-import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, planBufferedRedelivery, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
+import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, planBufferedRedelivery, selectEvictionVictim, DEFAULT_PENDING_INBOUND_CAP, APPROVAL_OUTCOME_PROTECTION_MS } from '../gateway/pending-inbound-buffer.js'
+import { APPROVAL_OUTCOME_SOURCES, APPROVAL_OUTCOME_DROPPED_SOURCE, isApprovalOutcome, createApprovalOutcomeDropNotifier } from '../gateway/approval-outcome-sources.js'
 import type { InboundMessage } from '../gateway/ipc-protocol.js'
 import { ObligationLedger } from '../gateway/obligation-ledger.js'
 import { makeRepresentRedeliveryGuard } from '../gateway/represent-delivery-guard.js'
@@ -171,7 +172,11 @@ describe('pending-inbound-buffer', () => {
     const buf = createPendingInboundBuffer({ capPerAgent: 1, log: (l) => logs.push(l) })
     buf.push('a', inbound('m1', 1))
     buf.push('a', inbound('m2', 2)) // evicts m1
-    expect(logs.some((l) => l.includes('cap=1') && l.includes('dropped oldest'))).toBe(true)
+    // PR D: victim selection is tiered, so the line names the index + tier
+    // rather than claiming "oldest" (it is the oldest of its tier).
+    expect(
+      logs.some((l) => l.includes('cap=1') && l.includes('dropped entry idx=0 reason=non-outcome')),
+    ).toBe(true)
     expect(logs.some((l) => l.includes('m1'))).toBe(true)
   })
 
@@ -849,3 +854,439 @@ describe('redeliverBufferedInbound — beforeRedeliver fail-open on throw', () =
     expect(buf.depth('a')).toBe(0) // nothing stranded
   })
 })
+
+/**
+ * PR D — cap eviction must not pick an APPROVAL OUTCOME while anything else is
+ * droppable. The victim used to be an unconditional `q.shift()`, and the oldest
+ * entry is exactly the one most likely to be a synthetic approval outcome that
+ * has been waiting through an entire turn. An ordinary chat message is
+ * resendable; a `vault_grant_approved` is not — the operator's tap already
+ * happened, so "please resend" is meaningless and the agent blocks forever.
+ */
+describe('pending-inbound-buffer — approval-outcome eviction protection (PR D)', () => {
+  /** A button tap: NO meta.source at all, only meta.button_callback. */
+  function tap(ts: number): InboundMessage {
+    return {
+      type: 'inbound',
+      chatId: 'c1',
+      messageId: ts,
+      user: 'alice',
+      userId: 42,
+      ts,
+      text: '[user tapped button: Approve]',
+      meta: { button_callback: 'true', button_callback_data: 'ag:ok', button_text: 'Approve' },
+    }
+  }
+
+  it('an outcome at the HEAD survives an overflow of ordinary messages', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} }) // cap 32
+    buf.push('a', inbound('vault_grant_approved', 1))
+    for (let i = 0; i < 31; i++) buf.push('a', userMsg({ text: `m${i}`, ts: 100 + i }))
+    buf.push('a', userMsg({ text: 'overflow', ts: 999 }))
+    const drained = buf.drain('a')
+    expect(drained.some((m) => m.meta?.source === 'vault_grant_approved')).toBe(true)
+    // The oldest ORDINARY message went instead, and nothing else was lost.
+    expect(drained).toHaveLength(32)
+    expect(drained.map((m) => m.text)).not.toContain('m0')
+    expect(drained.map((m) => m.text)).toContain('overflow')
+  })
+
+  it('a sustained ordinary-message burst never evicts the buffered outcome', () => {
+    const buf = createPendingInboundBuffer({ capPerAgent: 4, log: () => {} })
+    buf.push('a', inbound('secret_provided', 1))
+    for (let i = 0; i < 40; i++) buf.push('a', userMsg({ text: `u${i}`, ts: 100 + i }))
+    const drained = buf.drain('a')
+    expect(drained[0]?.meta?.source).toBe('secret_provided')
+    expect(drained.map((m) => m.text).slice(1)).toEqual(['u37', 'u38', 'u39'])
+  })
+
+  it('a button tap is protected too — it carries NO meta.source', () => {
+    const buf = createPendingInboundBuffer({ capPerAgent: 3, log: () => {} })
+    buf.push('a', tap(1))
+    buf.push('a', userMsg({ text: 'u1', ts: 2 }))
+    buf.push('a', userMsg({ text: 'u2', ts: 3 }))
+    buf.push('a', userMsg({ text: 'u3', ts: 4 }))
+    const drained = buf.drain('a')
+    expect(drained[0]?.meta?.button_callback).toBe('true')
+    expect(drained.map((m) => m.text).slice(1)).toEqual(['u2', 'u3'])
+  })
+
+  it('survivors keep insertion order after a mid-queue eviction (FIFO contract)', () => {
+    const buf = createPendingInboundBuffer({ capPerAgent: 4, log: () => {} })
+    buf.push('a', inbound('vault_grant_approved', 1))
+    buf.push('a', userMsg({ text: 'u1', ts: 2 }))
+    buf.push('a', userMsg({ text: 'u2', ts: 3 }))
+    buf.push('a', userMsg({ text: 'u3', ts: 4 }))
+    buf.push('a', userMsg({ text: 'u4', ts: 5 })) // evicts u1 (index 1), not the head
+    expect(buf.drain('a').map((m) => m.meta?.source ?? m.text)).toEqual([
+      'vault_grant_approved', 'u2', 'u3', 'u4',
+    ])
+  })
+
+  it('onEvict (not onEvictCritical) fires for an ordinary victim', () => {
+    const ordinary: InboundMessage[] = []
+    const critical: InboundMessage[] = []
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 2,
+      log: () => {},
+      onEvict: (_a, m) => ordinary.push(m),
+      onEvictCritical: (_a, m) => critical.push(m),
+    })
+    buf.push('a', inbound('vault_grant_approved', 1))
+    buf.push('a', userMsg({ text: 'u1', ts: 2 }))
+    buf.push('a', userMsg({ text: 'u2', ts: 3 }))
+    expect(ordinary.map((m) => m.text)).toEqual(['u1'])
+    expect(critical).toHaveLength(0)
+  })
+
+  it('all-outcomes fallback: drops the oldest and fires onEvictCritical, NOT onEvict', () => {
+    const ordinary: InboundMessage[] = []
+    const critical: { agent: string; msg: InboundMessage }[] = []
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      now: () => 1000, // all three below are well inside the protection window
+      onEvict: (_a, m) => ordinary.push(m),
+      onEvictCritical: (agent, msg) => critical.push({ agent, msg }),
+    })
+    buf.push('a', inbound('vault_grant_approved', 900))
+    buf.push('a', inbound('secret_provided', 950))
+    buf.push('a', inbound('skill_proposal_apply', 980))
+    expect(critical).toHaveLength(0)
+    buf.push('a', inbound('mental_model_proposal_applied', 999))
+    expect(ordinary).toHaveLength(0)
+    expect(critical).toHaveLength(1)
+    expect(critical[0]!.agent).toBe('a')
+    expect(critical[0]!.msg.meta?.source).toBe('vault_grant_approved')
+    expect(critical[0]!.msg.ts).toBe(900)
+    // The newest outcome is in and the other two are intact.
+    expect(buf.drain('a').map((m) => m.meta?.source)).toEqual([
+      'secret_provided', 'skill_proposal_apply', 'mental_model_proposal_applied',
+    ])
+  })
+
+  it('a STALE outcome is evictable — protection is bounded, so it cannot pin the buffer', () => {
+    const critical: InboundMessage[] = []
+    const nowMs = 100 * 60 * 1000
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 2,
+      log: () => {},
+      now: () => nowMs,
+      onEvictCritical: (_a, m) => critical.push(m),
+    })
+    // Stale: older than the 15-min protection window (already spool-escalated).
+    buf.push('a', inbound('vault_grant_timeout', nowMs - 20 * 60 * 1000))
+    // Fresh.
+    buf.push('a', inbound('secret_provided', nowMs - 1000))
+    buf.push('a', inbound('vault_grant_approved', nowMs))
+    expect(critical.map((m) => m.meta?.source)).toEqual(['vault_grant_timeout'])
+    // The FRESH outcomes both survived — staleness, not arrival order, decided it.
+    expect(buf.drain('a').map((m) => m.meta?.source)).toEqual([
+      'secret_provided', 'vault_grant_approved',
+    ])
+  })
+
+  it('APPROVAL_OUTCOME_PROTECTION_MS matches the spool escalation window', () => {
+    expect(APPROVAL_OUTCOME_PROTECTION_MS).toBe(15 * 60 * 1000)
+  })
+
+  it('cap of 1 with a single fresh outcome: evicts it and reports critical', () => {
+    const critical: InboundMessage[] = []
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 1,
+      log: () => {},
+      now: () => 1000,
+      onEvictCritical: (_a, m) => critical.push(m),
+    })
+    buf.push('a', inbound('vault_grant_approved', 900))
+    buf.push('a', inbound('secret_provided', 950))
+    expect(critical.map((m) => m.meta?.source)).toEqual(['vault_grant_approved'])
+    expect(buf.drain('a').map((m) => m.meta?.source)).toEqual(['secret_provided'])
+  })
+
+  it('a throwing onEvictCritical never breaks the push hot path', () => {
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 1,
+      log: () => {},
+      onEvictCritical: () => { throw new Error('notice failed') },
+    })
+    buf.push('a', inbound('vault_grant_approved', 1))
+    expect(() => buf.push('a', inbound('secret_provided', 2))).not.toThrow()
+    expect(buf.drain('a').map((m) => m.meta?.source)).toEqual(['secret_provided'])
+  })
+
+  describe('selectEvictionVictim tiers', () => {
+    const out = (ts: number) => inbound('vault_grant_approved', ts)
+    const ord = (ts: number) => userMsg({ text: `u${ts}`, ts })
+
+    it('empty queue is safe (index 0, no crash at the call site)', () => {
+      expect(selectEvictionVictim([], 0)).toEqual({ index: 0, reason: 'all-outcomes' })
+    })
+
+    it('picks the FIRST non-outcome, not merely any non-outcome', () => {
+      expect(selectEvictionVictim([out(1), out(2), ord(3), ord(4)], 5)).toEqual({
+        index: 2, reason: 'non-outcome',
+      })
+    })
+
+    it('prefers an ordinary message over a STALE outcome', () => {
+      const nowMs = 60 * 60 * 1000
+      expect(selectEvictionVictim([out(1), ord(nowMs)], nowMs)).toEqual({
+        index: 1, reason: 'non-outcome',
+      })
+    })
+
+    // Tier 2 vs tier 3. These two tiers agree on the victim whenever the queue
+    // is in `ts`-ascending order (the oldest entry is then also the stalest),
+    // so an in-order fixture CANNOT tell them apart — disabling the age bound
+    // entirely leaves such a test green (verified by mutation). The
+    // discriminating case is a queue whose head is FRESH and whose later entry
+    // is STALE.
+    it('prefers a STALE outcome over a fresher one queued ahead of it', () => {
+      const nowMs = 100 * 60 * 1000
+      const fresh = out(nowMs)
+      const stale = out(nowMs - 20 * 60 * 1000) // past the 15-min window
+      expect(selectEvictionVictim([fresh, stale], nowMs)).toEqual({
+        index: 1, reason: 'stale-outcome',
+      })
+    })
+
+    // The `reason` is not cosmetic: it is what the eviction log line reports,
+    // and it is the only signal distinguishing "dropped an outcome the spool
+    // already escalated" from "dropped a live one because there was nothing
+    // else". Pin it in the ordinary in-order shape too.
+    it('reports stale-outcome (not all-outcomes) when the victim is past its window', () => {
+      const nowMs = 100 * 60 * 1000
+      expect(
+        selectEvictionVictim([out(nowMs - 20 * 60 * 1000), out(nowMs)], nowMs).reason,
+      ).toBe('stale-outcome')
+    })
+
+    // The bound must actually be a bound: an outcome one millisecond inside
+    // the window is still protected, so tier 3 is what fires.
+    it('an outcome just INSIDE the window is not stale — falls through to tier 3', () => {
+      const nowMs = 100 * 60 * 1000
+      const justInside = out(nowMs - (APPROVAL_OUTCOME_PROTECTION_MS - 1))
+      expect(selectEvictionVictim([out(nowMs), justInside], nowMs)).toEqual({
+        index: 0, reason: 'all-outcomes',
+      })
+    })
+  })
+})
+
+/**
+ * PR D — the notifier the gateway wires to `onEvictCritical`. This drives the
+ * REAL production factory (gateway.ts calls exactly this), so the re-entrancy
+ * and termination properties are pinned where they live, not in a test copy.
+ */
+describe('approval-outcome drop notifier (PR D)', () => {
+  /** Run every queued microtask to quiescence. */
+  const settle = async (): Promise<void> => {
+    for (let i = 0; i < 50; i++) await Promise.resolve()
+  }
+
+  it('the approval_outcome_dropped notice lands in the buffer and names the source', async () => {
+    // Wire it exactly as gateway.ts does: the buffer's onEvictCritical calls
+    // the notifier, and the notifier pushes back into the same buffer.
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      now: () => 1000,
+      onEvictCritical: (a, m) => notifier(a, m),
+    })
+    const notifier = createApprovalOutcomeDropNotifier({
+      push: (agent, msg) => { buf.push(agent, msg) },
+      log: () => {},
+    })
+    buf.push('a', inbound('vault_grant_approved', 900))
+    buf.push('a', inbound('secret_provided', 950))
+    buf.push('a', inbound('skill_proposal_apply', 960))
+    buf.push('a', inbound('mental_model_proposal_applied', 970)) // critical evict
+    // Nothing enqueued synchronously — the notice must NOT ride the push frame.
+    expect(buf.depth('a')).toBe(3)
+    await settle()
+    const drained = buf.drain('a')
+    const notice = drained.find((m) => m.meta?.source === 'approval_outcome_dropped')
+    expect(notice).toBeDefined()
+    // The notice push itself ran against a queue still full of outcomes, so it
+    // evicted one more. The surviving notice must name BOTH — an earlier notice
+    // naming only the first drop is exactly what the next overflow evicts.
+    expect(notice!.meta?.dropped_sources).toBe('vault_grant_approved, secret_provided')
+    expect(notice!.text).toContain('vault_grant_approved')
+    // Every outcome that was NOT dropped is still buffered.
+    expect(drained.map((m) => m.meta?.source)).toEqual([
+      'skill_proposal_apply', 'mental_model_proposal_applied', 'approval_outcome_dropped',
+    ])
+  })
+
+  // The guarantee is "a dropped approval outcome is never silent". If it
+  // depended on each construction site passing a callback it would be
+  // discipline, not a mechanism — so the notifier defaults ON and this pins it.
+  it('is wired BY DEFAULT — a bare buffer still enqueues the notice', async () => {
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      now: () => 1000,
+      // NO onEvictCritical passed.
+    })
+    buf.push('a', inbound('vault_grant_approved', 900))
+    buf.push('a', inbound('secret_provided', 950))
+    buf.push('a', inbound('skill_proposal_apply', 960))
+    buf.push('a', inbound('vault_grant_denied', 970))
+    await settle()
+    const drained = buf.drain('a')
+    const notice = drained.find((m) => m.meta?.source === 'approval_outcome_dropped')
+    expect(notice).toBeDefined()
+    expect(notice!.meta?.dropped_sources).toContain('vault_grant_approved')
+  })
+
+  it('an explicit no-op onEvictCritical opts out of the notice', async () => {
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      now: () => 1000,
+      onEvictCritical: () => {},
+    })
+    for (let i = 0; i < 6; i++) buf.push('a', inbound('vault_grant_approved', 900 + i))
+    await settle()
+    expect(buf.drain('a').some((m) => m.meta?.source === 'approval_outcome_dropped')).toBe(false)
+  })
+
+  it('a burst of critical evictions terminates and does not spin the microtask queue', async () => {
+    let pushes = 0
+    const buf = createPendingInboundBuffer({
+      capPerAgent: 3,
+      log: () => {},
+      now: () => 1000,
+      onEvictCritical: (a, m) => notifier(a, m),
+    })
+    const notifier = createApprovalOutcomeDropNotifier({
+      push: (agent, msg) => { pushes++; buf.push(agent, msg) },
+      log: () => {},
+    })
+    for (let i = 0; i < 10; i++) buf.push('a', inbound('vault_grant_approved', 900 + i))
+    await settle()
+    // Bounded: at most one notice per burst plus the follow-up hop, never one
+    // notice per evicted outcome (that is the recursion this guards).
+    expect(pushes).toBeGreaterThan(0)
+    expect(pushes).toBeLessThanOrEqual(3)
+    // A notice is resident, and it is NOT itself an approval outcome — which is
+    // what makes it the preferred victim next time and bounds the chain.
+    const drained = buf.drain('a')
+    expect(drained.some((m) => m.meta?.source === 'approval_outcome_dropped')).toBe(true)
+  })
+
+  it('a burst coalesces into ONE notice naming every dropped source', async () => {
+    const notices: InboundMessage[] = []
+    const notifier = createApprovalOutcomeDropNotifier({
+      push: (_agent, msg) => { notices.push(msg) },
+      log: () => {},
+    })
+    notifier('a', inbound('vault_grant_approved', 1))
+    notifier('a', inbound('secret_declined', 2))
+    notifier('a', inbound('skill_proposal_apply', 3))
+    expect(notices).toHaveLength(0) // deferred, never same-frame
+    await settle()
+    expect(notices).toHaveLength(1)
+    expect(notices[0]!.meta?.dropped_sources).toBe(
+      'vault_grant_approved, secret_declined, skill_proposal_apply',
+    )
+    expect(notices[0]!.meta?.dropped_count).toBe('3')
+  })
+
+  it('a button tap victim is labelled button_callback, not "-"', async () => {
+    const notices: InboundMessage[] = []
+    const notifier = createApprovalOutcomeDropNotifier({
+      push: (_agent, msg) => { notices.push(msg) },
+      log: () => {},
+    })
+    notifier('a', {
+      type: 'inbound', chatId: 'c1', messageId: 1, user: 'alice', userId: 42, ts: 1,
+      text: '[user tapped button: Approve]', meta: { button_callback: 'true' },
+    })
+    await settle()
+    expect(notices[0]!.meta?.dropped_sources).toBe('button_callback')
+  })
+})
+
+describe('isApprovalOutcome (PR D)', () => {
+  const withMeta = (meta: Record<string, string> | undefined): InboundMessage => ({
+    type: 'inbound', chatId: 'c1', messageId: 1, user: 'u', userId: 1, ts: 1, text: 't',
+    ...(meta != null ? { meta } : {}),
+  } as InboundMessage)
+
+  it('true for every registered source', () => {
+    for (const s of APPROVAL_OUTCOME_SOURCES) {
+      expect(isApprovalOutcome(withMeta({ source: s }))).toBe(true)
+    }
+  })
+
+  it('true for a button tap with no source at all', () => {
+    expect(isApprovalOutcome(withMeta({ button_callback: 'true' }))).toBe(true)
+  })
+
+  it('false for ordinary messages and non-outcome system sources', () => {
+    expect(isApprovalOutcome(withMeta({}))).toBe(false)
+    expect(isApprovalOutcome(withMeta(undefined))).toBe(false)
+    for (const s of [
+      'missed_approval_retry', 'obligation_represent', 'subagent_handback',
+      'subagent_progress', 'resume_interrupted', 'warmup', 'reaction', 'cron',
+      'approval_outcome_dropped',
+    ]) {
+      expect(isApprovalOutcome(withMeta({ source: s }))).toBe(false)
+    }
+  })
+
+  // #4664. `eval_case_suppressed` is the one protected member that is not a
+  // verdict card, and it is the one with the least margin for error: no sweep
+  // regenerates it (it fires exactly once, at suppression time, and posts no
+  // card), so an eviction is a PERMANENT block on the agent's turn. Asserted
+  // through the buffer, not just the set, so the pin fails on the behaviour
+  // rather than on a membership literal.
+  it('a buffered eval_case_suppressed notice survives a cap overflow', () => {
+    const buf = createPendingInboundBuffer({ capPerAgent: 3, log: () => {} })
+    buf.push('a', inbound('eval_case_suppressed', 1))
+    buf.push('a', userMsg({ text: 'first', ts: 2 }))
+    buf.push('a', userMsg({ text: 'second', ts: 3 }))
+    // Overflow: the resendable user message must go, not the one-shot notice.
+    buf.push('a', userMsg({ text: 'third', ts: 4 }))
+    const drained = buf.drain('a')
+    expect(drained.map((m) => m.meta?.source ?? m.text)).toEqual([
+      'eval_case_suppressed', 'second', 'third',
+    ])
+  })
+
+  it('the dropped-notice source is deliberately NOT protected', () => {
+    expect(APPROVAL_OUTCOME_SOURCES.has(APPROVAL_OUTCOME_DROPPED_SOURCE)).toBe(false)
+  })
+
+  // Drift pin on the registry itself. `Object.freeze` on a Set does NOT block
+  // `.add` (Set data lives in internal slots), so asserting `isFrozen` would be
+  // a placebo — immutability is enforced at compile time by the `ReadonlySet`
+  // type. What IS worth pinning is membership: silently dropping a source here
+  // makes that verdict class evictable again with no test going red.
+  it('the registry contents are exactly the audited set', () => {
+    expect([...APPROVAL_OUTCOME_SOURCES].sort()).toEqual([
+      'eval_case_applied',
+      'eval_case_apply_failed',
+      'eval_case_rejected',
+      'eval_case_suppressed',
+      'mental_model_proposal_applied',
+      'mental_model_proposal_denied',
+      'mental_model_proposal_failed',
+      'mental_model_propose_timeout',
+      'secret_declined',
+      'secret_provide_failed',
+      'secret_provided',
+      'secret_request_timeout',
+      'skill_proposal_apply',
+      'vault_grant_approved',
+      'vault_grant_denied',
+      'vault_grant_timeout',
+      'vault_save_completed',
+      'vault_save_discarded',
+      'vault_save_failed',
+      'vault_save_timeout',
+    ])
+  })
+})

package/telegram-plugin/tests/render/dollar-math-guard.test.ts

@@ -160,3 +160,46 @@ describe("guardDollarMath — link / table awareness (findings 1 & 3)", () => {
     expect(out).not.toMatch(/(?<!\\)\$/);
   });
 });
+
+describe("guardDollarMath — intentional math spans are exempt (wire-verified 2026-08-13)", () => {
+  it("never escapes a compact `$…$` math span", () => {
+    // Telegram renders `$x^2+y^2$` as a native mathematical_expression node;
+    // escaping it destroys a SUPPORTED construct. On the pre-fix guard this
+    // input came back as `inline \$x^2+y^2\$ done`.
+    const s = "inline $x^2+y^2$ done";
+    expect(guardDollarMath(s)).toBe(s);
+  });
+
+  it("math span dollars do not count toward the 2+ arming threshold", () => {
+    // Only ONE prose `$` outside the math span → can never pair → untouched.
+    const s = "solve $x^2+y^2$ for the $BUDGET case";
+    expect(guardDollarMath(s)).toBe(s);
+  });
+
+  it("still escapes currency in the SAME message as an exempt math span", () => {
+    const out = guardDollarMath("sum $x^2+y^2$ costs $5 and $10");
+    expect(out).toContain("$x^2+y^2$");
+    expect(out).toContain("\\$5");
+    expect(out).toContain("\\$10");
+  });
+
+  it("a currency-shaped compact pair (`$5M-$10M`) is NOT treated as math", () => {
+    // The `$5M-$` inner run is digits/magnitude punctuation only — two
+    // adjacent amounts, the exact #3252 accident. Must still be escaped.
+    const out = guardDollarMath("the range is $5M-$10M this year");
+    expect(out).not.toMatch(/(?<!\\)\$/);
+  });
+
+  it("spaced `$…$` spans are NOT exempt (indistinguishable from currency prose)", () => {
+    // Documented residual: `$a + b$` cannot be told apart from two stray
+    // currency signs, so when a currency signal arms the guard it is escaped
+    // (renders as literal text — legible, not broken).
+    const out = guardDollarMath("we know $a + b$ plus $5 fees");
+    expect(out).not.toMatch(/(?<!\\)\$/);
+  });
+
+  it("is idempotent with a math span present", () => {
+    const once = guardDollarMath("sum $x^2+y^2$ costs $5 and $10");
+    expect(guardDollarMath(once)).toBe(once);
+  });
+});

package/telegram-plugin/tests/render/guard-composition.test.ts

@@ -135,4 +135,106 @@ describe("guardAccidentalFormatting composition (#3252)", () => {
     // And re-wrapping (streaming re-render) is byte-stable.
     expect(richMessage(wire.markdown).markdown).toBe(wire.markdown);
   });
+
+  // ── Wire-verified NATIVE constructs survive the FULL pipeline ────────────
+  // Raw sendRichMessage probes (2026-08-13) proved Telegram's rich markdown
+  // path natively renders `<details>`, `$…$` inline math, and footnotes. The
+  // pre-fix pipeline destroyed all three (details → the unsupported `**>`
+  // marker, `$x^2+y^2$` → `\$x^2+y^2\$`, `[^n1]` deleted) — each assertion
+  // below FAILS on that pipeline.
+  describe("native constructs pass through the full composed guard", () => {
+    it("<details open><summary> block survives byte-identical", () => {
+      const src = "<details open><summary>S</summary>\n\nbody\n\n</details>";
+      expect(guardAccidentalFormatting(src)).toBe(src);
+      expect(richMessage(src).markdown).toBe(src);
+    });
+
+    it("compact $math$ span survives byte-identical", () => {
+      const src = "inline $x^2+y^2$ done";
+      expect(guardAccidentalFormatting(src)).toBe(src);
+    });
+
+    it("footnote reference + definition survive byte-identical", () => {
+      const src = "claim[^n1]\n\n[^n1]: body";
+      expect(guardAccidentalFormatting(src)).toBe(src);
+    });
+
+    it("`**>` is never emitted for any input the pipeline repairs", () => {
+      const out = guardAccidentalFormatting(
+        "<details><summary>T</summary>\nbody\n</details>",
+      );
+      expect(out).not.toContain("**>");
+    });
+  });
+
+  // ── Guard-interaction cases for the now-passing-through constructs ───────
+  // Removing the old token conversions changes what the sibling guards see (a
+  // surviving `$`, a surviving `<`). These prove the emphasis / heading /
+  // block-construct / inline-pair / dollar guards do not mangle the natives,
+  // while their own repairs still fire in the SAME message.
+  describe("native constructs vs sibling guards (interaction)", () => {
+    it("math span is exempt while surrounding currency is still broken apart", () => {
+      const src = "sum $x^2+y^2$ costs $5 and $10 total";
+      const out = guardAccidentalFormatting(src);
+      // The math span reaches the wire byte-identical…
+      expect(out).toContain("$x^2+y^2$");
+      // …while the accidental currency pair is still defused (#3252).
+      expect(out).toContain("\$5");
+      expect(out).toContain("\$10");
+    });
+
+    it("currency-shaped adjacent amounts are NOT mistaken for math", () => {
+      // `$5M-$10M` has a whitespace-free `$…$` pair (`$5M-$`) — the currency
+      // shape must keep it guardable, else #3252 regresses.
+      const out = guardAccidentalFormatting("range is $5M-$10M this year");
+      expect(out).not.toMatch(/(?<!\\)\$/);
+    });
+
+    it("math span interior is protected from the emphasis and caret guards", () => {
+      // `a_b*c` inside math would trip the intra-word `_`/`*` escapes, and
+      // `^2y^` is an alphanumeric caret pair the token guard would strip —
+      // both must stay verbatim inside the protected span. The `_`/`*`
+      // OUTSIDE the span are still guarded — note the protected span's
+      // delimiters do NOT count toward the 2+ pairing threshold, so the
+      // prose needs its own pairable signals (`2*3 and 4*5`).
+      const src = "$a_b*c$ and file_name_here times 2*3 and 4*5";
+      const out = guardAccidentalFormatting(src);
+      expect(out).toContain("$a_b*c$");
+      expect(out).toContain("file\\_name\\_here");
+      expect(out).toContain("2\\*3");
+      expect(out).toContain("4\\*5");
+      expect(guardAccidentalFormatting("inline $x^2y^2$ done")).toBe(
+        "inline $x^2y^2$ done",
+      );
+    });
+
+    it("<details> lines are invisible to the line-start and heading guards", () => {
+      // A details block whose body carries genuine accidental signals: the
+      // guards must fire on the BODY prose without touching the tags.
+      const src =
+        "<details open><summary>Stats</summary>\n\n>2x growth and #1 priority\n\n</details>";
+      const out = guardAccidentalFormatting(src);
+      expect(out).toContain("<details open><summary>Stats</summary>");
+      expect(out).toContain("</details>");
+      // Line-start `>2x` and glued `#1` are still repaired inside the body.
+      expect(out).toContain("\>2x");
+      expect(out).toContain("\#1");
+    });
+
+    it("footnote markers survive alongside a firing dollar guard", () => {
+      const src = "cost[^1] was $5 then $9\n\n[^1]: the note";
+      const out = guardAccidentalFormatting(src);
+      expect(out).toContain("cost[^1]");
+      expect(out).toContain("[^1]: the note");
+      expect(out).toContain("\$5");
+      expect(out).toContain("\$9");
+    });
+
+    it("the whole composition stays idempotent with natives present", () => {
+      const src =
+        "claim[^1] and $x^2+y^2$ in <details><summary>T</summary>\nb\n</details> with $5 and $10\n\n[^1]: n";
+      const once = guardAccidentalFormatting(src);
+      expect(guardAccidentalFormatting(once)).toBe(once);
+    });
+  });
 });

package/telegram-plugin/tests/render/parse.test.ts

@@ -336,7 +336,7 @@ describe("parse: nested lists", () => {
   });
 });
 
-describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
+describe("expandable blockquote (LEGACY switchroom `**>` marker — input repair only)", () => {
   it("parses a single-line `**>` quote into an expandable blockquote", () => {
     const md = "**> a collapsible line";
     const doc = parse(md);
@@ -374,10 +374,10 @@ describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
   });
 
   it("only recognises the marker at column 0 (leading indent is not expandable)", () => {
-    // The renderer only ever emits `**>` at column 0; a leading-indented
-    // variant is deliberately NOT treated as an expandable quote (matching it
-    // would push the length-preserving rewrite past the 3-space blockquote
-    // budget into indented-code-block territory).
+    // The legacy encoding only ever placed `**>` at column 0; a
+    // leading-indented variant is deliberately NOT treated as an expandable
+    // quote (matching it would push the length-preserving rewrite past the
+    // 3-space blockquote budget into indented-code-block territory).
     const md = "   **> indented";
     const doc = parse(md);
     const bq = doc.blocks[0] as any;
@@ -391,3 +391,28 @@ describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
     expect(doc.blocks[0].type).toBe("paragraph");
   });
 });
+
+describe("footnotes fold to verbatim `raw` nodes (native Telegram construct)", () => {
+  it("a footnote reference marker folds to a raw inline carrying its source bytes", () => {
+    // GFM only recognises a reference when a matching definition exists in
+    // the document (a lone `[^n1]` is ordinary text).
+    const doc = parse("claim[^n1] more\n\n[^n1]: body");
+    const para = doc.blocks[0] as Extract<Block, { type: "paragraph" }>;
+    const raw = para.children.find((c: Inline) => c.type === "raw") as
+      | Extract<Inline, { type: "raw" }>
+      | undefined;
+    expect(raw).toBeDefined();
+    expect(raw!.text).toBe("[^n1]");
+  });
+
+  it("a footnote definition folds to a paragraph with one raw inline (verbatim slice)", () => {
+    const doc = parse("[^n1]: body text");
+    const para = doc.blocks[0] as Extract<Block, { type: "paragraph" }>;
+    expect(para.type).toBe("paragraph");
+    expect(para.children).toHaveLength(1);
+    expect(para.children[0].type).toBe("raw");
+    expect((para.children[0] as Extract<Inline, { type: "raw" }>).text).toBe(
+      "[^n1]: body text",
+    );
+  });
+});