@llblab/pi-telegram 0.20.1 → 0.20.3

package/lib/bus-follower.ts

@@ -40,6 +40,9 @@ export interface TelegramFollowerSessionHandoff {
   pid: number;
   instanceId: string;
   createdAtMs: number;
+  target: TelegramTarget;
+  slot?: string;
+  threadName?: string;
 }
 
 export function getTelegramFollowerSessionHandoff():
@@ -53,7 +56,10 @@ export function getTelegramFollowerSessionHandoff():
   if (
     typeof handoff.pid !== "number" ||
     typeof handoff.instanceId !== "string" ||
-    typeof handoff.createdAtMs !== "number"
+    typeof handoff.createdAtMs !== "number" ||
+    !handoff.target ||
+    typeof handoff.target !== "object" ||
+    typeof handoff.target.chatId !== "number"
   ) {
     return undefined;
   }
@@ -83,16 +89,19 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
   registerWithLeader: (
     ctx: TContext,
     leader: { busSocketPath?: string; busSecret?: string },
+    options?: { target?: TelegramTarget },
   ) => Promise<boolean>;
   setContext: (ctx: TContext) => void;
   stop: () => void;
 }
 
 export interface TelegramBusFollowerSessionReplacementSuspenderDeps {
-  registrationState: Pick<TelegramBusFollowerRegistrationState, "isRegistered">;
+  registrationState: Pick<
+    TelegramBusFollowerRegistrationState,
+    "isRegistered" | "getTarget" | "getSlot" | "getThreadName"
+  >;
   instanceId: string;
   suspendPolling: () => Promise<void>;
-  onFollowerSessionDisconnect?: () => Promise<void> | void;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
@@ -173,6 +182,63 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<
   onHeartbeatFailure?: (error: unknown, ctx: TContext) => Promise<void> | void;
 }
 
+export function createTelegramManualFollowerProfileKeyResolver(input: {
+  getActiveProfileName: () => string | undefined;
+  manualFollowerOwnerId: string;
+}): () => string {
+  return () =>
+    Threads.getTelegramThreadOwnerKey({
+      kind: "manual-follower",
+      instanceId: input.manualFollowerOwnerId,
+      telegramProfile: input.getActiveProfileName(),
+    });
+}
+
+export type TelegramBusFollowerPromotionHandler<TContext> = (
+  ctx: TContext,
+  binding: TelegramBusFollowerPromotedBinding,
+) => Promise<void>;
+
+export function createTelegramBusFollowerPromotionHandler<
+  TContext extends { cwd: string },
+>(input: {
+  topicTargetStore: Threads.TelegramTopicTargetStore;
+  instanceId: string;
+  getActiveProfileName: () => string | undefined;
+  startLeader: (ctx: TContext) => Promise<unknown> | unknown;
+  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,
+    });
+    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> {
   topicTargetStore: Pick<
     Threads.TelegramTopicTargetStore,
@@ -183,7 +249,7 @@ export interface TelegramBusFollowerTargetReplacementHandlerDeps<TContext> {
     "getTarget" | "setRegistered"
   >;
   instanceId: string;
-  manualFollowerProfileKey: string;
+  getManualFollowerProfileKey: () => string;
   manualFollowerOwnerId: string;
   getSyncState: () => Sync.TelegramSyncState;
   setSyncState: (state: Sync.TelegramSyncState) => void;
@@ -276,6 +342,71 @@ export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<
   ) => void;
 }
 
+export interface TelegramBusFollowerRuntimeAssemblyDeps<
+  TContext extends { cwd?: string },
+  TReactionUpdate,
+  TCallbackQuery,
+  TMessage = unknown,
+> {
+  receiver: Omit<
+    TelegramBusForwardedUpdateReceiverRuntimeDeps<
+      TContext,
+      TReactionUpdate,
+      TCallbackQuery,
+      TMessage
+    >,
+    "handleReplaceTarget"
+  >;
+  targetReplacement: TelegramBusFollowerTargetReplacementHandlerDeps<TContext>;
+  recovery: Omit<
+    TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext>,
+    "getRegistrationRuntime"
+  >;
+  registration: Omit<
+    TelegramBusFollowerRegistrationRuntimeDeps<TContext>,
+    "startReceiving" | "stopReceiving" | "onHeartbeatFailure"
+  >;
+}
+
+export interface TelegramBusFollowerRuntimeAssembly<TContext> {
+  receiver: TelegramBusForwardedUpdateReceiverRuntime;
+  registration: TelegramBusFollowerRegistrationRuntime<TContext>;
+}
+
+export function createTelegramBusFollowerRuntimeAssembly<
+  TContext extends { cwd?: string },
+  TReactionUpdate,
+  TCallbackQuery,
+  TMessage = unknown,
+>(
+  deps: TelegramBusFollowerRuntimeAssemblyDeps<
+    TContext,
+    TReactionUpdate,
+    TCallbackQuery,
+    TMessage
+  >,
+): TelegramBusFollowerRuntimeAssembly<TContext> {
+  const receiver = createTelegramBusForwardedUpdateReceiverRuntime({
+    ...deps.receiver,
+    handleReplaceTarget:
+      createTelegramBusFollowerTargetReplacementHandler(
+        deps.targetReplacement,
+      ),
+  });
+  let registration: TelegramBusFollowerRegistrationRuntime<TContext>;
+  const recovery = createTelegramBusFollowerHeartbeatRecoveryHandler({
+    ...deps.recovery,
+    getRegistrationRuntime: () => registration,
+  });
+  registration = createTelegramBusFollowerRegistrationRuntime({
+    ...deps.registration,
+    startReceiving: receiver.start,
+    stopReceiving: receiver.stop,
+    onHeartbeatFailure: recovery,
+  });
+  return { receiver, registration };
+}
+
 export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
   deps: TelegramBusFollowerTargetReplacementHandlerDeps<TContext>,
 ): NonNullable<
@@ -308,7 +439,7 @@ export function createTelegramBusFollowerTargetReplacementHandler<TContext>(
       );
     }
     const profileKey =
-      currentRecord?.profileKey ?? deps.manualFollowerProfileKey;
+      currentRecord?.profileKey ?? deps.getManualFollowerProfileKey();
     deps.topicTargetStore.upsert({
       profileKey,
       owner: {
@@ -392,40 +523,30 @@ function isTelegramStaleContextError(error: unknown): boolean {
   );
 }
 
-export async function markTelegramFollowerThreadStaleForSessionDisconnect(input: {
-  topicTargetStore: Threads.TelegramTopicTargetStore;
-  target: TelegramTarget;
-}): Promise<void> {
-  await input.topicTargetStore.load();
-  const record = input.topicTargetStore.list().find(
-    (candidate) =>
-      candidate.target.chatId === input.target.chatId &&
-      candidate.target.threadId === input.target.threadId,
-  );
-  const marked = input.topicTargetStore.markStaleByTarget(
-    input.target,
-    "unknown",
-    "Follower session reloaded before reconnect.",
-  );
-  const forgotIdentity = record?.profileKey
-    ? input.topicTargetStore.forgetIdentityByProfileKey(record.profileKey)
-    : false;
-  if (marked || forgotIdentity) await input.topicTargetStore.persist();
-}
-
 export function createTelegramBusFollowerSessionReplacementSuspender(
   deps: TelegramBusFollowerSessionReplacementSuspenderDeps,
 ): () => Promise<void> {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const getPid = deps.getPid ?? (() => process.pid);
   return async () => {
-    if (deps.registrationState.isRegistered()) {
-      setTelegramFollowerSessionHandoff(undefined);
-      await deps.onFollowerSessionDisconnect?.();
+    const target = deps.registrationState.getTarget();
+    if (deps.registrationState.isRegistered() && target) {
+      setTelegramFollowerSessionHandoff({
+        pid: getPid(),
+        instanceId: deps.instanceId,
+        createdAtMs: getNowMs(),
+        target,
+        slot: deps.registrationState.getSlot(),
+        threadName: deps.registrationState.getThreadName(),
+      });
       deps.recordRuntimeEvent(
         "bus",
-        "Telegram follower registration stopped for session replacement",
+        "Telegram follower registration suspended for session replacement",
         {
-          phase: "follower-session-disconnect",
+          phase: "follower-session-handoff",
           instanceId: deps.instanceId,
+          chatId: target.chatId,
+          threadId: target.threadId,
         },
       );
     }
@@ -446,6 +567,7 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
           const restored = await deps.registrationRuntime.registerWithLeader(
             ctx,
             lockState.lock,
+            { target: handoff.target },
           );
           if (restored) {
             setTelegramFollowerSessionHandoff(undefined);
@@ -654,6 +776,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
   let activeLeaderSocketPath: string | undefined;
   let activeAuthSecret: string | undefined;
   let activeContext: TContext | undefined;
+  let lastKnownTarget: TelegramTarget | undefined;
   const stopHeartbeat = () => {
     if (!heartbeatInterval) return;
     clearInterval(heartbeatInterval);
@@ -664,6 +787,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
     activeAuthSecret = undefined;
     deps.setActiveAuthSecret?.(undefined);
     deps.registrationState?.setRegistered(false);
+    lastKnownTarget = undefined;
     activeContext = undefined;
     void deps.stopReceiving?.();
   };
@@ -704,7 +828,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
     heartbeatInterval.unref?.();
   };
   return {
-    registerWithLeader: async (ctx, leader) => {
+    registerWithLeader: async (ctx, leader, options) => {
       const leaderSocketPath =
         leader.busSocketPath ??
         deps.getLeaderSocketPath?.() ??
@@ -729,6 +853,10 @@ export function createTelegramBusFollowerRegistrationRuntime<
             (ctx.cwd ? basename(ctx.cwd) : undefined),
           cwd: ctx.cwd,
           pid: getPid(),
+          target:
+            options?.target ??
+            deps.registrationState?.getTarget() ??
+            lastKnownTarget,
           busSocketPath:
             deps.getFollowerBusSocketPath?.() ?? deps.followerBusSocketPath,
           connectedAtMs: getNowMs(),
@@ -783,6 +911,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
           registrationResult.target,
           registrationResult,
         );
+        lastKnownTarget = registrationResult.target;
         activeLeaderSocketPath = leaderSocketPath;
         activeContext = ctx;
         await sendHeartbeat();

package/lib/bus-leader.ts

@@ -154,15 +154,109 @@ export interface TelegramBusLeaderApiProxyDeps {
   ) => Promise<unknown> | unknown;
 }
 
-export interface TelegramBusFollowerRegistryRestoreDeps {
-  topicTargetStore: Pick<Threads.TelegramTopicTargetStore, "load" | "list">;
-  followerRegistry: TelegramBusFollowerRegistry;
+export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
+  runtime: Omit<
+    TelegramBusLeaderRuntimeDeps<TContext>,
+    | "callApi"
+    | "onFollowerPruned"
+    | "provisionFollowerTarget"
+    | "provisionLeaderTarget"
+    | "reconcileFollowerBindings"
+    | "recordRuntimeEvent"
+  >;
+  getAllowedUserId: () => number | undefined;
+  instanceId: string;
+  getCwd?: (ctx: TContext) => string | undefined;
+  getTelegramProfile?: () => string | undefined;
+  shouldForceFreshUnnamed?: () => boolean;
+  topicTargetStore: Threads.TelegramTopicTargetStore;
+  callApi: TelegramBusLeaderTargetProvisionerDeps<TContext>["callApi"];
+  callMultipart: TelegramBusLeaderApiProxyDeps["callMultipart"];
+  downloadFile: TelegramBusLeaderApiProxyDeps["downloadFile"];
+  recoverStaleTargetError?: TelegramBusLeaderApiProxyDeps["recoverStaleTargetError"];
+  getCurrentLeaderEpoch?: () => number | string | undefined;
+  getThreadReconciliationMachineState?: TelegramBusLeaderTargetProvisionerDeps<TContext>["getThreadReconciliationMachineState"];
+  recordThreadReconciliationPlan?: TelegramBusLeaderTargetProvisionerDeps<TContext>["recordThreadReconciliationPlan"];
+  getSyncState: () => Sync.TelegramSyncState;
+  setSyncState: (state: Sync.TelegramSyncState) => void;
+  setLeaderTarget: TelegramBusLeaderTargetProvisionerDeps<TContext>["setLeaderTarget"];
+  onProvisioningStart?: () => void;
+  onProvisioningEnd?: () => void;
+  recordRuntimeEvent: NonNullable<
+    TelegramBusLeaderRuntimeDeps<TContext>["recordRuntimeEvent"]
+  >;
+}
+
+export function createTelegramBusLeaderRuntimeAssembly<TContext>(
+  deps: TelegramBusLeaderRuntimeAssemblyDeps<TContext>,
+): TelegramBusLeaderRuntime<TContext> {
+  const provisionerPorts = {
+    getAllowedUserId: deps.getAllowedUserId,
+    topicTargetStore: deps.topicTargetStore,
+    callApi: deps.callApi,
+    getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
+    getSyncState: deps.getSyncState,
+    setSyncState: deps.setSyncState,
+    onProvisioningStart: deps.onProvisioningStart,
+    onProvisioningEnd: deps.onProvisioningEnd,
+    recordRuntimeEvent: deps.recordRuntimeEvent,
+  };
+  return createTelegramBusLeaderRuntime({
+    ...deps.runtime,
+    provisionLeaderTarget: createTelegramBusLeaderTargetProvisioner({
+      ...provisionerPorts,
+      instanceId: deps.instanceId,
+      getCwd: deps.getCwd,
+      getTelegramProfile: deps.getTelegramProfile,
+      shouldForceFreshUnnamed: deps.shouldForceFreshUnnamed,
+      getThreadReconciliationMachineState:
+        deps.getThreadReconciliationMachineState,
+      recordThreadReconciliationPlan: deps.recordThreadReconciliationPlan,
+      setLeaderTarget: deps.setLeaderTarget,
+    }),
+    onFollowerPruned: createTelegramBusFollowerPruneHandler({
+      ...provisionerPorts,
+    }),
+    provisionFollowerTarget: createTelegramBusFollowerTargetProvisioner({
+      ...provisionerPorts,
+    }),
+    reconcileFollowerBindings:
+      createTelegramBusFollowerBindingRealityReconciler({
+        topicTargetStore: deps.topicTargetStore,
+        followerRegistry: deps.runtime.followerRegistry,
+        recordRuntimeEvent: deps.recordRuntimeEvent,
+      }),
+    callApi: createTelegramBusLeaderApiProxy({
+      call: deps.callApi,
+      callMultipart: deps.callMultipart,
+      downloadFile: deps.downloadFile,
+      recoverStaleTargetError: deps.recoverStaleTargetError,
+    }),
+    recordRuntimeEvent: deps.recordRuntimeEvent,
+  });
+}
+
+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;
-  getNowMs?: () => number;
 }
 
 export interface TelegramBusFollowerMessageOwnershipRecord {
@@ -192,11 +286,12 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
-  restoreFollowerRegistry?: () => Promise<void> | void;
+  reconcileFollowerBindings?: () => Promise<unknown> | unknown;
   provisionLeaderTarget?: (ctx: TContext) => Promise<void> | void;
   getNowMs?: () => number;
   followerPruneIntervalMs?: number;
   followerStaleAfterMs?: number;
+  followerRecoveryGraceMs?: number;
   onFollowerPruned?: (
     follower: TelegramBusFollowerView,
   ) => Promise<void> | void;
@@ -207,39 +302,67 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   ) => void;
 }
 
-export function createTelegramBusFollowerRegistryRestoreHandler(
-  deps: TelegramBusFollowerRegistryRestoreDeps,
-): () => Promise<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 = (deps.getNowMs ?? Date.now)();
-    let restored = 0;
-    for (const record of deps.topicTargetStore.list()) {
-      if (record.owner?.kind !== "manual-follower") continue;
-      if (!record.instanceId) continue;
-      if (
-        record.status !== "active" &&
-        record.status !== "starting" &&
-        record.status !== "pending"
-      ) {
-        continue;
-      }
-      deps.followerRegistry.register({
-        instanceId: record.instanceId,
-        profileKey: record.profileKey,
-        threadName: record.threadName,
-        target: record.target,
-        busSocketPath: getTelegramBusFollowerSocketPath(record.instanceId),
-        connectedAtMs: nowMs,
-      });
-      restored += 1;
+    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);
     }
-    if (restored > 0) {
-      deps.recordRuntimeEvent("bus", "Telegram follower registry restored", {
-        phase: "follower-registry-restore",
-        followers: restored,
-      });
+    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;
   };
 }
 
@@ -341,6 +464,17 @@ 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 followerOwner =
       Threads.getTelegramThreadOwnerFromProfileKey(followerProfileKey);
     const registrationKey = followerProfileKey || registration.instanceId;
@@ -368,7 +502,28 @@ export function createTelegramBusFollowerTargetProvisioner(
     const runRegistration = async (): Promise<
       (TelegramTarget & { slot?: string; threadName?: string }) | undefined
     > => {
-    let result = await provisionTarget();
+    let result = reconnectRecord
+      ? { target: reconnectRecord.target, reused: true, record: reconnectRecord }
+      : await provisionTarget();
+    if (reconnectRecord) {
+      const nowMs = getNowMs();
+      const transferredRecord = deps.topicTargetStore.upsert({
+        ...reconnectRecord,
+        instanceId: registration.instanceId,
+        updatedAtMs: nowMs,
+        lastSyncObservedAtMs: nowMs,
+        lastReconcileAction:
+          reconnectRecord.instanceId === registration.instanceId
+            ? "follower-register-reuse"
+            : "follower-session-handoff",
+      });
+      await deps.topicTargetStore.persist();
+      result = {
+        target: transferredRecord.target,
+        reused: true,
+        record: transferredRecord,
+      };
+    }
     deps.setSyncState(
       Sync.markTelegramSyncSliceFresh(deps.getSyncState(), "target-bindings", {
         nowMs: getNowMs(),
@@ -944,12 +1099,32 @@ 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 () => {
     const removed = deps.followerRegistry.pruneStale(
       getNowMs(),
@@ -998,25 +1173,21 @@ export function createTelegramBusLeaderRuntime<TContext>(
   return {
     startPolling: async (ctx) => {
       await localServer.start();
-      try {
-        await deps.restoreFollowerRegistry?.();
-      } catch (error) {
-        deps.recordRuntimeEvent?.("bus", error, {
-          phase: "follower-registry-restore",
-        });
-      }
+      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 {

package/lib/bus.ts

@@ -34,6 +34,40 @@ import { resolveAgentDir } from "./paths.ts";
 
 export type TelegramBusRole = "leader" | "follower";
 
+export interface TelegramBusProcessRuntime {
+  instanceId: string;
+  manualFollowerOwnerId: string;
+  getLeaderSocketPath: () => string;
+  getFollowerSocketPath: () => string;
+}
+
+export function createTelegramBusProcessRuntime(input: {
+  getActiveProfileName: () => string | undefined;
+  pid: number;
+  parentPid: number;
+  createdAtMs: number;
+}): TelegramBusProcessRuntime {
+  const instanceId = `${input.pid}:${input.createdAtMs}`;
+  const manualFollowerOwnerId = String(input.parentPid || input.pid);
+  return {
+    instanceId,
+    manualFollowerOwnerId,
+    getLeaderSocketPath: () =>
+      getTelegramBusSocketPath(
+        undefined,
+        undefined,
+        input.getActiveProfileName(),
+      ),
+    getFollowerSocketPath: () =>
+      getTelegramBusFollowerSocketPath(
+        instanceId,
+        undefined,
+        undefined,
+        input.getActiveProfileName(),
+      ),
+  };
+}
+
 export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }

package/lib/paths.ts

@@ -71,6 +71,17 @@ export function resolveTelegramProfileTempFilePath(
   );
 }
 
+export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
+  state: string;
+  logs: string;
+} {
+  const suffix = getTelegramProfilePathSuffix(profileName);
+  return {
+    state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
+    logs: `~/.pi/agent/tmp/telegram/logs${suffix}.jsonl`,
+  };
+}
+
 /** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
 export function resolveTelegramRuntimeLogPath(): string {
   return resolveTelegramProfileTempFilePath("logs", "jsonl");