switchroom 0.18.11 → 0.18.13

package/telegram-plugin/inline-keyboard-callbacks.ts

@@ -30,6 +30,7 @@
 
 import {
   validateInlineKeyboard,
+  TELEGRAM_BUTTON_LIMITS,
   type AnyButton,
   type ButtonValidationError,
 } from './telegram-button-constraints.js'
@@ -60,10 +61,25 @@ export interface AgentButtonMeta {
    * removes the entire keyboard to prevent double-fire.
    */
   single_use?: boolean
+  /**
+   * Per-message override for the button-choice-confirmation annotation
+   * (#789). When true, tapping annotates the source message body with a
+   * "✅ You chose: <label> · HH:MM" line even if the agent default is off;
+   * when false, annotation is skipped even if the agent default is on.
+   * Undefined falls back to the agent's
+   * channels.telegram.button_choice_confirmation.enabled default. Only takes
+   * effect on single-use keyboards (re-tappable keyboards are never
+   * annotated).
+   */
+  inline_keyboard_confirm?: boolean
 }
 
 /** Fields the gateway adds to button objects — not valid Telegram API fields. */
-const AGENT_META_FIELDS: ReadonlyArray<keyof AgentButtonMeta> = ['ack_text', 'single_use']
+const AGENT_META_FIELDS: ReadonlyArray<keyof AgentButtonMeta> = [
+  'ack_text',
+  'single_use',
+  'inline_keyboard_confirm',
+]
 
 /**
  * Wrap every callback_data field in a 2D inline-keyboard with the
@@ -99,6 +115,99 @@ export function wrapAgentCallbacks(keyboard: AnyButton[][]): AnyButton[][] {
   )
 }
 
+/**
+ * Redact agent-authored free-text on an inline keyboard BEFORE it is sent to
+ * Telegram (#3148 fast-follow secret-scrub coverage). `wrapAgentCallbacks`
+ * rewrites only `callback_data`; the visible `text` label, the `ack_text`
+ * toast, and any `copy_text.text` clipboard payload pass through VERBATIM. An
+ * agent that puts a secret in any of those transmits it unmasked, and it
+ * resurfaces on tap — the label is echoed back (`button_text`), re-rendered in
+ * the "✅ You chose: <label>" annotation (#789), and `ack_text` is shown as the
+ * toast. `switch_inline_query` / `switch_inline_query_current_chat` /
+ * `switch_inline_query_chosen_chat.query` are also agent-authored free text
+ * that Telegram pastes into a chat's input box on tap (the current chat for
+ * the `_current_chat` variant, a user-picked chat for `_chosen_chat` — both
+ * user-visible), so they carry the same leak class. Route every one of these free-text fields
+ * through the SAME outbound redactor the reply `text` body uses, at the
+ * outbound boundary, so every downstream resurface reads already-masked bytes.
+ *
+ * `callback_data` is the routing key and is NEVER touched — redacting it would
+ * break tap round-tripping. Button structure/order is preserved; the redactor
+ * (`redact()`) only replaces detected secret byte-ranges with a non-empty
+ * marker, so it never empties a label (the non-empty-text invariant holds).
+ * Returns a fresh keyboard; does not mutate the input. `redactFn` is injected
+ * so this stays pure + unit-testable and carries no gateway import cycle.
+ *
+ * Only agent-authored keyboards flow through here (the `reply` tool path);
+ * framework-internal keyboards (approval cards, vault wizard, model menus) are
+ * built separately and are NOT redacted by this function.
+ */
+export function redactAgentKeyboard(
+  keyboard: AnyButton[][],
+  redactFn: (s: string) => string,
+): AnyButton[][] {
+  // The keyboard is validated for length BEFORE redaction, but the redaction
+  // marker (`[REDACTED:...]`) can be longer than the secret it replaces, so a
+  // field that was within a Telegram cap can exceed it after masking. An
+  // over-limit button field makes sendMessage 400 → the WHOLE reply is dropped
+  // (worse than the leak we just closed), so clamp each masked free-text field
+  // to its cap. Truncating a marker is harmless — it's already non-secret.
+  const clamp = (s: string, max: number): string =>
+    s.length > max ? s.slice(0, max) : s
+  return keyboard.map((row) =>
+    row.map((btn) => {
+      const out: AnyButton = { ...btn }
+      if (typeof out.text === 'string') {
+        out.text = clamp(redactFn(out.text), TELEGRAM_BUTTON_LIMITS.TEXT_MAX)
+      }
+      // ack_text is a switchroom-side toast (answerCallbackQuery), not a
+      // sendMessage field, so an over-length value can't drop the reply — no
+      // clamp needed, but redact it all the same.
+      if (typeof out.ack_text === 'string') out.ack_text = redactFn(out.ack_text)
+      // switch_inline_query* paste agent free text into a chat input box on tap
+      // — same leak class as the label. URL-class fields (url/web_app/login_url)
+      // are deliberately left exact: a [REDACTED] marker would corrupt a URL.
+      const siq = (out as { switch_inline_query?: unknown }).switch_inline_query
+      if (typeof siq === 'string') {
+        (out as { switch_inline_query?: string }).switch_inline_query = clamp(
+          redactFn(siq), TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX)
+      }
+      const siqc = (out as { switch_inline_query_current_chat?: unknown })
+        .switch_inline_query_current_chat
+      if (typeof siqc === 'string') {
+        (out as { switch_inline_query_current_chat?: string })
+          .switch_inline_query_current_chat = clamp(
+            redactFn(siqc), TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX)
+      }
+      // switch_inline_query_chosen_chat.query is the third variant: agent free
+      // text pasted into a user-picked chat's input box on tap — same leak class.
+      const cc = (out as { switch_inline_query_chosen_chat?: unknown })
+        .switch_inline_query_chosen_chat
+      if (cc != null && typeof cc === 'object' &&
+          typeof (cc as { query?: unknown }).query === 'string') {
+        (out as { switch_inline_query_chosen_chat?: Record<string, unknown> })
+          .switch_inline_query_chosen_chat = {
+            ...(cc as Record<string, unknown>),
+            query: clamp(
+              redactFn((cc as { query: string }).query),
+              TELEGRAM_BUTTON_LIMITS.SWITCH_INLINE_QUERY_MAX),
+          }
+      }
+      const ct = out.copy_text
+      if (ct != null && typeof ct === 'object' &&
+          typeof (ct as { text?: unknown }).text === 'string') {
+        out.copy_text = {
+          ...(ct as Record<string, unknown>),
+          text: clamp(
+            redactFn((ct as { text: string }).text),
+            TELEGRAM_BUTTON_LIMITS.COPY_TEXT_MAX),
+        }
+      }
+      return out
+    }),
+  )
+}
+
 /**
  * Extract per-button {@link AgentButtonMeta} from a raw (pre-wrap)
  * keyboard. Returns a map keyed by the raw (unprefixed) callback_data
@@ -116,7 +225,14 @@ export function extractAgentButtonMeta(
       const meta: AgentButtonMeta = {}
       if (typeof btn.ack_text === 'string') meta.ack_text = btn.ack_text
       if (typeof btn.single_use === 'boolean') meta.single_use = btn.single_use
-      if (meta.ack_text != null || meta.single_use != null) {
+      if (typeof btn.inline_keyboard_confirm === 'boolean') {
+        meta.inline_keyboard_confirm = btn.inline_keyboard_confirm
+      }
+      if (
+        meta.ack_text != null ||
+        meta.single_use != null ||
+        meta.inline_keyboard_confirm != null
+      ) {
         out.set(btn.callback_data, meta)
       }
     }
@@ -149,6 +265,191 @@ export function parseAgentCallback(data: string): { raw: string } | null {
   return { raw: data.slice(AGENT_CALLBACK_PREFIX.length) }
 }
 
+// ─── #789 button-choice-confirmation ("✅ You chose: X") ──────────────────
+//
+// When a user taps an agent-emitted single-use inline_keyboard button, the
+// gateway can annotate the source message body with a
+// "✅ You chose: <label> · HH:MM" line so the chat surface is
+// self-documenting (mirrors the ask_user finalize UX). The DECISION and the
+// rendered text are pure functions here so they can be unit-tested against
+// the exact payload the gateway ships — the gateway owns only the Telegram
+// I/O and the once-per-process warning dedupe.
+
+/** Per-agent button-choice-confirmation config (projected into access.json). */
+export interface ButtonChoiceConfirmationConfig {
+  enabled?: boolean
+  format?: string
+  timezone?: 'gateway' | 'utc'
+}
+
+/** Default annotation template. `{label}` and `{time}` are substituted. */
+export const BUTTON_CONFIRM_DEFAULT_FORMAT = '✅ You chose: {label} · {time}'
+
+/**
+ * HTML-entity escaper for the annotation payload (shipped with
+ * parse_mode: 'HTML'). Escapes exactly the three characters Telegram's HTML
+ * parser treats specially — `&`, `<`, `>` — so arbitrary button labels and
+ * source-message text can never 400 the editMessageText call. `&` is escaped
+ * first so freshly produced entities aren't double-escaped. This is NOT the
+ * GFM-markdown escaper (#2669) — that one escapes backticks/underscores and
+ * would garble text (`Do_it` → `Do\_it`) under HTML parse mode.
+ */
+export function escapeHtmlEntities(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/**
+ * Dedup-strip regex: matches a prior DEFAULT-shape annotation appended to the
+ * body so a retap replaces rather than duplicates it. The `<b>`/`</b>` tags
+ * are optional because Telegram returns `message.text` as PLAIN text (entity
+ * markup lives in `message.entities`, not in the text) — on a real retap the
+ * prior annotation arrives without tags. The `s` (dotAll) flag tolerates a
+ * stray newline inside an older, un-stripped label (belt-and-braces alongside
+ * the newline-stripping applied to the label on the way in). NOTE: dedup only
+ * recognizes the DEFAULT annotation shape — a custom
+ * button_choice_confirmation.format that diverges from it accumulates one
+ * line per retap instead of replacing.
+ */
+export const BUTTON_CONFIRM_STRIP_RE =
+  /\n\n✅ You chose: (?:<b>)?.*(?:<\/b>)? · \d{2}:\d{2}$/s
+
+/**
+ * Build the confirmation line. `{label}` → the tapped button's text with
+ * newlines collapsed to spaces, trimmed to 60 chars (mirrors the toast trim),
+ * HTML-entity-escaped (`&`, `<`, `>`) and wrapped in `<b>`; `{time}` →
+ * HH:MM in the chosen timezone. `now`/`escapeLabel` are injectable for
+ * deterministic tests; `escapeLabel` defaults to the real
+ * {@link escapeHtmlEntities}. Substitutions use replacer FUNCTIONS so
+ * String.replace special patterns (`$&`, `$'`, …) in labels are inert.
+ */
+export function buildButtonConfirmation(args: {
+  template: string
+  label: string
+  timezone: 'gateway' | 'utc'
+  escapeLabel?: (s: string) => string
+  now?: Date
+}): string {
+  const escape = args.escapeLabel ?? escapeHtmlEntities
+  const cleanLabel = args.label.replace(/\n/g, ' ').slice(0, 60)
+  const now = args.now ?? new Date()
+  const hh = args.timezone === 'utc'
+    ? String(now.getUTCHours()).padStart(2, '0')
+    : String(now.getHours()).padStart(2, '0')
+  const mm = args.timezone === 'utc'
+    ? String(now.getUTCMinutes()).padStart(2, '0')
+    : String(now.getMinutes()).padStart(2, '0')
+  return args.template
+    .replace('{label}', () => `<b>${escape(cleanLabel)}</b>`)
+    .replace('{time}', () => `${hh}:${mm}`)
+}
+
+/** Outcome of the annotate-or-strip decision for a single tap. */
+export interface TapAnnotationResult {
+  /** True → gateway should editMessageText with `text` (and strip keyboard). */
+  annotate: boolean
+  /** Annotated body text, present iff `annotate` is true. */
+  text?: string
+  /** True → gateway should emit the once-per-process parseMode warning. */
+  warnParseMode: boolean
+  /** True → gateway should emit the once-per-process single_use-mismatch warning. */
+  warnSingleUseMismatch: boolean
+}
+
+/**
+ * Pure decision for the #789 annotation. Resolves the per-message override
+ * (the tapped button's `inline_keyboard_confirm`) over the agent default,
+ * gates on single-use + presence of body text + a resolvable label + the
+ * `html` parse mode, and renders the annotated body (with any prior
+ * default-shape annotation stripped so a retap replaces it). Returns
+ * `annotate:false` for every skip path; the caller still performs the
+ * historical keyboard-only strip when the keyboard is single-use.
+ *
+ * The base body is HTML-entity-escaped too (Telegram hands us `message.text`
+ * as plain text, so `&`/`<`/`>` in it would otherwise 400 the HTML edit).
+ * Known limitation: because the body is rebuilt from `message.text`, any
+ * entities/formatting (bold, links, …) on the original message are lost on
+ * annotation. Documented in the config schema + CHANGELOG.
+ */
+export function resolveTapAnnotation(args: {
+  perMessageOverride?: boolean
+  singleUse: boolean
+  config?: ButtonChoiceConfirmationConfig
+  parseMode: 'html' | 'markdownv2' | 'text'
+  sourceText?: string
+  label?: string
+  escapeLabel?: (s: string) => string
+  now?: Date
+}): TapAnnotationResult {
+  const shouldAnnotate = args.perMessageOverride ?? args.config?.enabled ?? false
+  const warnSingleUseMismatch = shouldAnnotate && !args.singleUse
+
+  const wantAnnotate =
+    shouldAnnotate &&
+    args.singleUse &&
+    args.sourceText != null &&
+    args.label != null
+  if (!wantAnnotate) {
+    return { annotate: false, warnParseMode: false, warnSingleUseMismatch }
+  }
+  if (args.parseMode !== 'html') {
+    return { annotate: false, warnParseMode: true, warnSingleUseMismatch }
+  }
+  const escape = args.escapeLabel ?? escapeHtmlEntities
+  // Strip a prior annotation from the RAW text first (Telegram delivers it
+  // un-tagged), then entity-escape the remainder for the HTML edit.
+  const base = escape(
+    (args.sourceText as string).replace(BUTTON_CONFIRM_STRIP_RE, ''),
+  )
+  const formatted = buildButtonConfirmation({
+    template: args.config?.format ?? BUTTON_CONFIRM_DEFAULT_FORMAT,
+    label: args.label as string,
+    timezone: args.config?.timezone ?? 'gateway',
+    escapeLabel: escape,
+    ...(args.now != null ? { now: args.now } : {}),
+  })
+  return {
+    annotate: true,
+    text: `${base}\n\n${formatted}`,
+    warnParseMode: false,
+    warnSingleUseMismatch,
+  }
+}
+
+/**
+ * Perform the annotation edit against Telegram, with a keyboard-strip
+ * fallback: if the editMessageText 400s/rejects for ANY reason (over-long
+ * body, HTML edge case, message too old, …), we still strip the inline
+ * keyboard via editMessageReplyMarkup so single-use protection holds even
+ * though the button meta has already been consumed. Extracted here (with the
+ * two Telegram calls injected) so the fallback is unit-testable.
+ *
+ * Returns 'annotated' | 'stripped-fallback' | 'failed' for observability.
+ */
+export async function applyTapAnnotationEdit(io: {
+  editMessageText: (text: string, other: {
+    parse_mode: 'HTML'
+    reply_markup: { inline_keyboard: never[] }
+  }) => Promise<unknown>
+  editMessageReplyMarkup: (other: {
+    reply_markup: { inline_keyboard: never[] }
+  }) => Promise<unknown>
+}, text: string): Promise<'annotated' | 'stripped-fallback' | 'failed'> {
+  try {
+    await io.editMessageText(text, {
+      parse_mode: 'HTML',
+      reply_markup: { inline_keyboard: [] },
+    })
+    return 'annotated'
+  } catch {
+    try {
+      await io.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } })
+      return 'stripped-fallback'
+    } catch {
+      return 'failed'
+    }
+  }
+}
+
 /**
  * Convenience: validate + wrap in one call. Returns either the
  * wrapped keyboard or a structured error list — caller throws so the

package/telegram-plugin/model-unavailable.ts

@@ -41,6 +41,44 @@ export interface ModelUnavailableDetection {
   raw: string
 }
 
+// ─── Transient-burst signals (canonical, single source of truth) ─────────────
+
+/**
+ * Explicit markers of a TRANSIENT per-account burst / server-side throttle —
+ * a short-term RPM/burst 429 that Claude Code retries internally with backoff,
+ * NOT the 5h/7d subscription usage-limit wall. Anthropic emits these with a
+ * `rate_limit_error` whose wording explicitly NEGATES the account-quota reading
+ * ("not your usage limit" / "would exceed your account's rate limit … try again
+ * later"). Keyed on the explicit negation so a genuine wall that merely contains
+ * the word "limit" is never down-classified.
+ *
+ * Exported so `session-tail.ts` classifies a 429 by wording against THIS list
+ * rather than hand-rolling its own copy (keeps the two in sync — issue #2922).
+ */
+export const transientUpstreamSignals = [
+  'not your usage limit',
+  'not your account',
+  "not your account's",
+  'temporarily limiting requests',
+  'temporarily rate',
+  'server is temporarily',
+  'would exceed your account’s rate limit',
+  "would exceed your account's rate limit",
+]
+
+/**
+ * True when `text` carries an EXPLICIT transient-burst marker (see
+ * `transientUpstreamSignals`). Never throws on weird input. Used to keep the
+ * calm rate-limit path and the model-unavailable detector reading the same
+ * canonical signal list.
+ */
+export function isTransientUpstreamSignal(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+  return transientUpstreamSignals.some(s => lower.includes(s))
+}
+
 // ─── Detection ───────────────────────────────────────────────────────────────
 
 /**
@@ -77,17 +115,9 @@ export function detectModelUnavailable(
   // failover that self-cancels and leaves the turn dead. These are upstream
   // throttles Claude Code retries internally with backoff — classify them as
   // `overload` (the calm rate-limit path) BEFORE the quota substrings run, so
-  // the negation is honoured and no failover is announced.
-  const transientUpstreamSignals = [
-    'not your usage limit',
-    'not your account',
-    "not your account's",
-    'temporarily limiting requests',
-    'temporarily rate',
-    'server is temporarily',
-    'would exceed your account’s rate limit',
-    "would exceed your account's rate limit",
-  ]
+  // the negation is honoured and no failover is announced. The signal list is
+  // module-level (`transientUpstreamSignals`) so session-tail.ts classifies a
+  // 429 against the SAME canonical wording.
   if (transientUpstreamSignals.some(s => lower.includes(s))) {
     const resetAt = parseResetTime(sample)
     return resetAt !== undefined

package/telegram-plugin/operator-events.ts

@@ -28,6 +28,7 @@ export type OperatorEventKind =
   | 'unknown-5xx'
   | 'config-warning'
   | 'always-allow-persist-failed'
+  | 'mental-model-persist-failed'
 
 export interface OperatorEvent {
   kind: OperatorEventKind
@@ -420,6 +421,28 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
           ],
         },
       }
+
+    // #2975 Stage 1 — an operator-APPROVED mental-model persist hit the
+    // config_propose_edit rate limit, and the ONE scheduled retry at the
+    // window-open time ALSO failed. MUST be a NEW message (not a card edit):
+    // the proposal card was already edited to the "applying at HH:MM" state
+    // and card edits don't ping, so a silent edit here would leave the lost
+    // approval unnoticed. Ask the operator to re-propose so it isn't dropped.
+    case 'mental-model-persist-failed':
+      return {
+        text: [
+          `⚠️ **${agent}**'s approved mental model didn't save.`,
+          detail ? `_${detail}_` : '',
+          `The retry after the rate window also failed — ask the agent to re-propose it.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
   }
 }
 

package/telegram-plugin/outbound-field-redact.ts

@@ -0,0 +1,69 @@
+/**
+ * Structured-payload outbound redaction (#2044 coverage extension).
+ *
+ * The original #2044 outbound scrub masks agent-authored FREE TEXT on the
+ * reply / edit_message / progress_update paths (see gateway.ts
+ * `redactOutboundText`). But several other outbound surfaces carry
+ * agent-authored text to Telegram inside STRUCTURED payloads and had no
+ * redaction at all:
+ *
+ *   - ask_user      → the question text + every option/button label
+ *   - send_checklist / update_checklist → the title + every task's text
+ *
+ * An agent that echoes a token or a DATABASE_URL it just read into an
+ * ask_user question, a button label, or a checklist task would transmit it
+ * unmasked — defeating the same scrub invariant the reply `text` path
+ * honors.
+ *
+ * These helpers apply the SAME redactor to each such field. The redactor is
+ * INJECTED (the gateway passes its `redactOutboundText`; tests pass the real
+ * `redact`) so the masking is deterministic and unit-testable at the OUTCOME
+ * level: the object returned here is exactly what the downstream send call
+ * receives, so a test can assert the secret is gone from the sent payload —
+ * not merely that a redactor was invoked.
+ */
+
+/** A pure text redactor: maps input text to a masked copy. */
+export type FieldRedactor = (text: string) => string
+
+/**
+ * Redact the two agent-authored outbound fields of an ask_user prompt: the
+ * question and each option label. Returns fresh values (the input arrays are
+ * not mutated) so the caller can assign them onto the validated args.
+ */
+export function redactAskUserFields(
+  question: string,
+  options: readonly string[],
+  redact: FieldRedactor,
+): { question: string; options: string[] } {
+  return {
+    question: redact(question),
+    options: options.map((opt) => redact(opt)),
+  }
+}
+
+/** Minimal shape of a checklist task — only `text` is redacted; every other
+ *  field (id, done, …) is carried through untouched. */
+export interface ChecklistTaskLike {
+  text?: string
+  [key: string]: unknown
+}
+
+/**
+ * Redact the agent-authored outbound fields of a checklist: the title and
+ * each task's `text`. `title`/`tasks` may be undefined (update_checklist
+ * allows partial patches); undefined passes through untouched. A task whose
+ * `text` is undefined (an id-only patch) is left as-is.
+ */
+export function redactChecklistFields<T extends ChecklistTaskLike>(
+  title: string | undefined,
+  tasks: readonly T[] | undefined,
+  redact: FieldRedactor,
+): { title: string | undefined; tasks: T[] | undefined } {
+  return {
+    title: title != null ? redact(title) : title,
+    tasks: tasks?.map((task) =>
+      task.text != null ? { ...task, text: redact(task.text) } : task,
+    ),
+  }
+}

package/telegram-plugin/package.json

@@ -30,7 +30,6 @@
     "@mtcute/node": "^0.30.1",
     "@secretlint/core": "^12.2.0",
     "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
-    "@secretlint/types": "^12.2.0",
     "@xterm/headless": "^6.0.0",
     "grammy": "^1.44",
     "mdast-util-from-markdown": "^2.0.2",

package/telegram-plugin/permission-rule.ts

@@ -62,6 +62,7 @@ const BROAD_ONLY_TOOLS = new Set([
   "WebSearch",
   "Task",
   "Agent",
+  "Workflow",
   "TodoWrite",
   "ExitPlanMode",
 ]);

package/telegram-plugin/permission-title.ts

@@ -212,6 +212,7 @@ export function naturalAction(
     }
     case "Task":
     case "Agent":
+    case "Workflow":
       return "dispatch a sub-agent";
     case "TodoWrite":
       return "update its task list";

package/telegram-plugin/render/render.ts

@@ -30,7 +30,7 @@
 // equivalent entities rather than accidentally re-triggering formatting or
 // breaking out of a code span.
 
-import { escapeMarkdown, codeSpanSafe, RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import { escapeMarkdown, codeSpanSafe, escapeLinkHref, RICH_MESSAGE_MAX_CHARS } from "../format.js";
 import type {
   Block,
   BlockquoteNode,
@@ -47,26 +47,44 @@ import type {
 // Inline rendering
 // ---------------------------------------------------------------------------
 
-function renderInline(node: Inline): string {
+/** Rendering context threaded through the inline walk. `inTableCell` is set
+ *  while rendering the inline content of a GFM table cell, where a literal `|`
+ *  — even inside an inline-code span — would be read as a column separator and
+ *  tear the row (F4). Plain-text `|` is already neutralised by `escapeMarkdown`
+ *  (`|` is one of its specials); the only gap is the code span, whose content
+ *  is otherwise verbatim, so we backslash-escape `|` there in the table
+ *  context. GFM strips the `\` and keeps the pipe literal inside the span. */
+interface InlineCtx {
+  inTableCell?: boolean;
+}
+
+function renderInline(node: Inline, ctx: InlineCtx = {}): string {
   switch (node.type) {
     case "plain":
       return escapeMarkdown(node.text);
     case "bold":
-      return `**${renderInlineChildren(node.children)}**`;
+      return `**${renderInlineChildren(node.children, ctx)}**`;
     case "italic":
-      return `*${renderInlineChildren(node.children)}*`;
+      return `*${renderInlineChildren(node.children, ctx)}*`;
     case "underline":
-      return `__${renderInlineChildren(node.children)}__`;
+      return `__${renderInlineChildren(node.children, ctx)}__`;
     case "strike":
-      return `~~${renderInlineChildren(node.children)}~~`;
+      return `~~${renderInlineChildren(node.children, ctx)}~~`;
     case "spoiler":
-      return `||${renderInlineChildren(node.children)}||`;
+      return `||${renderInlineChildren(node.children, ctx)}||`;
     case "highlight":
-      return `==${renderInlineChildren(node.children)}==`;
-    case "code":
-      return `\`${codeSpanSafe(node.text)}\``;
+      return `==${renderInlineChildren(node.children, ctx)}==`;
+    case "code": {
+      const safe = codeSpanSafe(node.text);
+      // In a table cell, an unescaped `|` inside the span closes the cell early
+      // and corrupts the row; `\|` survives (GFM keeps the pipe literal in the
+      // span and drops the backslash). Elsewhere the span content is verbatim.
+      return `\`${ctx.inTableCell ? safe.replace(/\|/g, "\\|") : safe}\``;
+    }
     case "link":
-      return `[${renderInlineChildren(node.children)}](${node.href})`;
+      // Escape the href so a literal `)` in the URL can't terminate the
+      // destination early and break the link (F3).
+      return `[${renderInlineChildren(node.children, ctx)}](${escapeLinkHref(node.href)})`;
     default: {
       // Exhaustiveness guard — the IR union is closed; a new variant must be
       // handled above rather than silently dropped.
@@ -76,8 +94,8 @@ function renderInline(node: Inline): string {
   }
 }
 
-function renderInlineChildren(children: Inline[]): string {
-  return children.map(renderInline).join("");
+function renderInlineChildren(children: Inline[], ctx: InlineCtx = {}): string {
+  return children.map((child) => renderInline(child, ctx)).join("");
 }
 
 // ---------------------------------------------------------------------------
@@ -154,7 +172,7 @@ function renderList(node: ListNode): string {
 /** Render a single cell's inline content for a table (no line breaks — GFM
  *  table cells can't contain them; pipes are escaped defensively). */
 function renderTableCell(cells: TableRow["cells"][number]): string {
-  return renderInlineChildren(cells.children).replace(/\n+/g, " ");
+  return renderInlineChildren(cells.children, { inTableCell: true }).replace(/\n+/g, " ");
 }
 
 function alignSeparator(align: TableNode["align"][number]): string {