@llblab/pi-kit 0.24.0 → 0.24.1

package/node_modules/@llblab/pi-telegram/dist/lib/threads.js

@@ -648,7 +648,7 @@ function cloneWorkspaceBinding(binding) {
 function cloneSessionReplacementIntent(intent) {
     return { ...intent, target: { ...intent.target } };
 }
-function normalizeSessionReplacementIntent(value) {
+export function normalizeTelegramSessionReplacementIntent(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const record = value;
@@ -663,7 +663,10 @@ function normalizeSessionReplacementIntent(value) {
         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"
@@ -687,6 +690,8 @@ function normalizeSessionReplacementIntent(value) {
         ...(typeof record.threadName === "string" ? { threadName: record.threadName } : {}),
         createdAtMs: record.createdAtMs,
         expiresAtMs: record.expiresAtMs,
+        ...(typeof record.sourceInstanceId === "string"
+            ? { sourceInstanceId: record.sourceInstanceId } : {}),
     };
 }
 function normalizeWorkspaceRetirementIntent(value) {
@@ -949,7 +954,7 @@ function parseTopicTargetFile(value) {
                 return normalized ? [normalized] : [];
             })
             : [],
-        sessionReplacement: normalizeSessionReplacementIntent(file.sessionReplacement),
+        sessionReplacement: normalizeTelegramSessionReplacementIntent(file.sessionReplacement),
         reservations: Array.isArray(file.reservations)
             ? file.reservations.flatMap((reservation) => {
                 const normalized = normalizeReservation(reservation);
@@ -1667,7 +1672,7 @@ export function createTelegramTopicTargetStore(options) {
                 : undefined;
         },
         async commitSessionReplacementIntent(intent, isCurrent) {
-            const next = normalizeSessionReplacementIntent(intent);
+            const next = normalizeTelegramSessionReplacementIntent(intent);
             if (!next || !isCurrent())
                 return false;
             await loadFromDisk();
@@ -2081,7 +2086,10 @@ export function createTelegramTopicTargetStore(options) {
                 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 &&
                     binding.sessionId === replacement.sourceSessionId &&
                     targetMatches(binding.target, replacement.target));

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

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

package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -83,7 +83,7 @@ Threaded Mode meaning:
 tmp/telegram/owners.json / <profile-slot> -> bus leader identity + heartbeat
 ```
 
-Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Pi session replacement (`new`) changes follower agent context, not bus membership: a registered follower preserves its registration and refreshes the live context instead of disconnecting. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains an exact-`cwd` Workspace binding. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
+Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Pi session replacement (`new`) changes follower agent context, not bus membership: a registered follower preserves its registration and refreshes the live context instead of disconnecting. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains a Workspace binding for the exact `cwd` and session ID. The recent-event log distinguishes missing session bindings, disabled Threaded Mode, leader-side restore refusal, and a restore that returned without connecting; none of these refusals silently provisions a new Thread. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
 
 The assembled follower receiver admits a registration generation only after its journal-binding preparation succeeds for the same generation and current Pi context. Registration identity is available during preparation so the worker can bind, but early inbound delivery receives a negative ACK rather than writing into a retained old journal. Readiness also binds the Pi session generation, so a reused context object cannot preserve it across session replacement. A registered follower's session refresh awaits binding preparation through `setContext` without re-registering or changing its bus generation. Preparation failure keeps inbound delivery unavailable and records a diagnostic; a later refresh can retry. Normal delivery retry proceeds after successful preparation. Registration requests also retain their original Pi session generation and local attempt authority across awaits. A late reply after session drift, stop or a newer request cannot publish success or tear down newer local authority; a context refresh likewise protects its retained membership from an older pending request. This refusal does not undo remote Thread provisioning or authorize deletion.
 
@@ -226,7 +226,7 @@ Followers first try to re-register after leader reload or unknown-heartbeat resp
 
 ### Protocol identity and compatibility
 
-The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding.
+The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding. `session-replacement-intent-v1` gates Telegram `/new` from a follower Thread: followers never write `state.json`, so `follower.publishSessionReplacement` asks the leader to CAS-publish the durable intent only when the live registration generation, leader epoch, Profile, exact `cwd`, source session, Thread target, and the leader's own Workspace binding slot/name all match, with a bounded unexpired TTL. The intent records the source runtime instance; only a successor registration from that instance or its authenticated same-process handoff (`previousInstanceId`) may re-key the binding, and `follower.settleSessionReplacement` claims it once only after the leader's store shows that successor session bound to the same target. A missing capability, stale generation, or mismatch fails the command closed.
 
 Negotiated identities remain on the live follower registry and appear in `/telegram-status --debug` plus the observational state snapshot. The Threaded Mode capability monitor owns one in-flight probe across lifecycle generations: stop/restart invalidates a late read, and a replacement monitor waits for the previous request to settle instead of creating overlapping transport transitions. Durable follower admission is authorized only when both peers advertise `durable-follower-admission-v1`, never inferred from package version: a capable runtime rejects missing support before provisioning, inbound routing, or election-roster eligibility. Authentication and exact registration generation remain mandatory independently of protocol compatibility. `follower.register` is the explicit bootstrap request and may provision; capability-gated `follower.restoreWorkspace` is startup-only and may claim, probe, or replace a remembered binding but returns `workspace-binding-unavailable` without allocating when no binding or claim-fenced legacy exact-`cwd` record exists. Both carry a fresh generation; every later request is exact-generation-fenced against the live registry entry. `bus.ack` is response-only and is rejected if submitted as a server request. Leader forwarding never synthesizes authority for an unknown recipient and preserves the follower's exact durable receipt end to end.
 

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -51,7 +51,7 @@ Stable commands inside Pi:
 Stable commands inside the paired Telegram DM:
 
 - `/start` — pair when needed and open the main application menu.
-- `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches one runtime-armed typed action through the internal `/telegram-internal` Pi gateway using `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Manual invocation reports that the gateway cannot be run manually; the armed handler receives a real `ExtensionCommandContext` and calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. Busy, identity-mismatch, and unavailable-host paths fail closed.
+- `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches one runtime-armed typed action through the internal `/telegram-internal` Pi gateway using `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Manual invocation reports that the gateway cannot be run manually; the armed handler receives a real `ExtensionCommandContext` and calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. In a follower Thread the leader publishes and claims the intent on the follower's behalf over capability-gated, exact-generation local bus requests; followers never persist leader-owned state. Busy, identity-mismatch, stale-registration, incompatible-leader, and unavailable-host paths fail closed.
 - `/compact` — open confirmation and compact when idle.
 - `/next` — abort active work first when needed, attempt the interrupted prompt's abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. That dispatch notice owns the turn's one reply header; later answer messages do not reply to the same prompt again. Abort-notice failure is diagnostic and cannot block dispatch. A later `/abort` or `/stop` cancels both pending transition notices before taking ownership. The `/next` command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.

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?.(