@llblab/pi-telegram 0.51.4 → 0.51.6

package/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;
 }
 
@@ -1124,10 +1130,16 @@ function isTelegramStaleContextError(error: unknown): boolean {
 
 export function createTelegramBusFollowerSessionReplacementSuspender(
   deps: TelegramBusFollowerSessionReplacementSuspenderDeps,
-): () => Promise<void> {
+): (preserveTarget?: boolean) => Promise<void> {
   const getNowMs = deps.getNowMs ?? Date.now;
   const getPid = deps.getPid ?? (() => process.pid);
-  return async () => {
+  return async (preserveTarget = true) => {
+    if (!preserveTarget) {
+      setTelegramFollowerSessionHandoff(undefined);
+      Threads.setTelegramLeaderSessionHandoff(undefined);
+      await deps.suspendPolling();
+      return;
+    }
     const target = deps.registrationState.getTarget();
     if (deps.registrationState.isRegistered() && target) {
       setTelegramFollowerSessionHandoff({
@@ -1919,7 +1931,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 +2162,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/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/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;