@llblab/pi-telegram 0.51.3 → 0.51.5

package/AGENTS.md

@@ -125,7 +125,7 @@ The detailed map is canonical in [`docs/architecture.md`](./docs/architecture.md
 - Command templates remain compact and shell-free. Use string leaves or ordered `template` arrays; shell operators are not an execution contract. Examples use portable executable placeholders, never machine-local paths.
 - `telegram_attach` is the canonical file path and `telegram_message` the direct Markdown text/buttons path. Both require current direct or registered-follower authority and must not replace the normal active-turn reply.
 - Inbound handlers transform text/media before queueing; outbound handlers precede programmatic/provider fallbacks. Public contracts and ordering live in `docs/inbound.md`, `docs/outbound.md`, and `docs/public-api.md`.
-- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through the single `/telegram-internal` Pi gateway via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; only a runtime-armed typed action may execute, manual invocation reports that the command cannot be run manually, and the handler receives the real `ExtensionCommandContext` before calling `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
+- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through the single `/telegram-internal` Pi gateway via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; only a runtime-armed typed action may execute, manual invocation reports that the command cannot be run manually, and the handler receives the real `ExtensionCommandContext` before calling `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. A registered follower cannot persist leader-owned state: its Workspace Thread intent is published and claimed by the leader over capability-gated exact-generation bus RPC after leader-side binding validation, and records its source runtime instance so only that follower lineage may re-key or claim it. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
 
 ## 7. Engineering Conventions
 
@@ -152,7 +152,7 @@ Before non-trivial work:
 While working:
 
 - Keep changes inside this repository; updating an installed Pi checkout is a separate operator action.
-- Rebuild the package with `npm run build` after edits. Pi loads `dist/pi-telegram/index.js`, so source-only changes are not live and `/reload` or process restart alone will reload stale compiled output.
+- Rebuild the package with `npm run build` after edits. Pi loads `dist/pi-telegram/index.js`, so source-only changes are not live and `/reload` or process restart alone will reload stale compiled output. Keep the committed `dist/` synchronized for Git installs; builds use a temporary candidate and rollback-safe swap, while `npm run build:check` rejects drift without rewriting the tree.
 - Read large artifacts search-first and range-bounded. For `CHANGELOG.md`, inspect only the current release section unless older history is relevant.
 - Keep successful validation output compact; inspect focused failure tails. Prefer focused tests/typecheck during iteration and broad validation at a stable gate.
 - Preserve unrelated work and do not commit, publish, tag, deploy, or perform external actions without explicit authorization.

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.51.5: Follower Thread new-session hotfix
+
+- `Follower Thread /new`: Telegram `/new` now starts a new session in a follower's Pi process and preserves its Thread binding. The leader publishes and later claims the durable replacement intent through capability-gated, generation-fenced bus requests, validating its own live registration and Workspace binding before accepting the follower's request. Incompatible or stale leaders fail closed rather than silently switching sessions.
+- `Follower restore diagnostics`: Session startup now records when automatic follower restore lacks a session binding, Threaded Mode, or leader-side Workspace authority, or finishes without connecting. Restore-only refusal still cannot create a new Thread; `/telegram-connect` remains the explicit recovery path.
+
+## 0.51.4: Resolver-owned Skills and drift-safe Git installs
+
+- `Resolver-owned Skills`: Auto-discovered user/project checkouts now contribute source Skills even when Pi selects their compiled entrypoint, while manifest-loaded npm, Git, and Pi Kit packages retain `pi.skills` filters and package provenance. Resolver regressions cover checkout and filtered-package behavior; unsupported source manifest aliases are removed.
+- `Drift-safe distributive`: The compiled runtime and Skill tree are now committed for self-contained Git installs. Builds compile into a temporary candidate and use a rollback-safe swap; validation rejects stale committed output without silently repairing it.
+
 ## 0.51.3: Follower recovery and filterable Skills
 
 - `Follower slot reconciliation`: Re-registration now treats the exact Workspace claim as canonical when a retained follower record carries a different slot. It repairs the record before binding commit, preserves the unrelated binding that owns the stale letter, and makes repeated registration idempotent instead of returning `Telegram Workspace binding claim changed.` forever.

package/README.md

@@ -26,7 +26,7 @@ From git:
 pi install git:github.com/llblab/pi-telegram
 ```
 
-Installed npm/git packages expose bundled Skills through their `pi.skills` manifest, so Pi package filters can select individual Skills. A raw TypeScript checkout placed directly under Pi's `extensions` directory instead contributes its adjacent source Skills at runtime; the two discovery paths are mutually exclusive.
+Installed npm/git packages expose bundled Skills through their `pi.skills` manifest, so Pi package filters and package provenance remain authoritative. A checkout auto-discovered directly under Pi's user or project `extensions` directory contributes its adjacent source Skills even when Pi selects the checkout's compiled entrypoint; the two discovery paths are mutually exclusive.
 
 The extension requires Pi `0.84.4` or newer, matching the package's peer dependencies. Its Activity API uses the public `agent_settled` lifecycle event to keep retries/continuations under one activity identity and release that identity only after the run fully settles.
 
@@ -319,7 +319,7 @@ The docs index lives at [docs/README.md](./docs/README.md).
 
 ## Development
 
-Pi loads the compiled `dist/pi-telegram/index.js` entrypoint. After every project change, run `npm run build` before `/reload`, restart, or live verification; reloading source without rebuilding can leave the running extension on stale compiled code.
+Pi loads the compiled `dist/pi-telegram/index.js` entrypoint. The committed distributive also makes Git installs self-contained. After every project change, run `npm run build` before `/reload`, restart, or live verification; `npm run build:check` verifies source/artifact synchronization without rewriting it.
 
 ```bash
 npm run build

package/dist/lib/bus-follower.d.ts

@@ -54,6 +54,8 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
         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;
 }
 export interface TelegramBusFollowerSessionReplacementSuspenderDeps {

package/dist/lib/bus-follower.js

@@ -11,7 +11,7 @@ import * as Threads from "./threads.js";
 import { parseTelegramUpdateJournalQueueOwner } from "./journal.js";
 import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, } from "./locks.js";
 import { isTelegramApiMethodRetrySafe, TelegramApiCommitUnknownError, TelegramApiStaleTargetError, } from "./telegram-api.js";
-import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, } from "./bus.js";
+import { createTelegramBusFollowerDeliveryIdentity, createTelegramBusFollowerTargetController, createTelegramBusForeignOwnedUpdateForwarder, createTelegramBusLocalServer, createTelegramBusRequestIdFactory, createUnauthorizedBusAck, getTelegramBusProtocolCompatibility, getTelegramBusSocketPath, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, resolveTelegramBusSocketPath, sendTelegramBusLocalEnvelope, 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.js";
 import { getTelegramBusTransportRetryPolicy, TELEGRAM_BUS_REGISTRATION_RETRY, } from "./bus-transport.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
 export const TELEGRAM_BUS_FOLLOWER_PROMOTION_GRACE_MS = 2_500;
@@ -1214,8 +1214,13 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
                 deps.setActiveAuthSecret?.(undefined);
                 await deps.stopReceiving?.();
                 if (registrationOptions?.restoreWorkspace &&
-                    response.error?.code === "workspace-binding-unavailable")
+                    response.error?.code === "workspace-binding-unavailable") {
+                    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.");
             }
@@ -1426,6 +1431,54 @@ export function createTelegramBusFollowerRegistrationRuntime(deps) {
             }
             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/dist/lib/bus-leader.d.ts

@@ -135,6 +135,23 @@ export interface TelegramBusLeaderRuntimeAssemblyDeps<TContext> {
     runWorkspaceOperation?: TelegramBusWorkspaceAdmissionRunner;
     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 declare function createTelegramBusFollowerSessionReplacementAuthority(deps: {
+    store: Pick<Threads.TelegramTopicTargetStore, "load" | "getWorkspaceBindingByTarget" | "getSessionReplacementIntent" | "commitSessionReplacementIntent" | "removeSessionReplacementIntent">;
+    getTelegramProfile?: () => string | undefined;
+    getNowMs?: () => number;
+    ttlMs?: number;
+}): {
+    publish: TelegramBusFollowerSessionReplacementOperation;
+    settle: TelegramBusFollowerSessionReplacementOperation;
+};
 export declare function createTelegramBusLeaderRuntimeAssembly<TContext>(deps: TelegramBusLeaderRuntimeAssemblyDeps<TContext>): TelegramBusLeaderRuntime<TContext> & {
     renameLeaderThreadAdmitted: (threadName: string, expectedTarget?: Threads.TelegramTopicTargetRecord["target"]) => Promise<Threads.TelegramTopicTargetRecord>;
     resetLeaderThreadName: (expectedTarget: Threads.TelegramTopicTargetRecord["target"]) => Promise<{
@@ -188,6 +205,8 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     }> | {
         threadName: string;
     };
+    publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+    settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
     getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
     onFollowerRegistered?: () => void;
     applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;
@@ -273,6 +292,8 @@ export declare function createTelegramBusLeaderEnvelopeHandler(deps: {
     }> | {
         threadName: string;
     };
+    publishFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
+    settleFollowerSessionReplacement?: TelegramBusFollowerSessionReplacementOperation;
     getFollowerDisplayTitle?: (follower: TelegramBusFollowerView) => string | undefined;
     onFollowerRegistered?: () => void;
     applyThreadDisplayMode?: (mode: TelegramThreadDisplayMode, isCurrent: () => boolean) => Promise<void>;

package/dist/lib/bus-leader.js

@@ -9,7 +9,7 @@ import { createTelegramThreadDisplayReconciler, resolveTelegramInitialWorkspaceD
 import * as ThreadReconciler from "./thread-reconciler.js";
 import { getTelegramApiErrorRequestTarget, isTelegramApiCommitUnknownError, } from "./telegram-api.js";
 import * as Threads from "./threads.js";
-import { createTelegramBusLocalServer, createUnauthorizedBusAck, getTelegramBusEnvelopeTrafficClass, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, getTelegramBusFollowerSocketPath, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, } from "./bus.js";
+import { createTelegramBusLocalServer, createUnauthorizedBusAck, getTelegramBusEnvelopeTrafficClass, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, getTelegramBusFollowerSocketPath, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, 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.js";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.js";
 import { createTelegramWorkspaceOperationRuntime, createTelegramWorkspaceSlotRotation, } from "./workspace-retirement.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
@@ -27,6 +27,75 @@ function formatTelegramBusInstanceLabel(input) {
         return escapeHtml(threadName);
     return input.slot && /^[A-Z]$/.test(input.slot) ? input.slot : "?";
 }
+/**
+ * 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) {
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const ttlMs = deps.ttlMs ?? Threads.TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS;
+    const assertCommon = (follower, intent) => {
+        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(deps) {
     const runWorkspaceAdmission = deps.getWorkspaceAdmission
         ? (input, operation) => {
@@ -327,6 +396,11 @@ export function createTelegramBusLeaderRuntimeAssembly(deps) {
             }
         });
     });
+    const followerSessionReplacement = createTelegramBusFollowerSessionReplacementAuthority({
+        store: deps.topicTargetStore,
+        getTelegramProfile: deps.getTelegramProfile,
+        getNowMs: deps.runtime.getNowMs,
+    });
     const runtime = createTelegramBusLeaderRuntime({
         ...deps.runtime,
         applyThreadDisplayMode,
@@ -427,6 +501,16 @@ export function createTelegramBusLeaderRuntimeAssembly(deps) {
                 }
             });
         }),
+        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({
                 operationId: createTelegramWorkspaceAdmissionOperationId(),
@@ -1796,6 +1880,63 @@ 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",
+                            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",
+                                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",
+                            requestId: envelope.requestId,
+                            ok: true,
+                            result: { committed: true },
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            kind: "bus.ack",
+                            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(registeredFollower ?? { instanceId: envelope.instanceId }, async () => {
@@ -2303,6 +2444,8 @@ export function createTelegramBusLeaderRuntime(deps) {
         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/dist/lib/bus.d.ts

@@ -8,6 +8,7 @@ import { type TelegramBusTransportEventRecorder, type TelegramBusTransportRetryP
 import { type TelegramQueueHandoffPayload } from "./queue.ts";
 import type { TelegramTarget } from "./target.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
+import { type TelegramSessionReplacementIntent } from "./threads.ts";
 export interface TelegramBusProcessRuntime {
     instanceId: string;
     processId: number;
@@ -60,6 +61,7 @@ export declare const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME: "workspace
 export declare const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE: "thread-display-mode-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT: "directory-display-format-v1";
 export declare const TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT: "workspace-follower-auto-connect-v1";
+export declare const TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT: "session-replacement-intent-v1";
 export interface TelegramBusProtocolIdentity {
     protocolVersion: number;
     runtimeBuild: string;
@@ -249,6 +251,13 @@ export type TelegramBusEnvelope = ({
         threadId: number;
     };
     sentAtMs: number;
+} | {
+    kind: "follower.publishSessionReplacement" | "follower.settleSessionReplacement";
+    requestId: string;
+    instanceId: string;
+    registrationGeneration: string;
+    intent: TelegramSessionReplacementIntent;
+    sentAtMs: number;
 } | {
     kind: "leader.forwardCallback";
     requestId: string;

package/dist/lib/bus.js

@@ -15,6 +15,7 @@ import { classifyTelegramBusTransportError, createTelegramBusTransportTimeoutErr
 import { TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS, TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES, } from "./queue.js";
 import { isProcessAlive } from "./locks.js";
 import { resolveAgentDir } from "./paths.js";
+import { normalizeTelegramSessionReplacementIntent, } from "./threads.js";
 function readDarwinProcessStart(pid) {
     return execFileSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], {
         encoding: "utf8",
@@ -124,6 +125,7 @@ export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME = "workspace-thread
 export const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE = "thread-display-mode-v1";
 export const TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT = "directory-display-format-v1";
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT = "workspace-follower-auto-connect-v1";
+export const TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT = "session-replacement-intent-v1";
 export function createTelegramBusProtocolIdentity(input) {
     const runtimeBuild = input.runtimeBuild.trim();
     if (!runtimeBuild || runtimeBuild.length > 128) {
@@ -505,6 +507,23 @@ export function parseTelegramBusEnvelope(line) {
             }
             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/dist/lib/commands.d.ts

@@ -645,6 +645,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;

package/dist/lib/commands.js

@@ -1294,7 +1294,15 @@ export function createTelegramSessionActionAssembly(deps) {
         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)
@@ -1304,7 +1312,7 @@ export function createTelegramSessionActionAssembly(deps) {
                 throw new Error("Telegram session replacement binding is unavailable.");
             }
             const createdAtMs = now();
-            if (!await deps.store.commitSessionReplacementIntent({
+            const intent = {
                 continuity: binding ? "workspace-thread" : "classic-chat",
                 cwd: binding?.cwd ?? ctx.cwd,
                 profileName: deps.getProfileName() ?? "default",
@@ -1317,7 +1325,11 @@ export function createTelegramSessionActionAssembly(deps) {
                     ? { 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.");
             }
         },
@@ -1331,11 +1343,22 @@ export function createTelegramSessionActionAssembly(deps) {
             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/dist/lib/extension.js

@@ -60,6 +60,7 @@ const telegramBusProtocolIdentity = Bus.createTelegramCurrentBusProtocolIdentity
     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 ---
 export default function (pi) {
@@ -191,6 +192,21 @@ export default function (pi) {
         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: [] } }, { scope: { kind: "target", target } });
             return delivery.ok ? { ok: true } : { ok: false,

package/dist/lib/locks.js

@@ -1171,8 +1171,12 @@ export function createTelegramLockedPollingRuntime(deps) {
                     return;
                 if (canRestoreRememberedFollower && state?.kind === "active-elsewhere") {
                     const restored = await deps.restoreFollowerWithOwner?.(ctx, state.lock);
-                    if (!isCurrent() || !restored)
+                    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?.("bus", "Telegram follower auto-connect completed", { phase: "follower-auto-connect" });

package/dist/lib/polling.js

@@ -752,10 +752,14 @@ export function createTelegramThreadAwarePollingPorts(deps) {
         return deps.registerFollowerWithLeader(ctx, owner);
     };
     const restoreFollowerWithOwner = async (ctx, owner) => {
-        if (!(await refreshFollowerState()))
+        if (!(await refreshFollowerState())) {
+            deps.recordEvent("bus", "Telegram follower auto-connect skipped: Threaded Mode is not enabled.", { phase: "follower-auto-connect-skip", reason: "thread-mode-unavailable" });
             return undefined;
-        if (!deps.hasRememberedWorkspaceBinding?.(ctx))
+        }
+        if (!deps.hasRememberedWorkspaceBinding?.(ctx)) {
+            deps.recordEvent("bus", "Telegram follower auto-connect skipped: no binding for this session.", { phase: "follower-auto-connect-skip", reason: "session-binding-unavailable" });
             return undefined;
+        }
         return deps.restoreFollowerWithLeader?.(ctx, owner);
     };
     return {

package/dist/lib/skills.d.ts

@@ -4,5 +4,11 @@
  * Owns source-checkout skill contribution; installed packages use their manifest
  */
 import type { ExtensionAPI } from "./pi.ts";
+export declare function getTelegramExtensionPackageRoot(modulePath: string): string;
+export interface TelegramRawExtensionCheckoutOptions {
+    agentDir?: string;
+    cwd?: string;
+}
+export declare function isRawTelegramExtensionCheckout(modulePath: string, options?: TelegramRawExtensionCheckoutOptions): boolean;
 export declare const TELEGRAM_SKILLS_PATH: string;
-export declare function registerTelegramSkillDiscovery(pi: Pick<ExtensionAPI, "on">, modulePath?: string): boolean;
+export declare function registerTelegramSkillDiscovery(pi: Pick<ExtensionAPI, "on">, modulePath?: string, options?: TelegramRawExtensionCheckoutOptions): boolean;