switchroom 0.18.6 → 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,
@@ -126,6 +128,14 @@ import {
 } from './permission-timeout.js'
 import { renderVaultRequestAccessCard } from './vault-request-access-card.js'
 import { createPermissionCardStore, type PersistedPermCard } from './permission-card-store.js'
+import { createPendingCardStore, type PersistedApprovalCard } from './pending-card-store.js'
+import {
+  buildVaultAccessTimeoutInbound,
+  buildVaultSaveTimeoutInbound,
+  buildSecretRequestTimeoutInbound,
+  buildMentalModelProposeTimeoutInbound,
+} from './approval-timeout-inbound-builders.js'
+import { expirePendingCard, sweepExpiredEntries } from './pending-card-expiry.js'
 import {
   isPermissionRearmEnabled,
   permissionRearmGraceMs,
@@ -134,6 +144,11 @@ import {
   distinctRequestIds,
 } from './permission-rearm.js'
 import { createMissedApprovalsStore, type MissedApproval } from './missed-approvals-store.js'
+import {
+  createAlwaysAllowPersistQueue,
+  drainAlwaysAllowPersistQueue,
+  type AlwaysAllowDrainDeps,
+} from './always-allow-persist-queue.js'
 import {
   renderMissedApprovalsDigest,
   missedApprovalsKeyboard,
@@ -143,6 +158,8 @@ import {
 import { pickRecoveredPermissionOrigin } from './permission-card-origin.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
 import { appendActivityLabel, clipNarrative, renderActivityFeedWithNested, formatStepSuffix, type SessionActivityHeader } from '../tool-activity-summary.js'
+import { formatModelLabel } from '../model-label.js'
+import { createSessionModelSource } from './session-model-source.js'
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { REPLY_TOOLS, isDraftOfReply } from '../narrative-dedup.js'
 import { toolLabel } from '../tool-labels.js'
@@ -160,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'
@@ -360,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 {
@@ -396,7 +426,7 @@ import {
   _resetHostdEnabledCache,
 } from './hostd-dispatch.js'
 import { formatUpdateStatusLine } from './update-status-line.js'
-import type { HostdRequest } from '../../src/host-control/protocol.js'
+import type { HostdRequest, HostdResponse } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 import { startWebhookIngestServer } from './webhook-ingest-server.js'
@@ -432,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'
@@ -530,6 +564,7 @@ import type {
   InjectInboundMessage,
   SendOutboundMessage,
   QuotaWallDetectedMessage,
+  QueryPendingPermissionMessage,
   PostSkillProposalMessage,
   PermissionEvent,
   RolloutStatusPostMessage,
@@ -561,6 +596,7 @@ import {
   clearCleanShutdownMarker,
   shouldSuppressRecoveryBanner,
   shouldSuppressBootResume,
+  parseBootResumeMode,
   resolveShutdownMarker,
   DEFAULT_MAX_AGE_MS as CLEAN_SHUTDOWN_MAX_AGE_MS,
 } from './clean-shutdown-marker.js'
@@ -677,9 +713,11 @@ import {
 import {
   buildResumeInterruptedInbound,
   buildResumeWatchdogReportInbound,
-  selectResumeBuilder,
+  buildResumeDeferredReportInbound,
+  decideBootResumeKind,
 } from './resume-inbound-builder.js'
-import { applySubagentsSchema, getSubagentByJsonlId, resolveSubagentOriginTurnKey } from '../registry/subagents-schema.js'
+import { applySubagentsSchema, getSubagentByJsonlId, resolveSubagentOriginTurnKey, listNonTerminalSubagentsForTurn } from '../registry/subagents-schema.js'
+import type { InterruptedSubagent } from './resume-inbound-builder.js'
 import { resolveWorkerFeedDispatch, type WorkerFeedDispatch } from './worker-feed-dispatch.js'
 import {
   resolveSubagentStatusSurface,
@@ -717,12 +755,127 @@ process.on('beforeExit', () => {
 // ─── Env + state dir ──────────────────────────────────────────────────────
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const permCardStore = createPermissionCardStore(STATE_DIR)
+// Durable store for the four AGENT-INITIATED approval-card families
+// (vault_request_access / vault_request_save / request_secret /
+// mental_model_propose). Persists card METADATA only — never any secret value
+// (see pending-card-store.ts secrets-hygiene note). Restored at boot so a
+// post-restart tap on a still-valid card works like a pre-restart tap, and
+// swept in the pendingStateReaper so an unanswered card wakes the parked agent
+// on TTL instead of leaving it parked forever.
+const pendingCardStore = createPendingCardStore(STATE_DIR)
 // #2862 — missed-approvals re-offer. Persisted list of approvals that
 // TTL-expired while the operator was away; a digest card is posted on the
 // operator's next activity. Kill switch: SWITCHROOM_MISSED_APPROVAL_REOFFER=0.
 const missedApprovalsStore = createMissedApprovalsStore(STATE_DIR)
 const MISSED_APPROVAL_REOFFER_ENABLED =
   process.env.SWITCHROOM_MISSED_APPROVAL_REOFFER !== '0'
+// #2973 pt.2 — durable retry queue for "🔁 Always allow" persists that
+// fail for a retryable reason (stale config view, rate limit, transient
+// hostd error). Drained at boot (below) and on a periodic timer so a
+// gateway restart mid-persist never loses the retry.
+const alwaysAllowPersistQueue = createAlwaysAllowPersistQueue(STATE_DIR)
+
+/** Read a hostd `error_envelope`'s structured `retry_after` fix (if
+ * present) as a millisecond delay from now. Returns undefined for any
+ * other fix kind / missing envelope / unparsable timestamp — callers
+ * fall back to plain exponential backoff in that case. */
+function extractRetryAfterMs(resp: HostdResponse): number | undefined {
+  const fix = resp.error_envelope?.fix
+  if (fix == null || fix.kind !== 'retry_after') return undefined
+  const at = Date.parse(fix.retry_at)
+  if (Number.isNaN(at)) return undefined
+  return Math.max(0, at - Date.now())
+}
+
+/**
+ * Build a FRESH dependency set for `drainAlwaysAllowPersistQueue` — a new
+ * factory call per drain pass, not a cached singleton, so every attempt
+ * re-reads config from disk (the #2973 stale-container-side-view failure
+ * class is fixed by never reusing a snapshot across retries).
+ */
+function alwaysAllowDrainDeps(): AlwaysAllowDrainDeps {
+  return {
+    readConfigText: () => {
+      const cfgPath = process.env.SWITCHROOM_CONFIG ?? SWITCHROOM_CONFIG ?? findSwitchroomConfigFile()
+      return readFileSync(cfgPath, 'utf8')
+    },
+    resolveAllowList: (_configText, agentName) => {
+      const cfg = loadSwitchroomConfig()
+      const rawAgent = cfg.agents?.[agentName]
+      if (!rawAgent) return []
+      const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent)
+      return (resolved as { tools?: { allow?: string[] } }).tools?.allow ?? []
+    },
+    isRulePersisted,
+    synthesizeDiff: (agentName, rule, configText) =>
+      synthesizeAllowRuleDiff({ agentName, rule, configText }),
+    dispatchConfigEdit: async (entry, unifiedDiff) => {
+      const req: HostdRequest = {
+        v: 1,
+        op: 'config_propose_edit',
+        request_id: hostdRequestId('gw-always-allow-retry'),
+        args: {
+          unified_diff: unifiedDiff,
+          reason: `Operator 'always allow' retry: ${entry.agentName} can ${entry.grantPhrase}`,
+          target_path: '/state/config/switchroom.yaml',
+        },
+      }
+      const resp = await tryHostdDispatch(entry.agentName, req, 720_000)
+      if (resp === 'not-configured') {
+        return { ok: false as const, error: 'hostd not-configured (retry queue requires host_control.enabled)' }
+      }
+      if (resp.result === 'completed') return { ok: true as const }
+      return {
+        ok: false as const,
+        error: resp.error ?? `hostd ${resp.result}`,
+        retryAfterMs: extractRetryAfterMs(resp),
+      }
+    },
+    // #2973 pt.3 — loud terminal failure. A card edit doesn't ping the
+    // operator (the original permission card was already edited to the
+    // "saving durably in background…" interim state); this posts a NEW
+    // message instead, via the same operator-event broadcast every other
+    // fleet alert uses.
+    notifyTerminalFailure: (entry, reason) => {
+      emitGatewayOperatorEvent({
+        kind: 'always-allow-persist-failed',
+        agent: entry.agentName,
+        detail: `"${entry.grantPhrase}" (rule \`${entry.rule}\`) — ${reason}`,
+        suggestedActions: [],
+        firstSeenAt: new Date(),
+      })
+    },
+    log: (line) => process.stderr.write(line),
+  }
+}
+
+/** ~10 min between periodic drain passes — frequent enough that a
+ * retryable failure (rate limit, transient hostd hiccup) resolves within
+ * a reasonable window, infrequent enough to never look like polling. */
+const ALWAYS_ALLOW_DRAIN_INTERVAL_MS = 10 * 60_000
+
+/**
+ * Boot drain (picks up anything a prior gateway process queued right
+ * before a restart — success criterion: "restarting the gateway mid-
+ * persist does not lose the queued entry") + a periodic timer thereafter.
+ * Called once at gateway startup. Every pass is independently
+ * fault-tolerant — `drainAlwaysAllowPersistQueue` never throws.
+ */
+function scheduleAlwaysAllowPersistDrain(): void {
+  void drainAlwaysAllowPersistQueue(alwaysAllowPersistQueue, alwaysAllowDrainDeps()).catch((err) => {
+    process.stderr.write(
+      `telegram gateway: always-allow-persist-queue boot drain failed: ${(err as Error).message}\n`,
+    )
+  })
+  const timer = setInterval(() => {
+    void drainAlwaysAllowPersistQueue(alwaysAllowPersistQueue, alwaysAllowDrainDeps()).catch((err) => {
+      process.stderr.write(
+        `telegram gateway: always-allow-persist-queue periodic drain failed: ${(err as Error).message}\n`,
+      )
+    })
+  }, ALWAYS_ALLOW_DRAIN_INTERVAL_MS)
+  timer.unref?.()
+}
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
 const ENV_FILE = join(STATE_DIR, '.env')
@@ -774,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`,
     )
@@ -785,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`,
   )
@@ -1383,70 +1550,123 @@ try {
   const pending = findLatestTurnIfInterrupted(turnsDb)
   const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
   if (pending != null && selfAgent) {
-    // Clean-shutdown gate: suppress auto-resume when the prior shutdown was
-    // operator/roll/CLI-initiated (clean). A clean-shutdown marker present and
-    // fresh means the agent was asked to stop; the "interrupted" turn was
-    // abandoned by that decision. Replaying it on every planned restart wastes
-    // subscription quota for no user benefit. Only unclean exits (crash/OOM/
-    // unexpected kill) should auto-resume.
+    // Boot-resume policy (2026-07, superseding #2585). The block only runs
+    // when `pending` exists — i.e. there IS genuinely in-flight work. The
+    // product decision is that a DELIBERATE restart must not silently drop
+    // that work: `session_continuity.boot_resume` (SWITCHROOM_BOOT_RESUME,
+    // default 'in-flight') resumes it even after a clean shutdown. #2585's
+    // quota-saving posture survives only as the opt-in 'never' mode — and
+    // even then we deliver a passive REPORT, never silence, because the user
+    // must always be told when in-flight work stopped.
     //
     // NOTE: GATEWAY_CLEAN_SHUTDOWN_MARKER_PATH is defined lower in this file
     // (module-init order); we compute the path inline here using the same
     // formula so we can read it at boot-resume time.
-    // SWITCHROOM_BOOT_RESUME_ALWAYS=1 is an escape hatch that restores
-    // unconditional resume if needed.
+    // SWITCHROOM_BOOT_RESUME_ALWAYS=1 remains a back-compat escape hatch that
+    // forces unconditional resume regardless of mode.
     const bootResumeMarkerPath =
       process.env.SWITCHROOM_GATEWAY_CLEAN_SHUTDOWN_MARKER ?? join(STATE_DIR, 'clean-shutdown.json')
     const bootResumeCleanMarker = readCleanShutdownMarker(bootResumeMarkerPath)
     const bootResumeForceAlways = process.env.SWITCHROOM_BOOT_RESUME_ALWAYS === '1'
+    const bootResumeMode = parseBootResumeMode(process.env.SWITCHROOM_BOOT_RESUME)
     const bootResumeSuppressed = shouldSuppressBootResume(bootResumeCleanMarker, Date.now(), {
       forceAlways: bootResumeForceAlways,
+      mode: bootResumeMode,
     })
-    if (bootResumeSuppressed) {
+
+    // 3h staleness failsafe (operator spec, 2026-06-03): never AUTO-resume
+    // interrupted work older than RESUME_MAX_AGE_MS — selectResumeBuilder
+    // downgrades a stale 'resume' to the passive 'report'. Env override
+    // SWITCHROOM_RESUME_MAX_AGE_MS (ms); set very high to disable.
+    const RESUME_MAX_AGE_MS = (() => {
+      const v = Number(process.env.SWITCHROOM_RESUME_MAX_AGE_MS)
+      return Number.isFinite(v) && v > 0 ? v : 10_800_000 // 3h
+    })()
+
+    // Decide the inbound kind (pure — see decideBootResumeKind). Precedence:
+    //   1. loop-guard  → 'defer-loop'       (never a second resume of a resume)
+    //   2. suppressed  → 'defer-suppressed' (boot_resume: never; notice, not silence)
+    //   3. otherwise   → selectResumeBuilder (resume | report | none)
+    const bootResumeKind = decideBootResumeKind({
+      pending,
+      suppressed: bootResumeSuppressed,
+      ageMs: Math.max(0, Date.now() - pending.started_at),
+      maxAgeMs: RESUME_MAX_AGE_MS,
+    })
+
+    // Sub-agents that were still in flight (running / stalled — non-terminal)
+    // when the turn was killed. Read HERE, at module top, BEFORE the
+    // subagent-watcher's boot scan + reaper run: the watcher never deletes
+    // these rows (it only flips running→stalled and marks files historical
+    // in-memory), and this accessor already includes 'stalled', so the data
+    // survives either ordering — but reading pre-watcher keeps it simplest.
+    // Threaded into ALL the builders below (resume, watchdog report, and the
+    // deferred report) so the session gets an explicit killed-workers block —
+    // it must not declare the task done on ghost workers, and even a
+    // suppressed/loop-guarded resume must still NAME the deaths.
+    let interruptedSubagents: InterruptedSubagent[] = []
+    try {
+      interruptedSubagents = listNonTerminalSubagentsForTurn(turnsDb, pending.turn_key).map(
+        (s) => ({ agentType: s.agent_type, description: s.description, status: s.status }),
+      )
+    } catch (err) {
       process.stderr.write(
-        `telegram gateway: boot-resume suppressed (clean shutdown` +
-        `${bootResumeCleanMarker?.reason ? ` reason=${JSON.stringify(bootResumeCleanMarker.reason)}` : ''}` +
-        `) — unclean exits still resume turnKey=${pending.turn_key}\n`,
+        `telegram gateway: boot-resume subagent lookup failed (${(err as Error).message}) — continuing without worker list\n`,
       )
-    } else {
-      // 3h staleness failsafe (operator spec, 2026-06-03): never AUTO-resume
-      // interrupted work older than RESUME_MAX_AGE_MS — selectResumeBuilder
-      // downgrades a stale 'resume' to the passive 'report' so the user is told
-      // ("I was working on X ~Nh ago") but nothing replays unprompted. Env
-      // override SWITCHROOM_RESUME_MAX_AGE_MS (ms); set very high to disable.
-      const RESUME_MAX_AGE_MS = (() => {
-        const v = Number(process.env.SWITCHROOM_RESUME_MAX_AGE_MS)
-        return Number.isFinite(v) && v > 0 ? v : 10_800_000 // 3h
-      })()
-      const kind = selectResumeBuilder(pending.ended_via, {
-        ageMs: Math.max(0, Date.now() - pending.started_at),
-        maxAgeMs: RESUME_MAX_AGE_MS,
-      })
-      if (kind === 'resume') {
-        bootResumeInbound = { agent: selfAgent, msg: buildResumeInterruptedInbound({ turn: pending }) }
-      } else if (kind === 'report') {
-        // idleMs: this boot's measured marker age if it just classified this
-        // turn; otherwise recover it from the persisted interrupt_reason (a
-        // later boot, marker already swept); else fall back to total runtime.
-        let idleMs = pending.turn_key === timeoutTurnKey && markerAgeMs != null ? markerAgeMs : null
-        if (idleMs == null && pending.interrupt_reason) {
-          try {
-            const parsed = JSON.parse(pending.interrupt_reason) as { idleMs?: unknown }
-            if (typeof parsed.idleMs === 'number' && Number.isFinite(parsed.idleMs)) idleMs = parsed.idleMs
-          } catch { /* malformed snapshot — fall through */ }
-        }
-        if (idleMs == null) idleMs = Math.max(0, Date.now() - pending.started_at)
-        bootResumeInbound = {
-          agent: selfAgent,
-          msg: buildResumeWatchdogReportInbound({ turn: pending, idleMs }),
-        }
+    }
+
+    if (bootResumeKind === 'resume') {
+      bootResumeInbound = {
+        agent: selfAgent,
+        msg: buildResumeInterruptedInbound({ turn: pending, subagents: interruptedSubagents }),
       }
-      if (bootResumeInbound != null) {
-        process.stderr.write(
-          `telegram gateway: boot-resume queued kind=${kind} turnKey=${pending.turn_key} ` +
-          `endedVia=${pending.ended_via ?? 'open'} chat=${pending.chat_id}\n`,
-        )
+    } else if (bootResumeKind === 'report') {
+      // idleMs: this boot's measured marker age if it just classified this
+      // turn; otherwise recover it from the persisted interrupt_reason (a
+      // later boot, marker already swept); else fall back to total runtime.
+      let idleMs = pending.turn_key === timeoutTurnKey && markerAgeMs != null ? markerAgeMs : null
+      if (idleMs == null && pending.interrupt_reason) {
+        try {
+          const parsed = JSON.parse(pending.interrupt_reason) as { idleMs?: unknown }
+          if (typeof parsed.idleMs === 'number' && Number.isFinite(parsed.idleMs)) idleMs = parsed.idleMs
+        } catch { /* malformed snapshot — fall through */ }
       }
+      if (idleMs == null) idleMs = Math.max(0, Date.now() - pending.started_at)
+      bootResumeInbound = {
+        agent: selfAgent,
+        msg: buildResumeWatchdogReportInbound({ turn: pending, idleMs, subagents: interruptedSubagents }),
+      }
+    } else if (bootResumeKind === 'defer-loop' || bootResumeKind === 'defer-suppressed') {
+      // Passive deferred-report: work was in flight but we decline to
+      // auto-resume (loop-guard, or boot_resume:never). Silence is never
+      // acceptable here — tell the user what was in flight and ask.
+      bootResumeInbound = {
+        agent: selfAgent,
+        msg: buildResumeDeferredReportInbound({
+          turn: pending,
+          reason: bootResumeKind === 'defer-loop' ? 'loop-guard' : 'clean-restart-suppressed',
+          subagents: interruptedSubagents,
+        }),
+      }
+    }
+
+    if (bootResumeKind === 'defer-suppressed') {
+      process.stderr.write(
+        `telegram gateway: boot-resume suppressed (clean shutdown` +
+        `${bootResumeCleanMarker?.reason ? ` reason=${JSON.stringify(bootResumeCleanMarker.reason)}` : ''}` +
+        `, mode=${bootResumeMode}) — passive report delivered for turnKey=${pending.turn_key}\n`,
+      )
+    } else if (bootResumeKind === 'defer-loop') {
+      process.stderr.write(
+        `telegram gateway: boot-resume loop-guard tripped (interrupted turn was itself a resume) ` +
+        `— passive report delivered instead of re-resuming turnKey=${pending.turn_key}\n`,
+      )
+    }
+    if (bootResumeInbound != null) {
+      process.stderr.write(
+        `telegram gateway: boot-resume queued kind=${bootResumeKind} mode=${bootResumeMode} ` +
+        `turnKey=${pending.turn_key} endedVia=${pending.ended_via ?? 'open'} chat=${pending.chat_id}\n`,
+      )
     }
   }
 
@@ -1687,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
@@ -2123,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
@@ -2273,6 +2518,110 @@ function deliverResumeSyntheticOrBuffer(agent: string, inbound: InboundMessage):
   return delivered
 }
 
+/** Outcome of routing an agent-authored button tap through the turn-safe
+ *  delivery machinery. `buffered-mid-turn` and `delivered` both mean "the tap
+ *  will be actioned" (the mid-turn case flushes on turn-complete); only
+ *  `buffered-bridge-offline` needs the user-facing "agent is restarting" notice. */
+type ButtonTapDeliveryOutcome = 'delivered' | 'buffered-mid-turn' | 'buffered-bridge-offline'
+
+/**
+ * Deliver an agent-authored inline-keyboard button tap (`agent:` callback_data)
+ * through the SAME turn-safe machinery as a normal Telegram inbound, instead of
+ * the old raw `sendToAgent` + buffer-only-on-bridge-miss.
+ *
+ * THE BUG (#271 button path, verified 2026-07): the `agent:` callback handler
+ * delivered the synthesized tap inbound with a bare `ipcServer.sendToAgent`,
+ * marked busy, and buffered ONLY when the bridge was offline. It never ran the
+ * #1556 turn gate — so a tap landing WHILE a turn is in flight fired the MCP
+ * channel notification mid-turn, typed into the CLI composer, and stranded there
+ * (the lawgpt/marko wedge). It also skipped the pre-send composer clear and the
+ * deliver-until-acked tracking, so a stranded tap was never sweep-redelivered.
+ *
+ * Fix: reuse the resume-synthetic turn gate (mid-turn → `buffer-until-idle`, the
+ * turn-complete hook + idle-drain flush it the instant claude goes idle), the
+ * pre-send composer clear, and the delivery-confirm tracking — exactly like the
+ * `handleInbound` fresh-turn path. A button tap carries no `meta.source` and a
+ * non-empty body, so `shouldTrackDelivery` enrols it; we additionally require a
+ * real `meta.message_id` so the `enqueue` ack has something to match (else the
+ * never-drop sweep would storm). The tap UX is unchanged — the ack toast, the
+ * single-use keyboard strip, and the bridge-offline spool + restart notice all
+ * stay at the call site; only delivery timing/safety changes.
+ */
+async function deliverButtonTapInbound(
+  agent: string,
+  inbound: InboundMessage,
+): Promise<ButtonTapDeliveryOutcome> {
+  // #1556 turn gate — same authoritative "is a turn in flight?" read the
+  // resume-synthetic path uses. Mid-turn → hold in the pending-inbound buffer;
+  // the turn-complete hook + idle-drain timer flush it when claude goes idle,
+  // where it lands cleanly as a fresh turn instead of stranding in the composer.
+  const { decision, reserve } = reserveInboundDelivery({
+    turnInFlight: turnInFlightForGate(),
+    isSteering: false,
+    isInterrupt: false,
+  })
+  if (decision === 'buffer-until-idle') {
+    pendingInboundBuffer.push(agent, inbound)
+    return 'buffered-mid-turn'
+  }
+  // #2917 per-chat FIFO: reserve the chat's busy key SYNCHRONOUSLY — before the
+  // composer-clear await below — so a concurrent same-chat inbound reaching the
+  // live gate observes this in-flight delivery and buffers behind it. Released
+  // in lockstep below if the send misses (bridge offline).
+  let reservedBusyKey: string | null = null
+  if (reserve && SERIALIZE_INBOUND_DELIVERY_ENABLED) {
+    reservedBusyKey = markClaudeBusyForInbound(inbound)
+  }
+  // Pre-send composer clear (the marko wedge) — wipe stale typed-ahead / ghost
+  // text so the channel notification lands at a clean line and auto-submits.
+  // Soft-fail by contract: a clear failure must NEVER block delivery.
+  if (agent) {
+    try {
+      const { clearAgentComposer } = await import('../../src/agents/tmux.js')
+      const cleared = clearAgentComposer({ agentName: agent })
+      if ('error' in cleared) {
+        process.stderr.write(
+          `telegram gateway: button-tap pre-send composer-clear soft-failed agent=${agent}: ${cleared.error} — delivering anyway\n`,
+        )
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: button-tap pre-send composer-clear threw agent=${agent}: ${(err as Error).message} — delivering anyway\n`,
+      )
+    }
+  }
+  const delivered = ipcServer.sendToAgent(agent, inbound)
+  if (delivered) {
+    const busyKey = reservedBusyKey ?? markClaudeBusyForInbound(inbound)
+    // Track until claude acks via `enqueue` so the deliver-until-acked sweep
+    // re-delivers a tap stranded in the composer. Only when we have a real
+    // message_id to match the ack against — otherwise the never-drop loop storms.
+    if (
+      DELIVERY_CONFIRM_ENABLED &&
+      inbound.meta?.message_id != null &&
+      inbound.meta.message_id !== '' &&
+      shouldTrackDelivery({
+        isSteering: false,
+        isInterrupt: false,
+        hasSource: inbound.meta?.source != null,
+        effectiveText: inbound.text,
+      })
+    ) {
+      trackDelivery(deliveryQueue, busyKey, inbound, Date.now(), String(inbound.messageId))
+    }
+    return 'delivered'
+  }
+  // Bridge offline: release the synchronous reservation in lockstep (else the
+  // orphaned busy key gates every later inbound into the buffer), then spool the
+  // tap so it replays on reconnect — same behaviour as before this fix.
+  if (reservedBusyKey != null) {
+    claudeBusyKeys.delete(reservedBusyKey)
+    claudeBusyKeySince.delete(reservedBusyKey)
+  }
+  pendingInboundBuffer.push(agent, inbound)
+  return 'buffered-bridge-offline'
+}
+
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
 
 // ─── Proactive context compaction (session.max_context_tokens) ──────────
@@ -2502,6 +2851,13 @@ type CurrentTurn = {
   // resume protocol uses this to decide "did the previous turn actually
   // finish a reply, or was it interrupted before commit?".
   lastAssistantDone: boolean
+  // Live model in use for THIS turn, sourced from the main transcript's
+  // `message.model` (the exact resolved model per API call) via the session-tail
+  // `model` event — never from config or launch-time state. Updated on change;
+  // undefined until the turn's first assistant line lands. Rendered onto the
+  // activity/liveness card header's metrics line (e.g. "2m · 14 tools · opus 4.8")
+  // and preferred by /status's buildAgentMetadata over the in-memory override.
+  currentModel?: string
   // Phase 1 of #332: count of tool_use events in the current turn, for
   // the tool_call_count column in the turns registry.
   toolCallCount: number
@@ -2627,6 +2983,16 @@ type CurrentTurn = {
 // is never written and this is exactly the old singleton.
 let currentTurn: CurrentTurn | null = null
 const currentTurnMap = new CurrentTurnMap<CurrentTurn>()
+// Freshness-aware /status session-model source. Two writers: the session-tail
+// `model` event (each assistant line's `message.model` — ground truth for the
+// last API call, survives between turns) and the #2982 /model override (set
+// the instant a switch is confirmed — the ONLY truthful source in the
+// idle-after-switch window, before the next assistant line lands). Every write
+// is seq-stamped and `resolve()` prefers the NEWER observation, so neither
+// source can go stale behind the other (session-model-source.ts, pinned by
+// tests/session-model-source.test.ts). buildAgentMetadata reads resolve();
+// the /model command paths write via setOverride.
+const sessionModelSource = createSessionModelSource()
 // Captures the most-recently-started turn's sessionChatId. Unlike currentTurn,
 // this is NOT cleared by the silence poke (firePoke/clearTurnStarted). It lets
 // the Bug B fallback in executeReply route to the correct chat even when the
@@ -3164,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
@@ -3175,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 } : {}) },
   )
 }
 
@@ -3195,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
@@ -3528,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).
@@ -4579,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
@@ -5236,17 +5732,26 @@ interface PendingVaultRequestSave {
   why?: string
   /** Unix-ms timestamp; entries are reaped after VAULT_REQUEST_SAVE_TTL_MS. */
   staged_at: number
+  /** Set on entries RESTORED from disk after a gateway restart. The staged
+   *  secret `value` is held in memory only (never persisted — secrets
+   *  hygiene), so a restored entry has an empty value and cannot complete the
+   *  write. A Save tap on such a card degrades gracefully: it tells the agent
+   *  the value was lost to a restart instead of writing an empty secret. */
+  restoredWithoutValue?: boolean
 }
 const pendingVaultRequestSaves = new Map<string, PendingVaultRequestSave>()
 // Gateway-side reap window for a staged vault-save card. Tracks the operator
 // approval-card lifetime (config-driven, 60-min default) so the reap never
 // races ahead of the card the operator is still looking at.
 const VAULT_REQUEST_SAVE_TTL_MS = approvalTtlMs()
-function sweepPendingVaultRequestSaves(): void {
-  const cutoff = Date.now() - VAULT_REQUEST_SAVE_TTL_MS
-  for (const [k, v] of pendingVaultRequestSaves) {
-    if (v.staged_at < cutoff) pendingVaultRequestSaves.delete(k)
-  }
+function sweepPendingVaultRequestSaves(now = Date.now()): void {
+  sweepExpiredEntries(
+    pendingVaultRequestSaves,
+    (v, n) => v.staged_at < n - VAULT_REQUEST_SAVE_TTL_MS,
+    expireVaultSaveCard,
+    now,
+    cardExpiryLog,
+  )
 }
 
 /**
@@ -5289,11 +5794,14 @@ const pendingVaultRequestAccesses = new Map<string, PendingVaultRequestAccess>()
 // Gateway-side reap window for a staged vault-access card. Tracks the operator
 // approval-card lifetime (config-driven, 60-min default) — see approvalTtlMs.
 const VAULT_REQUEST_ACCESS_TTL_MS = approvalTtlMs()
-function sweepPendingVaultRequestAccesses(): void {
-  const cutoff = Date.now() - VAULT_REQUEST_ACCESS_TTL_MS
-  for (const [k, v] of pendingVaultRequestAccesses) {
-    if (v.staged_at < cutoff) pendingVaultRequestAccesses.delete(k)
-  }
+function sweepPendingVaultRequestAccesses(now = Date.now()): void {
+  sweepExpiredEntries(
+    pendingVaultRequestAccesses,
+    (v, n) => v.staged_at < n - VAULT_REQUEST_ACCESS_TTL_MS,
+    expireVaultAccessCard,
+    now,
+    cardExpiryLog,
+  )
 }
 
 /**
@@ -5325,23 +5833,14 @@ const MENTAL_MODEL_PROPOSE_TTL_MS = approvalTtlMs()
 // posted card's keyboard away, so a stale card left in the chat can't be tapped
 // into a "Card expired" answer — the operator sees the ⌛ expiry inline instead.
 // Best-effort: card edits are fire-and-forget (the entry is removed regardless).
-function sweepPendingMentalModelProposes(): void {
-  const cutoff = Date.now() - MENTAL_MODEL_PROPOSE_TTL_MS
-  for (const [k, v] of pendingMentalModelProposes) {
-    if (v.staged_at < cutoff) {
-      pendingMentalModelProposes.delete(k)
-      if (v.card_message_id != null) {
-        void lockedBot.api
-          .editMessageText(
-            v.chat_id,
-            v.card_message_id,
-            richMessage('⌛ _This mental-model proposal card expired. Ask the agent to re-propose if it still stands._'),
-            { reply_markup: { inline_keyboard: [] } },
-          )
-          .catch(() => {})
-      }
-    }
-  }
+function sweepPendingMentalModelProposes(now = Date.now()): void {
+  sweepExpiredEntries(
+    pendingMentalModelProposes,
+    (v, n) => v.staged_at < n - MENTAL_MODEL_PROPOSE_TTL_MS,
+    expireMentalModelProposeCard,
+    now,
+    cardExpiryLog,
+  )
 }
 
 // Sliding-window rate limit for mental-model proposals: at most
@@ -5578,6 +6077,296 @@ function isAutoFallbackCooldownActive(_agentName: string, now: number): boolean
   }
 }
 
+// ── Agent-initiated approval-card TTL expiry → wake the parked agent ────────
+//
+// The four agent-initiated approval-card families (vault_request_access /
+// vault_request_save / request_secret / mental_model_propose) each park the
+// requesting agent (it ends its turn to wait for the operator's tap). Before
+// this, an unanswered card that TTL-expired left the agent parked FOREVER: the
+// lazy sweep just deleted the in-memory entry and nothing woke the agent. Each
+// expire* helper mirrors the permission-card timeout path (#2411 / #2862) by
+// routing through the pure `expirePendingCard` core (pending-card-expiry.ts),
+// whose ordering + fault-isolation contract is behaviorally pinned by
+// pending-card-expiry.test.ts:
+//   1. drop the in-memory entry AND its durable store record FIRST (single-
+//      shot — a second tick can never double-fire the wake),
+//   2. edit the card to a ⌛ expired state + strip its keyboard (best-effort),
+//   3. record it in missedApprovalsStore BEFORE delivering, so a throwing
+//      deliver can't lose the re-offer for the operator's return,
+//   4. inject a TIMEOUT-outcome synthetic inbound (turn-gated via
+//      deliverResumeSyntheticOrBuffer, guarded — a half-dead IPC socket that
+//      throws on write is contained, never escaping the reaper's setInterval
+//      callback into an uncaughtException gateway shutdown).
+// Called from BOTH the lazy sweeps (on next stage) and the pendingStateReaper
+// (every 60s — the authoritative timer so an idle gateway still wakes agents).
+
+async function editCardExpired(chatId: string, messageId: number | undefined, body: string): Promise<void> {
+  if (messageId == null) return
+  await lockedBot.api
+    // allow-raw-bot-api: message-id-targeted edit (no thread to lose); best-effort card-expiry strip from the reaper (no grammy ctx). Dropping reply_markup strips the stale keyboard atomically with the text edit.
+    .editMessageText(chatId, messageId, richMessage(body), { reply_markup: { inline_keyboard: [] } })
+    .catch(() => {})
+}
+
+function recordMissedApproval(opts: {
+  stageId: string
+  toolName: string
+  action: string
+  chatId: string
+  threadId?: number
+  now: number
+}): void {
+  if (!MISSED_APPROVAL_REOFFER_ENABLED) return
+  missedApprovalsStore.add({
+    requestId: opts.stageId,
+    toolName: opts.toolName,
+    action: opts.action,
+    chatId: opts.chatId,
+    threadId: opts.threadId ?? null,
+    timedOutAt: opts.now,
+  })
+}
+
+const cardExpiryLog = (msg: string): void => {
+  process.stderr.write(`telegram gateway: ${msg}\n`)
+}
+
+function expireVaultAccessCard(stageId: string, v: PendingVaultRequestAccess, now: number): void {
+  const timeoutMinutes = Math.round(VAULT_REQUEST_ACCESS_TTL_MS / 60000)
+  const { delivered } = expirePendingCard({
+    remove: () => {
+      pendingVaultRequestAccesses.delete(stageId)
+      pendingCardStore.remove(stageId)
+    },
+    editCard: () => void editCardExpired(
+      v.chat_id,
+      v.card_message_id,
+      `⌛ _This vault access request for \`${escapeHtmlForTg(v.key)}\` timed out before you tapped. Ask **${escapeHtmlForTg(v.agent)}** to re-request if it still stands._`,
+    ),
+    buildInbound: () => buildVaultAccessTimeoutInbound({
+      agent: v.agent,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      stageId,
+      timeoutMinutes,
+      key: v.key,
+      scope: v.scope,
+    }),
+    deliver: (inbound) => deliverResumeSyntheticOrBuffer(v.agent, inbound),
+    recordMiss: () => recordMissedApproval({
+      stageId,
+      toolName: 'vault_request_access',
+      action: `grant ${v.agent} ${v.scope} access to \`${v.key}\``,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      now,
+    }),
+    log: cardExpiryLog,
+  })
+  process.stderr.write(
+    `telegram gateway: vault_request_access TTL expired — wake agent=${v.agent} ` +
+    `key=${v.key} stage=${stageId} delivered=${delivered}\n`,
+  )
+}
+
+function expireVaultSaveCard(stageId: string, v: PendingVaultRequestSave, now: number): void {
+  const timeoutMinutes = Math.round(VAULT_REQUEST_SAVE_TTL_MS / 60000)
+  const { delivered } = expirePendingCard({
+    remove: () => {
+      pendingVaultRequestSaves.delete(stageId)
+      pendingCardStore.remove(stageId)
+    },
+    editCard: () => void editCardExpired(
+      v.chat_id,
+      v.card_message_id,
+      `⌛ _This vault-save card for \`${escapeHtmlForTg(v.key)}\` timed out before you tapped. The secret was NOT stored. Ask **${escapeHtmlForTg(v.agent)}** to re-issue if you still want to save._`,
+    ),
+    buildInbound: () => buildVaultSaveTimeoutInbound({
+      agent: v.agent,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      stageId,
+      timeoutMinutes,
+      key: v.key,
+    }),
+    deliver: (inbound) => deliverResumeSyntheticOrBuffer(v.agent, inbound),
+    recordMiss: () => recordMissedApproval({
+      stageId,
+      toolName: 'vault_request_save',
+      action: `save the secret \`${v.key}\` for ${v.agent}`,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      now,
+    }),
+    log: cardExpiryLog,
+  })
+  process.stderr.write(
+    `telegram gateway: vault_request_save TTL expired — wake agent=${v.agent} ` +
+    `key=${v.key} stage=${stageId} delivered=${delivered}\n`,
+  )
+}
+
+function expireSecretRequestCard(stageId: string, v: PendingSecretRequest, now: number): void {
+  const timeoutMinutes = Math.round(PENDING_SECRET_REQUEST_TTL_MS / 60000)
+  const { delivered } = expirePendingCard({
+    remove: () => {
+      pendingSecretRequests.delete(stageId)
+      pendingCardStore.remove(stageId)
+    },
+    editCard: () => void editCardExpired(
+      v.chat_id,
+      v.card_message_id,
+      `⌛ _This secret-request card for \`${escapeHtmlForTg(v.key)}\` timed out before you provided it. Ask **${escapeHtmlForTg(v.agent)}** to re-request if it still needs the value._`,
+    ),
+    buildInbound: () => buildSecretRequestTimeoutInbound({
+      agent: v.agent,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      stageId,
+      timeoutMinutes,
+      key: v.key,
+    }),
+    deliver: (inbound) => deliverResumeSyntheticOrBuffer(v.agent, inbound),
+    recordMiss: () => recordMissedApproval({
+      stageId,
+      toolName: 'request_secret',
+      action: `provide the secret \`${v.key}\` for ${v.agent}`,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      now,
+    }),
+    log: cardExpiryLog,
+  })
+  process.stderr.write(
+    `telegram gateway: request_secret TTL expired — wake agent=${v.agent} ` +
+    `key=${v.key} stage=${stageId} delivered=${delivered}\n`,
+  )
+}
+
+function expireMentalModelProposeCard(stageId: string, v: PendingMentalModelPropose, now: number): void {
+  const timeoutMinutes = Math.round(MENTAL_MODEL_PROPOSE_TTL_MS / 60000)
+  const { delivered } = expirePendingCard({
+    remove: () => {
+      pendingMentalModelProposes.delete(stageId)
+      pendingCardStore.remove(stageId)
+    },
+    editCard: () => void editCardExpired(
+      v.chat_id,
+      v.card_message_id,
+      `⌛ _This mental-model proposal card for \`${escapeHtmlForTg(v.spec.name)}\` timed out before you tapped. Ask **${escapeHtmlForTg(v.agent)}** to re-propose if it still stands._`,
+    ),
+    buildInbound: () => buildMentalModelProposeTimeoutInbound({
+      agent: v.agent,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      stageId,
+      timeoutMinutes,
+      name: v.spec.name,
+    }),
+    deliver: (inbound) => deliverResumeSyntheticOrBuffer(v.agent, inbound),
+    recordMiss: () => recordMissedApproval({
+      stageId,
+      toolName: 'mental_model_propose',
+      action: `declare the mental model \`${v.spec.name}\` for ${v.agent}`,
+      chatId: v.chat_id,
+      ...(v.threadId != null ? { threadId: v.threadId } : {}),
+      now,
+    }),
+    log: cardExpiryLog,
+  })
+  process.stderr.write(
+    `telegram gateway: mental_model_propose TTL expired — wake agent=${v.agent} ` +
+    `name=${v.spec.name} stage=${stageId} delivered=${delivered}\n`,
+  )
+}
+
+// Run all four agent-initiated approval-card expiry sweeps. Called from the
+// pendingStateReaper (the authoritative 60s timer). Each family sweep is
+// per-entry guarded via sweepExpiredEntries, so one throwing expiry (dead IPC
+// socket, store IO error) can't skip the remaining entries or families.
+function sweepExpiredApprovalCards(now: number): void {
+  sweepPendingVaultRequestAccesses(now)
+  sweepPendingVaultRequestSaves(now)
+  sweepPendingMentalModelProposes(now)
+  sweepSecretRequests(now)
+}
+
+// Boot restore: repopulate the four in-memory approval-card maps from the
+// durable store so a post-restart tap on a still-valid card resolves normally
+// (approve → grant + synthetic; deny → denial synthetic) instead of hitting
+// the "Card expired" tombstone. Entries already past their TTL are left for
+// the reaper's next tick, which wakes the parked agent via the timeout path.
+// vault_request_save entries restore WITHOUT their staged value (never
+// persisted) and are flagged `restoredWithoutValue` so a Save tap degrades
+// gracefully rather than writing an empty secret.
+function restorePendingApprovalCards(): number {
+  let restored = 0
+  for (const e of pendingCardStore.loadAll()) {
+    try {
+      if (e.family === 'vault_request_access') {
+        pendingVaultRequestAccesses.set(e.stageId, {
+          agent: e.agent,
+          chat_id: e.chatId,
+          ...(e.cardMessageId != null ? { card_message_id: e.cardMessageId } : {}),
+          ...(e.threadId != null ? { threadId: e.threadId } : {}),
+          key: e.key,
+          scope: e.scope,
+          ...(e.reason != null ? { reason: e.reason } : {}),
+          ttl_seconds: e.ttlSeconds,
+          staged_at: e.stagedAt,
+        })
+        restored++
+      } else if (e.family === 'vault_request_save') {
+        pendingVaultRequestSaves.set(e.stageId, {
+          agent: e.agent,
+          chat_id: e.chatId,
+          ...(e.cardMessageId != null ? { card_message_id: e.cardMessageId } : {}),
+          ...(e.threadId != null ? { threadId: e.threadId } : {}),
+          key: e.key,
+          kind: e.kind,
+          value: '', // never persisted — secrets hygiene
+          ...(e.why != null ? { why: e.why } : {}),
+          staged_at: e.stagedAt,
+          restoredWithoutValue: true,
+        })
+        restored++
+      } else if (e.family === 'request_secret') {
+        pendingSecretRequests.set(e.stageId, {
+          agent: e.agent,
+          chat_id: e.chatId,
+          ...(e.cardMessageId != null ? { card_message_id: e.cardMessageId } : {}),
+          ...(e.threadId != null ? { threadId: e.threadId } : {}),
+          key: e.key,
+          ...(e.reason != null ? { reason: e.reason } : {}),
+          staged_at: e.stagedAt,
+        })
+        restored++
+      } else if (e.family === 'mental_model_propose') {
+        pendingMentalModelProposes.set(e.stageId, {
+          agent: e.agent,
+          chat_id: e.chatId,
+          ...(e.cardMessageId != null ? { card_message_id: e.cardMessageId } : {}),
+          ...(e.threadId != null ? { threadId: e.threadId } : {}),
+          spec: e.spec,
+          ...(e.reason != null ? { reason: e.reason } : {}),
+          staged_at: e.stagedAt,
+        })
+        restored++
+      }
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: pending-card restore skipped a malformed entry: ${(err as Error).message}\n`,
+      )
+    }
+  }
+  if (restored > 0) {
+    process.stderr.write(
+      `telegram gateway: restored ${restored} pending approval card(s) from prior gateway session\n`,
+    )
+  }
+  return restored
+}
+
 // 60-second sweep drops anything past its documented TTL.
 const pendingStateReaper = setInterval(() => {
   const now = Date.now()
@@ -5711,6 +6500,23 @@ const pendingStateReaper = setInterval(() => {
   for (const [k, v] of deferredSecrets) {
     if (now - v.staged_at > DEFERRED_SECRET_TTL_MS) deferredSecrets.delete(k)
   }
+  // Agent-initiated approval cards (vault_request_access / vault_request_save /
+  // request_secret / mental_model_propose): expire past-TTL entries and WAKE
+  // the parked agent (timeout synthetic + missed-approvals re-offer). This is
+  // the authoritative timer — before this the only expiry path was a lazy
+  // sweep on the NEXT stage, so an agent that ended its turn to wait on one of
+  // these cards could sit parked forever if no further request ever staged.
+  // try/catch matches the sibling sweepStaleTurnActiveMarker guard: an escaped
+  // throw inside this setInterval callback would reach uncaughtException and
+  // take the WHOLE gateway down (per-entry faults are already contained inside
+  // sweepExpiredEntries/expirePendingCard; this is the outer belt).
+  try {
+    sweepExpiredApprovalCards(now)
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: approval-card expiry sweep failed: ${(err as Error).message}\n`,
+    )
+  }
   // #550: sweep a stale turn-active marker. Defence-in-depth for the
   // case where neither the turn_end arm nor onTurnComplete fired (SDK
   // killed before the JSONL turn_duration record, compaction window,
@@ -6186,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
@@ -6237,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
@@ -6287,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),
@@ -6297,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`,
     )
   }
 }
@@ -6398,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>()
@@ -6462,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(
@@ -6484,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(() => {
@@ -6571,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
   }
@@ -6593,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())
   }
 }
 
@@ -6638,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 })
   }
 }
@@ -7396,6 +8307,19 @@ function trackRedeliveredInbound(merged: InboundMessage): void {
   ) {
     return
   }
+  // Button-tap anti-storm guard — mirrors the immediate-delivery path in
+  // deliverButtonTapInbound. A tap synthesized without a source message
+  // (`cbMessageId == null` → `messageId: 0`, no meta.message_id) has no id
+  // the `enqueue` ack can ever match, so enrolling it would make the
+  // never-drop sweep re-deliver it until TTL. The immediate path skips
+  // tracking for such taps; a tap that buffered mid-turn and flushed through
+  // here must be skipped identically (asymmetry = a storm on one path only).
+  if (
+    merged.meta?.button_callback === 'true' &&
+    (merged.meta.message_id == null || merged.meta.message_id === '')
+  ) {
+    return
+  }
   const key = chatKey(merged.chatId, merged.threadId != null ? Number(merged.threadId) : null)
   trackDelivery(
     deliveryQueue,
@@ -8230,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
@@ -9261,6 +10186,42 @@ const ipcServer: IpcServer = createIpcServer({
     void fireFleetAutoFallback(msg.agentName, untilMs)
   },
 
+  // Issue #2971 — read-only wedge-watchdog probe: is there a live pending
+  // permission request (Telegram approval card) for this agent right now?
+  // Sourced directly from `pendingPermissions` — no mutation, no card
+  // posting, just a snapshot read. The watchdog uses this to decide whether
+  // to Esc a shape-persistent permission-prompt TUI or defer to the card /
+  // the #2724 TTL reaper. Always answered synchronously and on the SAME
+  // connection so the watchdog's short (~2s) budget can resolve promptly.
+  onQueryPendingPermission(client: IpcClient, msg: QueryPendingPermissionMessage) {
+    const self = process.env.SWITCHROOM_AGENT_NAME
+    if (self && msg.agentName !== self) {
+      process.stderr.write(
+        `telegram gateway: query_pending_permission rejected — agent mismatch (${msg.agentName} != ${self})\n`,
+      )
+      try {
+        client.send({ type: 'pending_permission_status', correlationId: msg.correlationId, pending: false })
+      } catch { /* best effort */ }
+      return
+    }
+    // Any LIVE entry answers the question — this gateway serves exactly one
+    // agent, so `pendingPermissions` is already scoped to `msg.agentName`.
+    const [requestId] = pendingPermissions.keys()
+    const pending = pendingPermissions.size > 0
+    try {
+      client.send({
+        type: 'pending_permission_status',
+        correlationId: msg.correlationId,
+        pending,
+        ...(pending && requestId ? { requestId } : {}),
+      })
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: query_pending_permission reply failed: ${(err as Error).message}\n`,
+      )
+    }
+  },
+
   // #2670 one-tap self-improvement — persist a skill-improvement proposal and
   // post its Approve/Dismiss card. The store transition + apply-injection on
   // Approve are owned by handleSkillProposalCallback (so a gateway restart
@@ -9788,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`,
@@ -11748,6 +12718,21 @@ async function executeVaultRequestSave(args: Record<string, unknown>): Promise<{
     { threadId, chat_id, verb: 'vault_request_save.card' },
   )
   pending.card_message_id = sent.message_id
+  // Persist card METADATA (never the staged `value` — secrets hygiene) so a
+  // gateway restart doesn't strand the parked agent. A restored Save tap can't
+  // complete (value is gone) and degrades to a "value lost to restart" wake-up.
+  pendingCardStore.add({
+    family: 'vault_request_save',
+    stageId,
+    agent: pending.agent,
+    chatId: pending.chat_id,
+    ...(pending.card_message_id != null ? { cardMessageId: pending.card_message_id } : {}),
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    key: pending.key,
+    kind: pending.kind,
+    ...(pending.why != null ? { why: pending.why } : {}),
+    stagedAt: pending.staged_at,
+  })
 
   return {
     content: [
@@ -11791,11 +12776,17 @@ const armedSecretCaptures = new Map<string, ArmedSecretCapture>()
 const PENDING_SECRET_REQUEST_TTL_MS = 30 * 60_000 // card lifetime
 const ARMED_SECRET_CAPTURE_TTL_MS = 10 * 60_000   // window to send the value after tapping
 
-function sweepSecretRequests(): void {
-  const now = Date.now()
-  for (const [k, v] of pendingSecretRequests) {
-    if (now - v.staged_at > PENDING_SECRET_REQUEST_TTL_MS) pendingSecretRequests.delete(k)
-  }
+function sweepSecretRequests(now = Date.now()): void {
+  sweepExpiredEntries(
+    pendingSecretRequests,
+    (v, n) => n - v.staged_at > PENDING_SECRET_REQUEST_TTL_MS,
+    expireSecretRequestCard,
+    now,
+    cardExpiryLog,
+  )
+  // armedSecretCaptures is a TRANSIENT post-tap window (never persisted): it's
+  // only set after the operator taps [Provide securely], and the request is
+  // no longer parked-on-a-card. Just drop stale ones — no wake needed.
   for (const [k, v] of armedSecretCaptures) {
     if (now - v.armed_at > ARMED_SECRET_CAPTURE_TTL_MS) armedSecretCaptures.delete(k)
   }
@@ -11845,7 +12836,10 @@ async function executeRequestSecret(args: Record<string, unknown>): Promise<{ co
   // Dedupe: one open request per (chat, key). Drop any prior stage for
   // the same target so the operator never sees stacked cards.
   for (const [sid, p] of pendingSecretRequests) {
-    if (p.chat_id === chat_id && p.key === key) pendingSecretRequests.delete(sid)
+    if (p.chat_id === chat_id && p.key === key) {
+      pendingSecretRequests.delete(sid)
+      pendingCardStore.remove(sid)
+    }
   }
 
   const stageId = randomBytes(4).toString('hex')
@@ -11867,6 +12861,21 @@ async function executeRequestSecret(args: Record<string, unknown>): Promise<{ co
     { threadId, chat_id, verb: 'request_secret.card' },
   )
   pending.card_message_id = sent.message_id
+  // Persist card metadata so a gateway restart doesn't strand the parked
+  // agent. request_secret holds NO value at staging time (the value arrives
+  // after the operator taps [Provide securely]), so nothing sensitive lands
+  // on disk here.
+  pendingCardStore.add({
+    family: 'request_secret',
+    stageId,
+    agent: pending.agent,
+    chatId: pending.chat_id,
+    ...(pending.card_message_id != null ? { cardMessageId: pending.card_message_id } : {}),
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    key: pending.key,
+    ...(pending.reason != null ? { reason: pending.reason } : {}),
+    stagedAt: pending.staged_at,
+  })
 
   return {
     content: [
@@ -11915,6 +12924,7 @@ async function captureProvidedSecret(
   armedSecretCaptures.delete(chat_id)
   const pending = pendingSecretRequests.get(armed.stageId)
   pendingSecretRequests.delete(armed.stageId)
+  pendingCardStore.remove(armed.stageId)
 
   // Delete the raw message FIRST — surfaces a warning if it fails.
   if (msgId != null) await deleteSensitiveMessage(chat_id, msgId, 'provided secret value')
@@ -12030,6 +13040,7 @@ async function handleSecretRequestCallback(ctx: Context, data: string): Promise<
 
   if (action === 'decline') {
     pendingSecretRequests.delete(stageId)
+    pendingCardStore.remove(stageId)
     armedSecretCaptures.delete(pending.chat_id)
     await ctx.answerCallbackQuery({ text: 'Declined.' }).catch(() => {})
     if (pending.card_message_id != null) {
@@ -12197,12 +13208,27 @@ async function executeVaultRequestAccess(args: Record<string, unknown>): Promise
     { threadId, chat_id, verb: 'vault_request_access.card' },
   )
   pending.card_message_id = sent.message_id
+  // Persist card metadata (no secret material — this flow stages only the ACL
+  // request) so a gateway restart doesn't strand the parked agent.
+  pendingCardStore.add({
+    family: 'vault_request_access',
+    stageId,
+    agent: pending.agent,
+    chatId: pending.chat_id,
+    ...(pending.card_message_id != null ? { cardMessageId: pending.card_message_id } : {}),
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    key: pending.key,
+    scope: pending.scope,
+    ...(pending.reason != null ? { reason: pending.reason } : {}),
+    ttlSeconds: pending.ttl_seconds,
+    stagedAt: pending.staged_at,
+  })
 
   return {
     content: [
       {
         type: 'text',
-        text: `vault_request_access: card sent (stage_id=${stageId}, key=${key}, scope=${scopeRaw}). Wait for the operator to tap Approve or Deny — do not retry the vault read until you see a confirmation message. If the card times out (10 min) you can re-request.`,
+        text: `vault_request_access: card sent (stage_id=${stageId}, key=${key}, scope=${scopeRaw}). Wait for the operator to tap Approve or Deny — do not retry the vault read until you see a confirmation message. If the card times out (${Math.round(VAULT_REQUEST_ACCESS_TTL_MS / 60000)} min) you can re-request.`,
       },
     ],
   }
@@ -12366,6 +13392,19 @@ async function executeMentalModelPropose(args: Record<string, unknown>): Promise
     { threadId, chat_id, verb: 'mental_model_propose.card' },
   )
   pending.card_message_id = sent.message_id
+  // Persist card metadata (the proposed DECLARATION is not secret material) so
+  // a gateway restart doesn't strand the parked agent.
+  pendingCardStore.add({
+    family: 'mental_model_propose',
+    stageId,
+    agent: pending.agent,
+    chatId: pending.chat_id,
+    ...(pending.card_message_id != null ? { cardMessageId: pending.card_message_id } : {}),
+    ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+    spec: pending.spec,
+    ...(pending.reason != null ? { reason: pending.reason } : {}),
+    stagedAt: pending.staged_at,
+  })
   // Only count a proposal against the rate budget once its card actually
   // posted (validation errors / dupes don't consume the budget).
   mentalModelProposeTimes.push(Date.now())
@@ -12526,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}` }] }
 }
 
@@ -12771,6 +13826,7 @@ function composeTurnActivity(turn: CurrentTurn, final = false, liveSuffix = ''):
     elapsedMs: turn.startedAt > 0 ? Date.now() - turn.startedAt : 0,
     toolCount: turn.labeledToolCount,
     state: final ? 'done' : 'running',
+    model: turn.currentModel,
   }
   return renderActivityFeedWithNested(turn.mirrorLines, childLines, final, liveSuffix, stepCount, header)
 }
@@ -13088,6 +14144,7 @@ function openLivenessFeedIfDue(turn: CurrentTurn): void {
   const lines = turn.mirrorLines.length > 0 ? turn.mirrorLines : ['Working…']
   const livenessHeader: SessionActivityHeader = {
     label: 'Agent', elapsedMs: age, toolCount: turn.labeledToolCount, state: 'running',
+    model: turn.currentModel,
   }
   // Liveness card is a single "step" whose start is the turn start, so `age`
   // IS the step's own elapsed. formatStepSuffix keeps the `→` line timer-free
@@ -13218,6 +14275,7 @@ function feedHeartbeatTick(): void {
     const age = Date.now() - turn.startedAt
     const livenessHeader: SessionActivityHeader = {
       label: 'Agent', elapsedMs: age, toolCount: turn.labeledToolCount, state: 'running',
+      model: turn.currentModel,
     }
     const lines = turn.mirrorLines.length > 0 ? turn.mirrorLines : ['Working in background…']
     // `subagentAt` is the worker's last ADVANCE — the current step's start —
@@ -13407,6 +14465,7 @@ function clearActivitySummary(turn: CurrentTurn, finalHtmlOverride?: string | nu
       const livenessElapsed = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
       const livenessHeader: SessionActivityHeader = {
         label: 'Agent', elapsedMs: livenessElapsed, toolCount: turn.labeledToolCount, state: 'done',
+        model: turn.currentModel,
       }
       finalHtml = renderActivityFeedWithNested(['Working…'], [], true, '', undefined, livenessHeader)
     }
@@ -13897,6 +14956,22 @@ function handleSessionEvent(ev: SessionEvent): void {
       return
     }
     case 'dequeue': return
+    case 'model': {
+      // Live model capture for the main turn. The session-tail projection
+      // already filtered sentinels (`<synthetic>` compaction lines), so any
+      // value reaching here is a real resolved model id. Record it on the turn
+      // (update-on-change) so the activity/liveness card header and /status
+      // render the model actually serving this turn's API calls — transcript-
+      // sourced, never config. Also note it on the freshness-aware session-model
+      // source so a /status query between turns still reflects the last model
+      // (and a fresh assistant line reclaims the source from a /model override).
+      const turn = currentTurn
+      if (turn != null) {
+        turn.currentModel = ev.model
+      }
+      sessionModelSource.noteTranscriptModel(ev.model)
+      return
+    }
     case 'thinking': {
       // #1067: snapshot the turn atom at handler entry. Even though this
       // handler is sync, the principle is uniform across all event arms
@@ -17022,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
   }
@@ -17074,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.
@@ -18463,13 +19557,12 @@ function buildAgentAudit(agentName: string): AgentAudit | undefined {
 // broker's fleet-wide `ListStateData` payload via
 // `buildAuthSummaryFromBroker`, with billingType pulled from the
 // agent's `.claude.json` (the broker doesn't track plan tier).
-/**
- * Live session-model override set by the `/model` picker (session-only). Held
- * in gateway memory so it clears on restart, the same point at which claude's
- * session reverts to the configured model — keeping `/status` honest without
- * a persisted store. Null when no session switch is active.
- */
-let activeSessionModelOverride: string | null = null
+// The live session-model override set by the `/model` picker (session-only)
+// lives on `sessionModelSource` (setOverride/getOverride, declared beside the
+// currentTurn globals). Held in gateway memory so it clears on restart, the
+// same point at which claude's session reverts to the configured model —
+// keeping `/status` honest without a persisted store. `resolve()` arbitrates
+// freshness against the transcript-observed model (#2982 idle-switch window).
 
 async function buildAgentMetadata(agentName: string): Promise<AgentMetadata> {
   type AgentListResp = {
@@ -18499,7 +19592,18 @@ async function buildAgentMetadata(agentName: string): Promise<AgentMetadata> {
   return {
     agentName,
     model: a?.model ?? null,
-    sessionModel: activeSessionModelOverride,
+    // The FRESHEST session-model observation wins (session-model-source.ts):
+    // the transcript's `message.model` (ground truth for the last API call)
+    // vs the #2982 /model override (the only truthful source in the idle-
+    // after-switch window, before the next assistant line). Both rendered
+    // through formatModelLabel for a consistent short form; an override value
+    // that isn't model-shaped (an already-friendly "Opus 4.8" label) passes
+    // through verbatim. Never sourced from config.
+    sessionModel: (() => {
+      const resolved = sessionModelSource.resolve()
+      if (resolved == null) return null
+      return formatModelLabel(resolved.model) ?? resolved.model
+    })(),
     extendsProfile: (a?.extends ?? a?.template) ?? null,
     topicName: a?.topic_name ?? null,
     topicEmoji: a?.topic_emoji ?? null,
@@ -18730,7 +19834,7 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
     },
     escapeHtml: escapeHtmlForTg,
     preBlock,
-    getActiveSessionModel: () => activeSessionModelOverride,
+    getActiveSessionModel: () => sessionModelSource.getOverride(),
     /**
      * Graceful restart for sr-* → Claude model switch. Same mechanism as
      * the /restart command: writes a restart marker (so the post-restart
@@ -18740,9 +19844,18 @@ function buildModelDeps(restartCtx?: ModelDepsRestartContext): ModelMenuDeps & M
     scheduleRestart: async (reason: string) => {
       const name = getMyAgentName()
       // Debounce: mirror the /restart command's 15 s guard to prevent
-      // double-dispatch on a rapid double-tap of /model <claude-alias>.
+      // double-dispatch on a rapid double-tap of /model <claude-alias>. This
+      // path previously `return`ed silently — indistinguishable from a
+      // successful dispatch — so a model switch caught in the window was a
+      // silent no-op while the caller reported success. THROW a tagged error
+      // so scheduleModelRelaunch can react (keep the in-flight restart's carrier,
+      // tell the operator honestly) instead of falsely claiming the switch stuck.
       const existing = readRestartMarker()
-      if (existing && Date.now() - existing.ts < 15_000) return
+      if (existing && Date.now() - existing.ts < 15_000) {
+        const e = new Error('a restart is already in flight — try again in ~15s')
+        ;(e as { code?: string }).code = 'restart_in_flight'
+        throw e
+      }
       if (restartCtx) {
         writeRestartMarker({
           chat_id: restartCtx.chatId,
@@ -18752,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,
@@ -18771,30 +19893,61 @@ 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.
-      writeFileSync(join(agentDir, '.session-model-override'), `${model}\n`, 'utf8')
-      activeSessionModelOverride = model
-      await deps.scheduleRestart(reason)
+      if (!agentDir) throw new Error('agent dir unresolvable — cannot write session-model file')
+      const prevOverride = sessionModelSource.getOverride()
+      const prevFileRaw = readSessionModelFileRaw(agentDir)
+      writeSessionModelFile(
+        agentDir,
+        model,
+        readConfiguredDefaultModel(agentDir) ??
+          resolveMainModel(deps.getConfiguredModel() ?? undefined),
+      )
+      sessionModelSource.setOverride(model)
+      try {
+        await deps.scheduleRestart(reason)
+      } catch (err) {
+        // 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') {
+          restoreSessionModelFileRaw(agentDir, prevFileRaw)
+          sessionModelSource.setOverride(prevOverride)
+          clearRelaunchModelIntent(agentDir)
+        }
+        throw err
+      }
     },
   }
   return deps
@@ -18823,7 +19976,50 @@ bot.command('model', async ctx => {
     return
   }
   const reply = await handleModelCommand(parsed, deps)
-  await switchroomReply(ctx, reply.text, { html: reply.html })
+  // Record a POSITIVELY-CONFIRMED typed switch so /status reflects what's
+  // actually running — the SAME in-memory override the menu callback path sets
+  // (buildAgentMetadata resolves it via sessionModelSource). Only
+  // 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.
+  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 + persistWarning, { html: reply.html })
 })
 
 // `/effort` — show or switch the reasoning effort for the live session.
@@ -18934,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,
@@ -19092,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,
@@ -21118,6 +22327,7 @@ async function performVaultAccessApproval(
       const visible = await listViaBroker()
       if (visible !== null && visible.includes(pending.key)) {
         pendingVaultRequestAccesses.delete(stageId)
+        pendingCardStore.remove(stageId)
         if (pending.card_message_id != null) {
           await ctx.api
             .editMessageText(
@@ -21216,6 +22426,7 @@ async function performVaultAccessApproval(
     // the agent to re-issue, or the broker error message will tell
     // them the next step.
     pendingVaultRequestAccesses.delete(stageId)
+    pendingCardStore.remove(stageId)
     if (pending.card_message_id != null) {
       await ctx.api
         .editMessageText(
@@ -21247,6 +22458,7 @@ async function performVaultAccessApproval(
   }
 
   pendingVaultRequestAccesses.delete(stageId)
+  pendingCardStore.remove(stageId)
   if (pending.card_message_id != null) {
     const days = Math.round(pending.ttl_seconds / 86400)
     const footer =
@@ -21455,23 +22667,17 @@ async function handleMentalModelProposeCallback(ctx: Context, data: string): Pro
   // this, a card left untapped past its TTL is still resolvable if no fresh
   // proposal has run the sweep — an operator could approve a stale proposal.
   if (Date.now() - pending.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS) {
-    pendingMentalModelProposes.delete(stageId)
-    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-propose.' }).catch(() => {})
-    if (pending.card_message_id != null) {
-      await ctx.api
-        .editMessageText(
-          pending.chat_id,
-          pending.card_message_id,
-          richMessage('⌛ _This mental-model proposal card expired before you tapped. Ask the agent to re-propose if it still stands._'),
-          { reply_markup: { inline_keyboard: [] } },
-        )
-        .catch(() => {})
-    }
+    // Expired between post and tap: route through the shared expiry path so the
+    // parked agent is WOKEN (timeout synthetic + missed-approvals re-offer) and
+    // the durable store entry is cleared — not just a silent map delete.
+    expireMentalModelProposeCard(stageId, pending, Date.now())
+    await ctx.answerCallbackQuery({ text: 'Card expired — the agent was notified.' }).catch(() => {})
     return
   }
   // Single-shot: remove the pending entry immediately so a double-tap can't
   // resolve twice.
   pendingMentalModelProposes.delete(stageId)
+  pendingCardStore.remove(stageId)
 
   const proposal: MentalModelPendingProposal = {
     agent: pending.agent,
@@ -21613,6 +22819,7 @@ async function handleVaultRequestAccessCallback(ctx: Context, data: string): Pro
 
   if (action === 'deny') {
     pendingVaultRequestAccesses.delete(stageId)
+    pendingCardStore.remove(stageId)
     await ctx.answerCallbackQuery({ text: '🚫 Denied' }).catch(() => {})
     if (pending.card_message_id != null) {
       await ctx.api
@@ -21835,6 +23042,7 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
 
   if (action === 'discard') {
     pendingVaultRequestSaves.delete(stageId)
+    pendingCardStore.remove(stageId)
     await ctx.answerCallbackQuery({ text: '🚫 Discarded' }).catch(() => {})
     if (pending.card_message_id != null) {
       await ctx.api
@@ -21905,6 +23113,43 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
     // stale "spinning" state on the button while we run the write.
     await ctx.answerCallbackQuery({ text: '⏳ Saving…' }).catch(() => {})
 
+    // Restored-after-restart guard: the staged secret VALUE is held in gateway
+    // memory only and is never persisted (secrets hygiene). If this card was
+    // restored from disk after a gateway restart, the value is gone — we CANNOT
+    // complete the write. Degrade gracefully: strip the card, wake the agent
+    // with a save-failed (value-lost) synthetic so it re-requests, and stop.
+    if (pending.restoredWithoutValue || pending.value.length === 0) {
+      pendingVaultRequestSaves.delete(stageId)
+      pendingCardStore.remove(stageId)
+      if (pending.card_message_id != null) {
+        await ctx.api
+          .editMessageText(
+            pending.chat_id,
+            pending.card_message_id,
+            richMessage(`⚠️ _The staged value for \`${escapeHtmlForTg(pending.key)}\` was lost to a gateway restart — nothing was saved. Ask **${escapeHtmlForTg(pending.agent)}** to re-issue \`vault_request_save\` if you still want to store it._`),
+            { reply_markup: { inline_keyboard: [] } },
+          )
+          .catch(() => {})
+      }
+      const lostInbound = buildVaultSaveFailedInbound({
+        ctx: {
+          agent: pending.agent,
+          key: pending.key,
+          chat_id: pending.chat_id,
+          ...(pending.threadId != null ? { threadId: pending.threadId } : {}),
+        },
+        stageId,
+        operatorId: senderId,
+        reason: 'staged value lost to a gateway restart — re-request the save',
+      })
+      const lDelivered = deliverResumeSyntheticOrBuffer(pending.agent, lostInbound)
+      process.stderr.write(
+        `telegram gateway: vault_request_save value lost to restart — wake agent=${pending.agent} ` +
+        `key=${pending.key} stage=${stageId} delivered=${lDelivered}\n`,
+      )
+      return
+    }
+
     // #1115 follow-up: the save-approve flow now mirrors the access-
     // approve flow under telegram-id mode — broker `put` accepts
     // `attest_via_posture: true` (server.ts:1448-1500), so the
@@ -21940,6 +23185,7 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
             .catch(() => {})
         }
         pendingVaultRequestSaves.delete(stageId)
+        pendingCardStore.remove(stageId)
         return
       }
       // defaultVaultWrite spawns `switchroom vault set <key>` with the
@@ -21971,6 +23217,7 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
       // retry by re-invoking the same MCP tool, but the value will be
       // re-staged with a new ID. Drop the current stage.
       pendingVaultRequestSaves.delete(stageId)
+      pendingCardStore.remove(stageId)
       // Wake the waiting agent with the failure (symmetric with the
       // success/discard paths) so it doesn't assume vault:<key> exists.
       const failReason =
@@ -21996,6 +23243,7 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
 
     // Success — mask the value in the card for visual confirmation.
     pendingVaultRequestSaves.delete(stageId)
+    pendingCardStore.remove(stageId)
     if (pending.card_message_id != null) {
       await ctx.api
         .editMessageText(
@@ -23888,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.
@@ -23921,13 +25169,38 @@ bot.on('callback_query:data', async ctx => {
     }
     const didInterimSrEdit = false
     try {
-      const prevSessionModel = activeSessionModelOverride
+      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) {
-        activeSessionModelOverride = 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
@@ -23949,6 +25222,36 @@ bot.on('callback_query:data', async ctx => {
             { reply_markup: { inline_keyboard: [] } },
           )
           .catch(() => {})
+        // Carry the requested Claude model across the restart via the SAME
+        // 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 {
+              writeSessionModelFile(
+                agentDir,
+                token,
+                readConfiguredDefaultModel(agentDir) ??
+                  resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
+              )
+              sessionModelSource.setOverride(token)
+            } catch (e) {
+              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.
         writeRestartMarker({ chat_id: cbChatId, thread_id: cbThreadId ?? null, ack_message_id: null, ts: Date.now() })
         stampUserRestartReason('user: sr-to-claude model switch (menu)')
@@ -24307,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
@@ -24332,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,
@@ -24351,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.
@@ -24401,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
@@ -24490,17 +25826,17 @@ bot.on('callback_query:data', async ctx => {
     process.stderr.write(
       `telegram gateway: button_callback chatId=${cbChatId} user=${ctx.from.id} data=${JSON.stringify(agentCb.raw)} btnText=${JSON.stringify(buttonText ?? null)}\n`,
     )
-    // Registered-keyed delivery + buffer-on-miss (same fix as the
-    // normal-inbound path above): broadcast()/clientCount() lost the
-    // tap whenever the bridge was mid-reconnect (clientCount() counts
-    // unregistered sockets, so the notice was suppressed AND nothing
-    // was actually queued). sendToAgent → pendingInboundBuffer (drained
-    // by onClientRegistered) makes the "queued" promise real.
+    // #271 turn-safety: route the tap through the SAME turn-safe delivery
+    // machinery as a normal inbound (deliverButtonTapInbound) instead of a raw
+    // sendToAgent. A tap landing mid-turn now buffers until idle (never strands
+    // in the composer, #1556), a delivered tap is composer-cleared first and
+    // tracked so the redelivery sweep rescues a strand, and a bridge-offline tap
+    // still spools + shows the restart notice below (unchanged UX). The old raw
+    // path (sendToAgent → pendingInboundBuffer, drained by onClientRegistered)
+    // fixed only the bridge-mid-reconnect drop; it never gated on turn state.
     const selfAgentBtn = process.env.SWITCHROOM_AGENT_NAME ?? ''
-    const btnDelivered = ipcServer.sendToAgent(selfAgentBtn, inboundMsg)
-    if (btnDelivered) markClaudeBusyForInbound(inboundMsg)
-    if (!btnDelivered) {
-      pendingInboundBuffer.push(selfAgentBtn, inboundMsg)
+    const btnOutcome = await deliverButtonTapInbound(selfAgentBtn, inboundMsg)
+    if (btnOutcome === 'buffered-bridge-offline') {
       // No registered bridge — the agent's mid-restart. Tell the user
       // so they don't think the button silently swallowed their tap;
       // the tap is genuinely buffered now and replays on reconnect.
@@ -24729,6 +26065,36 @@ bot.on('callback_query:data', async ctx => {
           process.stderr.write(
             `telegram gateway: always-allow hostd FAILED: ${failReason} (request_id=${request_id})\n`,
           )
+          // #2973 pt.2 — enqueue for the durable retry queue UNLESS the
+          // failure is non-retryable (config edits locked — retrying
+          // won't help until the operator flips the flag; that case
+          // keeps today's honest "did NOT save" card only). Everything
+          // else (stale config view, transient hostd error, rate limit)
+          // gets picked up by the boot/periodic drain instead of quietly
+          // requiring the operator to notice and re-tap.
+          if (!editLockHint) {
+            try {
+              await alwaysAllowPersistQueue.enqueue({
+                agentName,
+                rule: chosen.rule,
+                grantPhrase,
+                chatId: ctx.chat?.id != null ? String(ctx.chat.id) : undefined,
+                threadId: (ctx.callbackQuery?.message as { message_thread_id?: number } | undefined)?.message_thread_id,
+                error: failReason,
+              })
+            } catch (enqueueErr) {
+              // The retry queue's own write failed (disk full, perms, …) —
+              // don't pretend this landed. Fold it into the operator-facing
+              // failReason so the "did NOT save" card is honest about the
+              // retry mechanism ALSO having failed, not just the original
+              // dispatch (#2973 adversarial review pt.2).
+              const enqueueMsg = (enqueueErr as Error).message
+              process.stderr.write(
+                `telegram gateway: always-allow enqueue for retry FAILED: ${enqueueMsg} (request_id=${request_id})\n`,
+              )
+              failReason = `${failReason} (retry queue also failed to persist: ${enqueueMsg})`
+            }
+          }
         }
       }
 
@@ -26619,6 +27985,12 @@ void (async () => {
           }
         }
 
+        // #2973 pt.2 — drain any always-allow persists left queued by a
+        // prior gateway process (e.g. one that restarted mid-persist),
+        // then keep draining periodically for the rest of this process's
+        // lifetime.
+        scheduleAlwaysAllowPersistDrain()
+
         void registerSwitchroomBotCommands().catch(() => {})
 
         // #613 fix: pre-warm the chatAvailableReactions cache for every
@@ -26732,6 +28104,18 @@ void (async () => {
           }
         }
 
+        // Restore the four agent-initiated approval-card families from the
+        // durable store so a post-restart tap on a still-valid card resolves
+        // normally instead of hitting the "Card expired" tombstone (and an
+        // already-expired entry gets woken by the reaper's next tick).
+        try {
+          restorePendingApprovalCards()
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: pending approval-card restore failed: ${(err as Error).message}\n`,
+          )
+        }
+
         // Boot-time pin sweep
         try {
           const bootAccess = loadAccess()
@@ -26903,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
@@ -26961,8 +28346,9 @@ void (async () => {
                   // a phantom session override.
                   return resolveMainModel(raw ?? undefined)
                 })()
-                activeSessionModelOverride =
-                  launched.length > 0 && launched !== configured ? launched : null
+                sessionModelSource.setOverride(
+                  launched.length > 0 && launched !== configured ? launched : null,
+                )
               } catch { /* leave override as-is on a bad read */ }
             }
 
@@ -27276,7 +28662,7 @@ void (async () => {
               // Gated to background completions: foreground sub-agents
               // need nothing here, and 'orphan' is a stale historical-at-
               // boot row, not a fresh completion the user is waiting on.
-              onFinish: ({ agentId, outcome, description, resultText, toolCount, durationMs }) => {
+              onFinish: ({ agentId, outcome, description, resultText, toolCount, durationMs, background: entryBackground }) => {
                 // Reaction promotion: if the parent turn already ended
                 // with this (or another) worker still running, its 👍 was
                 // deferred (held on ✍️/⚡). Now that a worker finished,
@@ -27307,13 +28693,32 @@ void (async () => {
                 // (worker-feed-dispatch.ts, pinned by its test). Best-effort:
                 // a DB hiccup keeps the watcher's generic label rather than
                 // throwing out of the terminal handler.
-                let dispatch: WorkerFeedDispatch = resolveWorkerFeedDispatch(null, description)
+                let dispatch: WorkerFeedDispatch = resolveWorkerFeedDispatch(null, description, entryBackground)
                 if (turnsDb != null) {
                   try {
-                    dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(turnsDb, agentId), description)
+                    dispatch = resolveWorkerFeedDispatch(getSubagentByJsonlId(turnsDb, agentId), description, entryBackground)
                   } catch { /* best-effort */ }
                 }
-                const isBackground = dispatch.isBackground
+                let isBackground = dispatch.isBackground
+                // Fix #1(+#2): the registry row never linked AND the watcher
+                // entry's own cached background flag was never observed
+                // either (both `resolveWorkerFeedDispatch` fallbacks came up
+                // empty) — this is the "DB row is unlinked" bug's worst
+                // case. A finished worker with actual narrative result text
+                // is far more likely a dropped background handback than a
+                // legitimate foreground no-op (a foreground sub-agent's
+                // result returns inline as the Task tool result — the
+                // gateway wouldn't otherwise need to route anything here).
+                // Degrade to background so the result is delivered instead
+                // of silently lost. Idempotency: this only flips the
+                // dispatch classification for THIS single onFinish call —
+                // all the existing dedup/idempotency guards below
+                // (decideSubagentHandback's spool key, completionNotified,
+                // etc.) still apply unchanged, so this cannot cause a
+                // double-handback.
+                if (!dispatch.hasRow && entryBackground == null && resultText.trim().length > 0) {
+                  isBackground = true
+                }
                 // NESTED (depth-2+) worker terminal: its live status surfaced
                 // via the worker feed (see onProgress), so finalize that card
                 // cleanly — never leave it frozen mid-"→ step". But NO user
@@ -27330,6 +28735,10 @@ void (async () => {
                       latestSummary: resultText,
                       elapsedMs: durationMs,
                       state: outcome === 'failed' ? 'failed' : 'done',
+                      // Persisted (registry) model — the last one the watcher
+                      // recorded from the worker's transcript — so the terminal
+                      // card keeps the model tag even with no live entry.
+                      model: dispatch.feedModel ?? undefined,
                     })
                     reconcileWorkerPin(agentId, null, false)
                   }
@@ -27407,6 +28816,7 @@ void (async () => {
                       latestSummary: resultText,
                       elapsedMs: durationMs,
                       state: outcome === 'failed' ? 'failed' : 'done',
+                      model: dispatch.feedModel ?? undefined,
                     })
                     // Status-pin: worker done — drop its pin.
                     reconcileWorkerPin(agentId, null, false)
@@ -27426,6 +28836,7 @@ void (async () => {
                     latestSummary: resultText,
                     elapsedMs: durationMs,
                     state: outcome === 'failed' ? 'failed' : 'done',
+                    model: dispatch.feedModel ?? undefined,
                   })
                   // Status-pin: worker done — drop its pin.
                   reconcileWorkerPin(agentId, null, false)
@@ -27512,7 +28923,7 @@ void (async () => {
               // suppresses stale-after-restart delivery (a 4-h-old
               // "still working (5m)" would be a lie). Sweep on handback
               // lives in the `onFinish` block just above.
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model }) => {
                 let fleetChatId = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
@@ -27546,6 +28957,13 @@ void (async () => {
                 // never grew past "starting…" (the frozen-card symptom). The
                 // foreground nest path below already used this precedence.
                 const stepLine = (progressLine != null && progressLine.length > 0) ? progressLine : latestSummary
+                // Live model for the worker card: prefer the transcript-sourced
+                // model on the entry (threaded via onProgress) and fall back to
+                // the dispatch-time model persisted on the registry row
+                // (tool_input.model) until the worker's first assistant line
+                // lands. Undefined when neither is known — the card omits it,
+                // never guessing from config.
+                const feedModel = model ?? dispatch.feedModel ?? undefined
                 if (!isBackground) {
                   // Model A — a foreground sub-agent runs inside the parent's
                   // turn, so its live narrative nests under the parent's
@@ -27585,6 +29003,7 @@ void (async () => {
                         latestSummary: stepLine,
                         elapsedMs,
                         state: 'running',
+                        model: feedModel,
                       },
                       wk.threadId,
                     )?.then(() => reconcileWorkerPin(agentId, wkChat, true))
@@ -27726,6 +29145,7 @@ void (async () => {
                       latestSummary: stepLine,
                       elapsedMs,
                       state: 'running',
+                      model: feedModel,
                     },
                     wk.threadId,
                   )?.then(() => reconcileWorkerPin(agentId, wkChat, true))