switchroom 0.14.48 → 0.14.50

package/telegram-plugin/gateway/boot-card-msgid.ts

@@ -0,0 +1,70 @@
+/**
+ * Cross-reboot persistence for the boot card's Telegram message id.
+ *
+ * Why: a freshly *sent* Telegram message always bumps the chat's unread
+ * badge — `disable_notification: true` removes the sound/banner but not the
+ * badge (there is no Bot API flag for that). To make routine reboots produce
+ * ZERO notification (operator request, 2026-06-03), the gateway reuses the
+ * PRIOR boot card's message and EDITS it in place instead of sending a new
+ * one — and edits never touch the badge.
+ *
+ * That requires remembering the last boot card's `message_id` across gateway
+ * restarts, keyed by the chat (+ forum topic) it lives in. This module is the
+ * tiny JSON store for that, mirroring `config-snapshot.ts` /
+ * `boot-issue-cache.ts`: one file under the agent's (bind-mounted, reboot-
+ * surviving) state dir, read once on boot, written once after the id is
+ * established. All failures are non-fatal — a missing/corrupt file just means
+ * "no prior card", so the boot path falls back to a fresh (silent) send.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+
+/** Stable key for a boot-card target: chat id + optional forum topic. A DM
+ *  agent always boots to the same `<chatId>:` key; a supergroup agent keys by
+ *  `<chatId>:<threadId>` so a topic change starts a fresh card. */
+export function bootCardChatKey(chatId: string, threadId: number | undefined): string {
+  return `${chatId}:${threadId ?? ''}`
+}
+
+type Store = Record<string, number>
+
+function readStore(path: string): Store {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Store
+    }
+  } catch {
+    /* missing / corrupt → treat as empty */
+  }
+  return {}
+}
+
+/** The persisted message id for this chat+topic, or null when there's no
+ *  prior boot card to reuse (first boot, corrupt file, different chat). */
+export function loadBootCardMsgId(
+  path: string,
+  chatKey: string,
+): number | null {
+  const id = readStore(path)[chatKey]
+  return typeof id === 'number' && Number.isFinite(id) && id > 0 ? id : null
+}
+
+/** Record the current boot card's message id for this chat+topic. Merges into
+ *  the existing store (other chats' ids survive). Non-fatal on write failure —
+ *  the worst case is the next reboot sends a fresh card (one badge). */
+export function saveBootCardMsgId(
+  path: string,
+  chatKey: string,
+  messageId: number,
+): void {
+  if (!(Number.isFinite(messageId) && messageId > 0)) return
+  try {
+    const store = readStore(path)
+    if (store[chatKey] === messageId) return // idempotent — no rewrite
+    store[chatKey] = messageId
+    writeFileSync(path, JSON.stringify(store), 'utf8')
+  } catch {
+    /* non-fatal */
+  }
+}

package/telegram-plugin/gateway/boot-card.ts

@@ -67,6 +67,7 @@ import {
   type ConfigDiff,
 } from './config-snapshot.js'
 import { join } from 'path'
+import { bootCardChatKey, loadBootCardMsgId, saveBootCardMsgId } from './boot-card-msgid.js'
 import { loadConfig as _loadSwitchroomConfig } from '../../src/config/loader.js'
 import { resolveAgentConfig as _resolveAgentConfig } from '../../src/config/merge.js'
 
@@ -134,6 +135,21 @@ export interface BotApiForBootCard {
     text: string,
     opts?: Record<string, unknown>,
   ): Promise<unknown>
+  /**
+   * Like `editMessageText`, but reports whether the target message still
+   * exists rather than swallowing a "message to edit not found" the way the
+   * shared retry policy does (retry-api-call.ts) — the boot path needs to
+   * know so it can fall back to a fresh send when the prior card was deleted.
+   * `'edited'` = the edit landed (or content was identical → message exists);
+   * `'gone'` = the message is missing (or any other error → send fresh).
+   * Optional so existing callers/tests without it fall back to always-send.
+   */
+  editMessageTextStrict?(
+    chatId: string,
+    messageId: number,
+    text: string,
+    opts?: Record<string, unknown>,
+  ): Promise<'edited' | 'gone'>
 }
 
 export interface BootCardHandle {
@@ -568,6 +584,17 @@ export interface RunProbesOpts {
    * resolve the default memory collection label.
    */
   configSnapshotPath?: string
+  /**
+   * Cross-reboot store for the boot card's Telegram message id (JSON,
+   * typically `<agentDir>/.boot-card-msgid.json`). When set AND the bot
+   * supports `editMessageTextStrict`, a routine reboot (no `ackMessageId`)
+   * EDITS the prior boot card in place instead of sending a new one — edits
+   * never bump the unread badge, so reboots produce zero notification
+   * (operator request 2026-06-03). Falls back to a fresh silent send when
+   * there's no prior card or it was deleted. Omit to keep the always-send
+   * behaviour.
+   */
+  bootCardStatePath?: string
 }
 
 /** Run all six probes concurrently with their own per-probe timeouts.
@@ -641,20 +668,60 @@ export async function startBootCard(
   // the chat is where you look, and nothing here warrants a push.
   const silentBootCard = true
 
-  let messageId: number
-  try {
-    const sent = await bot.sendMessage(chatId, ackText, {
-      parse_mode: 'HTML',
-      link_preview_options: { is_disabled: true },
-      ...(threadId != null ? { message_thread_id: threadId } : {}),
-      ...(ackMessageId != null ? { reply_parameters: { message_id: ackMessageId } } : {}),
-      ...(silentBootCard ? { disable_notification: true } : {}),
-    })
-    messageId = sent.message_id
-    logger(`telegram gateway: boot-card: posted msgId=${messageId} chatId=${chatId} reason=${opts.restartReason ?? '-'} reason_detail=${opts.restartReasonDetail ?? '-'} silent=${silentBootCard}\n`)
-  } catch (err: unknown) {
-    logger(`telegram gateway: boot-card: failed to post ack: ${(err as Error)?.message ?? String(err)}\n`)
-    return { messageId: -1, complete: () => {} }
+  // Edit-in-place to produce ZERO notification (operator request 2026-06-03).
+  // A sent message always bumps the unread badge — `disable_notification`
+  // only kills the sound/banner. So for a ROUTINE reboot (no `ackMessageId`:
+  // operator update / cli rollout / crash / fresh) we EDIT the prior boot
+  // card in place — edits never touch the badge — instead of sending a new
+  // one. We only do this when the bot can tell us the prior message still
+  // exists (`editMessageTextStrict`); if it's gone, or this is a
+  // Telegram-initiated `/restart` (ackMessageId set — the operator asked and
+  // is watching, and the card should reply to their command), we fall back to
+  // a fresh silent send.
+  const chatKey = bootCardChatKey(chatId, threadId)
+  const reuseId =
+    ackMessageId == null && opts.bootCardStatePath != null && bot.editMessageTextStrict != null
+      ? loadBootCardMsgId(opts.bootCardStatePath, chatKey)
+      : null
+
+  let messageId = -1
+  if (reuseId != null && bot.editMessageTextStrict != null) {
+    try {
+      const outcome = await bot.editMessageTextStrict(chatId, reuseId, ackText, {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+        ...(threadId != null ? { message_thread_id: threadId } : {}),
+      })
+      if (outcome === 'edited') {
+        messageId = reuseId
+        logger(`telegram gateway: boot-card: reused msgId=${messageId} chatId=${chatId} reason=${opts.restartReason ?? '-'} reason_detail=${opts.restartReasonDetail ?? '-'} edit_in_place=true notify=none\n`)
+      }
+    } catch (err: unknown) {
+      logger(`telegram gateway: boot-card: edit-in-place probe failed (${(err as Error)?.message ?? String(err)}) — sending fresh\n`)
+    }
+  }
+
+  if (messageId < 0) {
+    try {
+      const sent = await bot.sendMessage(chatId, ackText, {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+        ...(threadId != null ? { message_thread_id: threadId } : {}),
+        ...(ackMessageId != null ? { reply_parameters: { message_id: ackMessageId } } : {}),
+        ...(silentBootCard ? { disable_notification: true } : {}),
+      })
+      messageId = sent.message_id
+      logger(`telegram gateway: boot-card: posted msgId=${messageId} chatId=${chatId} reason=${opts.restartReason ?? '-'} reason_detail=${opts.restartReasonDetail ?? '-'} silent=${silentBootCard}\n`)
+    } catch (err: unknown) {
+      logger(`telegram gateway: boot-card: failed to post ack: ${(err as Error)?.message ?? String(err)}\n`)
+      return { messageId: -1, complete: () => {} }
+    }
+  }
+
+  // Remember this card's id so the NEXT reboot can edit it in place (no
+  // notification). Idempotent on reuse; non-fatal on write failure.
+  if (opts.bootCardStatePath != null && messageId > 0) {
+    saveBootCardMsgId(opts.bootCardStatePath, chatKey, messageId)
   }
 
   // Determine the live window for agent-service status updates. Callers

package/telegram-plugin/gateway/gateway.ts

@@ -9,7 +9,7 @@
  * is connected, inbound LLM messages get a "⏳ Agent is restarting…" reply.
  */
 
-import { Bot, GrammyError, InlineKeyboard, InputFile, type Context } from 'grammy'
+import { Bot, GrammyError, InlineKeyboard, InputFile, type Context, type Api } from 'grammy'
 import { run, type RunnerHandle } from '@grammyjs/runner'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { randomBytes } from 'crypto'
@@ -287,6 +287,7 @@ import {
   sweep as sweepDeliveryQueue,
   forgetDelivery,
   shouldTrackDelivery,
+  isTrackableResumeSynthetic,
   type PendingDelivery,
 } from './inbound-delivery-confirm.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
@@ -2603,6 +2604,26 @@ function wrapBootCardApi(
           ),
         opts(cid),
       ) as Promise<unknown>,
+    // Strict edit for the boot-card edit-in-place probe: distinguishes
+    // "message gone" (→ 'gone', caller sends fresh) from a landed/identical
+    // edit (→ 'edited'). robustApiCall SWALLOWS "message to edit not found"
+    // to undefined (retry-api-call.ts), so this can't go through it — a
+    // deliberate single-attempt raw edit that classifies the error itself.
+    editMessageTextStrict: async (cid, mid, text, editOpts) => {
+      type EditOpts = Parameters<Api['editMessageText']>[3]
+      try {
+        // allow-raw-bot-api: boot-card edit-in-place probe — must detect a deleted target, which the shared retry policy swallows.
+        await lockedBot.api.editMessageText(cid, mid, text, editOpts as EditOpts)
+        return 'edited'
+      } catch (err) {
+        const desc =
+          err instanceof GrammyError ? err.description : err instanceof Error ? err.message : String(err)
+        // Content identical → message still exists; reuse it.
+        if (typeof desc === 'string' && desc.toLowerCase().includes('not modified')) return 'edited'
+        // Not found, or any other error → fall back to a fresh silent send.
+        return 'gone'
+      }
+    },
   }
 }
 
@@ -4192,15 +4213,17 @@ _deliveryMachineTick.unref?.()
 // re-deliver forever.
 function trackRedeliveredInbound(merged: InboundMessage): void {
   if (!DELIVERY_CONFIRM_ENABLED) return
+  // The boot-resume synthetic ('resume_interrupted') is the ONE synthetic we DO
+  // enrol: a restart can drop it into a not-ready session exactly like a user
+  // inbound, leaving the interrupted work silently un-resumed. Safe iff it
+  // carries the chat_id + message_id that make its enqueue ack-able — see
+  // isTrackableResumeSynthetic. Every other synthetic stays excluded below.
+  const isTrackableResume = isTrackableResumeSynthetic(merged.meta)
   if (
+    !isTrackableResume &&
     !shouldTrackDelivery({
       isSteering: false,
       isInterrupt: false,
-      // Synthetic inbounds (cron / vault / handback / resume) carry a source
-      // and are NOT tracked here — they enqueue under their own semantics, and
-      // (for the resume synthetics) tracking them safely first needs the
-      // resume builder to emit meta.message_id so the deliver-until-acked ack
-      // matches its enqueue. Tracked separately as a follow-up (see PR notes).
       hasSource: merged.meta?.source != null,
       effectiveText: merged.text,
     })
@@ -4578,6 +4601,7 @@ const ipcServer: IpcServer = createIpcServer({
             tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
             dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
             configSnapshotPath: join(resolvedAgentDirForCard, '.config-snapshot.json'),
+            bootCardStatePath: join(resolvedAgentDirForCard, '.boot-card-msgid.json'),
             ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
           }, ackMsgId).then(handle => {
             activeBootCard = handle
@@ -18469,6 +18493,7 @@ void (async () => {
                       tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
                       dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
                       configSnapshotPath: join(resolvedAgentDirForBootCard, '.config-snapshot.json'),
+                      bootCardStatePath: join(resolvedAgentDirForBootCard, '.boot-card-msgid.json'),
                       ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
                     }, ackMsgId)
                     activeBootCard = handle

package/telegram-plugin/gateway/inbound-delivery-confirm.ts

@@ -158,3 +158,29 @@ export function shouldTrackDelivery(input: {
   if (input.effectiveText !== undefined && input.effectiveText.trim().length === 0) return false
   return true
 }
+
+/**
+ * The ONE synthetic-source inbound that IS safe to enrol in the
+ * deliver-until-acked queue: the boot-resume synthetic
+ * (`meta.source === 'resume_interrupted'`). A restart can drop it into a
+ * not-ready (slow MCP boot) session exactly like a user inbound, leaving the
+ * interrupted work silently un-resumed — so it needs the same re-delivery
+ * backstop. It is safe to track ONLY when it carries BOTH:
+ *   - `meta.chat_id` — so the gateway's enqueue handler (gated on `ev.chatId`)
+ *     builds a currentTurn AND fires `ackDelivery` for it; and
+ *   - `meta.message_id` — so the enqueue's id round-trips and `ackDelivery`
+ *     matches THIS synthetic, stopping the sweep (no re-deliver-forever storm).
+ * Every other synthetic (cron / vault / handback / the watchdog `report`) omits
+ * `meta.message_id` and stays excluded by `shouldTrackDelivery`'s `hasSource`
+ * gate. We require message_id here (chat_id is implied by the ack mechanics);
+ * without a round-trippable id, tracking would storm.
+ */
+export function isTrackableResumeSynthetic(
+  meta: Record<string, string> | undefined,
+): boolean {
+  return (
+    meta?.source === 'resume_interrupted' &&
+    meta.message_id != null &&
+    meta.message_id !== ''
+  )
+}

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

@@ -78,14 +78,33 @@ function promptClause(turn: Turn): string {
 export function buildResumeInterruptedInbound(ctx: ResumeInboundContext): InboundMessage {
   const ts = ctx.nowMs ?? Date.now()
   const elapsed = humanizeElapsed(ts - ctx.turn.started_at)
+  const threadId = threadIdNum(ctx.turn)
   const meta: Record<string, string> = {
     source: 'resume_interrupted',
+    // Carry the originating chat/topic as model-visible channel attributes
+    // (mirrors the real-inbound + subagent_handback shapes — see
+    // gateway.ts:10753 and subagent-handback-inbound-builder.ts:115-121).
+    // Without meta.chat_id the enqueue's channel XML has no chat_id, so the
+    // gateway's enqueue handler (gateway.ts `if (ev.chatId)`) never builds a
+    // currentTurn for the resume turn — meaning no progress card, no
+    // silence-poke protection, and the reply falling back to the agent's
+    // default chat instead of the topic the interrupted work lived in.
+    chat_id: ctx.turn.chat_id,
+    ...(threadId != null ? { message_thread_id: String(threadId) } : {}),
+    // message_id rounds-trips the fabricated `ts` through the enqueue's
+    // channel XML so the deliver-until-acked queue can ack THIS synthetic by
+    // its own enqueue id (gateway trackRedeliveredInbound carve-in). It is
+    // never used as a Telegram reply_to: the model's reply tool quotes the
+    // real prior user message via getLatestInboundMessageId (role='user',
+    // synthetics aren't in history), and the activity feed anchors with
+    // allow_sending_without_reply. Required so tracking the resume can ack and
+    // never re-delivers forever.
+    message_id: String(ts),
     resume_turn_key: ctx.turn.turn_key,
     interrupted_via: ctx.turn.ended_via ?? 'restart',
     started_at: String(ctx.turn.started_at),
   }
   if (ctx.turn.user_prompt_preview) meta.original_prompt = ctx.turn.user_prompt_preview
-  const threadId = threadIdNum(ctx.turn)
   return {
     type: 'inbound',
     chatId: ctx.turn.chat_id,
@@ -127,8 +146,15 @@ export function buildResumeWatchdogReportInbound(
     ctx.turn.tool_call_count != null && ctx.turn.tool_call_count > 0
       ? ` You'd run ${ctx.turn.tool_call_count} tool call${ctx.turn.tool_call_count === 1 ? '' : 's'} before it stalled.`
       : ''
+  const threadId = threadIdNum(ctx.turn)
   const meta: Record<string, string> = {
     source: 'resume_watchdog_timeout',
+    // Origin chat/topic as channel attributes so the report turn gets a
+    // currentTurn (progress card + silence-poke) and the "your last turn was
+    // interrupted" notice lands in the topic the work lived in, not the
+    // agent's default chat. Same rationale as buildResumeInterruptedInbound.
+    chat_id: ctx.turn.chat_id,
+    ...(threadId != null ? { message_thread_id: String(threadId) } : {}),
     resume_turn_key: ctx.turn.turn_key,
     interrupted_via: 'timeout',
     idle_ms: String(ctx.idleMs),
@@ -136,7 +162,6 @@ 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
-  const threadId = threadIdNum(ctx.turn)
   return {
     type: 'inbound',
     chatId: ctx.turn.chat_id,

package/telegram-plugin/tests/boot-card-edit-in-place.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Edit-in-place boot card (zero-notification reboots, operator request
+ * 2026-06-03). A routine reboot must EDIT the prior boot card rather than
+ * send a new one — a sent message bumps the unread badge even with
+ * `disable_notification: true`; an edit never does.
+ *
+ * Pins the startBootCard contract:
+ *   - first boot (no persisted id) → SEND + persist the id
+ *   - next routine boot (persisted id exists) → EDIT in place, NO send
+ *   - persisted id but message deleted ('gone') → fall back to SEND
+ *   - Telegram-initiated /restart (ackMessageId set) → SEND fresh (replies to
+ *     the operator's command; they asked and are watching)
+ *   - no bootCardStatePath → always SEND (back-compat)
+ *
+ * State is an isolated mkdtemp file — NEVER ~/.switchroom (test discipline).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { startBootCard } from '../gateway/boot-card.js'
+import type { BotApiForBootCard } from '../gateway/boot-card.js'
+
+let dir: string
+let statePath: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'boot-card-eip-'))
+  statePath = join(dir, '.boot-card-msgid.json')
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+/** Capturing bot with a configurable strict-edit outcome. */
+function makeBot(strictOutcome: 'edited' | 'gone' | null) {
+  const sends: Array<{ chatId: string; opts: Record<string, unknown> }> = []
+  const strictEdits: Array<{ chatId: string; messageId: number }> = []
+  let nextId = 1000
+  const bot: BotApiForBootCard = {
+    sendMessage: async (chatId, _text, opts) => {
+      sends.push({ chatId, opts: opts ?? {} })
+      return { message_id: ++nextId }
+    },
+    editMessageText: async () => ({}),
+    ...(strictOutcome != null
+      ? {
+          editMessageTextStrict: async (chatId: string, messageId: number) => {
+            strictEdits.push({ chatId, messageId })
+            return strictOutcome
+          },
+        }
+      : {}),
+  }
+  return { bot, sends, strictEdits }
+}
+
+function mkOpts(overrides: Record<string, unknown> = {}) {
+  return {
+    agentName: 'TestAgent',
+    agentSlug: 'test-agent',
+    version: 'v0.0.0-test',
+    agentDir: dir,
+    gatewayInfo: { pid: 1, startedAtMs: Date.now() },
+    restartReason: 'graceful' as const,
+    agentLiveWindowMs: 0, // disable the live loop — we assert the initial post/edit only
+    settleWindowMs: 1_000_000,
+    bootCardStatePath: statePath,
+    ...overrides,
+  }
+}
+
+describe('boot card — edit-in-place (zero-notification reboots)', () => {
+  it('first boot with no persisted id → sends, and persists the id', async () => {
+    const { bot, sends, strictEdits } = makeBot('edited')
+    await startBootCard('chat1', undefined, bot, mkOpts())
+    expect(sends).toHaveLength(1) // first boot must send (one badge, ever)
+    expect(strictEdits).toHaveLength(0)
+    expect(sends[0]!.opts.disable_notification).toBe(true) // still silent
+  })
+
+  it('second routine boot → edits the prior card in place, NO new send', async () => {
+    // Boot 1 sends + persists.
+    const first = makeBot('edited')
+    await startBootCard('chat1', undefined, first.bot, mkOpts())
+    expect(first.sends).toHaveLength(1)
+
+    // Boot 2 (same state file) → reuse via strict edit, no send.
+    const second = makeBot('edited')
+    await startBootCard('chat1', undefined, second.bot, mkOpts())
+    expect(second.sends).toHaveLength(0) // ← zero notification: no new message
+    expect(second.strictEdits).toHaveLength(1)
+    // Boot 1's send returned message_id 1001 (nextId starts at 1000, ++ first);
+    // boot 2 must edit exactly that persisted id.
+    expect(second.strictEdits[0]!.messageId).toBe(1001)
+  })
+
+  it('persisted id but message was deleted (gone) → falls back to a fresh send', async () => {
+    const first = makeBot('edited')
+    await startBootCard('chat1', undefined, first.bot, mkOpts())
+
+    const second = makeBot('gone')
+    await startBootCard('chat1', undefined, second.bot, mkOpts())
+    expect(second.strictEdits).toHaveLength(1) // probed the old id
+    expect(second.sends).toHaveLength(1) // and fell back to a fresh send
+    expect(second.sends[0]!.opts.disable_notification).toBe(true)
+  })
+
+  it('Telegram-initiated /restart (ackMessageId set) → sends fresh, never edits', async () => {
+    // Seed a persisted id from a routine boot.
+    const seed = makeBot('edited')
+    await startBootCard('chat1', undefined, seed.bot, mkOpts())
+
+    // A /restart passes ackMessageId → must reply with a fresh card, not edit.
+    const restart = makeBot('edited')
+    await startBootCard('chat1', undefined, restart.bot, mkOpts(), 555)
+    expect(restart.strictEdits).toHaveLength(0) // no reuse on user-initiated restart
+    expect(restart.sends).toHaveLength(1)
+    expect(restart.sends[0]!.opts.reply_parameters).toEqual({ message_id: 555 })
+  })
+
+  it('no bootCardStatePath → always sends (back-compat, unchanged)', async () => {
+    const { bot, sends, strictEdits } = makeBot('edited')
+    await startBootCard('chat1', undefined, bot, mkOpts({ bootCardStatePath: undefined }))
+    expect(sends).toHaveLength(1)
+    expect(strictEdits).toHaveLength(0)
+  })
+
+  it('bot without editMessageTextStrict → always sends (graceful degrade)', async () => {
+    const { bot, sends } = makeBot(null) // no strict method
+    await startBootCard('chat1', undefined, bot, mkOpts())
+    const second = makeBot(null)
+    await startBootCard('chat1', undefined, second.bot, mkOpts())
+    // Both boots send — no strict method means no in-place reuse path.
+    expect(sends).toHaveLength(1)
+    expect(second.sends).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/boot-card-msgid.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Unit tests for the cross-reboot boot-card message-id store
+ * (gateway/boot-card-msgid.ts) — the persistence that lets a routine reboot
+ * EDIT the prior boot card in place (zero notification) instead of sending a
+ * new one.
+ *
+ * All I/O is to an isolated mkdtemp dir — NEVER ~/.switchroom (test discipline).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  bootCardChatKey,
+  loadBootCardMsgId,
+  saveBootCardMsgId,
+} from '../gateway/boot-card-msgid.js'
+
+let dir: string
+let path: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'boot-card-msgid-'))
+  path = join(dir, '.boot-card-msgid.json')
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+describe('bootCardChatKey', () => {
+  it('keys a DM (no topic) distinctly from a supergroup topic', () => {
+    expect(bootCardChatKey('12345', undefined)).toBe('12345:')
+    expect(bootCardChatKey('-1001234567890', 4)).toBe('-1001234567890:4')
+    // Different topics in the same supergroup are distinct cards.
+    expect(bootCardChatKey('-100', 3)).not.toBe(bootCardChatKey('-100', 4))
+  })
+})
+
+describe('loadBootCardMsgId / saveBootCardMsgId', () => {
+  it('returns null when the file does not exist (first boot)', () => {
+    expect(loadBootCardMsgId(path, 'dm:')).toBeNull()
+  })
+
+  it('round-trips a saved id', () => {
+    saveBootCardMsgId(path, 'dm:', 353)
+    expect(loadBootCardMsgId(path, 'dm:')).toBe(353)
+  })
+
+  it('keeps ids for different chats independent', () => {
+    saveBootCardMsgId(path, 'dm:', 100)
+    saveBootCardMsgId(path, '-100:4', 200)
+    expect(loadBootCardMsgId(path, 'dm:')).toBe(100)
+    expect(loadBootCardMsgId(path, '-100:4')).toBe(200)
+    // Updating one leaves the other intact.
+    saveBootCardMsgId(path, 'dm:', 101)
+    expect(loadBootCardMsgId(path, 'dm:')).toBe(101)
+    expect(loadBootCardMsgId(path, '-100:4')).toBe(200)
+  })
+
+  it('returns null for an unknown chat key', () => {
+    saveBootCardMsgId(path, 'dm:', 1)
+    expect(loadBootCardMsgId(path, 'other:')).toBeNull()
+  })
+
+  it('rejects non-positive / non-finite ids on save and load', () => {
+    saveBootCardMsgId(path, 'dm:', 0)
+    saveBootCardMsgId(path, 'dm:', -5)
+    saveBootCardMsgId(path, 'dm:', Number.NaN)
+    expect(loadBootCardMsgId(path, 'dm:')).toBeNull()
+  })
+
+  it('treats a corrupt file as empty (falls back to fresh send)', () => {
+    writeFileSync(path, 'not json{', 'utf8')
+    expect(loadBootCardMsgId(path, 'dm:')).toBeNull()
+    // And a subsequent save still works (overwrites the garbage).
+    saveBootCardMsgId(path, 'dm:', 7)
+    expect(loadBootCardMsgId(path, 'dm:')).toBe(7)
+  })
+
+  it('does not rewrite the file when the id is unchanged (idempotent)', () => {
+    saveBootCardMsgId(path, 'dm:', 42)
+    expect(existsSync(path)).toBe(true)
+    // Saving the same value again is a no-op; the value is still readable.
+    saveBootCardMsgId(path, 'dm:', 42)
+    expect(loadBootCardMsgId(path, 'dm:')).toBe(42)
+  })
+})

package/telegram-plugin/tests/inbound-delivery-confirm.test.ts

@@ -4,6 +4,7 @@ import {
   ackDelivery,
   createDeliveryQueue,
   forgetDelivery,
+  isTrackableResumeSynthetic,
   shouldTrackDelivery,
   sweep,
   trackDelivery,
@@ -178,3 +179,63 @@ describe('shouldTrackDelivery — only fresh-turn messages are tracked', () => {
     expect(shouldTrackDelivery({ isSteering: false, isInterrupt: false, effectiveText: 'draft the email' })).toBe(true)
   })
 })
+
+// The boot-resume synthetic is the one synthetic ENROLLED for re-delivery (so a
+// restart can't silently drop the "pick up your interrupted work" wake into a
+// not-ready session). It is safe ONLY because it carries a round-trippable
+// message_id that its own enqueue acks — without that it would re-deliver
+// forever (the storm the hasSource exclusion otherwise prevents).
+describe('isTrackableResumeSynthetic — resume carve-in to the deliver-until-acked queue', () => {
+  it('tracks a resume_interrupted synthetic that carries a message_id', () => {
+    expect(isTrackableResumeSynthetic({ source: 'resume_interrupted', message_id: '1700000000000' })).toBe(true)
+  })
+  it('does NOT track a resume_interrupted WITHOUT a message_id (would never ack → storm)', () => {
+    expect(isTrackableResumeSynthetic({ source: 'resume_interrupted' })).toBe(false)
+    expect(isTrackableResumeSynthetic({ source: 'resume_interrupted', message_id: '' })).toBe(false)
+  })
+  it('does NOT track the watchdog report (untracked by design) even though it carries chat_id', () => {
+    expect(isTrackableResumeSynthetic({ source: 'resume_watchdog_timeout', chat_id: '123' })).toBe(false)
+  })
+  it('does NOT track other synthetics (cron / vault / handback) even if they somehow had a message_id', () => {
+    expect(isTrackableResumeSynthetic({ source: 'cron', message_id: '1' })).toBe(false)
+    expect(isTrackableResumeSynthetic({ source: 'subagent_handback', message_id: '1' })).toBe(false)
+    expect(isTrackableResumeSynthetic({ source: 'vault_grant_approved', message_id: '1' })).toBe(false)
+  })
+  it('does NOT track a real (no source) inbound here — that path is shouldTrackDelivery', () => {
+    expect(isTrackableResumeSynthetic({ chat_id: '1', message_id: '2' })).toBe(false)
+    expect(isTrackableResumeSynthetic(undefined)).toBe(false)
+  })
+})
+
+// End-to-end queue contract for the resume synthetic: tracked by its fabricated
+// id, acked by its OWN enqueue (which round-trips the same id), and — crucially
+// — it can never re-deliver forever (the storm the original deferral feared).
+describe('resume synthetic: tracked, acked by own enqueue, never storms', () => {
+  const RESUME_ID = '1700000000000' // String(ts), the fabricated message_id
+  it('acks when its own enqueue arrives with the matching id (no storm)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'resume…' }, 1_000, RESUME_ID)
+    // The resume turn starts → enqueue fires carrying the round-tripped id.
+    expect(ackDelivery(q, 'chat:_', RESUME_ID)).toBe(true)
+    expect(q.pending.size).toBe(0)
+    // Never re-delivered after the ack — bounded, not a forever loop.
+    expect(sweep(q, 1_000 + 999_999, TIMEOUT)).toHaveLength(0)
+  })
+  it('strands then re-delivers until acked (rescues a drop into a not-ready session)', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'resume…' }, 1_000, RESUME_ID)
+    // Dropped into a not-ready session: no enqueue within the timeout → re-deliver.
+    const stranded = sweep(q, 1_000 + TIMEOUT + 1, TIMEOUT)
+    expect(stranded).toHaveLength(1)
+    expect(stranded[0]!.messageId).toBe(RESUME_ID)
+    // Once claude is ready, its enqueue acks it and the loop stops.
+    expect(ackDelivery(q, 'chat:_', RESUME_ID)).toBe(true)
+    expect(sweep(q, 1_000 + TIMEOUT * 10, TIMEOUT)).toHaveLength(0)
+  })
+  it('a DIFFERENT enqueue id (e.g. a racing real user msg) does NOT false-ack the resume', () => {
+    const q = fresh()
+    trackDelivery(q, 'chat:_', { text: 'resume…' }, 1_000, RESUME_ID)
+    expect(ackDelivery(q, 'chat:_', '999')).toBe(false) // not our id
+    expect(q.pending.size).toBe(1) // still pending, will re-deliver
+  })
+})