@llblab/pi-telegram 0.24.6 → 0.24.7

package/lib/bus-leader.ts

@@ -112,7 +112,10 @@ export interface TelegramBusFollowerTargetProvisionerDeps {
 export interface TelegramBusFollowerDisconnectHandlerDeps {
   topicTargetStore: Pick<
     Threads.TelegramTopicTargetStore,
-    "markOfflineByInstanceId" | "persist"
+    | "markStaleByTarget"
+    | "persist"
+    | "upsertPendingCleanup"
+    | "removePendingCleanup"
   >;
   callApi: <TResponse>(
     method: string,
@@ -155,6 +158,7 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
     TelegramBusLeaderRuntimeDeps<TContext>,
     | "callApi"
     | "onFollowerDisconnected"
+    | "onFollowerConfirmedDead"
     | "provisionFollowerTarget"
     | "provisionLeaderTarget"
     | "recordRuntimeEvent"
@@ -212,6 +216,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
     onFollowerDisconnected: createTelegramBusFollowerDisconnectHandler({
       ...provisionerPorts,
     }),
+    onFollowerConfirmedDead: createTelegramBusFollowerConfirmedDeadHandler({
+      ...provisionerPorts,
+    }),
     provisionFollowerTarget: createTelegramBusFollowerTargetProvisioner({
       ...provisionerPorts,
     }),
@@ -259,9 +266,14 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   getNowMs?: () => number;
   followerPruneIntervalMs?: number;
   followerStaleAfterMs?: number;
+  isFollowerProcessAlive?: (pid: number) => boolean;
+  shouldCleanupConfirmedDeadFollower?: () => Promise<boolean> | boolean;
   onFollowerDisconnected?: (
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
+  onFollowerConfirmedDead?: (
+    follower: TelegramBusFollowerView,
+  ) => Promise<void> | void;
   recordRuntimeEvent?: (
     category: string,
     error: unknown,
@@ -678,8 +690,9 @@ export function createTelegramBusFollowerTargetProvisioner(
   };
 }
 
-export function createTelegramBusFollowerDisconnectHandler(
+function createTelegramBusFollowerCleanupHandler(
   deps: TelegramBusFollowerDisconnectHandlerDeps,
+  trigger: "graceful-disconnect" | "confirmed-dead",
 ): (follower: TelegramBusFollowerView) => Promise<void> {
   return async (follower) => {
     const target = follower.target;
@@ -688,14 +701,33 @@ export function createTelegramBusFollowerDisconnectHandler(
     if (deps.getCurrentLeaderEpoch && leaderEpoch === undefined) {
       throw new Error("Follower disconnect cleanup requires leader ownership.");
     }
+    if (!follower.registrationGeneration) {
+      throw new Error(
+        "Follower disconnect cleanup requires an exact registration generation.",
+      );
+    }
+    const intent: ThreadReconciler.TelegramThreadCleanupIntent = {
+      id: `cleanup:${follower.instanceId}:${follower.registrationGeneration}:${target.chatId}:${target.threadId}`,
+      owner: "manual-follower",
+      instanceId: follower.instanceId,
+      runtimeGeneration: follower.registrationGeneration,
+      ...(follower.profileKey ? { profileKey: follower.profileKey } : {}),
+      target: { chatId: target.chatId, threadId: target.threadId },
+      requestedAtMs: (deps.getNowMs ?? Date.now)(),
+    };
+    deps.topicTargetStore.upsertPendingCleanup(intent);
+    await deps.topicTargetStore.persist();
     const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
-      ThreadReconciler.planDisconnectedInstanceThreadCleanup({
-        target: { chatId: target.chatId, threadId: target.threadId },
-        instanceId: follower.instanceId,
-        leaderEpoch,
+      ThreadReconciler.planThreadReconciliation({
+        nowMs: (deps.getNowMs ?? Date.now)(),
+        currentLeaderEpoch: leaderEpoch,
+        records: [],
+        pendingCleanups: [intent],
       }),
       {
         callApi: deps.callApi,
+        markStaleByTarget: deps.topicTargetStore.markStaleByTarget,
+        removeCleanupIntentById: deps.topicTargetStore.removePendingCleanup,
         persist: deps.topicTargetStore.persist,
         getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
         recordRuntimeEvent: deps.recordRuntimeEvent,
@@ -703,7 +735,7 @@ export function createTelegramBusFollowerDisconnectHandler(
     );
     if (cleanup.incompleteActions?.length) {
       throw new Error(
-        "Telegram follower thread deletion was not confirmed; reconnect the leader and retry /telegram-disconnect.",
+        "Telegram follower thread deletion was not confirmed; reconnect the leader to retry cleanup.",
       );
     }
     if (
@@ -712,24 +744,45 @@ export function createTelegramBusFollowerDisconnectHandler(
     ) {
       throw new Error("Follower disconnect cleanup lost leader ownership.");
     }
-    const changed =
-      deps.topicTargetStore.markOfflineByInstanceId(follower.instanceId) > 0;
-    if (changed) await deps.topicTargetStore.persist();
     deps.setSyncState(
       Sync.markTelegramSyncSliceFresh(deps.getSyncState(), "target-bindings", {
         nowMs: (deps.getNowMs ?? Date.now)(),
-        action: "manual-follower-disconnect",
+        action:
+          trigger === "confirmed-dead"
+            ? "manual-follower-confirmed-dead"
+            : "manual-follower-disconnect",
       }),
     );
-    deps.recordRuntimeEvent("bus", "Telegram bus follower disconnected", {
-      phase: "follower-disconnect",
-      instanceId: follower.instanceId,
-      chatId: target.chatId,
-      threadId: target.threadId,
-    });
+    deps.recordRuntimeEvent(
+      "bus",
+      trigger === "confirmed-dead"
+        ? "Confirmed-dead Telegram bus follower thread cleaned up"
+        : "Telegram bus follower disconnected",
+      {
+        phase:
+          trigger === "confirmed-dead"
+            ? "follower-confirmed-dead-cleanup"
+            : "follower-disconnect",
+        instanceId: follower.instanceId,
+        chatId: target.chatId,
+        threadId: target.threadId,
+      },
+    );
   };
 }
 
+export function createTelegramBusFollowerDisconnectHandler(
+  deps: TelegramBusFollowerDisconnectHandlerDeps,
+): (follower: TelegramBusFollowerView) => Promise<void> {
+  return createTelegramBusFollowerCleanupHandler(deps, "graceful-disconnect");
+}
+
+export function createTelegramBusFollowerConfirmedDeadHandler(
+  deps: TelegramBusFollowerDisconnectHandlerDeps,
+): (follower: TelegramBusFollowerView) => Promise<void> {
+  return createTelegramBusFollowerCleanupHandler(deps, "confirmed-dead");
+}
+
 export function createTelegramBusLeaderTargetProvisioner<TContext>(
   deps: TelegramBusLeaderTargetProvisionerDeps<TContext>,
 ): (ctx: TContext) => Promise<void> {
@@ -741,6 +794,23 @@ export function createTelegramBusLeaderTargetProvisioner<TContext>(
         "Telegram leader target provisioning requires ownership.",
       );
     }
+    await deps.topicTargetStore.load();
+    const pendingCleanupPlan = ThreadReconciler.planThreadReconciliation({
+      nowMs: getNowMs(),
+      currentLeaderEpoch: leaderEpoch,
+      previousState: deps.getThreadReconciliationMachineState?.(),
+      records: deps.topicTargetStore.list(),
+      pendingCleanups: deps.topicTargetStore.listPendingCleanups(),
+    });
+    deps.recordThreadReconciliationPlan?.(pendingCleanupPlan);
+    await ThreadReconciler.applyThreadReconciliationPlan(pendingCleanupPlan, {
+      callApi: deps.callApi,
+      markStaleByTarget: deps.topicTargetStore.markStaleByTarget,
+      removeCleanupIntentById: deps.topicTargetStore.removePendingCleanup,
+      persist: deps.topicTargetStore.persist,
+      getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
+      recordRuntimeEvent: deps.recordRuntimeEvent,
+    });
     deps.onProvisioningStart?.();
     let ownTarget: Threads.TelegramOwnTopicProvisionResult | undefined;
     try {
@@ -858,6 +928,33 @@ export function createTelegramBusLeaderApiProxy(
   };
 }
 
+type TelegramBusFollowerMutationRunner = <T>(
+  follower: { instanceId: string; profileKey?: string },
+  operation: () => Promise<T>,
+) => Promise<T>;
+
+function createTelegramBusFollowerMutationRunner(): TelegramBusFollowerMutationRunner {
+  const tails = new Map<string, Promise<void>>();
+  return async (follower, operation) => {
+    const key = follower.profileKey
+      ? `profile:${follower.profileKey}`
+      : `instance:${follower.instanceId}`;
+    const previous = tails.get(key);
+    let release!: () => void;
+    const current = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    tails.set(key, current);
+    if (previous) await previous;
+    try {
+      return await operation();
+    } finally {
+      release();
+      if (tails.get(key) === current) tails.delete(key);
+    }
+  };
+}
+
 export function createTelegramBusLeaderEnvelopeHandler(deps: {
   followerRegistry: TelegramBusFollowerRegistry;
   authSecret?: string;
@@ -883,38 +980,13 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
   getCurrentLeaderEpoch?: () => number | string | undefined;
+  runFollowerMutation?: TelegramBusFollowerMutationRunner;
 }): (
   envelope: TelegramBusEnvelope,
 ) => Promise<TelegramBusEnvelope> | TelegramBusEnvelope {
   const getNowMs = deps.getNowMs ?? Date.now;
-  const followerMutationTails = new Map<string, Promise<void>>();
-  const getFollowerMutationKey = (follower: {
-    instanceId: string;
-    profileKey?: string;
-  }): string =>
-    follower.profileKey
-      ? `profile:${follower.profileKey}`
-      : `instance:${follower.instanceId}`;
-  const runFollowerMutation = async <T>(
-    mutationKey: string,
-    operation: () => Promise<T>,
-  ): Promise<T> => {
-    const previous = followerMutationTails.get(mutationKey);
-    let release!: () => void;
-    const current = new Promise<void>((resolve) => {
-      release = resolve;
-    });
-    followerMutationTails.set(mutationKey, current);
-    if (previous) await previous;
-    try {
-      return await operation();
-    } finally {
-      release();
-      if (followerMutationTails.get(mutationKey) === current) {
-        followerMutationTails.delete(mutationKey);
-      }
-    }
-  };
+  const runFollowerMutation =
+    deps.runFollowerMutation ?? createTelegramBusFollowerMutationRunner();
   const forwardToFollower = async (
     envelope: Extract<
       TelegramBusEnvelope,
@@ -977,9 +1049,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
     }
     switch (envelope.kind) {
       case "follower.register": {
-        return runFollowerMutation(
-          getFollowerMutationKey(envelope.registration),
-          async () => {
+        return runFollowerMutation(envelope.registration, async () => {
           try {
             if (!envelope.registration.registrationGeneration) {
               throw new Error(
@@ -1041,9 +1111,7 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
       case "follower.disconnect": {
         const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
         return runFollowerMutation(
-          getFollowerMutationKey(
-            registeredFollower ?? { instanceId: envelope.instanceId },
-          ),
+          registeredFollower ?? { instanceId: envelope.instanceId },
           async () => {
           const follower = deps.followerRegistry.get(envelope.instanceId);
           if (!follower) {
@@ -1368,6 +1436,7 @@ export function createTelegramBusLeaderRuntime<TContext>(
   const getNowMs = deps.getNowMs ?? Date.now;
   const followerPruneIntervalMs = deps.followerPruneIntervalMs ?? 1000;
   const followerStaleAfterMs = deps.followerStaleAfterMs ?? 5000;
+  const runFollowerMutation = createTelegramBusFollowerMutationRunner();
   let pruneInterval: ReturnType<typeof setInterval> | undefined;
   const stopPruning = () => {
     if (!pruneInterval) return;
@@ -1387,14 +1456,87 @@ export function createTelegramBusLeaderRuntime<TContext>(
       followerStaleAfterMs,
     );
     for (const follower of removed) {
-      deps.recordRuntimeEvent?.(
-        "bus",
-        "Telegram bus follower heartbeat stale; preserving thread binding",
-        {
-          phase: "follower-pruned",
+      let processConfirmedDead = false;
+      if (follower.pid !== undefined && deps.isFollowerProcessAlive) {
+        try {
+          processConfirmedDead = !deps.isFollowerProcessAlive(follower.pid);
+        } catch (error) {
+          deps.recordRuntimeEvent?.("bus", error, {
+            phase: "follower-process-liveness",
+            instanceId: follower.instanceId,
+            pid: follower.pid,
+          });
+        }
+      }
+      if (!processConfirmedDead) {
+        deps.recordRuntimeEvent?.(
+          "bus",
+          "Telegram bus follower heartbeat stale; preserving thread binding",
+          {
+            phase: "follower-pruned",
+            instanceId: follower.instanceId,
+            processLiveness:
+              follower.pid === undefined || !deps.isFollowerProcessAlive
+                ? "unknown"
+                : "alive-or-unknown",
+          },
+        );
+        continue;
+      }
+      let cleanupEnabled = false;
+      try {
+        cleanupEnabled =
+          (await deps.shouldCleanupConfirmedDeadFollower?.()) ?? false;
+      } catch (error) {
+        deps.recordRuntimeEvent?.("bus", error, {
+          phase: "follower-confirmed-dead-cleanup-policy",
           instanceId: follower.instanceId,
-        },
-      );
+          pid: follower.pid,
+        });
+      }
+      if (!cleanupEnabled || !deps.onFollowerConfirmedDead) {
+        deps.recordRuntimeEvent?.(
+          "bus",
+          "Telegram bus follower process confirmed dead; preserving thread binding",
+          {
+            phase: "follower-confirmed-dead-preserved",
+            instanceId: follower.instanceId,
+            pid: follower.pid,
+            cleanupEnabled,
+          },
+        );
+        continue;
+      }
+      try {
+        await runFollowerMutation(follower, async () => {
+          const replacement = deps.followerRegistry.list().find((candidate) =>
+            follower.profileKey
+              ? candidate.profileKey === follower.profileKey
+              : candidate.instanceId === follower.instanceId,
+          );
+          if (replacement) {
+            deps.recordRuntimeEvent?.(
+              "bus",
+              "Telegram bus follower replaced before confirmed-dead cleanup; preserving thread binding",
+              {
+                phase: "follower-confirmed-dead-replaced",
+                instanceId: follower.instanceId,
+                replacementInstanceId: replacement.instanceId,
+              },
+            );
+            return;
+          }
+          await deps.onFollowerConfirmedDead!(follower);
+        });
+      } catch (error) {
+        deps.recordRuntimeEvent?.("bus", error, {
+          phase: "follower-confirmed-dead-cleanup",
+          instanceId: follower.instanceId,
+          pid: follower.pid,
+          chatId: follower.target?.chatId,
+          threadId: follower.target?.threadId,
+        });
+      }
     }
   };
   const startPruning = () => {
@@ -1423,14 +1565,17 @@ export function createTelegramBusLeaderRuntime<TContext>(
       provisionFollowerTarget: deps.provisionFollowerTarget,
       onFollowerDisconnected: deps.onFollowerDisconnected,
       getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
+      runFollowerMutation,
     }),
   });
   return {
     startPolling: async (ctx) => {
+      // Replay durable cleanup before publishing the follower endpoint so a
+      // replacement registration cannot reclaim a target while it is deleted.
+      await deps.provisionLeaderTarget?.(ctx);
       await localServer.start();
       startPruning();
       try {
-        await deps.provisionLeaderTarget?.(ctx);
         await deps.startPolling(ctx);
       } catch (error) {
         stopPruning();

package/lib/bus.ts

@@ -218,6 +218,7 @@ export function isTelegramFollowerApiCallAllowed(input: {
     "deleteForumTopic",
     "deleteMessage",
     "editForumTopic",
+    "editMessageReplyMarkup",
     "editMessageText",
     "sendChatAction",
     "sendMessage",
@@ -296,7 +297,11 @@ export function isTelegramFollowerApiCallAllowed(input: {
       const body = input.args[1] as Record<string, unknown>;
       return body.message_thread_id === undefined && isTargetChatScoped(body);
     }
-    if (apiMethod === "deleteMessage" || apiMethod === "editMessageText") {
+    if (
+      apiMethod === "deleteMessage" ||
+      apiMethod === "editMessageReplyMarkup" ||
+      apiMethod === "editMessageText"
+    ) {
       if (!isTargetMessageScoped(input.args[1])) return false;
       const body = input.args[1] as Record<string, unknown>;
       const messageId =

package/lib/config.ts

@@ -885,7 +885,7 @@ export function createTelegramAutomaticThreadCleanupResolver(
     await loadLatestTelegramConfig(configStore);
     if (configStore.didLastLoadRecoverInvalidConfig?.()) {
       throw new Error(
-        "Automatic thread cleanup setting is unavailable after invalid Telegram config recovery.",
+        "Thread cleanup setting is unavailable after invalid Telegram config recovery.",
       );
     }
     return createTelegramAutomaticThreadCleanupChecker(configStore)();

package/lib/keyboard.ts

@@ -7,6 +7,7 @@
 export interface TelegramInlineKeyboardButton {
   text: string;
   callback_data: string;
+  style?: "danger" | "success" | "primary";
 }
 
 export interface TelegramInlineKeyboardMarkup {

package/lib/menu-settings.ts

@@ -133,7 +133,7 @@ export interface TelegramSettingsMenuRuntimeDeps<
 
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
-  "<b>🧹 Automatic thread cleanup:</b>";
+  "<b>🧹 Thread cleanup:</b>";
 export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
 export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
 export const ASSISTANT_RENDERING_SETTINGS_TITLE =
@@ -172,7 +172,7 @@ export function buildAutomaticThreadCleanupSettingsText(
     "Delete this Pi instance's Telegram tab when Pi quits normally.",
     "",
     "<code>-</code> <code>on</code> (default): delete the bound thread and release Telegram authority on graceful quit.",
-    "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual /telegram-disconnect still confirms and deletes it.",
+    "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual <code>/telegram-disconnect</code> still confirms and deletes it.",
   ].join("\n");
 }
 
@@ -290,7 +290,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
   rows.push(
     [
       {
-        text: `🧹 Auto thread cleanup: ${automaticThreadCleanupEnabled ? "on" : "off"}`,
+        text: `🧹 Thread cleanup: ${automaticThreadCleanupEnabled ? "on" : "off"}`,
         callback_data: "settings:open:automatic-thread-cleanup",
       },
     ],
@@ -669,7 +669,7 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await updateAutomaticThreadCleanupSettingsMessage(deps);
     await deps.answerCallbackQuery(
       callbackQueryId,
-      `Automatic thread cleanup ${enabled ? "enabled" : "disabled"}`,
+      `Thread cleanup ${enabled ? "enabled" : "disabled"}`,
     );
     return true;
   }
@@ -709,8 +709,7 @@ export function createTelegramSettingsMenuRuntime<
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
-          isAutomaticThreadCleanupEnabled:
-            deps.isAutomaticThreadCleanupEnabled,
+          isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
           sendSettingsMenu: (state, text, replyMarkup) =>
             deps.sendInteractiveMessage(
               state.chatId,
@@ -733,8 +732,7 @@ export function createTelegramSettingsMenuRuntime<
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
-          isAutomaticThreadCleanupEnabled:
-            deps.isAutomaticThreadCleanupEnabled,
+          isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
           updateSettingsMessage: (text, replyMarkup) =>
             deps.editInteractiveMessage(
               state.chatId,
@@ -777,15 +775,13 @@ export function createTelegramSettingsMenuRuntime<
         getVoiceReplyMode: deps.getVoiceReplyMode,
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
-        isAutomaticThreadCleanupEnabled:
-          deps.isAutomaticThreadCleanupEnabled,
+        isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
         setProactivePushEnabled: deps.setProactivePushEnabled,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setVoiceReplyMode: deps.setVoiceReplyMode,
         setTimeInjectionMode: deps.setTimeInjectionMode,
-        setAutomaticThreadCleanupEnabled:
-          deps.setAutomaticThreadCleanupEnabled,
+        setAutomaticThreadCleanupEnabled: deps.setAutomaticThreadCleanupEnabled,
         updateSettingsMessage: (text, replyMarkup) =>
           deps.editInteractiveMessage(
             state.chatId,

package/lib/outbound-buttons.ts

@@ -51,6 +51,7 @@ export interface TelegramButtonCallbackQuery {
     message_id?: number;
     message_thread_id?: number;
     chat?: { id?: number };
+    reply_markup?: TelegramOutboundButtonMarkup;
   };
 }
 
@@ -66,7 +67,12 @@ export interface TelegramButtonCallbackHandlerDeps<TContext = unknown> {
     query: TelegramButtonCallbackQuery,
     action: TelegramOutboundButtonAction,
     ctx: TContext,
-  ) => void;
+  ) => boolean | void;
+  editMessageReplyMarkup?: (
+    chatId: number,
+    messageId: number,
+    replyMarkup: TelegramOutboundButtonMarkup,
+  ) => Promise<void>;
 }
 
 function nowMs(): number {
@@ -203,6 +209,21 @@ export function createTelegramButtonPromptTurn(options: {
   };
 }
 
+export function markTelegramButtonSelected(
+  replyMarkup: TelegramOutboundButtonMarkup,
+  callbackData: string,
+): TelegramOutboundButtonMarkup | undefined {
+  let matched = false;
+  const inlineKeyboard = replyMarkup.inline_keyboard.map((row) =>
+    row.map((button) => {
+      if (button.callback_data !== callbackData) return { ...button };
+      matched = true;
+      return { ...button, style: "success" as const };
+    }),
+  );
+  return matched ? { inline_keyboard: inlineKeyboard } : undefined;
+}
+
 export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
   query: TelegramButtonCallbackQuery,
   ctx: TContext,
@@ -225,7 +246,18 @@ export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
     return true;
   }
 
-  deps.enqueueButtonPrompt(query, action, ctx);
+  const enqueued = deps.enqueueButtonPrompt(query, action, ctx);
+  if (enqueued === false) {
+    await deps.answerCallbackQuery(query.id, "Already queued.");
+    return true;
+  }
+  const selectedMarkup =
+    query.data && query.message?.reply_markup
+      ? markTelegramButtonSelected(query.message.reply_markup, query.data)
+      : undefined;
+  if (selectedMarkup && deps.editMessageReplyMarkup) {
+    await deps.editMessageReplyMarkup(chatId, messageId, selectedMarkup);
+  }
   await deps.answerCallbackQuery(query.id, "Queued.");
   return true;
 }

package/lib/outbound.ts

@@ -817,6 +817,7 @@ export {
   createTelegramButtonPromptTurn,
   createTelegramButtonReplyPlanner,
   handleTelegramButtonCallbackQuery,
+  markTelegramButtonSelected,
   planTelegramButtonReply,
   type TelegramButtonActionStore,
   type TelegramButtonCallbackHandlerDeps,

package/lib/routing.ts

@@ -608,6 +608,11 @@ export interface TelegramInboundRouteRuntimeDeps<
     mode: "markdown" | "html" | "plain",
     replyMarkup: Menu.TelegramReplyMarkup,
   ) => Promise<void>;
+  editMessageReplyMarkup?: (
+    chatId: number,
+    messageId: number,
+    replyMarkup: OutboundHandlers.TelegramOutboundButtonMarkup,
+  ) => Promise<void>;
   sendInteractiveMessage?: (
     chatId: number,
     text: string,
@@ -1448,11 +1453,28 @@ export function createTelegramInboundRouteRuntime<
         {
           resolveAction: deps.buttonActionStore.resolve,
           answerCallbackQuery: deps.answerCallbackQuery,
+          editMessageReplyMarkup: deps.editMessageReplyMarkup
+            ? async (chatId, messageId, replyMarkup) => {
+                try {
+                  await deps.editMessageReplyMarkup?.(
+                    chatId,
+                    messageId,
+                    replyMarkup,
+                  );
+                } catch (error) {
+                  deps.recordRuntimeEvent?.("telegram", error, {
+                    phase: "button-selection-mark",
+                    chatId,
+                    messageId,
+                  });
+                }
+              }
+            : undefined,
           enqueueButtonPrompt: (buttonQuery, action, context) => {
             const chatId = buttonQuery.message?.chat?.id;
             const messageId = buttonQuery.message?.message_id;
             if (typeof chatId !== "number" || typeof messageId !== "number")
-              return;
+              return false;
             const queueOrder = deps.bridgeRuntime.queue.allocateItemOrder();
             const turn = OutboundHandlers.createTelegramButtonPromptTurn({
               chatId,
@@ -1471,10 +1493,11 @@ export function createTelegramInboundRouteRuntime<
               deps.telegramQueueStore.getQueuedItems(),
               turn,
             );
-            if (!result.appended) return;
+            if (!result.appended) return false;
             deps.telegramQueueStore.setQueuedItems(result.items);
             deps.updateStatus(context);
             requestDispatchNextQueuedTelegramTurn(context);
+            return true;
           },
         },
       );