@llblab/pi-telegram 0.51.4 → 0.51.6

package/dist/lib/commands.js

@@ -6,6 +6,7 @@
 import { randomUUID } from "node:crypto";
 import { pairTelegramUserIfNeeded, TELEGRAM_DEFAULT_PROFILE_NAME, } from "./config.js";
 import { escapeHtml } from "./rendering.js";
+import { formatTelegramConnectionFailure } from "./status.js";
 import { createTelegramControlItemBuilder, createTelegramControlQueueController, createTelegramQueueAdmissionReceipt, } from "./queue.js";
 const TELEGRAM_EXTENSION_COMMAND_REGISTRY_KEY = "__piTelegramCommandRegistry__";
 const TELEGRAM_BOT_COMMAND_NAME_PATTERN = /^[a-z0-9_]{1,32}$/;
@@ -270,121 +271,174 @@ export function registerTelegramBridgeCommands(pi, deps) {
     pi.registerCommand("telegram-connect", {
         description: "<profile> — Start Telegram bridge",
         handler: async (args, ctx) => {
+            const sessionGeneration = deps.getSessionGeneration?.();
+            let intentId;
+            // Pi context getters throw after replacement; check plain intent/generation first.
+            const isCurrent = () => (!intentId || deps.connectionIntent?.isActive(intentId) !== false) &&
+                (sessionGeneration === undefined || deps.getSessionGeneration?.() === sessionGeneration) &&
+                deps.isContextCurrent?.(ctx) !== false;
+            if (!isCurrent())
+                return;
             if (args.trim().split(/\s+/).some((word) => /^as=/i.test(word))) {
                 ctx.ui.notify("Thread names are configured from Telegram, not from Pi commands.", "warning");
                 deps.updateStatus(ctx);
                 return;
             }
             const profileName = parseTelegramProfileArg(args);
-            if (profileName && deps.activateProfileConfig) {
-                const ok = await deps.activateProfileConfig(ctx, profileName);
-                if (!ok) {
-                    ctx.ui.notify(`Profile "${profileName}" not found.`, "error");
-                    deps.updateStatus(ctx);
-                    return;
-                }
-                ctx.ui.notify(`Activated profile "${profileName}".`, "info");
-            }
-            else {
-                await (deps.activateDefaultProfileConfig?.(ctx) ?? deps.reloadConfig());
-            }
-            if (!deps.hasBotToken()) {
-                const botTokenDiagnostic = deps.getBotTokenDiagnostic?.();
-                if (botTokenDiagnostic)
-                    ctx.ui.notify(botTokenDiagnostic, "error");
-                const profileNames = deps.getProfileNames?.() ?? [];
-                if (!profileName && profileNames.length > 0) {
-                    ctx.ui.notify(`No default Telegram profile configured. Available profiles: ${profileNames.join(", ")}. Use /telegram-connect <profileName> or /telegram-setup to create a default profile.`, "info");
-                    deps.updateStatus(ctx);
-                    return;
+            intentId = deps.connectionIntent?.begin(ctx.cwd, profileName);
+            try {
+                if (profileName && deps.activateProfileConfig) {
+                    const ok = await deps.activateProfileConfig(ctx, profileName, isCurrent);
+                    if (!isCurrent())
+                        return;
+                    if (!ok) {
+                        ctx.ui.notify(`Profile "${profileName}" not found.`, "error");
+                        deps.updateStatus(ctx);
+                        return;
+                    }
+                    ctx.ui.notify(`Activated profile "${profileName}".`, "info");
                 }
-                await deps.promptForConfig(ctx, profileName);
-                return;
-            }
-            let recoveryUsed = false;
-            const startWithRecovery = async (options) => {
-                try {
-                    return await deps.startPolling(ctx, options);
+                else {
+                    await (deps.activateDefaultProfileConfig?.(ctx, isCurrent) ?? deps.reloadConfig());
+                    if (!isCurrent())
+                        return;
                 }
-                catch (error) {
-                    if (!deps.recoverPollingStart || recoveryUsed)
-                        throw error;
-                    const recovery = await deps.recoverPollingStart(error);
-                    if (recovery.kind === "unhandled")
-                        throw error;
-                    if (recovery.kind === "blocked") {
-                        return { ok: false, message: recovery.message };
+                if (!deps.hasBotToken()) {
+                    const botTokenDiagnostic = deps.getBotTokenDiagnostic?.();
+                    if (botTokenDiagnostic)
+                        ctx.ui.notify(botTokenDiagnostic, "error");
+                    const profileNames = deps.getProfileNames?.() ?? [];
+                    if (!profileName && profileNames.length > 0) {
+                        ctx.ui.notify(`No default Telegram profile configured. Available profiles: ${profileNames.join(", ")}. Use /telegram-connect <profileName> or /telegram-setup to create a default profile.`, "info");
+                        deps.updateStatus(ctx);
+                        return;
                     }
-                    recoveryUsed = true;
+                    await deps.promptForConfig(ctx, profileName);
+                    return;
+                }
+                let recoveryUsed = false;
+                const startWithRecovery = async (options) => {
                     try {
-                        const retry = await deps.startPolling(ctx, options);
-                        if (!retry) {
-                            return { ok: true, message: recovery.message };
+                        return await deps.startPolling(ctx, options);
+                    }
+                    catch (error) {
+                        if (!isCurrent())
+                            return;
+                        if (!deps.recoverPollingStart || recoveryUsed)
+                            throw error;
+                        deps.recordConnectionEvent?.(error, "polling-start");
+                        const recovery = await deps.recoverPollingStart(error);
+                        if (!isCurrent())
+                            return;
+                        if (recovery.kind === "unhandled")
+                            throw error;
+                        if (recovery.kind === "blocked") {
+                            return { ok: false, message: recovery.message,
+                                notice: "Telegram recovery blocked. Check /telegram-status --debug." };
+                        }
+                        recoveryUsed = true;
+                        deps.recordConnectionEvent?.(recovery.message, "recovery");
+                        try {
+                            const retry = await deps.startPolling(ctx, options);
+                            if (!isCurrent())
+                                return;
+                            if (!retry)
+                                return { ok: true, message: "Telegram bridge connected; temporary state recovered." };
+                            return {
+                                ...retry,
+                                message: retry.ok
+                                    ? "Telegram bridge connected; temporary state recovered."
+                                    : retry.message,
+                            };
+                        }
+                        catch (error) {
+                            if (!isCurrent())
+                                return;
+                            deps.recordConnectionEvent?.(error, "recovery-retry");
+                            return {
+                                ok: false,
+                                notice: "Telegram recovery failed. Restart this Pi instance.",
+                            };
                         }
-                        return {
-                            ...retry,
-                            message: retry.ok
-                                ? `${recovery.message} ${retry.message ?? "Telegram bridge connected."}`
-                                : retry.message,
-                        };
                     }
-                    catch {
-                        return {
-                            ok: false,
-                            message: "Telegram temporary state was recovered, but the bridge could not restart. Restart this Pi instance and run /telegram-connect again.",
-                        };
+                };
+                let result = await startWithRecovery({ forceFreshLeaderThread: true });
+                if (!isCurrent())
+                    return;
+                if (result && !result.ok && result.canTakeover) {
+                    const confirmed = await ctx.ui.confirm(formatTelegramTakeoverTitle(ctx), formatTelegramTakeoverPrompt(ctx, result.owner));
+                    if (!isCurrent())
+                        return;
+                    if (!confirmed) {
+                        ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
+                        deps.updateStatus(ctx);
+                        return;
                     }
+                    result = await startWithRecovery({ force: true, forceFreshLeaderThread: true });
+                    if (!isCurrent())
+                        return;
                 }
-            };
-            let result = await startWithRecovery({
-                forceFreshLeaderThread: true,
-            });
-            if (result && !result.ok && result.canTakeover) {
-                const confirmed = await ctx.ui.confirm(formatTelegramTakeoverTitle(ctx), formatTelegramTakeoverPrompt(ctx, result.owner));
-                if (!confirmed) {
-                    ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
-                    deps.updateStatus(ctx);
-                    return;
+                if (result && !result.ok) {
+                    if (result.message)
+                        deps.recordConnectionEvent?.(result.message, "connect-refused");
+                    ctx.ui.notify(result.notice ?? formatTelegramConnectionFailure(result.message), "warning");
                 }
-                result = await startWithRecovery({
-                    force: true,
-                    forceFreshLeaderThread: true,
-                });
+                else if (result?.message) {
+                    ctx.ui.notify(result.message, "info");
+                }
+                if (!result || result.ok)
+                    deps.queueAgentConnectionContext?.(true);
+                deps.updateStatus(ctx);
             }
-            if (result?.message) {
-                ctx.ui.notify(result.message, result.ok ? "info" : "warning");
+            catch (error) {
+                if (!isCurrent())
+                    return;
+                deps.recordConnectionEvent?.(error, "connect");
+                ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
+                deps.updateStatus(ctx);
             }
-            if (!result || result.ok) {
-                deps.queueAgentConnectionContext?.(true);
+            finally {
+                if (intentId)
+                    deps.connectionIntent?.finish(intentId);
             }
-            deps.updateStatus(ctx);
         },
     });
     pi.registerCommand("telegram-disconnect", {
         description: "Stop Telegram and delete current thread in Threaded Mode",
         handler: async (_args, ctx) => {
-            const threadName = deps.getDisconnectThreadName?.();
-            if (threadName) {
-                const confirmed = await ctx.ui.confirm(ctx.ui.theme.fg("accent", "pi-telegram"), `Delete Telegram thread ${ctx.ui.theme.fg("warning", threadName)} and disconnect this Pi session?`);
-                if (!confirmed) {
-                    ctx.ui.notify("Telegram disconnect cancelled.", "info");
-                    deps.updateStatus(ctx);
-                    return;
-                }
-            }
+            const generation = deps.getSessionGeneration?.();
+            const isCurrent = () => (generation === undefined || deps.getSessionGeneration?.() === generation) &&
+                deps.isContextCurrent?.(ctx) !== false;
+            if (!isCurrent())
+                return;
+            deps.connectionIntent?.cancel();
             try {
+                const threadName = deps.getDisconnectThreadName?.();
+                if (threadName) {
+                    const confirmed = await ctx.ui.confirm(ctx.ui.theme.fg("accent", "pi-telegram"), `Delete Telegram thread ${ctx.ui.theme.fg("warning", threadName)} and disconnect this Pi session?`);
+                    if (!isCurrent())
+                        return;
+                    if (!confirmed) {
+                        ctx.ui.notify("Telegram disconnect cancelled.", "info");
+                        return;
+                    }
+                }
                 const message = await deps.stopPolling();
+                if (!isCurrent())
+                    return;
                 if (message)
                     ctx.ui.notify(message, "info");
                 deps.queueAgentConnectionContext?.(false);
             }
             catch (error) {
-                const detail = error instanceof Error ? error.message : String(error);
-                ctx.ui.notify(`Telegram disconnect did not complete: ${detail} Keep this Pi session open, restore leader connectivity, inspect /telegram-status --debug, and retry /telegram-disconnect.`, "warning");
-                throw error;
+                deps.recordConnectionEvent?.(error, "disconnect");
+                if (!isCurrent())
+                    return;
+                ctx.ui.notify("Telegram disconnect incomplete; keep Pi open. Check /telegram-status --debug.", "warning");
             }
             finally {
-                deps.updateStatus(ctx);
+                if (isCurrent())
+                    deps.updateStatus(ctx);
             }
         },
     });
@@ -1294,7 +1348,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 +1366,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 +1379,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 +1397,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,
@@ -1345,6 +1361,28 @@ export default function (pi) {
         resolveAutomaticThreadCleanupEnabled: configControls.resolveAutomaticThreadCleanupEnabled,
         runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
     });
+    const connectionIntent = Lifecycle.createTelegramConnectionIntentRuntime();
+    const connectionLifecycle = Lifecycle.createTelegramConnectionLifecycle({
+        intent: connectionIntent,
+        getGeneration: telegramSessionContextStore.getGeneration,
+        isCurrent: telegramSessionContextStore.isCurrent,
+        getProfileName: configStore.getActiveProfileName,
+        isConnected() {
+            return lockRuntime.owns() || telegramBusFollowerRegistrationState.isRegistered();
+        },
+        async activateProfile(profileName, isCurrent) {
+            await configStore.load();
+            if (!isCurrent())
+                return false;
+            return configStore.activateProfile(profileName) && configStore.hasBotToken();
+        },
+        start(ctx) {
+            return lockedPollingRuntime.start(ctx);
+        },
+        recordError(error) {
+            recordRuntimeEvent("connection", error, { phase: "resume-connect" });
+        },
+    });
     const telegramBridgeSessionLifecycleDeps = Lifecycle.createTelegramBridgeSessionLifecycleDeps({
         contextStore: telegramSessionContextStore,
         queue: {
@@ -1392,6 +1430,7 @@ export default function (pi) {
             },
             delivery: deliveryLifecycleRuntime,
             polling: lockedPollingRuntime,
+            connection: connectionLifecycle,
             inboundWorker: {
                 onSessionShutdown: updateAdmissionRuntimeBinding.onSessionShutdown,
             },
@@ -1520,6 +1559,9 @@ export default function (pi) {
             modelContextAvailabilityRuntime.reconcile();
         },
         getStatusLines,
+        isContextCurrent: telegramSessionContextStore.isCurrent,
+        getSessionGeneration: telegramSessionContextStore.getGeneration,
+        connectionIntent,
         buttonActionStore,
         sendMarkdownReply,
         async sendChannelMarkdownMessage(channel, markdown, options) {

package/dist/lib/lifecycle.d.ts

@@ -1,7 +1,8 @@
 /**
- * Telegram lifecycle hook registration helpers
+ * Telegram session lifecycle coordination and hook registration
  * Zones: pi agent lifecycle, telegram session
- * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * Owns context generations, bounded connect intent across resume, and session sequencing.
+ * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 import * as BusFollower from "./bus-follower.ts";
 import * as Queue from "./queue.ts";
@@ -50,6 +51,58 @@ export interface TelegramSessionLifecycleHooks {
     onSessionStart: (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void>;
     onSessionShutdown: (event: SessionShutdownEvent, ctx: ExtensionContext) => Promise<void>;
 }
+export interface TelegramConnectionIntent {
+    id: string;
+    cwd: string;
+    profileName?: string;
+}
+interface TelegramConnectionHandoff extends TelegramConnectionIntent {
+    pid: number;
+    targetSessionFile: string;
+    expiresAtMs: number;
+}
+export interface TelegramConnectionHandoffStore {
+    pending?: TelegramConnectionHandoff;
+}
+export interface TelegramConnectionLifecycle {
+    prepare(event: SessionStartEvent, ctx: ExtensionContext): (() => void) | undefined;
+    onSessionShutdown(event: SessionShutdownEvent, ctx: ExtensionContext): void;
+}
+export declare function createTelegramConnectionLifecycle(deps: {
+    intent: ReturnType<typeof createTelegramConnectionIntentRuntime>;
+    getGeneration(): number;
+    isCurrent(ctx: ExtensionContext): boolean;
+    getProfileName(): string | undefined;
+    isConnected(): boolean;
+    activateProfile(profileName: string | undefined, isCurrent: () => boolean): Promise<boolean>;
+    start(ctx: ExtensionContext): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    recordError(error: unknown): void;
+}): TelegramConnectionLifecycle;
+export declare function createTelegramConnectionIntentRuntime(options?: {
+    store?: TelegramConnectionHandoffStore;
+    now?: () => number;
+    pid?: number;
+}): {
+    begin(cwd: string, profileName?: string): string;
+    isActive(id: string): boolean;
+    finish(id: string): void;
+    cancel(): void;
+    suspend(input: {
+        reason: string;
+        cwd: string;
+        targetSessionFile?: string;
+        connected: boolean;
+        profileName?: string;
+    }): void;
+    resume(input: {
+        reason: string;
+        cwd: string;
+        sessionFile?: string;
+    }): TelegramConnectionIntent | undefined;
+};
 export interface TelegramSessionContextStore<TContext> {
     get: () => TContext | undefined;
     getGeneration: () => number;
@@ -62,6 +115,7 @@ export declare function createTelegramSessionContextStore<TContext>(options?: {
 }): TelegramSessionContextStore<TContext>;
 export declare function createTelegramSessionGenerationFence(store: TelegramSessionContextStore<ExtensionContext>, hooks: TelegramSessionLifecycleHooks): TelegramSessionLifecycleHooks;
 export interface TelegramBridgeSessionServiceRuntime {
+    connection?: TelegramConnectionLifecycle;
     resumeGroupedInput(ctx: ExtensionContext): void;
     suspendGroupedInput(): void;
     delivery: {
@@ -108,6 +162,7 @@ export interface TelegramBridgeSessionLifecyclePorts<TQueueItem, TModel = unknow
         };
         delivery: TelegramBridgeSessionServiceRuntime["delivery"];
         polling: TelegramBridgeSessionServiceRuntime["polling"];
+        connection?: TelegramBridgeSessionServiceRuntime["connection"];
         inboundWorker: TelegramBridgeSessionServiceRuntime["inboundWorker"];
         capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
         queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];

package/dist/lib/lifecycle.js

@@ -1,8 +1,11 @@
 /**
- * Telegram lifecycle hook registration helpers
+ * Telegram session lifecycle coordination and hook registration
  * Zones: pi agent lifecycle, telegram session
- * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * Owns context generations, bounded connect intent across resume, and session sequencing.
+ * Transport authority, durable bindings, and queue custody remain with their owners.
  */
+import { randomUUID } from "node:crypto";
+import { formatTelegramConnectionFailure } from "./status.js";
 import * as BusFollower from "./bus-follower.js";
 import * as Queue from "./queue.js";
 import * as TextGroups from "./text-groups.js";
@@ -23,6 +26,98 @@ export function createAgentStartDedupHook(inner, schedulePublication) {
         return inner(event, ctx);
     };
 }
+const HANDOFF_KEY = Symbol.for("pi-telegram.connection-resume.v1");
+function processHandoffStore() {
+    const globals = globalThis;
+    return globals[HANDOFF_KEY] ??= {};
+}
+export function createTelegramConnectionLifecycle(deps) {
+    return {
+        onSessionShutdown(event, ctx) {
+            deps.intent.suspend({ reason: event.reason, cwd: ctx.cwd,
+                targetSessionFile: event.targetSessionFile, connected: deps.isConnected(),
+                profileName: deps.getProfileName() });
+        },
+        prepare(event, ctx) {
+            const intent = deps.intent.resume({ reason: event.reason, cwd: ctx.cwd,
+                sessionFile: event.reason === "resume" ? ctx.sessionManager.getSessionFile() : undefined });
+            if (!intent)
+                return undefined;
+            const generation = deps.getGeneration();
+            const isCurrent = () => deps.intent.isActive(intent.id) &&
+                generation === deps.getGeneration() && deps.isCurrent(ctx);
+            return () => {
+                // Startup remains extension-owned background work; no captured command ctx crosses resume.
+                void (async () => {
+                    if (!isCurrent())
+                        return;
+                    if (!await deps.activateProfile(intent.profileName, isCurrent)) {
+                        if (isCurrent())
+                            ctx.ui.notify("Telegram profile unavailable. Run /telegram-setup.", "warning");
+                        return;
+                    }
+                    if (!isCurrent())
+                        return;
+                    const result = await deps.start(ctx);
+                    if (!isCurrent())
+                        return;
+                    if (!result.ok) {
+                        deps.recordError(new Error(result.message ?? "Telegram resume connection failed."));
+                        ctx.ui.notify(formatTelegramConnectionFailure(result.message), "warning");
+                    }
+                })().catch((error) => {
+                    deps.recordError(error);
+                    if (isCurrent())
+                        ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
+                }).finally(() => deps.intent.finish(intent.id));
+            };
+        },
+    };
+}
+export function createTelegramConnectionIntentRuntime(options = {}) {
+    const store = options.store ?? processHandoffStore();
+    const now = options.now ?? Date.now;
+    const pid = options.pid ?? process.pid;
+    let active;
+    return {
+        begin(cwd, profileName) {
+            store.pending = undefined;
+            active = { id: randomUUID(), cwd, profileName };
+            return active.id;
+        },
+        isActive(id) {
+            return active?.id === id;
+        },
+        finish(id) {
+            if (active?.id === id)
+                active = undefined;
+        },
+        cancel() {
+            active = undefined;
+            store.pending = undefined;
+        },
+        suspend(input) {
+            const intent = active ?? (input.connected
+                ? { id: randomUUID(), cwd: input.cwd, profileName: input.profileName }
+                : undefined);
+            active = undefined;
+            store.pending = input.reason === "resume" && input.targetSessionFile &&
+                intent?.cwd === input.cwd
+                ? { ...intent, pid, targetSessionFile: input.targetSessionFile, expiresAtMs: now() + 30_000 }
+                : undefined;
+        },
+        resume(input) {
+            const handoff = store.pending;
+            store.pending = undefined;
+            if (!handoff || handoff.pid !== pid || now() >= handoff.expiresAtMs ||
+                input.reason !== "resume" || input.cwd !== handoff.cwd ||
+                input.sessionFile !== handoff.targetSessionFile)
+                return undefined;
+            active = { id: randomUUID(), cwd: handoff.cwd, profileName: handoff.profileName };
+            return { ...active };
+        },
+    };
+}
 export function createTelegramSessionContextStore(options = {}) {
     let currentContext;
     let currentIdentity;
@@ -112,6 +207,7 @@ export function createTelegramBridgeSessionLifecycleDeps(ports) {
             }),
             delivery: ports.services.delivery,
             polling: ports.services.polling,
+            connection: ports.services.connection,
             inboundWorker: ports.services.inboundWorker,
             capabilityMonitor: ports.services.capabilityMonitor,
             queueWatchdog: ports.services.queueWatchdog,
@@ -128,20 +224,27 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
         suspendPolling: deps.follower.suspendPolling,
         recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
+    let preserveTarget = true;
     const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
         ...deps.queue,
         isSessionActive,
-        stopPolling: suspendForReplacement,
+        stopPolling: () => suspendForReplacement(preserveTarget),
         clearPendingMediaGroups: deps.services.suspendGroupedInput,
     });
     const servicesLifecycle = {
         async onSessionStart(event, ctx) {
+            const resumeConnection = deps.services.connection?.prepare(event, ctx);
             await queueLifecycle.onSessionStart(event, ctx);
             if (!isSessionActive(ctx))
                 return;
             deps.services.resumeGroupedInput(ctx);
             await deps.services.delivery.onSessionStart();
-            await deps.services.polling.onSessionStart(event, ctx);
+            if (!isSessionActive(ctx))
+                return;
+            if (resumeConnection)
+                resumeConnection();
+            else
+                await deps.services.polling.onSessionStart(event, ctx);
             deps.services.capabilityMonitor.start(ctx);
             deps.services.queueWatchdog.start(ctx);
         },
@@ -150,6 +253,8 @@ export function createTelegramBridgeSessionLifecycleAssembly(deps) {
             const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
             if (!isCurrent())
                 return;
+            deps.services.connection?.onSessionShutdown(event, ctx);
+            preserveTarget = event.reason !== "resume";
             let preserveThread;
             if (event.reason === "quit") {
                 try {