switchroom 0.18.9 → 0.18.10

package/telegram-plugin/gateway/gateway.ts

@@ -41,6 +41,7 @@ import {
   resolveInterruptMaxWaitMs,
   resolveSafeBoundaryEnabled,
 } from './interrupt-defer.js'
+import { parseStopKeyword, buildStopReply } from './stop-command.js'
 import { shouldPostBusyAck, formatBusyAckText, BUSY_ACK_STEP_AGE_THRESHOLD_MS } from './busy-ack.js'
 import {
   resolveStickerSendArgs,
@@ -123,6 +124,7 @@ import {
   approvalTtlMs,
   ttlForTool,
   buildTimedOutCardEdits,
+  buildCancelledCardEdits,
   STALE_TAP_NOTICE,
   type PermissionCardRef,
 } from './permission-timeout.js'
@@ -183,7 +185,9 @@ import {
   createRetryApiCall,
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
+  isPhotoDimensionRejectError,
 } from '../retry-api-call.js'
+import { classifyPhotoFile, rerouteResultSuffix } from '../photo-precheck.js'
 import { installTgPostLogger, withTgPostTags } from '../shared/bot-runtime.js'
 import { floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
 import { buildAttachmentPath, assertInsideInbox } from '../attachment-path.js'
@@ -387,11 +391,14 @@ import {
   MODEL_CALLBACK_PREFIX,
   MODEL_CALLBACK_HEADER,
   MODEL_CALLBACK_SR,
+  MODEL_CALLBACK_ALIAS,
   MODEL_CALLBACK_PAGE_EXTERNAL,
   MODEL_CALLBACK_PAGE_MAIN,
   srFriendlyLabel,
   expandSrAlias,
   isSrModel,
+  isBusyRefusalText,
+  isOfflineTrustedModelToken,
   type ModelMenuDeps,
   type ModelCommandDeps,
   type ModelMenuReply,
@@ -405,9 +412,16 @@ import {
   writeRelaunchModelIntent,
   clearRelaunchModelIntent,
   intentForRestartReason,
+  readSessionModelFile,
+  RELAUNCH_MODEL_INTENT_FILE,
+  GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX,
+  clearStaleGatewayShutdownIntent,
+  writeSessionEffortFile,
+  clearSessionEffortFile,
+  readSessionEffortFile,
 } from './session-model-file.js'
 import { discoverModels, selectModel } from '../../src/agents/model-picker.js'
-import { resolveMainModel } from '../../src/agents/scaffold.js'
+import { resolveMainModel, SWITCHROOM_DEFAULT_THINKING_EFFORT } from '../../src/agents/scaffold.js'
 import {
   parseEffortCommand,
   handleEffortCommand,
@@ -417,6 +431,18 @@ import {
   type EffortCommandDeps,
   type EffortMenuReply,
 } from './effort-command.js'
+import {
+  createPendingSessionCommandSlots,
+  drainCapDecision as pendingCmdDrainCapDecision,
+  shutdownResolutionActions as pendingCmdShutdownResolutionActions,
+  resolveForRestart as pendingCmdResolveForRestart,
+  drainTakenCommands as pendingCmdDrainTaken,
+  type ShutdownResolutionAction,
+  ackText as pendingCmdAckText,
+  supersededText as pendingCmdSupersededText,
+  type PendingSessionCommand,
+} from './pending-session-command.js'
+import type { EffortLevel } from './effort-command.js'
 import { registerSwitchroomBotCommands } from './register-bot-commands.js'
 import { registerOpsInfoCommands } from './bot-commands-ops-info.js'
 import { applyEffort } from '../../src/agents/effort-picker.js'
@@ -657,7 +683,14 @@ import {
   buildQuotaClaimKey,
   QUOTA_WATCH_CLAIM_WINDOW_MS,
   isLiveCorroboration,
+  evaluateFleetRollAnnounce,
+  FLEET_ROLL_ANNOUNCE_KEY,
 } from '../quota-watch.js'
+import {
+  createModelUnavailableCardRegistry,
+  decideAnnouncementDelivery,
+  foldAnnouncementIntoCard,
+} from '../fallback-card-collapse.js'
 import { buildSnapshotsFromState, buildSnapshotsFromCachedState, zipProbeResults } from '../auth-snapshot-format.js'
 import { maskUsername } from '../demo-mask.js'
 import {
@@ -711,6 +744,13 @@ import {
   buildResumeDeferredReportInbound,
   decideBootResumeKind,
 } from './resume-inbound-builder.js'
+import {
+  createBridgeDeadWatchdog,
+  consumeBridgeDeadEscalationMarker,
+  buildBridgeDeadIdleNoticeInbound,
+  DEFAULT_BRIDGE_DEAD_GRACE_MS,
+} from './bridge-dead-watchdog.js'
+import { findAgentProcessInContainer } from './boot-probes.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'
@@ -966,6 +1006,24 @@ function triggerSelfRestart(
   }
 }
 
+// #3018 finding 4: a gateway-only bounce (supervisor relaunch, bare gateway
+// unit restart) leaves the shutdown handler's deploy-survival keep-intent
+// stamp on disk UNCONSUMED — start.sh only runs on a container-level boot.
+// If this gateway boot still sees a gateway-shutdown-stamped intent, the
+// preceding bounce was gateway-only: clear it so a genuine crash inside the
+// 10-min freshness window can't be converted into a "keep" (crash-reverts
+// policy intact). A real container stop/deploy consumes the file in start.sh
+// before any gateway boots, so a legitimate deploy stamp is never touched;
+// triggerSelfRestart / user-slash stamps use un-prefixed reasons.
+{
+  const bootSmDir = resolveAgentDirFromEnv()
+  if (bootSmDir != null && clearStaleGatewayShutdownIntent(bootSmDir)) {
+    process.stderr.write(
+      'telegram gateway: cleared stale gateway-shutdown relaunch-model intent (previous bounce was gateway-only — container never restarted)\n',
+    )
+  }
+}
+
 // Cached lazily — the claude CLI binary doesn't change inside a running
 // gateway process; on `switchroom update` the gateway restarts, refreshing this.
 let cachedClaudeCliVersion: string | null | undefined = undefined
@@ -1485,6 +1543,10 @@ let turnsDb: ReturnType<typeof openTurnsDb> | null = null
 // Stashed here; pushed to the spool once it's constructed below. The spool's
 // turn_key-keyed dedup makes a re-stash across multiple restarts a no-op.
 let bootResumeInbound: { agent: string; msg: InboundMessage } | null = null
+// #3038 cross-boot damper: consecutive bridge-dead escalations by PRIOR
+// boots (the consumed marker's `count`; 0 when no fresh marker). Set in
+// the boot block below, consumed by the watchdog constructor further down.
+let bridgeDeadPriorStreak = 0
 try {
   // STATE_DIR is `<agentDir>/telegram` in production. openTurnsDb expects
   // the parent (agent dir) and joins `telegram/registry.db` itself.
@@ -1540,6 +1602,32 @@ try {
     process.stderr.write(`telegram gateway: turn-registry initialized at ${join(agentDir, 'telegram', 'registry.db')}\n`)
   }
 
+  // #3038 — bridge-dead escalation marker. If the PREVIOUS gateway bounced
+  // this container because the MCP bridge died (see bridge-dead-watchdog.ts),
+  // it left a marker so THIS boot's resume inbound can state the real cause
+  // instead of implying an operator restart or a watchdog timeout. Consumed
+  // (always cleared) whether or not a turn was in flight.
+  const bridgeDeadMarker = consumeBridgeDeadEscalationMarker(
+    join(STATE_DIR, 'bridge-dead-escalation.json'),
+  )
+  if (bridgeDeadMarker != null) {
+    bridgeDeadPriorStreak = bridgeDeadMarker.count ?? 1
+    process.stderr.write(
+      `telegram gateway: boot: prior restart was a bridge-dead escalation (reason=${bridgeDeadMarker.reason}` +
+      `, consecutive=${bridgeDeadPriorStreak}` +
+      `${bridgeDeadMarker.crashTail ? `, crashTail=${bridgeDeadMarker.crashTail}` : ''})\n`,
+    )
+  }
+  const bridgeDeadRestartCause = bridgeDeadMarker != null
+    ? {
+        reason: bridgeDeadMarker.reason,
+        note:
+          'The framework itself triggered this restart: your Telegram MCP bridge process had died ' +
+          '(chat tools were unavailable — you could not send replies), so the container was bounced ' +
+          'to restore the chat surface. This was NOT an operator-initiated restart and NOT a hang-watchdog kill.',
+      }
+    : undefined
+
   // Build the boot resume/report inbound for the LATEST turn if it was
   // interrupted. selectResumeBuilder owns the resume-vs-report policy.
   const pending = findLatestTurnIfInterrupted(turnsDb)
@@ -1613,7 +1701,11 @@ try {
     if (bootResumeKind === 'resume') {
       bootResumeInbound = {
         agent: selfAgent,
-        msg: buildResumeInterruptedInbound({ turn: pending, subagents: interruptedSubagents }),
+        msg: buildResumeInterruptedInbound({
+          turn: pending,
+          subagents: interruptedSubagents,
+          restartCause: bridgeDeadRestartCause,
+        }),
       }
     } else if (bootResumeKind === 'report') {
       // idleMs: this boot's measured marker age if it just classified this
@@ -1629,7 +1721,12 @@ try {
       if (idleMs == null) idleMs = Math.max(0, Date.now() - pending.started_at)
       bootResumeInbound = {
         agent: selfAgent,
-        msg: buildResumeWatchdogReportInbound({ turn: pending, idleMs, subagents: interruptedSubagents }),
+        msg: buildResumeWatchdogReportInbound({
+          turn: pending,
+          idleMs,
+          subagents: interruptedSubagents,
+          restartCause: bridgeDeadRestartCause,
+        }),
       }
     } else if (bootResumeKind === 'defer-loop' || bootResumeKind === 'defer-suppressed') {
       // Passive deferred-report: work was in flight but we decline to
@@ -1641,6 +1738,7 @@ try {
           turn: pending,
           reason: bootResumeKind === 'defer-loop' ? 'loop-guard' : 'clean-restart-suppressed',
           subagents: interruptedSubagents,
+          restartCause: bridgeDeadRestartCause,
         }),
       }
     }
@@ -1665,6 +1763,38 @@ try {
     }
   }
 
+  // #3038 review finding 2 — idle-case honesty. When the previous boot was
+  // a bridge-dead escalation but NO turn was interrupted (idle agent, dead
+  // bridge), the consumed marker's cause would otherwise reach stderr only:
+  // the agent and the user never learn why the container bounced. Surface
+  // it once, via the same boot-inbound channel the resume path uses, routed
+  // to the agent's default/owner chat.
+  if (bridgeDeadMarker != null && bootResumeInbound == null && selfAgent) {
+    const idleNoticeChat = (() => {
+      try {
+        return loadAccess().allowFrom[0] ?? null
+      } catch {
+        return null
+      }
+    })()
+    if (idleNoticeChat != null) {
+      bootResumeInbound = {
+        agent: selfAgent,
+        msg: buildBridgeDeadIdleNoticeInbound({
+          chatId: String(idleNoticeChat),
+          marker: bridgeDeadMarker,
+        }),
+      }
+      process.stderr.write(
+        `telegram gateway: boot: bridge-dead idle notice queued chat=${idleNoticeChat} (no turn was in flight)\n`,
+      )
+    } else {
+      process.stderr.write(
+        `telegram gateway: boot: bridge-dead idle notice skipped — no allowFrom chat to surface it in\n`,
+      )
+    }
+  }
+
   // Diagnostic env file (one-shot, sourced by start.sh) — kept for the
   // wake-audit context. The injected inbound above is the real wake signal;
   // these vars are passive context only.
@@ -2619,6 +2749,19 @@ async function deliverButtonTapInbound(
 
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
 
+// Deterministic ack-queue-apply-confirm for /model + /effort issued mid-turn
+// (#3017). One slot per kind (model|effort): same-kind last-write-wins,
+// cross-kind coexist (#3018 finding 2). Enqueued at the busy gates (typed
+// and menu), drained at the SAME model-idle gate as pendingRestarts (turn
+// complete + the reaper cap), which then EDITS the ack card into the
+// confirmation. See pending-session-command.ts for the contract.
+const pendingSessionCommand = createPendingSessionCommandSlots()
+// Bounded drain-cap for a queued /model|/effort command whose session never
+// cleanly idles — mirrors PENDING_RESTART_DRAIN_CAP_MS. After this, force the
+// apply-or-report so the ack card never dangles unresolved — but ONLY while
+// no turn is in flight (#3018 finding 1; see drainCapDecision).
+const PENDING_CMD_DRAIN_CAP_MS = 60_000
+
 // ─── Proactive context compaction (session.max_context_tokens) ──────────
 //
 // Opt-in: when the resolved agent config sets session.max_context_tokens,
@@ -3766,6 +3909,194 @@ async function fireDeferredInterrupt(reason: 'boundary' | 'timeout'): Promise<vo
   }
 }
 
+// #3020 — halt-now (the operator kill switch: empty `!`, `/stop`, bare "stop").
+//
+// Unlike a `!` interrupt WITH a body (which stashes a replacement inbound in
+// `pendingDeferredInterrupt` and re-delivers it), a halt has no replacement:
+// the operator just wants the in-flight turn dead. Shared sequence:
+//   1. Honor the safe-boundary deferral (same `decideInterruptTiming` +
+//      max-wait config the `!` path uses) so we don't C-c mid-tool-call.
+//   2. SIGINT via tmux send-keys (`sendAgentInterrupt`) — the same primitive
+//      the `!` path fires.
+//   3. Cancel the killed turn's obligation (the user explicitly cancelled it;
+//      re-presenting it later would be wrong).
+//   4. Deterministically release the turn's busy state. With no replacement
+//      inbound there is no later event guaranteed to end the turn — an
+//      interrupted claude turn may never emit `turn_end`, and leaning on the
+//      busy-key reaper leaves the chat gated for minutes. Same primitives
+//      the reply path uses (`endCurrentTurnAtomic` + `releaseTurnBufferGate`),
+//      both idempotent, reaper stays as backstop. The obligation cancel in
+//      step 3 runs FIRST so `endCurrentTurnAtomic`'s no-reply branch is a
+//      ledger no-op instead of stamping a grace clock on a cancelled turn.
+//
+// The boundary wait is event-driven: `waitForSafeBoundary` parks a waiter
+// that the session-event ingest kicks (`notifyHaltBoundaryWaiters`) whenever
+// the tracker might have drained, with the configured max-wait as the bound.
+
+const haltBoundaryWaiters = new Set<() => void>()
+
+function notifyHaltBoundaryWaiters(): void {
+  if (haltBoundaryWaiters.size === 0) return
+  for (const check of [...haltBoundaryWaiters]) check()
+}
+
+function waitForSafeBoundary(maxWaitMs: number): Promise<'boundary' | 'timeout'> {
+  if (!toolFlightTracker.isMidToolCall()) return Promise.resolve('boundary')
+  return new Promise(resolve => {
+    let done = false
+    const finish = (reason: 'boundary' | 'timeout') => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      haltBoundaryWaiters.delete(check)
+      resolve(reason)
+    }
+    const timer = setTimeout(() => finish('timeout'), maxWaitMs)
+    const check = () => {
+      if (!toolFlightTracker.isMidToolCall()) finish('boundary')
+    }
+    haltBoundaryWaiters.add(check)
+  })
+}
+
+// #3020 item 4 — a halted turn may be suspended INSIDE an MCP permission
+// call with a live Approve/Deny card in chat. The card's pending entry keeps
+// the buffer gate closed (`hasPendingApproval`), and a later Approve tap
+// would dispatch a verdict into an idle session. Deny each pending request
+// (unblocking the suspended call before/as the C-c lands) and edit its
+// card(s) to a cancelled state with the keyboard stripped.
+function cancelPendingPermissionsForHalt(origin: string): void {
+  if (pendingPermissions.size === 0) return
+  for (const [requestId, details] of pendingPermissions) {
+    // halted-turn-verdict: the turn this card parked is being KILLED by the
+    // operator — there is nothing to resume, so no resumeReactionAfterVerdict
+    // / postPermissionResumeMessage pairing. The card edit ("⏹ Cancelled")
+    // is the visible terminal state and the /stop reply is the operator ack.
+    dispatchPermissionVerdict({
+      type: 'permission',
+      requestId,
+      behavior: 'deny',
+      message: 'Cancelled — the operator stopped this turn. Do not retry.',
+    })
+    void stripCancelledPermissionCards(details.card_text, details.cards)
+    pendingPermissions.delete(requestId)
+    permCardStore.remove(requestId)
+    process.stderr.write(
+      `telegram gateway: halt-now cancelled pending permission origin=${origin} ` +
+      `request=${requestId} tool=${details.tool_name}\n`,
+    )
+  }
+}
+
+async function stripCancelledPermissionCards(
+  cardText: string,
+  cards: PermissionCardRef[],
+): Promise<void> {
+  for (const edit of buildCancelledCardEdits(cardText, cards)) {
+    await swallowingApiCall(
+      // allow-raw-bot-api: routed through swallowingApiCall (retry policy); message-id-targeted edit (no thread to lose). Passing {} as opts (no reply_markup) strips the stale Allow/Deny keyboard atomically with the text edit.
+      () => bot.api.editMessageText(edit.chatId, edit.messageId, richMessage(edit.text), {}),
+      { chat_id: edit.chatId, verb: 'permission_halt.strip' },
+    )
+  }
+}
+
+async function executeHaltNow(origin: string): Promise<void> {
+  const agentName = process.env.SWITCHROOM_AGENT_NAME
+  if (!agentName) return
+  // #3020 item 3 — snapshot the halt target at request entry. The boundary
+  // wait below can park for seconds; if the targeted turn ends naturally in
+  // that window and a NEW turn starts, firing the C-c would kill an innocent
+  // turn the requester never saw. Identity is the currentTurn object itself
+  // (registryKey included, for the log line).
+  const haltTarget = currentTurn
+  const haltTargetKey = haltTarget?.registryKey ?? null
+  const access = loadAccess()
+  const timing = decideInterruptTiming({
+    safeBoundaryEnabled: resolveSafeBoundaryEnabled(access.interruptSafeBoundary),
+    midToolCall: toolFlightTracker.isMidToolCall(),
+  })
+  const startedAt = Date.now()
+  if (timing === 'defer') {
+    const maxWaitMs = resolveInterruptMaxWaitMs(access.interruptMaxWaitMs)
+    const reason = await waitForSafeBoundary(maxWaitMs)
+    process.stderr.write(
+      `telegram gateway: halt-now boundary-wait origin=${origin} reason=${reason} ` +
+      `waited_ms=${Date.now() - startedAt} in_flight=${toolFlightTracker.inFlightCount()}\n`,
+    )
+  }
+  // #3020 item 3 — wrong-turn kill guard: if the turn changed while we
+  // waited (the target ended naturally; a new turn may already be running),
+  // no-op the C-c AND the teardown — the requester's turn already ended and
+  // the current busy/permission state belongs to someone else. This also
+  // skips the benign-but-pointless idle-session C-c when target-ended → idle.
+  if (currentTurn !== haltTarget) {
+    process.stderr.write(
+      `telegram gateway: halt-now skipped — turn changed during boundary wait ` +
+      `origin=${origin} target_key=${haltTargetKey ?? 'none'} ` +
+      `current_key=${currentTurn?.registryKey ?? 'none'}\n`,
+    )
+    return
+  }
+  try {
+    // Same tmux-direct rationale as the `!` path: the gateway runs inside the
+    // agent container, so PID-probing interruptAgent can't work — send-keys can.
+    const { sendAgentInterrupt } = await import('../../src/agents/tmux.js')
+    const r = sendAgentInterrupt({ agentName })
+    if ('ok' in r) {
+      process.stderr.write(
+        `telegram gateway: halt-now SIGINT delivered via tmux send-keys origin=${origin} agent=${agentName}\n`,
+      )
+    } else {
+      process.stderr.write(
+        `telegram gateway: halt-now SIGINT via tmux failed origin=${origin} agent=${agentName}: ${r.error}\n`,
+      )
+    }
+  } catch (err) {
+    process.stderr.write(`telegram gateway: halt-now SIGINT failed origin=${origin}: ${(err as Error).message}\n`)
+  }
+  // The SIGINT just killed the in-flight turn — cancel its obligation so the
+  // cancelled question isn't re-presented/escalated later. Must run before the
+  // teardown below (it reads `currentTurn`).
+  cancelInterruptedObligation()
+  // Item 4 — deny + strip any Approve/Deny cards belonging to the halted
+  // turn so the buffer gate (`hasPendingApproval`) opens and a later tap
+  // can't dispatch into an idle session.
+  cancelPendingPermissionsForHalt(origin)
+  // Deterministic busy release (step 4 above).
+  const turn = currentTurn
+  if (turn != null) {
+    // Stamp the registry row as a CLEAN end (`endedVia: 'stop'`). A killed
+    // turn never emits the session `turn_end` event, so without this the row
+    // stays open (`ended_at IS NULL`) and `findLatestTurnIfInterrupted` would
+    // fire a resume_interrupted synthetic for it at the next boot — resuming
+    // work the operator explicitly cancelled. 'stop' is the resume gate's
+    // "ended cleanly" verdict, which is exactly what a deliberate cancel is.
+    if (turnsDb != null && turn.registryKey != null) {
+      const _turnKey = turn.registryKey
+      try {
+        recordTurnEnd(turnsDb, {
+          turnKey: _turnKey,
+          endedVia: 'stop' as const,
+          lastAssistantMsgId: turn.lastAssistantMsgId,
+          lastAssistantDone: turn.lastAssistantDone,
+          toolCallCount: turn.toolCallCount,
+        })
+      } catch (err) {
+        process.stderr.write(`telegram gateway: recordTurnEnd(halt) failed turnKey=${_turnKey}: ${(err as Error).message}\n`)
+      }
+    }
+    const key = statusKey(turn.sessionChatId, turn.sessionThreadId)
+    endCurrentTurnAtomic(turn)
+    releaseTurnBufferGate(key, turn)
+  }
+  // #3020 item 5 — the busy release above may have opened the idle gate, and
+  // no turn_end event follows a halt to trigger the usual idle-drain hook.
+  // Kick the queued session-command drain now so a queued /model or /effort
+  // applies promptly instead of waiting for the 60s reaper.
+  if (!turnInFlightForGate()) void drainPendingSessionCommand()
+}
+
 // #549 fix — preamble suppression for the answer-stream path.
 //
 // Background: assistant text emitted before a tool_use is "preamble"
@@ -4103,6 +4434,13 @@ function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
   // serialize gate): a pending self-restart or proactive compaction must
   // fire when claude is idle regardless of whether the last turn replied.
   if (!turnInFlightForGate()) {
+    // Apply any /model|/effort command queued mid-turn (#3017) BEFORE the
+    // restart drain reads the pending-restart map — drainPendingSessionCommand
+    // itself checks pendingRestarts and, when a restart is also pending,
+    // reports "restarting" on the ack card instead of a false confirmation.
+    // The sr-*→Claude menu apply may ITSELF enqueue a restart, which the
+    // restart drain below then picks up. Async + best-effort (own try/catch).
+    void drainPendingSessionCommand()
     if (pendingRestarts.size > 0) {
       for (const [agentName, _timestamp] of pendingRestarts.entries()) {
         triggerSelfRestart(agentName, 'turn-complete-pending-restart');
@@ -6389,6 +6727,34 @@ const pendingStateReaper = setInterval(() => {
       triggerSelfRestart(agentName, 'restart-drain-cap-forced', 100)
     }
   }
+  // Drain cap for queued /model|/effort commands (#3017): if the session
+  // never cleanly idled, force the apply-or-report so the ack card never
+  // dangles unresolved. drainPendingSessionCommand no-ops on an idle-gate race
+  // (its own re-entrancy guard) and reports honestly when a restart is pending.
+  // #3018 finding 1: NEVER force while a turn is genuinely in flight — a
+  // forced mid-turn drain hits the typed model handler's busy gate (edits the
+  // ack card into the old "try again" refusal, choice destroyed) and /effort
+  // has no busy gate at all (would type into the live claude input). The cap
+  // only rescues the missed-idle-gate case; mid-turn we keep waiting and the
+  // idle gate drains at turn end.
+  const queuedCmds = pendingSessionCommand.list()
+  const cmdDecision = pendingCmdDrainCapDecision(
+    queuedCmds,
+    now,
+    PENDING_CMD_DRAIN_CAP_MS,
+    turnInFlightForGate(),
+  )
+  if (cmdDecision === 'defer-turn-in-flight') {
+    process.stderr.write(
+      `telegram gateway: [pending-cmd-drain] deferred reason=turn-in-flight queued=${queuedCmds.map(c => c.kind).join(',')}\n`,
+    )
+  } else if (cmdDecision === 'force') {
+    const oldest = Math.min(...queuedCmds.map(c => c.requestedAt))
+    process.stderr.write(
+      `telegram gateway: [pending-cmd-drain] forcing queued=${queuedCmds.map(c => `${c.kind}:${c.targetLabel}`).join(',')} waited=${Math.round((now - oldest) / 1000)}s threshold=${Math.round(PENDING_CMD_DRAIN_CAP_MS / 1000)}s\n`,
+    )
+    void drainPendingSessionCommand()
+  }
 }, 60_000)
 pendingStateReaper.unref()
 
@@ -6560,6 +6926,10 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
   const modelUnavailable = resolveModelUnavailableFromOperatorEvent(event)
   let renderedText: string
   let renderedKeyboard: ReturnType<typeof renderOperatorEvent>['keyboard'] | undefined
+  // #3031 PR 3 — when the card promises an in-flight auto-failover, record
+  // each per-chat send in the collapse registry so a SUCCESSFUL swap edits
+  // the card (single evolving message) instead of sending a second one.
+  let cardPromisedFallback = false
   if (modelUnavailable) {
     // Two questions, asked synchronously to avoid the "card promises
     // an announcement that never arrives" trap:
@@ -6584,6 +6954,7 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
       autoFallbackInFlight: willActuallyFire,
     })
     renderedKeyboard = undefined
+    cardPromisedFallback = willActuallyFire
     // Trigger fleet-wide auto-fallback. Pre-fix this branch only
     // rendered the card; the fallback machinery was unreachable from
     // here. We fire-and-forget so card delivery is never blocked on
@@ -6654,11 +7025,26 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // very next line is what unlocks the raw bot.api call.
     // Opts now includes message_thread_id when supergroup mode is on.
     // allow-raw-bot-api: operator-event broadcast loop; topic-aware opts
-    void bot.api.sendRichMessage(chat_id, richMessage(renderedText), opts as never).catch(e => {
-      process.stderr.write(
-        `telegram gateway: operator-event send to ${chat_id} failed agent=${agent} kind=${kind}: ${e}\n`,
-      )
-    })
+    void bot.api.sendRichMessage(chat_id, richMessage(renderedText), opts as never)
+      .then((sent: { message_id: number }) => {
+        // #3031 PR 3 — remember the fallback-promising card so the swap
+        // announcement can EDIT it (collapse) instead of sending anew.
+        // Recorded only after the send resolves (we need the message_id);
+        // the collapse path degrades to a plain send when no record exists.
+        if (cardPromisedFallback) {
+          modelUnavailableCardRegistry.record(String(chat_id), {
+            messageId: sent.message_id,
+            text: renderedText,
+            atMs: Date.now(),
+            promisedFallback: true,
+          })
+        }
+      })
+      .catch(e => {
+        process.stderr.write(
+          `telegram gateway: operator-event send to ${chat_id} failed agent=${agent} kind=${kind}: ${e}\n`,
+        )
+      })
   }
 }
 
@@ -8789,6 +9175,51 @@ async function stripStalePermissionCard(card: PersistedPermCard): Promise<void>
   }
 }
 
+// ─── #3038 — bridge-dead watchdog ────────────────────────────────────────
+// When the gateway (re)starts, the MCP bridge inside the running claude
+// session normally re-registers on the IPC socket within seconds. If it
+// died with the previous gateway (Claude Code never respawns a dead MCP
+// server), the session stays alive but toolless/mute forever. This
+// watchdog escalates: no real bridge registered within the grace window
+// while claude is alive → bounce the container once (reason
+// 'bridge-dead-resume') so the MCP server respawns. See
+// bridge-dead-watchdog.ts for the guard rails.
+// Config: SWITCHROOM_BRIDGE_DEAD_GRACE_MS (default 90s),
+// SWITCHROOM_BRIDGE_DEAD_ESCALATION=0 disables.
+const BRIDGE_DEAD_ESCALATION_ENABLED = process.env.SWITCHROOM_BRIDGE_DEAD_ESCALATION !== '0'
+const BRIDGE_DEAD_GRACE_MS = (() => {
+  const v = Number(process.env.SWITCHROOM_BRIDGE_DEAD_GRACE_MS)
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_BRIDGE_DEAD_GRACE_MS
+})()
+const bridgeDeadWatchdog = createBridgeDeadWatchdog({
+  graceMs: BRIDGE_DEAD_GRACE_MS,
+  // Require a CONFIDENT claude match (comm === 'claude'), not
+  // findAgentProcessInContainer's heaviest-node fallback: an orphaned or
+  // unrelated node process must never flip a "claude not up" retry into a
+  // container bounce (#3038 review finding 4). False negatives are safe —
+  // the watchdog then retries forever instead of escalating.
+  isSessionAlive: () => findAgentProcessInContainer()?.comm === 'claude',
+  // `shuttingDown` is declared (let, module scope) further down this file;
+  // the closure only runs when the grace timer fires, long after module
+  // init completes, so the TDZ is never hit.
+  isShuttingDown: () => shuttingDown,
+  escalate: (reason) =>
+    triggerSelfRestart(process.env.SWITCHROOM_AGENT_NAME ?? '', reason, 1500),
+  crashLogPath: join(STATE_DIR, 'bridge-crash.log'),
+  markerPath: join(STATE_DIR, 'bridge-dead-escalation.json'),
+  log: (line) => process.stderr.write(`${line}\n`),
+  // Cross-boot damper (#3038 review finding 1): the consumed marker's
+  // consecutive-escalation count. At the cap, arm() stands down loudly
+  // instead of restart-looping a deterministically-failing bridge.
+  priorStreak: bridgeDeadPriorStreak,
+})
+if (BRIDGE_DEAD_ESCALATION_ENABLED) {
+  bridgeDeadWatchdog.arm()
+  process.stderr.write(
+    `telegram gateway: [bridge-dead-watchdog] armed (grace=${BRIDGE_DEAD_GRACE_MS}ms)\n`,
+  )
+}
+
 const ipcServer: IpcServer = createIpcServer({
   socketPath: SOCKET_PATH,
 
@@ -8818,6 +9249,13 @@ const ipcServer: IpcServer = createIpcServer({
     const bridgeUpEffects = client.agentName != null
       ? shadowEmit({ kind: 'bridgeUp', at: Date.now() })
       : []
+    // #3038 — a REAL (named, non-cron) bridge registered: stand the
+    // bridge-dead watchdog down. Anonymous clients (recall.py, mcp
+    // handshakes) and cron-session bridges must NOT satisfy it — the
+    // watchdog gates on the identity INTERNALLY (isRealBridgeIdentity), so
+    // this call is safe wherever it sits relative to the cron early-return
+    // above (#3038 review finding 5).
+    bridgeDeadWatchdog.noteBridgeRegistered(client.agentName)
     client.send({ type: 'status', status: 'agent_connected' })
 
     // Phase 2b PR 3a — bridgeUp cutover. The state machine's `bridgeUp`
@@ -9007,6 +9445,12 @@ const ipcServer: IpcServer = createIpcServer({
     if (client.agentName != null) {
       process.stderr.write(`telegram gateway: bridge disconnected — agent=${client.agentName}\n`)
       shadowEmit({ kind: 'bridgeDown', at: Date.now() })
+      // #3038 — the real bridge went away mid-life. Re-arm the grace
+      // window: a normal claude restart re-registers within seconds and
+      // stands it down; a bridge that died for good escalates once (the
+      // once-per-boot fuse inside the watchdog caps it). Cron/anonymous
+      // identities are ignored inside the watchdog itself (finding 5).
+      if (BRIDGE_DEAD_ESCALATION_ENABLED) bridgeDeadWatchdog.noteBridgeDisconnected(client.agentName)
     }
 
     // Scope the flush to clients that actually registered as an agent.
@@ -9094,6 +9538,9 @@ const ipcServer: IpcServer = createIpcServer({
     if (pendingDeferredInterrupt != null && !toolFlightTracker.isMidToolCall()) {
       void fireDeferredInterrupt('boundary')
     }
+    // #3020: a parked halt-now (/stop, bare "stop", empty `!`) waits on the
+    // same boundary — kick its waiters whenever the tracker may have drained.
+    notifyHaltBoundaryWaiters()
     // #1122 silence-poke: surface activity signals from the session
     // stream so the 300s framework-fallback message wording is honest
     // (thinking vs working, plus the longest-running in-flight tool).
@@ -11711,35 +12158,111 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     }
   }
 
+  // #3033 layer-2 (pre-send validation): probe each photo-extension file
+  // BEFORE it hits the wire and pre-route any that Telegram's photo path
+  // would reject (extreme aspect ratio, width+height over cap, >10MB) as
+  // documents. One bad photo fails a WHOLE sendMediaGroup album with an
+  // opaque 400 — catching it here keeps the good files deliverable and
+  // sends the offender as a document on the first attempt. Probe
+  // failures keep the photo route; the reactive #3022 fallback backstops.
+  const photoPrecheck = new Map<string, ReturnType<typeof classifyPhotoFile>>()
+  // #3038 polish: files that ultimately went out as documents despite a
+  // photo extension (precheck reroute or reactive fallback). Feeds two
+  // honesty surfaces: the reply tool result suffix (so the agent doesn't
+  // claim an inline image rendered) and attachment_kinds history (record
+  // what was actually sent).
+  const documentReroutes: Array<{ path: string; reason: string }> = []
+  const sentAsDocument = new Set<string>()
+  for (const f of files) {
+    if (!PHOTO_EXTS.has(extname(f).toLowerCase())) continue
+    const cls = classifyPhotoFile(f)
+    photoPrecheck.set(f, cls)
+    if (cls.route === 'document') {
+      documentReroutes.push({ path: f, reason: cls.reason })
+      sentAsDocument.add(f)
+      process.stderr.write(
+        `telegram gateway: photo-precheck rerouting ${f} as document (${cls.reason})\n`,
+      )
+    }
+  }
+  const sendableAsPhoto = (f: string) =>
+    PHOTO_EXTS.has(extname(f).toLowerCase()) && photoPrecheck.get(f)?.route !== 'document'
+
   // #273: when files is 2-10 photos, batch them into a single
   // sendMediaGroup album rather than N separate sendPhoto calls. The
   // user's device fires one notification for the album instead of N
   // (notification-budget protection per the issue's JTBD note). Falls
   // back to the per-file path for any non-all-photo set.
+  //
+  // #3038 known tradeoff: ONE precheck-rerouted photo in the set drops
+  // the WHOLE album to per-file sends — the user gets N notifications
+  // instead of 1. Deliberate: sendMediaGroup can't mix photo and
+  // document media, and a partial album plus a stray document is more
+  // confusing than N files. Revisit only if mixed albums become common.
   const allPhotos = files.length >= 2 && files.length <= 10
-    && files.every((f) => PHOTO_EXTS.has(extname(f).toLowerCase()))
+    && files.every(sendableAsPhoto)
   // #1075: thread-id-bearing file sends. Mirror the chunk-loop's
   // THREAD_NOT_FOUND fallback (deleted topic → drop the thread and
   // resend on the main chat) so an attachment-bearing reply doesn't
   // crash when the user deletes the topic mid-flight.
   const replyParams =
     reply_to != null && replyMode !== 'off' ? { reply_parameters: { message_id: reply_to } } : {}
-  if (allPhotos) {
-    const media = files.map((f) => ({
-      type: 'photo' as const,
-      media: new InputFile(f),
-    }))
-    const sent = await retryWithThreadFallback(
+  // Send one file as a document, routed through the same thread-fallback
+  // policy as the photo path. `InputFile` streams are single-use, so a
+  // document retry after a failed sendPhoto must build a FRESH InputFile
+  // from the path. Returns the sent message (with its echoed thread id).
+  const sendAsDocument = (f: string) =>
+    retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
       robustApiCall,
       (tid) => {
         const baseOpts = {
           ...replyParams,
           ...(tid != null ? { message_thread_id: tid } : {}),
         }
-        return lockedBot.api.sendMediaGroup(chat_id, media, baseOpts)
+        // allow-raw-bot-api: wrapped in retryWithThreadFallback (retry policy); topic-aware document fallback
+        return lockedBot.api.sendDocument(chat_id, new InputFile(f), baseOpts)
       },
-      { threadId, chat_id, verb: 'sendMediaGroup' },
+      { threadId, chat_id, verb: 'sendDocument' },
     )
+
+  if (allPhotos) {
+    const media = files.map((f) => ({
+      type: 'photo' as const,
+      media: new InputFile(f),
+    }))
+    let sent: Array<{ message_id: number; message_thread_id?: number }>
+    try {
+      sent = await retryWithThreadFallback(
+        robustApiCall,
+        (tid) => {
+          const baseOpts = {
+            ...replyParams,
+            ...(tid != null ? { message_thread_id: tid } : {}),
+          }
+          return lockedBot.api.sendMediaGroup(chat_id, media, baseOpts)
+        },
+        { threadId, chat_id, verb: 'sendMediaGroup' },
+      )
+    } catch (err) {
+      // Graceful fallback: one bad photo in the album (e.g. a tall phone
+      // screenshot → PHOTO_INVALID_DIMENSIONS) fails the WHOLE media group.
+      // Rather than surface an error, re-send each file individually as a
+      // document so the user still receives all of them. See #klanker
+      // 2026-07-10 incident + isPhotoDimensionRejectError.
+      if (!isPhotoDimensionRejectError(err)) throw err
+      process.stderr.write(
+        `telegram gateway: sendMediaGroup rejected the photo album ` +
+        `(${err instanceof Error ? err.message : String(err)}); ` +
+        `falling back to per-file sendDocument\n`,
+      )
+      sent = []
+      const albumReason = 'Telegram rejected the photo album; whole album re-sent as documents'
+      for (const f of files) {
+        sent.push(await sendAsDocument(f))
+        sentAsDocument.add(f)
+        documentReroutes.push({ path: f, reason: albumReason })
+      }
+    }
     if (threadId != null) {
       // If the fallback dropped the thread id, propagate that decision
       // to subsequent calls in this reply (no further retries needed).
@@ -11752,22 +12275,41 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     for (const m of sent) sentIds.push(m.message_id)
   } else {
     for (const f of files) {
-      const ext = extname(f).toLowerCase()
       const input = new InputFile(f)
-      const isPhoto = PHOTO_EXTS.has(ext)
-      const sent = await retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
-        robustApiCall,
-        (tid) => {
-          const baseOpts = {
-            ...replyParams,
-            ...(tid != null ? { message_thread_id: tid } : {}),
-          }
-          return isPhoto
-            ? lockedBot.api.sendPhoto(chat_id, input, baseOpts)
-            : lockedBot.api.sendDocument(chat_id, input, baseOpts)
-        },
-        { threadId, chat_id, verb: isPhoto ? 'sendPhoto' : 'sendDocument' },
-      )
+      // Photo-ext files that failed the pre-send probe route straight to
+      // sendDocument (see photoPrecheck above) instead of bouncing a 400.
+      const isPhoto = sendableAsPhoto(f)
+      let sent: { message_id: number; message_thread_id?: number }
+      try {
+        sent = await retryWithThreadFallback<{ message_id: number; message_thread_id?: number }>(
+          robustApiCall,
+          (tid) => {
+            const baseOpts = {
+              ...replyParams,
+              ...(tid != null ? { message_thread_id: tid } : {}),
+            }
+            return isPhoto
+              ? lockedBot.api.sendPhoto(chat_id, input, baseOpts)
+              : lockedBot.api.sendDocument(chat_id, input, baseOpts)
+          },
+          { threadId, chat_id, verb: isPhoto ? 'sendPhoto' : 'sendDocument' },
+        )
+      } catch (err) {
+        // Graceful fallback: an image Telegram won't accept as a photo
+        // (dimensions out of range / too large — a tall phone screenshot
+        // is the canonical trigger, PHOTO_INVALID_DIMENSIONS) is re-sent
+        // as a document so the user still receives the file instead of
+        // getting nothing. Non-photo-dimension errors propagate as before.
+        if (!(isPhoto && isPhotoDimensionRejectError(err))) throw err
+        process.stderr.write(
+          `telegram gateway: sendPhoto rejected ${f} ` +
+          `(${err instanceof Error ? err.message : String(err)}); ` +
+          `falling back to sendDocument\n`,
+        )
+        sent = await sendAsDocument(f)
+        sentAsDocument.add(f)
+        documentReroutes.push({ path: f, reason: 'Telegram rejected it as a photo; re-sent as document' })
+      }
       // Mirror the threadId-clear above so the *next* file in the
       // loop skips the doomed thread without paying for another
       // round trip + retry.
@@ -11778,9 +12320,13 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
     }
   }
 
-  const result = sentIds.length === 1
+  // #3038: surface photo→document reroutes in the tool result — the
+  // agent otherwise only "sees" success and may tell the user an inline
+  // image rendered when it went out as a file attachment.
+  const result = (sentIds.length === 1
     ? `sent (id: ${sentIds[0]})`
-    : `sent ${sentIds.length} parts (ids: ${sentIds.join(', ')})`
+    : `sent ${sentIds.length} parts (ids: ${sentIds.join(', ')})`)
+    + rerouteResultSuffix(documentReroutes)
 
   if (HISTORY_ENABLED && sentIds.length > 0) {
     try {
@@ -11790,9 +12336,14 @@ async function executeReply(args: Record<string, unknown>): Promise<{ content: A
       const attachKinds: (string | null)[] = []
       for (let i = 0; i < textCount; i++) { texts.push(chunks[i] ?? ''); attachKinds.push(null) }
       for (let i = 0; i < fileCount; i++) {
-        const ext = extname(files[i] ?? '').toLowerCase()
-        texts.push(`(${PHOTO_EXTS.has(ext) ? 'photo' : 'document'}: ${files[i]})`)
-        attachKinds.push(PHOTO_EXTS.has(ext) ? 'photo' : 'document')
+        const f = files[i] ?? ''
+        const ext = extname(f).toLowerCase()
+        // #3038: record what was ACTUALLY sent — a photo-extension file
+        // rerouted to sendDocument (precheck or reactive fallback) is a
+        // 'document' in history, not a 'photo' from its raw extension.
+        const kind = PHOTO_EXTS.has(ext) && !sentAsDocument.has(f) ? 'photo' : 'document'
+        texts.push(`(${kind}: ${f})`)
+        attachKinds.push(kind)
       }
       recordOutbound({ chat_id, thread_id: threadId ?? null, message_ids: sentIds, texts, attachment_kinds: attachKinds })
     } catch (err) {
@@ -16334,6 +16885,16 @@ async function handleInboundCoalesced(
     return handleInbound(ctx, text, downloadImage, attachment)
   }
 
+  // #3020: bare "stop" is a kill switch, same urgency as `!` — bypass the
+  // coalesce window so it fires mid-turn instead of merging into a normal
+  // turn (and so an earlier buffered message can't prepend itself and defeat
+  // the exact-word parse in handleInbound). Pure text only: a photo/document
+  // captioned "stop" is content for the agent (e.g. a stop sign to look at),
+  // not a halt request — attachments flow through the normal pipeline.
+  if (parseStopKeyword(text) && downloadImage == null && attachment == null) {
+    return handleInbound(ctx, text, downloadImage, attachment)
+  }
+
   const hasAttachment = downloadImage != null || attachment != null
   const maxAttachments = coalesceMaxAttachments()
 
@@ -16641,11 +17202,58 @@ async function handleInbound(
   // Authorization: same allowFrom gate as any inbound message —
   // unauthorized senders never reach this code (gate() above).
   // Interrupt requires the same trust as sending a normal message.
+  // #3020: bare operator "stop" — the kill switch without the `!` marker.
+  // Exact-word only (parseStopKeyword): "stop the build" flows to the agent
+  // as a normal turn. Intercepted here (never forwarded) so it fires mid-turn
+  // instead of queueing behind the very turn it's trying to cancel.
+  // Authorization: same allowFrom gate as any inbound (gate() above).
+  // Pure text only (7b): a photo/attachment captioned "stop" is content for
+  // the agent, not a halt request — it must never trip the halt-and-drop
+  // path (the caption + attachment flow through as a normal turn).
+  if (
+    parseStopKeyword(text) &&
+    downloadImage == null &&
+    attachment == null &&
+    (extraAttachments == null || extraAttachments.length === 0)
+  ) {
+    const queuedLabels = pendingSessionCommand.list().map(c => `/${c.kind} ${c.targetLabel}`)
+    const inFlight = turnInFlightForGate()
+    process.stderr.write(
+      `telegram gateway: stop-keyword received chat_id=${chat_id} in_flight_turn=${inFlight} ` +
+      `queued_cmds=${queuedLabels.length}\n`,
+    )
+    if (inFlight) {
+      if (msgId != null) {
+        void bot.api.setMessageReaction(chat_id, msgId, [
+          { type: 'emoji', emoji: '⚡' as ReactionTypeEmoji['emoji'] },
+        ]).catch(() => {})
+      }
+      await executeHaltNow('stop-keyword')
+    }
+    const stopReply = buildStopReply(inFlight, queuedLabels)
+    // #1075: thread-id-bearing — swallow so a deleted topic can't crash us.
+    await swallowingApiCall(
+      () =>
+        bot.api.sendMessage(
+          chat_id,
+          stopReply.text,
+          messageThreadId != null ? { message_thread_id: messageThreadId } : {},
+        ),
+      {
+        chat_id,
+        verb: 'stop-keyword-reply',
+        ...(messageThreadId != null ? { threadId: messageThreadId } : {}),
+      },
+    )
+    return
+  }
+
   const interrupt = parseInterruptMarker(text)
   // Problem B: defer this `!`'s SIGINT to a safe boundary instead of firing it
   // synchronously below. Set only when the `interrupt.safe_boundary` flag is on
   // AND a top-level tool call is in flight AND the body is non-empty (an empty
-  // `!` is an explicit halt-now and stays immediate). When set, we skip the
+  // `!` is a halt-now — routed through `executeHaltNow`, which honors the same
+  // safe-boundary deferral internally, #3020). When set, we skip the
   // synchronous SIGINT here and stash the built inbound at the delivery site.
   let deferInterrupt = false
   if (interrupt.isInterrupt) {
@@ -16667,6 +17275,29 @@ async function handleInbound(
         { type: 'emoji', emoji: '⚡' as ReactionTypeEmoji['emoji'] },
       ]).catch(() => {})
     }
+    if (interrupt.emptyBody) {
+      // #3020: empty `!` is a pure halt (no replacement body) — same shared
+      // sequence as /stop: safe-boundary deferral, tmux C-c, obligation
+      // cancel, deterministic busy release.
+      await executeHaltNow('bang-empty')
+      // #1075: thread-id-bearing — route through swallowingApiCall so
+      // a deleted topic doesn't crash the gateway; the reaction
+      // already acked the user so a missing follow-up is tolerable.
+      await swallowingApiCall(
+        () =>
+          bot.api.sendMessage(
+            chat_id,
+            '⚡ Interrupted. Send your replacement instruction now.',
+            messageThreadId != null ? { message_thread_id: messageThreadId } : {},
+          ),
+        {
+          chat_id,
+          verb: 'interrupt-empty-body',
+          ...(messageThreadId != null ? { threadId: messageThreadId } : {}),
+        },
+      )
+      return
+    }
     if (agentName && !deferInterrupt) {
       try {
         // The gateway runs INSIDE the agent container in docker mode,
@@ -16696,25 +17327,6 @@ async function handleInbound(
       // interrupted (user-redirected) question isn't re-presented/escalated later.
       cancelInterruptedObligation()
     }
-    if (interrupt.emptyBody) {
-      // #1075: thread-id-bearing — route through swallowingApiCall so
-      // a deleted topic doesn't crash the gateway; the reaction
-      // already acked the user so a missing follow-up is tolerable.
-      await swallowingApiCall(
-        () =>
-          bot.api.sendMessage(
-            chat_id,
-            '⚡ Interrupted. Send your replacement instruction now.',
-            messageThreadId != null ? { message_thread_id: messageThreadId } : {},
-          ),
-        {
-          chat_id,
-          verb: 'interrupt-empty-body',
-          ...(messageThreadId != null ? { threadId: messageThreadId } : {}),
-        },
-      )
-      return
-    }
     // Replace the inbound text with the body and continue normal
     // processing. The agent receives a fresh turn with no `!` prefix.
     text = interrupt.body
@@ -19866,62 +20478,406 @@ function modelMenuReplyMarkup(reply: ModelMenuReply): InlineKeyboard | undefined
   return kb
 }
 
-bot.command('model', async ctx => {
-  if (!isAuthorizedSender(ctx)) return
-  const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
-  const parsed = parseModelCommand(text) ?? { kind: 'show' as const }
-  const chatId = String(ctx.chat!.id)
-  const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
-  const deps = buildModelDeps({ chatId, threadId })
-  if (parsed.kind === 'show' && process.env.SWITCHROOM_MODEL_MENU !== '0') {
-    const menu = await buildModelMenu(deps)
-    await switchroomReply(ctx, menu.text, { html: true, reply_markup: modelMenuReplyMarkup(menu) })
-    return
-  }
-  const reply = await handleModelCommand(parsed, deps)
-  // 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 = ''
+/**
+ * Record a POSITIVELY-CONFIRMED typed `/model` switch: set the in-memory
+ * override so `/status` reflects the live model and persist the sticky
+ * `.session-model` carrier. Shared by the live `bot.command('model')` handler
+ * and the deferred (queued mid-turn) apply so both record identically. Returns
+ * a persist-warning suffix to append to the reply body (empty when clean).
+ *
+ * The `/status` honesty invariant lives here: only `reply.selectedModel`
+ * (present only on a confirmed switch) records; an unverified inject records
+ * nothing. `/model default` clears the carrier idempotently.
+ */
+function recordTypedModelSwitch(
+  reply: { text: string; selectedModel?: string },
+  requestedModelArg: string | null,
+  deps: ModelCommandDeps,
+): string {
+  const requested = requestedModelArg != null ? expandSrAlias(requestedModelArg) : null
   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(
+    return ''
+  }
+  if (!reply.selectedModel) return ''
+  sessionModelSource.setOverride(reply.selectedModel)
+  const smDir = resolveAgentDirFromEnv()
+  if (smDir && requested && isValidModelArg(requested) && !isSrModel(requested)) {
+    try {
+      writeSessionModelFile(
+        smDir,
+        requested,
+        readConfiguredDefaultModel(smDir) ??
+          resolveMainModel(deps.getConfiguredModel() ?? undefined),
+      )
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: session-model persist failed (typed /model): ${(err as Error)?.message ?? String(err)}\n`,
+      )
+      return '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
+    }
+  }
+  return ''
+}
+
+/**
+ * Record a model-MENU callback outcome (persist/clear sticky override) and
+ * drive an sr-*→Claude graceful restart when the tap crosses that boundary.
+ * Extracted from the live `mdl:*` dispatcher so the deferred (queued mid-turn)
+ * apply records + restarts identically. Does NOT edit any Telegram message —
+ * callers own the card edit. Returns a restart notice when a session restart
+ * was scheduled (the card should then drop its keyboard).
+ */
+function recordModelMenuSideEffects(
+  outcome: Awaited<ReturnType<typeof handleModelMenuCallback>>,
+  modelDeps: ModelCommandDeps,
+  cbChatId: string,
+  cbThreadId: number | undefined,
+  prevSessionModel: string | null,
+): { restartNotice?: string } {
+  // Record a successful session switch so /status reflects what's actually
+  // running, and persist the STICKY override
+  // (reference/rfcs/session-model-stickiness.md): the canonical token (never
+  // the display label) goes to the durable `.session-model`; a confirmed
+  // "Default (recommended)" selection clears it instead.
+  if (outcome.selectedModel) {
+    sessionModelSource.setOverride(outcome.selectedModel)
+    const smDir = resolveAgentDirFromEnv()
+    if (smDir && outcome.selectedModelToken) {
+      try {
+        writeSessionModelFile(
           smDir,
-          requested,
+          outcome.selectedModelToken,
           readConfiguredDefaultModel(smDir) ??
-            resolveMainModel(deps.getConfiguredModel() ?? undefined),
+            resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
         )
       } catch (err) {
-        // The reply body already promises stickiness — never let the promise
-        // and the disk disagree silently.
-        persistWarning =
+        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 (typed /model): ${(err as Error)?.message ?? String(err)}\n`,
+          `telegram gateway: session-model persist failed (menu): ${(err as Error)?.message ?? String(err)}\n`,
         )
       }
     }
   }
+  if (outcome.clearedDefault) {
+    const smDir = resolveAgentDirFromEnv()
+    if (smDir) clearSessionModelFile(smDir)
+  }
+
+  // sr-* → Claude transition: the picker-select only changes the session model
+  // label, but the sr-* LiteLLM routing context persists until the session is
+  // torn down — a graceful restart (same mechanism as /restart) is required.
+  if (outcome.selectedModel && isSrToClaudeTransition(prevSessionModel, outcome.selectedModel)) {
+    const agentName = getMyAgentName()
+    // 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.
+    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.
+      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)')
+    if (turnInFlightForGate()) {
+      // Defer restart until the in-flight turn completes (same gate as /restart).
+      pendingRestarts.set(agentName, Date.now())
+    } else {
+      void sweepBeforeSelfRestart().finally(() =>
+        triggerSelfRestart(agentName, 'sr-to-claude-model-switch', 1500),
+      )
+    }
+    return {
+      restartNotice: `🔄 Switching from **${escapeHtmlForTg(prevSessionModel!)}** back to Claude — restarting session cleanly. Claude will be ready in ~30s.`,
+    }
+  }
+  return {}
+}
+
+// ─── Mid-turn ack-queue-apply-confirm for /model + /effort (#3017) ──────────
+//
+// See pending-session-command.ts for the contract. The busy gates ENQUEUE
+// here + ACK; drainPendingSessionCommand() APPLIES the moment the agent idles
+// (from the same model-idle gate that drains pendingRestarts, plus the reaper
+// cap) and EDITS the ack card into the confirmation.
+
+/**
+ * Edit a queued command's ack card (chatId+messageId) into a new body,
+ * dropping any inline keyboard. Best-effort — a deleted card just logs.
+ * Mirrors redeliverBufferedInbound's edit-on-deliver via the shared retry
+ * policy so flood-wait / not-found are handled by the standard wrapper.
+ */
+async function editPendingCommandCard(chatId: string, messageId: number, text: string): Promise<void> {
+  try {
+    await robustApiCall(
+      () =>
+        // allow-raw-bot-api: deferred command-card edit routed through robustApiCall (not in the THREAD_NOT_FOUND blast pattern)
+        lockedBot.api.editMessageText(chatId, messageId, richMessage(hardenCardBreaks(text)), {
+          reply_markup: { inline_keyboard: [] },
+        }),
+      { chat_id: chatId, verb: 'pending-cmd-card' },
+    )
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: pending-command card edit failed chat=${chatId} msg=${messageId}: ${(err as Error)?.message ?? String(err)}\n`,
+    )
+  }
+}
+
+/**
+ * Enqueue a mid-turn session command (same-kind last-write-wins; a /model and
+ * a /effort coexist). If it displaces an earlier same-kind command, edit that
+ * stale ack card into a "superseded" note so the operator's replaced choice is
+ * never silently lost.
+ */
+function enqueueSessionCommand(cmd: PendingSessionCommand): void {
+  const displaced = pendingSessionCommand.set(cmd)
+  if (displaced) {
+    void editPendingCommandCard(
+      displaced.ackChatId,
+      displaced.ackMessageId,
+      pendingCmdSupersededText(displaced, cmd, escapeHtmlForTg),
+    )
+  }
+  // #3018 finding 5 — enqueue/turn-end race: if the idle gate fired between
+  // the busy check and this enqueue, no further turn-end will drain the slot
+  // and the command would sit until the reaper cap. If the session is idle
+  // NOW, kick the drain immediately (re-entrancy-guarded, no-op if a racing
+  // drain already ran).
+  if (!turnInFlightForGate()) void drainPendingSessionCommand()
+}
+
+/** Apply a queued typed/menu-alias model command at idle; return the reply body. */
+async function applyQueuedModelCommand(cmd: PendingSessionCommand): Promise<string> {
+  const deps = buildModelDeps({ chatId: cmd.chatId, threadId: cmd.threadId })
+  if (cmd.origin === 'menu') {
+    // Menu SELECT (mdl:s:<tag>) — replay the callback handler (discovery is
+    // idle-safe now) and record via the shared side-effects helper.
+    const prevSessionModel = sessionModelSource.getOverride()
+    const outcome = await handleModelMenuCallback(cmd.arg, deps)
+    const { restartNotice } = recordModelMenuSideEffects(
+      outcome,
+      deps,
+      cmd.chatId,
+      cmd.threadId,
+      prevSessionModel,
+    )
+    return restartNotice ?? outcome.reply.text
+  }
+  // Typed (and alias/sr menu taps converted to typed at enqueue): run the real
+  // handler + shared recording.
+  const reply = await handleModelCommand({ kind: 'set', model: cmd.arg }, deps)
+  const warning = recordTypedModelSwitch(reply, cmd.arg, deps)
+  return reply.text + warning
+}
+
+/** Apply a queued typed/menu effort command at idle; return the reply body. */
+async function applyQueuedEffortCommand(cmd: PendingSessionCommand): Promise<string> {
+  const deps = buildEffortDeps()
+  if (cmd.origin === 'menu') {
+    const outcome = await handleEffortMenuCallback(cmd.arg, deps)
+    return outcome.reply.text
+  }
+  const parsed =
+    cmd.arg === 'default'
+      ? ({ kind: 'default' } as const)
+      : ({ kind: 'set', level: cmd.arg as EffortLevel } as const)
+  const reply = await handleEffortCommand(parsed, deps)
+  return reply.text
+}
+
+/**
+ * Re-enqueue a command the drain took but could not safely apply (a turn
+ * raced in). If a NEWER same-kind command was enqueued while the drain was
+ * mid-flight, the newer one wins (last-write-wins invariant) and this older
+ * card is edited to superseded instead.
+ */
+function reEnqueueUnlessSuperseded(cmd: PendingSessionCommand): void {
+  const newer = pendingSessionCommand.get(cmd.kind)
+  if (newer != null) {
+    void editPendingCommandCard(
+      cmd.ackChatId,
+      cmd.ackMessageId,
+      pendingCmdSupersededText(cmd, newer, escapeHtmlForTg),
+    )
+    return
+  }
+  pendingSessionCommand.set(cmd)
+}
+
+/**
+ * #3039 — execute a shutdown/restart resolution action's durable write:
+ * carry a queued (typed) choice across the bounce via the boot carriers
+ * (`.session-model` / `.session-effort`) instead of asking for a re-issue.
+ * Returns the ack-card text to edit in (persisted vs re-issue fallback).
+ */
+function persistQueuedCommandForRestart(action: ShutdownResolutionAction): string {
+  if (action.persist == null) return action.reissueText
+  const agentDir = resolveAgentDirFromEnv()
+  if (agentDir == null) return action.reissueText
+  try {
+    switch (action.persist) {
+      case 'model': {
+        // #3042 blocker 2a: this token was QUEUED, never confirmed by claude.
+        // Under the keep-by-default boot a garbage-but-shape-valid token
+        // persisted here would crashloop `claude --model <garbage>` with the
+        // gateway dead. Only offline-trustable tokens (static Claude aliases,
+        // curated sr-* alias targets) may be persisted unconfirmed; anything
+        // else gets the honest "couldn't verify — re-issue" card instead.
+        if (!isOfflineTrustedModelToken(action.arg)) {
+          return `↩️ Couldn’t verify \`${escapeHtmlForTg(action.cmd.targetLabel || action.arg)}\` as a known model without the live session — it was NOT saved. Re-issue \`/model ${escapeHtmlForTg(action.arg)}\` once the agent is back.`
+        }
+        const configured =
+          readConfiguredDefaultModel(agentDir) ?? resolveMainModel(undefined)
+        writeSessionModelFile(agentDir, expandSrAlias(action.arg), configured)
+        // Boot default is keep (#3039), but stamp explicit keep-intent for
+        // reason-honesty in the boot notice.
+        writeRelaunchModelIntent(agentDir, 'keep', 'queued /model carried across restart')
+        break
+      }
+      case 'clear-model':
+        clearSessionModelFile(agentDir)
+        break
+      case 'effort':
+        writeSessionEffortFile(agentDir, action.arg, getConfiguredEffortForPersist())
+        break
+      case 'clear-effort':
+        clearSessionEffortFile(agentDir)
+        break
+    }
+    return action.persistedText
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: queued-command persist-for-restart failed kind=${action.cmd.kind} arg=${action.arg}: ${(err as Error)?.message ?? String(err)}\n`,
+    )
+    return action.reissueText
+  }
+}
+
+/**
+ * The cascade-resolved thinking_effort, for `.session-effort`'s
+ * configuredDefaultAtWrite. #3042 item 5: on a transient `agent list`
+ * failure fall back to the scaffold default rather than null — persisting ''
+ * would trip a bogus "configured default effort changed" clear+alert at the
+ * next boot (start.sh bakes the same default when yaml is unset).
+ */
+function getConfiguredEffortForPersist(): string {
+  try {
+    type AgentListResp = { agents: Array<{ name: string; thinking_effort?: string | null }> }
+    const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
+    return (
+      data?.agents?.find(a => a.name === getMyAgentName())?.thinking_effort ??
+      SWITCHROOM_DEFAULT_THINKING_EFFORT
+    )
+  } catch {
+    return SWITCHROOM_DEFAULT_THINKING_EFFORT
+  }
+}
+
+// Synchronous re-entrancy guard — the idle gate can fire several times per
+// turn-end; the async apply must not double-dispatch before the first settles
+// (mirrors compactDispatching).
+let pendingCmdDraining = false
+
+/**
+ * Drain the queued session command(s) when the agent goes idle: apply each,
+ * then edit its ack card into the confirmation (or a failure banner). Called
+ * from the model-idle gate (turn complete), the post-enqueue idle kick, and
+ * the reaper drain-cap. No-op when the slots are empty. If a restart is (or
+ * becomes — a model apply can itself enqueue one) pending, the session is
+ * going away — a Claude-model / effort session change would not survive, so
+ * report that honestly rather than falsely confirming.
+ */
+async function drainPendingSessionCommand(): Promise<void> {
+  if (pendingCmdDraining) return
+  if (pendingSessionCommand.size === 0) return
+  pendingCmdDraining = true
+  try {
+    // Iteration + loss-safety invariants live in drainTakenCommands
+    // (pending-session-command.ts, unit-tested): a restart-pending command is
+    // persisted to the boot carriers; an early stop (turn raced in / handler
+    // busy-refusal) re-enqueues EVERY not-yet-applied taken command (#3042
+    // blocker 1) instead of dropping the rest of the batch.
+    await pendingCmdDrainTaken(pendingSessionCommand.takeAll(), {
+      restartPending: () => pendingRestarts.size > 0,
+      turnInFlight: () => turnInFlightForGate(),
+      apply: cmd =>
+        cmd.kind === 'model' ? applyQueuedModelCommand(cmd) : applyQueuedEffortCommand(cmd),
+      isBusyRefusal: isBusyRefusalText,
+      resolveForRestartText: cmd =>
+        persistQueuedCommandForRestart(pendingCmdResolveForRestart(cmd, escapeHtmlForTg)),
+      editCard: (cmd, text) => editPendingCommandCard(cmd.ackChatId, cmd.ackMessageId, text),
+      reEnqueue: reEnqueueUnlessSuperseded,
+      failureText: (cmd, err) =>
+        `❌ Couldn’t apply the queued ${cmd.kind} switch to \`${escapeHtmlForTg(cmd.targetLabel)}\`: ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
+    })
+  } finally {
+    pendingCmdDraining = false
+  }
+}
+
+bot.command('model', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  const text = ctx.message?.text ?? ctx.channelPost?.text ?? ''
+  const parsed = parseModelCommand(text) ?? { kind: 'show' as const }
+  const chatId = String(ctx.chat!.id)
+  const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+  const deps = buildModelDeps({ chatId, threadId })
+  if (parsed.kind === 'show' && process.env.SWITCHROOM_MODEL_MENU !== '0') {
+    const menu = await buildModelMenu(deps)
+    await switchroomReply(ctx, menu.text, { html: true, reply_markup: modelMenuReplyMarkup(menu) })
+    return
+  }
+  // Mid-turn: instead of dead-ending ("Try again in a moment"), ACK + QUEUE +
+  // apply-on-idle + confirm (#3017). The typed set path either injects into
+  // claude's input box or triggers a carrier restart — both unsafe mid-turn.
+  if (parsed.kind === 'set' && deps.isBusy()) {
+    const target = expandSrAlias(parsed.model)
+    const sent = await ctx.replyWithRichMessage(
+      richMessage(hardenCardBreaks(pendingCmdAckText('model', target, escapeHtmlForTg))),
+      threadId != null ? { message_thread_id: threadId } : {},
+    )
+    enqueueSessionCommand({
+      kind: 'model',
+      origin: 'typed',
+      arg: target,
+      targetLabel: target,
+      chatId,
+      threadId,
+      ackChatId: chatId,
+      ackMessageId: (sent as { message_id: number }).message_id,
+      requestedAt: Date.now(),
+    })
+    return
+  }
+  const reply = await handleModelCommand(parsed, deps)
+  // Record a POSITIVELY-CONFIRMED typed switch so /status reflects what's
+  // actually running (shared with the deferred/menu paths). The sr-*/relaunch
+  // paths already set the override inside scheduleModelRelaunch; an unverified
+  // switch carries no selectedModel so /status is never lied to.
+  const persistWarning = recordTypedModelSwitch(
+    reply,
+    parsed.kind === 'set' ? parsed.model : null,
+    deps,
+  )
   await switchroomReply(ctx, reply.text + persistWarning, { html: reply.html })
 })
 
@@ -19936,12 +20892,36 @@ bot.command('model', async ctx => {
 // effort-command.ts so it's unit-testable without booting the bot.
 function buildEffortDeps(): EffortCommandDeps {
   return {
-    applyEffort: (agent, level) => applyEffort(agent, level),
+    // #3039: single persistence choke point — EVERY positively-confirmed
+    // effort apply (typed, menu tap, queued drain) durably records the level
+    // to `.session-effort`, which start.sh resolves into `--effort` on every
+    // boot. `/effort default` clears it via clearSessionEffort (the handler
+    // clears AFTER its restore-apply, so the wrapper's write is undone).
+    applyEffort: async (agent, level) => {
+      const result = await applyEffort(agent, level)
+      if (result.ok) {
+        const agentDir = resolveAgentDirFromEnv()
+        if (agentDir) {
+          try {
+            writeSessionEffortFile(agentDir, level, getConfiguredEffortForPersist())
+          } catch (err) {
+            process.stderr.write(
+              `telegram gateway: session-effort persist failed level=${level}: ${(err as Error)?.message ?? String(err)}\n`,
+            )
+          }
+        }
+      }
+      return result
+    },
     getAgentName: getMyAgentName,
-    getConfiguredEffort: () => {
-      type AgentListResp = { agents: Array<{ name: string; thinking_effort?: string | null }> }
-      const data = switchroomExecJson<AgentListResp>(['agent', 'list'])
-      return data?.agents?.find(a => a.name === getMyAgentName())?.thinking_effort ?? null
+    getConfiguredEffort: () => getConfiguredEffortForPersist(),
+    clearSessionEffort: () => {
+      const agentDir = resolveAgentDirFromEnv()
+      if (agentDir) clearSessionEffortFile(agentDir)
+    },
+    getSessionEffort: () => {
+      const agentDir = resolveAgentDirFromEnv()
+      return agentDir ? (readSessionEffortFile(agentDir)?.level ?? null) : null
     },
     escapeHtml: escapeHtmlForTg,
   }
@@ -19967,6 +20947,31 @@ bot.command('effort', async ctx => {
     await switchroomReply(ctx, menu.text, { html: true, reply_markup: effortMenuReplyMarkup(menu) })
     return
   }
+  // Mid-turn: ACK + QUEUE + apply-on-idle + confirm (#3017) — parity with
+  // /model. `applyEffort` mid-turn silently maybe-failed ("couldn't confirm it
+  // applied") before this gate existed. `currentTurn !== null` is the same
+  // busy signal the model path reads via deps.isBusy().
+  if ((parsed.kind === 'set' || parsed.kind === 'default') && currentTurn !== null) {
+    const requestedLevel = parsed.kind === 'set' ? parsed.level : 'default'
+    const chatId = String(ctx.chat!.id)
+    const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+    const sent = await ctx.replyWithRichMessage(
+      richMessage(hardenCardBreaks(pendingCmdAckText('effort', requestedLevel, escapeHtmlForTg))),
+      threadId != null ? { message_thread_id: threadId } : {},
+    )
+    enqueueSessionCommand({
+      kind: 'effort',
+      origin: 'typed',
+      arg: requestedLevel,
+      targetLabel: requestedLevel,
+      chatId,
+      threadId,
+      ackChatId: chatId,
+      ackMessageId: (sent as { message_id: number }).message_id,
+      requestedAt: Date.now(),
+    })
+    return
+  }
   const reply = await handleEffortCommand(parsed, deps)
   await switchroomReply(ctx, reply.text, { html: reply.html })
 })
@@ -19983,7 +20988,10 @@ bot.command('agentstart', async ctx => {
   )
 })
 
-bot.command('stop', async ctx => {
+// #3020: container stop lives on /agentstop (pairs with /agentstart above).
+// It WAS /stop; that word now cancels the in-flight turn instead — the
+// intuitive meaning for a chat-first operator.
+bot.command('agentstop', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
   try { assertSafeAgentName(name) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
@@ -19995,6 +21003,32 @@ bot.command('stop', async ctx => {
   )
 })
 
+// #3020: /stop — cancel the agent's in-flight turn (the typed sibling of the
+// bare "stop" keyword and the empty-`!` interrupt; shared executeHaltNow).
+bot.command('stop', async ctx => {
+  if (!isAuthorizedSender(ctx)) return
+  // 7a: /stop takes NO argument. "/stop worker" is almost certainly old
+  // container-stop muscle memory (the verb that moved to /agentstop) — warn
+  // and do NOT halt, so a mis-remembered command can't kill an unrelated turn.
+  const arg = ctx.match?.trim()
+  if (arg) {
+    await switchroomReply(
+      ctx,
+      `/stop takes no argument — it cancels MY in-flight turn. ` +
+      `To stop a container, use /agentstop ${arg}. Nothing was stopped.`,
+    )
+    return
+  }
+  const queuedLabels = pendingSessionCommand.list().map(c => `/${c.kind} ${c.targetLabel}`)
+  const inFlight = turnInFlightForGate()
+  if (!inFlight) {
+    await switchroomReply(ctx, buildStopReply(false, queuedLabels).text)
+    return
+  }
+  await executeHaltNow('stop-command')
+  await switchroomReply(ctx, buildStopReply(true, queuedLabels).text)
+})
+
 bot.command('restart', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const name = ctx.match?.trim() || getMyAgentName()
@@ -20033,12 +21067,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.
+    // #3039: /restart is "bounce the session", NOT "clear my model" — the
+    // durable override survives every restart and is cleared only by
+    // `/model default`. Stamp keep for reason-honesty in the boot notice
+    // (absence of intent keeps anyway under the keep-by-default boot).
     {
       const smDir = resolveAgentDirFromEnv()
-      if (smDir) writeRelaunchModelIntent(smDir, 'revert', 'user: /restart from chat')
+      if (smDir) writeRelaunchModelIntent(smDir, 'keep', 'user: /restart from chat')
     }
     await sweepBeforeSelfRestart()
     const hostdResp = await tryHostdDispatch(getMyAgentName(), {
@@ -20852,6 +21887,16 @@ const fleetFallbackGate = createFleetFallbackGate({
   brokerReachable: isAuthBrokerSocketReachable,
 })
 
+/**
+ * #3031 PR 3 — per-chat registry of the most recent model-unavailable card
+ * that promised an in-flight auto-failover. On a SUCCESSFUL swap the
+ * announcement is folded into an EDIT of that card (single evolving card);
+ * on every failure / no-op outcome the notice stays a separate message
+ * (promise-honesty: the 2026-06-06→07 incident contract). See
+ * fallback-card-collapse.ts for the decision seam.
+ */
+const modelUnavailableCardRegistry = createModelUnavailableCardRegistry()
+
 /**
  * Resume-after-swap gate (auth-failover-stall fix). Owns the single-flight +
  * staleness decision for re-running the turn a mid-turn 429 killed. See
@@ -21061,6 +22106,34 @@ async function doFireFleetAutoFallback(triggerAgent: string, untilMs?: number):
     // not the user's answer — silence the open ping.
     const opts = { disable_notification: true }
     for (const chat_id of access.allowFrom) {
+      // #3031 PR 3 — collapse: on a SUCCESSFUL swap, fold the announcement
+      // into an EDIT of the model-unavailable card this gateway just sent to
+      // this chat (single evolving card). One-shot `take` clears the record
+      // either way. Every non-switched outcome that REACHES this loop — and
+      // any edit failure — falls through to the pre-fix separate send.
+      // Known PRE-EXISTING hole, unchanged by the collapse (#3035 review,
+      // finding 2): the all-blocked cooldown early-return above exits before
+      // this loop, so a cooldown-suppressed all-blocked REPEAT delivers
+      // neither edit nor message even when a promising card exists. The
+      // first all-blocked card of a window does arrive and answers the
+      // promise; only the repeats inside the 30-min window are silent.
+      const card = modelUnavailableCardRegistry.take(String(chat_id), Date.now())
+      if (decideAnnouncementDelivery(outcome.kind, card) === 'edit' && card) {
+        try {
+          // allow-raw-bot-api: guarded edit; failure falls through to the wrapped send below
+          await bot.api.editMessageText(
+            chat_id,
+            card.messageId,
+            richMessage(foldAnnouncementIntoCard(card.text, outcome.announcement)),
+            {},
+          )
+          continue
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: [fleet-fallback] card edit failed chat=${chat_id} — sending announcement separately: ${(err as Error)?.message ?? err}\n`,
+          )
+        }
+      }
       void swallowingApiCall(
         // allow-raw-bot-api: wrapped in swallowingApiCall (retry policy)
         () => bot.api.sendRichMessage(chat_id, richMessage(outcome.announcement), opts),
@@ -21312,6 +22385,61 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
     }
   }
 
+  // #3031 PR 3 — broker-initiated proactive roll announcement. The broker's
+  // fleetQuotaProbeTick roll previously emitted stdout + audit only (zero
+  // operator Telegram visibility); it now records `last_fleet_roll` in
+  // list-state. Edge-triggered on the roll's `at` timestamp; deduped across
+  // the multi-gateway fan-in via the same broker claim-notification verb the
+  // per-account pushes use — one card per roll per chat, fleet-wide.
+  {
+    const rollPrev = watchState[FLEET_ROLL_ANNOUNCE_KEY] ?? emptyAccountState()
+    const rollDecision = evaluateFleetRollAnnounce({
+      roll: listStateData.last_fleet_roll ?? null,
+      prev: rollPrev,
+      now,
+    })
+    if (rollDecision.kind === 'notify') {
+      for (const chat_id of access.allowFrom) {
+        if (tuning.fleetDedup) {
+          const granted = await claimQuotaNotification(
+            brokerClient,
+            buildQuotaClaimKey(
+              FLEET_ROLL_ANNOUNCE_KEY,
+              String(listStateData.last_fleet_roll!.at),
+              chat_id,
+            ),
+          )
+          if (!granted) {
+            process.stderr.write(
+              `telegram gateway: quota-watch: fleet-roll claim denied chat=${chat_id} — another agent notified\n`,
+            )
+            continue
+          }
+        }
+        await swallowingApiCall(
+          () =>
+            bot.api.sendRichMessage(chat_id, richMessage(rollDecision.message), {
+              // Reassuring status notice, not the user's answer — silent.
+              disable_notification: true,
+            }),
+          { chat_id, verb: 'quota-watch.fleet-roll' },
+        )
+      }
+      // Persist immediately — mirrors the all-exhausted block's rationale:
+      // a per-account early return below must not drop the latch advance.
+      watchState = patchQuotaWatchState(watchState, FLEET_ROLL_ANNOUNCE_KEY, rollDecision.newState)
+      try {
+        saveQuotaWatchState(stateDir, watchState)
+      } catch (err) {
+        process.stderr.write(`telegram gateway: quota-watch: fleet-roll state save failed: ${err}\n`)
+      }
+      process.stderr.write(
+        `telegram gateway: quota-watch: announced broker fleet roll ` +
+          `${listStateData.last_fleet_roll!.from} → ${listStateData.last_fleet_roll!.to}\n`,
+      )
+    }
+  }
+
   // First pass: evaluate all accounts against cached state. Collect
   // labels that need a live probe (i.e. accounts with a detected transition
   // that we're about to notify about). We probe those to get fresh
@@ -21331,9 +22459,13 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
   let reconciledCount = 0
   let mutatedState = watchState
 
+  // #3031 PR 3 — thread the last broker roll so a 🟡 throttling push for the
+  // just-rolled-off account is latched silently (the roll card covered it).
+  const lastRoll = listStateData.last_fleet_roll ?? null
+
   for (const snap of snapshots) {
     const prev = watchState[snap.label] ?? emptyAccountState()
-    const decision = evaluateQuotaWatchAccount({ agentName, snap, prev, now, bootTick, tuning })
+    const decision = evaluateQuotaWatchAccount({ agentName, snap, prev, now, bootTick, tuning, lastRoll })
     if (decision.kind === 'reconcile') {
       mutatedState = patchQuotaWatchState(mutatedState, decision.accountLabel, decision.newAccountState)
       reconciledCount++
@@ -21428,7 +22560,7 @@ async function runQuotaWatch(opts: { bootTick?: boolean } = {}): Promise<void> {
       // staleness gate never misfires on data we JUST probed.
       const enrichedSnap = { ...snapshots[snapIndex]!, quota: freshEntry!.result.data, capturedAtMs: undefined }
       const prev = watchState[accountLabel] ?? emptyAccountState()
-      const re = evaluateQuotaWatchAccount({ agentName, snap: enrichedSnap, prev, now, bootTick, tuning })
+      const re = evaluateQuotaWatchAccount({ agentName, snap: enrichedSnap, prev, now, bootTick, tuning, lastRoll })
       // If the fresh probe still shows the same transition, use the
       // enriched message. If it no longer shows a transition (e.g. the
       // account recovered in the 100ms between listState and probe),
@@ -22704,9 +23836,37 @@ bot.on('callback_query:data', async ctx => {
       await ctx.answerCallbackQuery({ text: 'Not authorized.' })
       return
     }
-    // No picker-driving (the inline `/effort <level>` form sets it
-    // directly via the inject primitive), so no mid-turn guard is needed
-    // here — just ack and apply.
+    // Mid-turn: ACK + QUEUE + apply-on-idle + confirm (#3017). `applyEffort`
+    // types `/effort <level>` into claude's input box + drives the confirm
+    // modal — mid-turn that queues the text as user input instead of switching
+    // (the silent maybe-fail this fix closes). Parity with the model-menu gate.
+    const effLevel = data.startsWith('eff:s:') ? data.slice('eff:s:'.length) : null
+    const effCardMsgId = ctx.callbackQuery?.message?.message_id
+    if (effLevel != null && currentTurn !== null && effCardMsgId != null) {
+      await ctx
+        .answerCallbackQuery({ text: '📥 Queued — applies when the turn ends' })
+        .catch(() => {})
+      const effChatId = String(ctx.chat?.id ?? '')
+      const effThreadId = resolveThreadId(effChatId, ctx.callbackQuery?.message?.message_thread_id)
+      await ctx
+        .editMessageText(richMessage(hardenCardBreaks(pendingCmdAckText('effort', effLevel, escapeHtmlForTg))), {
+          reply_markup: { inline_keyboard: [] },
+        })
+        .catch(() => {})
+      enqueueSessionCommand({
+        kind: 'effort',
+        origin: 'menu',
+        arg: data,
+        targetLabel: effLevel,
+        chatId: effChatId,
+        threadId: effThreadId,
+        ackChatId: effChatId,
+        ackMessageId: effCardMsgId,
+        requestedAt: Date.now(),
+      })
+      return
+    }
+    // Idle: apply directly. No picker-driving concern — just ack and apply.
     await ctx.answerCallbackQuery({ text: 'Setting effort…' }).catch(() => {})
     try {
       const outcome = await handleEffortMenuCallback(data, buildEffortDeps())
@@ -22745,12 +23905,51 @@ bot.on('callback_query:data', async ctx => {
     const cbChatId = String(ctx.chat?.id ?? '')
     const cbThreadId = resolveThreadId(cbChatId, ctx.callbackQuery?.message?.message_thread_id)
     const modelDeps = buildModelDeps({ chatId: cbChatId, threadId: cbThreadId })
-    // Mid-turn refusal is INSTANT (a sync isBusy() check, no picker drive),
-    // so handle it before the "Working…" ack: toast WHY and leave the menu
-    // message untouched (buttons intact) so the operator taps again when
-    // idle. Editing the menu into a button-less "try again" line was the
-    // "nothing happened" report — the menu looked dead.
+    // Mid-turn (#3017): a model-SWITCH tap no longer dead-ends. ACK + QUEUE +
+    // apply-on-idle + confirm — the tap edits the menu card into the ack, which
+    // the idle drain then edits into the confirmation. Non-switch taps (Refresh
+    // / page-nav / header) still just toast — they drive the picker (discovery)
+    // which is unsafe mid-turn and carry no operator choice to preserve.
     if (modelDeps.isBusy()) {
+      // Classify: sr-*/alias taps carry a real model token → queue as a typed
+      // apply (reuses the typed drain + recording). A select tag (mdl:s:<tag>)
+      // needs idle discovery to resolve → queue as a menu apply (replayed).
+      const cardMsgId = ctx.callbackQuery?.message?.message_id
+      let queueArg: string | null = null
+      let queueOrigin: 'typed' | 'menu' = 'menu'
+      let queueLabel = 'the selected model'
+      if (data.startsWith(MODEL_CALLBACK_SR)) {
+        const srName = data.slice(MODEL_CALLBACK_SR.length)
+        if (isValidModelArg(srName)) { queueArg = srName; queueOrigin = 'typed'; queueLabel = srFriendlyLabel(srName) }
+      } else if (data.startsWith(MODEL_CALLBACK_ALIAS)) {
+        const alias = data.slice(MODEL_CALLBACK_ALIAS.length)
+        if (isValidModelArg(alias)) { queueArg = alias; queueOrigin = 'typed'; queueLabel = alias }
+      } else if (data.startsWith('mdl:s:')) {
+        queueArg = data; queueOrigin = 'menu'
+      }
+      if (queueArg != null && cardMsgId != null) {
+        await ctx
+          .answerCallbackQuery({ text: '📥 Queued — applies when the turn ends' })
+          .catch(() => {})
+        await ctx
+          .editMessageText(richMessage(hardenCardBreaks(pendingCmdAckText('model', queueLabel, escapeHtmlForTg))), {
+            reply_markup: { inline_keyboard: [] },
+          })
+          .catch(() => {})
+        enqueueSessionCommand({
+          kind: 'model',
+          origin: queueOrigin,
+          arg: queueArg,
+          targetLabel: queueLabel,
+          chatId: cbChatId,
+          threadId: cbThreadId,
+          ackChatId: cbChatId,
+          ackMessageId: cardMsgId,
+          requestedAt: Date.now(),
+        })
+        return
+      }
+      // Non-switch tap (or unresolvable) — keep the menu intact, just toast.
       await ctx
         .answerCallbackQuery({ text: '⏳ Agent is mid-turn — tap again when it’s idle', show_alert: false })
         .catch(() => {})
@@ -22814,105 +24013,32 @@ bot.on('callback_query:data', async ctx => {
       }
       return
     }
-    const didInterimSrEdit = false
     try {
       const prevSessionModel = sessionModelSource.getOverride()
       const outcome = await handleModelMenuCallback(data, modelDeps)
-      // Record a successful session switch so /status reflects what's
-      // actually running, and persist the STICKY override
-      // (reference/rfcs/session-model-stickiness.md): the canonical token
-      // (never the display label) goes to the durable `.session-model`; a
-      // confirmed "Default (recommended)" selection clears it instead.
-      if (outcome.selectedModel) {
-        sessionModelSource.setOverride(outcome.selectedModel)
-        const smDir = resolveAgentDirFromEnv()
-        if (smDir && outcome.selectedModelToken) {
-          try {
-            writeSessionModelFile(
-              smDir,
-              outcome.selectedModelToken,
-              readConfiguredDefaultModel(smDir) ??
-                resolveMainModel(modelDeps.getConfiguredModel() ?? undefined),
-            )
-          } catch (err) {
-            // The banner already promises stickiness — surface the failure on
-            // the same card instead of only stderr.
-            outcome.reply.text +=
-              '\n⚠️ Couldn’t persist the sticky override — the switch is live now but won’t survive a relaunch.'
-            process.stderr.write(
-              `telegram gateway: session-model persist failed (menu): ${(err as Error)?.message ?? String(err)}\n`,
-            )
-          }
-        }
-      }
-      if (outcome.clearedDefault) {
-        const smDir = resolveAgentDirFromEnv()
-        if (smDir) clearSessionModelFile(smDir)
-      }
-      // toastOnly: leave the menu untouched — but only if we haven't already
-      // cleared its buttons with the interim sr-* edit. If we have, fall
-      // through to the final edit so the message is recovered (busyReply or
-      // the full menu) rather than left permanently button-less.
-      if (outcome.toastOnly && !didInterimSrEdit) return
-
-      // sr-* → Claude transition via the model menu: trigger a graceful restart.
-      // Switching FROM an sr-* (LiteLLM/OpenRouter) model BACK to a Claude model
-      // via the picker requires a session restart — the picker-select only changes
-      // the session model label, but the sr-* LiteLLM routing context persists
-      // until the session is torn down. Same mechanism as the /restart command.
-      if (outcome.selectedModel && isSrToClaudeTransition(prevSessionModel, outcome.selectedModel)) {
-        const agentName = getMyAgentName()
-        // Replace the menu with a restart notice (no buttons — session is ending).
+      // toastOnly: leave the menu untouched — a mid-turn refusal keeps its
+      // buttons so the operator can tap again. (In the enqueue world this
+      // branch is unreachable — the dispatcher enqueues switches mid-turn
+      // before ever calling the handler — but retained for callers that skip
+      // the dispatcher gate.)
+      if (outcome.toastOnly) return
+      // Record the switch (persist/clear sticky override) + drive an sr-*→Claude
+      // graceful restart when needed. Shared with the deferred (queued) apply so
+      // both surfaces record identically. Returns a restart notice when a
+      // session restart was scheduled.
+      const { restartNotice } = recordModelMenuSideEffects(
+        outcome,
+        modelDeps,
+        cbChatId,
+        cbThreadId,
+        prevSessionModel,
+      )
+      if (restartNotice) {
         await ctx
-          .editMessageText(
-            richMessage(`🔄 Switching from **${escapeHtmlForTg(prevSessionModel!)}** back to Claude — restarting session cleanly. Claude will be ready in ~30s.`),
-            { reply_markup: { inline_keyboard: [] } },
-          )
+          .editMessageText(richMessage(restartNotice), { 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)')
-        if (turnInFlightForGate()) {
-          // Defer restart until the in-flight turn completes (same gate as /restart).
-          pendingRestarts.set(agentName, Date.now())
-        } else {
-          void sweepBeforeSelfRestart().finally(() =>
-            triggerSelfRestart(agentName, 'sr-to-claude-model-switch', 1500),
-          )
-        }
         return
       }
-
       await ctx
         .editMessageText(richMessage(outcome.reply.text), {
           reply_markup: modelMenuReplyMarkup(outcome.reply) ?? { inline_keyboard: [] },
@@ -25157,6 +26283,10 @@ async function shutdown(signal: string): Promise<void> {
   shuttingDown = true
   const agentName = process.env.SWITCHROOM_AGENT_NAME ?? '-'
   process.stderr.write('telegram gateway: shutting down\n')
+  // #3038 — never let a pending bridge-dead grace timer race a shutdown
+  // already in progress (its check() also skips on shuttingDown; this is
+  // the belt to that brace).
+  bridgeDeadWatchdog.stop()
 
   // Write the clean-shutdown sentinel BEFORE any drain work begins so
   // even if the drain hangs and the +5s force-exit kills us, the marker
@@ -25191,10 +26321,66 @@ async function shutdown(signal: string): Promise<void> {
     } catch (err) {
       process.stderr.write(`telegram gateway: shutdown.clean_marker_write_failed err=${(err as Error).message}\n`)
     }
+    // #3017 — persist a Telegram-set model across a GRACEFUL deploy/restart.
+    // Boot default is REVERT, and an EXTERNAL deploy (SIGTERM to PID 1 from
+    // `switchroom apply` / `docker compose up`) never routes through
+    // triggerSelfRestart, so it stamps no `.relaunch-model-intent` and start.sh
+    // drops the user's `/model` choice (the overlord `fable`→`opus` revert on
+    // the v0.18.9 roll). A graceful OS-signal shutdown IS a clean, planned
+    // bounce — stamp keep-intent for an active `.session-model` override so the
+    // chosen model survives and start.sh re-confirms it via `.session-model-alert`
+    // on boot. Respect an intent an initiator already stamped (a /restart stamps
+    // 'revert' before SIGTERM): only stamp when none exists. A crash routes
+    // through the non-OS-signal branch and still reverts (safe side preserved).
+    try {
+      const smDir = resolveAgentDirFromEnv()
+      if (smDir != null) {
+        const hasOverride = readSessionModelFile(smDir) != null
+        const intentAlreadyStamped = existsSync(join(smDir, RELAUNCH_MODEL_INTENT_FILE))
+        if (hasOverride && !intentAlreadyStamped) {
+          // The GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX makes this stamp
+          // recognisable at the next GATEWAY boot: a gateway-only bounce never
+          // runs start.sh, so a leftover stamp with this prefix is cleared at
+          // boot (clearStaleGatewayShutdownIntent) instead of lingering to
+          // convert a later genuine crash into a "keep" (#3018 finding 4).
+          writeRelaunchModelIntent(smDir, 'keep', `${GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX} graceful ${signal} shutdown (deploy/rolling restart) — preserving user-chosen session model`)
+          process.stderr.write(`telegram gateway: shutdown.session_model_keep_stamped signal=${signal}\n`)
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`telegram gateway: shutdown.session_model_keep_stamp_failed err=${(err as Error).message}\n`)
+    }
   } else {
     process.stderr.write(`telegram gateway: shutdown.clean_marker_skipped signal=${signal} (crash path — banner will fire on next boot)\n`)
   }
 
+  // #3018 finding 3 + #3039: resolve any queued /model|/effort ack cards. The
+  // gateway (and with it the in-memory queue) is going away — persist each
+  // typed choice to the durable boot carriers (`.session-model` /
+  // `.session-effort`) so it still deterministically applies as the agent
+  // boots, and edit the ack card to say so. Only an unresolvable menu-tag
+  // selection falls back to a re-issue note. Best-effort and time-bounded so
+  // a wedged Telegram API can't block shutdown.
+  const orphanedCmdActions = pendingCmdShutdownResolutionActions(pendingSessionCommand, escapeHtmlForTg)
+  const orphanedCmdEdits = orphanedCmdActions.map(a => ({
+    chatId: a.cmd.ackChatId,
+    messageId: a.cmd.ackMessageId,
+    text: persistQueuedCommandForRestart(a),
+  }))
+  if (orphanedCmdEdits.length > 0) {
+    process.stderr.write(
+      `telegram gateway: shutdown.pending_cmd_resolved count=${orphanedCmdEdits.length}\n`,
+    )
+    await Promise.race([
+      Promise.allSettled(
+        orphanedCmdEdits.map(e => editPendingCommandCard(e.chatId, e.messageId, e.text)),
+      ),
+      new Promise<void>(resolve => {
+        setTimeout(resolve, SHUTDOWN_PROGRESS_FLUSH_BUDGET_MS).unref()
+      }),
+    ])
+  }
+
   // Stage 3c: stamp any in-flight turn as endedVia='sigterm' (or 'restart'
   // for the schedule_restart-initiated case where pendingRestarts is set).
   // Best-effort — SIGKILL / OOM skip this path entirely and the next-boot
@@ -26309,6 +27495,44 @@ 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.
+              // Issue #3023 (card resurrection). A worker whose card was
+              // FALSELY finalised (silent-stall synthesis fired, then the
+              // JSONL resumed growing) is being revived by the watcher. This
+              // callback ONLY clears the worker feed's durable `finalized` gate
+              // (workerActivityFeed.resurrect) — it does NOT itself paint or pin
+              // anything. The actual repaint + re-pin happen DOWNSTREAM on the
+              // next replayed `running` cue: the watcher's re-registration
+              // replays `onProgress`, which calls `workerActivityFeed.update()`
+              // (now un-gated) to first-paint a FRESH `🛠 Worker` message, and
+              // its `.then(reconcileWorkerPin(agentId, wkChat, true))` pins that
+              // new message via the `wk:<agentId>` status-pin. Clearing the gate
+              // here FIRST is the ordering requirement — without it those first
+              // replayed ticks would be swallowed by the finalized gate and no
+              // new card would ever paint. Net effect restores the operator
+              // invariant "active work must always be visible" for the case
+              // PR #3019's in-flight gate can't fully prevent.
+              onResurrect: (agentId, _description) => {
+                try {
+                  workerActivityFeed?.resurrect(agentId)
+                } catch (err) {
+                  process.stderr.write(
+                    `telegram gateway: worker resurrect error agent=${agentId}: ${(err as Error).message}\n`,
+                  )
+                }
+                process.stderr.write(
+                  `telegram gateway: worker ${agentId} card RESURRECTED — false terminal finish reversed, worker resumed (issue #3023)\n`,
+                )
+              },
+              // Issue #3023 (bounded chain). A worker resurrected once and then
+              // falsely finalised again is NOT resurrected forever — the
+              // watcher names it lost. Surface the fact in the log; the
+              // handback (onFinish) still delivered the synthesised result, so
+              // there is nothing further to paint.
+              onWorkerLost: (agentId, _description) => {
+                process.stderr.write(
+                  `telegram gateway: worker ${agentId} NAMED AS LOST — falsely finalised twice, resurrection chain bound reached (issue #3023)\n`,
+                )
+              },
               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