@llblab/pi-kit 0.23.2 → 0.24.1

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

@@ -9,7 +9,7 @@ import { createTelegramThreadDisplayReconciler, resolveTelegramInitialWorkspaceD
 import * as ThreadReconciler from "./thread-reconciler.js";
 import { getTelegramApiErrorRequestTarget, isTelegramApiCommitUnknownError, } from "./telegram-api.js";
 import * as Threads from "./threads.js";
-import { createTelegramBusLocalServer, createUnauthorizedBusAck, getTelegramBusEnvelopeTrafficClass, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, getTelegramBusFollowerSocketPath, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, } from "./bus.js";
+import { createTelegramBusLocalServer, createUnauthorizedBusAck, getTelegramBusEnvelopeTrafficClass, getTelegramBusProtocolCompatibility, hasTelegramBusCapability, isTelegramBusEnvelopeAuthorized, getTelegramBusFollowerSocketPath, sendTelegramBusLocalEnvelope, stripTelegramBusApiMetadata, TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION, TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF, TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT, TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME, TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE, TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT, } from "./bus.js";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.js";
 import { createTelegramWorkspaceOperationRuntime, createTelegramWorkspaceSlotRotation, } from "./workspace-retirement.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
@@ -27,6 +27,75 @@ function formatTelegramBusInstanceLabel(input) {
         return escapeHtml(threadName);
     return input.slot && /^[A-Z]$/.test(input.slot) ? input.slot : "?";
 }
+/**
+ * Leader-owned durable session-replacement authority for registered followers.
+ * Followers cannot persist `state.json`; the leader validates the request
+ * against its live registry entry and authoritative Workspace binding before
+ * one CAS publication or claim. Follower memory is never accepted as binding
+ * evidence.
+ */
+export function createTelegramBusFollowerSessionReplacementAuthority(deps) {
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const ttlMs = deps.ttlMs ?? Threads.TELEGRAM_LEADER_SESSION_HANDOFF_TTL_MS;
+    const assertCommon = (follower, intent) => {
+        const cwd = follower.cwd
+            ? Threads.normalizeTelegramWorkspacePath(follower.cwd)
+            : undefined;
+        const sessionId = follower.sessionId
+            ? Threads.normalizeTelegramSessionId(follower.sessionId)
+            : undefined;
+        const nowMs = getNowMs();
+        if (intent.continuity !== "workspace-thread" ||
+            typeof intent.target.threadId !== "number" ||
+            follower.target?.chatId !== intent.target.chatId ||
+            follower.target.threadId !== intent.target.threadId ||
+            !cwd || cwd !== intent.cwd || !sessionId ||
+            intent.profileName !== (deps.getTelegramProfile?.() ?? "default")) {
+            throw new Error("Telegram session replacement does not match the current follower registration.");
+        }
+        if (intent.expiresAtMs <= nowMs || intent.expiresAtMs > nowMs + ttlMs) {
+            throw new Error("Telegram session replacement intent is expired or unbounded.");
+        }
+        return { cwd, sessionId };
+    };
+    return {
+        async publish(follower, intent, isCurrent) {
+            const { sessionId } = assertCommon(follower, intent);
+            if (intent.sourceInstanceId !== follower.instanceId ||
+                intent.sourceSessionId !== sessionId) {
+                throw new Error("Telegram session replacement source does not match the current follower registration.");
+            }
+            await deps.store.load();
+            if (!isCurrent())
+                return false;
+            const binding = deps.store.getWorkspaceBindingByTarget(intent.target);
+            if (!binding || binding.cwd !== intent.cwd ||
+                binding.sessionId !== intent.sourceSessionId ||
+                binding.slot !== intent.slot ||
+                (binding.manualThreadName ?? binding.threadName) !== intent.threadName) {
+                throw new Error("Telegram session replacement binding is unavailable.");
+            }
+            return deps.store.commitSessionReplacementIntent(intent, isCurrent);
+        },
+        async settle(follower, intent, isCurrent) {
+            const { sessionId } = assertCommon(follower, intent);
+            if (!intent.sourceInstanceId ||
+                (intent.sourceInstanceId !== follower.instanceId &&
+                    intent.sourceInstanceId !== follower.previousInstanceId) ||
+                intent.sourceSessionId === sessionId) {
+                throw new Error("Telegram session replacement successor does not match the current follower registration.");
+            }
+            await deps.store.load();
+            if (!isCurrent())
+                return false;
+            if (deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd !==
+                intent.cwd) {
+                throw new Error("Telegram session replacement successor binding is unavailable.");
+            }
+            return deps.store.removeSessionReplacementIntent(intent, isCurrent);
+        },
+    };
+}
 export function createTelegramBusLeaderRuntimeAssembly(deps) {
     const runWorkspaceAdmission = deps.getWorkspaceAdmission
         ? (input, operation) => {
@@ -327,6 +396,11 @@ export function createTelegramBusLeaderRuntimeAssembly(deps) {
             }
         });
     });
+    const followerSessionReplacement = createTelegramBusFollowerSessionReplacementAuthority({
+        store: deps.topicTargetStore,
+        getTelegramProfile: deps.getTelegramProfile,
+        getNowMs: deps.runtime.getNowMs,
+    });
     const runtime = createTelegramBusLeaderRuntime({
         ...deps.runtime,
         applyThreadDisplayMode,
@@ -427,6 +501,16 @@ export function createTelegramBusLeaderRuntimeAssembly(deps) {
                 }
             });
         }),
+        publishFollowerSessionReplacement: (follower, intent, isCurrent) => runWorkspaceOperation({
+            operationId: createTelegramWorkspaceAdmissionOperationId(),
+            operationKind: "workspace.publish-follower-session-replacement",
+            scopes: [{ kind: "profile" }],
+        }, () => followerSessionReplacement.publish(follower, intent, isCurrent)),
+        settleFollowerSessionReplacement: (follower, intent, isCurrent) => runWorkspaceOperation({
+            operationId: createTelegramWorkspaceAdmissionOperationId(),
+            operationKind: "workspace.settle-follower-session-replacement",
+            scopes: [{ kind: "profile" }],
+        }, () => followerSessionReplacement.settle(follower, intent, isCurrent)),
         onFollowerConfirmedDead: async (follower) => {
             await runWorkspaceOperation({
                 operationId: createTelegramWorkspaceAdmissionOperationId(),
@@ -1796,6 +1880,63 @@ export function createTelegramBusLeaderEnvelopeHandler(deps) {
                     }
                 });
             }
+            case "follower.publishSessionReplacement":
+            case "follower.settleSessionReplacement": {
+                const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
+                return runFollowerMutation(registeredFollower ?? { instanceId: envelope.instanceId }, async () => {
+                    const publish = envelope.kind === "follower.publishSessionReplacement";
+                    const operation = publish
+                        ? deps.publishFollowerSessionReplacement
+                        : deps.settleFollowerSessionReplacement;
+                    const epoch = deps.getCurrentLeaderEpoch?.();
+                    const follower = deps.followerRegistry.get(envelope.instanceId);
+                    const isCurrent = () => epoch !== undefined &&
+                        deps.getCurrentLeaderEpoch?.() === epoch &&
+                        deps.followerRegistry.get(envelope.instanceId)?.registrationGeneration ===
+                            envelope.registrationGeneration;
+                    if (!follower?.registrationGeneration ||
+                        follower.registrationGeneration !== envelope.registrationGeneration ||
+                        !isCurrent() || !operation ||
+                        !hasTelegramBusCapability(deps.protocolIdentity, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT) ||
+                        !hasTelegramBusCapability(follower.protocol, TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT)) {
+                        return {
+                            kind: "bus.ack",
+                            requestId: envelope.requestId,
+                            ok: false,
+                            message: "Telegram session replacement requires current follower registration and compatible leader authority.",
+                        };
+                    }
+                    try {
+                        const committed = await operation(follower, envelope.intent, isCurrent);
+                        if (!committed || !isCurrent()) {
+                            return {
+                                kind: "bus.ack",
+                                requestId: envelope.requestId,
+                                ok: false,
+                                message: publish
+                                    ? "Telegram session replacement intent was not persisted."
+                                    : "Telegram session replacement intent was not claimed.",
+                            };
+                        }
+                        return {
+                            kind: "bus.ack",
+                            requestId: envelope.requestId,
+                            ok: true,
+                            result: { committed: true },
+                        };
+                    }
+                    catch (error) {
+                        return {
+                            kind: "bus.ack",
+                            requestId: envelope.requestId,
+                            ok: false,
+                            message: error instanceof Error
+                                ? error.message
+                                : "Telegram session replacement request failed.",
+                        };
+                    }
+                });
+            }
             case "follower.disconnect": {
                 const registeredFollower = deps.followerRegistry.get(envelope.instanceId);
                 return runFollowerMutation(registeredFollower ?? { instanceId: envelope.instanceId }, async () => {
@@ -2303,6 +2444,8 @@ export function createTelegramBusLeaderRuntime(deps) {
         onFollowerDisconnected: deps.onFollowerDisconnected,
         renameFollowerThread: deps.renameFollowerThread,
         resetFollowerThreadName: deps.resetFollowerThreadName,
+        publishFollowerSessionReplacement: deps.publishFollowerSessionReplacement,
+        settleFollowerSessionReplacement: deps.settleFollowerSessionReplacement,
         getFollowerDisplayTitle: deps.getFollowerDisplayTitle,
         onFollowerRegistered: deps.onFollowerRegistered,
         applyThreadDisplayMode: deps.applyThreadDisplayMode,

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

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

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

@@ -15,6 +15,7 @@ import { classifyTelegramBusTransportError, createTelegramBusTransportTimeoutErr
 import { TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS, TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES, } from "./queue.js";
 import { isProcessAlive } from "./locks.js";
 import { resolveAgentDir } from "./paths.js";
+import { normalizeTelegramSessionReplacementIntent, } from "./threads.js";
 function readDarwinProcessStart(pid) {
     return execFileSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], {
         encoding: "utf8",
@@ -124,6 +125,7 @@ export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME = "workspace-thread
 export const TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE = "thread-display-mode-v1";
 export const TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT = "directory-display-format-v1";
 export const TELEGRAM_BUS_CAPABILITY_WORKSPACE_FOLLOWER_AUTO_CONNECT = "workspace-follower-auto-connect-v1";
+export const TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT = "session-replacement-intent-v1";
 export function createTelegramBusProtocolIdentity(input) {
     const runtimeBuild = input.runtimeBuild.trim();
     if (!runtimeBuild || runtimeBuild.length > 128) {
@@ -505,6 +507,23 @@ export function parseTelegramBusEnvelope(line) {
             }
             break;
         }
+        case "follower.publishSessionReplacement":
+        case "follower.settleSessionReplacement": {
+            const intent = normalizeTelegramSessionReplacementIntent(value.intent);
+            if (typeof value.instanceId === "string" &&
+                typeof value.registrationGeneration === "string" &&
+                typeof value.sentAtMs === "number" && intent) {
+                envelope = {
+                    kind,
+                    requestId,
+                    instanceId: value.instanceId,
+                    registrationGeneration: value.registrationGeneration,
+                    intent,
+                    sentAtMs: value.sentAtMs,
+                };
+            }
+            break;
+        }
         case "leader.forwardCallback":
             envelope = parseForwardCallbackEnvelope(value, requestId);
             break;

package/node_modules/@llblab/pi-telegram/dist/lib/commands.d.ts

@@ -645,6 +645,19 @@ export interface TelegramSessionActionAssemblyDeps {
     };
     getProfileName: () => string | undefined;
     ownsPersistence: () => boolean;
+    /**
+     * Registered-follower port. A follower cannot persist leader-owned state, so
+     * its Workspace Thread intent is published and claimed by the leader over
+     * authenticated generation-fenced bus RPC.
+     */
+    follower?: {
+        instanceId: string;
+        isRegisteredFor: (target: {
+            chatId: number;
+            threadId?: number;
+        }) => boolean;
+        requestSessionReplacement: (operation: "publish" | "settle", intent: TelegramSessionReplacementIntent) => Promise<boolean>;
+    };
     sendResult: (target: {
         chatId: number;
         threadId?: number;

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

@@ -1294,7 +1294,15 @@ export function createTelegramSessionActionAssembly(deps) {
         sendUserMessage: deps.sendUserMessage,
         notifyResult(target, result) { return sendTerminalResult(target, result); },
         async prepareReplacement(ctx, updateId, target) {
-            await deps.store.load();
+            const follower = !deps.ownsPersistence() && typeof target.threadId === "number" &&
+                deps.follower?.isRegisteredFor(target)
+                ? deps.follower
+                : undefined;
+            // Follower memory is not authority; reread the leader-published snapshot.
+            if (follower && deps.store.refresh)
+                await deps.store.refresh();
+            else
+                await deps.store.load();
             const sessionId = ctx.sessionManager.getSessionId();
             const binding = typeof target.threadId === "number"
                 ? deps.store.getWorkspaceBindingByTarget(target)
@@ -1304,7 +1312,7 @@ export function createTelegramSessionActionAssembly(deps) {
                 throw new Error("Telegram session replacement binding is unavailable.");
             }
             const createdAtMs = now();
-            if (!await deps.store.commitSessionReplacementIntent({
+            const intent = {
                 continuity: binding ? "workspace-thread" : "classic-chat",
                 cwd: binding?.cwd ?? ctx.cwd,
                 profileName: deps.getProfileName() ?? "default",
@@ -1317,7 +1325,11 @@ export function createTelegramSessionActionAssembly(deps) {
                     ? { threadName: binding.manualThreadName ?? binding.threadName } : {}),
                 createdAtMs,
                 expiresAtMs: createdAtMs + deps.handoffTtlMs,
-            }, deps.ownsPersistence)) {
+                ...(follower ? { sourceInstanceId: follower.instanceId } : {}),
+            };
+            if (!await (follower
+                ? follower.requestSessionReplacement("publish", intent)
+                : deps.store.commitSessionReplacementIntent(intent, deps.ownsPersistence))) {
                 throw new Error("Telegram session replacement intent was not persisted.");
             }
         },
@@ -1331,11 +1343,22 @@ export function createTelegramSessionActionAssembly(deps) {
             return {
                 async getIntent() { await deps.store.refresh?.(); return deps.store.getSessionReplacementIntent(); },
                 hasSuccessorContinuity(intent) {
-                    return intent.continuity === "classic-chat" ||
-                        deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd === intent.cwd;
+                    if (intent.continuity === "classic-chat")
+                        return true;
+                    if (deps.store.getWorkspaceBindingByTarget(intent.target, sessionId)?.cwd !==
+                        intent.cwd)
+                        return false;
+                    // A follower successor claims only after its own re-registration is live.
+                    return intent.sourceInstanceId === undefined || deps.ownsPersistence() ||
+                        deps.follower?.isRegisteredFor(intent.target) === true;
                 },
                 editSuccess(intent) { return deps.sendResult(intent.target, "<b>🆕 New session started.</b>"); },
-                clearIntent(intent) { return deps.store.removeSessionReplacementIntent(intent, deps.ownsPersistence); },
+                async clearIntent(intent) {
+                    if (intent.sourceInstanceId === undefined || deps.ownsPersistence()) {
+                        return deps.store.removeSessionReplacementIntent(intent, deps.ownsPersistence);
+                    }
+                    return await deps.follower?.requestSessionReplacement("settle", intent) ?? false;
+                },
                 profileName: deps.getProfileName() ?? "default",
                 cwd: ctx.cwd,
                 sessionId,

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

@@ -60,6 +60,7 @@ const telegramBusProtocolIdentity = Bus.createTelegramCurrentBusProtocolIdentity
     Bus.TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
     Bus.TELEGRAM_BUS_CAPABILITY_THREAD_DISPLAY_MODE,
     Bus.TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
+    Bus.TELEGRAM_BUS_CAPABILITY_SESSION_REPLACEMENT_INTENT,
 ]);
 // --- Extension Runtime ---
 export default function (pi) {
@@ -191,6 +192,21 @@ export default function (pi) {
         store: threadStore,
         getProfileName: configStore.getActiveProfileName,
         ownsPersistence: lockRuntime.owns,
+        follower: {
+            instanceId: telegramInstanceId,
+            isRegisteredFor(target) {
+                const registered = telegramBusFollowerRegistrationState.getTarget();
+                return telegramBusFollowerRegistrationState.isRegistered() &&
+                    registered?.chatId === target.chatId &&
+                    registered.threadId === target.threadId;
+            },
+            async requestSessionReplacement(operation, intent) {
+                const request = telegramBusFollowerRegistration.requestSessionReplacement;
+                if (!request)
+                    return false;
+                return await request(operation, intent);
+            },
+        },
         async sendResult(target, html) {
             const delivery = await Delivery.sendTelegramView({ text: html, parseMode: "html", replyMarkup: { inline_keyboard: [] } }, { scope: { kind: "target", target } });
             return delivery.ok ? { ok: true } : { ok: false,

package/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/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/node_modules/@llblab/pi-telegram/dist/lib/threads.d.ts

@@ -187,6 +187,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 +391,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/node_modules/@llblab/pi-telegram/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) {
@@ -949,7 +954,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 +1672,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 +2086,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));

package/node_modules/@llblab/pi-telegram/dist/package.json

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

package/node_modules/@llblab/pi-telegram/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.
 
@@ -226,7 +226,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/node_modules/@llblab/pi-telegram/docs/public-api.md

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