@llblab/pi-kit 0.26.0 → 0.27.0

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

@@ -14,7 +14,7 @@ import {
 import type * as Pi from "./pi.ts";
 import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
 import { escapeHtml } from "./rendering.ts";
-import type { TelegramBridgeStatusLineOptions } from "./status.ts";
+import { formatTelegramConnectionFailure, type TelegramBridgeStatusLineOptions } from "./status.ts";
 import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import {
   createTelegramControlItemBuilder,
@@ -399,14 +399,24 @@ export interface TelegramBridgeCommandRegistrationDeps {
   recoverPollingStart?: (
     error: unknown,
   ) => Promise<TelegramPollingStartRecoveryResult>;
+  recordConnectionEvent?: (error: unknown, phase: string) => void;
   getDisconnectThreadName?: () => string | undefined;
   queueAgentConnectionContext?: (connected: boolean) => void;
   updateStatus: (ctx: ExtensionCommandContext) => void;
+  isContextCurrent?: (ctx: ExtensionCommandContext) => boolean;
+  getSessionGeneration?: () => number;
+  connectionIntent?: {
+    begin(cwd: string, profileName?: string): string;
+    finish(id: string): void;
+    isActive(id: string): boolean;
+    cancel(): void;
+  };
   getProfileNames?: () => string[];
-  activateDefaultProfileConfig?: (ctx: ExtensionCommandContext) => Promise<void>;
+  activateDefaultProfileConfig?: (ctx: ExtensionCommandContext, isCurrent: () => boolean) => Promise<void>;
   activateProfileConfig?: (
     ctx: ExtensionCommandContext,
     profileName: string,
+    isCurrent: () => boolean,
   ) => Promise<boolean>;
 }
 
@@ -504,6 +514,14 @@ export function registerTelegramBridgeCommands(
   pi.registerCommand("telegram-connect", {
     description: "<profile> — Start Telegram bridge",
     handler: async (args, ctx) => {
+      const sessionGeneration = deps.getSessionGeneration?.();
+      let intentId: string | undefined;
+      // Pi context getters throw after replacement; check plain intent/generation first.
+      const isCurrent = () =>
+        (!intentId || deps.connectionIntent?.isActive(intentId) !== false) &&
+        (sessionGeneration === undefined || deps.getSessionGeneration?.() === sessionGeneration) &&
+        deps.isContextCurrent?.(ctx) !== false;
+      if (!isCurrent()) return;
       if (args.trim().split(/\s+/).some((word) => /^as=/i.test(word))) {
         ctx.ui.notify(
           "Thread names are configured from Telegram, not from Pi commands.",
@@ -513,121 +531,141 @@ export function registerTelegramBridgeCommands(
         return;
       }
       const profileName = parseTelegramProfileArg(args);
-      if (profileName && deps.activateProfileConfig) {
-        const ok = await deps.activateProfileConfig(ctx, profileName);
-        if (!ok) {
-          ctx.ui.notify(`Profile "${profileName}" not found.`, "error");
-          deps.updateStatus(ctx);
-          return;
+      intentId = deps.connectionIntent?.begin(ctx.cwd, profileName);
+      try {
+        if (profileName && deps.activateProfileConfig) {
+          const ok = await deps.activateProfileConfig(ctx, profileName, isCurrent);
+          if (!isCurrent()) return;
+          if (!ok) {
+            ctx.ui.notify(`Profile "${profileName}" not found.`, "error");
+            deps.updateStatus(ctx);
+            return;
+          }
+          ctx.ui.notify(`Activated profile "${profileName}".`, "info");
+        } else {
+          await (deps.activateDefaultProfileConfig?.(ctx, isCurrent) ?? deps.reloadConfig());
+          if (!isCurrent()) return;
         }
-        ctx.ui.notify(`Activated profile "${profileName}".`, "info");
-      } else {
-        await (deps.activateDefaultProfileConfig?.(ctx) ?? deps.reloadConfig());
-      }
-      if (!deps.hasBotToken()) {
-        const botTokenDiagnostic = deps.getBotTokenDiagnostic?.();
-        if (botTokenDiagnostic) ctx.ui.notify(botTokenDiagnostic, "error");
-        const profileNames = deps.getProfileNames?.() ?? [];
-        if (!profileName && profileNames.length > 0) {
-          ctx.ui.notify(
-            `No default Telegram profile configured. Available profiles: ${profileNames.join(", ")}. Use /telegram-connect <profileName> or /telegram-setup to create a default profile.`,
-            "info",
-          );
-          deps.updateStatus(ctx);
+        if (!deps.hasBotToken()) {
+          const botTokenDiagnostic = deps.getBotTokenDiagnostic?.();
+          if (botTokenDiagnostic) ctx.ui.notify(botTokenDiagnostic, "error");
+          const profileNames = deps.getProfileNames?.() ?? [];
+          if (!profileName && profileNames.length > 0) {
+            ctx.ui.notify(
+              `No default Telegram profile configured. Available profiles: ${profileNames.join(", ")}. Use /telegram-connect <profileName> or /telegram-setup to create a default profile.`,
+              "info",
+            );
+            deps.updateStatus(ctx);
+            return;
+          }
+          await deps.promptForConfig(ctx, profileName);
           return;
         }
-        await deps.promptForConfig(ctx, profileName);
-        return;
-      }
-      let recoveryUsed = false;
-      const startWithRecovery = async (
-        options: TelegramBridgeCommandStartPollingOptions,
-      ): Promise<void | TelegramBridgeCommandStartPollingResult> => {
-        try {
-          return await deps.startPolling(ctx, options);
-        } catch (error) {
-          if (!deps.recoverPollingStart || recoveryUsed) throw error;
-          const recovery = await deps.recoverPollingStart(error);
-          if (recovery.kind === "unhandled") throw error;
-          if (recovery.kind === "blocked") {
-            return { ok: false, message: recovery.message };
-          }
-          recoveryUsed = true;
+        let recoveryUsed = false;
+        const startWithRecovery = async (
+          options: TelegramBridgeCommandStartPollingOptions,
+        ): Promise<void | (TelegramBridgeCommandStartPollingResult & { notice?: string })> => {
           try {
-            const retry = await deps.startPolling(ctx, options);
-            if (!retry) {
-              return { ok: true, message: recovery.message };
+            return await deps.startPolling(ctx, options);
+          } catch (error) {
+            if (!isCurrent()) return;
+            if (!deps.recoverPollingStart || recoveryUsed) throw error;
+            deps.recordConnectionEvent?.(error, "polling-start");
+            const recovery = await deps.recoverPollingStart(error);
+            if (!isCurrent()) return;
+            if (recovery.kind === "unhandled") throw error;
+            if (recovery.kind === "blocked") {
+              return { ok: false, message: recovery.message,
+                notice: "Telegram recovery blocked. Check /telegram-status --debug." };
+            }
+            recoveryUsed = true;
+            deps.recordConnectionEvent?.(recovery.message, "recovery");
+            try {
+              const retry = await deps.startPolling(ctx, options);
+              if (!isCurrent()) return;
+              if (!retry) return { ok: true, message: "Telegram bridge connected; temporary state recovered." };
+              return {
+                ...retry,
+                message: retry.ok
+                  ? "Telegram bridge connected; temporary state recovered."
+                  : retry.message,
+              };
+            } catch (error) {
+              if (!isCurrent()) return;
+              deps.recordConnectionEvent?.(error, "recovery-retry");
+              return {
+                ok: false,
+                notice: "Telegram recovery failed. Restart this Pi instance.",
+              };
             }
-            return {
-              ...retry,
-              message: retry.ok
-                ? `${recovery.message} ${retry.message ?? "Telegram bridge connected."}`
-                : retry.message,
-            };
-          } catch {
-            return {
-              ok: false,
-              message:
-                "Telegram temporary state was recovered, but the bridge could not restart. Restart this Pi instance and run /telegram-connect again.",
-            };
           }
+        };
+        let result = await startWithRecovery({ forceFreshLeaderThread: true });
+        if (!isCurrent()) return;
+        if (result && !result.ok && result.canTakeover) {
+          const confirmed = await ctx.ui.confirm(
+            formatTelegramTakeoverTitle(ctx),
+            formatTelegramTakeoverPrompt(ctx, result.owner),
+          );
+          if (!isCurrent()) return;
+          if (!confirmed) {
+            ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
+            deps.updateStatus(ctx);
+            return;
+          }
+          result = await startWithRecovery({ force: true, forceFreshLeaderThread: true });
+          if (!isCurrent()) return;
         }
-      };
-      let result = await startWithRecovery({
-        forceFreshLeaderThread: true,
-      });
-      if (result && !result.ok && result.canTakeover) {
-        const confirmed = await ctx.ui.confirm(
-          formatTelegramTakeoverTitle(ctx),
-          formatTelegramTakeoverPrompt(ctx, result.owner),
-        );
-        if (!confirmed) {
-          ctx.ui.notify("Telegram bridge takeover cancelled.", "info");
-          deps.updateStatus(ctx);
-          return;
+        if (result && !result.ok) {
+          if (result.message) deps.recordConnectionEvent?.(result.message, "connect-refused");
+          ctx.ui.notify(result.notice ?? formatTelegramConnectionFailure(result.message), "warning");
+        } else if (result?.message) {
+          ctx.ui.notify(result.message, "info");
         }
-        result = await startWithRecovery({
-          force: true,
-          forceFreshLeaderThread: true,
-        });
-      }
-      if (result?.message) {
-        ctx.ui.notify(result.message, result.ok ? "info" : "warning");
-      }
-      if (!result || result.ok) {
-        deps.queueAgentConnectionContext?.(true);
+        if (!result || result.ok) deps.queueAgentConnectionContext?.(true);
+        deps.updateStatus(ctx);
+      } catch (error) {
+        if (!isCurrent()) return;
+        deps.recordConnectionEvent?.(error, "connect");
+        ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
+        deps.updateStatus(ctx);
+      } finally {
+        if (intentId) deps.connectionIntent?.finish(intentId);
       }
-      deps.updateStatus(ctx);
     },
   });
   pi.registerCommand("telegram-disconnect", {
     description: "Stop Telegram and delete current thread in Threaded Mode",
     handler: async (_args, ctx) => {
-      const threadName = deps.getDisconnectThreadName?.();
-      if (threadName) {
-        const confirmed = await ctx.ui.confirm(
-          ctx.ui.theme.fg("accent", "pi-telegram"),
-          `Delete Telegram thread ${ctx.ui.theme.fg("warning", threadName)} and disconnect this Pi session?`,
-        );
-        if (!confirmed) {
-          ctx.ui.notify("Telegram disconnect cancelled.", "info");
-          deps.updateStatus(ctx);
-          return;
-        }
-      }
+      const generation = deps.getSessionGeneration?.();
+      const isCurrent = () =>
+        (generation === undefined || deps.getSessionGeneration?.() === generation) &&
+        deps.isContextCurrent?.(ctx) !== false;
+      if (!isCurrent()) return;
+      deps.connectionIntent?.cancel();
       try {
+        const threadName = deps.getDisconnectThreadName?.();
+        if (threadName) {
+          const confirmed = await ctx.ui.confirm(
+            ctx.ui.theme.fg("accent", "pi-telegram"),
+            `Delete Telegram thread ${ctx.ui.theme.fg("warning", threadName)} and disconnect this Pi session?`,
+          );
+          if (!isCurrent()) return;
+          if (!confirmed) {
+            ctx.ui.notify("Telegram disconnect cancelled.", "info");
+            return;
+          }
+        }
         const message = await deps.stopPolling();
+        if (!isCurrent()) return;
         if (message) ctx.ui.notify(message, "info");
         deps.queueAgentConnectionContext?.(false);
       } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        ctx.ui.notify(
-          `Telegram disconnect did not complete: ${detail} Keep this Pi session open, restore leader connectivity, inspect /telegram-status --debug, and retry /telegram-disconnect.`,
-          "warning",
-        );
-        throw error;
+        deps.recordConnectionEvent?.(error, "disconnect");
+        if (!isCurrent()) return;
+        ctx.ui.notify("Telegram disconnect incomplete; keep Pi open. Check /telegram-status --debug.", "warning");
       } finally {
-        deps.updateStatus(ctx);
+        if (isCurrent()) deps.updateStatus(ctx);
       }
     },
   });

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -1633,6 +1633,27 @@ export default function (pi: Pi.ExtensionAPI) {
     resolveAutomaticThreadCleanupEnabled: configControls.resolveAutomaticThreadCleanupEnabled,
     runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
   });
+  const connectionIntent = Lifecycle.createTelegramConnectionIntentRuntime();
+  const connectionLifecycle = Lifecycle.createTelegramConnectionLifecycle({
+    intent: connectionIntent,
+    getGeneration: telegramSessionContextStore.getGeneration,
+    isCurrent: telegramSessionContextStore.isCurrent,
+    getProfileName: configStore.getActiveProfileName,
+    isConnected() {
+      return lockRuntime.owns() || telegramBusFollowerRegistrationState.isRegistered();
+    },
+    async activateProfile(profileName, isCurrent) {
+      await configStore.load();
+      if (!isCurrent()) return false;
+      return configStore.activateProfile(profileName) && configStore.hasBotToken();
+    },
+    start(ctx) {
+      return lockedPollingRuntime.start(ctx);
+    },
+    recordError(error) {
+      recordRuntimeEvent("connection", error, { phase: "resume-connect" });
+    },
+  });
   const telegramBridgeSessionLifecycleDeps =
     Lifecycle.createTelegramBridgeSessionLifecycleDeps({
       contextStore: telegramSessionContextStore,
@@ -1681,6 +1702,7 @@ export default function (pi: Pi.ExtensionAPI) {
         },
         delivery: deliveryLifecycleRuntime,
         polling: lockedPollingRuntime,
+        connection: connectionLifecycle,
         inboundWorker: {
           onSessionShutdown: updateAdmissionRuntimeBinding.onSessionShutdown,
         },
@@ -1827,6 +1849,9 @@ export default function (pi: Pi.ExtensionAPI) {
       modelContextAvailabilityRuntime.reconcile();
     },
     getStatusLines,
+    isContextCurrent: telegramSessionContextStore.isCurrent,
+    getSessionGeneration: telegramSessionContextStore.getGeneration,
+    connectionIntent,
     buttonActionStore,
     sendMarkdownReply,
     async sendChannelMarkdownMessage(channel, markdown, options) {

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -1,9 +1,12 @@
 /**
- * Telegram lifecycle hook registration helpers
+ * Telegram session lifecycle coordination and hook registration
  * Zones: pi agent lifecycle, telegram session
- * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * Owns context generations, bounded connect intent across resume, and session sequencing.
+ * Transport authority, durable bindings, and queue custody remain with their owners.
  */
 
+import { randomUUID } from "node:crypto";
+import { formatTelegramConnectionFailure } from "./status.ts";
 import * as BusFollower from "./bus-follower.ts";
 import * as Queue from "./queue.ts";
 import * as TextGroups from "./text-groups.ts";
@@ -157,6 +160,130 @@ export interface TelegramSessionLifecycleHooks {
   ) => Promise<void>;
 }
 
+export interface TelegramConnectionIntent {
+  id: string;
+  cwd: string;
+  profileName?: string;
+}
+interface TelegramConnectionHandoff extends TelegramConnectionIntent {
+  pid: number;
+  targetSessionFile: string;
+  expiresAtMs: number;
+}
+export interface TelegramConnectionHandoffStore {
+  pending?: TelegramConnectionHandoff;
+}
+const HANDOFF_KEY = Symbol.for("pi-telegram.connection-resume.v1");
+function processHandoffStore(): TelegramConnectionHandoffStore {
+  const globals = globalThis as unknown as Record<symbol, TelegramConnectionHandoffStore>;
+  return globals[HANDOFF_KEY] ??= {};
+}
+
+export interface TelegramConnectionLifecycle {
+  prepare(event: SessionStartEvent, ctx: ExtensionContext): (() => void) | undefined;
+  onSessionShutdown(event: SessionShutdownEvent, ctx: ExtensionContext): void;
+}
+
+export function createTelegramConnectionLifecycle(deps: {
+  intent: ReturnType<typeof createTelegramConnectionIntentRuntime>;
+  getGeneration(): number;
+  isCurrent(ctx: ExtensionContext): boolean;
+  getProfileName(): string | undefined;
+  isConnected(): boolean;
+  activateProfile(profileName: string | undefined, isCurrent: () => boolean): Promise<boolean>;
+  start(ctx: ExtensionContext): Promise<{ ok: boolean; message?: string }>;
+  recordError(error: unknown): void;
+}): TelegramConnectionLifecycle {
+  return {
+    onSessionShutdown(event, ctx) {
+      deps.intent.suspend({ reason: event.reason, cwd: ctx.cwd,
+        targetSessionFile: event.targetSessionFile, connected: deps.isConnected(),
+        profileName: deps.getProfileName() });
+    },
+    prepare(event, ctx) {
+      const intent = deps.intent.resume({ reason: event.reason, cwd: ctx.cwd,
+        sessionFile: event.reason === "resume" ? ctx.sessionManager.getSessionFile() : undefined });
+      if (!intent) return undefined;
+      const generation = deps.getGeneration();
+      const isCurrent = () => deps.intent.isActive(intent.id) &&
+        generation === deps.getGeneration() && deps.isCurrent(ctx);
+      return () => {
+        // Startup remains extension-owned background work; no captured command ctx crosses resume.
+        void (async () => {
+          if (!isCurrent()) return;
+          if (!await deps.activateProfile(intent.profileName, isCurrent)) {
+            if (isCurrent()) ctx.ui.notify("Telegram profile unavailable. Run /telegram-setup.", "warning");
+            return;
+          }
+          if (!isCurrent()) return;
+          const result = await deps.start(ctx);
+          if (!isCurrent()) return;
+          if (!result.ok) {
+            deps.recordError(new Error(result.message ?? "Telegram resume connection failed."));
+            ctx.ui.notify(formatTelegramConnectionFailure(result.message), "warning");
+          }
+        })().catch((error) => {
+          deps.recordError(error);
+          if (isCurrent()) ctx.ui.notify(formatTelegramConnectionFailure(error), "warning");
+        }).finally(() => deps.intent.finish(intent.id));
+      };
+    },
+  };
+}
+
+export function createTelegramConnectionIntentRuntime(options: {
+  store?: TelegramConnectionHandoffStore;
+  now?: () => number;
+  pid?: number;
+} = {}) {
+  const store = options.store ?? processHandoffStore();
+  const now = options.now ?? Date.now;
+  const pid = options.pid ?? process.pid;
+  let active: TelegramConnectionIntent | undefined;
+  return {
+    begin(cwd: string, profileName?: string): string {
+      store.pending = undefined;
+      active = { id: randomUUID(), cwd, profileName };
+      return active.id;
+    },
+    isActive(id: string): boolean {
+      return active?.id === id;
+    },
+    finish(id: string): void {
+      if (active?.id === id) active = undefined;
+    },
+    cancel(): void {
+      active = undefined;
+      store.pending = undefined;
+    },
+    suspend(input: {
+      reason: string;
+      cwd: string;
+      targetSessionFile?: string;
+      connected: boolean;
+      profileName?: string;
+    }): void {
+      const intent = active ?? (input.connected
+        ? { id: randomUUID(), cwd: input.cwd, profileName: input.profileName }
+        : undefined);
+      active = undefined;
+      store.pending = input.reason === "resume" && input.targetSessionFile &&
+          intent?.cwd === input.cwd
+        ? { ...intent, pid, targetSessionFile: input.targetSessionFile, expiresAtMs: now() + 30_000 }
+        : undefined;
+    },
+    resume(input: { reason: string; cwd: string; sessionFile?: string }): TelegramConnectionIntent | undefined {
+      const handoff = store.pending;
+      store.pending = undefined;
+      if (!handoff || handoff.pid !== pid || now() >= handoff.expiresAtMs ||
+          input.reason !== "resume" || input.cwd !== handoff.cwd ||
+          input.sessionFile !== handoff.targetSessionFile) return undefined;
+      active = { id: randomUUID(), cwd: handoff.cwd, profileName: handoff.profileName };
+      return { ...active };
+    },
+  };
+}
+
 export interface TelegramSessionContextStore<TContext> {
   get: () => TContext | undefined;
   getGeneration: () => number;
@@ -250,6 +377,7 @@ export function createTelegramSessionGenerationFence(
 }
 
 export interface TelegramBridgeSessionServiceRuntime {
+  connection?: TelegramConnectionLifecycle;
   resumeGroupedInput(ctx: ExtensionContext): void;
   suspendGroupedInput(): void;
   delivery: {
@@ -319,6 +447,7 @@ export interface TelegramBridgeSessionLifecyclePorts<
     };
     delivery: TelegramBridgeSessionServiceRuntime["delivery"];
     polling: TelegramBridgeSessionServiceRuntime["polling"];
+    connection?: TelegramBridgeSessionServiceRuntime["connection"];
     inboundWorker: TelegramBridgeSessionServiceRuntime["inboundWorker"];
     capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
     queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
@@ -348,6 +477,7 @@ export function createTelegramBridgeSessionLifecycleDeps<
       }),
       delivery: ports.services.delivery,
       polling: ports.services.polling,
+      connection: ports.services.connection,
       inboundWorker: ports.services.inboundWorker,
       capabilityMonitor: ports.services.capabilityMonitor,
       queueWatchdog: ports.services.queueWatchdog,
@@ -371,19 +501,23 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       suspendPolling: deps.follower.suspendPolling,
       recordRuntimeEvent: deps.follower.recordRuntimeEvent,
     });
+  let preserveTarget = true;
   const queueLifecycle = Queue.createTelegramSessionLifecycleRuntime({
     ...deps.queue,
     isSessionActive,
-    stopPolling: suspendForReplacement,
+    stopPolling: () => suspendForReplacement(preserveTarget),
     clearPendingMediaGroups: deps.services.suspendGroupedInput,
   });
   const servicesLifecycle: TelegramSessionLifecycleHooks = {
     async onSessionStart(event, ctx) {
+      const resumeConnection = deps.services.connection?.prepare(event, ctx);
       await queueLifecycle.onSessionStart(event, ctx);
       if (!isSessionActive(ctx)) return;
       deps.services.resumeGroupedInput(ctx);
       await deps.services.delivery.onSessionStart();
-      await deps.services.polling.onSessionStart(event, ctx);
+      if (!isSessionActive(ctx)) return;
+      if (resumeConnection) resumeConnection();
+      else await deps.services.polling.onSessionStart(event, ctx);
       deps.services.capabilityMonitor.start(ctx);
       deps.services.queueWatchdog.start(ctx);
     },
@@ -391,6 +525,8 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       const generation = deps.contextStore.getGeneration();
       const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
       if (!isCurrent()) return;
+      deps.services.connection?.onSessionShutdown(event, ctx);
+      preserveTarget = event.reason !== "resume";
       let preserveThread: (() => Promise<void>) | undefined;
       if (event.reason === "quit") {
         try {

package/node_modules/@llblab/pi-telegram/lib/model.ts

@@ -454,10 +454,8 @@ export function buildTelegramModelSwitchContinuationText<
   thinkingLevel?: ScopedTelegramModel<TModel>["thinkingLevel"],
 ): string {
   const modelLabel = `${model.provider}/${model.id}`;
-  const thinkingSuffix = thinkingLevel
-    ? ` Keep the selected thinking level (${thinkingLevel}) if it still applies.`
-    : "";
-  return `${telegramPrefix} Continue the interrupted previous request using the newly selected model (${modelLabel}). Resume from the last unfinished step instead of restarting from scratch unless necessary.${thinkingSuffix}`;
+  const thinkingSuffix = thinkingLevel ? `; thinking: ${thinkingLevel}` : "";
+  return `${telegramPrefix} Continue from the last unfinished step. Model: ${modelLabel}${thinkingSuffix}.`;
 }
 
 export type TelegramModelSwitchContinuationSource = Pick<

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