switchroom 0.18.11 → 0.18.13

package/telegram-plugin/tests/queued-card-store.test.ts

@@ -0,0 +1,232 @@
+/**
+ * queued-card-store.test.ts — outcome-based tests for the queued-status /
+ * busy-ack card restart-survivability fix (#3002).
+ *
+ * PRE-FIX PROOF: before this change, no persistence existed for the
+ * `queuedStatusMsgIds` Map at all — `../gateway/queued-card-store.js` did not
+ * exist, so `import` itself failed at collection time and every test below
+ * failed on today's (pre-fix) base — there was no seam to test.
+ *
+ * This file exercises the REAL exported store + boot-reaper functions (not a
+ * structural grep), mirroring `activity-card-store.test.ts`'s in-memory fs seam
+ * convention, proving the exact outcome contract:
+ *   (a) card post persists a record;
+ *   (b) in-process reap clears it;
+ *   (c) a boot reaper against a leftover record performs EXACTLY ONE Telegram
+ *       delete and empties the store;
+ *   (d) a second boot performs ZERO deletes;
+ *   (e) a corrupt state file never crashes boot and is dropped without a delete;
+ *   (f) a delete failure never crashes the reaper and still clears the row.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  loadQueuedCards,
+  persistQueuedCards,
+  writeQueuedCardRecord,
+  clearQueuedCardRecord,
+  runQueuedCardBootReaper,
+  type QueuedCardRecord,
+  type QueuedCardStoreFsSeam,
+} from '../gateway/queued-card-store.js'
+
+/** In-memory fs seam with an atomic rename — same convention as
+ *  activity-card-store.test.ts's memFs, so the tmp→rename crash-safety
+ *  contract is exercised without touching real disk. */
+function memFs(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed))
+  const calls: string[] = []
+  const fs: QueuedCardStoreFsSeam = {
+    readFileSync: (p) => {
+      if (!files.has(p)) throw new Error(`ENOENT ${p}`)
+      return files.get(p)!
+    },
+    writeFileSync: (p, d) => {
+      calls.push(`write:${p}`)
+      files.set(p, d)
+    },
+    renameSync: (a, b) => {
+      calls.push(`rename:${a}->${b}`)
+      if (!files.has(a)) throw new Error(`ENOENT ${a}`)
+      files.set(b, files.get(a)!)
+      files.delete(a)
+    },
+    existsSync: (p) => files.has(p),
+  }
+  return { fs, files, calls }
+}
+
+const PATH = '/state/agent/telegram/queued-cards-pending.json'
+
+function card(over: Partial<QueuedCardRecord> = {}): QueuedCardRecord {
+  return {
+    key: '-100123:42',
+    chatId: '-100123',
+    threadId: 42,
+    messageId: 715,
+    ...over,
+  }
+}
+
+describe('queued-card-store — persistence primitives', () => {
+  it('loads [] when no file exists (fresh boot)', () => {
+    const { fs } = memFs()
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('(a) card post → state persisted (round-trips a written record)', () => {
+    const { fs } = memFs()
+    const record = card()
+    writeQueuedCardRecord(PATH, fs, record)
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]).toEqual(record)
+  })
+
+  it('round-trips a DM card (threadId null)', () => {
+    const { fs } = memFs()
+    const record = card({ key: '-100123:', threadId: null })
+    writeQueuedCardRecord(PATH, fs, record)
+    expect(loadQueuedCards(PATH, fs)[0]).toEqual(record)
+  })
+
+  it('a fresh post for the same topic replaces (upserts) the stale row, not appends', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 900 }))
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.messageId).toBe(900)
+  })
+
+  it('keeps rows for distinct keys (different topics) side by side', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:42', messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:43', messageId: 716 }))
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(2)
+  })
+
+  it('(b) in-process reap → state cleared', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card())
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(1)
+    clearQueuedCardRecord(PATH, fs, '-100123:42')
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('clearing an absent/mismatched key is a no-op (never throws)', () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:99' }))
+    clearQueuedCardRecord(PATH, fs, '-100123:42')
+    expect(loadQueuedCards(PATH, fs)).toHaveLength(1)
+  })
+
+  it('reap-race guard: clear scoped to messageId leaves a fresh live card intact', () => {
+    const { fs } = memFs()
+    // A live turn posted a NEW card (msg 900) under the same key while a stale
+    // reap tries to clear the OLD one (msg 715) — the new row must survive.
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 900 }))
+    clearQueuedCardRecord(PATH, fs, '-100123:42', 715)
+    const loaded = loadQueuedCards(PATH, fs)
+    expect(loaded).toHaveLength(1)
+    expect(loaded[0]!.messageId).toBe(900)
+  })
+
+  it('writes via tmp + atomic rename (crash-safe)', () => {
+    const { fs, calls } = memFs()
+    persistQueuedCards(PATH, fs, [card()])
+    expect(calls).toEqual([`write:${PATH}.tmp`, `rename:${PATH}.tmp->${PATH}`])
+  })
+
+  it('(e) corrupt state file: boot survives, loads as [] (fail-open, never throws)', () => {
+    const { fs } = memFs({ [PATH]: '{not json' })
+    expect(() => loadQueuedCards(PATH, fs)).not.toThrow()
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('fail-open: wrong envelope version / malformed shape loads as []', () => {
+    const { fs: f1 } = memFs({ [PATH]: JSON.stringify({ v: 2, cards: [card()] }) })
+    expect(loadQueuedCards(PATH, f1)).toEqual([])
+    const { fs: f2 } = memFs({ [PATH]: JSON.stringify({ v: 1, cards: 'nope' }) })
+    expect(loadQueuedCards(PATH, f2)).toEqual([])
+    const { fs: f3 } = memFs({ [PATH]: JSON.stringify({ v: 1, cards: [{ key: '' }] }) })
+    expect(loadQueuedCards(PATH, f3)).toEqual([])
+  })
+})
+
+describe('queued-card-store — boot reaper (reap-on-boot, delete is the terminal)', () => {
+  it('(c) deletes each persisted card EXACTLY ONCE and empties the store', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:42', messageId: 715 }))
+    writeQueuedCardRecord(PATH, fs, card({ key: '-100123:43', messageId: 716 }))
+    const deletes: number[] = []
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async (r) => {
+        deletes.push(r.messageId)
+        return { message_id: r.messageId }
+      },
+    })
+    expect(res).toEqual({ deleted: 2, total: 2 })
+    expect(deletes.sort()).toEqual([715, 716])
+    // Store is emptied — the stale cards can never be re-reaped.
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('(d) a SECOND boot performs ZERO deletes (store already drained)', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card())
+    await runQueuedCardBootReaper({ path: PATH, fs, deleteCard: async () => ({}) })
+    const deletes: number[] = []
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async (r) => {
+        deletes.push(r.messageId)
+        return {}
+      },
+    })
+    expect(res).toEqual({ deleted: 0, total: 0 })
+    expect(deletes).toEqual([])
+  })
+
+  it('deletes the record BEFORE the delete call (idempotency guard — no double-delete on crash)', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    let storeAtDeleteTime: QueuedCardRecord[] | null = null
+    await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async () => {
+        // At the moment the Telegram delete runs, the row is already gone from
+        // disk — a crash here or a concurrent second boot cannot re-issue it.
+        storeAtDeleteTime = loadQueuedCards(PATH, fs)
+        return {}
+      },
+    })
+    expect(storeAtDeleteTime).toEqual([])
+  })
+
+  it('(f) a delete FAILURE never crashes the reaper and still clears the row (best-effort, tolerate "not found")', async () => {
+    const { fs } = memFs()
+    writeQueuedCardRecord(PATH, fs, card({ messageId: 715 }))
+    const res = await runQueuedCardBootReaper({
+      path: PATH,
+      fs,
+      deleteCard: async () => {
+        throw new Error('Bad Request: message to delete not found')
+      },
+      log: () => {},
+    })
+    // Not counted as deleted, but the row is dropped (delete-first) so it can't
+    // wedge every future boot.
+    expect(res).toEqual({ deleted: 0, total: 1 })
+    expect(loadQueuedCards(PATH, fs)).toEqual([])
+  })
+
+  it('empty store: reaper is a no-op', async () => {
+    const { fs } = memFs()
+    const res = await runQueuedCardBootReaper({ path: PATH, fs, deleteCard: async () => ({}) })
+    expect(res).toEqual({ deleted: 0, total: 0 })
+  })
+})

package/telegram-plugin/tests/reaction-flush-turn-gated.test.ts

@@ -0,0 +1,100 @@
+/**
+ * #2094 finding 3 — reaction-flush uses the #1556 turn gate.
+ *
+ * THE BUG: flushReactionBatch delivered its synthetic reaction inbound with a
+ * bare `ipcServer.sendToAgent` + busy-mark, buffering ONLY on a bridge-offline
+ * miss. It never ran the #1556 decideInboundDelivery gate. So a reaction that
+ * landed WHILE a turn was in flight fired the MCP channel notification mid-turn
+ * — the unmodified CLI typed it into its TUI composer and the auto-submit raced
+ * turn-completion, re-creating the composer wedge.
+ *
+ * THE FIX: route the flush through deliverResumeSyntheticOrBuffer, the shared
+ * helper that consults the gate (mid-turn → buffer-until-idle, flushed by the
+ * turn-complete hook + idle-drain timer; idle → deliver now; buffer only on a
+ * genuine miss).
+ *
+ * gateway.ts is a large side-effecting module that can't be imported into a
+ * unit test, so this file pins (a) the gate decision for a reaction inbound's
+ * shape via the pure gate + a modeled buffer/drain, and (b) that
+ * flushReactionBatch wires the turn-safe helper structurally — the same
+ * strategy button-tap-turn-gated.test.ts uses.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decideInboundDelivery } from '../gateway/inbound-delivery-gate.js'
+import { planBufferedRedelivery } from '../gateway/pending-inbound-buffer.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+// A reaction inbound as flushReactionBatch builds it: synthetic messageId (ts),
+// never steering, never an interrupt — the exact inputs the shared helper
+// (deliverResumeSyntheticOrBuffer) passes to the gate.
+function reactionInbound(ts: number): InboundMessage {
+  return {
+    type: 'inbound',
+    chatId: 'c1',
+    messageId: ts,
+    user: 'u',
+    userId: 42,
+    ts,
+    text: `[user reacted 👍 to your message]`,
+    meta: { chat_id: 'c1', count: '1' },
+  }
+}
+
+describe('reaction flush uses the turn-gate (mid-turn → buffer)', () => {
+  it('buffers a reaction that lands mid-turn, delivers when idle, never mid-turn', () => {
+    const shape = { isSteering: false as const, isInterrupt: false as const }
+    // Reaction lands WHILE a turn is in flight → HELD, not sent (the wedge the
+    // raw sendToAgent used to cause).
+    expect(decideInboundDelivery({ ...shape, turnInFlight: true })).toBe(
+      'buffer-until-idle',
+    )
+    // Reaction lands at an idle prompt → delivered immediately.
+    expect(decideInboundDelivery({ ...shape, turnInFlight: false })).toBe(
+      'deliver',
+    )
+  })
+
+  it('a mid-turn-buffered reaction drains as a fresh turn after turn end', () => {
+    // Model the buffer→drain: the reaction was held mid-turn; on turn-complete
+    // the buffer is planned for redelivery and the reaction lands cleanly as
+    // its own turn (never merged away / dropped).
+    const plan = planBufferedRedelivery([reactionInbound(1000)])
+    expect(plan).toHaveLength(1)
+    expect(plan[0]!.merged.text).toBe('[user reacted 👍 to your message]')
+  })
+})
+
+describe('flushReactionBatch wires the turn-safe helper', () => {
+  const start = gatewaySrc.indexOf('function flushReactionBatch(batch: ReactionBatch)')
+  // Bound the body by the next top-level declaration (the message_reaction
+  // handler block).
+  const body = gatewaySrc.slice(
+    start,
+    gatewaySrc.indexOf("bot.on('message_reaction'", start),
+  )
+
+  it('exists', () => {
+    expect(start, 'flushReactionBatch missing').toBeGreaterThan(0)
+  })
+
+  it('delivers via deliverResumeSyntheticOrBuffer, not a raw ungated sendToAgent', () => {
+    expect(body).toMatch(/deliverResumeSyntheticOrBuffer\(agentName, inbound\)/)
+    // The regressed path — a raw ungated send of the reaction inbound + an
+    // out-of-helper busy-mark — is gone.
+    expect(body).not.toMatch(/ipcServer\.sendToAgent\(agentName, inbound\)/)
+    expect(body).not.toMatch(/markClaudeBusyForInbound\(inbound\)/)
+  })
+
+  it('no longer open-codes the buffer-on-failure push (the helper owns it)', () => {
+    // The #1150 buffer-on-failure guarantee now lives inside
+    // deliverResumeSyntheticOrBuffer, so the flush body must not push directly.
+    expect(body).not.toMatch(/pendingInboundBuffer\.push\(/)
+  })
+})

package/telegram-plugin/tests/reaction-gate-routing.test.ts

@@ -0,0 +1,173 @@
+/**
+ * #3155 — `setMessageReaction` must route through the send gate + flood breaker.
+ *
+ * Before this change ~13 raw `bot.api.setMessageReaction(...)` /
+ * `lockedBot.api.setMessageReaction(...)` call sites (early-ack 👀, status
+ * reactions, stop/interrupt ⚡, permission verdict ✅/❌, refusal 🚫, ack-only,
+ * the MCP `react` tool, the crash-recovery sweeps, the auth-code 🔑 redact)
+ * fired reactions OUTSIDE both:
+ *
+ *   (a) the send gate — so reaction churn was never paced/shed under flood
+ *       pressure even with the gate ON; and
+ *   (b) the flood circuit breaker — a 429 from a reaction never reached the
+ *       retry module's `onFloodWait` hook, so the ban went unrecorded.
+ *
+ * Reactions were therefore a residual flood vector even when the gate is on.
+ * The gateway now funnels every reaction through ONE seam,
+ * `robustApiCall(() => lockedBot.api.setMessageReaction(...), { priorityClass:
+ * 'cosmetic', verb: 'set-message-reaction' })`.
+ *
+ * Two levels of coverage:
+ *   1. BEHAVIOURAL — compose the real `send-gate` + `retry-api-call` modules the
+ *      same way `gateway.ts` wires `robustApiCall`, and prove a cosmetic
+ *      reaction is (a) shed when a flood window is open and (b) visible to
+ *      `onFloodWait` on a 429.
+ *   2. LOAD-BEARING SOURCE SCAN — assert the gateway has exactly ONE runtime
+ *      `setMessageReaction` call and that it is the cosmetic seam. This FAILS if
+ *      any future change re-introduces a raw (ungated, breaker-blind) reaction.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { createSendGate, type Clock } from '../send-gate.js'
+import { createRetryApiCall } from '../retry-api-call.js'
+import { errors } from './fake-bot-api.js'
+
+const GATEWAY_SRC = fileURLToPath(new URL('../gateway/gateway.ts', import.meta.url))
+
+/** Fixed-time clock; `sleep` is a no-op so nothing actually waits under test. */
+function fixedClock(now: number): Clock {
+  return { now: () => now, sleep: () => Promise.resolve() }
+}
+
+/**
+ * Reconstruct the gateway's outbound wiring for reactions: `robustApiCall =
+ * gate(rawRetry)`, and a `sendReaction` closure that tags the call `cosmetic`
+ * exactly like `gatedSetMessageReaction` in gateway.ts.
+ */
+function wireReactionPath(opts: {
+  clock: Clock
+  enabled: boolean
+  windowUntilTs?: number
+  onFloodWait?: (retryAfterSec: number) => void
+}) {
+  const setMessageReaction = vi.fn(async () => true as const)
+  const sendGate = createSendGate({
+    enabled: opts.enabled,
+    clock: opts.clock,
+    ...(opts.windowUntilTs != null
+      ? { initialWindows: [{ scopeKey: 'global', untilTs: opts.windowUntilTs }] }
+      : {}),
+  })
+  const rawRetry = createRetryApiCall({
+    maxRetries: 2,
+    sleep: async () => {},
+    ...(opts.onFloodWait ? { onFloodWait: opts.onFloodWait } : {}),
+  })
+  const robustApiCall = <T>(
+    fn: () => Promise<T>,
+    o?: Parameters<typeof rawRetry<T>>[1],
+  ): Promise<T> => sendGate.gate(() => rawRetry(fn, o), o)
+
+  // Mirrors gateway.ts `gatedSetMessageReaction` / `sendReaction`.
+  const sendReaction = (chatId: string, messageId: number, emoji: string): Promise<unknown> =>
+    robustApiCall(() => setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji }]), {
+      chat_id: chatId,
+      verb: 'set-message-reaction',
+      priorityClass: 'cosmetic',
+    })
+
+  return { sendReaction, setMessageReaction, sendGate }
+}
+
+describe('#3155 reactions route through the send gate (cosmetic)', () => {
+  it('SHEDS a reaction while a flood window is open (paced/shed by the gate)', async () => {
+    const now = 1_000_000
+    const { sendReaction, setMessageReaction, sendGate } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: true,
+      windowUntilTs: now + 60_000, // an open global ban window
+    })
+
+    const result = await sendReaction('chatA', 42, '👀')
+
+    // Cosmetic + a covering window ⇒ shed: the API is NEVER hit, the promise
+    // resolves undefined (fire-and-forget callers .catch nothing), and the gate
+    // counts the shed.
+    expect(setMessageReaction).not.toHaveBeenCalled()
+    expect(result).toBeUndefined()
+    expect(sendGate.stats().global.shed).toBe(1)
+  })
+
+  it('does NOT shed when the gate is OFF (proves the gate is what sheds)', async () => {
+    const now = 1_000_000
+    const { sendReaction, setMessageReaction } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: false, // gate disabled ⇒ pure passthrough
+      windowUntilTs: now + 60_000,
+    })
+
+    await sendReaction('chatA', 42, '👀')
+
+    // Flag OFF ⇒ the reaction still fires (the window only bites when enabled).
+    expect(setMessageReaction).toHaveBeenCalledTimes(1)
+  })
+
+  it('records a 429 on a reaction to the flood breaker via onFloodWait', async () => {
+    const now = 1_000_000
+    const onFloodWait = vi.fn()
+    const { sendReaction, setMessageReaction } = wireReactionPath({
+      clock: fixedClock(now),
+      enabled: true, // gate on, no open window ⇒ the cosmetic call is admitted
+      onFloodWait,
+    })
+    // The reaction send hits a Telegram 429 flood-wait.
+    setMessageReaction.mockRejectedValue(errors.floodWait(7, 'setMessageReaction'))
+
+    // Fire-and-forget semantics: callers swallow. The point is the SIDE EFFECT.
+    await sendReaction('chatA', 42, '🤝').catch(() => {})
+
+    // The reaction actually reached the API (was admitted, not shed)...
+    expect(setMessageReaction).toHaveBeenCalled()
+    // ...and its 429 was recorded by the breaker — the whole gap this closes.
+    expect(onFloodWait).toHaveBeenCalledWith(7)
+  })
+})
+
+describe('#3155 load-bearing: gateway.ts sends no reaction raw', () => {
+  const src = readFileSync(GATEWAY_SRC, 'utf-8')
+  const lines = src.split('\n')
+
+  /** Non-comment source lines that call `(bot|lockedBot).api.setMessageReaction`. */
+  const rawReactionLines = lines
+    .map((text, i) => ({ text, n: i + 1 }))
+    .filter(({ text }) => {
+      const t = text.trim()
+      if (t.startsWith('*') || t.startsWith('//') || t.startsWith('/*')) return false
+      return /\b(bot|lockedBot)\.api\.setMessageReaction\b/.test(text)
+    })
+
+  it('has EXACTLY ONE runtime setMessageReaction callsite (the shared seam)', () => {
+    // If this fails with >1, a raw reaction was re-introduced somewhere —
+    // ungated and invisible to the flood breaker. Route it through
+    // `sendReaction` / `gatedSetMessageReaction` instead.
+    expect(rawReactionLines).toHaveLength(1)
+  })
+
+  it('the sole seam is tagged cosmetic and routed through robustApiCall', () => {
+    const seamLine = rawReactionLines[0]!.n
+    // Look at the seam line + a small window for its opts object.
+    const window = lines.slice(seamLine - 2, seamLine + 6).join('\n')
+    expect(window).toContain('robustApiCall(')
+    expect(window).toContain("priorityClass: 'cosmetic'")
+    expect(window).toContain("verb: 'set-message-reaction'")
+  })
+
+  it('no reaction is fired as a raw fire-and-forget bot.api call', () => {
+    // Belt-and-braces: the old `bot.api.setMessageReaction(...).catch(() => {})`
+    // shape must be gone entirely.
+    expect(src).not.toMatch(/bot\.api\.setMessageReaction\([^)]*\)\s*\.catch/)
+    // And the fire-and-forget callers now go through the helper.
+    expect(src).toContain('void sendReaction(')
+  })
+})

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

@@ -48,6 +48,65 @@ describe("render: inline palette", () => {
       "[label](https://example.com)",
     );
   });
+  it("escapes a `)` in a link href so the URL is not truncated (F3)", () => {
+    // An angle-bracket destination is the only way to smuggle an UNBALANCED
+    // `)` into an href via the parser (a bare `)` would otherwise close the
+    // destination). CommonMark strips the angle brackets → href holds the `)`.
+    const doc = parse("[wiki](<https://example.com/a)b>)");
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a)b"); // parser captured the full URL
+
+    const out = render(doc);
+    // The `)` is backslash-escaped so it can no longer terminate the `(...)`
+    // destination early — a valid Bot API 10.1 link, not a broken one.
+    expect(out).toContain("a\\)b");
+    // And it round-trips: re-parsing recovers the SAME href, not a truncated
+    // `https://example.com/a` with stray `b)` prose spilled after it.
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a)b");
+  });
+  it("round-trips a balanced-paren href (Wikipedia disambiguation) without leaking a backslash", () => {
+    // A bare destination with BALANCED parens is legal CommonMark; the parser
+    // captures the whole URL including the inner `(...)`. Escaping only `)`
+    // (the old fix) would unbalance the parens and leak a literal backslash
+    // into the decoded href. Escaping both parens keeps it balanced.
+    const src = "[w](https://en.wikipedia.org/wiki/Foo_(disambiguation))";
+    const doc = parse(src);
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://en.wikipedia.org/wiki/Foo_(disambiguation)");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    // Re-parsed href is byte-for-byte the original — no truncation, no stray `\`.
+    expect(reLink.href).toBe("https://en.wikipedia.org/wiki/Foo_(disambiguation)");
+    expect(reLink.href).not.toContain("\\");
+  });
+  it("round-trips an href with multiple balanced paren groups", () => {
+    const src = "[m](https://example.com/a(b)c(d))";
+    const doc = parse(src);
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a(b)c(d)");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a(b)c(d)");
+    expect(reLink.href).not.toContain("\\");
+  });
+  it("round-trips an href with a lone unbalanced `)` without leaking a backslash", () => {
+    // Angle-bracket destination smuggles a lone `)` past the parser.
+    const doc = parse("[x](<https://example.com/a)b>)");
+    const link = (doc.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(link.href).toBe("https://example.com/a)b");
+
+    const out = render(doc);
+    const reparsed = parse(out);
+    const reLink = (reparsed.blocks[0] as any).children.find((c: any) => c.type === "link");
+    expect(reLink.href).toBe("https://example.com/a)b");
+    expect(reLink.href).not.toContain("\\");
+  });
   it("underline", () => {
     expect(render(parse("__hi__"))).toBe("__hi__");
   });
@@ -226,6 +285,35 @@ describe("render: block palette", () => {
     const out = render(parse(md));
     expect(out).toContain("**bold** cell");
   });
+  it("neutralizes a `|` inside a code span in a table cell so the row survives (F4)", () => {
+    // Source pipe inside the code span is `\|`-escaped so the INPUT is a valid
+    // GFM table; the parser folds it to a code node whose text is `a|b`.
+    const md = ["| Col |", "| --- |", "| `a\\|b` |"].join("\n");
+    const doc = parse(md);
+    const srcCell = (doc.blocks[0] as TableNode).rows[0].cells[0].children.find(
+      (c: any) => c.type === "code",
+    ) as any;
+    expect(srcCell.text).toBe("a|b"); // parser captured the literal pipe
+
+    const out = render(doc);
+    // The `|` is re-escaped inside the code span so it can't be read as a
+    // column separator and tear the row — valid Bot API 10.1 GFM output.
+    expect(out).toContain("`a\\|b`");
+    // Every rendered table line stays a structurally-valid row (`|`-delimited,
+    // balanced) — a torn row would start with `|` but not end with one.
+    for (const line of out.split("\n")) {
+      if (line.trimStart().startsWith("|")) {
+        expect(line.trimEnd().endsWith("|")).toBe(true);
+      }
+    }
+    // And it round-trips: the re-parsed table still has ONE body cell whose
+    // code text is `a|b`, not a torn row with an unterminated code span.
+    const reparsed = parse(out);
+    const reRow = (reparsed.blocks[0] as TableNode).rows[0];
+    expect(reRow.cells).toHaveLength(1);
+    const reCell = reRow.cells[0].children.find((c: any) => c.type === "code") as any;
+    expect(reCell.text).toBe("a|b");
+  });
 });
 
 describe("render: full document", () => {