@llblab/pi-telegram 0.51.3 → 0.51.5

package/dist/lib/skills.js

@@ -3,17 +3,42 @@
  * Zones: pi agent, telegram guidance
  * Owns source-checkout skill contribution; installed packages use their manifest
  */
-import { extname } from "node:path";
+import { existsSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveAgentDir } from "./paths.js";
 const TELEGRAM_SKILLS_MODULE_PATH = fileURLToPath(import.meta.url);
-export const TELEGRAM_SKILLS_PATH = fileURLToPath(new URL("../skills", import.meta.url));
-export function registerTelegramSkillDiscovery(pi, modulePath = TELEGRAM_SKILLS_MODULE_PATH) {
-    // A raw source extension has no package manifest owner. Compiled npm/git
-    // packages do, so contributing again would bypass their resource filters.
-    if (extname(modulePath) !== ".ts")
+export function getTelegramExtensionPackageRoot(modulePath) {
+    let current = dirname(modulePath);
+    while (true) {
+        if (existsSync(join(current, "package.json"))) {
+            const parent = dirname(current);
+            if (basename(current) === "dist" && existsSync(join(parent, "package.json"))) {
+                return parent;
+            }
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return dirname(modulePath);
+        current = parent;
+    }
+}
+export function isRawTelegramExtensionCheckout(modulePath, options = {}) {
+    const packageRoot = resolve(getTelegramExtensionPackageRoot(modulePath));
+    const agentDir = resolve(options.agentDir ?? resolveAgentDir());
+    const cwd = resolve(options.cwd ?? process.cwd());
+    return dirname(packageRoot) === join(agentDir, "extensions") ||
+        dirname(packageRoot) === join(cwd, ".pi", "extensions");
+}
+export const TELEGRAM_SKILLS_PATH = join(getTelegramExtensionPackageRoot(TELEGRAM_SKILLS_MODULE_PATH), "skills");
+export function registerTelegramSkillDiscovery(pi, modulePath = TELEGRAM_SKILLS_MODULE_PATH, options = {}) {
+    // Pi auto-discovers extension entrypoints but not their manifest Skills.
+    // Manifest-loaded packages own Skills and filters through `pi.skills`.
+    if (!isRawTelegramExtensionCheckout(modulePath, options))
         return false;
     pi.on("resources_discover", () => ({
-        skillPaths: [TELEGRAM_SKILLS_PATH],
+        skillPaths: [join(getTelegramExtensionPackageRoot(modulePath), "skills")],
     }));
     return true;
 }

package/dist/lib/threads.d.ts

@@ -187,6 +187,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 {
     version: 1;
@@ -385,6 +391,7 @@ export declare function isTelegramLeaderSessionHandoffFresh(handoff: TelegramLea
 }): handoff is TelegramLeaderSessionHandoff;
 export declare function getTelegramThreadOwnerKey(owner: TelegramThreadOwner): string;
 export declare function getTelegramThreadOwnerFromProfileKey(profileKey: string): TelegramThreadOwner;
+export declare function normalizeTelegramSessionReplacementIntent(value: unknown): TelegramSessionReplacementIntent | undefined;
 export declare function isSameTelegramProcessInstance(left: string | undefined, right: string | undefined): boolean;
 export declare function createTelegramTopicTargetStore(options: TelegramTopicTargetStoreOptions): TelegramTopicTargetStore;
 export declare function normalizeTelegramTopicTargetThreadName(threadName: string): string;

package/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/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.51.3",
+  "version": "0.51.5",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -31,12 +31,13 @@
     "test:verbose": "node --experimental-strip-types --test --test-reporter=spec tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "node scripts/build-dist.mjs",
+    "build:check": "node scripts/build-dist.mjs --check",
     "prepack": "npm run build",
     "check": "node -e \"await import('./dist/pi-telegram/index.js'); console.log('pi-telegram: extension import ok')\"",
     "audit": "npm audit --omit=peer",
     "audit:host": "npm audit",
     "pack:check": "npm pack --dry-run",
-    "validate": "npm run build && npm run typecheck && npm test && npm run audit && npm run check && npm run pack:check"
+    "validate": "npm run build:check && npm run typecheck && npm test && npm run audit && npm run check && npm run pack:check"
   },
   "files": [
     "index.ts",
@@ -102,15 +103,9 @@
     "extensions": [
       "./dist/pi-telegram/index.js"
     ],
-    "sourceExtensions": [
-      "./index.ts"
-    ],
     "skills": [
       "./dist/skills"
     ],
-    "sourceSkills": [
-      "./skills"
-    ],
     "image": "https://raw.githubusercontent.com/llblab/pi-telegram/main/screenshot.png"
   },
   "peerDependencies": {

package/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/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/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/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;