@llblab/pi-telegram 0.51.4 → 0.51.6

package/lib/polling.ts

@@ -1180,8 +1180,16 @@ export function createTelegramThreadAwarePollingPorts<TContext, TOwner>(
     ctx: TContext,
     owner: TOwner,
   ): Promise<boolean | undefined> => {
-    if (!(await refreshFollowerState())) return undefined;
-    if (!deps.hasRememberedWorkspaceBinding?.(ctx)) return undefined;
+    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)) {
+      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/lib/status.ts

@@ -1,9 +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: unknown): string {
+  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";
 
 export type TelegramStatusQueueLane = "control" | "priority" | "default";

package/lib/sync.ts

@@ -773,6 +773,7 @@ export async function ensureTelegramLeaderThreadBinding(
     : undefined;
   const legacyWorkspaceBinding =
     workspaceIdentity?.instanceSlot === "a" &&
+    deps.sessionId === undefined &&
     !persistedWorkspaceBinding &&
     typeof legacyLeaderRecord?.target.threadId === "number"
       ? {
@@ -885,10 +886,9 @@ export async function ensureTelegramLeaderThreadBinding(
       (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",

package/lib/threads.ts

@@ -229,6 +229,7 @@ export interface TelegramThreadPendingProvision {
   owner: "leader" | "manual-follower";
   instanceId: string;
   profileKey?: string;
+  workspaceBindingKey?: string;
   status?: "in-flight" | "ambiguous";
   threadName?: string;
   displayTitle?: string;
@@ -371,6 +372,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 {
@@ -1329,7 +1336,7 @@ function cloneSessionReplacementIntent(
   return { ...intent, target: { ...intent.target } };
 }
 
-function normalizeSessionReplacementIntent(
+export function normalizeTelegramSessionReplacementIntent(
   value: unknown,
 ): TelegramSessionReplacementIntent | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
@@ -1346,7 +1353,10 @@ function normalizeSessionReplacementIntent(
     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"
@@ -1370,6 +1380,8 @@ function normalizeSessionReplacementIntent(
     ...(typeof record.threadName === "string" ? { threadName: record.threadName } : {}),
     createdAtMs: record.createdAtMs,
     expiresAtMs: record.expiresAtMs,
+    ...(typeof record.sourceInstanceId === "string"
+      ? { sourceInstanceId: record.sourceInstanceId } : {}),
   };
 }
 
@@ -1517,6 +1529,9 @@ function normalizePendingProvision(
     ...(record.status === "in-flight" || record.status === "ambiguous"
       ? { status: record.status }
       : {}),
+    ...(typeof record.workspaceBindingKey === "string"
+      ? { workspaceBindingKey: record.workspaceBindingKey }
+      : {}),
     ...(typeof record.threadName === "string"
       ? { threadName: record.threadName }
       : {}),
@@ -1680,7 +1695,7 @@ function parseTopicTargetFile(value: unknown): TelegramTopicTargetFile {
           return normalized ? [normalized] : [];
         })
       : [],
-    sessionReplacement: normalizeSessionReplacementIntent(file.sessionReplacement),
+    sessionReplacement: normalizeTelegramSessionReplacementIntent(file.sessionReplacement),
     reservations: Array.isArray(file.reservations)
       ? file.reservations.flatMap((reservation) => {
           const normalized = normalizeReservation(reservation);
@@ -2510,7 +2525,7 @@ export function createTelegramTopicTargetStore(
         : undefined;
     },
     async commitSessionReplacementIntent(intent, isCurrent) {
-      const next = normalizeSessionReplacementIntent(intent);
+      const next = normalizeTelegramSessionReplacementIntent(intent);
       if (!next || !isCurrent()) return false;
       await loadFromDisk();
       if (!isCurrent()) return false;
@@ -2925,7 +2940,10 @@ export function createTelegramTopicTargetStore(
         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 &&
@@ -4905,6 +4923,13 @@ export function createTelegramTopicTargetProvisioner(
         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) =>
@@ -4919,8 +4944,13 @@ export function createTelegramTopicTargetProvisioner(
         pendingForRequest = undefined;
       }
     }
+    const matchesWorkspace = (target: TelegramTarget): boolean =>
+      !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();
@@ -5003,7 +5033,7 @@ export function createTelegramTopicTargetProvisioner(
     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.");
       }
@@ -5041,7 +5071,7 @@ export function createTelegramTopicTargetProvisioner(
       getNextTelegramThreadNamePaletteSlot(deps.store.list(), undefined) ??
       request.preferredSlot;
     const slot =
-      existing?.slot ??
+      (existing && matchesWorkspace(existing.target) ? existing.slot : undefined) ??
       deps.store.allocateSlot(
         request.profileKey,
         isManualFollowerRequest
@@ -5050,6 +5080,7 @@ export function createTelegramTopicTargetProvisioner(
             (candidateThreadName ? undefined : identity?.slot) ??
             preferredNameSlot),
         request.workspaceBindingKey,
+        { excludeCurrentRecord: !!existing && !matchesWorkspace(existing.target) },
       );
     if (!slot) {
       throw new TelegramWorkspaceSlotUnavailableError();
@@ -5093,6 +5124,7 @@ export function createTelegramTopicTargetProvisioner(
       owner: pendingOwner,
       instanceId: request.instanceId,
       profileKey: request.profileKey,
+      ...(request.workspaceBindingKey ? { workspaceBindingKey: request.workspaceBindingKey } : {}),
       threadName: requestThreadName,
       ...(displayTitle ? { displayTitle } : {}),
       slot,

package/lib/workspace-retirement.ts

@@ -884,6 +884,7 @@ export async function executeTelegramWorkspaceRetirement(input: {
     | "listWorkspaceRetirementIntents"
     | "commitWorkspaceRetirement"
     | "removeWorkspaceRetirementIntent"
+    | "markStaleByTarget"
     | "persist"
   >;
   admission: Pick<
@@ -971,6 +972,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 },
@@ -1040,6 +1047,9 @@ export async function executeTelegramWorkspaceRetirement(input: {
       fence = input.admission.confirmRetirementAbsence(fence);
     }
     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)) {
       return { kind: "retained", reason: "commit-rejected" };
@@ -1212,7 +1222,7 @@ export type TelegramWorkspaceRetirementLifecycleResult =
 export async function runTelegramWorkspaceRetirementLifecycle(input: {
   store: TelegramWorkspaceRetirementPreparationDeps["store"] & Pick<
     TelegramTopicTargetStore,
-    "replaceWorkspaceRetirementIntent" | "commitWorkspaceRetirement"
+    "replaceWorkspaceRetirementIntent" | "commitWorkspaceRetirement" | "markStaleByTarget"
   >;
   getExternalProtection: (
     binding: TelegramWorkspaceThreadBinding,
@@ -1257,19 +1267,42 @@ 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/package.json

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