@llblab/pi-telegram 0.51.4 → 0.51.6

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/model.js

@@ -294,10 +294,8 @@ function truncateTelegramModelSwitchStatusSummary(text, maxWords = 4, maxLength
 }
 export function buildTelegramModelSwitchContinuationText(telegramPrefix, model, thinkingLevel) {
     const modelLabel = `${model.provider}/${model.id}`;
-    const thinkingSuffix = thinkingLevel
-        ? ` Keep the selected thinking level (${thinkingLevel}) if it still applies.`
-        : "";
-    return `${telegramPrefix} Continue the interrupted previous request using the newly selected model (${modelLabel}). Resume from the last unfinished step instead of restarting from scratch unless necessary.${thinkingSuffix}`;
+    const thinkingSuffix = thinkingLevel ? `; thinking: ${thinkingLevel}` : "";
+    return `${telegramPrefix} Continue from the last unfinished step. Model: ${modelLabel}${thinkingSuffix}.`;
 }
 export function buildTelegramModelSwitchContinuationTurn(options) {
     const modelLabel = `${options.selection.model.provider}/${options.selection.model.id}`;

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/status.d.ts

@@ -1,8 +1,10 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Builds usage, cost, and context summaries for the interactive Telegram status view
+ * Owns status summaries, redacted runtime diagnostics, and compact connection-failure copy
  */
+/** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
+export declare function formatTelegramConnectionFailure(error: unknown): string;
 export type TelegramStatusQueueLane = "control" | "priority" | "default";
 export interface TelegramUsageStats {
     totalInput: number;

package/dist/lib/status.js

@@ -1,8 +1,38 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Builds usage, cost, and context summaries for the interactive Telegram status view
+ * Owns status summaries, redacted runtime diagnostics, and compact connection-failure copy
  */
+/** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
+export function formatTelegramConnectionFailure(error) {
+    const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    const status = error && typeof error === "object" && "status" in error ? error.status : undefined;
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    if (status === 401)
+        return "Telegram token rejected. Run /telegram-setup.";
+    if (status === 403)
+        return "Telegram access denied. Check /telegram-status --debug.";
+    if ((typeof code === "string" && ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET"].includes(code)) ||
+        /network unavailable|fetch failed/i.test(message)) {
+        return "Telegram network unavailable. Retry /telegram-connect.";
+    }
+    if (/Workspace slots?.*(?:unavailable|exhausted)|no free.*slot/i.test(message)) {
+        return "No Telegram slot available. Check /telegram-status --debug.";
+    }
+    if (code === "incompatible-protocol" || /protocol.*(?:incompatible|mismatch)|incompatible.*protocol/i.test(message)) {
+        return "Telegram instances are incompatible. Update them together.";
+    }
+    if (/unsupported.*(?:journal|version)|(?:journal|version).*unsupported/i.test(message)) {
+        return "Telegram state version unsupported. Use a compatible runtime.";
+    }
+    if (/follower registration failed|active in another Pi instance/i.test(message)) {
+        return "Telegram leader is active but unavailable. Check /telegram-status --debug.";
+    }
+    if (/unfinished Thread creation does not match/i.test(message)) {
+        return "Telegram Thread creation is unresolved. Check /telegram-status --debug.";
+    }
+    return "Telegram connection failed. Check /telegram-status --debug.";
+}
 const TELEGRAM_STATUS_DEFAULT_PROFILE_NAME = "default";
 const TELEGRAM_STATUS_LINE_PROVIDER_REGISTRY_KEY = "__piTelegramStatusLineProviders__";
 const MAX_RECENT_TELEGRAM_RUNTIME_EVENTS = 10;

package/dist/lib/sync.js

@@ -459,6 +459,7 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
             ? deps.topicTargetStore.getWorkspaceBinding(workspaceIdentity.cwd, workspaceIdentity.instanceSlot, workspaceIdentity.sessionId)
             : undefined;
         const legacyWorkspaceBinding = workspaceIdentity?.instanceSlot === "a" &&
+            deps.sessionId === undefined &&
             !persistedWorkspaceBinding &&
             typeof legacyLeaderRecord?.target.threadId === "number"
             ? {
@@ -553,10 +554,9 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
             return (record.instanceId === deps.instanceId &&
                 (record.status === "active" || record.status === "starting"));
         });
-        // Short-circuit: when the instance already has an active thread and we are not
-        // force-freshing, reuse it without re-provisioning. A thread belongs to the
-        // live instance binding, not to one transient Pi session lifecycle.
-        if (!deps.forceFreshUnnamed && priorTargets.length > 0) {
+        // Legacy callers without session identity may reuse the active instance target.
+        // Session-aware callers must resolve their exact Workspace binding instead.
+        if (deps.sessionId === undefined && !deps.forceFreshUnnamed && priorTargets.length > 0) {
             const record = priorTargets[0];
             deps.recordEvent("telegram", "Leader thread preserved after session lifecycle change", {
                 phase: "leader-thread-reused",

package/dist/lib/threads.d.ts

@@ -68,6 +68,7 @@ export interface TelegramThreadPendingProvision {
     owner: "leader" | "manual-follower";
     instanceId: string;
     profileKey?: string;
+    workspaceBindingKey?: string;
     status?: "in-flight" | "ambiguous";
     threadName?: string;
     displayTitle?: string;
@@ -187,6 +188,12 @@ export interface TelegramSessionReplacementIntent {
     threadName?: string;
     createdAtMs: number;
     expiresAtMs: number;
+    /**
+     * Present only when the leader published the intent for a registered
+     * follower. Successor re-key and settlement must come from this exact
+     * follower runtime or its authenticated same-process session handoff.
+     */
+    sourceInstanceId?: string;
 }
 export interface TelegramTopicTargetFile {
     version: 1;
@@ -385,6 +392,7 @@ export declare function isTelegramLeaderSessionHandoffFresh(handoff: TelegramLea
 }): handoff is TelegramLeaderSessionHandoff;
 export declare function getTelegramThreadOwnerKey(owner: TelegramThreadOwner): string;
 export declare function getTelegramThreadOwnerFromProfileKey(profileKey: string): TelegramThreadOwner;
+export declare function normalizeTelegramSessionReplacementIntent(value: unknown): TelegramSessionReplacementIntent | undefined;
 export declare function isSameTelegramProcessInstance(left: string | undefined, right: string | undefined): boolean;
 export declare function createTelegramTopicTargetStore(options: TelegramTopicTargetStoreOptions): TelegramTopicTargetStore;
 export declare function normalizeTelegramTopicTargetThreadName(threadName: string): string;

package/dist/lib/threads.js

@@ -648,7 +648,7 @@ function cloneWorkspaceBinding(binding) {
 function cloneSessionReplacementIntent(intent) {
     return { ...intent, target: { ...intent.target } };
 }
-function normalizeSessionReplacementIntent(value) {
+export function normalizeTelegramSessionReplacementIntent(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const record = value;
@@ -663,7 +663,10 @@ function normalizeSessionReplacementIntent(value) {
         typeof record.messageId !== "number" || !Number.isSafeInteger(record.messageId) ||
         typeof record.createdAtMs !== "number" || !Number.isSafeInteger(record.createdAtMs) ||
         typeof record.expiresAtMs !== "number" || !Number.isSafeInteger(record.expiresAtMs) ||
-        record.expiresAtMs <= record.createdAtMs)
+        record.expiresAtMs <= record.createdAtMs ||
+        (record.sourceInstanceId !== undefined &&
+            (typeof record.sourceInstanceId !== "string" || !record.sourceInstanceId ||
+                record.sourceInstanceId.length > 256)))
         return undefined;
     const continuity = record.continuity === "workspace-thread" ||
         record.continuity === "classic-chat"
@@ -687,6 +690,8 @@ function normalizeSessionReplacementIntent(value) {
         ...(typeof record.threadName === "string" ? { threadName: record.threadName } : {}),
         createdAtMs: record.createdAtMs,
         expiresAtMs: record.expiresAtMs,
+        ...(typeof record.sourceInstanceId === "string"
+            ? { sourceInstanceId: record.sourceInstanceId } : {}),
     };
 }
 function normalizeWorkspaceRetirementIntent(value) {
@@ -807,6 +812,9 @@ function normalizePendingProvision(value) {
         ...(record.status === "in-flight" || record.status === "ambiguous"
             ? { status: record.status }
             : {}),
+        ...(typeof record.workspaceBindingKey === "string"
+            ? { workspaceBindingKey: record.workspaceBindingKey }
+            : {}),
         ...(typeof record.threadName === "string"
             ? { threadName: record.threadName }
             : {}),
@@ -949,7 +957,7 @@ function parseTopicTargetFile(value) {
                 return normalized ? [normalized] : [];
             })
             : [],
-        sessionReplacement: normalizeSessionReplacementIntent(file.sessionReplacement),
+        sessionReplacement: normalizeTelegramSessionReplacementIntent(file.sessionReplacement),
         reservations: Array.isArray(file.reservations)
             ? file.reservations.flatMap((reservation) => {
                 const normalized = normalizeReservation(reservation);
@@ -1667,7 +1675,7 @@ export function createTelegramTopicTargetStore(options) {
                 : undefined;
         },
         async commitSessionReplacementIntent(intent, isCurrent) {
-            const next = normalizeSessionReplacementIntent(intent);
+            const next = normalizeTelegramSessionReplacementIntent(intent);
             if (!next || !isCurrent())
                 return false;
             await loadFromDisk();
@@ -2081,7 +2089,10 @@ export function createTelegramTopicTargetStore(options) {
                 replacement.expiresAtMs > getNowMs() &&
                 replacement.profileName === (getTelegramProfile() ?? "default") &&
                 replacement.cwd === normalizedCwd &&
-                replacement.sourceSessionId !== normalizedSessionId) {
+                replacement.sourceSessionId !== normalizedSessionId &&
+                (replacement.sourceInstanceId === undefined ||
+                    replacement.sourceInstanceId === instanceId ||
+                    replacement.sourceInstanceId === previousInstanceId)) {
                 const sourceEntry = Array.from(workspaceBindings.entries()).find(([, binding]) => binding.cwd === normalizedCwd &&
                     binding.sessionId === replacement.sourceSessionId &&
                     targetMatches(binding.target, replacement.target));
@@ -3591,6 +3602,12 @@ export function createTelegramTopicTargetProvisioner(deps) {
             .listPendingProvisions()
             .find((pending) => pending.profileKey === request.profileKey ||
             pending.instanceId === request.instanceId);
+        const pendingTarget = pendingForRequest?.target;
+        if (pendingForRequest && request.workspaceBindingKey &&
+            pendingForRequest.workspaceBindingKey !== request.workspaceBindingKey &&
+            !(pendingTarget && deps.store.listWorkspaceBindings().some((binding) => binding.bindingKey === request.workspaceBindingKey && targetMatches(binding.target, pendingTarget)))) {
+            throw new Error("Telegram unfinished Thread creation does not match this session binding.");
+        }
         if (pendingForRequest?.target) {
             const target = pendingForRequest.target;
             const observation = deps.store.listSyncObservations().find((entry) => targetMatches(entry.target, target));
@@ -3603,8 +3620,11 @@ export function createTelegramTopicTargetProvisioner(deps) {
                 pendingForRequest = undefined;
             }
         }
+        const matchesWorkspace = (target) => !request.workspaceBindingKey ||
+            deps.store.listWorkspaceBindings().some((binding) => binding.bindingKey === request.workspaceBindingKey && targetMatches(binding.target, target)) ||
+            (!!pendingForRequest?.target && targetMatches(pendingForRequest.target, target));
         const existing = deps.store.getByProfileKey(request.profileKey);
-        if (existing && isCurrentThreadRecord(existing)) {
+        if (existing && isCurrentThreadRecord(existing) && matchesWorkspace(existing.target)) {
             const slot = existing.slot ?? deps.store.allocateSlot(request.profileKey);
             if (!slot) {
                 throw new TelegramWorkspaceSlotUnavailableError();
@@ -3683,7 +3703,7 @@ export function createTelegramTopicTargetProvisioner(deps) {
             throw new Error(`Telegram topic provisioning remains ${pendingForRequest.status ?? "in-flight"} for this instance.`);
         }
         const activeForInstance = deps.store.getActiveByInstanceId(request.instanceId);
-        if (activeForInstance) {
+        if (activeForInstance && matchesWorkspace(activeForInstance.target)) {
             if (!activeForInstance.slot) {
                 throw new Error("Telegram Workspace slot reservation is unavailable.");
             }
@@ -3715,12 +3735,12 @@ export function createTelegramTopicTargetProvisioner(deps) {
         const preferredNameSlot = getTelegramThreadNameLeadingSlot(candidateThreadName) ??
             getNextTelegramThreadNamePaletteSlot(deps.store.list(), undefined) ??
             request.preferredSlot;
-        const slot = existing?.slot ??
+        const slot = (existing && matchesWorkspace(existing.target) ? existing.slot : undefined) ??
             deps.store.allocateSlot(request.profileKey, isManualFollowerRequest
                 ? request.preferredSlot
                 : (request.preferredSlot ??
                     (candidateThreadName ? undefined : identity?.slot) ??
-                    preferredNameSlot), request.workspaceBindingKey);
+                    preferredNameSlot), request.workspaceBindingKey, { excludeCurrentRecord: !!existing && !matchesWorkspace(existing.target) });
         if (!slot) {
             throw new TelegramWorkspaceSlotUnavailableError();
         }
@@ -3754,6 +3774,7 @@ export function createTelegramTopicTargetProvisioner(deps) {
             owner: pendingOwner,
             instanceId: request.instanceId,
             profileKey: request.profileKey,
+            ...(request.workspaceBindingKey ? { workspaceBindingKey: request.workspaceBindingKey } : {}),
             threadName: requestThreadName,
             ...(displayTitle ? { displayTitle } : {}),
             slot,

package/dist/lib/workspace-retirement.d.ts

@@ -218,7 +218,7 @@ export type TelegramWorkspaceRetirementExecution = {
 };
 export type TelegramWorkspaceRetirementAbsence = "absent" | "present" | "unknown";
 export declare function executeTelegramWorkspaceRetirement(input: {
-    store: Pick<TelegramTopicTargetStore, "captureWorkspaceSlotOccupancy" | "listWorkspaceBindings" | "listWorkspaceRetirementIntents" | "commitWorkspaceRetirement" | "removeWorkspaceRetirementIntent" | "persist">;
+    store: Pick<TelegramTopicTargetStore, "captureWorkspaceSlotOccupancy" | "listWorkspaceBindings" | "listWorkspaceRetirementIntents" | "commitWorkspaceRetirement" | "removeWorkspaceRetirementIntent" | "markStaleByTarget" | "persist">;
     admission: Pick<TelegramWorkspaceAdmissionLedger, "getOwner" | "read" | "acquireRetirementFence" | "adoptRetirementFence" | "issueDeletionPermit" | "confirmRetirementAbsence" | "confirmRetirementRejection" | "completeRejectedRetirementFence" | "releaseUnissuedRetirementFence" | "completeRetirementFence">;
     intent: TelegramWorkspaceRetirementIntent;
     getExternalProtection: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceExternalProtectionEvidence;
@@ -263,7 +263,7 @@ export type TelegramWorkspaceRetirementLifecycleResult = TelegramWorkspaceRetire
     reason: string;
 };
 export declare function runTelegramWorkspaceRetirementLifecycle(input: {
-    store: TelegramWorkspaceRetirementPreparationDeps["store"] & Pick<TelegramTopicTargetStore, "replaceWorkspaceRetirementIntent" | "commitWorkspaceRetirement">;
+    store: TelegramWorkspaceRetirementPreparationDeps["store"] & Pick<TelegramTopicTargetStore, "replaceWorkspaceRetirementIntent" | "commitWorkspaceRetirement" | "markStaleByTarget">;
     getExternalProtection: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceExternalProtectionEvidence;
     getLeaderEpoch: () => number | string | undefined;
     getProfileKey: () => string;

package/dist/lib/workspace-retirement.js

@@ -605,6 +605,12 @@ export async function executeTelegramWorkspaceRetirement(input) {
             }
             return { kind: "retained", reason: "stale-intent" };
         }
+        if (fence?.phase === "commit-ready") {
+            // Exact confirmed absence retires any same-target routing record that
+            // survived the deletion attempt. The fence prevents replacement target
+            // publication while this stale local projection is removed.
+            input.store.markStaleByTarget(binding.target, "deleted");
+        }
         const eligible = () => input.store.captureWorkspaceSlotOccupancy(input.getExternalProtection, { expectedRetirement: input.intent }).bindings.find((candidate) => candidate.bindingKey === input.intent.binding.bindingKey)?.protection === "eligible";
         if (!eligible())
             return { kind: "retained", reason: "protection-changed" };
@@ -669,6 +675,9 @@ export async function executeTelegramWorkspaceRetirement(input) {
         }
         if (!isCurrent())
             return { kind: "retained", reason: "authority-changed" };
+        if (fence.phase === "commit-ready") {
+            input.store.markStaleByTarget(binding.target, "deleted");
+        }
         if (!eligible())
             return { kind: "retained", reason: "protection-changed" };
         if (!await input.store.commitWorkspaceRetirement(input.intent, isCurrent)) {
@@ -799,19 +808,46 @@ export async function runTelegramWorkspaceRetirementLifecycle(input) {
         });
     }
     if (intent) {
-        const adoption = await adoptTelegramWorkspaceRetirementIntent({
-            store: input.store,
-            intent,
-            getExternalProtection: input.getExternalProtection,
-            getLeaderEpoch: input.getLeaderEpoch,
-            getProfileKey: input.getProfileKey,
-            isCurrent: input.isCurrent,
-            runExclusive: input.runExclusive,
-        });
-        if (adoption.kind !== "adopted") {
-            return { kind: "blocked", stage: "adoption", reason: adoption.reason };
+        if (retainedFence && isTelegramWorkspaceRetirementFence(retainedFence) &&
+            retainedFence.phase === "commit-ready" &&
+            matchesTelegramWorkspaceRetirementFence(retainedFence, intent)) {
+            const resumed = await input.runExclusive(async () => {
+                const epoch = input.getLeaderEpoch();
+                const profileKey = input.getProfileKey();
+                const isCurrent = () => epoch !== undefined && input.getLeaderEpoch() === epoch &&
+                    input.getProfileKey() === profileKey && input.isCurrent?.() !== false;
+                if (!isCurrent() || intent.profileKey !== profileKey)
+                    return undefined;
+                const intents = input.store.listWorkspaceRetirementIntents();
+                const binding = input.store.listWorkspaceBindings().find(candidate => candidate.bindingKey === intent.binding.bindingKey);
+                if (intents.length !== 1 || !isDeepStrictEqual(intents[0], intent) ||
+                    !binding || !isDeepStrictEqual(binding, intent.binding))
+                    return undefined;
+                if (intent.leaderEpoch === epoch)
+                    return intent;
+                const replacement = { ...intent, leaderEpoch: epoch };
+                return await input.store.replaceWorkspaceRetirementIntent(intent, replacement, isCurrent)
+                    ? replacement : undefined;
+            });
+            if (!resumed)
+                return { kind: "blocked", stage: "adoption", reason: "commit-rejected" };
+            intent = resumed;
+        }
+        else {
+            const adoption = await adoptTelegramWorkspaceRetirementIntent({
+                store: input.store,
+                intent,
+                getExternalProtection: input.getExternalProtection,
+                getLeaderEpoch: input.getLeaderEpoch,
+                getProfileKey: input.getProfileKey,
+                isCurrent: input.isCurrent,
+                runExclusive: input.runExclusive,
+            });
+            if (adoption.kind !== "adopted") {
+                return { kind: "blocked", stage: "adoption", reason: adoption.reason };
+            }
+            intent = adoption.intent;
         }
-        intent = adoption.intent;
     }
     else {
         const preparation = await prepareTelegramWorkspaceRetirement({

package/dist/package.json

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

package/docs/architecture.md

@@ -42,7 +42,7 @@ Keep this boundary explicit:
 
 ### Instance, Session, And Context Cost
 
-A Telegram destination follows a Pi instance, not an immutable Pi session file. Ordinary Telegram prompts enter whichever session is active in that assigned instance when dispatch occurs. If the operator replaces or resumes a session locally, pi-telegram rebinds its session-scoped runtime state while preserving the instance's Telegram target where supported. Telegram exposes compaction and new-session replacement for the active session: `/new` first completes and removes its exact durable update, then dispatches an internal registered Pi command through `pi.sendUserMessage(..., { expandPromptTemplates: true })` so the handler runs with a real `ExtensionCommandContext` and calls the same `AgentSessionRuntime.newSession()` path as the terminal. Before invoking that path, the current transport owner CAS-publishes one expiring replacement intent inside the existing profile target snapshot. The intent discriminates `workspace-thread` from `classic-chat`. A same- or cross-process successor may consume either only for the exact profile, CWD, source session, target, and fresh lifetime: Threaded continuity re-keys the retained Workspace binding and preserves Thread, slot, and display identity, while Classic continuity preserves the exact chat target without creating a Workspace binding or entering topic lifecycle APIs. A confirmed callback is acknowledged and its dialog is deleted before session replacement begins. Once the successor has delivery authority, it atomically claims the intent by CAS-clearing it and then sends one separate terminal success result with bounded in-process transport retry. The old `withSession` path never publishes success, and an unclaimed intent never sends, preventing duplicate terminal notices across same-process startup and cleanup-ack ambiguity. Mismatch or expiry never authorizes binding takeover. Resume, fork, tree navigation, session switching, and full reload remain outside the stable Telegram API until Pi exposes safe public extension hooks for them.
+Live Telegram routing belongs to the active authenticated Pi instance, while a durable Workspace Thread belongs to the exact profile/CWD/session identity. Ordinary Telegram prompts enter the session currently bound to that target. Local `/resume` replaces session-scoped runtime state and selects the destination session's binding; it never inherits the source Thread merely because the process is unchanged. Telegram exposes compaction and new-session replacement for the active session: `/new` first completes and removes its exact durable update, then dispatches an internal registered Pi command through `pi.sendUserMessage(..., { expandPromptTemplates: true })` so the handler runs with a real `ExtensionCommandContext` and calls the same `AgentSessionRuntime.newSession()` path as the terminal. Before invoking that path, the current transport owner CAS-publishes one expiring replacement intent inside the existing profile target snapshot. The intent discriminates `workspace-thread` from `classic-chat`. A same- or cross-process successor may consume either only for the exact profile, CWD, source session, target, and fresh lifetime: Threaded continuity re-keys the retained Workspace binding and preserves Thread, slot, and display identity, while Classic continuity preserves the exact chat target without creating a Workspace binding or entering topic lifecycle APIs. A confirmed callback is acknowledged and its dialog is deleted before session replacement begins. Once the successor has delivery authority, it atomically claims the intent by CAS-clearing it and then sends one separate terminal success result with bounded in-process transport retry. The old `withSession` path never publishes success, and an unclaimed intent never sends, preventing duplicate terminal notices across same-process startup and cleanup-ack ambiguity. Mismatch or expiry never authorizes binding takeover. Resume, fork, tree navigation, session switching, and full reload remain outside the stable Telegram API until Pi exposes safe public extension hooks for them.
 
 `/telegram-connect` never launches a hidden or headless Pi process. A long-lived background Pi process can own Telegram only when something else explicitly launched that process and it satisfies the normal lock/runtime rules. Pi `print` and `json` modes stay passive and exit rather than becoming hidden polling owners.
 
@@ -90,8 +90,8 @@ The repository uses a **Flat Domain DAG**:
 - `generative-apps`: managed deterministic application identity, canonical installation and explicit replacement, content-addressed module loading, state timelines, cross-process transition serialization, bounded executable-plus-argv adaptation, `telegram_bind`, and pre-model-queue `app::method` invocation. It does not own Telegram transport, arbitrary shell execution, or the external application adapted by one Generative App.
 - `outbound-attachments`: `telegram_attach`, queued outbound files, stat/limit checks, ordinary photo/document delivery, and narrow single-artifact Rich Message planning/sending for probe-confirmed photo/video/audio formats. It owns known-failure fallback eligibility and ambiguous-send no-replay classification through structural error contracts without importing Bot API helpers.
 - `channel-posts`: profile/token-bound authority for agent-authored channel publication intents, one-shot send/edit/delete fencing, outcome-unknown retention, exact successful post identity, capacity refusal, and bounded local listing. It never reads Telegram history; the composition root supplies direct-leader Bot API effects only after its durable grants.
-- `status` / `logs`: status bar/status-message rendering, queue-lane summaries, the structural redacted event ring, profile-aware JSONL scope/reset/append behavior, exact-owner destructive commits, fail-soft synchronous and queued diagnostics persistence, status snapshot scheduling, and grouped diagnostics. `status` remains a structural leaf; `logs` composes filesystem evidence with status projections and contains every persistence failure so diagnostics cannot terminate or poison the runtime queue.
-- `bindings` / `lifecycle` / `prompts` / `prompt-templates` / `pi`: Pi-facing command/tool/hook registration and cohesive cross-domain binding assembly, including queue mutation/dispatch/watchdog composition over admission and transport ports; session-generation fencing and start/shutdown sequencing across Queue, grouped input, Delivery, polling, capability monitor, follower refresh, and assistant-output projection; Telegram prompt guidance; prompt-template discovery/expansion; and centralized direct Pi SDK imports.
+- `status` / `logs`: status bar/status-message rendering, queue-lane summaries, the structural redacted event ring, profile-aware JSONL scope/reset/append behavior, exact-owner destructive commits, fail-soft synchronous and queued diagnostics persistence, status snapshot scheduling, grouped diagnostics, and allowlisted compact connection-failure copy shared by commands and lifecycle. `status` remains a structural leaf; `logs` composes filesystem evidence with status projections and contains every persistence failure so diagnostics cannot terminate or poison the runtime queue.
+- `bindings` / `lifecycle` / `prompts` / `prompt-templates` / `pi`: Pi-facing command/tool/hook registration and cohesive cross-domain binding assembly, including queue mutation/dispatch/watchdog composition over admission and transport ports; session-generation fencing and start/shutdown sequencing across Queue, grouped input, Delivery, polling, capability monitor, follower refresh, and assistant-output projection; Telegram prompt guidance; prompt-template discovery/expansion; and centralized direct Pi SDK imports. `lifecycle` also owns bounded same-process connect intent across local `/resume`, cancellation/supersession, and fresh-context startup scheduling; it does not own transport authority, durable bindings, queue custody, or source-target continuity.
 - `command-templates`: shell-free command-template helpers, composition expansion, placeholder substitution, executable resolution, warnings, and retry/timeout semantics.
 
 ### Host Compatibility Boundary
@@ -326,14 +326,15 @@ Read-only migration probes constrain that comparison. Publishing a v2 snapshot o
 ### Runtime Ownership
 
 - `/telegram-connect` acquires or moves the active profile's owner slot before polling starts. `/telegram-disconnect` keeps its destructive confirmation, then stops polling and releases only that exact slot. In Threaded Mode it tears down the disconnecting instance's bound Telegram thread: leaders delete their own thread directly, and followers send an authenticated exact-generation disconnect envelope and wait for confirmed leader cleanup before unregistering. Graceful Pi `quit` always preserves the owner slot as restart intent, allowing a reopened same-`cwd` session to reclaim the stale lease. When `threads.automaticCleanup` is enabled (the default), quit also deletes the bound Telegram tab without releasing that restart intent; disabling it preserves the tab. After delivery, polling and inbound-worker shutdown complete, a quitting leader detaches its exact owner record under profile admission while retaining the Workspace, letter and restart ownership. Publication rechecks the captured session generation, profile, leader epoch and successful current-generation suspension; unfinished startup/teardown, unproven suspension and pending cleanup stay protected. Preparation/publication errors are diagnostic and cannot block remaining session cleanup. Failed automatic deletion likewise falls back to safe suspension.
-- Session start schedules polling resume asynchronously only when the owner slot already points at the current `pid`/`cwd`, or when a stale same-`cwd` owner can be safely replaced after process restart. Under a live foreign leader, startup instead attempts capability-gated restore-only follower admission when the selected profile has a remembered exact-`cwd` Workspace binding; it never provisions an unremembered Workspace. Startup and `/resume` do not wait on leader election, Bot API probes, poller handoff, or thread reconciliation before restoring the Pi session.
+- Without an explicit carried connection intent, session start schedules polling resume asynchronously only when the owner slot already points at the current `pid`/`cwd`, or when a stale same-`cwd` owner can be safely replaced after process restart. Under a live foreign leader, startup instead attempts capability-gated restore-only follower admission when the selected profile has a remembered exact-`cwd` Workspace binding; it never provisions an unremembered Workspace. Startup and `/resume` do not wait on leader election, Bot API probes, poller handoff, or thread reconciliation before restoring the Pi session.
+- On local `/resume`, an in-flight `/telegram-connect` or established connection supplies one process-local, 30-second intent containing the selected profile, exact CWD and target session file. The file matches only the lifecycle successor; the fresh public session ID still owns binding selection. Startup claims intent before asynchronous initialization and uses the normal connection path instead of concurrent auto-restore. Quit/reload/disconnect, mismatch, expiry or supersession cancel it. The predecessor carries no Pi context, callback, Thread or slot, and late completion can clear only its own attempt. Resume startup has no automatic forced takeover or repeated failure retry; errors remain diagnostic with a compact recovery notice.
 - The polling owner alone bounds `getUpdates`: each request derives its cancellation budget from Telegram's declared long-poll timeout plus 10 seconds of transport grace (10 seconds for the zero-timeout initial sync and 40 seconds for the normal 30-second poll). The request-local controller inherits poller cancellation, rejects its owner at the budget, and fences any late transport result. Ordinary Bot API and media operations do not receive speculative blanket deadlines. Existing caller signals remain authoritative through API retry waits, only retry-safe methods replay explicit retryable responses, and non-idempotent sends preserve commit-unknown evidence instead of risking duplicate mutation.
 - Ten consecutive `getUpdates` conflict responses, including initial cursor sync, terminate polling with `persistent-conflict`; a successful response or a different error resets the count. The controller detaches its inner promise before notifying the locked lifecycle, avoiding teardown waiting on itself. That lifecycle stops ownership checks, lease refresh, capability monitoring, typing, and classic or bus transport (including leader health, pruning, and IPC), withdraws local direct authority, and transactionally releases only its exact lock. A failed durable release leaves local authority revoked; explicit reacquisition mints a fresh epoch. Accepted queue receipts and local Pi dispatch survive. One terminal diagnostic distinguishes lost local ownership from a competing client despite an apparently owned lock and reports cleanup failures; ordinary status refreshes retain generic `error` until transport recovers. Remove the competing client, then use `/telegram-connect`; no automatic retry continues after the terminal threshold.
 - Manual and automatic polling starts share a lifecycle generation. A later suspend, disconnect, persistent-conflict stop, or accepted start invalidates older startup continuations; reconnect captures its generation before waiting for transport teardown and rechecks it before acquiring ownership and after awaited startup work. Obsolete completion or failure cannot report a successful connection or roll back a replacement. Admission rejects stale/unauthorized contexts before advancing its own startup generation, so a rejected call cannot cancel valid in-flight initialization. After awaited bus startup, thread-aware completion checks its generation before starting leader health or changing fallback/startup-option state; teardown clears health independently of the current mode flag. Startup probes, capability-monitor transitions, and observed-target transitions share an orchestration lifecycle fence and check it inside their effect-owning helpers after awaited queries, persistence, or transport work. Monitor stop also invalidates pending observations. These checks suppress subsequent state changes, fallback, health, and status effects; already-issued API/persistence calls retain their own transport/storage fencing.
 - `pollingActive` reports only whether this runtime still owns an unresolved polling lifecycle; it is not health evidence. A separate observable state records `starting`, `long-poll`, `persisting-journal`, `persisting-offset`, `retrying`, or `stopped`, together with phase start, current update id, last successful response time/count, and terminal stop reason. This distinguishes a stuck HTTP poll from downstream update work without a wall-clock stale heuristic.
 - Built-in read-only menu commands return after required local mutation and schedule context-fenced rendering and command synchronization independently, so those effects cannot withhold the next inbound offset.
 - Pi `print`/`json` run modes stay passive. Inherited child sessions that share `telegram.json` but do not own the exact `pid`/`cwd` slot must not poll or call `getUpdates` unless the operator force-takes ownership.
-- Session replacement through `reload`, `new`, `resume`, or `fork` suspends polling/watchers without releasing ownership or publishing inactivity so the next session in the same process can resume. Late shutdown cannot clear a replacement context even when its identity is reused: the captured session generation must still match. A registered follower snapshots its assigned target into a short-lived same-process handoff, stops the old receiver/heartbeat, and re-registers through the live leader without marking or replacing its Telegram thread. Hard process termination cannot run graceful teardown, so stale recovery retains its restart-hint path.
+- Session replacement through `reload`, `new`, `resume`, or `fork` suspends polling/watchers without releasing ownership or publishing inactivity so the next session in the same process can resume. Late shutdown cannot clear a replacement context even when its identity is reused: the captured session generation must still match. For replacements other than `/resume`, a registered follower snapshots its assigned target into a short-lived same-process handoff, stops the old receiver/heartbeat, and re-registers through the live leader without marking or replacing its Telegram thread. Local `/resume` suppresses that source-target handoff and selects the destination session's binding instead. Hard process termination cannot run graceful teardown, so stale recovery retains its restart-hint path.
 - Live external owners require explicit takeover confirmation. Long-lived timers compare against snapshotted owner identity and stop local transport work when the slot no longer matches.
 - `owners.json` owns only Telegram transport control. Local extension and accepted queue state remain per Pi instance when ownership moves, but previews, final delivery, dispatch transport mutations, and delayed Bot API work fail closed until exact direct or follower authority becomes valid again.
 - Exact ownership remains checked every second, while the durable owner heartbeat refresh runs every two seconds and becomes stale after eight seconds. This keeps replacement detection responsive while halving steady-state atomic `owners.json` rewrites without changing the cross-platform file-transaction authority. Every acquisition, refresh, release, takeover, and stale recovery serializes through the sibling `owners.json.transaction` guard. The guard publishes one private generation-named owner record atomically, validates filename/payload generation agreement, fences stale recovery and delayed release against replacement-owner ABA, and fails closed on malformed state, unverifiable ownership, contention timeout, or unsupported filesystem behavior. The JSON store publishes through a private same-directory temporary file and atomic rename; atomic payload replacement does not replace transaction serialization.

package/docs/multi-instance-bus.md

@@ -83,7 +83,7 @@ Threaded Mode meaning:
 tmp/telegram/owners.json / <profile-slot> -> bus leader identity + heartbeat
 ```
 
-Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Pi session replacement (`new`) changes follower agent context, not bus membership: a registered follower preserves its registration and refreshes the live context instead of disconnecting. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains an exact-`cwd` Workspace binding. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
+Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Pi session replacement (`new`) changes follower agent context, not bus membership: a registered follower preserves its registration and refreshes the live context instead of disconnecting. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains a Workspace binding for the exact `cwd` and session ID. The recent-event log distinguishes missing session bindings, disabled Threaded Mode, leader-side restore refusal, and a restore that returned without connecting; none of these refusals silently provisions a new Thread. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
 
 The assembled follower receiver admits a registration generation only after its journal-binding preparation succeeds for the same generation and current Pi context. Registration identity is available during preparation so the worker can bind, but early inbound delivery receives a negative ACK rather than writing into a retained old journal. Readiness also binds the Pi session generation, so a reused context object cannot preserve it across session replacement. A registered follower's session refresh awaits binding preparation through `setContext` without re-registering or changing its bus generation. Preparation failure keeps inbound delivery unavailable and records a diagnostic; a later refresh can retry. Normal delivery retry proceeds after successful preparation. Registration requests also retain their original Pi session generation and local attempt authority across awaits. A late reply after session drift, stop or a newer request cannot publish success or tear down newer local authority; a context refresh likewise protects its retained membership from an older pending request. This refusal does not undo remote Thread provisioning or authorize deletion.
 
@@ -208,6 +208,8 @@ The persisted binding stores the exact session ID and derives its new binding ke
 
 Legacy cwd-only bindings remain exact compatibility identities whose absent session component is itself a unique key. They are neither wildcard session bindings nor adoption candidates: session-aware claims never stamp, migrate, consume, or restore them, and instead allocate their own `{ cwd, sessionId }` binding subject to the same global slot and protection rules. `{ cwd, ∅ }`, `{ cwd, session-a }`, and `{ cwd, session-b }` may coexist as majestic degradation for older state and peers. The 0.46 runtime reads strict legacy records as inert independent `{ cwd, ∅ }` bindings but never migrates, adopts, or routes a session through them. Protocol v2 is session-native and intentionally incompatible with protocol-v1 0.45.x peers. Upgrade requires stopping all Telegram instances first, updating them together, and then starting them again; the first v2 process becomes leader with its own session-qualified binding.
 
+Local `/resume` suppresses the same-process source-target handoff. A carried explicit connect intent or established connection starts the destination through normal owner acquisition/follower registration before ordinary auto-restore; it restores that session's exact binding or provisions a new one. Pending Thread-creation evidence records its Workspace binding key. Recovery rejects a different or unproven session key without consuming evidence or repeating creation; legacy pending evidence is reusable only when its target already proves the exact requested binding. Profile/CWD equality and a shared PID never authorize session reassignment. Telegram `/new` remains the separately authenticated, durable continuity exception described above.
+
 Routing authority remains the authenticated live owner plus exact numeric Telegram target. Session identity selects and restores a durable binding but never authorizes message delivery by itself. Slot pressure and retirement continue to operate on exact binding snapshots; they must carry the session component so cleanup, displacement, and letter reuse cannot target another session in the same directory.
 
 ## Leader Election
@@ -226,7 +228,7 @@ Followers first try to re-register after leader reload or unknown-heartbeat resp
 
 ### Protocol identity and compatibility
 
-The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding.
+The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding. `session-replacement-intent-v1` gates Telegram `/new` from a follower Thread: followers never write `state.json`, so `follower.publishSessionReplacement` asks the leader to CAS-publish the durable intent only when the live registration generation, leader epoch, Profile, exact `cwd`, source session, Thread target, and the leader's own Workspace binding slot/name all match, with a bounded unexpired TTL. The intent records the source runtime instance; only a successor registration from that instance or its authenticated same-process handoff (`previousInstanceId`) may re-key the binding, and `follower.settleSessionReplacement` claims it once only after the leader's store shows that successor session bound to the same target. A missing capability, stale generation, or mismatch fails the command closed.
 
 Negotiated identities remain on the live follower registry and appear in `/telegram-status --debug` plus the observational state snapshot. The Threaded Mode capability monitor owns one in-flight probe across lifecycle generations: stop/restart invalidates a late read, and a replacement monitor waits for the previous request to settle instead of creating overlapping transport transitions. Durable follower admission is authorized only when both peers advertise `durable-follower-admission-v1`, never inferred from package version: a capable runtime rejects missing support before provisioning, inbound routing, or election-roster eligibility. Authentication and exact registration generation remain mandatory independently of protocol compatibility. `follower.register` is the explicit bootstrap request and may provision; capability-gated `follower.restoreWorkspace` is startup-only and may claim, probe, or replace a remembered binding but returns `workspace-binding-unavailable` without allocating when no binding or claim-fenced legacy exact-`cwd` record exists. Both carry a fresh generation; every later request is exact-generation-fenced against the live registry entry. `bus.ack` is response-only and is rejected if submitted as a server request. Leader forwarding never synthesizes authority for an unknown recipient and preserves the follower's exact durable receipt end to end.
 

package/docs/public-api.md

@@ -40,8 +40,8 @@ import {
 Stable commands inside Pi:
 
 - `/telegram-setup` — configure/update the bot token.
-- `/telegram-connect` — start polling here and acquire external Telegram control ownership, optionally for a named profile. Thread names are configured from Telegram rather than Pi commands. Accepted queue/reply state stays local if ownership later moves elsewhere. A successful command queues a hidden connection-state note for delivery with the agent's next turn without triggering one; it says Telegram is connected and that connectivity alone is not user intent.
-- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. A successful command queues the corresponding hidden, non-triggering disconnected context note; cancelled or failed disconnects do not publish a false state transition. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while `reload`, `new`, `resume`, and `fork` preserve same-process handoff.
+- `/telegram-connect` — start polling here and acquire external Telegram control ownership, optionally for a named profile. Thread names are configured from Telegram rather than Pi commands. Accepted queue/reply state stays local if ownership later moves elsewhere. A successful command queues a hidden connection-state note for delivery with the agent's next turn without triggering one; it says Telegram is connected and that connectivity alone is not user intent. An immediate local `/resume` carries pending connection intent and the selected profile to the destination session without carrying the source Thread; its own binding is restored or allocated through normal authority checks. Connection failures produce one compact cause/action notice instead of rethrowing raw exception text into Pi; redacted technical evidence remains available through `/telegram-status --debug`.
+- `/telegram-disconnect` — after destructive confirmation, stop polling and release ownership without deleting or silencing accepted local queue state. A successful command queues the corresponding hidden, non-triggering disconnected context note; cancelled or failed disconnects do not publish a false state transition. In Threaded Mode it deletes this instance's current Telegram thread; a follower waits for its active leader to confirm generation-fenced cleanup before stopping. Graceful Pi `quit` performs the same teardown without prompting, while session replacement suspends transport without disconnect teardown. Local `/resume` carries connection intent rather than the source Thread; other supported replacements retain their existing continuity rules.
 - `/telegram-status` — show connection, polling, execution, queue, and recent event diagnostics; debug output separates poller and worker progress, durable automatic-retry state, exact foreign queued-owner identity, and negotiated protocol/build/capabilities.
 
 ### Telegram commands
@@ -51,7 +51,7 @@ Stable commands inside Pi:
 Stable commands inside the paired Telegram DM:
 
 - `/start` — pair when needed and open the main application menu.
-- `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches one runtime-armed typed action through the internal `/telegram-internal` Pi gateway using `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Manual invocation reports that the gateway cannot be run manually; the armed handler receives a real `ExtensionCommandContext` and calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. Busy, identity-mismatch, and unavailable-host paths fail closed.
+- `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches one runtime-armed typed action through the internal `/telegram-internal` Pi gateway using `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Manual invocation reports that the gateway cannot be run manually; the armed handler receives a real `ExtensionCommandContext` and calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. In a follower Thread the leader publishes and claims the intent on the follower's behalf over capability-gated, exact-generation local bus requests; followers never persist leader-owned state. Busy, identity-mismatch, stale-registration, incompatible-leader, and unavailable-host paths fail closed.
 - `/compact` — open confirmation and compact when idle.
 - `/next` — abort active work first when needed, attempt the interrupted prompt's abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. That dispatch notice owns the turn's one reply header; later answer messages do not reply to the same prompt again. Abort-notice failure is diagnostic and cannot block dispatch. A later `/abort` or `/stop` cancels both pending transition notices before taking ownership. The `/next` command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.

package/docs/ui-style.md

@@ -218,6 +218,10 @@ Examples:
 - Main menu → Settings: first row is `⬆️ Main menu`.
 - Settings → Voice reply mode: first row is `⬆️ Back`.
 
+## Pi Connection Notices
+
+Pi TUI connection notices use plain text: a short known cause and one recovery action. Unknown failures use a generic connection-failed notice with `/telegram-status --debug`; never interpolate raw exceptions, credentials, stack traces or Pi lifecycle guidance. Technical evidence belongs in the redacted runtime recorder. Failed disconnect must retain the instruction to keep Pi open; do not also rethrow the same error as a second Pi banner. These TUI notices are distinct from Telegram bot message cards below.
+
 ## Message Cards
 
 Message cards and standalone informational notices sent by the bot should start with a strong heading.

package/lib/bindings.ts

@@ -602,6 +602,9 @@ interface TelegramCommandsAndToolsBindingDeps {
       | undefined,
   ) => void;
   updateStatus: TelegramBridgeStatusUpdater;
+  isContextCurrent: (ctx: Pi.ExtensionContext) => boolean;
+  getSessionGeneration: () => number;
+  connectionIntent: NonNullable<Commands.TelegramBridgeCommandRegistrationDeps["connectionIntent"]>;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
 
@@ -633,6 +636,9 @@ export function registerTelegramCommandsAndTools({
   setGenerativeAppLiveSurfaceRuntime,
   recordRuntimeEvent,
   updateStatus,
+  isContextCurrent,
+  getSessionGeneration,
+  connectionIntent,
 }: TelegramCommandsAndToolsBindingDeps): void {
   GenerativeApps.registerTelegramBindTool(pi, {
     agentDir,
@@ -783,38 +789,39 @@ export function registerTelegramCommandsAndTools({
     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();
       if (!storedConfig.profiles?.[profileName]) return false;
       if (previousProfileName !== profileName) {
         await (stopPolling ?? lockedPollingRuntime.stop)();
+        if (!isCurrent()) return false;
       }
       if (!configStore.activateProfile(profileName)) return false;
       await onTransportChanged?.();