@llblab/pi-telegram 0.21.1 → 0.22.1

package/lib/bus-follower.ts

@@ -10,10 +10,17 @@ import { basename } from "node:path";
 
 import * as Sync from "./sync.ts";
 import * as Threads from "./threads.ts";
-import type { TelegramLockState } from "./locks.ts";
+import type { TelegramLockEntry, TelegramLockState } from "./locks.ts";
 import type { TelegramTarget } from "./target.ts";
 import {
+  isTelegramApiMethodRetrySafe,
+  TelegramApiCommitUnknownError,
+} from "./telegram-api.ts";
+import {
+  createTelegramBusFollowerTargetController,
+  createTelegramBusForeignOwnedUpdateForwarder,
   createTelegramBusLocalServer,
+  createTelegramBusRequestIdFactory,
   createUnauthorizedBusAck,
   getTelegramBusSocketPath,
   resolveTelegramBusSocketPath,
@@ -46,8 +53,7 @@ export interface TelegramFollowerSessionHandoff {
 }
 
 export function getTelegramFollowerSessionHandoff():
-  | TelegramFollowerSessionHandoff
-  | undefined {
+  TelegramFollowerSessionHandoff | undefined {
   const value = (globalThis as Record<string, unknown>)[
     TELEGRAM_FOLLOWER_SESSION_HANDOFF_KEY
   ];
@@ -118,6 +124,7 @@ export interface TelegramBusFollowerSessionRefreshHookDeps<TContext> {
     "registerWithLeader" | "setContext"
   >;
   getLeaderState: () => TelegramLockState;
+  isSessionActive?: (ctx: TContext) => boolean;
   updateStatus: (ctx: TContext) => void;
   recordRuntimeEvent: (
     category: string,
@@ -131,10 +138,11 @@ export interface TelegramBusFollowerRegistrationState {
   getTarget: () => TelegramTarget | undefined;
   getSlot: () => string | undefined;
   getThreadName: () => string | undefined;
+  getGeneration: () => string | undefined;
   setRegistered: (
     registered: boolean,
     target?: TelegramTarget,
-    metadata?: { slot?: string; threadName?: string },
+    metadata?: { slot?: string; threadName?: string; generation?: string },
   ) => void;
 }
 
@@ -143,11 +151,21 @@ export interface TelegramBusForwardedUpdateReceiverRuntime {
   stop: () => Promise<void>;
 }
 
+export interface TelegramBusFollowerClientRuntimeDeps {
+  socketPath: TelegramBusSocketPathSource;
+  instanceId: string;
+  getApiAuthSecret?: () => string | undefined;
+  getForwardingAuthSecret?: () => string | undefined;
+  getRegistrationGeneration?: () => string | undefined;
+  timeoutMs?: number;
+}
+
 export interface TelegramBusFollowerApiCallerDeps {
   socketPath: TelegramBusSocketPathSource;
   instanceId: string;
   createRequestId: () => string;
   getAuthSecret?: () => string | undefined;
+  getRegistrationGeneration?: () => string | undefined;
   getNowMs?: () => number;
   timeoutMs?: number;
 }
@@ -165,6 +183,7 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<
   startReceiving?: () => Promise<void>;
   stopReceiving?: () => Promise<void> | void;
   registrationState?: TelegramBusFollowerRegistrationState;
+  isContextActive?: (ctx: TContext) => boolean;
   getProfileKey?: (ctx: TContext) => string | undefined;
   getThreadName?: (ctx: TContext) => string | undefined;
   getNowMs?: () => number;
@@ -194,10 +213,15 @@ export function createTelegramManualFollowerProfileKeyResolver(input: {
     });
 }
 
+export interface TelegramBusFollowerElection {
+  expectedOwner?: TelegramLockEntry;
+}
+
 export type TelegramBusFollowerPromotionHandler<TContext> = (
   ctx: TContext,
   binding: TelegramBusFollowerPromotedBinding,
-) => Promise<void>;
+  election: TelegramBusFollowerElection,
+) => Promise<boolean>;
 
 export function createTelegramBusFollowerPromotionHandler<
   TContext extends { cwd: string },
@@ -205,38 +229,43 @@ export function createTelegramBusFollowerPromotionHandler<
   topicTargetStore: Threads.TelegramTopicTargetStore;
   instanceId: string;
   getActiveProfileName: () => string | undefined;
-  startLeader: (ctx: TContext) => Promise<unknown> | unknown;
+  startLeader: (
+    ctx: TContext,
+    election: TelegramBusFollowerElection,
+    onAcquired: () => Promise<void>,
+  ) => Promise<boolean>;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
     details?: Record<string, unknown>,
   ) => void;
 }): TelegramBusFollowerPromotionHandler<TContext> {
-  return async (ctx, binding) => {
-    const promotedRecord = await Threads.promoteTelegramFollowerBindingToLeader({
-      store: input.topicTargetStore,
-      instanceId: input.instanceId,
-      cwd: ctx.cwd,
-      telegramProfile: input.getActiveProfileName(),
-      target: binding.target,
-      slot: binding.slot,
-      threadName: binding.threadName,
+  return async (ctx, binding, election) =>
+    input.startLeader(ctx, election, async () => {
+      const promotedRecord =
+        await Threads.promoteTelegramFollowerBindingToLeader({
+          store: input.topicTargetStore,
+          instanceId: input.instanceId,
+          cwd: ctx.cwd,
+          telegramProfile: input.getActiveProfileName(),
+          target: binding.target,
+          slot: binding.slot,
+          threadName: binding.threadName,
+        });
+      if (promotedRecord) {
+        input.recordRuntimeEvent(
+          "bus",
+          "Follower thread binding promoted to leader",
+          {
+            phase: "follower-promoted-binding",
+            chatId: promotedRecord.target.chatId,
+            threadId: promotedRecord.target.threadId,
+            slot: promotedRecord.slot,
+            threadName: promotedRecord.threadName,
+          },
+        );
+      }
     });
-    if (promotedRecord) {
-      input.recordRuntimeEvent(
-        "bus",
-        "Follower thread binding promoted to leader",
-        {
-          phase: "follower-promoted-binding",
-          chatId: promotedRecord.target.chatId,
-          threadId: promotedRecord.target.threadId,
-          slot: promotedRecord.slot,
-          threadName: promotedRecord.threadName,
-        },
-      );
-    }
-    await input.startLeader(ctx);
-  };
 }
 
 export interface TelegramBusFollowerTargetReplacementHandlerDeps<TContext> {
@@ -247,7 +276,8 @@ export interface TelegramBusFollowerTargetReplacementHandlerDeps<TContext> {
   registrationState: Pick<
     TelegramBusFollowerRegistrationState,
     "getTarget" | "setRegistered"
-  >;
+  > &
+    Partial<Pick<TelegramBusFollowerRegistrationState, "getGeneration">>;
   instanceId: string;
   getManualFollowerProfileKey: () => string;
   manualFollowerOwnerId: string;
@@ -268,10 +298,7 @@ export type TelegramBusFollowerLeaderState =
   | { kind: "active-elsewhere"; lock: TelegramBusFollowerLeaderLock }
   | { kind: "stale"; lock: TelegramBusFollowerLeaderLock };
 
-export interface TelegramBusFollowerLeaderLock {
-  busSocketPath?: string;
-  busSecret?: string;
-}
+export type TelegramBusFollowerLeaderLock = TelegramLockEntry;
 
 export interface TelegramBusFollowerPromotedBinding {
   target?: TelegramTarget;
@@ -291,9 +318,12 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
   promoteToLeader: (
     ctx: TContext,
     binding: TelegramBusFollowerPromotedBinding,
-  ) => Promise<void> | void;
-  sleep: (ms: number) => Promise<void>;
-  promotionGraceMs: number;
+    election: TelegramBusFollowerElection,
+  ) => Promise<boolean>;
+  sleep?: (ms: number) => Promise<void>;
+  scheduleRetry?: (retry: () => void, delayMs: number) => void;
+  getActiveContext?: () => TContext | undefined;
+  promotionGraceMs?: number;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
@@ -310,6 +340,7 @@ export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<
   socketPath: TelegramBusSocketPathSource;
   instanceId: string;
   getAuthSecret?: () => string | undefined;
+  getRegistrationGeneration?: () => string | undefined;
   getContext: () => TContext | undefined;
   handleForwardedCallback: (
     query: TCallbackQuery,
@@ -373,6 +404,47 @@ export interface TelegramBusFollowerRuntimeAssembly<TContext> {
   registration: TelegramBusFollowerRegistrationRuntime<TContext>;
 }
 
+export function createTelegramBusForwardedRouteHandlers<
+  TContext,
+  TReactionUpdate,
+  TCallbackQuery,
+  TMessage,
+>(route: {
+  handleUpdate(
+    update: {
+      callback_query?: TCallbackQuery;
+      message?: TMessage;
+      edited_message?: TMessage;
+    },
+    ctx: TContext,
+  ): Promise<void> | void;
+  handleAuthorizedReactionUpdate(
+    reactionUpdate: TReactionUpdate,
+    ctx: TContext,
+  ): Promise<void> | void;
+}): Pick<
+  TelegramBusForwardedUpdateReceiverRuntimeDeps<
+    TContext,
+    TReactionUpdate,
+    TCallbackQuery,
+    TMessage
+  >,
+  | "handleForwardedCallback"
+  | "handleForwardedReaction"
+  | "handleForwardedMessage"
+  | "handleForwardedEditedMessage"
+> {
+  return {
+    handleForwardedCallback: (query, ctx) =>
+      route.handleUpdate({ callback_query: query }, ctx),
+    handleForwardedReaction: route.handleAuthorizedReactionUpdate,
+    handleForwardedMessage: (message, ctx) =>
+      route.handleUpdate({ message }, ctx),
+    handleForwardedEditedMessage: (message, ctx) =>
+      route.handleUpdate({ edited_message: message }, ctx),
+  };
+}
+
 export function createTelegramBusFollowerRuntimeAssembly<
   TContext extends { cwd?: string },
   TReactionUpdate,
@@ -388,10 +460,11 @@ export function createTelegramBusFollowerRuntimeAssembly<
 ): TelegramBusFollowerRuntimeAssembly<TContext> {
   const receiver = createTelegramBusForwardedUpdateReceiverRuntime({
     ...deps.receiver,
-    handleReplaceTarget:
-      createTelegramBusFollowerTargetReplacementHandler(
-        deps.targetReplacement,
-      ),
+    getRegistrationGeneration:
+      deps.targetReplacement.registrationState.getGeneration,
+    handleReplaceTarget: createTelegramBusFollowerTargetReplacementHandler(
+      deps.targetReplacement,
+    ),
   });
   let registration: TelegramBusFollowerRegistrationRuntime<TContext>;
   const recovery = createTelegramBusFollowerHeartbeatRecoveryHandler({
@@ -458,7 +531,11 @@ export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
       threadName: currentRecord?.threadName,
       rerouteConfirmedAtMs: nowMs,
     });
-    deps.registrationState.setRegistered(true, input.target);
+    deps.registrationState.setRegistered(true, input.target, {
+      slot: currentRecord?.slot,
+      threadName: currentRecord?.threadName,
+      generation: deps.registrationState.getGeneration?.(),
+    });
     deps.setSyncState(
       Sync.markTelegramSyncSliceFresh(deps.getSyncState(), "target-bindings", {
         nowMs,
@@ -482,6 +559,42 @@ export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
   };
 }
 
+export function createTelegramBusFollowerClientRuntime<
+  TContext,
+  TReactionUpdate,
+  TCallbackQuery,
+  TMessage = unknown,
+>(deps: TelegramBusFollowerClientRuntimeDeps) {
+  const createRequestId = createTelegramBusRequestIdFactory(deps.instanceId);
+  const sharedClientDeps = {
+    socketPath: deps.socketPath,
+    createRequestId,
+    timeoutMs: deps.timeoutMs,
+  };
+  return {
+    createRequestId,
+    callApi: createTelegramBusFollowerApiCaller({
+      ...sharedClientDeps,
+      instanceId: deps.instanceId,
+      getAuthSecret: deps.getApiAuthSecret,
+      getRegistrationGeneration: deps.getRegistrationGeneration,
+    }),
+    foreignOwnedUpdateForwarder: createTelegramBusForeignOwnedUpdateForwarder<
+      TContext,
+      TReactionUpdate,
+      TCallbackQuery,
+      TMessage
+    >({
+      ...sharedClientDeps,
+      getAuthSecret: deps.getForwardingAuthSecret,
+    }),
+    targetController: createTelegramBusFollowerTargetController({
+      ...sharedClientDeps,
+      getAuthSecret: deps.getForwardingAuthSecret,
+    }),
+  };
+}
+
 export function createTelegramBusFollowerApiCaller(
   deps: TelegramBusFollowerApiCallerDeps,
 ): (method: string, args: unknown[]) => Promise<unknown> {
@@ -489,28 +602,55 @@ export function createTelegramBusFollowerApiCaller(
   const timeoutMs = deps.timeoutMs ?? 30000;
   return async (method, args) => {
     const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
-    const response = await sendTelegramBusLocalEnvelope({
-      socketPath,
-      timeoutMs,
-      retry: getTelegramBusTransportRetryPolicy({
-        endpoint: socketPath,
-        operation: "operation",
-      }),
-      envelope: {
-        kind: "follower.callApi",
-        requestId: deps.createRequestId(),
-        auth: deps.getAuthSecret?.(),
-        instanceId: deps.instanceId,
-        method,
-        args,
-        sentAtMs: getNowMs(),
-      },
-    });
+    let response: TelegramBusEnvelope | undefined;
+    try {
+      response = await sendTelegramBusLocalEnvelope({
+        socketPath,
+        timeoutMs,
+        retry: getTelegramBusTransportRetryPolicy({
+          endpoint: socketPath,
+          operation: "operation",
+        }),
+        envelope: {
+          kind: "follower.callApi",
+          requestId: deps.createRequestId(),
+          auth: deps.getAuthSecret?.(),
+          instanceId: deps.instanceId,
+          ...(deps.getRegistrationGeneration?.()
+            ? {
+                registrationGeneration: deps.getRegistrationGeneration?.(),
+              }
+            : {}),
+          method,
+          args,
+          sentAtMs: getNowMs(),
+        },
+      });
+    } catch (error) {
+      const apiMethod =
+        (method === "call" || method === "callMultipart") &&
+        typeof args[0] === "string"
+          ? args[0]
+          : method;
+      if (!isTelegramApiMethodRetrySafe(apiMethod)) {
+        throw new TelegramApiCommitUnknownError(apiMethod, error);
+      }
+      throw error;
+    }
     if (response?.kind === "bus.ack" && response.ok) return response.result;
     const message =
       response?.kind === "bus.ack"
         ? response.message
         : "Telegram bus API call did not return an acknowledgement.";
+    if (
+      response?.kind === "bus.ack" &&
+      response.error?.code === "commit-unknown"
+    ) {
+      throw new TelegramApiCommitUnknownError(
+        response.error.method ?? method,
+        new Error(message ?? "Telegram bus API call result is ambiguous."),
+      );
+    }
     throw new Error(message ?? "Telegram bus API call failed.");
   };
 }
@@ -558,6 +698,7 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
   deps: TelegramBusFollowerSessionRefreshHookDeps<TContext>,
 ): (_event: unknown, ctx: TContext) => Promise<void> {
   return async (_event, ctx) => {
+    if (deps.isSessionActive && !deps.isSessionActive(ctx)) return;
     if (!deps.registrationState.isRegistered()) {
       const handoff = getTelegramFollowerSessionHandoff();
       const lockState = deps.getLeaderState();
@@ -569,6 +710,7 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
             lockState.lock,
             { target: handoff.target },
           );
+          if (deps.isSessionActive && !deps.isSessionActive(ctx)) return;
           if (restored) {
             setTelegramFollowerSessionHandoff(undefined);
             deps.updateStatus(ctx);
@@ -592,6 +734,7 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
       }
     }
     if (!deps.registrationState.isRegistered()) return;
+    if (deps.isSessionActive && !deps.isSessionActive(ctx)) return;
     deps.registrationRuntime.setContext(ctx);
     deps.updateStatus(ctx);
     deps.recordRuntimeEvent(
@@ -607,16 +750,19 @@ export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowe
   let target: TelegramTarget | undefined;
   let slot: string | undefined;
   let threadName: string | undefined;
+  let generation: string | undefined;
   return {
     isRegistered: () => registered,
     getTarget: () => (target ? { ...target } : undefined),
     getSlot: () => slot,
     getThreadName: () => threadName,
+    getGeneration: () => generation,
     setRegistered: (next, nextTarget, metadata) => {
       registered = next;
       target = next ? (nextTarget ? { ...nextTarget } : undefined) : undefined;
       slot = next ? metadata?.slot : undefined;
       threadName = next ? metadata?.threadName : undefined;
+      generation = next ? metadata?.generation : undefined;
     },
   };
 }
@@ -624,6 +770,17 @@ export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowe
 export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
   deps: TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>,
 ): (error: unknown, ctx: TContext) => Promise<void> {
+  const promotionGraceMs =
+    deps.promotionGraceMs ?? TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS;
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const scheduleRetry =
+    deps.scheduleRetry ??
+    ((retry: () => void, delayMs: number) => {
+      const timer = setTimeout(retry, delayMs);
+      timer.unref?.();
+    });
   let promotionPending = false;
   const safeUpdateStatus = (ctx: TContext) => {
     try {
@@ -643,11 +800,16 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     ctx: TContext,
     leader: TelegramBusFollowerLeaderLock,
     phase: string,
+    binding?: TelegramBusFollowerPromotedBinding,
   ) => {
     try {
       const restored = await deps
         .getRegistrationRuntime()
-        .registerWithLeader(ctx, leader);
+        .registerWithLeader(
+          ctx,
+          leader,
+          binding?.target ? { target: binding.target } : undefined,
+        );
       if (!restored) return false;
       deps.setLifecyclePhase(undefined);
       safeUpdateStatus(ctx);
@@ -670,11 +832,34 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     slot: deps.registrationState.getSlot(),
     threadName: deps.registrationState.getThreadName(),
   });
+  const scheduleRecovery = (
+    reason: unknown,
+    fallbackCtx: TContext,
+    binding: TelegramBusFollowerPromotedBinding,
+  ) => {
+    const retry = () => {
+      const activeCtx = deps.getActiveContext
+        ? deps.getActiveContext()
+        : fallbackCtx;
+      if (!activeCtx) {
+        scheduleRetry(retry, promotionGraceMs);
+        return;
+      }
+      void recover(reason, activeCtx, binding);
+    };
+    scheduleRetry(retry, promotionGraceMs);
+  };
   const promoteToLeader = async (
     reason: unknown,
     ctx: TContext,
-    binding = snapshotBinding(),
+    binding: TelegramBusFollowerPromotedBinding,
+    election: TelegramBusFollowerElection,
   ) => {
+    const activeCtx = deps.getActiveContext?.();
+    if (deps.getActiveContext && activeCtx !== ctx) {
+      scheduleRecovery(reason, ctx, binding);
+      return;
+    }
     deps.setLifecyclePhase("electing");
     safeUpdateStatus(ctx);
     deps.recordRuntimeEvent("bus", reason, {
@@ -686,18 +871,31 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
     deps.recordRuntimeEvent("bus", "Telegram follower elected for promotion", {
       phase: "follower-promotion-electing",
     });
-    await deps.promoteToLeader(ctx, binding);
+    const promoted = await deps.promoteToLeader(ctx, binding, election);
     deps.setLifecyclePhase(undefined);
     safeUpdateStatus(ctx);
-    deps.recordRuntimeEvent("bus", "Telegram follower promotion completed", {
-      phase: "follower-promotion-complete",
-    });
+    deps.recordRuntimeEvent(
+      "bus",
+      promoted
+        ? "Telegram follower promotion completed"
+        : "Telegram follower promotion lost election",
+      {
+        phase: promoted
+          ? "follower-promotion-complete"
+          : "follower-promotion-lost",
+      },
+    );
+    if (!promoted) scheduleRecovery(reason, ctx, binding);
   };
-  return async (error, ctx) => {
+  const recover = async (
+    error: unknown,
+    ctx: TContext,
+    carriedBinding?: TelegramBusFollowerPromotedBinding,
+  ): Promise<void> => {
     if (promotionPending) return;
     promotionPending = true;
     try {
-      const initialBinding = snapshotBinding();
+      const initialBinding = carriedBinding ?? snapshotBinding();
       const state = deps.getLeaderState();
       if (state.kind === "active-elsewhere") {
         clearRegisteredState(ctx);
@@ -706,6 +904,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
             ctx,
             state.lock,
             "follower-register-restore",
+            initialBinding,
           )
         ) {
           return;
@@ -717,7 +916,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
           "Telegram follower waiting for leader reload recovery",
           { phase: "follower-promotion-grace" },
         );
-        await deps.sleep(deps.promotionGraceMs);
+        await sleep(promotionGraceMs);
         const graceState = deps.getLeaderState();
         if (graceState.kind === "active-elsewhere") {
           if (
@@ -725,20 +924,37 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
               ctx,
               graceState.lock,
               "follower-register-restore-grace",
+              initialBinding,
             )
           ) {
             return;
           }
-          await promoteToLeader(error, ctx, initialBinding);
+          deps.setLifecyclePhase(undefined);
+          safeUpdateStatus(ctx);
+          deps.recordRuntimeEvent(
+            "bus",
+            "Telegram follower promotion blocked by live leader lease",
+            {
+              phase: "follower-promotion-live-owner",
+              leaderInstanceId: graceState.lock.instanceId,
+              leaderEpoch: graceState.lock.leaderEpoch,
+            },
+          );
+          scheduleRecovery(error, ctx, initialBinding);
           return;
         }
         if (graceState.kind === "stale" || graceState.kind === "inactive") {
-          await promoteToLeader(error, ctx, initialBinding);
+          await promoteToLeader(error, ctx, initialBinding, {
+            expectedOwner:
+              graceState.kind === "stale" ? graceState.lock : undefined,
+          });
         }
         return;
       }
       if (state.kind === "stale" || state.kind === "inactive") {
-        await promoteToLeader(error, ctx, initialBinding);
+        await promoteToLeader(error, ctx, initialBinding, {
+          expectedOwner: state.kind === "stale" ? state.lock : undefined,
+        });
       }
     } catch (promotionError) {
       deps.setLifecyclePhase(undefined);
@@ -754,6 +970,7 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
       promotionPending = false;
     }
   };
+  return recover;
 }
 
 export function createTelegramBusFollowerRegistrationRuntime<
@@ -775,6 +992,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
   let heartbeatInterval: ReturnType<typeof setInterval> | undefined;
   let activeLeaderSocketPath: string | undefined;
   let activeAuthSecret: string | undefined;
+  let activeRegistrationGeneration: string | undefined;
   let activeContext: TContext | undefined;
   let lastKnownTarget: TelegramTarget | undefined;
   let lastKnownSlot: string | undefined;
@@ -787,6 +1005,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
   const stop = () => {
     stopHeartbeat();
     activeAuthSecret = undefined;
+    activeRegistrationGeneration = undefined;
     deps.setActiveAuthSecret?.(undefined);
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
@@ -810,6 +1029,9 @@ export function createTelegramBusFollowerRegistrationRuntime<
           requestId: deps.createRequestId(),
           auth: activeAuthSecret,
           instanceId: deps.instanceId,
+          ...(activeRegistrationGeneration
+            ? { registrationGeneration: activeRegistrationGeneration }
+            : {}),
           sentAtMs: getNowMs(),
         },
       });
@@ -840,12 +1062,13 @@ export function createTelegramBusFollowerRegistrationRuntime<
       await deps.startReceiving?.();
       activeAuthSecret = deps.getLeaderAuthSecret?.(leader);
       deps.setActiveAuthSecret?.(activeAuthSecret);
-      const createRegistrationEnvelope = (): Extract<
+      const registrationGeneration = deps.createRequestId();
+      const registrationEnvelope: Extract<
         TelegramBusEnvelope,
         { kind: "follower.register" }
-      > => ({
+      > = {
         kind: "follower.register",
-        requestId: deps.createRequestId(),
+        requestId: registrationGeneration,
         auth: activeAuthSecret,
         registration: {
           instanceId: deps.instanceId,
@@ -857,7 +1080,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
             lastKnownThreadName ??
             deps.getThreadName?.(ctx) ??
             (ctx.cwd ? basename(ctx.cwd) : undefined),
-          ...(deps.registrationState?.getSlot() ?? lastKnownSlot
+          ...((deps.registrationState?.getSlot() ?? lastKnownSlot)
             ? { slot: deps.registrationState?.getSlot() ?? lastKnownSlot }
             : {}),
           cwd: ctx.cwd,
@@ -868,15 +1091,16 @@ export function createTelegramBusFollowerRegistrationRuntime<
             lastKnownTarget,
           busSocketPath:
             deps.getFollowerBusSocketPath?.() ?? deps.followerBusSocketPath,
+          registrationGeneration,
           connectedAtMs: getNowMs(),
         },
-      });
+      };
       let response: TelegramBusEnvelope | undefined;
       try {
         response = await sendTelegramBusLocalEnvelope({
           socketPath: leaderSocketPath,
           timeoutMs: registrationTimeoutMs,
-          envelope: createRegistrationEnvelope(),
+          envelope: registrationEnvelope,
           retry: getTelegramBusTransportRetryPolicy({
             endpoint: leaderSocketPath,
             operation: "registration",
@@ -901,6 +1125,14 @@ export function createTelegramBusFollowerRegistrationRuntime<
         await deps.stopReceiving?.();
         throw error;
       }
+      if (deps.isContextActive && !deps.isContextActive(ctx)) {
+        stopHeartbeat();
+        activeLeaderSocketPath = undefined;
+        activeAuthSecret = undefined;
+        deps.setActiveAuthSecret?.(undefined);
+        await deps.stopReceiving?.();
+        return false;
+      }
       if (response?.kind === "bus.ack" && !response.ok) {
         stopHeartbeat();
         activeLeaderSocketPath = undefined;
@@ -915,15 +1147,15 @@ export function createTelegramBusFollowerRegistrationRuntime<
       }
       if (response?.kind === "bus.ack" && response.ok) {
         const registrationResult = parseRegistrationResult(response.result);
-        deps.registrationState?.setRegistered(
-          true,
-          registrationResult.target,
-          registrationResult,
-        );
+        deps.registrationState?.setRegistered(true, registrationResult.target, {
+          ...registrationResult,
+          generation: registrationGeneration,
+        });
         lastKnownTarget = registrationResult.target;
         lastKnownSlot = registrationResult.slot;
         lastKnownThreadName = registrationResult.threadName;
         activeLeaderSocketPath = leaderSocketPath;
+        activeRegistrationGeneration = registrationGeneration;
         activeContext = ctx;
         await sendHeartbeat();
         startHeartbeat(leaderSocketPath);
@@ -985,6 +1217,18 @@ export function createTelegramBusForwardedUpdateReceiverRuntime<
           message: "Telegram bus receiver cannot handle this envelope.",
         };
       }
+      const registrationGeneration = deps.getRegistrationGeneration?.();
+      if (
+        registrationGeneration &&
+        envelope.recipientRegistrationGeneration !== registrationGeneration
+      ) {
+        return {
+          kind: "bus.ack",
+          requestId: envelope.requestId,
+          ok: false,
+          message: "Stale Telegram bus follower registration generation.",
+        };
+      }
       const ctx = deps.getContext();
       if (!ctx) {
         return {