@llblab/pi-telegram 0.22.1 → 0.23.1

package/lib/bus-leader.ts

@@ -109,17 +109,10 @@ export interface TelegramBusFollowerTargetProvisionerDeps {
   ) => void;
 }
 
-export interface TelegramBusFollowerPruneHandlerDeps {
+export interface TelegramBusFollowerDisconnectHandlerDeps {
   topicTargetStore: Pick<
     Threads.TelegramTopicTargetStore,
-    | "load"
-    | "getActiveByInstanceId"
-    | "list"
-    | "listPendingProvisions"
-    | "markStaleByTarget"
-    | "markOfflineByInstanceId"
-    | "persist"
-    | "removePendingProvision"
+    "markOfflineByInstanceId" | "persist"
   >;
   callApi: <TResponse>(
     method: string,
@@ -161,10 +154,9 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
   runtime: Omit<
     TelegramBusLeaderRuntimeDeps<TContext>,
     | "callApi"
-    | "onFollowerPruned"
+    | "onFollowerDisconnected"
     | "provisionFollowerTarget"
     | "provisionLeaderTarget"
-    | "reconcileFollowerBindings"
     | "recordRuntimeEvent"
   >;
   getAllowedUserId: () => number | undefined;
@@ -217,19 +209,13 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
       recordThreadReconciliationPlan: deps.recordThreadReconciliationPlan,
       setLeaderTarget: deps.setLeaderTarget,
     }),
-    onFollowerPruned: createTelegramBusFollowerPruneHandler({
+    onFollowerDisconnected: createTelegramBusFollowerDisconnectHandler({
       ...provisionerPorts,
     }),
     provisionFollowerTarget: createTelegramBusFollowerTargetProvisioner({
       ...provisionerPorts,
     }),
     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
-    reconcileFollowerBindings:
-      createTelegramBusFollowerBindingRealityReconciler({
-        topicTargetStore: deps.topicTargetStore,
-        followerRegistry: deps.runtime.followerRegistry,
-        recordRuntimeEvent: deps.recordRuntimeEvent,
-      }),
     callApi: createTelegramBusLeaderApiProxy({
       call: deps.callApi,
       callMultipart: deps.callMultipart,
@@ -240,29 +226,6 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
   });
 }
 
-export const TELEGRAM_BUS_RECENT_FOLLOWER_BINDING_GRACE_MS = 10_000;
-
-export interface TelegramBusFollowerBindingRealityDeps {
-  topicTargetStore: Pick<
-    Threads.TelegramTopicTargetStore,
-    | "load"
-    | "list"
-    | "markOfflineByInstanceId"
-    | "forgetIdentityByProfileKey"
-    | "getBotState"
-    | "persist"
-    | "setBotState"
-  >;
-  followerRegistry: Pick<TelegramBusFollowerRegistry, "list">;
-  getNowMs?: () => number;
-  recentBindingGraceMs?: number;
-  recordRuntimeEvent: (
-    category: string,
-    error: unknown,
-    details?: Record<string, unknown>,
-  ) => void;
-}
-
 export interface TelegramBusFollowerMessageOwnershipRecord {
   follower: TelegramBusFollowerView;
   chatId: number;
@@ -292,13 +255,11 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     registration: TelegramBusInstanceRegistration,
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
   getCurrentLeaderEpoch?: () => number | string | undefined;
-  reconcileFollowerBindings?: () => Promise<unknown> | unknown;
   provisionLeaderTarget?: (ctx: TContext) => Promise<void> | void;
   getNowMs?: () => number;
   followerPruneIntervalMs?: number;
   followerStaleAfterMs?: number;
-  followerRecoveryGraceMs?: number;
-  onFollowerPruned?: (
+  onFollowerDisconnected?: (
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
   recordRuntimeEvent?: (
@@ -308,76 +269,11 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   ) => void;
 }
 
-export function createTelegramBusFollowerBindingRealityReconciler(
-  deps: TelegramBusFollowerBindingRealityDeps,
-): () => Promise<number> {
-  const getNowMs = deps.getNowMs ?? Date.now;
-  const recentBindingGraceMs =
-    deps.recentBindingGraceMs ?? TELEGRAM_BUS_RECENT_FOLLOWER_BINDING_GRACE_MS;
-  return async () => {
-    await deps.topicTargetStore.load();
-    const nowMs = getNowMs();
-    const liveInstanceIds = new Set(
-      deps.followerRegistry.list().map((follower) => follower.instanceId),
-    );
-    const staleRecords = deps.topicTargetStore.list().filter((record) => {
-      return (
-        record.owner?.kind === "manual-follower" &&
-        !!record.instanceId &&
-        !liveInstanceIds.has(record.instanceId) &&
-        nowMs - record.updatedAtMs > recentBindingGraceMs
-      );
-    });
-    const staleInstanceIds = new Set(
-      staleRecords.flatMap((record) =>
-        record.instanceId ? [record.instanceId] : [],
-      ),
-    );
-    let removed = 0;
-    for (const instanceId of staleInstanceIds) {
-      removed += deps.topicTargetStore.markOfflineByInstanceId(instanceId);
-    }
-    for (const record of staleRecords) {
-      const profileKey =
-        record.profileKey ??
-        (record.owner
-          ? Threads.getTelegramThreadOwnerKey(record.owner)
-          : undefined);
-      if (profileKey)
-        deps.topicTargetStore.forgetIdentityByProfileKey(profileKey);
-    }
-    if (removed === 0) return 0;
-    const cursorRealigned = Threads.reconcileTelegramFreshAllocationCursor(
-      deps.topicTargetStore,
-    );
-    await deps.topicTargetStore.persist();
-    deps.recordRuntimeEvent(
-      "bus",
-      "Historical follower bindings removed from live state",
-      {
-        phase: "follower-binding-reality",
-        removed,
-      },
-    );
-    if (cursorRealigned) {
-      deps.recordRuntimeEvent(
-        "bus",
-        "Fresh allocation cursor realigned after live-state compaction",
-        {
-          phase: "follower-binding-reality-cursor",
-          lastSlot: deps.topicTargetStore.getBotState().lastSlot,
-        },
-      );
-    }
-    return removed;
-  };
-}
-
 export function createTelegramBusInstanceLifecycleAnnouncement(input: {
   target: TelegramTarget & { threadId: number };
   threadName?: string;
   slot?: string;
-  state: "connected" | "disconnected";
+  state: "connected";
 }): TelegramBusFollowerLifecycleAnnouncement {
   return {
     target: { ...input.target },
@@ -386,23 +282,6 @@ export function createTelegramBusInstanceLifecycleAnnouncement(input: {
   };
 }
 
-export function createTelegramBusFollowerDisconnectedAnnouncement(input: {
-  follower: TelegramBusFollowerView;
-  threadName?: string;
-  slot?: string;
-}): TelegramBusFollowerLifecycleAnnouncement | undefined {
-  if (!input.follower.target?.threadId) return undefined;
-  return createTelegramBusInstanceLifecycleAnnouncement({
-    target: {
-      chatId: input.follower.target.chatId,
-      threadId: input.follower.target.threadId,
-    },
-    threadName: input.threadName,
-    slot: input.slot,
-    state: "disconnected",
-  });
-}
-
 const TELEGRAM_BUS_SLOW_FOLLOWER_REGISTRATION_MS = 1000;
 
 function scheduleTelegramBusLeaderBackgroundTask(
@@ -473,29 +352,29 @@ export function createTelegramBusFollowerTargetProvisioner(
     const recordsBeforeProvision = deps.topicTargetStore.list();
     const followerProfileKey =
       registration.profileKey ?? `manual:${registration.instanceId}`;
-    const reconnectRecord = registration.target
-      ? recordsBeforeProvision.find((record) => {
-          return (
-            record.owner?.kind === "manual-follower" &&
-            (record.instanceId === registration.instanceId ||
-              record.profileKey === followerProfileKey) &&
-            record.target.chatId === registration.target?.chatId &&
-            record.target.threadId === registration.target.threadId
-          );
-        })
-      : undefined;
+    const requestedTarget = registration.target;
+    const reconnectRecord = recordsBeforeProvision.find((record) => {
+      return (
+        record.owner?.kind === "manual-follower" &&
+        (record.instanceId === registration.instanceId ||
+          record.profileKey === followerProfileKey) &&
+        (!requestedTarget ||
+          (record.target.chatId === requestedTarget.chatId &&
+            record.target.threadId === requestedTarget.threadId))
+      );
+    });
     const followerOwner =
       Threads.getTelegramThreadOwnerFromProfileKey(followerProfileKey);
     const recoverableTarget =
       !reconnectRecord &&
-      registration.target?.chatId === chatId &&
-      registration.target.threadId !== undefined &&
+      requestedTarget?.chatId === chatId &&
+      requestedTarget.threadId !== undefined &&
       !recordsBeforeProvision.some(
         (record) =>
-          record.target.chatId === registration.target?.chatId &&
-          record.target.threadId === registration.target.threadId,
+          record.target.chatId === requestedTarget.chatId &&
+          record.target.threadId === requestedTarget.threadId,
       )
-        ? registration.target
+        ? requestedTarget
         : undefined;
     const recoveryHint = recoverableTarget
       ? deps.topicTargetStore.getFollowerRecoveryHintByTarget?.(
@@ -526,13 +405,14 @@ export function createTelegramBusFollowerTargetProvisioner(
     };
     const recoverRequestedTarget = async () => {
       const nowMs = getNowMs();
+      const carriedThreadName = registration.threadName;
       const requestedThreadName =
-        registration.threadName &&
+        carriedThreadName &&
         Threads.isTelegramTopicThreadNameValidForSlot(
-          registration.threadName,
+          carriedThreadName,
           registration.slot,
         )
-          ? registration.threadName
+          ? carriedThreadName
           : recoveryHint?.threadName &&
               Threads.isTelegramTopicThreadNameValidForSlot(
                 recoveryHint.threadName,
@@ -540,7 +420,7 @@ export function createTelegramBusFollowerTargetProvisioner(
               )
             ? recoveryHint.threadName
             : undefined;
-      let recoveredRecord = deps.topicTargetStore.upsert({
+      let recoveredRecord: Threads.TelegramTopicTargetRecord = {
         profileKey: followerProfileKey,
         owner:
           followerOwner.kind === "manual-follower"
@@ -560,19 +440,15 @@ export function createTelegramBusFollowerTargetProvisioner(
         ...(requestedThreadName ? { threadName: requestedThreadName } : {}),
         lastSyncObservedAtMs: nowMs,
         lastReconcileAction: "follower-live-target-recovery",
-      });
+      };
       const requestedSlot = registration.slot ?? recoveryHint?.slot;
       const requestedSlotAvailable =
         !!requestedSlot &&
         /^[A-Z]$/.test(requestedSlot) &&
         !recordsBeforeProvision.some((record) => record.slot === requestedSlot);
       if (requestedSlotAvailable) {
-        recoveredRecord = deps.topicTargetStore.upsert({
-          ...recoveredRecord,
-          slot: requestedSlot,
-        });
+        recoveredRecord = { ...recoveredRecord, slot: requestedSlot };
       }
-      await deps.topicTargetStore.persist();
       return {
         target: recoveredRecord.target,
         reused: true,
@@ -591,25 +467,117 @@ export function createTelegramBusFollowerTargetProvisioner(
         : recoverableTarget
           ? await recoverRequestedTarget()
           : await provisionTarget();
-      if (reconnectRecord) {
+      const crossSessionReuse =
+        !!reconnectRecord &&
+        reconnectRecord.instanceId !== registration.instanceId;
+      if (reconnectRecord && !crossSessionReuse) {
         const nowMs = getNowMs();
-        const transferredRecord = deps.topicTargetStore.upsert({
+        const refreshedRecord = deps.topicTargetStore.upsert({
           ...reconnectRecord,
           instanceId: registration.instanceId,
           updatedAtMs: nowMs,
           lastSyncObservedAtMs: nowMs,
-          lastReconcileAction:
-            reconnectRecord.instanceId === registration.instanceId
-              ? "follower-register-reuse"
-              : "follower-session-handoff",
+          lastReconcileAction: "follower-register-reuse",
         });
         await deps.topicTargetStore.persist();
         result = {
-          target: transferredRecord.target,
+          target: refreshedRecord.target,
           reused: true,
-          record: transferredRecord,
+          record: refreshedRecord,
         };
       }
+      const probeRequiredRecord =
+        reconnectRecord?.status === "probe-required";
+      const requiresVisibilityProbe =
+        crossSessionReuse ||
+        probeRequiredRecord ||
+        recoverableTarget !== undefined;
+      let connectedAnnouncement =
+        !result.reused || requiresVisibilityProbe
+          ? createTelegramBusInstanceLifecycleAnnouncement({
+              target: result.target,
+              threadName: result.record.threadName,
+              slot: result.record.slot,
+              state: "connected",
+            })
+          : undefined;
+      if (requiresVisibilityProbe && connectedAnnouncement) {
+        try {
+          await deps.callApi("sendMessage", {
+            chat_id: connectedAnnouncement.target.chatId,
+            message_thread_id: connectedAnnouncement.target.threadId,
+            text: connectedAnnouncement.text,
+            parse_mode: connectedAnnouncement.parseMode,
+          });
+          if (recoverableTarget || probeRequiredRecord) {
+            const activatedRecord = deps.topicTargetStore.upsert({
+              ...result.record,
+              status: "active",
+              updatedAtMs: getNowMs(),
+              lastSyncObservedAtMs: getNowMs(),
+              lastReconcileAction: "follower-live-target-recovery",
+            });
+            await deps.topicTargetStore.persist();
+            result = {
+              target: activatedRecord.target,
+              reused: true,
+              record: activatedRecord,
+            };
+          } else if (crossSessionReuse && reconnectRecord) {
+            const nowMs = getNowMs();
+            const transferredRecord = deps.topicTargetStore.upsert({
+              ...reconnectRecord,
+              instanceId: registration.instanceId,
+              updatedAtMs: nowMs,
+              lastSyncObservedAtMs: nowMs,
+              lastReconcileAction: "follower-session-handoff",
+            });
+            await deps.topicTargetStore.persist();
+            result = {
+              target: transferredRecord.target,
+              reused: true,
+              record: transferredRecord,
+            };
+          }
+          connectedAnnouncement = undefined;
+        } catch (error) {
+          if (Threads.isTelegramTopicTargetStaleError(error)) {
+            deps.topicTargetStore.markStaleByTarget(
+              result.target,
+              "deleted",
+              error instanceof Error ? error.message : String(error),
+            );
+            await deps.topicTargetStore.persist();
+            result = await provisionTarget();
+            connectedAnnouncement =
+              createTelegramBusInstanceLifecycleAnnouncement({
+                target: result.target,
+                threadName: result.record.threadName,
+                slot: result.record.slot,
+                state: "connected",
+              });
+          } else {
+            deps.recordRuntimeEvent("telegram", error, {
+              phase: "follower-topic-reuse-probe",
+              instanceId: registration.instanceId,
+              chatId: result.target.chatId,
+              threadId: result.target.threadId,
+            });
+            if (recoverableTarget) {
+              deps.topicTargetStore.upsert({
+                ...result.record,
+                status: "probe-required",
+                updatedAtMs: getNowMs(),
+                lastSyncError:
+                  error instanceof Error ? error.message : String(error),
+                lastReconcileAction: "follower-visibility-probe-required",
+              });
+              await deps.topicTargetStore.persist();
+            }
+            throw error;
+          }
+        }
+      }
       deps.setSyncState(
         Sync.markTelegramSyncSliceFresh(
           deps.getSyncState(),
@@ -620,14 +588,6 @@ export function createTelegramBusFollowerTargetProvisioner(
           },
         ),
       );
-      const connectedAnnouncement = result.reused
-        ? undefined
-        : createTelegramBusInstanceLifecycleAnnouncement({
-            target: result.target,
-            threadName: result.record.threadName,
-            slot: result.record.slot,
-            state: "connected",
-          });
       recordSlowTelegramBusFollowerRegistrationStep(deps, {
         phase: "follower-register-critical",
         elapsedMs: Date.now() - registrationStartedAtMs,
@@ -718,18 +678,55 @@ export function createTelegramBusFollowerTargetProvisioner(
   };
 }
 
-export function createTelegramBusFollowerPruneHandler(
-  deps: TelegramBusFollowerPruneHandlerDeps,
+export function createTelegramBusFollowerDisconnectHandler(
+  deps: TelegramBusFollowerDisconnectHandlerDeps,
 ): (follower: TelegramBusFollowerView) => Promise<void> {
   return async (follower) => {
-    deps.recordRuntimeEvent(
-      "bus",
-      "Telegram bus follower heartbeat stale; preserving thread binding",
-      {
-        phase: "follower-pruned",
+    const target = follower.target;
+    if (!target?.threadId) return;
+    const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+    if (deps.getCurrentLeaderEpoch && leaderEpoch === undefined) {
+      throw new Error("Follower disconnect cleanup requires leader ownership.");
+    }
+    const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
+      ThreadReconciler.planDisconnectedInstanceThreadCleanup({
+        target: { chatId: target.chatId, threadId: target.threadId },
         instanceId: follower.instanceId,
+        leaderEpoch,
+      }),
+      {
+        callApi: deps.callApi,
+        persist: deps.topicTargetStore.persist,
+        getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
+        recordRuntimeEvent: deps.recordRuntimeEvent,
       },
     );
+    if (cleanup.incompleteActions?.length) {
+      throw new Error(
+        "Telegram follower thread deletion was not confirmed; reconnect the leader and retry /telegram-disconnect.",
+      );
+    }
+    if (
+      deps.getCurrentLeaderEpoch &&
+      deps.getCurrentLeaderEpoch() !== leaderEpoch
+    ) {
+      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",
+      }),
+    );
+    deps.recordRuntimeEvent("bus", "Telegram bus follower disconnected", {
+      phase: "follower-disconnect",
+      instanceId: follower.instanceId,
+      chatId: target.chatId,
+      threadId: target.threadId,
+    });
   };
 }
 
@@ -875,12 +872,49 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   recordFollowerMessageOwnership?: TelegramBusFollowerMessageOwnershipRecorder;
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
-  ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  ) =>
+    | Promise<
+        | (TelegramTarget & { slot?: string; threadName?: string })
+        | undefined
+      >
+    | (TelegramTarget & { slot?: string; threadName?: string })
+    | undefined;
+  onFollowerDisconnected?: (
+    follower: TelegramBusFollowerView,
+  ) => Promise<void> | void;
   getCurrentLeaderEpoch?: () => number | string | undefined;
 }): (
   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 forwardToFollower = async (
     envelope: Extract<
       TelegramBusEnvelope,
@@ -943,47 +977,115 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
     }
     switch (envelope.kind) {
       case "follower.register": {
-        try {
-          const leaderEpoch = deps.getCurrentLeaderEpoch?.();
-          if (deps.getCurrentLeaderEpoch && leaderEpoch === undefined) {
-            throw new Error(
-              "Telegram follower registration requires leader ownership.",
+        return runFollowerMutation(
+          getFollowerMutationKey(envelope.registration),
+          async () => {
+          try {
+            if (!envelope.registration.registrationGeneration) {
+              throw new Error(
+                "Telegram follower registration requires an exact generation.",
+              );
+            }
+            const leaderEpoch = deps.getCurrentLeaderEpoch?.();
+            if (deps.getCurrentLeaderEpoch && leaderEpoch === undefined) {
+              throw new Error(
+                "Telegram follower registration requires leader ownership.",
+              );
+            }
+            const target = await deps.provisionFollowerTarget?.(
+              envelope.registration,
             );
+            if (
+              deps.getCurrentLeaderEpoch &&
+              deps.getCurrentLeaderEpoch() !== leaderEpoch
+            ) {
+              throw new Error(
+                "Telegram follower registration lost leader ownership.",
+              );
+            }
+            const registeredTarget = target ?? envelope.registration.target;
+            deps.followerRegistry.register({
+              ...envelope.registration,
+              connectedAtMs: getNowMs(),
+              target: registeredTarget,
+              ...((target?.slot ?? envelope.registration.slot)
+                ? { slot: target?.slot ?? envelope.registration.slot }
+                : {}),
+              ...((target?.threadName ?? envelope.registration.threadName)
+                ? {
+                    threadName:
+                      target?.threadName ?? envelope.registration.threadName,
+                  }
+                : {}),
+            });
+            return {
+              kind: "bus.ack" as const,
+              requestId: envelope.requestId,
+              ok: true,
+              ...(registeredTarget ? { result: registeredTarget } : {}),
+            };
+          } catch (error) {
+            return {
+              kind: "bus.ack" as const,
+              requestId: envelope.requestId,
+              ok: false,
+              message:
+                error instanceof Error
+                  ? error.message
+                  : "Telegram bus follower target provisioning failed.",
+            };
+          }
+          },
+        );
+      }
+      case "follower.disconnect": {
+        const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
+        return runFollowerMutation(
+          getFollowerMutationKey(
+            registeredFollower ?? { instanceId: envelope.instanceId },
+          ),
+          async () => {
+          const follower = deps.followerRegistry.get(envelope.instanceId);
+          if (!follower) {
+            return {
+              kind: "bus.ack" as const,
+              requestId: envelope.requestId,
+              ok: false,
+              message: "Unknown Telegram bus follower instance.",
+            };
           }
-          const target = await deps.provisionFollowerTarget?.(
-            envelope.registration,
-          );
           if (
-            deps.getCurrentLeaderEpoch &&
-            deps.getCurrentLeaderEpoch() !== leaderEpoch
+            !follower.registrationGeneration ||
+            !envelope.registrationGeneration ||
+            envelope.registrationGeneration !== follower.registrationGeneration
           ) {
-            throw new Error(
-              "Telegram follower registration lost leader ownership.",
-            );
+            return {
+              kind: "bus.ack" as const,
+              requestId: envelope.requestId,
+              ok: false,
+              message: "Stale Telegram bus follower registration generation.",
+            };
           }
-          const registeredTarget = target ?? envelope.registration.target;
-          deps.followerRegistry.register({
-            ...envelope.registration,
-            connectedAtMs: getNowMs(),
-            target: registeredTarget,
-          });
+          await deps.onFollowerDisconnected?.(follower);
+          const current = deps.followerRegistry.get(follower.instanceId);
+          if (
+            current?.registrationGeneration !== follower.registrationGeneration
+          ) {
+            return {
+              kind: "bus.ack" as const,
+              requestId: envelope.requestId,
+              ok: false,
+              message: "Stale Telegram bus follower registration generation.",
+            };
+          }
+          deps.followerRegistry.remove(follower.instanceId);
           return {
-            kind: "bus.ack",
+            kind: "bus.ack" as const,
             requestId: envelope.requestId,
             ok: true,
-            ...(registeredTarget ? { result: registeredTarget } : {}),
-          };
-        } catch (error) {
-          return {
-            kind: "bus.ack",
-            requestId: envelope.requestId,
-            ok: false,
-            message:
-              error instanceof Error
-                ? error.message
-                : "Telegram bus follower target provisioning failed.",
           };
-        }
+          },
+        );
       }
       case "follower.heartbeat": {
         const current = deps.followerRegistry.get(envelope.instanceId);
@@ -1003,7 +1105,20 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
           getNowMs(),
         );
         return follower
-          ? { kind: "bus.ack", requestId: envelope.requestId, ok: true }
+          ? {
+              kind: "bus.ack",
+              requestId: envelope.requestId,
+              ok: true,
+              result: {
+                eligibleElectionSlots: deps.followerRegistry
+                  .list()
+                  .map((candidate) => candidate.slot)
+                  .filter((slot): slot is string =>
+                    typeof slot === "string" && /^[A-Z]$/.test(slot),
+                  )
+                  .sort(),
+              },
+            }
           : {
               kind: "bus.ack",
               requestId: envelope.requestId,
@@ -1253,32 +1368,12 @@ export function createTelegramBusLeaderRuntime<TContext>(
   const getNowMs = deps.getNowMs ?? Date.now;
   const followerPruneIntervalMs = deps.followerPruneIntervalMs ?? 1000;
   const followerStaleAfterMs = deps.followerStaleAfterMs ?? 5000;
-  const followerRecoveryGraceMs = deps.followerRecoveryGraceMs ?? 5000;
   let pruneInterval: ReturnType<typeof setInterval> | undefined;
-  let followerRealityTimer: ReturnType<typeof setTimeout> | undefined;
   const stopPruning = () => {
     if (!pruneInterval) return;
     clearInterval(pruneInterval);
     pruneInterval = undefined;
   };
-  const stopFollowerRealityTimer = () => {
-    if (!followerRealityTimer) return;
-    clearTimeout(followerRealityTimer);
-    followerRealityTimer = undefined;
-  };
-  const scheduleFollowerBindingReality = () => {
-    stopFollowerRealityTimer();
-    if (!deps.reconcileFollowerBindings) return;
-    followerRealityTimer = setTimeout(() => {
-      followerRealityTimer = undefined;
-      void Promise.resolve(deps.reconcileFollowerBindings?.()).catch((error) =>
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-binding-reality",
-        }),
-      );
-    }, followerRecoveryGraceMs);
-    followerRealityTimer.unref?.();
-  };
   const pruneFollowers = async () => {
     try {
       await localServer.ensureEndpoint();
@@ -1292,18 +1387,14 @@ export function createTelegramBusLeaderRuntime<TContext>(
       followerStaleAfterMs,
     );
     for (const follower of removed) {
-      try {
-        await deps.onFollowerPruned?.(follower);
-      } catch (error) {
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-prune-offline",
+      deps.recordRuntimeEvent?.(
+        "bus",
+        "Telegram bus follower heartbeat stale; preserving thread binding",
+        {
+          phase: "follower-pruned",
           instanceId: follower.instanceId,
-        });
-      }
-      deps.recordRuntimeEvent?.("bus", "Telegram bus follower timed out", {
-        phase: "follower-prune",
-        instanceId: follower.instanceId,
-      });
+        },
+      );
     }
   };
   const startPruning = () => {
@@ -1330,27 +1421,25 @@ export function createTelegramBusLeaderRuntime<TContext>(
       authorizeFollowerApiCall: deps.authorizeFollowerApiCall,
       recordFollowerMessageOwnership: deps.recordFollowerMessageOwnership,
       provisionFollowerTarget: deps.provisionFollowerTarget,
+      onFollowerDisconnected: deps.onFollowerDisconnected,
       getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
     }),
   });
   return {
     startPolling: async (ctx) => {
       await localServer.start();
-      scheduleFollowerBindingReality();
       startPruning();
       try {
         await deps.provisionLeaderTarget?.(ctx);
         await deps.startPolling(ctx);
       } catch (error) {
         stopPruning();
-        stopFollowerRealityTimer();
         await localServer.stop();
         throw error;
       }
     },
     stopPolling: async () => {
       stopPruning();
-      stopFollowerRealityTimer();
       try {
         await deps.stopPolling();
       } finally {