switchroom 0.18.10 → 0.18.12

package/telegram-plugin/hooks/dispatch-claim-scan.mjs

@@ -0,0 +1,259 @@
+/**
+ * Pure helpers for the dispatch-claim Stop hook (#396) — extracted so
+ * unit tests can exercise the scan logic without spawning the .mjs
+ * subprocess (mirrors the `silent-end-scan.mjs` extraction pattern).
+ *
+ * The defect (#396): the model sends a reply that TELLS the user it has
+ * dispatched work ("Dispatching a worker now to fix this") but the turn
+ * contains no `Agent`/`Task` tool call and no backgrounded `Bash` — the
+ * narration was never backed by an actual dispatch. The silent-end Stop
+ * gate (#1664) does not catch this: that turn HAS a qualifying final
+ * reply, so it passes untouched.
+ *
+ * Mechanism (Stop-hook only — the design comment on #396 drops the
+ * 2026-04 PreToolUse deny; a pre-send deny would fire before the Agent
+ * call exists and block legitimate reply-then-dispatch flows):
+ *   1. Walk the current turn's transcript slice (same turn-anchor walk as
+ *      `silent-end-scan.mjs:scanTurnForFinalReply`), skipping
+ *      `isSidechain:true` lines. A sub-agent's own reply/dispatch lines
+ *      leak into the parent transcript with that marker; they are neither
+ *      the parent's claim NOR the parent's dispatch, so they are skipped
+ *      for BOTH detections.
+ *   2. Collect the text of qualifying `reply`/`stream_reply` tool_use
+ *      calls (reuse `REPLY_TOOLS`).
+ *   3. Detect whether the turn actually dispatched: any non-sidechain
+ *      `Agent`/`Task` tool_use, OR a `Bash` tool_use with
+ *      `run_in_background: true`.
+ *   4. Block only when a reply text makes a first-person dispatch
+ *      commitment AND the turn dispatched nothing.
+ *
+ * Registry-check decision (design comment "belt-and-braces" step 4):
+ * The design offered two options — (a) query the subagent-tracker
+ * `registry.db` for a dispatch row in this turn window, or (b) skip the
+ * registry and rely on transcript-only detection, in which case
+ * "past-tense phrasing must be excluded by the regex". We take (b). The
+ * transcript already carries the ground truth for THIS turn's dispatches
+ * (the `Agent`/`Task` tool_use blocks are in the same JSONL slice we
+ * walk), so a second sqlite round-trip from a dependency-free .mjs hook
+ * would be redundant and awkward. The registry's real value in the design
+ * was clearing PAST-tense references to earlier-turn dispatches; we
+ * achieve the same by EXCLUDING pure past-tense verb forms from the
+ * commitment regex (see DISPATCH_COMMIT_RE below) so "the worker I
+ * dispatched earlier" never trips the gate in the first place. This keeps
+ * the hook self-contained and deterministic (no cross-process DB read on
+ * the reply path).
+ */
+
+// Same two MCP tools whose payload is the model's free-text answer text
+// reaching the user (verified complete in silent-end-scan.mjs's header).
+const REPLY_TOOLS = new Set([
+  'mcp__switchroom-telegram__reply',
+  'mcp__switchroom-telegram__stream_reply',
+])
+
+// Dispatch tool names — Claude Code emits the sub-agent dispatch tool under
+// either the legacy `Agent` or the newer `Task` name depending on version
+// (same dual-name recognition subagent-tracker-pretool.mjs uses).
+const DISPATCH_TOOLS = new Set(['Agent', 'Task'])
+
+// Silent marker (NO_REPLY / HEARTBEAT_OK + optional trailing punct) — a turn
+// whose only reply is a bare silent marker made no claim about anything.
+// Matches silent-end-scan.mjs SILENT_MARKER_RE.
+const SILENT_MARKER_RE = /^(NO_REPLY|HEARTBEAT_OK)[\s.!?]*$/i
+
+// First-person dispatch-commitment regex. Seed list from the #396 design
+// comment:
+//   \b(dispatch(ing|ed)?|launch(ing|ed)?|spinning up|kick(ing|ed) off|
+//     delegat(ing|ed)|spawn(ing|ed)?)\b[^.?!]{0,60}\b(worker|researcher|
+//     reviewer|sub-?agent|agent|task)\b
+//
+// DEVIATION (documented above): because we skip the registry belt-and-
+// braces check, we drop the PURE PAST-TENSE alternatives (`dispatched`,
+// `launched`, `kicked off`, `delegated`, `spawned`) from the verb group.
+// Present/progressive/bare-infinitive forms ("dispatching a worker",
+// "I'll dispatch a worker", "spinning up a researcher") are commitments
+// about THIS turn; a bare past-tense reference ("the worker I dispatched
+// earlier") is about a prior turn and must not trip the gate. Keeping only
+// the non-past forms is the transcript-only substitute for the registry's
+// past-tense clearing.
+const DISPATCH_COMMIT_RE =
+  /\b(?:dispatch(?:ing)?|launch(?:ing)?|spinning up|kick(?:ing)? off|delegat(?:e|ing)|spawn(?:ing)?)\b[^.?!]{0,60}?\b(?:worker|researcher|reviewer|sub-?agent|agent|task)\b/i
+
+// Interrogative / conditional exclusion. A sentence offering to dispatch
+// ("want me to dispatch a worker?", "I could spin up a reviewer if you
+// like") is not a commitment that a dispatch HAPPENED — it is a question
+// or a conditional, so it must not block. Seed list from the design
+// comment: '?', could|should|would|want me to|shall I|if you.
+const CONDITIONAL_RE = /\?|\b(?:could|should|would|want me to|shall i|if you)\b/i
+
+/**
+ * True when `text` (one reply's payload) contains at least one SENTENCE
+ * that makes a first-person dispatch commitment and is not interrogative
+ * or conditional.
+ *
+ * Split into sentences first (retaining the trailing `.?!` terminator) so
+ * the conditional exclusion is scoped to the sentence carrying the verb —
+ * a later unrelated sentence with a '?' must not amnesty a real earlier
+ * commitment, and vice versa.
+ *
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function replyClaimsDispatch(text) {
+  if (typeof text !== 'string' || text.length === 0) return false
+  // Bare silent markers carry no claim.
+  if (SILENT_MARKER_RE.test(text.trim())) return false
+  const sentences = text.match(/[^.?!]+[.?!]*/g) || [text]
+  for (const sentence of sentences) {
+    if (!DISPATCH_COMMIT_RE.test(sentence)) continue
+    if (CONDITIONAL_RE.test(sentence)) continue
+    return true
+  }
+  return false
+}
+
+/**
+ * Compute a stable per-turn signature from the enqueue anchor line's raw
+ * content string (the inbound message envelope). Used by the hook's
+ * 1-retry budget so the budget resets on a genuinely new turn (a new
+ * enqueue line with a new message_id) but is preserved across the
+ * re-prompt of the SAME turn (same enqueue anchor — no new inbound).
+ *
+ * A tiny djb2 hash keeps the state file small and dependency-free.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+export function turnSignature(content) {
+  const s = typeof content === 'string' ? content : ''
+  let h = 5381
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) >>> 0
+  }
+  return `t${h.toString(36)}`
+}
+
+/**
+ * Scan a JSONL transcript and decide whether the current turn told the
+ * user it dispatched work without actually dispatching anything.
+ *
+ * Returns:
+ *   { decided: 'allow',  reason }             — no unbacked dispatch claim
+ *   { decided: 'block',  reason, turnSig }    — a reply claimed a dispatch
+ *                                               but the turn dispatched
+ *                                               nothing; `turnSig` anchors
+ *                                               the hook's retry budget
+ *   { decided: 'unknown', reason }            — no turn-start anchor found;
+ *                                               caller fails open
+ *
+ * Turn-start anchor: the most recent `queue-operation`/`enqueue` line
+ * (identical to `scanTurnForFinalReply`). Fail-open on any structural
+ * miss — a mis-firing gate must never wedge the reply path.
+ *
+ * @param {string} jsonl
+ * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnSig?: string }}
+ */
+export function scanTurnForDispatchClaim(jsonl) {
+  if (typeof jsonl !== 'string' || jsonl.length === 0) {
+    return { decided: 'unknown', reason: 'empty-transcript' }
+  }
+  const lines = jsonl.split('\n')
+
+  // 1. Walk backward to the most-recent enqueue (the turn-start anchor).
+  let startIdx = -1
+  let enqueueContent = ''
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line || line[0] !== '{') continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    if (obj?.type === 'queue-operation' && obj.operation === 'enqueue') {
+      startIdx = i
+      enqueueContent = typeof obj.content === 'string' ? obj.content : ''
+      break
+    }
+  }
+  if (startIdx < 0) {
+    return { decided: 'unknown', reason: 'no-turn-start' }
+  }
+
+  // 2. Walk the turn forward, skipping sub-agent (isSidechain) lines for
+  //    BOTH claim detection and dispatch detection. Collect reply texts;
+  //    note whether the turn dispatched anything real.
+  let dispatched = false
+  const replyTexts = []
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line || line[0] !== '{') continue
+    let obj
+    try { obj = JSON.parse(line) } catch { continue }
+    // Sidechain (sub-agent) lines are not the parent's claim NOR the
+    // parent's dispatch — skip entirely.
+    if (obj?.isSidechain === true) continue
+    if (obj?.type !== 'assistant') continue
+    const content = obj?.message?.content
+    if (!Array.isArray(content)) continue
+    for (const c of content) {
+      if (c?.type !== 'tool_use') continue
+      const name = c.name
+      if (DISPATCH_TOOLS.has(name)) {
+        dispatched = true
+        continue
+      }
+      if (name === 'Bash') {
+        const input = c.input ?? {}
+        if (input.run_in_background === true) dispatched = true
+        continue
+      }
+      if (REPLY_TOOLS.has(name)) {
+        const input = c.input ?? {}
+        replyTexts.push(String(input.text ?? ''))
+        continue
+      }
+    }
+  }
+
+  // 3. If the turn actually dispatched work, the claim (if any) is backed
+  //    — allow, regardless of reply phrasing.
+  if (dispatched) {
+    return { decided: 'allow', reason: 'dispatched' }
+  }
+
+  // 4. No dispatch happened. Block iff a reply made a first-person
+  //    dispatch commitment that was neither interrogative nor conditional.
+  const claimed = replyTexts.some((t) => replyClaimsDispatch(t))
+  if (claimed) {
+    return { decided: 'block', reason: 'claim-without-dispatch', turnSig: turnSignature(enqueueContent) }
+  }
+  return { decided: 'allow', reason: 'no-claim' }
+}
+
+/**
+ * Pure 1-retry-budget helper for the Stop hook. Mirrors the
+ * `silent-end-interrupt-stop.mjs` MAX_RETRIES pattern but with its own
+ * state shape, keyed on the per-turn signature so the budget resets on a
+ * new turn and is honoured across the re-prompt of the same turn.
+ *
+ * Returns:
+ *   { block: true,  nextState }  — budget available; write nextState and block
+ *   { block: false }             — budget exhausted for this turn; fail open
+ *
+ * @param {{ turnSig?: string, retryCount?: number } | null | undefined} existingState
+ * @param {string} turnSig
+ * @param {number} maxRetries
+ * @returns {{ block: boolean, nextState?: { turnSig: string, retryCount: number, timestamp: number } }}
+ */
+export function applyRetryBudget(existingState, turnSig, maxRetries) {
+  const prev = existingState && typeof existingState === 'object' ? existingState : {}
+  // Only carry the counter forward when it belongs to the SAME turn;
+  // otherwise this is a fresh turn and the budget starts at 0.
+  const prevCount =
+    prev.turnSig === turnSig && typeof prev.retryCount === 'number' ? prev.retryCount : 0
+  if (prevCount >= maxRetries) {
+    return { block: false }
+  }
+  return {
+    block: true,
+    nextState: { turnSig, retryCount: prevCount + 1, timestamp: Date.now() },
+  }
+}

package/telegram-plugin/hooks/dispatch-claim-stop.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Stop hook (#396) — deterministic guardrail against "narrate a dispatch
+ * without executing it".
+ *
+ * The defect: the model replies "Dispatching a worker now to fix this",
+ * the user sees a confident hand-off, but the turn contains no `Agent` /
+ * `Task` tool call and no backgrounded `Bash` — nothing was actually
+ * dispatched. The #1664 silent-end Stop gate does NOT catch this: that
+ * turn HAS a qualifying final reply, so it passes untouched.
+ *
+ * This hook, at Stop, scans the just-finished turn's transcript slice for
+ * a reply that makes a first-person dispatch commitment while the turn
+ * dispatched nothing, and re-prompts the model exactly once to actually
+ * dispatch (or send a correction reply). See `dispatch-claim-scan.mjs`
+ * for the pure decision logic and the registry-check rationale.
+ *
+ * Protocol (Claude Code Stop hook v1):
+ *   Input:  JSON on stdin — { session_id, transcript_path, ... }
+ *   Output: exit 0 + empty stdout → allow stop.
+ *           exit 0 + JSON stdout { decision: "block", reason } → re-prompt.
+ *
+ * Fail-open on EVERY error path (no transcript / unreadable / no
+ * turn-start anchor / state-file failure) — consistent with every sibling
+ * reply-path hook. A mis-firing gate must never loop a session; the
+ * 1-retry budget bounds the block direction on top of that.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+import { scanTurnForDispatchClaim, applyRetryBudget } from './dispatch-claim-scan.mjs'
+
+// Exactly one re-prompt per turn (#396 design). A second Stop fire on the
+// same turn (same turnSig) exhausts the budget and fails open.
+const MAX_RETRIES = 1
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+function getStateDir() {
+  return process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
+}
+
+function main() {
+  const raw = readStdin().trim()
+  if (!raw) process.exit(0)
+
+  let event
+  try {
+    event = JSON.parse(raw)
+  } catch {
+    process.exit(0)
+  }
+
+  const transcriptPath = event?.transcript_path
+  if (!transcriptPath || typeof transcriptPath !== 'string' || !existsSync(transcriptPath)) {
+    process.exit(0)
+  }
+
+  let jsonl
+  try {
+    jsonl = readFileSync(transcriptPath, 'utf8')
+  } catch (err) {
+    process.stderr.write(
+      `[dispatch-claim] failed to read transcript ${transcriptPath}: ${err.message}\n`,
+    )
+    process.exit(0)
+  }
+
+  const decision = scanTurnForDispatchClaim(jsonl)
+
+  // 'allow' (no unbacked claim) and 'unknown' (no turn-start anchor) both
+  // allow the stop.
+  if (decision.decided !== 'block') {
+    process.exit(0)
+  }
+
+  // 1-retry budget, keyed on the per-turn signature so a second Stop fire
+  // on the SAME turn fails open while a genuinely new turn starts fresh.
+  const statePath = join(getStateDir(), 'dispatch-claim-pending.json')
+
+  let state = {}
+  if (existsSync(statePath)) {
+    try {
+      state = JSON.parse(readFileSync(statePath, 'utf8'))
+    } catch {
+      state = {}
+    }
+  }
+
+  const budget = applyRetryBudget(state, decision.turnSig, MAX_RETRIES)
+  if (!budget.block) {
+    process.stderr.write(
+      `[dispatch-claim] retry budget exhausted for turn ${decision.turnSig} — allowing stop\n`,
+    )
+    process.exit(0)
+  }
+
+  try {
+    writeFileSync(statePath, JSON.stringify(budget.nextState), 'utf8')
+  } catch (err) {
+    // Fail-open: a retry-count write failure must not loop the session.
+    process.stderr.write(`[dispatch-claim] failed to update state file: ${err.message}\n`)
+    process.exit(0)
+  }
+
+  process.stderr.write(
+    `[dispatch-claim] blocking stop to re-prompt agent (reason=${decision.reason} turn=${decision.turnSig})\n`,
+  )
+
+  process.stdout.write(
+    JSON.stringify({
+      decision: 'block',
+      reason:
+        'Your reply told the user you dispatched work, but no Agent/Task call ' +
+        'ran this turn. Actually dispatch it now, or send a correction reply.',
+    }),
+  )
+  process.exit(0)
+}
+
+main()

package/telegram-plugin/hooks/hooks.json

@@ -91,6 +91,15 @@
           }
         ]
       },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.sh\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/dispatch-claim-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      },
       {
         "hooks": [
           {

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

@@ -60,10 +60,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
@@ -116,7 +131,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 +171,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/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/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",