switchroom 0.16.38 → 0.16.47

package/telegram-plugin/gateway/gateway.ts

@@ -62,11 +62,19 @@ import {
   buildListenKeyboard,
   mayInjectListenButton,
 } from '../voice-ondemand.js'
+import {
+  PreSynthQueue,
+  sweepVoiceCacheDir,
+  writeVoiceCacheFile,
+  eagerVoiceEnabled,
+  VOICE_SWEEP_INTERVAL_MS,
+} from '../voice-presynth.js'
 
 /** Fleet default TTS speed when voice_out is enabled but speed is unset —
  *  slightly brisker than neutral (Ken's chosen default). */
 const VOICE_OUT_DEFAULT_SPEED = 1.1
 import { normalizeForSpeech } from '../voice-normalize-text.js'
+import { normalizeForTts } from '../tts-normalize.js'
 import { synthesizeViaOpenAi } from '../voice-synthesize.js'
 import {
   createTelegraphAccount,
@@ -225,7 +233,7 @@ const REPLY_TO_TEXT_MAX = 200
 const SILENT_END_FALLBACK_TEXT =
   '⚠️ The agent finished working but didn’t send a reply — your last ' +
   'message may not have been answered. Please try asking again.'
-import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, escapeMarkdown, RICH_MESSAGE_MAX_CHARS } from '../format.js'
+import { splitMarkdownChunks, hardSliceToCap, repairEscapedWhitespace, normalizeParagraphBreaks, addParagraphSpacers, normalizePunctuation, stripExcessBold, escapeMarkdown, RICH_MESSAGE_MAX_CHARS } from '../format.js'
 import { richMessage } from '../rich-send.js'
 import { scrubVoice } from '../text-voice-scrub.js'
 import {
@@ -317,6 +325,8 @@ import {
   MODEL_CALLBACK_PREFIX,
   MODEL_CALLBACK_HEADER,
   MODEL_CALLBACK_SR,
+  MODEL_CALLBACK_PAGE_EXTERNAL,
+  MODEL_CALLBACK_PAGE_MAIN,
   srFriendlyLabel,
   type ModelMenuDeps,
   type ModelCommandDeps,
@@ -8623,7 +8633,79 @@ const VOICE_OUT_HARD_CHUNK_CAP = 4096
  * Bounded LRU with a TTL so a stale button (tapped an hour later) degrades to
  * a graceful "expired" toast rather than pinning reply text in memory forever.
  */
-const voiceOnDemandCache = new VoiceOnDemandCache()
+// Persist the Listen-token cache under STATE_DIR (= /state/agent/telegram in
+// prod, a volume that survives container recreation). Without this the Map was
+// wiped on every gateway restart, so a 🔊 Listen button tapped on a message
+// sent before the restart degraded to "Voice expired". The same TTL + LRU cap
+// still applies; expired entries are dropped on load.
+const voiceOnDemandCache = new VoiceOnDemandCache({
+  persistPath: join(STATE_DIR, 'voice-ondemand.json'),
+})
+
+// ─── Eager voice pre-synthesis (#2763) ─────────────────────────────────────
+// Whenever a reply becomes Listen-eligible (a voiceOnDemandCache entry is
+// persisted alongside the Listen button), ALSO synthesize the audio in the
+// background via the LOCAL sidecar and park it on disk, so the 🔊 Listen tap
+// attaches the pre-made file instantly instead of waiting on the GPU. Local
+// engine only (kokoro — zero token/dollar cost); the openai cloud engine
+// never pre-synthesizes. Strictly off the reply critical path: jobs drain
+// through a bounded FIFO (concurrency 1, drop-oldest past the cap) and every
+// failure is swallowed — the tap just falls back to the lazy synth path.
+// Kill switch: SWITCHROOM_DISABLE_EAGER_VOICE=1 (the sweep still runs so old
+// files age out).
+const VOICE_CACHE_DIR = join(STATE_DIR, 'voice-cache')
+
+const voicePreSynthQueue = new PreSynthQueue({
+  runJob: async (job) => {
+    const sidecarToken = await materializeSidecarToken()
+    if (!sidecarToken) return // sidecar unavailable — lazy path will retry on tap
+    const result = await synthesizeViaSidecar({
+      token: sidecarToken,
+      // Same deterministic normalization the lazy Listen path applies —
+      // job.text is normalizeForSpeech(reply); normalizeForTts is the #2760
+      // L1 pass on top.
+      text: normalizeForTts(job.text),
+      voice: job.voice,
+      speed: job.speed,
+    })
+    if (!result.ok) {
+      process.stderr.write(
+        `telegram gateway: voice-presynth: sidecar synthesis failed token=${job.token} reason=${result.reason}\n`,
+      )
+      return
+    }
+    const filePath = writeVoiceCacheFile(VOICE_CACHE_DIR, job.token, result.audio)
+    voiceOnDemandCache.setFilePath(job.token, filePath)
+    process.stderr.write(
+      `telegram gateway: voice-presynth: cached ${result.audio.length} bytes at ${filePath} ` +
+        `(${result.durationMs}ms, backlog=${voicePreSynthQueue.size})\n`,
+    )
+  },
+})
+
+/** Rolling 7-day TTL + 500MB size-budget sweep over VOICE_CACHE_DIR. Runs at
+ *  boot and hourly; ALWAYS runs (even under the eager-voice kill switch) so
+ *  previously written files age out. Crash-safe: missing dir/files tolerated. */
+function sweepVoiceCache(): void {
+  try {
+    const result = sweepVoiceCacheDir({ dir: VOICE_CACHE_DIR })
+    if (result.deletedTokens.length > 0) {
+      voiceOnDemandCache.prune(result.deletedTokens)
+      process.stderr.write(
+        `telegram gateway: voice-presynth: sweep removed ${result.deletedTokens.length} file(s), ` +
+          `${result.remainingBytes} bytes remain\n`,
+      )
+    }
+  } catch (err) {
+    // Defence in depth — sweepVoiceCacheDir is already per-file crash-safe.
+    process.stderr.write(`telegram gateway: voice-presynth: sweep failed: ${String(err)}\n`)
+  }
+}
+
+if (!STATIC) {
+  sweepVoiceCache() // boot sweep — covers a died timer / long downtime
+  setInterval(sweepVoiceCache, VOICE_SWEEP_INTERVAL_MS).unref()
+}
 
 type VoiceOutAccess = NonNullable<Access['voice_out']>
 
@@ -8735,12 +8817,16 @@ async function synthesizeVoiceOut(plan: {
   ttsText: string
 }): Promise<Uint8Array | null> {
   try {
+    // #2760 Phase 1: deterministic L1 TTS normalization, applied at the
+    // single choke point where every engine's request body is built.
+    // On by default; kill switch: SWITCHROOM_DISABLE_TTS_NORMALIZE=1.
+    const ttsText = normalizeForTts(plan.ttsText)
     if (plan.engine === 'kokoro') {
       const token = await materializeSidecarToken()
       if (!token) return null // materializeSidecarToken already logged why.
       const result = await synthesizeViaSidecar({
         token,
-        text: plan.ttsText,
+        text: ttsText,
         voice: plan.voice,
         speed: plan.speed,
       })
@@ -8764,7 +8850,7 @@ async function synthesizeVoiceOut(plan: {
     if (!apiKey) return null // materializeVoiceKey already logged why.
     const result = await synthesizeViaOpenAi({
       apiKey,
-      text: plan.ttsText,
+      text: ttsText,
       voice: plan.voice,
     })
     if (!result.ok) {
@@ -8834,8 +8920,16 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
   // Outbound secret scrub (#2044): mask any secret the agent echoed BEFORE
   // the stderr preview below, the dedup key, the send, and the history
   // record. Mutates `text` so every downstream consumer sees the masked
-  // value, exactly like the voice scrub that follows.
+  // value, exactly like the voice scrub that follows. Runs BEFORE the
+  // punctuation/bold normalizers so a secret containing an em-dash or `**`
+  // is matched literally by the redactor before any mutation.
   text = redactOutboundText(text, 'reply')
+  // Fleet-wide consistent formatting: normalize dashes/bullets and trip the
+  // over-bold guard deterministically, on code-masked text (same contract on
+  // reply / edit / stream paths). Runs before scrubVoice below so dashes get
+  // the comma treatment on every path; scrubVoice's dash telemetry
+  // (voice_scrub_applied) drops to ~zero here as a result — deliberate.
+  text = stripExcessBold(normalizePunctuation(text))
   // Voice scrub (#1683): replace em / en dashes with commas / periods.
   // Runs BEFORE outboundDedup so retries see the scrubbed key, and on the
   // raw markdown text (the scrubber does its own code-region parking so
@@ -9258,6 +9352,22 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
       // replayed. The gate above guarantees this is the ONLY button on the
       // message, so keeping it is safe (no agent buttons to protect).
       replyMarkup = buildListenKeyboard(token)
+      // #2763 eager pre-synthesis: kick a background synth of the same
+      // payload so the Listen tap attaches the pre-made file instantly.
+      // Local-engine only (useOnDemandButton already gates engine==='kokoro'
+      // — the cloud engine never eager-synthesizes). enqueue() is a
+      // synchronous array push; the drain is deferred + async and never
+      // awaited here, so the text sends below are never delayed and a synth
+      // failure can never affect message delivery (the tap just falls back
+      // to the lazy path).
+      if (eagerVoiceEnabled()) {
+        voicePreSynthQueue.enqueue({
+          token,
+          text: voiceOutPlan.ttsChunks[0]!,
+          ...(voiceOutPlan.voice != null ? { voice: voiceOutPlan.voice } : {}),
+          speed: voiceOutPlan.speed,
+        })
+      }
     }
   }
 
@@ -10094,6 +10204,16 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
   // controller, dedup record, history record) see the scrubbed
   // version. Kill switch: SWITCHROOM_DISABLE_VOICE_SCRUB.
   {
+    // Cross-path consistency (#2755): normalizePunctuation runs BEFORE
+    // scrubVoice here, matching the reply/edit paths, so a spaced em-dash
+    // gets the same comma treatment on every outbound path (scrubVoice
+    // would otherwise see the raw dash first on this path only and apply
+    // its period substitution). handleStreamReply's own deps run
+    // normalizePunctuation again downstream — it is idempotent, so the
+    // second pass is a no-op. Side effect: scrubVoice's dash telemetry
+    // (voice_scrub_applied) drops to ~zero on this path since the dashes
+    // are consumed here first — deliberate.
+    args.text = normalizePunctuation(args.text as string)
     const scrub = scrubVoice(args.text as string)
     if (scrub.replaced > 0) {
       args.text = scrub.scrubbed
@@ -10251,6 +10371,8 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       retry: robustApiCall,
       repairEscapedWhitespace,
       normalizeParagraphBreaks,
+      normalizePunctuation,
+      stripExcessBold,
       addParagraphSpacers,
       assertAllowedChat,
       resolveThreadId,
@@ -11319,7 +11441,12 @@ async function executeVaultRequestAccess(args: Record<string, unknown>): Promise
   if (scopeRaw !== 'read' && scopeRaw !== 'write') {
     throw new Error('vault_request_access: scope must be "read" or "write"')
   }
-  const reason = typeof args.reason === 'string' ? args.reason : undefined
+  // Accept `why` as an alias for `reason`: the sibling tool
+  // vault_request_save uses `why`, and agents cross-contaminate the two
+  // schemas — without the alias the rationale silently drops off the
+  // approval card and the operator sees "why: not provided".
+  const reason =
+    typeof args.reason === 'string' ? args.reason : typeof args.why === 'string' ? args.why : undefined
   // Duration: accept a "30d" / "12h" string from the agent OR default
   // to 30 days. Cap at 90 days — beyond that the operator should use
   // the host CLI and pick the lifetime explicitly. Refuse "never"
@@ -11480,10 +11607,14 @@ async function executeEditMessage(args: Record<string, unknown>): Promise<unknow
   // paragraph breaks for the rich path. A literal-text edit (`format:'text'`)
   // skips paragraph normalization — it must edit byte-for-byte as given.
   let editRawText = repairEscapedWhitespace(args.text as string)
-  if (!editLiteralText) editRawText = addParagraphSpacers(normalizeParagraphBreaks(editRawText))
+  if (!editLiteralText) editRawText = normalizeParagraphBreaks(editRawText)
   // Outbound secret scrub (#2044): an edit must not re-introduce a raw
   // secret into a live bubble or the history row. Mask before scrub/send.
   editRawText = redactOutboundText(editRawText, 'edit_message')
+  // Fleet-wide consistent formatting (same order as the reply path: redact
+  // first so secrets are matched literally, then normalize, then spacers on
+  // the rich path only).
+  if (!editLiteralText) editRawText = addParagraphSpacers(stripExcessBold(normalizePunctuation(editRawText)))
   // Voice scrub (#1683): same em-dash scrub as the reply path. Edits
   // are how silent-anchor and progress-update mutate already-sent
   // bubbles, so without this an edit can re-introduce dashes the
@@ -20029,20 +20160,61 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
       // cards open at once.
       const joiningBatch = items.length > 1
       await ctx.answerCallbackQuery({ text: joiningBatch ? `🔐 Queued — one passphrase covers ${items.length} cards` : '🔐 Send your passphrase…' }).catch(() => {})
+
+      // Strip the buttons on the ORIGINAL card and mark it "waiting" so it
+      // can't be re-tapped, but do NOT overload it as the passphrase prompt.
+      // An in-place edit fires no notification and stays pinned to the card's
+      // old position in the chat, so a busy topic buries it and the operator
+      // never sees the passphrase ask — the exact admin-key miss this fixes
+      // (v0.16.45: the prompt scrolled off, the passphrase never arrived, the
+      // grant was never minted). The prompt goes out as a fresh message below.
       await ctx.api
         .editMessageText(
           pending.chat_id,
           pending.card_message_id,
-          joiningBatch
-            ? `🔐 **Queued behind an earlier card.** Type your passphrase as your next message — it covers **${items.length}** pending approvals in this chat (one entry mints all grants, no re-type per card).`
-            : isAdminOnly
-            ? `🔒 **Admin-only credential.** \`${pending.key}\` requires your vault passphrase to grant — reply with it as your next message and we'll mint the grant for **${escapeHtmlForTg(pending.agent)}**, then delete the passphrase message.\n\n` +
-              `_The passphrase is what proves it's you: an agent can never mint this key on its own._`
-            : `🔐 **Vault is locked.** Reply with your passphrase as your next message — we'll unlock, mint the grant for **${escapeHtmlForTg(pending.agent)}**, and delete the passphrase message in one step.\n\n` +
-              richMessage(`_Mint authority stays operator-only: the broker only accepts the grant when the passphrase matches._`),
+          richMessage(`🔐 _Approved — waiting for your vault passphrase. See the prompt below._`),
           { reply_markup: { inline_keyboard: [] } },
         )
         .catch(() => {})
+
+      // The passphrase prompt as a NEW rich message. Three fixes vs. the old
+      // in-place edit, all of which the reported bug needed:
+      //   1. Real bold/italic — rendered through the sanctioned `richMessage`
+      //      GFM path (`sendRichMessage`), never a raw string. The old admin
+      //      and joining-batch branches passed raw markdown to editMessageText
+      //      (parse_mode=none), so `**`/`_` rendered as literal characters;
+      //      the "locked" branch even concatenated a string with a
+      //      `richMessage()` object (→ `[object Object]`). All three are gone.
+      //   2. It lands at the BOTTOM of the chat, not stapled to an old card
+      //      that later messages bury.
+      //   3. It fires a notification — `disable_notification` is deliberately
+      //      NOT set — so the operator is actually pinged to act.
+      // Attention-grabbing header, short lines, key in code formatting.
+      const promptText = joiningBatch
+        ? `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
+          `Type your vault passphrase as your **next message**.\n` +
+          `One entry covers **${items.length}** pending approvals in this chat, no re-type per card.\n\n` +
+          `_We delete the passphrase message the moment we read it._`
+        : isAdminOnly
+        ? `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
+          `\`${pending.key}\` is an **admin-only credential**.\n` +
+          `Type your vault passphrase as your **next message** to mint the grant for **${escapeHtmlForTg(pending.agent)}**.\n\n` +
+          `_The passphrase is what proves it's you. An agent can never mint this key on its own. We delete the passphrase message the moment we read it._`
+        : `**⚠️🔐 ACTION NEEDED: passphrase required**\n\n` +
+          `Your vault is locked.\n` +
+          `Reply with your passphrase as your **next message** to unlock and mint the grant for **${escapeHtmlForTg(pending.agent)}**.\n\n` +
+          `_Mint authority stays operator-only: the broker only accepts the grant when the passphrase matches. We delete the passphrase message the moment we read it._`
+
+      // #1075: deleted-topic safe — fall back to the main chat. Wrapped
+      // through robustApiCall for flood-wait retries, mirroring the card send.
+      await retryWithThreadFallback<{ message_id: number }>(
+        robustApiCall,
+        (tid) =>
+          lockedBot.api.sendRichMessage(pending.chat_id, richMessage(promptText), {
+            ...(tid != null && Number.isFinite(tid) ? { message_thread_id: tid } : {}),
+          }),
+        { threadId: pending.threadId, chat_id: pending.chat_id, verb: 'vault_request_access.passphrase_prompt' },
+      ).catch(() => {})
       return
     }
 
@@ -22076,7 +22248,11 @@ bot.on('callback_query:data', async ctx => {
       await ctx.answerCallbackQuery({ text: 'Tap a model in this section to switch' }).catch(() => {})
       return
     }
-    await ctx.answerCallbackQuery({ text: 'Switching…' }).catch(() => {})
+    // Page navigation (External ▸ / ◂ Back) just re-renders the menu with the
+    // other keyboard page — it never drives the picker, so ack "Loading…"
+    // rather than the switch-oriented "Switching…".
+    const isPageNav = data === MODEL_CALLBACK_PAGE_EXTERNAL || data === MODEL_CALLBACK_PAGE_MAIN
+    await ctx.answerCallbackQuery({ text: isPageNav ? 'Loading…' : 'Switching…' }).catch(() => {})
     // sr-* inject waits for claude to respond (can take 10-30s). Edit the
     // menu immediately to show a "working on it" state so the operator isn't
     // left looking at a stale menu with no feedback. The final edit (✅/❌)
@@ -22453,7 +22629,6 @@ bot.on('callback_query:data', async ctx => {
         .catch(() => {})
       return
     }
-    await ctx.answerCallbackQuery({ text: '🔊 Synthesizing…' }).catch(() => {})
     const cbChatId = String(ctx.chat?.id ?? ctx.from.id)
     const cbMessageId = ctx.callbackQuery?.message?.message_id
     const cbThreadId = (() => {
@@ -22464,31 +22639,57 @@ bot.on('callback_query:data', async ctx => {
       }
       return undefined
     })()
-    // Local sidecar (kokoro) synthesis — same helper the immediate voice-out
-    // path uses. On-demand is a local-engine feature; the cache is only
-    // populated when resolveVoiceOutPlan gated the local verdict.
-    const sidecarToken = await materializeSidecarToken()
-    if (!sidecarToken) {
-      await ctx
-        .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
-        .catch(() => {})
-      return
+    // #2763 attach-on-tap: prefer the eagerly pre-synthesized file (written
+    // by the pre-synth queue at reply time). If it's on disk, attach it
+    // immediately — no GPU wait. Missing/unreadable file (expired + swept,
+    // crash, pre-feature entry, kill-switched gateway) falls back
+    // transparently to the lazy synth path below.
+    let audio: Uint8Array | null = null
+    if (entry.filePath != null) {
+      try {
+        audio = readFileSync(entry.filePath)
+      } catch {
+        audio = null // swept/missing — lazy fallback
+      }
     }
-    const result = await synthesizeViaSidecar({
-      token: sidecarToken,
-      text: entry.text,
-      voice: entry.voice,
-      speed: entry.speed,
-    })
-    if (!result.ok) {
-      process.stderr.write(
-        `telegram gateway: voice-out on-demand: synthesis failed reason=${result.reason}\n`,
-      )
-      await ctx
-        .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
-        .catch(() => {})
-      return
+    if (audio != null) {
+      await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+    } else {
+      await ctx.answerCallbackQuery({ text: '🔊 Synthesizing…' }).catch(() => {})
+      // Local sidecar (kokoro) synthesis — same helper the immediate voice-out
+      // path uses. On-demand is a local-engine feature; the cache is only
+      // populated when resolveVoiceOutPlan gated the local verdict.
+      const sidecarToken = await materializeSidecarToken()
+      if (!sidecarToken) {
+        await ctx
+          .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
+          .catch(() => {})
+        return
+      }
+      const result = await synthesizeViaSidecar({
+        token: sidecarToken,
+        // #2760 Phase 1: same deterministic normalization as the immediate
+        // voice-out path — the Listen lazy path builds its own /tts body from
+        // the persisted cache, so it must normalize independently (cache
+        // entries may predate the flag flip).
+        text: normalizeForTts(entry.text),
+        voice: entry.voice,
+        speed: entry.speed,
+      })
+      if (!result.ok) {
+        process.stderr.write(
+          `telegram gateway: voice-out on-demand: synthesis failed reason=${result.reason}\n`,
+        )
+        await ctx
+          .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
+          .catch(() => {})
+        return
+      }
+      audio = result.audio
     }
+    // Rebind as const so the closure below narrows to non-null (TS doesn't
+    // narrow a captured `let` inside an arrow function).
+    const audioOut: Uint8Array = audio
     try {
       // Native voice note (NOT a document), quote-replying the button's
       // message.
@@ -22497,7 +22698,7 @@ bot.on('callback_query:data', async ctx => {
           bot.api.sendVoice(
             cbChatId,
             // allow-raw-bot-api: single native voice-note send for an on-demand Listen tap.
-            new InputFile(Buffer.from(result.audio)),
+            new InputFile(Buffer.from(audioOut)),
             {
               ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
               ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
@@ -22759,9 +22960,48 @@ bot.on('callback_query:data', async ctx => {
       action: naturalAction(details.tool_name, details.input_preview),
     })
 
-    // (3) Decide the persistence path. tryHostdDispatch returns
-    // "not-configured" when host_control is disabled or the per-agent
-    // socket is absent → legacy fallback.
+    // (3) Ack the tap IMMEDIATELY with an honest interim status. The
+    // durable persist below goes through hostd `config_propose_edit`
+    // (validate→approve→apply→reconcile), which can take 5-10 minutes on
+    // a busy host — the old code awaited only 60s and then reported
+    // "did NOT save" even when the edit later landed. Instead: ack now,
+    // run the persistence in a background continuation with a 12-min
+    // dispatch window, then edit the card with the REAL outcome.
+    // HTML-escape baseText — `ctx.callbackQuery.message.text` returns
+    // entities-stripped plain UTF-8, so raw `<`/`>`/`&` in the
+    // expanded permission card's `description` or `input_preview`
+    // (claude-generated tool descriptions routinely carry these)
+    // would break the HTML re-parse. PR #1158 review caught the same
+    // issue on the operator-event card.
+    const sourceMsg = ctx.callbackQuery?.message
+    const baseText = sourceMsg && 'text' in sourceMsg && sourceMsg.text
+      ? escapeHtmlForTg(sourceMsg.text)
+      : ''
+    const interimLabel =
+      `⏳ **Rule applied for this session** — ${escapeHtmlForTg(agentName)} can ${escapeHtmlForTg(grantPhrase)} ` +
+      `without asking for now; saving durably in background…`
+    // #1150 audit: route through finalizeCallback so the keyboard
+    // strips alongside the status-line edit. The in-flight verdict was
+    // ALREADY dispatched above (independently of this host round-trip)
+    // so the turn never blocked — finalizeCallback here only edits the
+    // card; no synthInbound (would double-fire the verdict).
+    await finalizeCallback(ctx, {
+      ackText: 'Rule applied for this session; saving durably in background…'.slice(0, 200),
+      newText: baseText ? `${baseText}\n\n${interimLabel}` : interimLabel,
+    })
+
+    // Background continuation: decide the persistence path.
+    // tryHostdDispatch returns "not-configured" when host_control is
+    // disabled or the per-agent socket is absent → legacy fallback.
+    // The whole body is wrapped in try/catch: a throw inside a void
+    // IIFE (scheduleGrantRestart's sync fs writes, richMessage, etc.)
+    // would surface as an unhandledRejection — which this gateway
+    // routes through shutdown(). Pre-background, those throws were
+    // contained by grammY's handler wrapper; keep that containment.
+    // Known accepted gap: if the gateway restarts mid-persist, the
+    // interim "saving durably in background…" card stays stale.
+    void (async () => {
+    try {
     let durable = false
     let legacy = false
     let failReason = ''
@@ -22803,8 +23043,10 @@ bot.on('callback_query:data', async ctx => {
           },
         }
         // config_propose_edit blocks on validate→approve→apply→reconcile,
-        // so allow ~60s (well past the default 5s).
-        const resp = await tryHostdDispatch(agentName, req, 60_000)
+        // which can legitimately take 5-10 minutes — allow 12 min. Safe
+        // to wait this long because we're in a background continuation:
+        // the tap was already acked and the verdict already dispatched.
+        const resp = await tryHostdDispatch(agentName, req, 720_000)
         if (resp === 'not-configured') {
           warnLegacySpawnIfHostdDisabled('always-allow')
           legacy = true
@@ -22888,23 +23130,6 @@ bot.on('callback_query:data', async ctx => {
         `always-allow: ${grantPhrase}`,
       ) !== "disabled"
     const liveSuffix = restartScheduled ? " — applying now (restarting to take effect)" : ""
-    const ackText = ok
-      ? (legacyNote
-          ? `✅ Saved. ${agentName} can now ${grantPhrase} without asking (legacy path).`
-          : `✅ Saved. ${agentName} can now ${grantPhrase} without asking.${liveSuffix}`)
-      : (editLockHint
-          ? `⚠️ Allowed for now — config edits are locked. Enable hostd.config_edit_enabled.`
-          : `⚠️ Allowed for now, but "always" did NOT save — it will ask again after restart. Check gateway log.`)
-    // HTML-escape baseText — `ctx.callbackQuery.message.text` returns
-    // entities-stripped plain UTF-8, so raw `<`/`>`/`&` in the
-    // expanded permission card's `description` or `input_preview`
-    // (claude-generated tool descriptions routinely carry these)
-    // would break the HTML re-parse. PR #1158 review caught the same
-    // issue on the operator-event card.
-    const sourceMsg = ctx.callbackQuery?.message
-    const baseText = sourceMsg && 'text' in sourceMsg && sourceMsg.text
-      ? escapeHtmlForTg(sourceMsg.text)
-      : ''
     const editLabel = ok
       ? (legacyNote
           ? `✅ **${escapeHtmlForTg(agentName)} can now ${escapeHtmlForTg(grantPhrase)}** without asking (legacy path); restart agent for full effect`
@@ -22914,15 +23139,30 @@ bot.on('callback_query:data', async ctx => {
       : (editLockHint
           ? `⚠️ **Allowed for now — "always" did NOT save.** Config edits are locked; enable \`hostd.config_edit_enabled\`.`
           : `⚠️ **Allowed for now — "always" did NOT save.** It will ask again after restart. Check gateway log.`)
-    // #1150 audit: route through finalizeCallback so the keyboard
-    // strips alongside the status-line edit. The in-flight verdict was
-    // ALREADY dispatched above (independently of this host round-trip)
-    // so the turn never blocked — finalizeCallback here only edits the
-    // card; no synthInbound (would double-fire the verdict).
-    await finalizeCallback(ctx, {
-      ackText: ackText.slice(0, 200),
-      newText: baseText ? `${baseText}\n\n${editLabel}` : editLabel,
+    // Edit the card with the REAL outcome. The keyboard was already
+    // stripped by the interim finalizeCallback ack above, and the
+    // callback query was already answered — this is a plain edit
+    // replacing the "saving durably in background…" interim line.
+    await ctx.editMessageText(
+      richMessage(baseText ? `${baseText}\n\n${editLabel}` : editLabel),
+      {
+        reply_markup: { inline_keyboard: [] },
+        link_preview_options: { is_disabled: true },
+      },
+    ).catch((err: unknown) => {
+      process.stderr.write(
+        `telegram gateway: always-allow outcome card edit failed: ${(err as Error).message} (request_id=${request_id})\n`,
+      )
     })
+    } catch (err) {
+      // Never let the background persist take the gateway down — an
+      // unhandledRejection here becomes shutdown(). Log and move on;
+      // the in-session rule was already applied at tap time.
+      process.stderr.write(
+        `telegram gateway: always-allow background persist threw: ${(err as Error).message} (request_id=${request_id})\n`,
+      )
+    }
+    })()
     return
   }