switchroom 0.18.9 → 0.18.10

package/telegram-plugin/gateway/model-command.ts

@@ -175,7 +175,7 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '_Sticky across switchroom-managed relaunches (\`/new\`, watchdog recovery); reverts on \`/restart\`, agent restart, crash, or external container restart. \`/model default\` clears it. To persist, set \`model:\` in switchroom.yaml._'
+  '_Sticky — persists across restarts, deploys, and crashes until \`/model default\` clears it (or the configured \`model:\` in switchroom.yaml changes, which resets it and notifies you). To change the default, set \`model:\` in switchroom.yaml._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
   const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
@@ -230,7 +230,7 @@ export async function handleModelCommand(
   // and ask the operator to retry (parity with the menu callback's isBusy check).
   if (deps.isBusy()) {
     return {
-      text: '⏳ The agent is mid-turn — a model switch needs an idle session. Try again in a moment.',
+      text: '⏳ The agent is mid-turn — a model switch needs an idle session. The switch was not applied.',
       html: true,
     }
   }
@@ -506,6 +506,26 @@ export const SR_MODEL_ALIASES: Record<string, string> = {
 }
 
 /** Expand a short alias (case-insensitive) to its full sr-* id, or return the original. */
+/**
+ * #3042 review blocker 2a: can `token` be trusted for a DURABLE, boot-applied
+ * `.session-model` persist WITHOUT a live confirmation from claude?
+ *
+ * A queued typed `/model <arg>` that is persisted at shutdown was never
+ * validated by claude's picker — and under the keep-by-default boot (#3039)
+ * a garbage-but-shape-valid token (e.g. `claude-nonexistnet-9`) would make
+ * every boot run `claude --model <garbage>` with the gateway dead. Only
+ * tokens with a switchroom-known meaning are offline-trustable: the static
+ * Claude aliases (claude resolves them itself) and the curated sr-* alias
+ * TARGETS (present in the LiteLLM config by construction). Full `claude-*` /
+ * arbitrary `sr-*` ids typed by hand are refused — they need the live
+ * session to verify, so the operator is asked to re-issue after boot.
+ */
+export function isOfflineTrustedModelToken(token: string): boolean {
+  if ((MODEL_ALIASES as readonly string[]).includes(token)) return true
+  if (token in SR_MODEL_ALIASES) return true
+  return Object.values(SR_MODEL_ALIASES).includes(token)
+}
+
 export function expandSrAlias(arg: string): string {
   return SR_MODEL_ALIASES[arg.toLowerCase()] ?? arg
 }
@@ -548,10 +568,67 @@ export function modelSelectCallbackData(label: string): string {
   return `${MODEL_CALLBACK_SELECT}${labelTag(label)}`
 }
 
-function busyReply(deps: Pick<ModelMenuDeps, 'escapeHtml'>): ModelMenuReply {
+const BUSY_REFUSAL_TEXT =
+  '⏳ The agent is mid-turn — the model picker needs an idle prompt. Your tap was not applied.'
+
+/**
+ * Busy-refusal detector (#3039). The gateway's queued-command drain applies a
+ * command believing the session is idle; if a new turn started in the race
+ * window the underlying handler still refuses with one of these texts. The
+ * drain matches on this and RE-ENQUEUES the command instead of stamping the
+ * refusal onto the ack card as a false final state — so no user-visible path
+ * ever ends at "try again".
+ */
+export function isBusyRefusalText(text: string): boolean {
+  return text.includes('The agent is mid-turn')
+}
+
+/**
+ * Mid-turn `/model` menu (#3039): instead of refusing ("try again in a
+ * moment"), render a STATIC keyboard that needs no picker discovery — the
+ * alias rows + the external page. Every switch tap rides the gateway's
+ * mid-turn queue (ack → apply at idle → confirm), so opening the menu during
+ * a long turn still lets the operator lock in a choice.
+ */
+function busyStaticMenu(
+  deps: Pick<ModelMenuDeps, 'escapeHtml'> & Pick<ModelCommandDeps, 'getAgentName'>,
+  page: ModelMenuPage,
+): ModelMenuReply {
+  const externalNames = externalModelNames([])
+  if (page === 'external') {
+    return {
+      text: [
+        `**Model — ${deps.escapeHtml(deps.getAgentName())}** · 🌐 External`,
+        '_Agent is mid-turn — taps are queued and apply the moment the turn ends._',
+        'These models are **billed separately** via OpenRouter. Tap one to switch the **live session**:',
+        PERSIST_NOTE,
+      ].join('\n'),
+      html: true,
+      keyboard: externalPageKeyboard(externalNames),
+    }
+  }
+  const rows: ModelMenuKeyboardButton[][] = []
+  for (const alias of MODEL_ALIASES) {
+    if (alias === 'default') continue
+    rows.push([{
+      text: alias.charAt(0).toUpperCase() + alias.slice(1),
+      callback_data: `${MODEL_CALLBACK_ALIAS}${alias}`,
+    }])
+  }
+  rows.push([{ text: 'Default (configured)', callback_data: `${MODEL_CALLBACK_ALIAS}default` }])
+  if (externalNames.length > 0) {
+    rows.push([{ text: '🌐 External models ▸', callback_data: MODEL_CALLBACK_PAGE_EXTERNAL }])
+  }
+  rows.push([{ text: '🔄 Refresh', callback_data: MODEL_CALLBACK_REFRESH }])
   return {
-    text: '⏳ The agent is mid-turn — the model picker needs an idle prompt. Try again in a moment.',
+    text: [
+      `**Model — ${deps.escapeHtml(deps.getAgentName())}**`,
+      '_Agent is mid-turn, so the live picker can\u2019t be read right now — this is the quick list. A tap is queued and applies the moment the turn ends._',
+      'Tap a model to switch the **live session**:',
+      PERSIST_NOTE,
+    ].join('\n'),
     html: true,
+    keyboard: rows,
   }
 }
 
@@ -654,7 +731,7 @@ export async function buildModelMenu(
   deps: ModelMenuDeps & ModelCommandDeps,
   page: ModelMenuPage = 'main',
 ): Promise<ModelMenuReply> {
-  if (deps.isBusy()) return busyReply(deps)
+  if (deps.isBusy()) return busyStaticMenu(deps, page)
 
   const [discovered, quota, srNames] = await Promise.all([
     deps.discover(deps.getAgentName()),
@@ -734,6 +811,12 @@ export interface ModelCallbackOutcome {
    * "try again" line (which read as "nothing happened").
    */
   toastOnly?: boolean
+  /**
+   * True when this outcome is the mid-turn refusal (#3039). The queued-command
+   * drain re-enqueues on this instead of stamping the refusal onto the ack
+   * card as a false final state.
+   */
+  busyRefusal?: boolean
   /**
    * On a successful session switch, the live model name now running (parsed
    * from claude's confirmation, e.g. "Fable 5"). The gateway records this as
@@ -799,8 +882,9 @@ export async function handleModelMenuCallback(
     if (deps.isBusy()) {
       return {
         answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-        reply: busyReply(deps),
+        reply: { text: BUSY_REFUSAL_TEXT, html: true },
         toastOnly: true,
+        busyRefusal: true,
       }
     }
     let aliasResult: InjectResult
@@ -862,8 +946,9 @@ export async function handleModelMenuCallback(
     if (deps.isBusy()) {
       return {
         answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-        reply: busyReply(deps),
+        reply: { text: BUSY_REFUSAL_TEXT, html: true },
         toastOnly: true,
+        busyRefusal: true,
       }
     }
     try {
@@ -896,8 +981,9 @@ export async function handleModelMenuCallback(
   if (deps.isBusy()) {
     return {
       answer: '⏳ Agent is mid-turn — tap again when it’s idle',
-      reply: busyReply(deps),
+      reply: { text: BUSY_REFUSAL_TEXT, html: true },
       toastOnly: true,
+      busyRefusal: true,
     }
   }
 

package/telegram-plugin/gateway/pending-session-command.ts

@@ -0,0 +1,365 @@
+/**
+ * Deterministic ack-queue-apply-confirm for the session-mutating Telegram
+ * commands (`/model`, `/effort`).
+ *
+ * The bug this closes (#TODO): a `/model` or `/effort` command issued while
+ * the agent is MID-TURN used to dead-end. The typed `/model <name>` path
+ * refused with "⏳ … Try again in a moment." and dropped the request; the
+ * menu taps toasted the same refusal; `/effort` had no busy gate at all and
+ * silently maybe-failed ("sent, but couldn't confirm it applied"). In every
+ * case the operator's choice was lost — they had to notice and re-issue it.
+ *
+ * The contract now, consistent across BOTH commands and BOTH their typed and
+ * menu surfaces:
+ *
+ *   1. immediately APPLICABLE (session idle) → apply + confirm, unchanged.
+ *   2. session MID-TURN → immediately ACK ("📥 … the moment this turn
+ *      finishes"), deterministically QUEUE the request, then APPLY the moment
+ *      the agent goes idle and EDIT the ack card into the confirmation.
+ *
+ * This is a PER-KIND slot store (one slot for `model`, one for `effort`):
+ * same-kind last-write-wins — a rapid `/model fable` then `/model opus`
+ * queues only the latest (the earlier ack card is edited to "superseded") —
+ * while cross-kind requests coexist (a queued `/effort` never displaces a
+ * queued `/model`; both apply at idle). It reuses the same idle-gate
+ * discipline as `pendingRestarts` / proactive `/compact` — drained at the
+ * model-idle gate (`activeTurnStartedAt.size === 0`) with a bounded reaper
+ * fallback so a session that never cleanly idles still applies-or-reports.
+ * The reaper cap DEFERS while a turn is genuinely in flight (see
+ * `drainCapDecision`): forcing mid-turn would hit the typed handler's busy
+ * refusal (dropping the choice) or type into the live claude input.
+ *
+ * The apply itself (running the real handler, recording the session-model
+ * override, editing the ack card) lives in the gateway — this module is the
+ * pure slot + the ack/confirm/superseded text so it is unit-testable without
+ * booting the bot. Mirrors the split shape of model-command.ts /
+ * effort-command.ts.
+ */
+
+export type PendingCommandKind = 'model' | 'effort'
+export type PendingCommandOrigin = 'typed' | 'menu'
+
+export interface PendingSessionCommand {
+  kind: PendingCommandKind
+  /**
+   * How the request arrived — `typed` for `/model <name>` / `/effort <level>`,
+   * `menu` for an inline-keyboard tap. Determines which handler the drain
+   * replays (the typed handler vs the menu-callback handler).
+   */
+  origin: PendingCommandOrigin
+  /**
+   * The apply payload the drain replays verbatim:
+   *   - typed model  → the (alias-expanded) model token, e.g. `fable`, `sr-glm-5`
+   *   - typed effort → the effort level, e.g. `high`
+   *   - menu         → the raw callback data (`mdl:s:<tag>` / `mdl:alias:<a>` /
+   *                    `mdl:sr:<name>` / `eff:s:<level>`), replayed through the
+   *                    menu-callback handler which re-discovers at idle.
+   */
+  arg: string
+  /**
+   * Human-facing label for the ack / superseded text (e.g. `fable`, `high`,
+   * `Gemini 2.5 Pro`). Display-only — never fed to `claude --model`.
+   */
+  targetLabel: string
+  /** The chat the command came from (for building model deps on the deferred apply). */
+  chatId: string
+  /** The forum topic, if any. */
+  threadId?: number
+  /** The chat the ack card was posted to (usually === chatId). */
+  ackChatId: string
+  /** The ack card's message id — the drain EDITS this into the confirmation. */
+  ackMessageId: number
+  requestedAt: number
+}
+
+export interface PendingSessionCommandSlots {
+  /** The queued command of that kind, or null when its slot is empty. */
+  get(kind: PendingCommandKind): PendingSessionCommand | null
+  /**
+   * Enqueue. SAME-KIND last-write-wins: returns the same-kind command it
+   * DISPLACED (if any) so the caller can edit that stale ack card into a
+   * "superseded" note. CROSS-KIND commands coexist — a `/effort` never
+   * displaces a queued `/model` and vice versa.
+   */
+  set(cmd: PendingSessionCommand): PendingSessionCommand | null
+  /** Atomically remove and return the queued command of that kind. */
+  take(kind: PendingCommandKind): PendingSessionCommand | null
+  /**
+   * Atomically remove and return ALL queued commands in enqueue order (a
+   * same-kind re-enqueue moves to the back). The drain's and shutdown's read.
+   */
+  takeAll(): PendingSessionCommand[]
+  /** Snapshot of every queued command WITHOUT removing (the reaper's overdue check). */
+  list(): PendingSessionCommand[]
+  /** Drop every queued command without applying it. */
+  clear(): void
+  /** 0..2 — mirrors the `pendingRestarts.size` gate shape. */
+  readonly size: number
+}
+
+/** Create an empty per-kind slot store. */
+export function createPendingSessionCommandSlots(): PendingSessionCommandSlots {
+  const slots = new Map<PendingCommandKind, PendingSessionCommand>()
+  return {
+    get: (kind: PendingCommandKind) => slots.get(kind) ?? null,
+    set(cmd: PendingSessionCommand): PendingSessionCommand | null {
+      const displaced = slots.get(cmd.kind) ?? null
+      // Delete-then-set so a same-kind re-enqueue moves to the BACK of the
+      // enqueue order — takeAll applies in latest-request order.
+      slots.delete(cmd.kind)
+      slots.set(cmd.kind, cmd)
+      return displaced
+    },
+    take(kind: PendingCommandKind): PendingSessionCommand | null {
+      const cur = slots.get(kind) ?? null
+      slots.delete(kind)
+      return cur
+    },
+    takeAll(): PendingSessionCommand[] {
+      const all = [...slots.values()]
+      slots.clear()
+      return all
+    },
+    list: () => [...slots.values()],
+    clear(): void {
+      slots.clear()
+    },
+    get size(): number {
+      return slots.size
+    },
+  }
+}
+
+/**
+ * IO seams the drain iteration needs from the gateway. Extracted so the
+ * iteration ORDER + loss-safety invariants (#3042 blocker 1) are unit-testable
+ * without booting the bot.
+ */
+export interface DrainIo {
+  /** Is a session relaunch pending (the live session is going away)? */
+  restartPending: () => boolean
+  /** Is a turn in flight right now (re-checked per command)? */
+  turnInFlight: () => boolean
+  /** Apply the command via the real handler; returns the reply body. */
+  apply: (cmd: PendingSessionCommand) => Promise<string>
+  /** Does this reply body mean "refused because busy" (not applied)? */
+  isBusyRefusal: (text: string) => boolean
+  /** Resolve a command that must ride the restart carriers; returns card text. */
+  resolveForRestartText: (cmd: PendingSessionCommand) => string
+  /** Edit the command's ack card. Best-effort. */
+  editCard: (cmd: PendingSessionCommand, text: string) => Promise<void>
+  /** Re-enqueue a command the drain could not safely apply. */
+  reEnqueue: (cmd: PendingSessionCommand) => void
+  /** Render the apply-threw failure card text. */
+  failureText: (cmd: PendingSessionCommand, err: unknown) => string
+}
+
+/**
+ * Drain iteration over the commands takeAll() returned. The loss-safety
+ * invariant (#3042 blocker 1): when the loop must stop early (turn raced in,
+ * or the handler returned a busy refusal), EVERY not-yet-applied taken
+ * command — including the current one — is re-enqueued. takeAll() can hold
+ * both a model AND an effort command; breaking after re-enqueueing only the
+ * current one would silently drop the other with its ack card stuck at
+ * "queued" forever.
+ */
+export async function drainTakenCommands(
+  taken: readonly PendingSessionCommand[],
+  io: DrainIo,
+): Promise<void> {
+  for (let i = 0; i < taken.length; i++) {
+    const cmd = taken[i]
+    if (io.restartPending()) {
+      // The live session is going away — carry the choice across the bounce
+      // via the durable carriers (or the re-issue fallback).
+      await io.editCard(cmd, io.resolveForRestartText(cmd))
+      continue
+    }
+    // Race guard: a new turn may have started before the drain reached this
+    // command. Applying now would hit the handlers' busy refusals and stamp
+    // "not applied" onto the ack card as a false final state.
+    if (io.turnInFlight()) {
+      for (const rest of taken.slice(i)) io.reEnqueue(rest)
+      return
+    }
+    let body: string
+    try {
+      body = await io.apply(cmd)
+    } catch (err) {
+      await io.editCard(cmd, io.failureText(cmd, err))
+      continue
+    }
+    // The handler itself refused because a turn raced in — not applied.
+    if (io.isBusyRefusal(body)) {
+      for (const rest of taken.slice(i)) io.reEnqueue(rest)
+      return
+    }
+    await io.editCard(cmd, body)
+  }
+}
+
+/**
+ * What the reaper's bounded drain-cap should do this tick.
+ *
+ *   - 'wait'                 — nothing queued long enough; keep waiting.
+ *   - 'defer-turn-in-flight' — something IS overdue, but a turn is genuinely
+ *     in flight. Forcing a drain now would destroy the queued command: the
+ *     typed model path hits handleModelCommand's busy gate (the old "try
+ *     again" refusal, choice dropped) and /effort would type into the live
+ *     claude input. The cap only rescues the MISSED-IDLE-GATE case, so keep
+ *     waiting — the idle gate drains at turn end.
+ *   - 'force'                — overdue AND idle: the idle gate was missed;
+ *     force the apply-or-report so the ack card never dangles unresolved.
+ */
+export type DrainCapDecision = 'wait' | 'defer-turn-in-flight' | 'force'
+
+export function drainCapDecision(
+  queued: readonly PendingSessionCommand[],
+  now: number,
+  capMs: number,
+  turnInFlight: boolean,
+): DrainCapDecision {
+  const overdue = queued.some(c => now - c.requestedAt > capMs)
+  if (!overdue) return 'wait'
+  return turnInFlight ? 'defer-turn-in-flight' : 'force'
+}
+
+/** One best-effort ack-card edit the caller should perform. */
+export interface PendingCommandCardEdit {
+  chatId: string
+  messageId: number
+  text: string
+}
+
+/**
+ * What the gateway should DURABLY record for a queued command that can't
+ * apply live because the session is going away (gateway shutdown or a pending
+ * session relaunch). #3039: instead of telling the operator to re-issue, the
+ * choice is persisted to the durable carriers (`.session-model` /
+ * `.session-effort`) that start.sh honors on every boot — so the queued
+ * command still deterministically applies, just via the relaunch.
+ *
+ *   - 'model'        — persist `arg` as the `.session-model` override
+ *   - 'effort'       — persist `arg` as the `.session-effort` override
+ *   - 'clear-model'  — the queued command was `/model default`: clear the carrier
+ *   - 'clear-effort' — the queued command was `/effort default`: clear the carrier
+ *   - null           — not offline-resolvable (a `mdl:s:<tag>` menu selection
+ *                      needs live picker discovery to become a token); the
+ *                      operator is asked to re-issue after boot.
+ */
+export type ShutdownPersistKind = 'model' | 'effort' | 'clear-model' | 'clear-effort' | null
+
+export interface ShutdownResolutionAction {
+  cmd: PendingSessionCommand
+  persist: ShutdownPersistKind
+  /** The canonical token / allowlisted level to persist (when persist != null). */
+  arg: string
+  /** Ack-card edit when the durable write succeeds. */
+  persistedText: string
+  /** Ack-card edit when persist is null or the durable write failed. */
+  reissueText: string
+}
+
+const EFFORT_MENU_SELECT_PREFIX = 'eff:s:'
+
+function classifyShutdownPersist(cmd: PendingSessionCommand): { persist: ShutdownPersistKind; arg: string } {
+  if (cmd.kind === 'effort') {
+    const level = cmd.origin === 'menu' && cmd.arg.startsWith(EFFORT_MENU_SELECT_PREFIX)
+      ? cmd.arg.slice(EFFORT_MENU_SELECT_PREFIX.length)
+      : cmd.arg
+    if (level === 'default') return { persist: 'clear-effort', arg: level }
+    return { persist: 'effort', arg: level }
+  }
+  // model
+  if (cmd.origin === 'menu') return { persist: null, arg: cmd.arg } // mdl:s:<tag> — needs live discovery
+  if (cmd.arg === 'default') return { persist: 'clear-model', arg: cmd.arg }
+  return { persist: 'model', arg: cmd.arg }
+}
+
+function persistedText(cmd: PendingSessionCommand, escapeHtml: (s: string) => string): string {
+  const noun = KIND_NOUN[cmd.kind]
+  const isClear = cmd.arg === 'default' || cmd.targetLabel === 'default'
+  if (isClear) {
+    return `💾 The session is restarting — your ${noun} override was cleared as requested; the agent boots on the configured default.`
+  }
+  return `💾 The session is restarting — your \`${escapeHtml(cmd.targetLabel)}\` ${noun} choice is saved and applies as the agent boots.`
+}
+
+/**
+ * Empty the slots and return, per queued command, what to persist and which
+ * ack-card edit to make. The gateway performs the durable writes (this module
+ * stays fs-free and unit-testable) and edits with `persistedText` on success
+ * or `reissueText` on a null/failed persist. Shared by the SIGTERM shutdown
+ * handler AND the drain's pending-restart branch — a queued choice is never
+ * dropped with a bare "re-issue" when it can be carried across the bounce.
+ */
+export function shutdownResolutionActions(
+  slots: PendingSessionCommandSlots,
+  escapeHtml: (s: string) => string,
+): ShutdownResolutionAction[] {
+  return slots.takeAll().map(cmd => resolveForRestart(cmd, escapeHtml))
+}
+
+/** Single-command form of shutdownResolutionActions (the drain's pending-restart branch). */
+export function resolveForRestart(
+  cmd: PendingSessionCommand,
+  escapeHtml: (s: string) => string,
+): ShutdownResolutionAction {
+  const { persist, arg } = classifyShutdownPersist(cmd)
+  return {
+    cmd,
+    persist,
+    arg,
+    persistedText: persistedText(cmd, escapeHtml),
+    reissueText: restartSupersededText(cmd, escapeHtml),
+  }
+}
+
+const KIND_NOUN: Record<PendingCommandKind, string> = {
+  model: 'model',
+  effort: 'effort',
+}
+
+const KIND_VERB: Record<PendingCommandKind, string> = {
+  model: 'switch to',
+  effort: 'set effort to',
+}
+
+/**
+ * The immediate ACK shown when a command is queued behind a live turn. Names
+ * the target so the operator sees their choice was captured, not dropped.
+ * `escapeHtml` guards the (already shape-gated) label for the HTML send path.
+ */
+export function ackText(
+  kind: PendingCommandKind,
+  targetLabel: string,
+  escapeHtml: (s: string) => string,
+): string {
+  return `📥 Agent is mid-turn — I'll ${KIND_VERB[kind]} \`${escapeHtml(targetLabel)}\` the moment this turn finishes.`
+}
+
+/**
+ * Edited onto a stale ack card when a NEWER command of the same slot displaces
+ * it (last-write-wins). Tells the operator their earlier choice was replaced,
+ * not silently lost.
+ */
+export function supersededText(
+  displaced: PendingSessionCommand,
+  next: PendingSessionCommand,
+  escapeHtml: (s: string) => string,
+): string {
+  return `↩️ Superseded — queued \`${escapeHtml(next.targetLabel)}\` instead (your earlier \`${escapeHtml(displaced.targetLabel)}\` ${KIND_NOUN[displaced.kind]} request was replaced before it applied).`
+}
+
+/**
+ * Edited onto the ack card when the queued command could not apply because the
+ * session is restarting (a Claude-model / effort session change does not
+ * survive the bounce). The operator is told to re-issue after boot rather than
+ * being left believing it landed.
+ */
+export function restartSupersededText(
+  cmd: PendingSessionCommand,
+  escapeHtml: (s: string) => string,
+): string {
+  return `↩️ The session is restarting before your \`${escapeHtml(cmd.targetLabel)}\` ${KIND_NOUN[cmd.kind]} change could apply — re-issue \`/${cmd.kind} ${escapeHtml(cmd.targetLabel)}\` once the agent is back.`
+}

package/telegram-plugin/gateway/permission-timeout.ts

@@ -150,6 +150,31 @@ export function buildTimedOutCardEdits(
   }))
 }
 
+/**
+ * Suffix appended to a card body when its turn is halted by the operator
+ * (#3020 `/stop` / bare "stop" / empty `!`). Same keyboard-strip contract as
+ * the timeout path: the halted turn's MCP permission call is being denied,
+ * so a later Approve tap must not be able to dispatch into an idle session.
+ */
+export const CANCELLED_FOOTER = '\n\n⏹ Cancelled — the turn was stopped'
+
+/**
+ * Build the (pure) list of card edits the halt path applies when the
+ * operator stops the in-flight turn: re-render each recorded card with the
+ * cancelled footer and strip the keyboard. Mirrors buildTimedOutCardEdits.
+ */
+export function buildCancelledCardEdits(
+  cardText: string,
+  cards: readonly PermissionCardRef[],
+): TimedOutCardEdit[] {
+  return cards.map(({ chatId, messageId }) => ({
+    chatId,
+    messageId,
+    text: `${cardText}${CANCELLED_FOOTER}`,
+    stripKeyboard: true,
+  }))
+}
+
 /**
  * A tap on a permission card is STALE when no pending entry exists for its
  * request_id — the reaper already auto-denied + deleted it on TTL. A stale

package/telegram-plugin/gateway/resume-inbound-builder.ts

@@ -140,6 +140,20 @@ export interface ResumeInboundContext {
    *  Rendered into the inbound so the resumed session knows what to
    *  re-dispatch. Omitted / empty → the inbound is unchanged. */
   subagents?: InterruptedSubagent[]
+  /** Why the framework itself triggered the restart, when it did (e.g. the
+   *  bridge-dead escalation, #3038). Surfaced verbatim in the inbound text
+   *  (`note`) and as `meta.restart_cause` (`reason`) so the resume is
+   *  HONEST about the cause — a bridge-dead bounce must not read as an
+   *  operator restart or masquerade as a watchdog timeout. Omitted → the
+   *  inbound is unchanged (the common human-restart/crash case). */
+  restartCause?: { reason: string; note: string }
+}
+
+/** Render the optional framework-restart-cause block appended to a resume /
+ *  report inbound. Empty string when no cause was recorded. */
+function renderRestartCauseBlock(cause: { note: string } | undefined): string {
+  if (!cause || cause.note.trim().length === 0) return ''
+  return `\n\nWhy this restart happened: ${cause.note.trim()}`
 }
 
 /**
@@ -223,6 +237,7 @@ export function buildResumeInterruptedInbound(ctx: ResumeInboundContext): Inboun
     started_at: String(ctx.turn.started_at),
   }
   if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  if (ctx.restartCause) meta.restart_cause = ctx.restartCause.reason
   return {
     type: 'inbound',
     chatId: ctx.turn.chat_id,
@@ -247,7 +262,8 @@ export function buildResumeInterruptedInbound(ctx: ResumeInboundContext): Inboun
       `actual task. Do not ask whether to resume; just resume. If even after ` +
       `reading the recent messages you genuinely can't tell what the work was, ` +
       `say so and ask.` +
-      renderInterruptedSubagentsBlock(ctx.subagents),
+      renderInterruptedSubagentsBlock(ctx.subagents) +
+      renderRestartCauseBlock(ctx.restartCause),
     meta,
   }
 }
@@ -287,6 +303,7 @@ export function buildResumeWatchdogReportInbound(
   }
   if (ctx.turn.tool_call_count != null) meta.tool_call_count = String(ctx.turn.tool_call_count)
   if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  if (ctx.restartCause) meta.restart_cause = ctx.restartCause.reason
   return {
     type: 'inbound',
     chatId: ctx.turn.chat_id,
@@ -309,7 +326,8 @@ export function buildResumeWatchdogReportInbound(
       `speculate about a deeper root cause you can't see.` +
       // Deferred (non-assertive) form: this is the ask-first path — the killed
       // workers are listed as facts, but re-dispatch waits on the user's call.
-      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }),
+      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }) +
+      renderRestartCauseBlock(ctx.restartCause),
     meta,
   }
 }
@@ -398,6 +416,7 @@ export function buildResumeDeferredReportInbound(
     started_at: String(ctx.turn.started_at),
   }
   if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
+  if (ctx.restartCause) meta.restart_cause = ctx.restartCause.reason
   const cause =
     ctx.reason === 'loop-guard'
       ? `Your previous turn was ALREADY a resume of earlier interrupted work, ` +
@@ -428,7 +447,8 @@ export function buildResumeDeferredReportInbound(
       // Deferred (non-assertive) form, same as the watchdog path: this is an
       // ask-first inbound — killed workers are named as facts, but
       // re-dispatch waits on the user's call.
-      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }),
+      renderInterruptedSubagentsBlock(ctx.subagents, { assertive: false }) +
+      renderRestartCauseBlock(ctx.restartCause),
     meta,
   }
 }