@llblab/pi-kit 0.26.0 → 0.27.0

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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;

package/node_modules/@llblab/pi-telegram/dist/lib/threads.js

@@ -812,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 }
             : {}),
@@ -3599,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));
@@ -3611,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();
@@ -3691,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.");
             }
@@ -3723,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();
         }
@@ -3762,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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/dist/package.json

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

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -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

package/node_modules/@llblab/pi-telegram/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

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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?.();

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -1130,10 +1130,16 @@ function isTelegramStaleContextError(error: unknown): boolean {
 
 export function createTelegramBusFollowerSessionReplacementSuspender(
   deps: TelegramBusFollowerSessionReplacementSuspenderDeps,
-): () => Promise<void> {
+): (preserveTarget?: boolean) => Promise<void> {
   const getNowMs = deps.getNowMs ?? Date.now;
   const getPid = deps.getPid ?? (() => process.pid);
-  return async () => {
+  return async (preserveTarget = true) => {
+    if (!preserveTarget) {
+      setTelegramFollowerSessionHandoff(undefined);
+      Threads.setTelegramLeaderSessionHandoff(undefined);
+      await deps.suspendPolling();
+      return;
+    }
     const target = deps.registrationState.getTarget();
     if (deps.registrationState.isRegistered() && target) {
       setTelegramFollowerSessionHandoff({