@llblab/pi-telegram 0.51.4 → 0.51.6

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
 

package/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Connect intent across resume` (`post-release acceptance`): The operator approved 0.51.6 release on the successful smoke and green Linux/macOS/Windows CI; this expanded live matrix is not a release blocker. Run live acceptance after rebuilding/reloading: start bare Pi, invoke `/telegram-connect` (default and named profile), immediately `/resume` a session with/without a binding. Check both leader and follower; confirm one connected destination, its correct retained/new slot, no source-target transplant, stale-context error or duplicate notice. Repeat a switch during startup and confirm disconnect cancels it. Native composition, destination-binding, cancellation, and late-completion regressions pass locally. The operator observed one immediate-resume connection complete after a short wait without error; the full profile/role/binding and cancellation matrix remains unverified live.
 - [ ] [`Workspace Thread recovery`](./docs/multi-instance-bus.md) (`environment-gated`): Complete native-Windows coverage for follower restore, inaccessible callbacks, stale targets, and Singleton↔Threaded transitions while preserving accepted work and current ownership.
   - [ ] Select an approved exact-absence observation before implementing ambiguous `deletion-issued` recovery. Never replay an unknown deletion or infer absence from cache, heartbeat silence, empty `editForumTopic`, or `sendChatAction` success.
 - [ ] [`Automatic pairing and follower input custody`](./docs/architecture.md#automatic-pairing-confirmation-design) (`activation-gated`): Keep production custody disabled until historical sources and physical references are reconciled, all legacy writers/consumers are retired or excluded under operator authority, migration is complete, and every participating peer supports the final protocol. Preserve outcome-unknown running work, exact receipt/group authority, authenticated handoff, and rollback/downgrade safety. Then compose the prepared v3 lifecycle/bus ports, add bounded operator disposition for retained legacy retry state, and run real-process plus native-Windows acceptance.

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 ## Unreleased
 
+## 0.51.6: Connection resume and Workspace recovery hotfix
+
+- `Workspace slot recovery`: Confirmed pressure-retirement deletion invalidates the exact stale active-target record before binding removal. Same-process and successor retries finish a retained `commit-ready` fence without repeating Telegram deletion, preventing exhausted A–Z slots from deadlocking on `protection-changed`. Includes [#305](https://github.com/llblab/pi-telegram/pull/305).
+- `Connect lifecycle`: `/telegram-connect` checks plain session generation before reading Pi context getters after awaited work. Replaced commands cannot publish stale connection notices or retry startup against the old session; config, startup, recovery and takeover confirmation discard obsolete results.
+- `Resume connection`: In-flight `/telegram-connect` or an already connected bridge carries bounded same-process intent into the resumed session, retaining the selected profile but not the source Thread. Startup restores the destination's exact binding or provisions its own slot; cancellation, expiry and late completion cannot revive obsolete work.
+- `Thread binding isolation`: Session-aware startup no longer reuses another session's active target or legacy instance binding. Pending Thread creation records its Workspace binding key; unproven or foreign-session recovery is blocked without consuming evidence or repeating creation.
+- `Connection feedback`: Manual/resumed connection failures use compact cause-and-action notices rather than raw exception guidance. Detailed errors remain in redacted diagnostics; recovery success produces one short notice, and failed disconnect keeps Pi open without a duplicate exception banner. Delayed disconnect completion cannot touch a replaced Pi context.
+- `Model continuation`: In-flight model switching injects one compact line with the resume instruction, selected model and optional thinking level, preserving the control lane and exact reply target.
+- `Lifecycle ownership`: Connect intent and resume scheduling belong to the existing session lifecycle domain; compact failure formatting belongs to status. Transport authority, durable bindings and queue custody keep their existing owners, without introducing a separate connection domain.
+
+## 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.

package/README.md

@@ -57,7 +57,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 /telegram-connect
 ```
 
-The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Reopening or resuming the same Pi session restores its remembered Thread at session startup; a distinct session in the same directory has its own binding and still requires explicit `/telegram-connect` when no remembered binding exists.
+The connected Pi instance owns Telegram polling. Use `/telegram-connect <profile>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers. Reopening or resuming the same Pi session restores its remembered Thread at session startup. If `/resume` immediately follows `/telegram-connect`, or the bridge is already connected, connection intent follows the switch: the destination restores its own Thread/slot or receives a new binding, never the source session's Thread. Otherwise, a distinct unbound session still requires explicit `/telegram-connect`.
 
 After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. A journal snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the snapshot and segments are quarantined as recovery evidence, a fresh journal is published, and startup continues with an informational diagnostic instead of requiring manual JSON repair. Unsupported journal versions block recovery without rewriting or quarantining the retained files; use a compatible runtime rather than deleting journals. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
 

package/dist/lib/bindings.d.ts

@@ -194,9 +194,12 @@ interface TelegramCommandsAndToolsBindingDeps {
     canSendDirect: () => boolean;
     setGenerativeAppLiveSurfaceRuntime?: (runtime: GenerativeApps.GenerativeAppLiveSurfaceRuntime<GenerativeApps.TelegramBindLiveHandle> | undefined) => void;
     updateStatus: TelegramBridgeStatusUpdater;
+    isContextCurrent: (ctx: Pi.ExtensionContext) => boolean;
+    getSessionGeneration: () => number;
+    connectionIntent: NonNullable<Commands.TelegramBridgeCommandRegistrationDeps["connectionIntent"]>;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
-export declare function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, }: TelegramCommandsAndToolsBindingDeps): void;
+export declare function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, isContextCurrent, getSessionGeneration, connectionIntent, }: TelegramCommandsAndToolsBindingDeps): void;
 interface TelegramLifecycleBindingDeps {
     pi: Pi.ExtensionAPI;
     publicationRuntime: TelegramBridgePublicationRuntime;

package/dist/lib/bindings.js

@@ -323,7 +323,7 @@ export function createTelegramActivityBindingRuntime(deps) {
         },
     };
 }
-export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, }) {
+export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, persistConfig, setup, activeTurnRuntime, lockedPollingRuntime, stopPolling, recoverPollingStart, getDisconnectThreadName, onTransportChanged, getStatusLines, buttonActionStore, sendMarkdownReply, sendChannelMarkdownMessage, sendChannelMediaMessage, listChannelPosts, mutateChannelPost, callMultipart, getDefaultChatId, getDefaultTarget, resolveAgentTarget, routeAgentMessage, canSendDirect, setGenerativeAppLiveSurfaceRuntime, recordRuntimeEvent, updateStatus, isContextCurrent, getSessionGeneration, connectionIntent, }) {
     GenerativeApps.registerTelegramBindTool(pi, {
         agentDir,
         getActiveProfileName: configStore.getActiveProfileName,
@@ -452,33 +452,35 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         reloadConfig: configStore.load,
         hasBotToken: configStore.hasBotToken,
         getBotTokenDiagnostic: configStore.getBotTokenDiagnostic,
-        startPolling: async (ctx, options) => {
-            try {
-                return await lockedPollingRuntime.start(ctx, options);
-            }
-            catch (error) {
-                recordRuntimeEvent("recovery", error, { phase: "polling-start" });
-                throw error;
-            }
-        },
+        startPolling: lockedPollingRuntime.start,
+        recordConnectionEvent: (error, phase) => recordRuntimeEvent("connection", error, { phase }),
         stopPolling: stopPolling ?? lockedPollingRuntime.stop,
         recoverPollingStart,
         getDisconnectThreadName,
         queueAgentConnectionContext,
         updateStatus,
+        isContextCurrent,
+        getSessionGeneration,
+        connectionIntent,
         getProfileNames: () => Config.getTelegramProfileNames(configStore.getStoredConfig()),
-        activateDefaultProfileConfig: async () => {
+        activateDefaultProfileConfig: async (_ctx, isCurrent) => {
             const previousProfileName = configStore.getActiveProfileName();
             await configStore.load();
+            if (!isCurrent())
+                return;
             if (previousProfileName) {
                 await (stopPolling ?? lockedPollingRuntime.stop)();
+                if (!isCurrent())
+                    return;
             }
             configStore.activateProfile(undefined);
             await onTransportChanged?.();
         },
-        activateProfileConfig: async (_ctx, profileName) => {
+        activateProfileConfig: async (_ctx, profileName, isCurrent) => {
             const previousProfileName = configStore.getActiveProfileName();
             await configStore.load();
+            if (!isCurrent())
+                return false;
             if (!Config.isValidTelegramProfileName(profileName))
                 return false;
             const storedConfig = configStore.getStoredConfig();
@@ -486,6 +488,8 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
                 return false;
             if (previousProfileName !== profileName) {
                 await (stopPolling ?? lockedPollingRuntime.stop)();
+                if (!isCurrent())
+                    return false;
             }
             if (!configStore.activateProfile(profileName))
                 return false;

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 {
@@ -369,7 +371,7 @@ export declare function createTelegramBusAgentMessageClient(deps: TelegramBusFol
     routeMessage: (message: TelegramBusAgentMessage) => Promise<void>;
 };
 export declare function createTelegramBusFollowerApiCaller(deps: TelegramBusFollowerApiCallerDeps): (method: string, args: unknown[]) => Promise<unknown>;
-export declare function createTelegramBusFollowerSessionReplacementSuspender(deps: TelegramBusFollowerSessionReplacementSuspenderDeps): () => Promise<void>;
+export declare function createTelegramBusFollowerSessionReplacementSuspender(deps: TelegramBusFollowerSessionReplacementSuspenderDeps): (preserveTarget?: boolean) => Promise<void>;
 export declare function createTelegramBusFollowerSessionRefreshHook<TContext>(deps: TelegramBusFollowerSessionRefreshHookDeps<TContext>): (_event: unknown, ctx: TContext) => Promise<void>;
 export declare function createTelegramBusFollowerControlState(): TelegramBusFollowerControlState;
 export declare function createTelegramBusFollowerRegistrationState(options?: {

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;
@@ -519,7 +519,13 @@ function isTelegramStaleContextError(error) {
 export function createTelegramBusFollowerSessionReplacementSuspender(deps) {
     const getNowMs = deps.getNowMs ?? Date.now;
     const getPid = deps.getPid ?? (() => process.pid);
-    return async () => {
+    return async (preserveTarget = true) => {
+        if (!preserveTarget) {
+            setTelegramFollowerSessionHandoff(undefined);
+            Threads.setTelegramLeaderSessionHandoff(undefined);
+            await deps.suspendPolling();
+            return;
+        }
         const target = deps.registrationState.getTarget();
         if (deps.registrationState.isRegistered() && target) {
             setTelegramFollowerSessionHandoff({
@@ -1214,8 +1220,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 +1437,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

@@ -6,7 +6,7 @@
 import { type TelegramConfigStore } from "./config.ts";
 import type * as Pi from "./pi.ts";
 import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
-import type { TelegramBridgeStatusLineOptions } from "./status.ts";
+import { type TelegramBridgeStatusLineOptions } from "./status.ts";
 import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import { type PendingTelegramControlItem, type TelegramQueueAdmissionReceipt } from "./queue.ts";
 export interface ParsedTelegramCommand {
@@ -112,12 +112,21 @@ export interface TelegramBridgeCommandRegistrationDeps {
     startPolling: (ctx: ExtensionCommandContext, options?: TelegramBridgeCommandStartPollingOptions) => void | Promise<void | TelegramBridgeCommandStartPollingResult> | TelegramBridgeCommandStartPollingResult;
     stopPolling: () => Promise<void | string>;
     recoverPollingStart?: (error: unknown) => Promise<TelegramPollingStartRecoveryResult>;
+    recordConnectionEvent?: (error: unknown, phase: string) => void;
     getDisconnectThreadName?: () => string | undefined;
     queueAgentConnectionContext?: (connected: boolean) => void;
     updateStatus: (ctx: ExtensionCommandContext) => void;
+    isContextCurrent?: (ctx: ExtensionCommandContext) => boolean;
+    getSessionGeneration?: () => number;
+    connectionIntent?: {
+        begin(cwd: string, profileName?: string): string;
+        finish(id: string): void;
+        isActive(id: string): boolean;
+        cancel(): void;
+    };
     getProfileNames?: () => string[];
-    activateDefaultProfileConfig?: (ctx: ExtensionCommandContext) => Promise<void>;
-    activateProfileConfig?: (ctx: ExtensionCommandContext, profileName: string) => Promise<boolean>;
+    activateDefaultProfileConfig?: (ctx: ExtensionCommandContext, isCurrent: () => boolean) => Promise<void>;
+    activateProfileConfig?: (ctx: ExtensionCommandContext, profileName: string, isCurrent: () => boolean) => Promise<boolean>;
 }
 export type TelegramThreadDisplayNameRenamePort = (target: {
     chatId: number;
@@ -645,6 +654,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;