@llblab/pi-kit 0.23.2 → 0.24.1

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -48,6 +48,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
   TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
+  TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
 } from "./bus.ts";
 import type { TelegramConfigStore, TelegramThreadDisplayMode } from "./config.ts";
 import {
@@ -142,6 +143,11 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
     target: TelegramTarget & { threadId: number },
   ) => Promise<string>;
   setThreadDisplayMode?: (mode: TelegramThreadDisplayMode) => Promise<void>;
+  /** Leader-mediated durable publication or successor claim; true only after exact commit. */
+  requestSessionReplacement?: (
+    operation: "publish" | "settle",
+    intent: Threads.TelegramSessionReplacementIntent,
+  ) => Promise<boolean>;
   stop: () => void;
 }
 
@@ -1919,7 +1925,13 @@ export function createTelegramBusFollowerRegistrationRuntime<
         if (
           registrationOptions?.restoreWorkspace &&
           response.error?.code === "workspace-binding-unavailable"
-        ) return false;
+        ) {
+          deps.recordRuntimeEvent?.("bus", "Telegram follower auto-connect refused by leader: Workspace binding unavailable.", {
+            phase: "follower-auto-connect-skip",
+            reason: "leader-binding-unavailable",
+          });
+          return false;
+        }
         throw new Error(
           response.message ??
             "Telegram bus follower registration was rejected.",
@@ -2144,6 +2156,72 @@ export function createTelegramBusFollowerRegistrationRuntime<
       }
       return resetName;
     },
+    async requestSessionReplacement(operation, intent) {
+      if (!activeLeaderSocketPath || !activeRegistrationGeneration) {
+        throw new Error("Telegram follower is not registered with the leader.");
+      }
+      if (
+        !hasTelegramBusCapability(
+          deps.protocolIdentity,
+          TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
+        ) ||
+        !hasTelegramBusCapability(
+          deps.registrationState?.getLeaderProtocol(),
+          TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
+        )
+      ) {
+        throw new Error(
+          "The active Telegram leader does not support follower session replacement. Update or restart that Pi instance.",
+        );
+      }
+      const expectedLeaderSocketPath = activeLeaderSocketPath;
+      const expectedRegistrationGeneration = activeRegistrationGeneration;
+      const expectedAuthSecret = activeAuthSecret;
+      const requestId = deps.createRequestId();
+      const response = await sendTelegramBusLocalEnvelope({
+        socketPath: expectedLeaderSocketPath,
+        timeoutMs: registrationTimeoutMs,
+        retry: getTelegramBusTransportRetryPolicy({
+          endpoint: expectedLeaderSocketPath,
+          operation: "operation",
+        }),
+        envelope: {
+          kind: operation === "publish"
+            ? "follower.publishSessionReplacement"
+            : "follower.settleSessionReplacement",
+          requestId,
+          auth: expectedAuthSecret,
+          instanceId: deps.instanceId,
+          registrationGeneration: expectedRegistrationGeneration,
+          intent,
+          sentAtMs: getNowMs(),
+        },
+      });
+      if (
+        response?.kind !== "bus.ack" || !response.ok ||
+        response.requestId !== requestId ||
+        !isRecord(response.result) || response.result.committed !== true
+      ) {
+        throw new Error(
+          response?.kind === "bus.ack"
+            ? (response.message ?? "Telegram session replacement was rejected.")
+            : "Telegram session replacement was not acknowledged.",
+        );
+      }
+      if (
+        activeLeaderSocketPath !== expectedLeaderSocketPath ||
+        activeRegistrationGeneration !== expectedRegistrationGeneration ||
+        activeAuthSecret !== expectedAuthSecret ||
+        (deps.registrationState &&
+          deps.registrationState.getGeneration() !==
+            expectedRegistrationGeneration)
+      ) {
+        throw new Error(
+          "Telegram session replacement completed for a stale follower registration.",
+        );
+      }
+      return true;
+    },
     async disconnectFromLeader() {
       if (!activeLeaderSocketPath || !activeRegistrationGeneration) {
         return false;

package/node_modules/@llblab/pi-telegram/lib/bus-leader.ts

@@ -42,6 +42,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
   TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
+  TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
 } from "./bus.ts";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.ts";
 import type { TelegramQueueHandoffPayload } from "./queue.ts";
@@ -273,6 +274,110 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
   workspaceRotation?: TelegramWorkspaceSlotRotationPorts;
 }
 
+export type TelegramBusFollowerSessionReplacementOperation = (
+  follower: TelegramBusFollowerView,
+  intent: Threads.TelegramSessionReplacementIntent,
+  isCurrent: () => boolean,
+) => Promise<boolean>;
+
+/**
+ * Leader-owned durable session-replacement authority for registered followers.
+ * Followers cannot persist `state.json`; the leader validates the request
+ * against its live registry entry and authoritative Workspace binding before
+ * one CAS publication or claim. Follower memory is never accepted as binding
+ * evidence.
+ */
+export function createTelegramBusFollowerSessionReplacementAuthority(deps: {
+  store: Pick<
+    Threads.TelegramTopicTargetStore,
+    | "load"
+    | "getWorkspaceBindingByTarget"
+    | "getSessionReplacementIntent"
+    | "commitSessionReplacementIntent"
+    | "removeSessionReplacementIntent"
+  >;
+  getTelegramProfile?: () => string | undefined;
+  getNowMs?: () => number;
+  ttlMs?: number;
+}): {
+  publish: TelegramBusFollowerSessionReplacementOperation;
+  settle: TelegramBusFollowerSessionReplacementOperation;
+} {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const ttlMs = deps.ttlMs ?? Threads.TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS;
+  const assertCommon = (
+    follower: TelegramBusFollowerView,
+    intent: Threads.TelegramSessionReplacementIntent,
+  ): { cwd: string; sessionId: string } => {
+    const cwd = follower.cwd
+      ? Threads.normalizeTelegramWorkspacePath(follower.cwd)
+      : undefined;
+    const sessionId = follower.sessionId
+      ? Threads.normalizeTelegramSessionId(follower.sessionId)
+      : undefined;
+    const nowMs = getNowMs();
+    if (
+      intent.continuity !== "workspace-thread" ||
+      typeof intent.target.threadId !== "number" ||
+      follower.target?.chatId !== intent.target.chatId ||
+      follower.target.threadId !== intent.target.threadId ||
+      !cwd || cwd !== intent.cwd || !sessionId ||
+      intent.profileName !== (deps.getTelegramProfile?.() ?? "default")
+    ) {
+      throw new Error(
+        "Telegram session replacement does not match the current follower registration.",
+      );
+    }
+    if (intent.expiresAtMs <= nowMs || intent.expiresAtMs > nowMs + ttlMs) {
+      throw new Error("Telegram session replacement intent is expired or unbounded.");
+    }
+    return { cwd, sessionId };
+  };
+  return {
+    async publish(follower, intent, isCurrent) {
+      const { sessionId } = assertCommon(follower, intent);
+      if (intent.sourceInstanceId !== follower.instanceId ||
+          intent.sourceSessionId !== sessionId) {
+        throw new Error(
+          "Telegram session replacement source does not match the current follower registration.",
+        );
+      }
+      await deps.store.load();
+      if (!isCurrent()) return false;
+      const binding = deps.store.getWorkspaceBindingByTarget(intent.target);
+      if (
+        !binding || binding.cwd !== intent.cwd ||
+        binding.sessionId !== intent.sourceSessionId ||
+        binding.slot !== intent.slot ||
+        (binding.manualThreadName ?? binding.threadName) !== intent.threadName
+      ) {
+        throw new Error("Telegram session replacement binding is unavailable.");
+      }
+      return deps.store.commitSessionReplacementIntent(intent, isCurrent);
+    },
+    async settle(follower, intent, isCurrent) {
+      const { sessionId } = assertCommon(follower, intent);
+      if (
+        !intent.sourceInstanceId ||
+        (intent.sourceInstanceId !== follower.instanceId &&
+          intent.sourceInstanceId !== follower.previousInstanceId) ||
+        intent.sourceSessionId === sessionId
+      ) {
+        throw new Error(
+          "Telegram session replacement successor does not match the current follower registration.",
+        );
+      }
+      await deps.store.load();
+      if (!isCurrent()) return false;
+      if (deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd !==
+          intent.cwd) {
+        throw new Error("Telegram session replacement successor binding is unavailable.");
+      }
+      return deps.store.removeSessionReplacementIntent(intent, isCurrent);
+    },
+  };
+}
+
 export function createTelegramBusLeaderRuntimeAssembly<TContext>(
   deps: TelegramBusLeaderRuntimeAssemblyDeps<TContext>,
 ): TelegramBusLeaderRuntime<TContext> & {
@@ -624,6 +729,12 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
   }
 });
   });
+  const followerSessionReplacement =
+    createTelegramBusFollowerSessionReplacementAuthority({
+      store: deps.topicTargetStore,
+      getTelegramProfile: deps.getTelegramProfile,
+      getNowMs: deps.runtime.getNowMs,
+    });
   const runtime = createTelegramBusLeaderRuntime({
     ...deps.runtime,
     applyThreadDisplayMode,
@@ -750,6 +861,18 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         });
       },
     ),
+    publishFollowerSessionReplacement: (follower, intent, isCurrent) =>
+      runWorkspaceOperation({
+        operationId: createTelegramWorkspaceAdmissionOperationId(),
+        operationKind: "workspace.publish-follower-session-replacement",
+        scopes: [{ kind: "profile" }],
+      }, () => followerSessionReplacement.publish(follower, intent, isCurrent)),
+    settleFollowerSessionReplacement: (follower, intent, isCurrent) =>
+      runWorkspaceOperation({
+        operationId: createTelegramWorkspaceAdmissionOperationId(),
+        operationKind: "workspace.settle-follower-session-replacement",
+        scopes: [{ kind: "profile" }],
+      }, () => followerSessionReplacement.settle(follower, intent, isCurrent)),
     onFollowerConfirmedDead: async (follower) => {
       await runWorkspaceOperation(
         {
@@ -899,6 +1022,8 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
   resetFollowerThreadName?: (
     follower: TelegramBusFollowerView,
   ) => Promise<{ threadName: string }> | { threadName: string };
+  publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+  settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
   getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
   onFollowerRegistered?: () => void;
   applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
@@ -1923,6 +2048,8 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   resetFollowerThreadName?: (
     follower: TelegramBusFollowerView,
   ) => Promise<{ threadName: string }> | { threadName: string };
+  publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+  settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
   getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
   onFollowerRegistered?: () => void;
   applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
@@ -2547,6 +2674,74 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
           },
         );
       }
+      case "follower.publishSessionReplacement":
+      case "follower.settleSessionReplacement": {
+        const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
+        return runFollowerMutation(
+          registeredFollower ?? { instanceId: envelope.instanceId },
+          async () => {
+            const publish = envelope.kind === "follower.publishSessionReplacement";
+            const operation = publish
+              ? deps.publishFollowerSessionReplacement
+              : deps.settleFollowerSessionReplacement;
+            const epoch = deps.getCurrentLeaderEpoch?.();
+            const follower = deps.followerRegistry.get(envelope.instanceId);
+            const isCurrent = () => epoch !== undefined &&
+              deps.getCurrentLeaderEpoch?.() === epoch &&
+              deps.followerRegistry.get(envelope.instanceId)?.registrationGeneration ===
+                envelope.registrationGeneration;
+            if (
+              !follower?.registrationGeneration ||
+              follower.registrationGeneration !== envelope.registrationGeneration ||
+              !isCurrent() || !operation ||
+              !hasTelegramBusCapability(
+                deps.protocolIdentity,
+                TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
+              ) ||
+              !hasTelegramBusCapability(
+                follower.protocol,
+                TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
+              )
+            ) {
+              return {
+                kind: "bus.ack" as const,
+                requestId: envelope.requestId,
+                ok: false,
+                message:
+                  "Telegram session replacement requires current follower registration and compatible leader authority.",
+              };
+            }
+            try {
+              const committed = await operation(follower, envelope.intent, isCurrent);
+              if (!committed || !isCurrent()) {
+                return {
+                  kind: "bus.ack" as const,
+                  requestId: envelope.requestId,
+                  ok: false,
+                  message: publish
+                    ? "Telegram session replacement intent was not persisted."
+                    : "Telegram session replacement intent was not claimed.",
+                };
+              }
+              return {
+                kind: "bus.ack" as const,
+                requestId: envelope.requestId,
+                ok: true,
+                result: { committed: true },
+              };
+            } catch (error) {
+              return {
+                kind: "bus.ack" as const,
+                requestId: envelope.requestId,
+                ok: false,
+                message: error instanceof Error
+                  ? error.message
+                  : "Telegram session replacement request failed.",
+              };
+            }
+          },
+        );
+      }
       case "follower.disconnect": {
         const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
         return runFollowerMutation(
@@ -3118,6 +3313,8 @@ export function createTelegramBusLeaderRuntime<TContext>(
     onFollowerDisconnected: deps.onFollowerDisconnected,
     renameFollowerThread: deps.renameFollowerThread,
     resetFollowerThreadName: deps.resetFollowerThreadName,
+    publishFollowerSessionReplacement: deps.publishFollowerSessionReplacement,
+    settleFollowerSessionReplacement: deps.settleFollowerSessionReplacement,
     getFollowerDisplayTitle: deps.getFollowerDisplayTitle,
     onFollowerRegistered: deps.onFollowerRegistered,
     applyThreadDisplayMode: deps.applyThreadDisplayMode,

package/node_modules/@llblab/pi-telegram/lib/bus.ts

@@ -52,6 +52,10 @@ import type { TelegramTarget } from "./target.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
 import { isProcessAlive } from "./locks.ts";
 import { resolveAgentDir } from "./paths.ts";
+import {
+  normalizeTelegramSessionReplacementIntent,
+  type TelegramSessionReplacementIntent,
+} from "./threads.ts";
 
 export interface TelegramBusProcessRuntime {
   instanceId: string;
@@ -234,6 +238,8 @@ export const TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT =
   "directory-display-format-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT =
   "workspace-follower-auto-connect-v1" as const;
+export const TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT =
+  "session-replacement-intent-v1" as const;
 
 export interface TelegramBusProtocolIdentity {
   protocolVersion: number;
@@ -816,6 +822,16 @@ export type TelegramBusEnvelope = (
       target: TelegramTarget & { threadId: number };
       sentAtMs: number;
     }
+  | {
+      kind:
+        | "follower.publishSessionReplacement"
+        | "follower.settleSessionReplacement";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration: string;
+      intent: TelegramSessionReplacementIntent;
+      sentAtMs: number;
+    }
   | {
       kind: "leader.forwardCallback";
       requestId: string;
@@ -1055,6 +1071,23 @@ export function parseTelegramBusEnvelope(
       }
       break;
     }
+    case "follower.publishSessionReplacement":
+    case "follower.settleSessionReplacement": {
+      const intent = normalizeTelegramSessionReplacementIntent(value.intent);
+      if (typeof value.instanceId === "string" &&
+          typeof value.registrationGeneration === "string" &&
+          typeof value.sentAtMs === "number" && intent) {
+        envelope = {
+          kind,
+          requestId,
+          instanceId: value.instanceId,
+          registrationGeneration: value.registrationGeneration,
+          intent,
+          sentAtMs: value.sentAtMs,
+        };
+      }
+      break;
+    }
     case "leader.forwardCallback":
       envelope = parseForwardCallbackEnvelope(value, requestId);
       break;

package/node_modules/@llblab/pi-telegram/lib/commands.ts

@@ -2440,6 +2440,19 @@ export interface TelegramSessionActionAssemblyDeps {
   };
   getProfileName: () => string | undefined;
   ownsPersistence: () => boolean;
+  /**
+   * Registered-follower port. A follower cannot persist leader-owned state, so
+   * its Workspace Thread intent is published and claimed by the leader over
+   * authenticated generation-fenced bus RPC.
+   */
+  follower?: {
+    instanceId: string;
+    isRegisteredFor: (target: { chatId: number; threadId?: number }) => boolean;
+    requestSessionReplacement: (
+      operation: "publish" | "settle",
+      intent: TelegramSessionReplacementIntent,
+    ) => Promise<boolean>;
+  };
   sendResult: (
     target: { chatId: number; threadId?: number },
     html: string,
@@ -2478,7 +2491,13 @@ export function createTelegramSessionActionAssembly(
     sendUserMessage: deps.sendUserMessage,
     notifyResult(target, result) { return sendTerminalResult(target, result); },
     async prepareReplacement(ctx, updateId, target) {
-      await deps.store.load();
+      const follower = !deps.ownsPersistence() && typeof target.threadId === "number" &&
+          deps.follower?.isRegisteredFor(target)
+        ? deps.follower
+        : undefined;
+      // Follower memory is not authority; reread the leader-published snapshot.
+      if (follower && deps.store.refresh) await deps.store.refresh();
+      else await deps.store.load();
       const sessionId = ctx.sessionManager.getSessionId();
       const binding = typeof target.threadId === "number"
         ? deps.store.getWorkspaceBindingByTarget(target)
@@ -2488,7 +2507,7 @@ export function createTelegramSessionActionAssembly(
         throw new Error("Telegram session replacement binding is unavailable.");
       }
       const createdAtMs = now();
-      if (!await deps.store.commitSessionReplacementIntent({
+      const intent: TelegramSessionReplacementIntent = {
         continuity: binding ? "workspace-thread" : "classic-chat",
         cwd: binding?.cwd ?? ctx.cwd,
         profileName: deps.getProfileName() ?? "default",
@@ -2501,7 +2520,11 @@ export function createTelegramSessionActionAssembly(
           ? { threadName: binding.manualThreadName ?? binding.threadName } : {}),
         createdAtMs,
         expiresAtMs: createdAtMs + deps.handoffTtlMs,
-      }, deps.ownsPersistence)) {
+        ...(follower ? { sourceInstanceId: follower.instanceId } : {}),
+      };
+      if (!await (follower
+        ? follower.requestSessionReplacement("publish", intent)
+        : deps.store.commitSessionReplacementIntent(intent, deps.ownsPersistence))) {
         throw new Error("Telegram session replacement intent was not persisted.");
       }
     },
@@ -2514,11 +2537,20 @@ export function createTelegramSessionActionAssembly(
       return {
         async getIntent() { await deps.store.refresh?.(); return deps.store.getSessionReplacementIntent(); },
         hasSuccessorContinuity(intent) {
-          return intent.continuity === "classic-chat" ||
-            deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd === intent.cwd;
+          if (intent.continuity === "classic-chat") return true;
+          if (deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd !==
+              intent.cwd) return false;
+          // A follower successor claims only after its own re-registration is live.
+          return intent.sourceInstanceId === undefined || deps.ownsPersistence() ||
+            deps.follower?.isRegisteredFor(intent.target) === true;
         },
         editSuccess(intent) { return deps.sendResult(intent.target, "<b>🆕 New session started.</b>"); },
-        clearIntent(intent) { return deps.store.removeSessionReplacementIntent(intent, deps.ownsPersistence); },
+        async clearIntent(intent) {
+          if (intent.sourceInstanceId === undefined || deps.ownsPersistence()) {
+            return deps.store.removeSessionReplacementIntent(intent, deps.ownsPersistence);
+          }
+          return await deps.follower?.requestSessionReplacement("settle", intent) ?? false;
+        },
         profileName: deps.getProfileName() ?? "default",
         cwd: ctx.cwd,
         sessionId,

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -65,6 +65,7 @@ const telegramBusProtocolIdentity =
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
     Bus.TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
+    Bus.TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
   ]);
 
 // --- Extension Runtime ---
@@ -244,6 +245,20 @@ export default function (pi: Pi.ExtensionAPI) {
     store: threadStore,
     getProfileName: configStore.getActiveProfileName,
     ownsPersistence: lockRuntime.owns,
+    follower: {
+      instanceId: telegramInstanceId,
+      isRegisteredFor(target) {
+        const registered = telegramBusFollowerRegistrationState.getTarget();
+        return telegramBusFollowerRegistrationState.isRegistered() &&
+          registered?.chatId === target.chatId &&
+          registered.threadId === target.threadId;
+      },
+      async requestSessionReplacement(operation, intent) {
+        const request = telegramBusFollowerRegistration.requestSessionReplacement;
+        if (!request) return false;
+        return await request(operation, intent);
+      },
+    },
     async sendResult(target, html) {
       const delivery = await Delivery.sendTelegramView(
         { text: html, parseMode: "html", replyMarkup: { inline_keyboard: [] } },

package/node_modules/@llblab/pi-telegram/lib/locks.ts

@@ -1515,7 +1515,12 @@ export function createTelegramLockedPollingRuntime<
             ctx,
             state.lock,
           );
-          if (!isCurrent() || !restored) return;
+          if (!isCurrent()) return;
+          if (!restored) {
+            deps.recordRuntimeEvent?.("lock", "Telegram follower auto-connect did not restore this session.",
+              { phase: "follower-auto-connect-unavailable" });
+            return;
+          }
           deps.onTransportAvailabilityChanged?.();
           deps.updateStatus(ctx);
           deps.recordRuntimeEvent?.(

package/node_modules/@llblab/pi-telegram/lib/polling.ts

@@ -1180,8 +1180,16 @@ export function createTelegramThreadAwarePollingPorts<TContext, TOwner>(
     ctx: TContext,
     owner: TOwner,
   ): Promise<boolean | undefined> => {
-    if (!(await refreshFollowerState())) return undefined;
-    if (!deps.hasRememberedWorkspaceBinding?.(ctx)) return undefined;
+    if (!(await refreshFollowerState())) {
+      deps.recordEvent("bus", "Telegram follower auto-connect skipped: Threaded Mode is not enabled.",
+        { phase: "follower-auto-connect-skip", reason: "thread-mode-unavailable" });
+      return undefined;
+    }
+    if (!deps.hasRememberedWorkspaceBinding?.(ctx)) {
+      deps.recordEvent("bus", "Telegram follower auto-connect skipped: no binding for this session.",
+        { phase: "follower-auto-connect-skip", reason: "session-binding-unavailable" });
+      return undefined;
+    }
     return deps.restoreFollowerWithLeader?.(ctx, owner);
   };
   return {

package/node_modules/@llblab/pi-telegram/lib/threads.ts

@@ -371,6 +371,12 @@ export interface TelegramSessionReplacementIntent {
   threadName?: string;
   createdAtMs: number;
   expiresAtMs: number;
+  /**
+   * Present only when the leader published the intent for a registered
+   * follower. Successor re-key and settlement must come from this exact
+   * follower runtime or its authenticated same-process session handoff.
+   */
+  sourceInstanceId?: string;
 }
 
 export interface TelegramTopicTargetFile {
@@ -1329,7 +1335,7 @@ function cloneSessionReplacementIntent(
   return { ...intent, target: { ...intent.target } };
 }
 
-function normalizeSessionReplacementIntent(
+export function normalizeTelegramSessionReplacementIntent(
   value: unknown,
 ): TelegramSessionReplacementIntent | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
@@ -1346,7 +1352,10 @@ function normalizeSessionReplacementIntent(
     typeof record.messageId !== "number" || !Number.isSafeInteger(record.messageId) ||
     typeof record.createdAtMs !== "number" || !Number.isSafeInteger(record.createdAtMs) ||
     typeof record.expiresAtMs !== "number" || !Number.isSafeInteger(record.expiresAtMs) ||
-    record.expiresAtMs <= record.createdAtMs
+    record.expiresAtMs <= record.createdAtMs ||
+    (record.sourceInstanceId !== undefined &&
+      (typeof record.sourceInstanceId !== "string" || !record.sourceInstanceId ||
+        record.sourceInstanceId.length > 256))
   ) return undefined;
   const continuity = record.continuity === "workspace-thread" ||
       record.continuity === "classic-chat"
@@ -1370,6 +1379,8 @@ function normalizeSessionReplacementIntent(
     ...(typeof record.threadName === "string" ? { threadName: record.threadName } : {}),
     createdAtMs: record.createdAtMs,
     expiresAtMs: record.expiresAtMs,
+    ...(typeof record.sourceInstanceId === "string"
+      ? { sourceInstanceId: record.sourceInstanceId } : {}),
   };
 }
 
@@ -1680,7 +1691,7 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
           return normalized ? [normalized] : [];
         })
       : [],
-    sessionReplacement: normalizeSessionReplacementIntent(file.sessionReplacement),
+    sessionReplacement: normalizeTelegramSessionReplacementIntent(file.sessionReplacement),
     reservations: Array.isArray(file.reservations)
       ? file.reservations.flatMap((reservation) => {
           const normalized = normalizeReservation(reservation);
@@ -2510,7 +2521,7 @@ export function createTelegramTopicTargetStore(
         : undefined;
     },
     async commitSessionReplacementIntent(intent, isCurrent) {
-      const next = normalizeSessionReplacementIntent(intent);
+      const next = normalizeTelegramSessionReplacementIntent(intent);
       if (!next || !isCurrent()) return false;
       await loadFromDisk();
       if (!isCurrent()) return false;
@@ -2925,7 +2936,10 @@ export function createTelegramTopicTargetStore(
         replacement.expiresAtMs > getNowMs() &&
         replacement.profileName === (getTelegramProfile() ?? "default") &&
         replacement.cwd === normalizedCwd &&
-        replacement.sourceSessionId !== normalizedSessionId
+        replacement.sourceSessionId !== normalizedSessionId &&
+        (replacement.sourceInstanceId === undefined ||
+          replacement.sourceInstanceId === instanceId ||
+          replacement.sourceInstanceId === previousInstanceId)
       ) {
         const sourceEntry = Array.from(workspaceBindings.entries()).find(([, binding]) =>
           binding.cwd === normalizedCwd &&

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.4",
+  "version": "0.51.5",
   "private": false,
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.23.2",
+  "version": "0.24.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,8 +45,8 @@
     "@llblab/pi-clean-room": "0.2.0",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.2",
-    "@llblab/pi-state-flow": "0.19.1",
-    "@llblab/pi-telegram": "0.51.4",
+    "@llblab/pi-state-flow": "0.21.0",
+    "@llblab/pi-telegram": "0.51.5",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [