switchroom 0.18.8 → 0.18.10

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/pending-state-stores.ts

@@ -0,0 +1,106 @@
+/**
+ * In-memory storage for the LONG-TAIL of gateway.ts pending-state Maps —
+ * the auth/vault-wizard, config-edit correlation, and transient capture Maps
+ * that PR #3008 deferred when it moved the four agent-initiated approval-card
+ * families behind `approval-card-stores.ts`. Phase 3 step 2 of the gateway
+ * decomposition (see #2996): STORAGE ONLY.
+ *
+ * Two shapes, mirroring the two shapes the long-tail Maps actually have:
+ *
+ *  - `createSweepableStore<T>(isExpired)` — a Map-compatible store whose
+ *    `sweep(now)` deletes every entry the caller's `isExpired(value, now)`
+ *    predicate reports as past its TTL. The predicate is supplied by the
+ *    gateway and CLOSES OVER the family's TTL constant, so the TTL and its
+ *    comparison DIRECTION stay verbatim in gateway.ts — different families use
+ *    `now - staged_at > TTL`, `now - startedAt > TTL`, `now - createdAt > TTL`,
+ *    or an absolute `now > expiresAt`, and each is preserved byte-identically.
+ *    `sweep` is a plain delete-past-TTL loop (no wake / side effects); it
+ *    replaces the identical open-coded reaper / standalone-sweep loops. The
+ *    delete-during-iteration is safe (JS Map iterators tolerate deleting the
+ *    current key) — exactly as the original loops relied on.
+ *
+ *  - `createPlainStore<T>()` — a Map-compatible store with NO sweep, for the
+ *    long-tail Maps whose lifetime is bounded by per-entry timers or an
+ *    LRU cap rather than a TTL sweep (`pendingAskUser`, `agentButtonMeta`).
+ *
+ * Why a Map-compatible surface (get/set/delete/has/size/keys/values/entries/
+ * forEach/iteration) rather than a bespoke API: every existing gateway call
+ * site used the raw Map directly. Preserving the exact Map method surface —
+ * and keeping the variable name unchanged — keeps those call sites
+ * BYTE-IDENTICAL. The store moves WHERE the Map is constructed and (for the
+ * sweepable shape) WHERE its sweep lives, nothing about how the gateway reads
+ * or writes it.
+ *
+ * The backing Map is the sole storage and backs every iterator, so mutation-
+ * during-iteration order/semantics are identical to the raw Map the gateway
+ * used before.
+ */
+
+export interface PlainStore<T> {
+  get(key: string): T | undefined
+  set(key: string, value: T): void
+  delete(key: string): boolean
+  has(key: string): boolean
+  clear(): void
+  readonly size: number
+  keys(): IterableIterator<string>
+  values(): IterableIterator<T>
+  entries(): IterableIterator<[string, T]>
+  forEach(cb: (value: T, key: string, map: Map<string, T>) => void): void
+  [Symbol.iterator](): IterableIterator<[string, T]>
+}
+
+export interface SweepableStore<T> extends PlainStore<T> {
+  /**
+   * Delete every entry past its TTL per the injected `isExpired` predicate.
+   * Plain delete-past-TTL, no wake — byte-identical to the open-coded reaper /
+   * standalone sweep loop it replaces.
+   */
+  sweep(now: number): void
+}
+
+// Build the shared Map surface onto `target` (a getter for `size`, so the
+// live Map size is read on every access — an object spread would freeze it).
+function attachMapSurface<T, S extends object>(target: S, map: Map<string, T>): S & PlainStore<T> {
+  return Object.defineProperties(target, {
+    get: { value: (key: string) => map.get(key), enumerable: true },
+    set: { value: (key: string, value: T) => void map.set(key, value), enumerable: true },
+    delete: { value: (key: string) => map.delete(key), enumerable: true },
+    has: { value: (key: string) => map.has(key), enumerable: true },
+    clear: { value: () => map.clear(), enumerable: true },
+    size: { get: () => map.size, enumerable: true },
+    keys: { value: () => map.keys(), enumerable: true },
+    values: { value: () => map.values(), enumerable: true },
+    entries: { value: () => map.entries(), enumerable: true },
+    forEach: {
+      value: (cb: (value: T, key: string, m: Map<string, T>) => void) => map.forEach(cb),
+      enumerable: true,
+    },
+    [Symbol.iterator]: { value: () => map[Symbol.iterator](), enumerable: true },
+  }) as S & PlainStore<T>
+}
+
+/**
+ * Create a Map-backed store with no automatic expiry. For long-tail Maps
+ * whose entries are removed by per-entry timers or an LRU cap, not a TTL sweep.
+ */
+export function createPlainStore<T>(): PlainStore<T> {
+  return attachMapSurface({}, new Map<string, T>())
+}
+
+/**
+ * Create a Map-backed, self-sweeping store for one long-tail pending-state
+ * family. `isExpired` closes over the family's TTL constant and encodes its
+ * exact comparison direction; `sweep(now)` deletes every entry it flags.
+ */
+export function createSweepableStore<T>(
+  isExpired: (value: T, now: number) => boolean,
+): SweepableStore<T> {
+  const map = new Map<string, T>()
+  const sweep = (now: number): void => {
+    for (const [k, v] of map) {
+      if (isExpired(v, now)) map.delete(k)
+    }
+  }
+  return attachMapSurface({ sweep }, map)
+}

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/register-bot-commands.ts

@@ -0,0 +1,30 @@
+import type { Bot } from 'grammy'
+import {
+  TELEGRAM_BASE_COMMANDS,
+  TELEGRAM_SWITCHROOM_COMMANDS,
+} from '../welcome-text.js'
+
+/**
+ * Register the bot's slash-command menu with Telegram (`setMyCommands`).
+ *
+ * Extracted verbatim from gateway.ts (#2996 Phase 5 leaf move). The `bot`
+ * singleton is injected rather than imported so this stays a pure leaf with
+ * no back-reference into the gateway module.
+ *
+ * Slash-menu is deliberately trimmed from the full command catalogue.
+ * See telegram-plugin/welcome-text.ts TELEGRAM_MENU_COMMANDS for the
+ * rationale (mobile UX focus; ops primitives stay typable but out of
+ * the autocomplete clutter). /commands surfaces the full list.
+ */
+export async function registerSwitchroomBotCommands(bot: Bot): Promise<void> {
+  await bot.api.setMyCommands(
+    [...TELEGRAM_BASE_COMMANDS, ...TELEGRAM_SWITCHROOM_COMMANDS],
+    { scope: { type: 'all_private_chats' } },
+  )
+  // Group chats don't support /start pairing, so only the switchroom
+  // commands are registered there.
+  await bot.api.setMyCommands(
+    TELEGRAM_SWITCHROOM_COMMANDS,
+    { scope: { type: 'all_group_chats' } },
+  )
+}

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,
   }
 }