switchroom 0.14.47 → 0.14.49

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'
@@ -1064,7 +1064,19 @@ try {
   const pending = findLatestTurnIfInterrupted(turnsDb)
   const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
   if (pending != null && selfAgent) {
-    const kind = selectResumeBuilder(pending.ended_via)
+    // 3h staleness failsafe (operator spec, 2026-06-03): never AUTO-resume
+    // interrupted work older than RESUME_MAX_AGE_MS — selectResumeBuilder
+    // downgrades a stale 'resume' to the passive 'report' so the user is told
+    // ("I was working on X ~Nh ago") but nothing replays unprompted. Env
+    // override SWITCHROOM_RESUME_MAX_AGE_MS (ms); set very high to disable.
+    const RESUME_MAX_AGE_MS = (() => {
+      const v = Number(process.env.SWITCHROOM_RESUME_MAX_AGE_MS)
+      return Number.isFinite(v) && v > 0 ? v : 10_800_000 // 3h
+    })()
+    const kind = selectResumeBuilder(pending.ended_via, {
+      ageMs: Math.max(0, Date.now() - pending.started_at),
+      maxAgeMs: RESUME_MAX_AGE_MS,
+    })
     if (kind === 'resume') {
       bootResumeInbound = { agent: selfAgent, msg: buildResumeInterruptedInbound({ turn: pending }) }
     } else if (kind === 'report') {
@@ -1801,6 +1813,7 @@ function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
           return d
         },
         inboundSpool,
+        trackRedeliveredInbound,
       )
       if (fr.redelivered > 0) {
         process.stderr.write(
@@ -1896,6 +1909,7 @@ function releaseTurnBufferGate(key: string): void {
           return d
         },
         inboundSpool,
+        trackRedeliveredInbound,
       )
       if (fr.redelivered > 0) {
         process.stderr.write(
@@ -2589,6 +2603,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'
+      }
+    },
   }
 }
 
@@ -4134,6 +4168,7 @@ silencePoke.startTimer({
         return d
       },
       inboundSpool,
+      trackRedeliveredInbound,
     )
     process.stderr.write(
       `telegram gateway: silence-poke framework-fallback ended wedged turn ` +
@@ -4163,6 +4198,45 @@ const _deliveryMachineTick = setInterval(() => {
 }, DELIVERY_MACHINE_TICK_MS)
 _deliveryMachineTick.unref?.()
 
+// Enrol a buffer-redelivered inbound in the deliver-until-acked queue so the
+// existing sweep re-delivers it until claude's `enqueue` ack lands. Wired into
+// EVERY redelivery path (bridgeUp drain, silence-poke fallback, flap/reply-gate
+// flushes) — `send` returning true only means the bytes reached the bridge, NOT
+// that claude consumed them. Right after a restart (esp. a slow MCP boot) the
+// inject can hit a not-ready session and be silently dropped, and nothing
+// retried it: the clerk 2026-06-03 lost-message incident. Mirrors the
+// live-delivery tracking at the handleInbound site (chatKey + messageId), so
+// DMs and supergroup forum topics are handled identically. Only real user
+// inbounds are tracked — shouldTrackDelivery excludes steer/interrupt/
+// synthetic-source/empty, which never produce an `enqueue` and would otherwise
+// re-deliver forever.
+function trackRedeliveredInbound(merged: InboundMessage): void {
+  if (!DELIVERY_CONFIRM_ENABLED) return
+  if (
+    !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,
+    })
+  ) {
+    return
+  }
+  const key = chatKey(merged.chatId, merged.threadId != null ? Number(merged.threadId) : null)
+  trackDelivery(
+    deliveryQueue,
+    key,
+    merged,
+    Date.now(),
+    merged.messageId != null ? String(merged.messageId) : null,
+  )
+}
+
 // Re-deliver stranded inbounds until claude acks (the marko drop-wedge).
 // Every few seconds, re-send any inbound that was handed to claude but never
 // acked by an `enqueue` — it stranded unsubmitted in the composer. Re-clear
@@ -4400,6 +4474,11 @@ const ipcServer: IpcServer = createIpcServer({
           inboundSpool: inboundSpool ?? null,
           pendingPermissionBuffer,
           client,
+          // Enrol each drained user inbound in the deliver-until-acked queue
+          // so the 5s sweep re-delivers until claude's `enqueue` ack lands —
+          // a socket-write into a still-booting session is NOT consumption
+          // (clerk lost-message incident, 2026-06-03).
+          onUserInboundDelivered: trackRedeliveredInbound,
         })
       } else {
         // Kill-switch fallback: imperative drain (parity with pre-cutover
@@ -4410,6 +4489,10 @@ const ipcServer: IpcServer = createIpcServer({
           try {
             client.send(msg)
             inboundSpool?.ack(msg)
+            // Same enrol as the cutover drain path: a socket-write success is
+            // not proof claude consumed it — enrol so the sweep re-delivers
+            // until `enqueue` (clerk lost-message incident, 2026-06-03).
+            trackRedeliveredInbound(msg)
           } catch (err) {
             process.stderr.write(
               `telegram gateway: pending-inbound drain failed agent=${client.agentName} ` +
@@ -4515,6 +4598,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
@@ -5318,6 +5402,7 @@ if (!STATIC) {
         return d
       },
       inboundSpool,
+      trackRedeliveredInbound,
     )
     if (r != null && r.redelivered > 0) {
       process.stderr.write(
@@ -18405,6 +18490,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-machine-dispatch.ts

@@ -45,6 +45,15 @@ export interface DispatchCtx {
   readonly client?: IpcClient
   /** Optional log sink — default stderr. Test hook. */
   readonly log?: (line: string) => void
+  /**
+   * Optional: enrol a drained+redelivered inbound in the deliver-until-acked
+   * queue. The bridgeUp drain's socket-write "success" is NOT proof claude
+   * consumed the message — right after a restart (esp. with a slow MCP boot)
+   * the inject can hit a not-ready session and be dropped. Wiring this makes
+   * the existing 5s sweep re-deliver until claude's `enqueue` ack lands.
+   * (clerk lost-message incident, 2026-06-03.)
+   */
+  readonly onUserInboundDelivered?: (merged: InboundMessage) => void
 }
 
 const enabled = process.env.SWITCHROOM_DELIVERY_MACHINE_CUTOVER !== '0'
@@ -103,6 +112,9 @@ function dispatchOne(effect: Effect, ctx: DispatchCtx): void {
         ctx.selfAgent,
         send,
         ctx.inboundSpool ?? undefined,
+        ctx.onUserInboundDelivered
+          ? (merged) => ctx.onUserInboundDelivered!(merged)
+          : undefined,
       )
       if (result.drained > 0) {
         log(

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -87,6 +87,14 @@ export function redeliverBufferedInbound(
   agent: string,
   send: (msg: InboundMessage) => boolean,
   spool?: InboundSpool,
+  // Called once per merged group on CONFIRMED delivery (after spool.ack).
+  // The caller uses it to enrol the redelivered inbound in the
+  // deliver-until-acked queue (`trackDelivery`) so it is re-sent until
+  // claude's `enqueue` ack lands — closing the restart boot-race where a
+  // socket-write "succeeds" into a not-ready session and the message is
+  // silently dropped (clerk 2026-06-03). `send` returning true only means
+  // the bytes reached the bridge, NOT that claude consumed them.
+  onDelivered?: (merged: InboundMessage, originals: InboundMessage[]) => void,
 ): { drained: number; redelivered: number; rebuffered: number } {
   const pending = buffer.drain(agent)
   let redelivered = 0
@@ -110,6 +118,10 @@ export function redeliverBufferedInbound(
       // originals are, so we ack by original identity.
       for (const o of originals) spool?.ack(o)
       redelivered += originals.length
+      // Enrol in the deliver-until-acked queue (caller's hook). A bare
+      // socket-write success is NOT proof claude consumed it; the queue's
+      // sweep re-delivers until the `enqueue` ack lands.
+      onDelivered?.(merged, originals)
     } else {
       // Re-buffer the originals (not the merged synthetic) so the spool
       // identity is preserved and the next drain re-merges them losslessly.
@@ -258,11 +270,15 @@ export function idleDrainTick(
   isBridgeAlive: () => boolean,
   send: (msg: InboundMessage) => boolean,
   spool?: InboundSpool,
+  // Forwarded to redeliverBufferedInbound so the post-flap-settle drain also
+  // enrols redelivered inbounds in the deliver-until-acked queue (parity with
+  // the bridgeUp drain — clerk lost-message incident, 2026-06-03).
+  onDelivered?: (merged: InboundMessage, originals: InboundMessage[]) => void,
 ): { drained: number; redelivered: number; rebuffered: number } | null {
   if (!agent) return null
   if (buffer.depth(agent) === 0) return null
   if (!isBridgeAlive()) return null
-  return redeliverBufferedInbound(buffer, agent, send, spool)
+  return redeliverBufferedInbound(buffer, agent, send, spool, onDelivered)
 }
 
 export function createPendingInboundBuffer(

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

@@ -172,9 +172,25 @@ export function buildResumeWatchdogReportInbound(
  */
 export function selectResumeBuilder(
   endedVia: TurnEndedVia | null,
+  // 3h staleness failsafe (operator spec, 2026-06-03): when the interrupted
+  // turn is older than `maxAgeMs`, an AUTO-resume is downgraded to the passive
+  // `report` — silently re-injecting hours-old work could act on long-stale
+  // context (a tax figure, a "send it" the user has moved on from). Pass both
+  // to enable; omit (default) keeps the legacy blanket-resume behaviour.
+  opts?: { ageMs?: number; maxAgeMs?: number },
 ): 'resume' | 'report' | null {
-  if (endedVia === 'timeout') return 'report'
-  if (endedVia === 'restart' || endedVia === 'sigterm' || endedVia === 'unknown') return 'resume'
-  if (endedVia == null) return 'resume' // still-open at boot = killed mid-flight
-  return null
+  let kind: 'resume' | 'report' | null
+  if (endedVia === 'timeout') kind = 'report'
+  else if (endedVia === 'restart' || endedVia === 'sigterm' || endedVia === 'unknown') kind = 'resume'
+  else if (endedVia == null) kind = 'resume' // still-open at boot = killed mid-flight
+  else kind = null
+  if (
+    kind === 'resume' &&
+    opts?.ageMs != null &&
+    opts?.maxAgeMs != null &&
+    opts.ageMs > opts.maxAgeMs
+  ) {
+    return 'report' // too old to safely auto-resume — passive notice only
+  }
+  return kind
 }

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)
+  })
+})