switchroom 0.18.7 → 0.18.8

package/telegram-plugin/gateway/gateway.ts

@@ -41,6 +41,7 @@ import {
   resolveInterruptMaxWaitMs,
   resolveSafeBoundaryEnabled,
 } from './interrupt-defer.js'
+import { shouldPostBusyAck, formatBusyAckText, BUSY_ACK_STEP_AGE_THRESHOLD_MS } from './busy-ack.js'
 import {
   resolveStickerSendArgs,
   resolveGifSendArgs,
@@ -62,6 +63,7 @@ import {
   buildListenKeyboard,
   mayInjectListenButton,
 } from '../voice-ondemand.js'
+import { sendVoiceReusingFileId } from '../voice-send.js'
 import {
   PreSynthQueue,
   sweepVoiceCacheDir,
@@ -175,6 +177,7 @@ import {
   isMessageTooLongError,
 } from '../retry-api-call.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
+import { floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
 import { buildAttachmentPath, assertInsideInbox } from '../attachment-path.js'
 import { logStreamingEvent } from '../streaming-metrics.js'
 import * as signalTracker from '../turn-signal-tracker.js'
@@ -375,10 +378,22 @@ import {
   MODEL_CALLBACK_PAGE_EXTERNAL,
   MODEL_CALLBACK_PAGE_MAIN,
   srFriendlyLabel,
+  expandSrAlias,
+  isSrModel,
   type ModelMenuDeps,
   type ModelCommandDeps,
   type ModelMenuReply,
 } from './model-command.js'
+import {
+  writeSessionModelFile,
+  readSessionModelFileRaw,
+  restoreSessionModelFileRaw,
+  clearSessionModelFile,
+  readConfiguredDefaultModel,
+  writeRelaunchModelIntent,
+  clearRelaunchModelIntent,
+  intentForRestartReason,
+} from './session-model-file.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
 import { resolveMainModel } from '../../src/agents/scaffold.js'
 import {
@@ -447,6 +462,10 @@ import {
   restartOrphanCardFinalizeText,
   type ActivityCardStoreFsSeam,
 } from './activity-card-store.js'
+import {
+  decideWorkerPinReaps,
+  WORKER_PIN_TTL_MS_DEFAULT,
+} from './worker-pin-reaper.js'
 import { driveEscalation } from './escalation-drive.js'
 import { shouldSuppressRepresent } from './represent-guard.js'
 import { shouldDeferEscalationForBridge } from './escalation-bridge-gate.js'
@@ -908,6 +927,16 @@ function triggerSelfRestart(
       )
       return false
     }
+    // Session-model stickiness (reference/rfcs/session-model-stickiness.md):
+    // boot default is REVERT, so every switchroom-managed bounce must stamp
+    // its intent BEFORE the SIGTERM is even scheduled (write-before-kill
+    // invariant — pinned by gateway-session-model-relaunch.test.ts). The
+    // per-reason table classifies recovery/model-switch bounces as "keep"
+    // and the deliberate inline restart button as "revert".
+    {
+      const smDir = resolveAgentDirFromEnv()
+      if (smDir) writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)
+    }
     process.stderr.write(
       `telegram gateway: restart-via-SIGTERM-PID1 agent=${targetAgent} reason=${reason} (docker)\n`,
     )
@@ -919,6 +948,10 @@ function triggerSelfRestart(
     return true
   }
   // Legacy systemd path.
+  if (targetAgent === selfAgent) {
+    const smDir = resolveAgentDirFromEnv()
+    if (smDir) writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)
+  }
   process.stderr.write(
     `telegram gateway: restart-via-systemctl agent=${targetAgent} reason=${reason}\n`,
   )
@@ -1874,7 +1907,22 @@ const activeReactionMsgIds = new Map<string, { chatId: string; messageId: number
 // by chatKey(chat_id, bufferedThread). Delete-on-answer: never a dangling
 // placeholder. Reaped on answer (executeReply/stream), on turn-flush, and
 // in purgeReactionTracking cleanup so an abnormal turn-end can't strand it.
-const queuedStatusMsgIds = new Map<string, { chatId: string; threadId: number; messageId: number }>()
+// #2995: threadId is null for DM cards — the mid-flight busy-ack extends
+// this lifecycle to DMs and same-topic surfaces (the original component-5
+// card was cross-topic only).
+const queuedStatusMsgIds = new Map<string, { chatId: string; threadId: number | null; messageId: number }>()
+// #2995 mid-flight busy-ack dedupe: statusKeys that already got a busy-ack
+// card during the CURRENT turn — at most one card per turn per chat/topic
+// even after the card itself is reaped. The ending turn's key is deleted in
+// purgeReactionTracking (per-key, not a global clear — a purge for topic A
+// must not reset topic B's dedupe).
+const busyAckPostedKeys = new Set<string>()
+// #2995 deferred re-check: a ping that arrives while the blocking step is
+// still YOUNG (< threshold) must not be silently forgotten — the step may
+// run for minutes more (the original #2995 silence). One timer per key,
+// armed for (threshold − stepAge); it re-evaluates live state when it
+// fires and is cancelled by purgeReactionTracking when the turn ends.
+const busyAckRecheckTimers = new Map<string, ReturnType<typeof setTimeout>>()
 // Reactions whose terminal 👍 is deferred because a background sub-agent
 // worker was still running when the parent's `turn_end` fired. Painting 👍
 // then would read as "done / nothing happening" while the worker keeps
@@ -2310,6 +2358,16 @@ const TOPIC_FRAMING_ENABLED =
 // → no placeholder (the 👀 ack reaction still fires). Delete-on-answer.
 const QUEUED_STATUS_UX_ENABLED =
   process.env.SWITCHROOM_QUEUED_STATUS_UX !== '0'
+// #2995 mid-flight busy ack. When a mid-turn inbound is buffered (or lands
+// as a steer) while the running turn sits inside ONE long tool call (step
+// age past the threshold in busy-ack.ts), post a silent deterministic
+// "⏳ Queued — currently inside `<tool>` …" card into the inbound's own
+// chat/topic — model-free, zero tokens. Reuses the queuedStatusMsgIds
+// edit/delete lifecycle (delete-on-answer, reap on abnormal turn-end),
+// extending it to DMs and same-topic surfaces. At most one card per turn
+// per chat/topic. Kill switch off (=0) → legacy silence (👀 only).
+const MIDFLIGHT_BUSY_ACK_ENABLED =
+  process.env.SWITCHROOM_MIDFLIGHT_BUSY_ACK !== '0'
 // Feed-reopen-after-ack. When a tool label arrives for a turn already
 // marked finalAnswerDelivered, the model is still WORKING — so the earlier
 // "final" reply was an interim ACK (an ack-first reply pings or runs ≥200
@@ -3472,7 +3530,9 @@ function postQueuedStatus(chatId: string, bufferedThread: number, inFlightThread
  */
 function promoteQueuedStatus(chatId: string, thread: number | undefined): void {
   if (!QUEUED_STATUS_UX_ENABLED) return
-  if (thread == null) return
+  // #2995: thread == null is a DM (or General-topic) card — the busy-ack
+  // extended this lifecycle to DMs, so promote those too (statusKey keys
+  // a null thread identically at post and promote time).
   const key = statusKey(chatId, thread)
   const entry = queuedStatusMsgIds.get(key)
   if (entry == null) return
@@ -3483,7 +3543,7 @@ function promoteQueuedStatus(chatId: string, thread: number | undefined): void {
   void swallowingApiCall(
     () =>
       bot.api.editMessageText(chatId, entry.messageId, '✍️ On it — replying now.', {}),
-    { chat_id: chatId, verb: 'queued-status.promote', threadId: thread },
+    { chat_id: chatId, verb: 'queued-status.promote', ...(thread != null ? { threadId: thread } : {}) },
   )
 }
 
@@ -3503,6 +3563,115 @@ function reapQueuedStatus(chatId: string, thread: number | undefined): void {
   )
 }
 
+/**
+ * #2995 — mid-flight busy ack (decision + dispatch). Called when a mid-turn
+ * inbound was buffered (`buffer-until-idle`) or delivered as a steer. If the
+ * running turn is sitting inside one LONG tool step (see busy-ack.ts for the
+ * threshold rationale), post a silent deterministic card into the inbound's
+ * own chat/topic naming the blocking activity — so a quick question asked
+ * behind a `--watch`-style blocking call doesn't read as ignored for
+ * minutes. Model-free, zero tokens. The card is stored in
+ * `queuedStatusMsgIds`, so it inherits the component-5 lifecycle: promoted
+ * ("On it") when the buffered turn starts, deleted when the answer lands or
+ * the turn ends. Dedupe is per turn per chat/topic via `busyAckPostedKeys`.
+ */
+function maybePostBusyAck(
+  gateDecision: 'buffer-until-idle' | 'steer',
+  chatId: string,
+  threadId: number | undefined,
+): void {
+  if (!MIDFLIGHT_BUSY_ACK_ENABLED) return
+  const key = statusKey(chatId, threadId)
+  const inFlight = currentTurn
+  const inFlightKey =
+    inFlight != null ? statusKey(inFlight.sessionChatId, inFlight.sessionThreadId) : key
+  const now = Date.now()
+  const step = silencePoke.longestInFlightTool(inFlightKey, now)
+  const midToolCall = toolFlightTracker.isMidToolCall()
+  const stepAgeMs = step?.durationMs ?? null
+  const alreadyAcked = queuedStatusMsgIds.has(key) || busyAckPostedKeys.has(key)
+  const fire = shouldPostBusyAck({ gateDecision, midToolCall, stepAgeMs, alreadyAcked })
+  if (!fire) {
+    // Deferred re-check: the ONLY miss reason we re-arm for is a step that
+    // is genuinely open but still young — it may run for minutes more, and
+    // a one-shot evaluation would re-create the original #2995 silence. Arm
+    // one timer for (threshold − stepAge); everything is re-read live at
+    // fire time, and the timer is pinned to THIS turn (turnId guard) plus
+    // cancelled outright by purgeReactionTracking when the turn ends.
+    if (
+      midToolCall &&
+      !alreadyAcked &&
+      stepAgeMs != null &&
+      stepAgeMs < BUSY_ACK_STEP_AGE_THRESHOLD_MS &&
+      !busyAckRecheckTimers.has(key)
+    ) {
+      const turnIdAtSchedule = inFlight?.turnId ?? null
+      const delayMs = BUSY_ACK_STEP_AGE_THRESHOLD_MS - stepAgeMs + 250
+      busyAckRecheckTimers.set(key, setTimeout(() => {
+        busyAckRecheckTimers.delete(key)
+        // The ping is only still waiting if the SAME turn is still running
+        // (a new/ended turn means the buffered inbound is being handled —
+        // a "Queued" card then would be a lie).
+        if (turnIdAtSchedule == null || currentTurn?.turnId !== turnIdAtSchedule) return
+        maybePostBusyAck(gateDecision, chatId, threadId)
+      }, delayMs))
+    }
+    return
+  }
+  const pendingRecheck = busyAckRecheckTimers.get(key)
+  if (pendingRecheck != null) {
+    clearTimeout(pendingRecheck)
+    busyAckRecheckTimers.delete(key)
+  }
+  busyAckPostedKeys.add(key)
+  const text = formatBusyAckText({
+    gateDecision,
+    toolName: step?.name ?? null,
+    toolLabel: step?.label ?? null,
+  })
+  process.stderr.write(
+    `telegram gateway: mid-flight busy ack chat=${chatId} thread=${threadId ?? '-'} ` +
+    `decision=${gateDecision} step=${step?.name ?? '-'} step_age_ms=${step?.durationMs ?? '-'}\n`,
+  )
+  postBusyAck(chatId, threadId, text)
+}
+
+/**
+ * #2995 — send the busy-ack card. Mirrors `postQueuedStatus` (idempotent
+ * key, silent send, post-race orphan cleanup) but is thread-OPTIONAL so it
+ * covers DMs and same-topic queues — the surfaces the cross-topic queued
+ * status deliberately suppressed. Shares `queuedStatusMsgIds`, so
+ * promote/reap clean it up exactly like the queued-status placeholder.
+ */
+function postBusyAck(chatId: string, threadId: number | undefined, text: string): void {
+  const key = statusKey(chatId, threadId)
+  if (queuedStatusMsgIds.has(key)) return
+  void (async () => {
+    const sent = await swallowingApiCall(
+      () =>
+        // Deterministic busy-ack placeholder, not the user's answer —
+        // silent by contract (no device ping for a status card).
+        bot.api.sendMessage(chatId, text, {
+          ...(threadId != null ? { message_thread_id: threadId } : {}),
+          disable_notification: true,
+        }),
+      { chat_id: chatId, verb: 'busy-ack.post', ...(threadId != null ? { threadId } : {}) },
+    )
+    const messageId = (sent as { message_id?: number } | undefined)?.message_id
+    if (typeof messageId !== 'number') return
+    // Re-check after the await (same race pattern as postQueuedStatus):
+    // if a placeholder landed for this key in the gap, delete this orphan.
+    if (queuedStatusMsgIds.has(key)) {
+      void swallowingApiCall(
+        () => bot.api.deleteMessage(chatId, messageId),
+        { chat_id: chatId, verb: 'busy-ack.post-race-cleanup', ...(threadId != null ? { threadId } : {}) },
+      )
+      return
+    }
+    queuedStatusMsgIds.set(key, { chatId, threadId: threadId ?? null, messageId })
+  })()
+}
+
 // Problem B — deferred safe-boundary interrupt.
 //
 // `toolFlightTracker` mirrors the session-event stream to know whether a
@@ -3836,6 +4005,17 @@ function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
     const pqThread = pqThreadPart === '_' || pqThreadPart === '' ? null : Number(pqThreadPart)
     reapQueuedStatus(pqChatId, Number.isFinite(pqThread) ? (pqThread as number) : undefined)
   }
+  // #2995 — reset the ending turn's OWN busy-ack dedupe + cancel its pending
+  // deferred re-check. Per-key, not a global clear: a purge for topic A must
+  // not reset topic B's dedupe or kill B's armed re-check. A buffered topic's
+  // entry clears when ITS turn eventually runs and ends (this same path), and
+  // the re-check timer self-guards on turnId anyway (defense-in-depth).
+  busyAckPostedKeys.delete(key)
+  const busyAckRecheck = busyAckRecheckTimers.get(key)
+  if (busyAckRecheck != null) {
+    clearTimeout(busyAckRecheck)
+    busyAckRecheckTimers.delete(key)
+  }
   // PR3b: clear the parallel-turns fleet-gate entry. Symmetric with
   // the markClaudeBusyForInbound on the delivery path. Safe no-op
   // when the key was never marked (synthetic purge from a sweep).
@@ -4887,8 +5067,16 @@ const typingWrapper = createTypingWrapper({
 // ─── Robust API call wrapper ──────────────────────────────────────────────
 // Extracted to telegram-plugin/retry-api-call.ts so it's unit-testable in
 // isolation; the gateway just composes the pure policy with its own logger.
+// #2923: the shared flood-wait marker. Every observed 429 retry_after window
+// is persisted here via onFloodWait, and both boot-card callsites consult the
+// SAME file to suppress a restart card while a per-bot flood ban is open (so a
+// restart doesn't post into the window and extend the ban). Falls back to a
+// no-op recorder when TELEGRAM_STATE_DIR is unset (dev/one-shot contexts).
+// STATE_DIR always resolves (env or a ~/.claude fallback), so this is live.
+const FLOOD_STATE_PATH = floodStatePath(STATE_DIR)
 const robustApiCall = createRetryApiCall({
   log: (line) => process.stderr.write(line),
+  onFloodWait: makeFloodWaitRecorder(FLOOD_STATE_PATH),
 })
 
 // Fire-and-forget wrapper for outbound surfaces that previously had
@@ -6804,6 +6992,10 @@ const statusPinState = new Map<string, PinState>()
 // owned pins without threading the chat id through every call site. Written on
 // every desired-pinned reconcile, cleared alongside the state on unpin.
 const statusPinChatIds = new Map<string, string>()
+// Companion registry: pinKey → wall-clock ms the claim was FIRST taken (a
+// re-pin of the same key keeps the original timestamp). Feeds the TTL gate of
+// the mid-session `wk:` pin reaper (#3001); cleared alongside the state.
+const statusPinPinnedAt = new Map<string, number>()
 
 // Durable snapshot of the pin claim set on the persistent per-agent volume
 // (STATE_DIR = /state/agent/telegram in prod). Closes the crash hole: the
@@ -6855,6 +7047,22 @@ const BANNER_PIN_KEY = 'banner:owner'
 // run → no-op). The boot-cleanup gate below is widened to cover this.
 const bannerPinPersistEnabled = !STATIC
 
+// `pin_message` MCP-tool pin registration (#3001). Tool pins ride the same
+// shared status-pins.json store under `tool:<chatId>:<messageId>` keys, but
+// with a TTL row (`expiresAt`): a tool pin is a deliberate agent action with
+// no "work finished" event, so a restart does NOT reset it — boot cleanup
+// keeps unexpired tool rows and only unpins them once the TTL lapses (the
+// backstop against agent-pinned messages accumulating forever). Independent
+// of PIN_STATUS_WHILE_WORKING (it gates the auto status pin, not the tool).
+const toolPinPersistEnabled = !STATIC
+// 7 days: generous — an agent-pinned message the operator still cares about
+// after a week has usually been re-pinned or acted on; anything older is the
+// stale-pin long tail this issue exists to clear. Override for tuning.
+const TOOL_PIN_TTL_MS = (() => {
+  const v = Number(process.env.SWITCHROOM_TOOL_PIN_TTL_MS)
+  return Number.isFinite(v) && v > 0 ? v : 7 * 24 * 60 * 60_000
+})()
+
 // Persist (or drop) the slot-banner's pin row into the shared store. Routes
 // through mutateStatusPinRow: a read-modify-write for ONLY the banner:owner key,
 // serialised on the store's per-path lock, so the live fg:/wk: status-pin rows
@@ -6905,9 +7113,9 @@ async function statusPinBootCleanup(): Promise<void> {
   // map-backed status pins (statusPinPersistEnabled) or the slot banner
   // (bannerPinPersistEnabled). A single cleanup drains ALL orphaned rows —
   // status pins AND banner alike — since they share status-pins.json.
-  if (!statusPinPersistEnabled && !bannerPinPersistEnabled) return
+  if (!statusPinPersistEnabled && !bannerPinPersistEnabled && !toolPinPersistEnabled) return
   const api = statusPinApi()
-  const { cleared, total } = await runStatusPinBootCleanup({
+  const { cleared, retained, kept, total } = await runStatusPinBootCleanup({
     path: STATUS_PIN_STORE_PATH,
     fs: statusPinStoreFs,
     unpin: (chatId, messageId) => api.unpinChatMessage(chatId, messageId),
@@ -6915,7 +7123,8 @@ async function statusPinBootCleanup(): Promise<void> {
   if (total > 0) {
     process.stderr.write(
       `telegram gateway: status-pin: cleared ${cleared}/${total} ` +
-        `orphaned pin(s) from a prior session\n`,
+        `orphaned pin(s) from a prior session ` +
+        `(retained ${retained} for retry, kept ${kept} unexpired tool pin(s))\n`,
     )
   }
 }
@@ -7016,6 +7225,25 @@ const MID_SESSION_CARD_REAPER_INTERVAL_MS = (() => {
   return Number.isFinite(v) && v > 0 ? v : 5 * 60_000 // 5 min
 })()
 
+// ─── Mid-session stale worker-pin reaper (#3001) ─────────────────────────────
+// The `wk:<agentId>` pin is normally dropped by the worker's completion
+// handler, but a missed onFinish (watcher crash / SDK SIGKILL / dropped JSONL
+// tail) used to leave the pin glued to the chat until the NEXT gateway boot.
+// This sweep (piggybacking on the mid-session reaper interval) unpins a
+// claimed worker pin when the registry says its worker is TERMINAL, or when
+// the pin has been held past a TTL. Pure decision in worker-pin-reaper.ts;
+// each reap executes through reconcileStatusPin so the in-memory claim and
+// the durable store row clear together.
+//
+// Kill switch: SWITCHROOM_WORKER_PIN_REAPER=0 disables (clean revert, mirrors
+// SWITCHROOM_MID_SESSION_CARD_REAPER). TTL overridable via env for tuning.
+const WORKER_PIN_REAPER_ENABLED =
+  process.env.SWITCHROOM_WORKER_PIN_REAPER !== '0'
+const WORKER_PIN_REAPER_TTL_MS = (() => {
+  const v = Number(process.env.SWITCHROOM_WORKER_PIN_REAPER_TTL_MS)
+  return Number.isFinite(v) && v > 0 ? v : WORKER_PIN_TTL_MS_DEFAULT // 6 h
+})()
+
 // Snapshot the turn_keys / topic keys owned by a live in-flight turn right now.
 function liveTurnKeySets(): { registryKeys: Set<string>; topicKeys: Set<string> } {
   const registryKeys = new Set<string>()
@@ -7080,15 +7308,27 @@ async function runMidSessionCardReaper(): Promise<void> {
               verb: 'activity-card.mid-session-reap-finalize',
             },
           ),
-        unpinCard: (record) =>
-          robustApiCall(
+        // #3001: route through reconcileStatusPin when the pin is a live
+        // in-memory claim, so the claim AND the durable status-pins.json row
+        // clear together (the raw-API unpin left both behind — the boot sweep
+        // then re-unpinned an already-unpinned message and the service-message
+        // handler kept a phantom claim). Falls back to the raw unpin when no
+        // claim is tracked (e.g. claim already dropped out-of-band).
+        unpinCard: async (record) => {
+          const pinKey = `fg:${record.turnKey}`
+          if (statusPinState.has(pinKey)) {
+            await reconcileStatusPin(pinKey, record.chatId, { pinned: false })
+            return true
+          }
+          return robustApiCall(
             () => lockedBot.api.unpinChatMessage(record.chatId, record.activityMessageId),
             {
               chat_id: record.chatId,
               ...(record.threadId != null ? { threadId: record.threadId } : {}),
               verb: 'activity-card.mid-session-reap-unpin',
             },
-          ),
+          )
+        },
       })
       if (total > 0) {
         process.stderr.write(
@@ -7102,6 +7342,55 @@ async function runMidSessionCardReaper(): Promise<void> {
       )
     }
   }
+
+  // 3) Reap stale `wk:` worker pins (#3001): a claimed worker pin whose worker
+  //    is terminal in the registry (missed onFinish) or whose claim outlived
+  //    the TTL. Executes through reconcileStatusPin so the in-memory claim and
+  //    the durable store row clear together.
+  if (WORKER_PIN_REAPER_ENABLED && PIN_STATUS_WHILE_WORKING) {
+    try {
+      const candidates = [...statusPinState.keys()]
+        .filter((k) => k.startsWith('wk:'))
+        .map((k) => ({
+          pinKey: k,
+          chatId: statusPinChatIds.get(k) ?? '',
+          // A missing timestamp (should not happen — set on every claim)
+          // degrades to "claimed just now": terminality can still reap it,
+          // the TTL gate never can. Conservative, never a spurious unpin.
+          pinnedAt: statusPinPinnedAt.get(k) ?? now,
+        }))
+      const reaps = decideWorkerPinReaps({
+        pins: candidates,
+        statusOf: (agentId) => {
+          if (turnsDb == null) return 'unknown'
+          try {
+            const row = getSubagentByJsonlId(turnsDb, agentId)
+            if (row == null) return 'unknown'
+            if (row.status === 'completed' || row.status === 'failed') return 'terminal'
+            // A live 'running' row exempts the pin from the TTL (no churn on
+            // healthy long workers); 'stalled' degrades to 'unknown' → TTL.
+            if (row.status === 'running') return 'running'
+            return 'unknown'
+          } catch {
+            return 'unknown' // DB hiccup degrades to "keep until TTL"
+          }
+        },
+        ttlMs: WORKER_PIN_REAPER_TTL_MS,
+        now,
+      })
+      for (const reap of reaps) {
+        process.stderr.write(
+          `telegram gateway: worker-pin reaper unpinning ${reap.pinKey} ` +
+            `(chat=${reap.chatId} reason=${reap.reason})\n`,
+        )
+        await reconcileStatusPin(reap.pinKey, reap.chatId, { pinned: false })
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: worker-pin reaper error: ${(err as Error).message}\n`,
+      )
+    }
+  }
 }
 
 const midSessionCardReaper = setInterval(() => {
@@ -7189,9 +7478,11 @@ async function reconcileStatusPinInner(
     if (next == null) {
       statusPinState.delete(pinKey)
       statusPinChatIds.delete(pinKey)
+      statusPinPinnedAt.delete(pinKey)
     } else {
       statusPinState.set(pinKey, next)
       statusPinChatIds.set(pinKey, chatId)
+      if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
     }
     return
   }
@@ -7211,9 +7502,11 @@ async function reconcileStatusPinInner(
   if (next == null) {
     statusPinState.delete(pinKey)
     statusPinChatIds.delete(pinKey)
+    statusPinPinnedAt.delete(pinKey)
   } else {
     statusPinState.set(pinKey, next)
     statusPinChatIds.set(pinKey, chatId)
+    if (!statusPinPinnedAt.has(pinKey)) statusPinPinnedAt.set(pinKey, Date.now())
   }
 }
 
@@ -7256,7 +7549,7 @@ async function unpinAllStatusPins(): Promise<void> {
     if (st == null) continue
     // Recover the chat id from the state map's companion key registry.
     const chatId = statusPinChatIds.get(key)
-    if (chatId == null) { statusPinState.delete(key); continue }
+    if (chatId == null) { statusPinState.delete(key); statusPinPinnedAt.delete(key); continue }
     await reconcileStatusPin(key, chatId, { pinned: false })
   }
 }
@@ -8861,6 +9154,7 @@ const ipcServer: IpcServer = createIpcServer({
             dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
             configSnapshotPath: join(resolvedAgentDirForCard, '.config-snapshot.json'),
             bootCardStatePath: join(resolvedAgentDirForCard, '.boot-card-msgid.json'),
+            floodStatePath: FLOOD_STATE_PATH,
             ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
           }, ackMsgId).then(handle => {
             activeBootCard = handle
@@ -10455,6 +10749,15 @@ const voicePreSynthQueue = new PreSynthQueue({
     }
     const filePath = writeVoiceCacheFile(VOICE_CACHE_DIR, job.token, result.audio)
     voiceOnDemandCache.setFilePath(job.token, filePath)
+    // TODO(first-tap-instant): pre-mint the Telegram file_id here so even the
+    // FIRST user tap sends by id (no upload). Would require uploading this ogg
+    // once to the bot's OWN hidden storage/log chat and calling
+    // voiceOnDemandCache.setTelegramFileId(job.token, msg.voice.file_id).
+    // Deferred: no storage-chat id exists in config/env today, and the product
+    // invariant forbids sending audio to the USER's chat without a tap — so a
+    // dedicated bot-storage chat id must be added first. Until then, the first
+    // tap uploads (via the disk fast-path) and captures the id for reuse; only
+    // the second+ taps are instant.
     process.stderr.write(
       `telegram gateway: voice-presynth: cached ${result.audio.length} bytes at ${filePath} ` +
         `(${result.durationMs}ms, backlog=${voicePreSynthQueue.size})\n`,
@@ -13262,10 +13565,26 @@ async function executePinMessage(args: Record<string, unknown>): Promise<unknown
   // errors are retried. THREAD_NOT_FOUND on a stale topic surfaces to the
   // agent as a tool-error — pinning a vanished message is genuinely a
   // failure the agent should see.
+  const pinMsgId = Number(args.message_id)
   await robustApiCall(
-    () => lockedBot.api.pinChatMessage(pinChatId, Number(args.message_id)),
+    () => lockedBot.api.pinChatMessage(pinChatId, pinMsgId),
     { chat_id: pinChatId, verb: 'pin_message' },
   )
+  // #3001: register the tool pin in the shared status-pin store under a
+  // `tool:` key so it is no longer fire-and-forget. Unlike work-scoped
+  // fg:/wk: rows a tool pin has no "work finished" event, so a restart does
+  // NOT reset it — boot cleanup keeps the row until its TTL, then unpins the
+  // (likely long-forgotten) message. Best-effort fire-and-forget: a store
+  // failure must never fail the tool call the pin already landed for.
+  if (toolPinPersistEnabled) {
+    const toolPinKey = `tool:${pinChatId}:${pinMsgId}`
+    void mutateStatusPinRow(STATUS_PIN_STORE_PATH, statusPinStoreFs, toolPinKey, {
+      pinKey: toolPinKey,
+      chatId: pinChatId,
+      messageId: pinMsgId,
+      expiresAt: Date.now() + TOOL_PIN_TTL_MS,
+    })
+  }
   return { content: [{ type: 'text', text: `pinned message ${args.message_id}` }] }
 }
 
@@ -17778,13 +18097,23 @@ async function handleInbound(
     // know they're queued. Suppressed for DMs (no topics) and same-topic
     // queues (the in-flight turn's own card already covers them).
     const inFlightThread = currentTurn?.sessionThreadId
-    if (
+    const crossTopicQueuedCard =
       QUEUED_STATUS_UX_ENABLED &&
       !isDmChatId(chat_id) &&
       messageThreadId != null &&
       messageThreadId !== inFlightThread
-    ) {
+    if (crossTopicQueuedCard) {
       postQueuedStatus(chat_id, messageThreadId, inFlightThread)
+    } else {
+      // #2995 mid-flight busy ack — ONLY the surfaces the cross-topic card
+      // suppresses (DMs, same-topic). Mutually exclusive with
+      // postQueuedStatus above: both record into queuedStatusMsgIds only
+      // AFTER their sendMessage awaits resolve, so calling both here would
+      // race past each other's has(key) check and double-card the topic.
+      // When the running turn is inside one LONG tool step, a buffered
+      // quick question would otherwise wait minutes with only a 👀; post a
+      // silent deterministic "Queued — currently inside <tool>" card.
+      maybePostBusyAck('buffer-until-idle', chat_id, messageThreadId ?? undefined)
     }
     return
   }
@@ -17830,6 +18159,15 @@ async function handleInbound(
 
   const delivered = ipcServer.sendToAgent(selfAgent, inboundMsg)
   if (delivered) {
+    // #2995 — a steer delivered mid-turn while the turn is stuck inside one
+    // long tool step gets a deterministic ack (worded as a steer, not
+    // "Queued" — classification visibility): the model can't narrate the
+    // steer until the blocking call returns. Posted only AFTER the bridge
+    // dispatch succeeded — a "Steer noted" card for a send that missed
+    // (bridge offline → buffered/dropped below) would be untrue.
+    if (isSteering) {
+      maybePostBusyAck('steer', chat_id, messageThreadId ?? undefined)
+    }
     // Reuse the key reserved synchronously above (#2917) when present, else
     // mark now — markClaudeBusyForInbound is idempotent (lockstep re-stamp),
     // so a re-mark is safe and returns the same chat key.
@@ -19527,6 +19865,15 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
         })
       }
       stampUserRestartReason(reason)
+      // Model-switch restarts are switchroom-managed relaunches: the session
+      // override (written by the caller before this dispatch) must survive
+      // the bounce, so stamp keep-intent BEFORE dispatch (boot default is
+      // revert). hostd shells through `switchroom agent restart`, which
+      // deliberately writes no intent of its own.
+      {
+        const smDir = resolveAgentDirFromEnv()
+        if (smDir) writeRelaunchModelIntent(smDir, 'keep', reason)
+      }
       await sweepBeforeSelfRestart()
       const hostdResp = await tryHostdDispatch(name, {
         v: 1,
@@ -19546,43 +19893,58 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
         )
         return
       }
-      // hostd is configured but returned an error/denied result.
+      // hostd is configured but returned an error/denied result. No restart
+      // is coming, so the keep-intent stamped above must not linger — a
+      // crash within its 10-min freshness window would wrongly KEEP.
       if (hostdResp.result !== 'started' && hostdResp.result !== 'completed') {
         clearRestartMarker()
+        {
+          const smDir = resolveAgentDirFromEnv()
+          if (smDir) clearRelaunchModelIntent(smDir)
+        }
         throw new Error(
           `hostd restart failed (result=${hostdResp.result}): ${hostdResp.error ?? '(no details)'}`,
         )
       }
     },
     /**
-     * Session-only switch TO an sr-* (LiteLLM/OpenRouter) model. claude's
-     * native `/model` picker rejects unknown sr-* ids, so we can't inject.
-     * Write the token to the `.session-model-override` carrier file (start.sh
-     * consumes it on the next boot and launches `claude --model <token>`), set
-     * the in-memory session-model so /status stays honest across the restart
-     * window, then run the SAME restart dispatch as scheduleRestart above.
+     * Switch TO a model that needs a relaunch (sr-* LiteLLM/OpenRouter ids,
+     * which claude's native `/model` picker rejects, and the sr-to-claude
+     * direction). Write the DURABLE `.session-model` override (start.sh
+     * applies it on every keep-relaunch boot and launches `claude --model
+     * <token>`), set the in-memory session-model so /status stays honest
+     * across the restart window, then run the SAME restart dispatch as
+     * scheduleRestart above — which stamps the keep-intent this boot needs.
      */
     scheduleModelRelaunch: async (model: string, reason: string) => {
       const agentDir = resolveAgentDirFromEnv()
-      if (!agentDir) throw new Error('agent dir unresolvable — cannot write session-model carrier')
-      // Carrier: single line, token + newline, no quoting (start.sh strips
-      // whitespace and shape-gates). One-shot — consumed on the next boot.
+      if (!agentDir) throw new Error('agent dir unresolvable — cannot write session-model file')
       const prevOverride = sessionModelSource.getOverride()
-      writeFileSync(join(agentDir, '.session-model-override'), `${model}\n`, 'utf8')
+      const prevFileRaw = readSessionModelFileRaw(agentDir)
+      writeSessionModelFile(
+        agentDir,
+        model,
+        readConfiguredDefaultModel(agentDir) ??
+          resolveMainModel(deps.getConfiguredModel() ?? undefined),
+      )
       sessionModelSource.setOverride(model)
       try {
         await deps.scheduleRestart(reason)
       } catch (err) {
-        const carrierPath = join(agentDir, '.session-model-override')
-        // A restart already in flight OWNS the carrier we just wrote — it will
-        // consume our token at boot, so the switch is queued, not lost: keep the
-        // carrier + override and let the caller tell the operator "~15s". Any
-        // OTHER dispatch failure means no restart is coming, so roll BOTH back —
-        // a lingering carrier/override would lie to /status and mis-launch the
-        // NEXT ordinary restart.
+        // A restart already in flight OWNS the override we just wrote — its
+        // boot (stamped keep by the in-flight path's own intent, last-writer-
+        // wins) will apply our token, so the switch is queued, not lost: keep
+        // the file + override and let the caller tell the operator "~15s".
+        // Any OTHER dispatch failure means no restart is coming, so roll BOTH
+        // back — a lingering file/override would lie to /status and
+        // mis-launch the NEXT relaunch. The keep-intent goes with them
+        // (belt-and-braces: scheduleRestart's failure branch clears it too):
+        // a fresh keep on disk with no restart coming would wrongly KEEP
+        // across a crash inside its 10-min window.
         if ((err as { code?: string })?.code !== 'restart_in_flight') {
-          try { rmSync(carrierPath, { force: true }) } catch { /* best-effort */ }
+          restoreSessionModelFileRaw(agentDir, prevFileRaw)
           sessionModelSource.setOverride(prevOverride)
+          clearRelaunchModelIntent(agentDir)
         }
         throw err
       }
@@ -19620,10 +19982,44 @@ bot.command('model', async ctx => {
   // set on the confirmed inject path; the sr-*/relaunch paths already set the
   // override inside scheduleModelRelaunch, and an unverified switch carries no
   // selectedModel so /status is never lied to.
-  if (reply.selectedModel) {
+  const requested = parsed.kind === 'set' ? expandSrAlias(parsed.model) : null
+  let persistWarning = ''
+  if (requested?.toLowerCase() === 'default') {
+    // `/model default` clears the sticky file even WITHOUT a positive
+    // confirmation: claude's arg-form switch can be silent, and a surviving
+    // sticky file would resurrect the old model on the next keep-relaunch.
+    // Clearing is idempotent; the in-memory override change stays gated on a
+    // confirmed switch so an unverified inject never lies to /status.
+    const smDir = resolveAgentDirFromEnv()
+    if (smDir) clearSessionModelFile(smDir)
+    if (reply.selectedModel) sessionModelSource.setOverride(null)
+  } else if (reply.selectedModel) {
     sessionModelSource.setOverride(reply.selectedModel)
+    // Durable stickiness: persist the REQUESTED canonical token — never
+    // the confirmation's display label ("Opus 4.8"), which `claude
+    // --model` would reject on the next boot. sr-* switches never reach
+    // here (they go through scheduleModelRelaunch, which persists).
+    const smDir = resolveAgentDirFromEnv()
+    if (smDir && requested && isValidModelArg(requested) && !isSrModel(requested)) {
+      try {
+        writeSessionModelFile(
+          smDir,
+          requested,
+          readConfiguredDefaultModel(smDir) ??
+            resolveMainModel(deps.getConfiguredModel() ?? undefined),
+        )
+      } catch (err) {
+        // The reply body already promises stickiness — never let the promise
+        // and the disk disagree silently.
+        persistWarning =
+          '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
+        process.stderr.write(
+          `telegram gateway: session-model persist failed (typed /model): ${(err as Error)?.message ?? String(err)}\n`,
+        )
+      }
+    }
   }
-  await switchroomReply(ctx, reply.text, { html: reply.html })
+  await switchroomReply(ctx, reply.text + persistWarning, { html: reply.html })
 })
 
 // `/effort` — show or switch the reasoning effort for the live session.
@@ -19734,6 +20130,13 @@ bot.command('restart', async ctx => {
     // greeting card shows "Restarted  user: /restart from chat" instead
     // of whatever reason the downstream CLI would default to.
     stampUserRestartReason('user: /restart from chat')
+    // /restart is a DELIBERATE restart: the session model reverts to the
+    // configured default. Absence of intent would revert anyway (boot
+    // default) — the explicit stamp is reason-honesty for the boot notice.
+    {
+      const smDir = resolveAgentDirFromEnv()
+      if (smDir) writeRelaunchModelIntent(smDir, 'revert', 'user: /restart from chat')
+    }
     await sweepBeforeSelfRestart()
     const hostdResp = await tryHostdDispatch(getMyAgentName(), {
       v: 1,
@@ -19892,6 +20295,12 @@ async function handleNewCommand(ctx: Context): Promise<void> {
   // Stamp user attribution so the next greeting shows "Restarted  user:
   // /new" / "user: /reset" rather than the downstream CLI default.
   stampUserRestartReason(`user: /${kind} from chat`)
+  // /new and /reset start a fresh CONVERSATION, not a fresh model choice:
+  // the sticky session-model override KEEPS across them (contract row 7).
+  // Boot default is revert, so the keep-intent must land before dispatch.
+  if (agentDir != null) {
+    writeRelaunchModelIntent(agentDir, 'keep', `user: /${kind} from chat`)
+  }
   await sweepBeforeSelfRestart()
   const hostdResp = await tryHostdDispatch(getMyAgentName(), {
     v: 1,
@@ -24727,7 +25136,7 @@ bot.on('callback_query:data', async ctx => {
     // sr-* TARGET tap: switch TO a non-Claude (LiteLLM/OpenRouter) model.
     // Parity with the text `/model sr-*` path — claude's native picker rejects
     // unknown sr-* ids, so an in-place inject can't set them. Carry the token
-    // across a graceful restart (the `.session-model-override` carrier) and
+    // across a graceful restart (the durable `.session-model` override) and
     // relaunch `claude --model sr-*`. Session-only; reverts to the configured
     // default on the next restart. The sr-* → Claude direction is handled below
     // via the SELECT/alias outcome + isSrToClaudeTransition.
@@ -24763,10 +25172,35 @@ bot.on('callback_query:data', async ctx => {
       const prevSessionModel = sessionModelSource.getOverride()
       const outcome = await handleModelMenuCallback(data, modelDeps)
       // Record a successful session switch so /status reflects what's
-      // actually running. In-memory only → clears when the gateway (and thus
-      // claude's session) restarts, exactly matching the session-only scope.
+      // actually running, and persist the STICKY override
+      // (reference/rfcs/session-model-stickiness.md): the canonical token
+      // (never the display label) goes to the durable `.session-model`; a
+      // confirmed "Default (recommended)" selection clears it instead.
       if (outcome.selectedModel) {
         sessionModelSource.setOverride(outcome.selectedModel)
+        const smDir = resolveAgentDirFromEnv()
+        if (smDir && outcome.selectedModelToken) {
+          try {
+            writeSessionModelFile(
+              smDir,
+              outcome.selectedModelToken,
+              readConfiguredDefaultModel(smDir) ??
+                resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
+            )
+          } catch (err) {
+            // The banner already promises stickiness — surface the failure on
+            // the same card instead of only stderr.
+            outcome.reply.text +=
+              '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
+            process.stderr.write(
+              `telegram gateway: session-model persist failed (menu): ${(err as Error)?.message ?? String(err)}\n`,
+            )
+          }
+        }
+      }
+      if (outcome.clearedDefault) {
+        const smDir = resolveAgentDirFromEnv()
+        if (smDir) clearSessionModelFile(smDir)
       }
       // toastOnly: leave the menu untouched — but only if we haven't already
       // cleared its buttons with the interim sr-* edit. If we have, fall
@@ -24789,22 +25223,33 @@ bot.on('callback_query:data', async ctx => {
           )
           .catch(() => {})
         // Carry the requested Claude model across the restart via the SAME
-        // `.session-model-override` carrier a Claude → sr-* switch uses — otherwise
-        // boot launches the CONFIGURED default and the tapped model is silently
-        // dropped. `selectedModelToken` is a real `claude --model` token (alias or
-        // full claude-* id); a "Default"-row tap yields no token → boot the
-        // configured default (correct). start.sh's LiteLLM-down guard only drops
-        // sr-* overrides, so a Claude token is never dropped.
+        // durable `.session-model` override a Claude → sr-* switch uses —
+        // otherwise boot launches the CONFIGURED default and the tapped model
+        // is silently dropped. `selectedModelToken` is a real `claude --model`
+        // token (alias or full claude-* id); a "Default"-row tap yields no
+        // token → clear the override and boot the configured default
+        // (correct). start.sh's LiteLLM-down guard only skips sr-* overrides,
+        // so a Claude token is never dropped.
         {
           const agentDir = resolveAgentDirFromEnv()
           const token = outcome.selectedModelToken
           if (agentDir && token) {
             try {
-              writeFileSync(join(agentDir, '.session-model-override'), `${token}\n`, 'utf8')
+              writeSessionModelFile(
+                agentDir,
+                token,
+                readConfiguredDefaultModel(agentDir) ??
+                  resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
+              )
               sessionModelSource.setOverride(token)
             } catch (e) {
-              process.stderr.write(`telegram gateway: sr-to-claude carrier write failed: ${(e as Error)?.message ?? String(e)}\n`)
+              process.stderr.write(`telegram gateway: sr-to-claude session-model write failed: ${(e as Error)?.message ?? String(e)}\n`)
             }
+          } else if (agentDir) {
+            // Default-row tap while on sr-*: the restart must land on the
+            // configured default — a stale sticky override would resurrect
+            // the old model on the next keep-relaunch.
+            clearSessionModelFile(agentDir)
           }
         }
         // Write the restart marker so the post-restart boot card edits into this chat.
@@ -25165,22 +25610,36 @@ bot.on('callback_query:data', async ctx => {
       }
       return undefined
     })()
-    // #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
+    const tok = token as string
+    const sendOpts = {
+      ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
+      ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
+    } as never
+    const sendVerbOpts = {
+      chat_id: cbChatId,
+      verb: 'voice-ondemand.sendVoice',
+      ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
+    }
+
+    // #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
+    // crash, pre-feature entry, kill-switched gateway) falls back transparently
+    // to the lazy synth path. Only invoked when there's no reusable file_id (or
+    // a stored id was rejected as stale) — see sendVoiceReusingFileId.
+    const loadAudio = async (): Promise<Uint8Array | null> => {
+      let audio: Uint8Array | null = null
+      if (entry.filePath != null) {
+        try {
+          audio = readFileSync(entry.filePath)
+        } catch {
+          audio = null // swept/missing — lazy fallback
+        }
+      }
+      if (audio != null) {
+        await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+        return audio
       }
-    }
-    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
@@ -25190,7 +25649,7 @@ bot.on('callback_query:data', async ctx => {
         await ctx
           .answerCallbackQuery({ text: 'Voice sidecar unavailable — try again later.' })
           .catch(() => {})
-        return
+        return null
       }
       const result = await synthesizeViaSidecar({
         token: sidecarToken,
@@ -25209,33 +25668,52 @@ bot.on('callback_query:data', async ctx => {
         await ctx
           .answerCallbackQuery({ text: `Voice failed: ${result.reason}` })
           .catch(() => {})
-        return
+        return null
+      }
+      return result.audio
+    }
+
+    // Fast path: if we already captured a reusable file_id, ack instantly and
+    // send BY the id — no disk read, no re-upload. First tap (no id yet) and a
+    // stale-id fallback both go through loadAudio + InputFile below and refresh
+    // the stored id from the returned message.
+    if (entry.telegramFileId != null) {
+      await ctx.answerCallbackQuery({ text: '🔊' }).catch(() => {})
+    }
+    const sendResult = await sendVoiceReusingFileId({
+      fileId: entry.telegramFileId ?? null,
+      sendByFileId: (fid) =>
+        robustApiCall(
+          // allow-raw-bot-api: reuse Telegram's file_id — no re-upload.
+          () => bot.api.sendVoice(cbChatId, fid, sendOpts),
+          sendVerbOpts,
+        ),
+      loadAudio,
+      sendByUpload: (audioOut) =>
+        robustApiCall(
+          // allow-raw-bot-api: single native voice-note send for an on-demand Listen tap.
+          () => bot.api.sendVoice(cbChatId, new InputFile(Buffer.from(audioOut)), sendOpts),
+          sendVerbOpts,
+        ),
+      onFileId: (fid) => voiceOnDemandCache.setTelegramFileId(tok, fid),
+      log: (line) => process.stderr.write(line),
+    })
+
+    if (!sendResult.ok) {
+      // no-audio already surfaced a toast inside loadAudio; send-failed is
+      // logged non-fatally — the '🔊 Listen' keyboard is left intact so the
+      // user can retry (only a successful send strips it below).
+      if (sendResult.reason === 'send-failed') {
+        const err = sendResult.error
+        const msg = err instanceof Error ? err.message : String(err)
+        process.stderr.write(
+          `telegram gateway: voice-out on-demand: sendVoice failed (non-fatal): ${msg}\n`,
+        )
       }
-      audio = result.audio
+      return
     }
-    // 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.
-      await robustApiCall(
-        () =>
-          bot.api.sendVoice(
-            cbChatId,
-            // allow-raw-bot-api: single native voice-note send for an on-demand Listen tap.
-            new InputFile(Buffer.from(audioOut)),
-            {
-              ...(cbMessageId != null ? { reply_parameters: { message_id: cbMessageId } } : {}),
-              ...(cbThreadId != null ? { message_thread_id: cbThreadId } : {}),
-            } as never,
-          ),
-        {
-          chat_id: cbChatId,
-          verb: 'voice-ondemand.sendVoice',
-          ...(cbThreadId != null ? { threadId: cbThreadId } : {}),
-        },
-      )
       // Single-use on SUCCESS: strip the '🔊 Listen' keyboard so the button
       // can't be re-tapped now that the audio has been delivered. Mirrors the
       // agent-button single_use strip (keyboardIsSingleUse) house style.
@@ -25259,7 +25737,7 @@ bot.on('callback_query:data', async ctx => {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       process.stderr.write(
-        `telegram gateway: voice-out on-demand: sendVoice failed (non-fatal): ${msg}\n`,
+        `telegram gateway: voice-out on-demand: strip-listen-keyboard failed (non-fatal): ${msg}\n`,
       )
     }
     return
@@ -27809,6 +28287,7 @@ void (async () => {
                       dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
                       configSnapshotPath: join(resolvedAgentDirForBootCard, '.config-snapshot.json'),
                       bootCardStatePath: join(resolvedAgentDirForBootCard, '.boot-card-msgid.json'),
+                      floodStatePath: FLOOD_STATE_PATH,
                       ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
                     }, ackMsgId)
                     activeBootCard = handle