switchroom 0.19.36 → 0.19.38

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.19.36", COMMIT_SHA = "ba505b15";
+var VERSION = "0.19.38", COMMIT_SHA = "9ec88983";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -31355,8 +31355,8 @@ into your system prompt every session; this is the conversational summary.
   Kicking off a worker to crawl the changelog.
 
   **What it'll do**
-  \u2022 pull every entry since v0.14
-  \u2022 flag anything user-facing
+  - pull every entry since v0.14
+  - flag anything user-facing
 
   **Back in** ~2 min with a synthesized summary.
 - Use backtick-wrapped \`inline code\` for filenames, commands, and
@@ -31540,7 +31540,8 @@ You're writing for a phone screen in Telegram. Every reply renders as rich Markd
   fenced code blocks ALWAYS with a language
   hint (\`\`\`diff, \`\`\`json, \`\`\`bash \u2014 bare fence only for non-code fixed-width output);
   and the flagship \u2014 the **expandable blockquote** \`**> first line\` + \`> continuation\`
-  for a long quote, stack trace, or detailed aside the reader can collapse. Use it
+  for a long quote, stack trace, or detailed aside the reader can collapse. The \`**>\`
+  opener must be at the line start (column 0) \u2014 never indented \u2014 or it won't parse. Use it
   whenever a bulky supporting block would otherwise dominate the message.
 
 Renders wrong on this path \u2014 never emit: underline (\`__x__\` renders as bold),
@@ -31623,6 +31624,8 @@ var init_scaffold = __esm(() => {
     "mcp__hindsight__list_banks",
     "mcp__hindsight__get_memory",
     "mcp__hindsight__list_memories",
+    "mcp__hindsight__invalidate_memory",
+    "mcp__hindsight__update_memory",
     "mcp__hindsight__get_document",
     "mcp__hindsight__list_documents",
     "mcp__hindsight__delete_document",
@@ -45991,13 +45994,15 @@ var init_install_cron = () => {};
 function inParts(memories) {
   return Math.round(memories * PARTS_PER_MEMORY);
 }
-var RING_MAX = 8, MAX_SAMPLE_AGE_MS, MIN_RETAIN_SAMPLES = 20, RETAIN_FAILURE_RATE = 0.1, PARTS_PER_MEMORY = 6, QUEUE_FLOOR_MEMORIES = 100, QUEUE_FLOOR, QUEUE_GROWTH_FRACTION = 0.1, QUEUE_GROWTH_MIN_ABS_MEMORIES = 20, QUEUE_GROWTH_MIN_ABS, BREACHES_TO_FIRE_LEVEL = 2, BREACHES_TO_FIRE_EDGE = 1, CLEARS_TO_RESOLVE = 2, RENOTIFY_MS, DEFAULT_METRICS_URL = "http://127.0.0.1:18888/metrics", DEFAULT_CONTAINER = "switchroom-hindsight", METRICS_MAX_BYTES, METRICS_TIMEOUT_MS = 1e4, RECALL_OWN_BANK_TIMEOUT_WARN = 0.05, RECALL_OWN_BANK_TIMEOUT_PAGE = 0.15, RECALL_ZERO_MEMORY_WARN = 0.25, RECALL_ZERO_MEMORY_PAGE = 0.4, RECALL_POOL_MEDIAN_WARN = 8, RECALL_POOL_MEDIAN_PAGE = 3, RECALL_SCORE_P50_WARN = 0.02, RECALL_SCORE_P50_PAGE = 0.01, CONSOLIDATION_AGE_WARN_S, CONSOLIDATION_AGE_PAGE_S, CONSOLIDATION_FAILURE_STREAK_WARN = 3, CONSOLIDATION_FAILURE_STREAK_PAGE = 10, CONSOLIDATION_STREAK_RECENCY_S, PENDING_CONSOLIDATION_FLOOR = 500, PENDING_CONSOLIDATION_GROWTH_FRACTION = 0.5, PENDING_CONSOLIDATION_GROWTH_WARN_ABS = 500, PENDING_CONSOLIDATION_GROWTH_PAGE_ABS = 5000, VECTOR_INDEX_SAMPLE_ROWS = 3, RECALL_MIN_SAMPLES = 30, LLM_FAILURE_RATE_WARN = 0.02, LLM_FAILURE_RATE_PAGE = 0.1, LLM_MIN_SAMPLES = 20;
+var RING_MAX = 8, MAX_SAMPLE_AGE_MS, MIN_RETAIN_SAMPLES = 20, RETAIN_FAILURE_RATE = 0.1, PARTS_PER_MEMORY = 6, QUEUE_FLOOR_MEMORIES = 100, QUEUE_FLOOR, QUEUE_GROWTH_FRACTION = 0.1, QUEUE_GROWTH_MIN_ABS_MEMORIES = 20, QUEUE_GROWTH_MIN_ABS, BREACHES_TO_FIRE_LEVEL = 2, BREACHES_TO_FIRE_EDGE = 1, CLEARS_TO_RESOLVE = 2, RENOTIFY_MS, DEFAULT_METRICS_URL = "http://127.0.0.1:18888/metrics", DEFAULT_CONTAINER = "switchroom-hindsight", METRICS_MAX_BYTES, METRICS_TIMEOUT_MS = 1e4, RECALL_OWN_BANK_TIMEOUT_WARN = 0.05, RECALL_OWN_BANK_TIMEOUT_PAGE = 0.15, RECALL_ZERO_MEMORY_WARN = 0.25, RECALL_ZERO_MEMORY_PAGE = 0.4, RECALL_POOL_MEDIAN_WARN = 8, RECALL_POOL_MEDIAN_PAGE = 3, RECALL_SCORE_P50_WARN = 0.02, RECALL_SCORE_P50_PAGE = 0.01, RECALL_WALL_MS, CONSOLIDATION_AGE_WARN_S, CONSOLIDATION_AGE_PAGE_S, CONSOLIDATION_FAILURE_STREAK_WARN = 3, CONSOLIDATION_FAILURE_STREAK_PAGE = 10, CONSOLIDATION_STREAK_RECENCY_S, PENDING_CONSOLIDATION_FLOOR = 500, PENDING_CONSOLIDATION_GROWTH_FRACTION = 0.5, PENDING_CONSOLIDATION_GROWTH_WARN_ABS = 500, PENDING_CONSOLIDATION_GROWTH_PAGE_ABS = 5000, VECTOR_INDEX_SAMPLE_ROWS = 3, RECALL_MIN_SAMPLES = 30, LLM_FAILURE_RATE_WARN = 0.02, LLM_FAILURE_RATE_PAGE = 0.1, LLM_MIN_SAMPLES = 20;
 var init_thresholds = __esm(() => {
+  init_hindsight_recall_tunables();
   MAX_SAMPLE_AGE_MS = 3 * 60 * 60000;
   QUEUE_FLOOR = inParts(QUEUE_FLOOR_MEMORIES);
   QUEUE_GROWTH_MIN_ABS = inParts(QUEUE_GROWTH_MIN_ABS_MEMORIES);
   RENOTIFY_MS = 6 * 60 * 60 * 1000;
   METRICS_MAX_BYTES = 16 * 1024 * 1024;
+  RECALL_WALL_MS = resolveHindsightRecallTunables(undefined).parallelDeadlineSeconds * 1000;
   CONSOLIDATION_AGE_WARN_S = 2 * 60 * 60;
   CONSOLIDATION_AGE_PAGE_S = 12 * 60 * 60;
   CONSOLIDATION_STREAK_RECENCY_S = 2 * 60 * 60;
@@ -105309,7 +105314,7 @@ function latencySuffix(r) {
     return "";
   const n = typeof r.elapsedConsidered === "number" ? r.elapsedConsidered : 0;
   return `
-  recall wall time p95 ${Math.round(p95)}ms over ${n} fire(s) (not thresholded \u2014 the 8000ms per-bank budget leaves no healthy band below it)`;
+  recall wall time p95 ${Math.round(p95)}ms over ${n} fire(s) (not thresholded \u2014 the ${RECALL_WALL_MS}ms recall deadline leaves no healthy band below it)`;
 }
 function evaluateRecallOwnBankTimeout(ring) {
   const signal = "recall-own-bank-timeout";
@@ -105908,14 +105913,25 @@ function runInstallCron(cronUser) {
 `);
   return 0;
 }
-async function notifyOperator(agentsDir, text, log) {
+var PREFERRED_RELAY_AGENT = "overlord";
+function orderRelayCandidates(candidates, preferred = PREFERRED_RELAY_AGENT) {
+  const first = candidates.filter((c) => c.agent === preferred);
+  const rest = candidates.filter((c) => c.agent !== preferred);
+  return [...first, ...rest];
+}
+function collectRelayCandidates(agentsDir) {
   const candidates = [];
+  for (const name of readdirSync45(agentsDir).sort()) {
+    const sock = resolve63(agentsDir, name, "telegram", "gateway.sock");
+    if (existsSync112(sock))
+      candidates.push({ agent: name, sock });
+  }
+  return orderRelayCandidates(candidates);
+}
+async function notifyOperator(agentsDir, text, log) {
+  let candidates = [];
   try {
-    for (const name of readdirSync45(agentsDir).sort()) {
-      const sock = resolve63(agentsDir, name, "telegram", "gateway.sock");
-      if (existsSync112(sock))
-        candidates.push({ agent: name, sock });
-    }
+    candidates = collectRelayCandidates(agentsDir);
   } catch (e) {
     log(`hindsight-watch: agents dir unreadable (${e.message})`);
   }

package/dist/host-control/main.js

@@ -21311,7 +21311,7 @@ function allocateAgentUid(name) {
 }
 
 // src/build-info.ts
-var VERSION = "0.19.36";
+var VERSION = "0.19.38";
 
 // src/setup/hindsight-recall-tunables.ts
 var RECALL_DEADLINE_HEADROOM_SECONDS = 2;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.36",
+  "version": "0.19.38",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/bridge/bridge.ts

@@ -94,7 +94,7 @@ const TOOL_SCHEMAS = [
       // client and this detail was being silently truncated away.
       'FORUM TOPICS: a reply is auto-routed back to the topic the question came from, so do NOT pass message_thread_id on a normal reply — pass the inbound\'s origin_turn_id instead, so the answer lands in the right topic even if a message from another topic arrived while you were working. message_thread_id is only for deliberately posting into a topic that is not the one you were asked in. ' +
       // Format modes: likewise moved out of the truncated instructions string.
-      'FORMAT: the default format is "html" — write natural markdown and it is auto-converted to Telegram HTML (bold, italic, code, links, code blocks). Pass format: "markdownv2" for MarkdownV2 with auto-escaping, or "text" for plain text sent verbatim.',
+      'FORMAT: by default your text is rendered as rich GFM markdown (Bot API 10.1) — write natural markdown (bold, italic, code, links, code blocks, lists, tables) and it renders as-is. Pass format: "text" to send plain text verbatim with no rendering. "html" and "markdownv2" are accepted legacy aliases that route through the exact same single rich GFM path — there is no separate HTML engine and no auto-escaping.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -105,7 +105,7 @@ const TOOL_SCHEMAS = [
         message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified.' },
         origin_turn_id: { type: 'string', description: 'In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message\'s topic even if another topic\'s turn started meanwhile. Omit in DMs / single-topic chats.' },
         files: { type: 'array', items: { type: 'string' }, description: 'Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each. Telegram rejects photos with extreme dimensions (aspect ratio over ~10:1, width+height over 10000px, or over 10MB) — very tall images like full-page screenshots are auto-rerouted as documents; crop or split them first if the user should see them inline as photos.' },
-        format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
+        format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path — no separate HTML engine, no auto-escaping." },
         disable_web_page_preview: { type: 'boolean', description: 'Disable link preview thumbnails. Default: true.' },
         protect_content: { type: 'boolean', description: 'When true, Telegram prevents the message from being forwarded or saved.' },
         quote_text: { type: 'string', description: 'Surgical quote: specific text to highlight from the reply_to message. Requires reply_to.' },
@@ -180,7 +180,7 @@ const TOOL_SCHEMAS = [
         chat_id: { type: 'string' },
         message_id: { type: 'string' },
         text: { type: 'string' },
-        format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
+        format: { type: 'string', enum: ['html', 'markdownv2', 'text'], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path — no separate HTML engine, no auto-escaping." },
       },
       required: ['chat_id', 'message_id', 'text'],
     },
@@ -341,7 +341,7 @@ const TOOL_SCHEMAS = [
       type: 'object',
       properties: {
         chat_id: { type: 'string', description: 'Chat that should receive the question. Pass from inbound meta.' },
-        question: { type: 'string', description: 'The question text. Plain text or HTML. Keep it short — buttons render below.' },
+        question: { type: 'string', description: 'The question text. Plain text or GFM markdown (rendered through the same rich path as replies). Keep it short — buttons render below.' },
         options: {
           type: 'array',
           items: { type: 'string' },

package/telegram-plugin/dist/bridge/bridge.js

@@ -25061,7 +25061,7 @@ var mcp = new Server({ name: "telegram", version: "1.0.0" }, {
 var TOOL_SCHEMAS = [
   {
     name: "reply",
-    description: "Reply on Telegram. Pass chat_id from the inbound message. By default the reply is a quote-reply to the latest inbound user message in this chat+thread \u2014 pass quote:false to opt out, or pass an explicit reply_to to thread under a specific earlier message. files (absolute paths) attach images or documents. inline_keyboard adds tappable buttons (URL or callback) under the message \u2014 single-tap actions beat asking the user to type YES. " + "FORUM TOPICS: a reply is auto-routed back to the topic the question came from, so do NOT pass message_thread_id on a normal reply \u2014 pass the inbound's origin_turn_id instead, so the answer lands in the right topic even if a message from another topic arrived while you were working. message_thread_id is only for deliberately posting into a topic that is not the one you were asked in. " + 'FORMAT: the default format is "html" \u2014 write natural markdown and it is auto-converted to Telegram HTML (bold, italic, code, links, code blocks). Pass format: "markdownv2" for MarkdownV2 with auto-escaping, or "text" for plain text sent verbatim.',
+    description: "Reply on Telegram. Pass chat_id from the inbound message. By default the reply is a quote-reply to the latest inbound user message in this chat+thread \u2014 pass quote:false to opt out, or pass an explicit reply_to to thread under a specific earlier message. files (absolute paths) attach images or documents. inline_keyboard adds tappable buttons (URL or callback) under the message \u2014 single-tap actions beat asking the user to type YES. " + "FORUM TOPICS: a reply is auto-routed back to the topic the question came from, so do NOT pass message_thread_id on a normal reply \u2014 pass the inbound's origin_turn_id instead, so the answer lands in the right topic even if a message from another topic arrived while you were working. message_thread_id is only for deliberately posting into a topic that is not the one you were asked in. " + 'FORMAT: by default your text is rendered as rich GFM markdown (Bot API 10.1) \u2014 write natural markdown (bold, italic, code, links, code blocks, lists, tables) and it renders as-is. Pass format: "text" to send plain text verbatim with no rendering. "html" and "markdownv2" are accepted legacy aliases that route through the exact same single rich GFM path \u2014 there is no separate HTML engine and no auto-escaping.',
     inputSchema: {
       type: "object",
       properties: {
@@ -25072,7 +25072,7 @@ var TOOL_SCHEMAS = [
         message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified." },
         origin_turn_id: { type: "string", description: "In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message's topic even if another topic's turn started meanwhile. Omit in DMs / single-topic chats." },
         files: { type: "array", items: { type: "string" }, description: "Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each. Telegram rejects photos with extreme dimensions (aspect ratio over ~10:1, width+height over 10000px, or over 10MB) \u2014 very tall images like full-page screenshots are auto-rerouted as documents; crop or split them first if the user should see them inline as photos." },
-        format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
+        format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path \u2014 no separate HTML engine, no auto-escaping." },
         disable_web_page_preview: { type: "boolean", description: "Disable link preview thumbnails. Default: true." },
         protect_content: { type: "boolean", description: "When true, Telegram prevents the message from being forwarded or saved." },
         quote_text: { type: "string", description: "Surgical quote: specific text to highlight from the reply_to message. Requires reply_to." },
@@ -25146,7 +25146,7 @@ var TOOL_SCHEMAS = [
         chat_id: { type: "string" },
         message_id: { type: "string" },
         text: { type: "string" },
-        format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." }
+        format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path \u2014 no separate HTML engine, no auto-escaping." }
       },
       required: ["chat_id", "message_id", "text"]
     }
@@ -25303,7 +25303,7 @@ var TOOL_SCHEMAS = [
       type: "object",
       properties: {
         chat_id: { type: "string", description: "Chat that should receive the question. Pass from inbound meta." },
-        question: { type: "string", description: "The question text. Plain text or HTML. Keep it short \u2014 buttons render below." },
+        question: { type: "string", description: "The question text. Plain text or GFM markdown (rendered through the same rich path as replies). Keep it short \u2014 buttons render below." },
         options: {
           type: "array",
           items: { type: "string" },

package/telegram-plugin/dist/gateway/gateway.js

@@ -6923,7 +6923,11 @@ function normalizePunctuation(text) {
   const escNonce = nonce.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const linkRestoreRe = new RegExp(`\x00RML${escNonce}_(\\d+)\x00`, "g");
   const restoreLinks = (s) => s.replace(linkRestoreRe, (_m, idx) => linkMasks[Number(idx)] ?? _m);
-  let out = maskedAutolinks.replace(/(\S)[ \t][\u2014\u2013][ \t](?=(\S))/g, (_m, a, b) => /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `).replace(/(\w)\u2014(?=(\w))/g, (_m, a, b) => /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `).replace(/(\w)\u2013(?=\w)/g, "$1-");
+  const rewriteDashes = (line) => line.replace(/(\S)[ \t][\u2014\u2013][ \t](?=(\S))/g, (_m, a, b) => /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `).replace(/(\w)\u2014(?=(\w))/g, (_m, a, b) => /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `).replace(/(\w)\u2013(?=\w)/g, "$1-");
+  const isQuotedLine = (line) => isBlockquoteLine(line) || line.trimStart().startsWith("**>");
+  let out = maskedAutolinks.split(`
+`).map((line) => isQuotedLine(line) ? line : rewriteDashes(line)).join(`
+`);
   out = restoreLinks(out);
   out = out.split(`
 `).map((line) => line.replace(/^([ \t]*)[\u2022\u00b7][ \t]+/, "$1- ")).join(`
@@ -13607,7 +13611,7 @@ function guardUnsupportedTokens(text) {
 var CARET_PAIR, FOOTNOTE_MARKER, DETAILS_BLOCK, ORPHAN_TAGS;
 var init_unsupported_token_guard = __esm(() => {
   CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
-  FOOTNOTE_MARKER = /\[\^\d+\](?!:)/g;
+  FOOTNOTE_MARKER = /\[\^[A-Za-z0-9]{1,10}\](?!:)/g;
   DETAILS_BLOCK = /<details[^>]*>\s*(?:<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/gi;
   ORPHAN_TAGS = /<\/?(?:details|summary)[^>]*>/gi;
 });
@@ -53401,6 +53405,12 @@ function createHandbackPreturnSignal(deps) {
     entry.reapTimer = null;
     if (entry.consumed)
       return;
+    if (deps.isClaudeBusy?.() === true) {
+      log(`handback-preturn-signal: reap deferred key=${entry.statusKey} ` + `(claude busy \u2014 handback enqueued behind an in-flight turn, not orphaned)
+`);
+      entry.reapTimer = setTimer(() => reap(entry), adoptTimeoutMs);
+      return;
+    }
     entry.consumed = true;
     stopTypingUnlessTurnLive(entry, "orphan reap");
     if (entry.activityMessageId != null) {
@@ -99668,10 +99678,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.19.36";
-var COMMIT_SHA = "ba505b15";
-var COMMIT_DATE = "2026-07-30T07:53:24Z";
-var LATEST_PR = 4019;
+var VERSION2 = "0.19.38";
+var COMMIT_SHA = "9ec88983";
+var COMMIT_DATE = "2026-07-30T09:50:08Z";
+var LATEST_PR = 4031;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -104881,7 +104891,7 @@ async function runMidSessionCardReaper() {
       const { finalized, vanished, total } = await runActivityCardMidSessionReaper({
         path: ACTIVITY_CARD_STORE_PATH,
         fs: activityCardStoreFs,
-        isLive: (record2) => topicKeys.has(record2.turnKey),
+        isLive: (record2) => topicKeys.has(record2.turnKey) || handbackPreturnSignal.isPreTurnRecord(record2.turnKey) && isMachineInTurn(),
         ttlMs: MID_SESSION_CARD_REAPER_TTL_MS,
         now,
         finalizeCard: (record2) => {
@@ -107521,7 +107531,8 @@ var handbackPreturnSignal = createHandbackPreturnSignal({
     if (live == null || live.endedAt != null)
       return false;
     return statusKey(live.sessionChatId, live.sessionThreadId) === key;
-  }
+  },
+  isClaudeBusy: () => isMachineInTurn()
 });
 var memoryLegibilityStager = new MemoryLegibilityStager;
 function sendMemoryLegibilityLine(event, chatId, threadId) {

package/telegram-plugin/dist/server.js

@@ -24827,7 +24827,7 @@ var init_bridge = __esm(async () => {
   TOOL_SCHEMAS = [
     {
       name: "reply",
-      description: "Reply on Telegram. Pass chat_id from the inbound message. By default the reply is a quote-reply to the latest inbound user message in this chat+thread \u2014 pass quote:false to opt out, or pass an explicit reply_to to thread under a specific earlier message. files (absolute paths) attach images or documents. inline_keyboard adds tappable buttons (URL or callback) under the message \u2014 single-tap actions beat asking the user to type YES. " + "FORUM TOPICS: a reply is auto-routed back to the topic the question came from, so do NOT pass message_thread_id on a normal reply \u2014 pass the inbound's origin_turn_id instead, so the answer lands in the right topic even if a message from another topic arrived while you were working. message_thread_id is only for deliberately posting into a topic that is not the one you were asked in. " + 'FORMAT: the default format is "html" \u2014 write natural markdown and it is auto-converted to Telegram HTML (bold, italic, code, links, code blocks). Pass format: "markdownv2" for MarkdownV2 with auto-escaping, or "text" for plain text sent verbatim.',
+      description: "Reply on Telegram. Pass chat_id from the inbound message. By default the reply is a quote-reply to the latest inbound user message in this chat+thread \u2014 pass quote:false to opt out, or pass an explicit reply_to to thread under a specific earlier message. files (absolute paths) attach images or documents. inline_keyboard adds tappable buttons (URL or callback) under the message \u2014 single-tap actions beat asking the user to type YES. " + "FORUM TOPICS: a reply is auto-routed back to the topic the question came from, so do NOT pass message_thread_id on a normal reply \u2014 pass the inbound's origin_turn_id instead, so the answer lands in the right topic even if a message from another topic arrived while you were working. message_thread_id is only for deliberately posting into a topic that is not the one you were asked in. " + 'FORMAT: by default your text is rendered as rich GFM markdown (Bot API 10.1) \u2014 write natural markdown (bold, italic, code, links, code blocks, lists, tables) and it renders as-is. Pass format: "text" to send plain text verbatim with no rendering. "html" and "markdownv2" are accepted legacy aliases that route through the exact same single rich GFM path \u2014 there is no separate HTML engine and no auto-escaping.',
       inputSchema: {
         type: "object",
         properties: {
@@ -24838,7 +24838,7 @@ var init_bridge = __esm(async () => {
           message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified." },
           origin_turn_id: { type: "string", description: "In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message's topic even if another topic's turn started meanwhile. Omit in DMs / single-topic chats." },
           files: { type: "array", items: { type: "string" }, description: "Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each. Telegram rejects photos with extreme dimensions (aspect ratio over ~10:1, width+height over 10000px, or over 10MB) \u2014 very tall images like full-page screenshots are auto-rerouted as documents; crop or split them first if the user should see them inline as photos." },
-          format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
+          format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path \u2014 no separate HTML engine, no auto-escaping." },
           disable_web_page_preview: { type: "boolean", description: "Disable link preview thumbnails. Default: true." },
           protect_content: { type: "boolean", description: "When true, Telegram prevents the message from being forwarded or saved." },
           quote_text: { type: "string", description: "Surgical quote: specific text to highlight from the reply_to message. Requires reply_to." },
@@ -24912,7 +24912,7 @@ var init_bridge = __esm(async () => {
           chat_id: { type: "string" },
           message_id: { type: "string" },
           text: { type: "string" },
-          format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." }
+          format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. Default renders your text as rich GFM markdown (Bot API 10.1). 'text' sends plain text verbatim. 'html' and 'markdownv2' are legacy aliases that route through the same single rich GFM path \u2014 no separate HTML engine, no auto-escaping." }
         },
         required: ["chat_id", "message_id", "text"]
       }
@@ -25069,7 +25069,7 @@ var init_bridge = __esm(async () => {
         type: "object",
         properties: {
           chat_id: { type: "string", description: "Chat that should receive the question. Pass from inbound meta." },
-          question: { type: "string", description: "The question text. Plain text or HTML. Keep it short \u2014 buttons render below." },
+          question: { type: "string", description: "The question text. Plain text or GFM markdown (rendered through the same rich path as replies). Keep it short \u2014 buttons render below." },
           options: {
             type: "array",
             items: { type: "string" },

package/telegram-plugin/format.ts

@@ -718,21 +718,37 @@ export function normalizePunctuation(text: string): string {
   const restoreLinks = (s: string): string =>
     s.replace(linkRestoreRe, (_m, idx: string) => linkMasks[Number(idx)] ?? _m)
 
+  // The dash rewrite runs per line so blockquote lines can be exempted:
+  // `>` blockquotes are reserved for VERBATIM quoted text, and rewriting an
+  // author's ` — ` to `, ` inside a quotation would corrupt what they quoted.
+  // The expandable-blockquote opener `**>` is a blockquote line too even though
+  // isBlockquoteLine (which keys on a leading `>`) doesn't catch the `**`
+  // prefix, so exempt it explicitly. Code spans and link hrefs stay masked
+  // throughout, so their dashes are already protected on every line.
+  const rewriteDashes = (line: string): string =>
+    line
+      // 1. Space-flanked em/en dash. Numeric range keeps a hyphen. The right
+      //    flank is a LOOKAHEAD (captured, not consumed) so consecutive spaced
+      //    dashes ("a — b — c") all normalize in one pass — a consumed \S would
+      //    swallow the char that anchors the next match.
+      .replace(/(\S)[ \t][—–][ \t](?=(\S))/g, (_m, a: string, b: string) =>
+        /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
+      )
+      // 2. Bare em-dash between word chars. Numeric range keeps a hyphen.
+      //    Right flank is a lookahead for the same consecutive-match reason.
+      .replace(/(\w)—(?=(\w))/g, (_m, a: string, b: string) =>
+        /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
+      )
+      // 3. Bare en-dash between word chars → hyphen (ranges: 2019–2024).
+      .replace(/(\w)–(?=\w)/g, '$1-')
+
+  const isQuotedLine = (line: string): boolean =>
+    isBlockquoteLine(line) || line.trimStart().startsWith('**>')
+
   let out = maskedAutolinks
-    // 1. Space-flanked em/en dash. Numeric range keeps a hyphen. The right
-    //    flank is a LOOKAHEAD (captured, not consumed) so consecutive spaced
-    //    dashes ("a — b — c") all normalize in one pass — a consumed \S would
-    //    swallow the char that anchors the next match.
-    .replace(/(\S)[ \t][—–][ \t](?=(\S))/g, (_m, a: string, b: string) =>
-      /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
-    )
-    // 2. Bare em-dash between word chars. Numeric range keeps a hyphen.
-    //    Right flank is a lookahead for the same consecutive-match reason.
-    .replace(/(\w)—(?=(\w))/g, (_m, a: string, b: string) =>
-      /\d/.test(a) && /\d/.test(b) ? `${a}-` : `${a}, `,
-    )
-    // 3. Bare en-dash between word chars → hyphen (ranges: 2019–2024).
-    .replace(/(\w)–(?=\w)/g, '$1-')
+    .split('\n')
+    .map((line) => (isQuotedLine(line) ? line : rewriteDashes(line)))
+    .join('\n')
 
   // Restore link hrefs now that the dash passes are done — before the bullet
   // pass and the code restore.

package/telegram-plugin/gateway/gateway.ts

@@ -8909,10 +8909,14 @@ async function runMidSessionCardReaper(): Promise<void> {
       const { finalized, vanished, total } = await runActivityCardMidSessionReaper({
         path: ACTIVITY_CARD_STORE_PATH,
         fs: activityCardStoreFs,
-        // A synthetic pre-turn record's key is never a live topic key, so it is
-        // correctly seen as ownerless here (the seam's own age-based self-reap is
-        // the fast path; this is the crash / long-lived backstop).
-        isLive: (record) => topicKeys.has(record.turnKey),
+        // A synthetic pre-turn key reads as ownerless here (self-reap is the fast
+        // path; this is the crash backstop). EXCEPTION: a pre-turn handback still
+        // enqueued behind an in-flight turn is NOT an orphan — keep it live while
+        // claude is busy, else this 15-min backstop re-posts the false nudge the
+        // self-reap gate removed. (Boot reaper stays ungated: boot is never mid-turn.)
+        isLive: (record) =>
+          topicKeys.has(record.turnKey) ||
+          (handbackPreturnSignal.isPreTurnRecord(record.turnKey) && isMachineInTurn()),
         ttlMs: MID_SESSION_CARD_REAPER_TTL_MS,
         now,
         finalizeCard: (record) => {
@@ -13827,6 +13831,10 @@ const handbackPreturnSignal = createHandbackPreturnSignal({
     // dark-indicator bug). Flag-ON is already per-key; the check is a no-op there.
     return statusKey(live.sessionChatId, live.sessionThreadId) === key
   },
+  // Queue-state gate for the orphan reap (see the signal's `isClaudeBusy` doc):
+  // while a turn is in flight the handback is enqueued behind it, not orphaned.
+  // False for both `bridge_alive_idle` and `bridge_dead` → genuine orphan reaps.
+  isClaudeBusy: () => isMachineInTurn(),
 })
 
 /**

package/telegram-plugin/gateway/handback-preturn-signal.ts

@@ -54,9 +54,23 @@
  *     On adoption the durable record is re-keyed from its synthetic pre-turn key
  *     to the real `statusKey` so that teardown matches.
  *
- *   • NEVER-ADOPTED ORPHAN REAP. A degenerate case (bridge death after release,
- *     no enqueue ever arrives) would leave a frozen card + a forever `typing…`
- *     loop. The pre-turn card is persisted as a COMPLETE `ActivityCardRecord`
+ *   • NEVER-ADOPTED ORPHAN REAP — GATED ON A GLOBAL-BUSY QUEUE CHECK. A
+ *     degenerate case (bridge death after release, no enqueue ever arrives)
+ *     would leave a frozen card + a forever `typing…` loop. But the reap must
+ *     fire ONLY for that genuine orphan, never for a handback that is correctly
+ *     enqueued and simply waiting behind a long in-flight turn: claude has ONE
+ *     bridge / ONE input queue, so a released handback mints its adopting turn
+ *     only when claude next goes idle. A flat age-based reap cannot tell the two
+ *     apart and (before this gate) posted a false "never started — needs a
+ *     nudge" card every time a parent turn out-ran the timeout (the 3-cards-in-
+ *     4-min incident). The reap therefore consults `isClaudeBusy()` — the
+ *     machine-level "a turn is in flight right now" signal — and DEFERS
+ *     (re-arms for another `adoptTimeoutMs`) while claude is busy, finalizing
+ *     only once claude is idle AND the handback still has not been adopted. That
+ *     idle-with-no-adoption state is the genuine bridge-death / dropped-inbound
+ *     degenerate case. Lengthening the flat timeout would merely move the false
+ *     positive; the queue-state gate removes it. The pre-turn card is persisted
+ *     as a COMPLETE `ActivityCardRecord`
  *     under a SYNTHETIC `turnKey` (`preturn:<statusKey>:<startedAt>`) — synthetic
  *     so a sibling REAL turn on the same topic key can neither upsert-clobber it
  *     nor keep it "live" (the mid-session reaper's `isLive` keys on live topic
@@ -171,6 +185,22 @@ export interface HandbackPreturnSignalDeps {
    *  canonical turn-end owns the stop. Optional; defaults to "no live turn"
    *  (the pre-#3544 behaviour). */
   hasLiveTurn?: (statusKey: string) => boolean
+  /** True IFF claude is CURRENTLY producing a turn (ANY topic — the machine has
+   *  ONE bridge / ONE input queue). Consulted by the orphan reap: a released
+   *  handback is delivered into that single queue and only mints its adopting
+   *  turn when claude next goes idle, so while claude is busy the handback is
+   *  NOT orphaned — it is correctly enqueued BEHIND the in-flight turn (a long
+   *  parent turn can run many minutes). Finalizing it as an orphan in that
+   *  window posts a false "never started — needs a nudge" card. The reap
+   *  therefore DEFERS (re-arms) while this is true and finalizes only once
+   *  claude is idle and the handback still has not been adopted — the genuine
+   *  bridge-death / dropped-inbound degenerate case the reap exists for.
+   *  Distinct from `hasLiveTurn`, which is PER-KEY and only governs the
+   *  typing-loop stop; this is the GLOBAL busy signal because the handback
+   *  queues behind whatever turn is running, regardless of topic. Optional;
+   *  defaults to "not busy" (immediate reap — the pre-fix behaviour), so the
+   *  genuine-orphan path is unchanged. */
+  isClaudeBusy?: () => boolean
   now?: () => number
   /** Debounce before painting the pre-turn card (kills sub-second flicker). */
   debounceMs?: number
@@ -349,6 +379,25 @@ export function createHandbackPreturnSignal(
   function reap(entry: PreTurnEntry): void {
     entry.reapTimer = null
     if (entry.consumed) return
+    // PRIMARY GATE (queue state, not a flat timeout): a released handback is
+    // delivered into claude's SINGLE input queue and mints its adopting turn
+    // only when claude next goes idle. If claude is STILL in a turn, this
+    // handback is not orphaned — it is correctly enqueued behind the in-flight
+    // turn (a long parent turn can run many minutes). Finalizing now would post
+    // a false "never started — needs a nudge" card (the 3-cards-in-4-min
+    // incident). Defer: re-arm and re-check. We finalize only once claude is
+    // idle AND the handback still has not been adopted (the genuine bridge-
+    // death / dropped-inbound case). This cannot loop forever on a healthy
+    // agent: claude processes its queue FIFO, so the handback is either adopted
+    // (cancelling the reap) or claude eventually goes idle (letting it fire).
+    if (deps.isClaudeBusy?.() === true) {
+      log(
+        `handback-preturn-signal: reap deferred key=${entry.statusKey} ` +
+          `(claude busy — handback enqueued behind an in-flight turn, not orphaned)\n`,
+      )
+      entry.reapTimer = setTimer(() => reap(entry), adoptTimeoutMs)
+      return
+    }
     entry.consumed = true
     // Stop the forever-running typing loop and finalize the frozen card.
     stopTypingUnlessTurnLive(entry, 'orphan reap')

package/telegram-plugin/render/unsupported-token-guard.ts

@@ -59,12 +59,16 @@ import { splitProtectedSegments } from "./code-segments.js";
  *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. */
 const CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
 
-/** Footnote reference marker `[^N]` (digits only) NOT immediately followed by
- *  `:` (which would make it a footnote DEFINITION line we leave intact). Removed
- *  entirely. Restricting the id to digits keeps this off in-prose bracket
- *  literals like `array[^index]` and regex-ish `[^/]`, which are NOT footnotes
- *  and would otherwise be silently eaten. */
-const FOOTNOTE_MARKER = /\[\^\d+\](?!:)/g;
+/** Footnote reference marker `[^id]` where the id is a short alphanumeric run
+ *  (`[^1]`, `[^note]`, `[^ref]`) NOT immediately followed by `:` (which would
+ *  make it a footnote DEFINITION line we leave intact). Removed entirely.
+ *  Requiring the id to be 1–10 ALPHANUMERIC chars keeps this off regex-ish
+ *  literals like `[^/]`, `[^\s]`, `[^-a-z]`, whose bodies contain punctuation
+ *  and so never match. In-prose subscript-ish `array[^i]` outside a code span
+ *  is a rare theoretical false positive (an `i` id matches); code spans are
+ *  masked upstream by splitProtectedSegments so real code is safe, and prose
+ *  that writes a literal `[^i]` reads as footnote noise anyway. */
+const FOOTNOTE_MARKER = /\[\^[A-Za-z0-9]{1,10}\](?!:)/g;
 
 /** `<details>…</details>` with an optional leading `<summary>…</summary>`.
  *  Dot-all via `[\s\S]`; non-greedy so adjacent blocks don't merge. */

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

@@ -245,6 +245,24 @@ describe('normalizePunctuation', () => {
     expect(normalizePunctuation('<not—a—url>')).toBe('<not, a, url>')
   })
 
+  test('does NOT rewrite a dash inside a `>` blockquote (verbatim quote)', () => {
+    // `>` blockquotes hold quoted text the author is reproducing verbatim;
+    // rewriting their em-dash to `, ` corrupts the quotation.
+    expect(normalizePunctuation('> she said — plainly — no')).toBe(
+      '> she said — plainly — no',
+    )
+    // Indented blockquote line is still a blockquote.
+    expect(normalizePunctuation('  > quoted — text')).toBe('  > quoted — text')
+    // The expandable-blockquote opener `**>` is a blockquote line too.
+    expect(normalizePunctuation('**> first — line\n> continues — here')).toBe(
+      '**> first — line\n> continues — here',
+    )
+    // Prose OUTSIDE the quote still normalizes; only the quoted line is spared.
+    expect(normalizePunctuation('intro — here\n> quote — verbatim\nafter — end')).toBe(
+      'intro, here\n> quote — verbatim\nafter, end',
+    )
+  })
+
   test('idempotent', () => {
     const once = normalizePunctuation('a — b\n• c\nd—e\n1–2')
     expect(normalizePunctuation(once)).toBe(once)

package/telegram-plugin/tests/handback-preturn-signal.test.ts

@@ -300,6 +300,73 @@ describe('handback-preturn-signal — dead-air pre-turn emit→adopt→reap', ()
     expect(h.signal.pendingCount()).toBe(0) // map empty
   })
 
+  // ── queued-behind-a-long-turn is NOT an orphan (the 3-cards-in-4-min bug) ──
+  // A handback released while the parent is mid-turn on a long task is delivered
+  // into claude's single input queue and mints its adopting turn only when the
+  // parent turn ends. The flat 30 s reap could not tell "enqueued and waiting"
+  // from "bridge died, never enqueued" and finalized a false "handback never
+  // started — needs a nudge" card. With the queue-state gate (`isClaudeBusy`)
+  // the reap DEFERS while claude is busy and the late adoption finalizes the
+  // card honestly. This test FAILS on the pre-fix flat-30 s behaviour: without
+  // the gate the reap fires at 30 s, finalizes the orphan text, and consumes the
+  // entry so the later adoption returns null.
+  it('does NOT finalize a handback whose turn adopts late because the parent was busy', async () => {
+    let busy = false
+    const h = makeHarness({ isClaudeBusy: () => busy })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatBusy', messageId: 700 }))
+    await h.sched.advance(700) // debounce: card painted, reap armed
+    const resolvedId = await h.openCard.mock.results[0]!.value
+    expect(h.records.size).toBe(1)
+
+    // The parent turn is now in flight (a long Wave-2 assembly). The handback is
+    // enqueued behind it.
+    busy = true
+
+    // Two full reap intervals elapse — well beyond the flat 30 s. The reap must
+    // DEFER each time: no false orphan card, entry still live, typing still lit.
+    await h.sched.advance(30_000)
+    await h.sched.advance(30_000)
+    expect(h.finalizedIds).toEqual([]) // NEVER posted the "never started" nudge
+    expect(h.signal.pendingCount()).toBe(1) // still queued, not reaped
+    expect(h.typing.activeCount()).toBe(1) // indicator kept while queued
+
+    // The parent turn finally ends and the handback mints its own turn: it
+    // adopts the SAME card (an edit, not a second send / not an orphan finalize).
+    busy = false
+    const turnId = deriveTurnId('chatBusy', null, 700)!
+    const adoption = h.signal.tryAdopt(turnId)
+    expect(adoption).not.toBeNull()
+    expect(adoption!.activityMessageId).toBe(resolvedId)
+    expect(h.finalizedIds).toEqual([]) // adopted, never finalized as orphan
+    expect(h.openCard).toHaveBeenCalledTimes(1) // no double-send
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
+  // The deferred reap is not a leak: once claude goes idle and the handback has
+  // STILL not been adopted (genuine bridge-death / dropped inbound), the re-armed
+  // reap finalizes honestly — the degenerate case the reap exists for.
+  it('finalizes a genuine orphan once claude goes idle, even after deferring while busy', async () => {
+    let busy = true
+    const h = makeHarness({ isClaudeBusy: () => busy })
+    h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatIdleOrphan', messageId: 710 }))
+    await h.sched.advance(700)
+    const resolvedId = await h.openCard.mock.results[0]!.value
+
+    // Busy: the first reap defers.
+    await h.sched.advance(30_000)
+    expect(h.finalizedIds).toEqual([])
+    expect(h.signal.pendingCount()).toBe(1)
+
+    // Claude goes idle but NO adopting turn ever mints (the inbound was dropped).
+    // The re-armed reap now finalizes the genuine orphan.
+    busy = false
+    await h.sched.advance(30_000)
+    expect(h.finalizedIds).toEqual([resolvedId])
+    expect(h.typing.activeCount()).toBe(0)
+    expect(h.records.size).toBe(0)
+    expect(h.signal.pendingCount()).toBe(0)
+  })
+
   it('identity race: a user inbound on the same topic never mis-adopts the handback, no double-send', async () => {
     const h = makeHarness()
     h.signal.noteHandbackRelease(handbackInbound({ chatId: 'chatE', messageId: 200 }))

package/telegram-plugin/tests/mcp-instructions-budget.test.ts

@@ -162,8 +162,15 @@ describe("moved instruction content landed in tool descriptions", () => {
 
   it("format modes landed in the reply description", () => {
     expect(bridgeCode).toContain("FORMAT:");
-    expect(bridgeCode).toMatch(/default format is "html"/);
+    // The description must describe the ONE real render path (rich GFM), and
+    // still name the legacy aliases so the enum values stay documented. It must
+    // NOT resurrect the deleted-engine claims (html→HTML conversion, MarkdownV2
+    // auto-escaping) — those are false at HEAD (single GFM path, no escaping).
+    expect(bridgeCode).toMatch(/rich GFM markdown/);
     expect(bridgeCode).toContain("markdownv2");
+    expect(bridgeCode).not.toMatch(/default format is "html"/);
+    expect(bridgeCode).not.toMatch(/auto-converted to Telegram HTML/);
+    expect(bridgeCode).not.toMatch(/MarkdownV2 with auto-escaping/);
   });
 
   it("history-buffer rationale landed in get_recent_messages", () => {

package/telegram-plugin/tests/render/unsupported-token-guard.test.ts

@@ -71,15 +71,46 @@ describe("guardUnsupportedTokens — deterministic send-time repair", () => {
     expect(guardUnsupportedTokens("x^2^ metres")).toBe("x2 metres");
   });
 
-  it("leaves in-prose bracket literals intact, repairs real numeric footnotes", () => {
-    // `array[^index]` is a negated-char-class / index literal, not a footnote.
-    expect(guardUnsupportedTokens("array[^index] lookup")).toBe(
-      "array[^index] lookup",
+  it("repairs alphanumeric footnote markers, not just numeric", () => {
+    // POLISH-4: widened from digits-only so `[^note]`/`[^ref]` no longer ship
+    // as literal bracket noise. Each would survive UNTOUCHED on origin/main.
+    expect(guardUnsupportedTokens("see the note[^note] here")).toBe(
+      "see the note here",
+    );
+    expect(guardUnsupportedTokens("as shown[^ref] above")).toBe(
+      "as shown above",
+    );
+    expect(guardUnsupportedTokens("point[^fn1] made")).toBe("point made");
+    // A single-letter id is a footnote too.
+    expect(guardUnsupportedTokens("claim[^a] holds")).toBe("claim holds");
+    // Definition lines with an alphanumeric id are still left intact (`(?!:)`).
+    expect(guardUnsupportedTokens("[^note]: the definition")).toBe(
+      "[^note]: the definition",
     );
+  });
+
+  it("leaves regex-literal negated char classes intact", () => {
+    // Real negated char classes contain punctuation / ranges / escapes, so the
+    // alphanumeric-only id requirement excludes them — these stay verbatim.
     expect(guardUnsupportedTokens("use [^/] to match")).toBe(
       "use [^/] to match",
     );
-    // A real numeric footnote marker is still stripped.
+    expect(guardUnsupportedTokens("strip [^a-z] chars")).toBe(
+      "strip [^a-z] chars",
+    );
+    expect(guardUnsupportedTokens('match [^"] here')).toBe('match [^"] here');
+    // Accepted tradeoff (task POLISH-4): a PURE-alphanumeric negated class in
+    // BARE prose like `array[^index]` is now treated as a footnote and stripped.
+    // This is rare — regex/index literals in real prose live in code spans,
+    // which splitProtectedSegments masks (see code-span test below).
+    expect(guardUnsupportedTokens("array[^index] lookup")).toBe("array lookup");
+    // …but inside a code span the same literal is untouched.
+    expect(guardUnsupportedTokens("`array[^index]` lookup")).toBe(
+      "`array[^index]` lookup",
+    );
+  });
+
+  it("repairs a real numeric footnote marker", () => {
     expect(guardUnsupportedTokens("see the note[^1] here")).toBe(
       "see the note here",
     );