@llblab/pi-telegram 0.22.1 → 0.23.0

package/lib/activity.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram activity lifecycle normalization and extension dispatch
  * Zones: pi agent lifecycle, extension API, operational delivery
- * Owns stable handler registration, evidence-based activity/source identity, assistant segment and reasoning normalization, executed-tool and compaction events, isolated non-blocking queues, shutdown fencing, diagnostics, and fresh delivery contexts; excludes Pi hook wiring, visibility policy, Telegram rendering, and consumer-extension behavior
+ * Owns stable handler registration, evidence-based activity/source identity, assistant segment and reasoning normalization, ordered public-output projection, executed-tool and compaction events, isolated non-blocking queues, shutdown fencing, diagnostics, and fresh delivery contexts; excludes Pi hook wiring, Telegram rendering implementation, raw transport clients, and consumer-extension behavior
  */
 
 import {
@@ -91,6 +91,9 @@ export type TelegramActivityPayload =
 export type TelegramActivityEvent = TelegramActivityEnvelope &
   TelegramActivityPayload;
 
+export type TelegramAssistantSegmentEvent = TelegramActivityEnvelope &
+  Extract<TelegramActivityPayload, { type: "assistant-segment" }>;
+
 export interface TelegramActivityContext {
   activityId: string;
   sequence: number;
@@ -383,6 +386,7 @@ export function createTelegramActivityDispatcher(deps: {
 /** @internal */
 export function createTelegramActivityBridgeRuntime(deps: {
   generation: string;
+  observeEvent?: (event: TelegramActivityEvent) => void;
   recordFailure?: (
     handlerId: string,
     event: TelegramActivityEvent,
@@ -401,6 +405,11 @@ export function createTelegramActivityBridgeRuntime(deps: {
         dispatcher: createTelegramActivityDispatcher({
           recordFailure: deps.recordFailure,
         }),
+        observeEvent: deps.observeEvent,
+        recordObserverFailure: deps.recordFailure
+          ? (event, error) =>
+              deps.recordFailure!("@llblab/pi-telegram/proactive", event, error)
+          : undefined,
         now: deps.now,
       });
     },
@@ -507,6 +516,11 @@ interface PendingAssistantSegment {
 export function createTelegramActivityRuntime(deps: {
   generation: string;
   dispatcher: TelegramActivityDispatcher;
+  observeEvent?: (event: TelegramActivityEvent) => void;
+  recordObserverFailure?: (
+    event: TelegramActivityEvent,
+    error: unknown,
+  ) => void;
   now?: () => number;
 }): TelegramActivityRuntime {
   const now = deps.now ?? Date.now;
@@ -542,14 +556,20 @@ export function createTelegramActivityRuntime(deps: {
   const emit = (event: TelegramActivityPayload): void => {
     const currentActivityId = ensureActivity();
     sequence += 1;
-    deps.dispatcher.dispatch({
+    const normalizedEvent = {
       ...event,
       activityId: currentActivityId,
       sequence,
       source: activitySource,
       ...(activityTarget ? { target: activityTarget } : {}),
       timestamp: now(),
-    } as TelegramActivityEvent);
+    } as TelegramActivityEvent;
+    try {
+      deps.observeEvent?.(normalizedEvent);
+    } catch (error) {
+      deps.recordObserverFailure?.(normalizedEvent, error);
+    }
+    deps.dispatcher.dispatch(normalizedEvent);
   };
   const flushPendingSegment = (
     placement: "intermediate" | "final" | "terminal-partial",
@@ -681,3 +701,80 @@ export function createTelegramActivityRuntime(deps: {
     },
   };
 }
+
+// --- Public Assistant Output Projection ---
+
+export interface TelegramAssistantOutputRuntime {
+  start: () => void;
+  accept: (event: TelegramAssistantSegmentEvent) => void;
+  waitForIdle: () => Promise<void>;
+  stop: () => void;
+}
+
+export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(deps: {
+  isEnabled: () => boolean;
+  captureAuthority?: () => TAuthority;
+  isAuthorityActive?: (authority: TAuthority) => boolean;
+  canDeliver: (event: TelegramAssistantSegmentEvent) => boolean;
+  send: (
+    event: TelegramAssistantSegmentEvent,
+    authority: TAuthority,
+    isAuthorityActive: () => boolean,
+  ) => Promise<void>;
+  recordFailure?: (
+    event: TelegramAssistantSegmentEvent,
+    error: unknown,
+  ) => void;
+}): TelegramAssistantOutputRuntime {
+  let generation = 0;
+  let running = false;
+  let tail: Promise<void> = Promise.resolve();
+  const admitted = new Set<string>();
+  const isEligibleSource = (
+    source: TelegramAssistantSegmentEvent["source"],
+  ): boolean => source === "local" || source === "autonomous";
+
+  return {
+    start() {
+      generation += 1;
+      running = true;
+      admitted.clear();
+      tail = Promise.resolve();
+    },
+    accept(event) {
+      if (!running || !deps.isEnabled()) return;
+      if (!isEligibleSource(event.source) || !event.text.trim()) return;
+      const key = `${event.activityId}:${event.sequence}`;
+      if (admitted.has(key)) return;
+      admitted.add(key);
+      const admittedGeneration = generation;
+      const admittedAuthority = deps.captureAuthority?.();
+      tail = tail.then(async () => {
+        const isAdmittedAuthorityActive = () =>
+          running &&
+          generation === admittedGeneration &&
+          deps.isEnabled() &&
+          (deps.isAuthorityActive === undefined ||
+            deps.isAuthorityActive(admittedAuthority as TAuthority));
+        if (!isAdmittedAuthorityActive() || !deps.canDeliver(event)) return;
+        try {
+          await deps.send(
+            event,
+            admittedAuthority as TAuthority,
+            isAdmittedAuthorityActive,
+          );
+        } catch (error) {
+          deps.recordFailure?.(event, error);
+        }
+      });
+    },
+    waitForIdle() {
+      return tail;
+    },
+    stop() {
+      generation += 1;
+      running = false;
+      admitted.clear();
+    },
+  };
+}

package/lib/bindings.ts

@@ -19,6 +19,7 @@ import * as Preview from "./preview.ts";
 import * as Prompts from "./prompts.ts";
 import * as Queue from "./queue.ts";
 import * as Replies from "./replies.ts";
+import * as Routing from "./routing.ts";
 import * as Runtime from "./runtime.ts";
 import * as Setup from "./setup.ts";
 import * as Status from "./status.ts";
@@ -35,6 +36,60 @@ type TelegramRuntimeEventRecorder = (
 type TelegramBridgeStatusUpdater =
   Status.TelegramStatusRuntime<Pi.ExtensionContext>["updateStatus"];
 
+export interface TelegramAssistantOutputBindingRuntime<
+  TTransportStamp,
+> {
+  runtime: Activity.TelegramAssistantOutputRuntime;
+  observeEvent: (event: Activity.TelegramActivityEvent) => void;
+  authority: Routing.TelegramAssistantOutputAuthorityRuntime<TTransportStamp>;
+}
+
+export function createTelegramAssistantOutputBindingRuntime<
+  TTransportStamp,
+>(deps: {
+  isEnabled: () => boolean;
+  authority: {
+    getPreferredTarget: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"] | undefined;
+    getFallbackChatId: () => number | undefined;
+    getTransportStamp: () => TTransportStamp;
+    isTransportStampActive: (stamp: TTransportStamp) => boolean;
+    ownsDirect: () => boolean;
+    getDirectEpoch: () => number | string | undefined;
+    isFollowerRegistered: () => boolean;
+    getFollowerGeneration: () => string | undefined;
+  };
+  sender: Parameters<
+    typeof OutboundHandlers.createTelegramAssistantOutputSender<TTransportStamp>
+  >[0];
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}): TelegramAssistantOutputBindingRuntime<TTransportStamp> {
+  const authority =
+    Routing.createTelegramAssistantOutputAuthorityRuntime(deps.authority);
+  const send =
+    OutboundHandlers.createTelegramAssistantOutputSender<TTransportStamp>(
+      deps.sender,
+    );
+  const runtime = Activity.createTelegramAssistantOutputRuntime({
+    isEnabled: deps.isEnabled,
+    ...authority,
+    send,
+    recordFailure(event, error) {
+      deps.recordRuntimeEvent("proactive-push", error, {
+        activityId: event.activityId,
+        sequence: event.sequence,
+        placement: event.placement,
+      });
+    },
+  });
+  return {
+    runtime,
+    authority,
+    observeEvent(event) {
+      if (event.type === "assistant-segment") runtime.accept(event);
+    },
+  };
+}
+
 interface TelegramCommandsAndToolsBindingDeps {
   pi: Pi.ExtensionAPI;
   configStore: Config.TelegramConfigStore;
@@ -43,6 +98,7 @@ interface TelegramCommandsAndToolsBindingDeps {
   activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
   lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
   stopPolling?: () => Promise<void | string>;
+  getDisconnectThreadName?: () => string | undefined;
   onTransportChanged?: () => Promise<void> | void;
   getStatusLines: (
     options?: Status.TelegramBridgeStatusLineOptions,
@@ -70,6 +126,7 @@ export function registerTelegramCommandsAndTools({
   activeTurnRuntime,
   lockedPollingRuntime,
   stopPolling,
+  getDisconnectThreadName,
   onTransportChanged,
   getStatusLines,
   buttonActionStore,
@@ -186,6 +243,7 @@ export function registerTelegramCommandsAndTools({
     hasBotToken: configStore.hasBotToken,
     startPolling: lockedPollingRuntime.start,
     stopPolling: stopPolling ?? lockedPollingRuntime.stop,
+    getDisconnectThreadName,
     updateStatus,
     getProfileNames: () =>
       Config.getTelegramProfileNames(configStore.getStoredConfig()),
@@ -217,6 +275,10 @@ export function registerTelegramCommandsAndTools({
 interface TelegramLifecycleBindingDeps {
   pi: Pi.ExtensionAPI;
   activityRuntime: Activity.TelegramActivityRuntime;
+  assistantOutputRuntime: Pick<
+    Activity.TelegramAssistantOutputRuntime,
+    "start" | "stop"
+  >;
   sessionLifecycleRuntime: Pick<
     Lifecycle.TelegramLifecycleRegistrationDeps,
     "onSessionStart" | "onSessionShutdown" | "onModelSelect"
@@ -285,7 +347,12 @@ interface TelegramLifecycleBindingDeps {
   proactivePushChatIdGetter: () => number | undefined;
   proactivePushTargetGetter: () => Queue.TelegramQueueTarget | undefined;
   isProactivePushEnabled: () => boolean;
-  canSendProactivePush: (ctx: Pi.ExtensionContext) => boolean;
+  getAssistantRenderingMode: () => "rich" | "html";
+  recordMessageOwnership?: (input: {
+    chatId: number;
+    messageId: number;
+    target?: Queue.TelegramQueueTarget;
+  }) => void;
   canSendAgentActivity: (ctx: Pi.ExtensionContext) => boolean;
   isSessionContextActive: (ctx: Pi.ExtensionContext) => boolean;
   isTurnTransportActive?: (turn: Queue.PendingTelegramTurn) => boolean;
@@ -296,6 +363,7 @@ interface TelegramLifecycleBindingDeps {
 export function registerTelegramLifecycleRuntimeHooks({
   pi,
   activityRuntime,
+  assistantOutputRuntime,
   sessionLifecycleRuntime,
   configStore,
   abort,
@@ -322,7 +390,8 @@ export function registerTelegramLifecycleRuntimeHooks({
   proactivePushChatIdGetter,
   proactivePushTargetGetter,
   isProactivePushEnabled,
-  canSendProactivePush,
+  getAssistantRenderingMode,
+  recordMessageOwnership,
   canSendAgentActivity,
   isSessionContextActive = () => true,
   isTurnTransportActive,
@@ -343,6 +412,13 @@ export function registerTelegramLifecycleRuntimeHooks({
       sendTextReply,
       recordRuntimeEvent,
     });
+  const richAttachmentSender =
+    OutboundAttachments.createTelegramRichOutboundAttachmentSender({
+      sendMultipart: callMultipart,
+      getRenderingMode: getAssistantRenderingMode,
+      recordOwnership: recordMessageOwnership,
+      recordRuntimeEvent,
+    });
   const sendGuestAttachment = async (
     turn: Queue.PendingTelegramTurn,
     attachment: Queue.QueuedAttachment,
@@ -499,16 +575,13 @@ export function registerTelegramLifecycleRuntimeHooks({
     sendMarkdownReply,
     sendTextReply,
     sendQueuedAttachments: queuedAttachmentSender,
+    sendRichAttachmentReply: richAttachmentSender,
     answerGuestQuery,
     sendGuestReply,
     sendGuestAttachment,
     sendGuestVoiceReply,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
-    getDefaultChatId: proactivePushChatIdGetter,
-    getDefaultTarget: proactivePushTargetGetter,
-    isProactivePushEnabled,
-    canSendProactivePush,
     recordRuntimeEvent,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
     setActiveToolExecutions: lifecycle.setActiveToolExecutions,
@@ -565,12 +638,14 @@ export function registerTelegramLifecycleRuntimeHooks({
     },
     async onSessionStart(event, ctx) {
       previewRuntime.invalidate();
+      assistantOutputRuntime.start();
       activityRuntime.onSessionStart?.();
       await sessionLifecycleRuntime.onSessionStart(event, ctx);
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
       activityRuntime.onSessionShutdown();
+      assistantOutputRuntime.stop();
       compactionObserver.onSessionShutdown();
       await sessionLifecycleRuntime.onSessionShutdown(event, ctx);
     },

package/lib/bus-follower.ts

@@ -98,6 +98,7 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
     options?: { target?: TelegramTarget },
   ) => Promise<boolean>;
   setContext: (ctx: TContext) => void;
+  disconnectFromLeader?: () => Promise<boolean>;
   stop: () => void;
 }
 
@@ -108,6 +109,10 @@ export interface TelegramBusFollowerSessionReplacementSuspenderDeps {
   >;
   instanceId: string;
   suspendPolling: () => Promise<void>;
+  isLeader?: () => boolean;
+  getLeaderBinding?: () => TelegramBusFollowerPromotedBinding | undefined;
+  getActiveContext?: () => { cwd?: string } | undefined;
+  getActiveProfileName?: () => string | undefined;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
@@ -139,6 +144,8 @@ export interface TelegramBusFollowerRegistrationState {
   getSlot: () => string | undefined;
   getThreadName: () => string | undefined;
   getGeneration: () => string | undefined;
+  getEligibleElectionSlots: () => readonly string[];
+  setEligibleElectionSlots: (slots: readonly string[]) => void;
   setRegistered: (
     registered: boolean,
     target?: TelegramTarget,
@@ -151,12 +158,20 @@ export interface TelegramBusForwardedUpdateReceiverRuntime {
   stop: () => Promise<void>;
 }
 
-export interface TelegramBusFollowerClientRuntimeDeps {
+export interface TelegramBusFollowerClientRuntimeDeps<TMessage = unknown> {
   socketPath: TelegramBusSocketPathSource;
   instanceId: string;
   getApiAuthSecret?: () => string | undefined;
   getForwardingAuthSecret?: () => string | undefined;
   getRegistrationGeneration?: () => string | undefined;
+  getForwardCommentBatchPosition?: (
+    message: TMessage,
+  ) => "comment" | "forward" | undefined;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
   timeoutMs?: number;
 }
 
@@ -239,9 +254,11 @@ export function createTelegramBusFollowerPromotionHandler<
     error: unknown,
     details?: Record<string, unknown>,
   ) => void;
+  getNowMs?: () => number;
+  getPid?: () => number;
 }): TelegramBusFollowerPromotionHandler<TContext> {
-  return async (ctx, binding, election) =>
-    input.startLeader(ctx, election, async () => {
+  return async (ctx, binding, election) => {
+    const promoted = await input.startLeader(ctx, election, async () => {
       const promotedRecord =
         await Threads.promoteTelegramFollowerBindingToLeader({
           store: input.topicTargetStore,
@@ -266,6 +283,39 @@ export function createTelegramBusFollowerPromotionHandler<
         );
       }
     });
+    if (promoted && typeof binding.target?.threadId === "number") {
+      const profileKey = Threads.getTelegramThreadOwnerKey({
+        kind: "leader",
+        cwd: ctx.cwd,
+        instanceId: input.instanceId,
+        telegramProfile: input.getActiveProfileName(),
+      });
+      Threads.setTelegramLeaderSessionHandoff({
+        pid: input.getPid?.() ?? process.pid,
+        instanceId: input.instanceId,
+        createdAtMs: input.getNowMs?.() ?? Date.now(),
+        profileKey,
+        target: {
+          chatId: binding.target.chatId,
+          threadId: binding.target.threadId,
+        },
+        slot: binding.slot,
+        threadName: binding.threadName,
+      });
+      input.recordRuntimeEvent(
+        "bus",
+        "Promoted leader binding retained for session replacement",
+        {
+          phase: "follower-promoted-session-handoff",
+          chatId: binding.target.chatId,
+          threadId: binding.target.threadId,
+          slot: binding.slot,
+          threadName: binding.threadName,
+        },
+      );
+    }
+    return promoted;
+  };
 }
 
 export interface TelegramBusFollowerTargetReplacementHandlerDeps<TContext> {
@@ -309,7 +359,11 @@ export interface TelegramBusFollowerPromotedBinding {
 export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
   registrationState: Pick<
     TelegramBusFollowerRegistrationState,
-    "getTarget" | "getSlot" | "getThreadName" | "setRegistered"
+    | "getTarget"
+    | "getSlot"
+    | "getThreadName"
+    | "getEligibleElectionSlots"
+    | "setRegistered"
   >;
   getRegistrationRuntime: () => TelegramBusFollowerRegistrationRuntime<TContext>;
   getLeaderState: () => TelegramBusFollowerLeaderState;
@@ -350,6 +404,10 @@ export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<
     reactionUpdate: TReactionUpdate,
     ctx: TContext,
   ) => Promise<void> | void;
+  prepareForwardedMessage?: (
+    message: TMessage,
+    position: "comment" | "forward",
+  ) => void;
   handleForwardedMessage?: (
     message: TMessage,
     ctx: TContext,
@@ -564,7 +622,7 @@ export function createTelegramBusFollowerClientRuntime<
   TReactionUpdate,
   TCallbackQuery,
   TMessage = unknown,
->(deps: TelegramBusFollowerClientRuntimeDeps) {
+>(deps: TelegramBusFollowerClientRuntimeDeps<TMessage>) {
   const createRequestId = createTelegramBusRequestIdFactory(deps.instanceId);
   const sharedClientDeps = {
     socketPath: deps.socketPath,
@@ -587,6 +645,9 @@ export function createTelegramBusFollowerClientRuntime<
     >({
       ...sharedClientDeps,
       getAuthSecret: deps.getForwardingAuthSecret,
+      getForwardCommentBatchPosition:
+        deps.getForwardCommentBatchPosition,
+      recordRuntimeEvent: deps.recordRuntimeEvent,
     }),
     targetController: createTelegramBusFollowerTargetController({
       ...sharedClientDeps,
@@ -689,6 +750,41 @@ export function createTelegramBusFollowerSessionReplacementSuspender(
           threadId: target.threadId,
         },
       );
+    } else if (deps.isLeader?.()) {
+      const leaderBinding = deps.getLeaderBinding?.();
+      if (typeof leaderBinding?.target?.threadId === "number") {
+        const activeContext = deps.getActiveContext?.();
+        const profileKey = Threads.getTelegramThreadOwnerKey({
+          kind: "leader",
+          cwd: activeContext?.cwd,
+          instanceId: deps.instanceId,
+          telegramProfile: deps.getActiveProfileName?.(),
+        });
+        Threads.setTelegramLeaderSessionHandoff({
+          pid: getPid(),
+          instanceId: deps.instanceId,
+          createdAtMs: getNowMs(),
+          profileKey,
+          target: {
+            chatId: leaderBinding.target.chatId,
+            threadId: leaderBinding.target.threadId,
+          },
+          slot: leaderBinding.slot,
+          threadName: leaderBinding.threadName,
+        });
+        deps.recordRuntimeEvent(
+          "bus",
+          "Telegram leader binding suspended for session replacement",
+          {
+            phase: "leader-session-handoff",
+            instanceId: deps.instanceId,
+            chatId: leaderBinding.target.chatId,
+            threadId: leaderBinding.target.threadId,
+            slot: leaderBinding.slot,
+            threadName: leaderBinding.threadName,
+          },
+        );
+      }
     }
     await deps.suspendPolling();
   };
@@ -751,12 +847,19 @@ export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowe
   let slot: string | undefined;
   let threadName: string | undefined;
   let generation: string | undefined;
+  let eligibleElectionSlots: string[] = [];
   return {
     isRegistered: () => registered,
     getTarget: () => (target ? { ...target } : undefined),
     getSlot: () => slot,
     getThreadName: () => threadName,
     getGeneration: () => generation,
+    getEligibleElectionSlots: () => [...eligibleElectionSlots],
+    setEligibleElectionSlots: (slots) => {
+      eligibleElectionSlots = Array.from(
+        new Set(slots.filter((slot) => /^[A-Z]$/.test(slot))),
+      ).sort();
+    },
     setRegistered: (next, nextTarget, metadata) => {
       registered = next;
       target = next ? (nextTarget ? { ...nextTarget } : undefined) : undefined;
@@ -868,7 +971,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     deps.getRegistrationRuntime().stop();
     deps.setLifecyclePhase("electing");
     safeUpdateStatus(ctx);
-    deps.recordRuntimeEvent("bus", "Telegram follower elected for promotion", {
+    deps.recordRuntimeEvent("bus", "Telegram follower attempting promotion", {
       phase: "follower-promotion-electing",
     });
     const promoted = await deps.promoteToLeader(ctx, binding, election);
@@ -887,6 +990,51 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     );
     if (!promoted) scheduleRecovery(reason, ctx, binding);
   };
+  const attemptPreferredPromotion = async (
+    reason: unknown,
+    ctx: TContext,
+    binding: TelegramBusFollowerPromotedBinding,
+    candidateState: TelegramBusFollowerLeaderState,
+  ): Promise<void> => {
+    const slot = binding.slot;
+    const lowerEligibleSlot = slot
+      ? deps.registrationState
+          .getEligibleElectionSlots()
+          .find((candidate) => candidate < slot)
+      : undefined;
+    if (lowerEligibleSlot) {
+      deps.recordRuntimeEvent(
+        "bus",
+        "Telegram follower deferring to a lower-slot election candidate",
+        {
+          phase: "follower-promotion-slot-priority",
+          slot,
+          lowerEligibleSlot,
+        },
+      );
+      await sleep(promotionGraceMs);
+      candidateState = deps.getLeaderState();
+      if (candidateState.kind === "active-elsewhere") {
+        if (
+          !(await tryRegisterWithLeader(
+            ctx,
+            candidateState.lock,
+            "follower-register-preferred-successor",
+            binding,
+          ))
+        ) {
+          scheduleRecovery(reason, ctx, binding);
+        }
+        return;
+      }
+    }
+    if (candidateState.kind !== "stale" && candidateState.kind !== "inactive")
+      return;
+    await promoteToLeader(reason, ctx, binding, {
+      expectedOwner:
+        candidateState.kind === "stale" ? candidateState.lock : undefined,
+    });
+  };
   const recover = async (
     error: unknown,
     ctx: TContext,
@@ -943,19 +1091,15 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
           scheduleRecovery(error, ctx, initialBinding);
           return;
         }
-        if (graceState.kind === "stale" || graceState.kind === "inactive") {
-          await promoteToLeader(error, ctx, initialBinding, {
-            expectedOwner:
-              graceState.kind === "stale" ? graceState.lock : undefined,
-          });
-        }
+        await attemptPreferredPromotion(
+          error,
+          ctx,
+          initialBinding,
+          graceState,
+        );
         return;
       }
-      if (state.kind === "stale" || state.kind === "inactive") {
-        await promoteToLeader(error, ctx, initialBinding, {
-          expectedOwner: state.kind === "stale" ? state.lock : undefined,
-        });
-      }
+      await attemptPreferredPromotion(error, ctx, initialBinding, state);
     } catch (promotionError) {
       deps.setLifecyclePhase(undefined);
       safeUpdateStatus(ctx);
@@ -1035,6 +1179,17 @@ export function createTelegramBusFollowerRegistrationRuntime<
           sentAtMs: getNowMs(),
         },
       });
+      if (response?.kind === "bus.ack" && response.ok) {
+        const heartbeatResult = isRecord(response.result)
+          ? response.result
+          : undefined;
+        const slots = Array.isArray(heartbeatResult?.eligibleElectionSlots)
+          ? heartbeatResult.eligibleElectionSlots.filter(
+              (slot): slot is string => typeof slot === "string",
+            )
+          : [];
+        deps.registrationState?.setEligibleElectionSlots(slots);
+      }
       if (response?.kind === "bus.ack" && !response.ok) {
         throw new Error(
           response.message ?? "Telegram bus follower heartbeat was rejected.",
@@ -1172,6 +1327,33 @@ export function createTelegramBusFollowerRegistrationRuntime<
     setContext(ctx) {
       activeContext = ctx;
     },
+    async disconnectFromLeader() {
+      if (!activeLeaderSocketPath || !activeRegistrationGeneration) {
+        return false;
+      }
+      const response = await sendTelegramBusLocalEnvelope({
+        socketPath: activeLeaderSocketPath,
+        timeoutMs: registrationTimeoutMs,
+        retry: getTelegramBusTransportRetryPolicy({
+          endpoint: activeLeaderSocketPath,
+          operation: "operation",
+        }),
+        envelope: {
+          kind: "follower.disconnect",
+          requestId: deps.createRequestId(),
+          auth: activeAuthSecret,
+          instanceId: deps.instanceId,
+          registrationGeneration: activeRegistrationGeneration,
+          sentAtMs: getNowMs(),
+        },
+      });
+      if (response?.kind === "bus.ack" && response.ok) return true;
+      throw new Error(
+        response?.kind === "bus.ack"
+          ? (response.message ?? "Telegram follower disconnect was rejected.")
+          : "Telegram follower disconnect was not acknowledged.",
+      );
+    },
     stop,
   };
 }
@@ -1250,6 +1432,12 @@ export function createTelegramBusForwardedUpdateReceiverRuntime<
             ctx,
           );
         } else if (envelope.kind === "leader.forwardMessage") {
+          if (envelope.forwardCommentBatchPosition) {
+            deps.prepareForwardedMessage?.(
+              envelope.message as TMessage,
+              envelope.forwardCommentBatchPosition,
+            );
+          }
           if (!deps.handleForwardedMessage) {
             throw new Error(
               "Telegram bus receiver cannot handle this envelope.",