@llblab/pi-telegram 0.50.1 → 0.51.1

package/lib/commands.ts

@@ -711,6 +711,7 @@ export interface TelegramCommandActionDeps<TMessage, TContext> {
 export interface TelegramStopCommandDeps {
   hasAbortHandler: () => boolean;
   clearPendingModelSwitch: () => void;
+  cancelNextTransitionAnnouncements?: () => void;
   clearQueuedTelegramItems: () => number;
   setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
   abortCurrentTurn: () => void;
@@ -1146,6 +1147,8 @@ export interface TelegramCommandRuntimeDeps<
   isContextActive?: (ctx: TContext) => boolean;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
   requestNextDispatchAnnouncement?: () => void;
+  markActiveTurnNextAbortAnnouncement?: () => boolean;
+  cancelNextTransitionAnnouncements?: () => void;
   requestDeferredDispatchNextQueuedTelegramTurn?: (
     dispatch: (ctx: TContext) => void,
   ) => void;
@@ -1352,6 +1355,7 @@ export async function handleTelegramStopCommand(
   deps: TelegramStopCommandDeps,
 ): Promise<void> {
   deps.clearPendingModelSwitch();
+  deps.cancelNextTransitionAnnouncements?.();
   const clearedCount = deps.clearQueuedTelegramItems();
   deps.setFoldQueuedPromptsIntoHistory(false);
   if (!deps.hasAbortHandler()) {
@@ -1385,6 +1389,7 @@ export async function handleTelegramAbortCommand(deps: {
   hasAbortHandler: () => boolean;
   hasActiveTelegramTurn: () => boolean;
   clearPendingModelSwitch: () => void;
+  cancelNextTransitionAnnouncements?: () => void;
   abortCurrentTurn: () => void;
   setFoldQueuedPromptsIntoHistory: (fold: boolean) => void;
   updateStatus: () => void;
@@ -1394,6 +1399,7 @@ export async function handleTelegramAbortCommand(deps: {
   ) => Promise<void>;
 }): Promise<void> {
   deps.clearPendingModelSwitch();
+  deps.cancelNextTransitionAnnouncements?.();
   if (!deps.hasAbortHandler()) {
     await deps.sendTextReply(
       formatTelegramInformationHeading("💤", "No active turn."),
@@ -1418,6 +1424,7 @@ export async function handleTelegramNextCommand(deps: {
   abortCurrentTurn: () => void;
   dispatchNextQueuedTurn: () => void;
   requestNextDispatchAnnouncement?: () => void;
+  markActiveTurnNextAbortAnnouncement?: () => boolean;
   clearFoldForDispatch: () => void;
   updateStatus: () => void;
   sendTextReply: (
@@ -1439,6 +1446,7 @@ export async function handleTelegramNextCommand(deps: {
   if (!deps.isIdle() && deps.hasAbortHandler()) {
     deps.clearFoldForDispatch();
     deps.requestNextDispatchAnnouncement?.();
+    deps.markActiveTurnNextAbortAnnouncement?.();
     deps.abortCurrentTurn();
     deps.updateStatus();
     return;
@@ -1880,6 +1888,11 @@ export function createTelegramCommandHandlerTargetRuntime<
     updateStatus: deps.updateStatus,
     isContextActive: deps.isContextActive,
     dispatchNextQueuedTelegramTurn: deps.dispatchNextQueuedTelegramTurn,
+    requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
+    markActiveTurnNextAbortAnnouncement:
+      deps.markActiveTurnNextAbortAnnouncement,
+    cancelNextTransitionAnnouncements:
+      deps.cancelNextTransitionAnnouncements,
     startTypingLoop: deps.startTypingLoop,
     stopTypingLoop: deps.stopTypingLoop,
     enqueueContinueTurn: deps.enqueueContinueTurn,
@@ -2037,6 +2050,8 @@ async function handleTelegramCommandRuntime<
         await handleTelegramStopCommand({
           hasAbortHandler: deps.hasAbortHandler,
           clearPendingModelSwitch: deps.clearPendingModelSwitch,
+          cancelNextTransitionAnnouncements:
+            deps.cancelNextTransitionAnnouncements,
           clearQueuedTelegramItems: () =>
             deps.clearQueuedTelegramItems(commandCtx),
           setFoldQueuedPromptsIntoHistory: deps.setFoldQueuedPromptsIntoHistory,
@@ -2113,6 +2128,8 @@ async function handleTelegramCommandRuntime<
           hasAbortHandler: deps.hasAbortHandler,
           hasActiveTelegramTurn: deps.hasActiveTelegramTurn,
           clearPendingModelSwitch: deps.clearPendingModelSwitch,
+          cancelNextTransitionAnnouncements:
+            deps.cancelNextTransitionAnnouncements,
           abortCurrentTurn: deps.abortCurrentTurn,
           setFoldQueuedPromptsIntoHistory: deps.setFoldQueuedPromptsIntoHistory,
           updateStatus: updateStatusFor(commandCtx),
@@ -2129,6 +2146,8 @@ async function handleTelegramCommandRuntime<
           dispatchNextQueuedTurn: () =>
             deps.dispatchNextQueuedTelegramTurn(commandCtx),
           requestNextDispatchAnnouncement: deps.requestNextDispatchAnnouncement,
+          markActiveTurnNextAbortAnnouncement:
+            deps.markActiveTurnNextAbortAnnouncement,
           clearFoldForDispatch: () =>
             deps.setFoldQueuedPromptsIntoHistory(false),
           updateStatus: updateStatusFor(commandCtx),

package/lib/extension.ts

@@ -104,7 +104,7 @@ export default function (pi: Pi.ExtensionAPI) {
     WorkspaceAdmission.createTelegramWorkspaceAdmissionRuntimeBinding({
       getProfileName: configStore.getActiveProfileName,
       getBotToken: configStore.getBotToken,
-      getPath: Paths.resolveTelegramWorkspaceAdmissionPath,
+      getPath: Paths.resolveTelegramWorkspaceAdmissionPathForProfile,
       owner: {
         processId: telegramProcessId,
         processBirthId: telegramQueueProcessBirthId,
@@ -187,7 +187,7 @@ export default function (pi: Pi.ExtensionAPI) {
         },
         getWorkspaceAdmission: workspaceAdmissionRuntime.resolve,
       },
-      getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPath,
+      getLeaderJournalPath: Paths.resolveTelegramUpdateJournalPathForProfile,
       getFollowerJournalPath(bindingKey, profileName) {
         return Paths.resolveTelegramFollowerJournalPath(
           bindingKey,
@@ -387,6 +387,51 @@ export default function (pi: Pi.ExtensionAPI) {
           : "clear";
       },
     });
+  const reclaimTelegramWorkspaceDeadOwnerQueue =
+    WorkspaceRetirement.createTelegramWorkspaceDeadOwnerQueueReclaimer({
+      getExternalProtection: captureWorkspaceExternalProtection,
+      getActiveTurnTarget: activeTurnRuntime.getTarget,
+      getQueuedItems: telegramQueueStore.getQueuedItems,
+      resolveLeaderJournal: resolveTelegramUpdateJournalBinding,
+      createFollowerJournalResolver:
+        telegramJournalBindingRuntime.createRecipientResolver,
+      discoverFollowerJournals() {
+        return Journal.discoverTelegramFollowerJournalPaths({
+          directory: Paths.resolveTelegramTempDir(),
+          profileName: configStore.getActiveProfileName(),
+        });
+      },
+      createJournalPathResolver: telegramJournalBindingRuntime.createPathResolver,
+      withJournalReference(binding, operation) {
+        if (!binding.recoveryKey) throw new Error(
+          "Telegram workspace journal reference identity is unavailable.",
+        );
+        return telegramJournalReferenceRegistry.withReference({
+          referenceClass: "workspace-retirement",
+          recoveryKey: binding.recoveryKey,
+        }, operation);
+      },
+      getRecoveryOwner() {
+        return {
+          instanceId: telegramInstanceId,
+          processId: telegramProcessId,
+          processBirthId: telegramQueueProcessBirthId,
+          sessionGeneration: telegramSessionContextStore.getGeneration(),
+        };
+      },
+      getQueueOwnerLiveness: Bus.getTelegramProcessLiveness,
+      onMutationError(error) {
+        recordRuntimeEvent("Telegram dead-owner queue reclamation was refused.", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      },
+      isBindingCurrent(binding) {
+        return WorkspaceRetirement.isCurrentTelegramWorkspaceBinding(
+          threadStore,
+          binding,
+        );
+      },
+    });
   const inactiveThreadCleanupReviewRuntime =
     ThreadCleanupManager.createTelegramInactiveThreadCleanupReviewRuntime({
       getProfileName() { return configStore.getActiveProfileName() ?? "default"; },
@@ -775,6 +820,7 @@ export default function (pi: Pi.ExtensionAPI) {
     mutation: queueMutationRuntime,
     dispatchNext: dispatchNextQueuedTelegramTurn,
     requestNextDispatchAnnouncement,
+    cancelNextDispatchAnnouncement,
     watchdog: queueDispatchWatchdogRuntime,
   } = Bindings.createTelegramQueueBindingRuntime({
     store: telegramQueueStore,
@@ -790,6 +836,13 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatus,
     sendTextReply,
     sendUserMessage,
+    reconcileNextDispatchAnnouncementReplyOwnership(item) {
+      Replies.preserveTransportReplyDedupOnNextReset(
+        item.chatId,
+        item.replyToMessageId,
+        item.target,
+      );
+    },
     recordRuntimeEvent,
   });
   const { finalizeMarkdownPreview, preparePreviewDelivery } =
@@ -1048,6 +1101,7 @@ export default function (pi: Pi.ExtensionAPI) {
     isContextActive: telegramSessionContextStore.isCurrent,
     dispatchNextQueuedTelegramTurn,
     requestNextDispatchAnnouncement,
+    cancelNextDispatchAnnouncement,
     requestDeferredDispatchNextQueuedTelegramTurn:
       deferredQueueDispatchRuntime.request,
     hasDeferredDispatchContext: deferredQueueDispatchRuntime.isBound,
@@ -1410,6 +1464,18 @@ export default function (pi: Pi.ExtensionAPI) {
       getWorkspaceAdmission: workspaceAdmissionRuntime.resolve,
       runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
       captureWorkspaceExternalProtection,
+      workspaceRotation: {
+        getAdmission: workspaceAdmissionRuntime.resolve,
+        runExclusive: telegramWorkspaceOperationRuntime.runExclusive,
+        deleteThread: directTelegramApiRuntime.deleteWorkspaceThread,
+        reclaimDeadOwnerQueuedWork(binding, isCurrent) {
+          return telegramWorkspaceOperationRuntime.run({
+            operationId: WorkspaceAdmission.createTelegramWorkspaceAdmissionOperationId(),
+            operationKind: "workspace.reclaim-dead-owner-queue",
+            scopes: [{ kind: "target", target: binding.target }],
+          }, reclaimTelegramWorkspaceDeadOwnerQueue.bind(undefined, binding, isCurrent));
+        },
+      },
       callApi(method, body, options) {
         return directTelegramApiRuntime.call(method, body, options);
       },
@@ -1545,6 +1611,15 @@ export default function (pi: Pi.ExtensionAPI) {
     recordRuntimeEvent,
     runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
   });
+  const prepareThreadPreservationOnQuit = Sync.createTelegramPreservedLeaderQuitHandler({
+    instanceId: telegramInstanceId,
+    topicTargetStore: threadStore,
+    getCurrentLeaderEpoch,
+    getProfileName: configStore.getActiveProfileName,
+    isPollingSuspended: lockedPollingRuntime.isSuspended,
+    resolveAutomaticThreadCleanupEnabled: configControls.resolveAutomaticThreadCleanupEnabled,
+    runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
+  });
   const telegramBridgeSessionLifecycleDeps =
     Lifecycle.createTelegramBridgeSessionLifecycleDeps({
       contextStore: telegramSessionContextStore,
@@ -1599,6 +1674,7 @@ export default function (pi: Pi.ExtensionAPI) {
         capabilityMonitor: telegramThreadCapabilityMonitor,
         queueWatchdog: queueDispatchWatchdogRuntime,
         guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
+        prepareThreadPreservationOnQuit,
       },
     });
   const sessionLifecycleRuntime =

package/lib/journal.ts

@@ -2428,6 +2428,7 @@ export interface TelegramUpdateJournalRuntimeBinding {
   runtimeKey: string;
   recoveryKey: string;
   journal: TelegramUpdateJournalStore;
+  readForProtection?: () => { entries: readonly TelegramUpdateJournalEntry[] };
 }
 
 export interface TelegramUpdateJournalRuntimeBindingResolverDeps {
@@ -2470,6 +2471,19 @@ export function createTelegramUpdateJournalRuntimeBindingResolver(
         profileName,
         botIdentity,
       }),
+      readForProtection() {
+        // Protection must never turn corruption/recovery into empty-work evidence.
+        const evidence = inspectTelegramUpdateJournalFamily({
+          directory: dirname(path), path, profile: profileName, botIdentity,
+          limits: {
+            maxFiles: 1024,
+            maxBytes: TELEGRAM_UPDATE_JOURNAL_MAX_BYTES * 2,
+            maxEntries: TELEGRAM_UPDATE_JOURNAL_MAX_ENTRIES,
+            maxWork: TELEGRAM_UPDATE_JOURNAL_MAX_ENTRIES * 1024,
+          },
+        });
+        return { entries: evidence.kind === "present" ? evidence.file.entries : [] };
+      },
       journal: createTelegramUpdateJournalStore({
         path,
         profileName,

package/lib/lifecycle.ts

@@ -244,7 +244,7 @@ export function createTelegramSessionGenerationFence(
       const generation = store.getGeneration();
       if (!store.isCurrent(ctx, generation)) return;
       await hooks.onSessionShutdown(event, ctx);
-      store.clear(ctx);
+      if (store.isCurrent(ctx, generation)) store.clear(ctx);
     },
   };
 }
@@ -266,6 +266,7 @@ export interface TelegramBridgeSessionServiceRuntime {
   capabilityMonitor: { start(ctx: ExtensionContext): void; stop(): void };
   queueWatchdog: { start(ctx: ExtensionContext): void; stop(): void };
   guestPlaceholder?: { stopAll(): void };
+  prepareThreadPreservationOnQuit?: (isSessionCurrent: () => boolean) => (() => Promise<void>) | undefined;
 }
 
 export interface TelegramBridgeSessionLifecycleAssemblyDeps<
@@ -322,6 +323,7 @@ export interface TelegramBridgeSessionLifecyclePorts<
     capabilityMonitor: TelegramBridgeSessionServiceRuntime["capabilityMonitor"];
     queueWatchdog: TelegramBridgeSessionServiceRuntime["queueWatchdog"];
     guestPlaceholder?: TelegramBridgeSessionServiceRuntime["guestPlaceholder"];
+    prepareThreadPreservationOnQuit?: TelegramBridgeSessionServiceRuntime["prepareThreadPreservationOnQuit"];
   };
 }
 
@@ -350,6 +352,7 @@ export function createTelegramBridgeSessionLifecycleDeps<
       capabilityMonitor: ports.services.capabilityMonitor,
       queueWatchdog: ports.services.queueWatchdog,
       guestPlaceholder: ports.services.guestPlaceholder,
+      prepareThreadPreservationOnQuit: ports.services.prepareThreadPreservationOnQuit,
     },
   };
 }
@@ -385,15 +388,31 @@ export function createTelegramBridgeSessionLifecycleAssembly<
       deps.services.queueWatchdog.start(ctx);
     },
     async onSessionShutdown(event, ctx) {
-      if (!isSessionActive(ctx)) return;
+      const generation = deps.contextStore.getGeneration();
+      const isCurrent = () => deps.contextStore.isCurrent(ctx, generation);
+      if (!isCurrent()) return;
+      let preserveThread: (() => Promise<void>) | undefined;
+      if (event.reason === "quit") {
+        try {
+          preserveThread = deps.services.prepareThreadPreservationOnQuit?.(isCurrent);
+        } catch (error) {
+          deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+        }
+      }
       deps.services.guestPlaceholder?.stopAll();
       await deps.services.delivery.onSessionShutdown();
-      if (!isSessionActive(ctx)) return;
+      if (!isCurrent()) return;
       deps.services.queueWatchdog.stop();
       deps.services.capabilityMonitor.stop();
       await queueLifecycle.onSessionShutdown(event, ctx);
-      if (!isSessionActive(ctx)) return;
+      if (!isCurrent()) return;
       await deps.services.inboundWorker.onSessionShutdown();
+      if (!isCurrent()) return;
+      try {
+        await preserveThread?.();
+      } catch (error) {
+        deps.follower.recordRuntimeEvent("session", error, { phase: "preserve-thread-on-quit" });
+      }
     },
   };
   const followerLifecycle = appendTelegramLifecycleHooks(

package/lib/locks.ts

@@ -739,7 +739,8 @@ export function isProcessAlive(pid: number): boolean {
     process.kill(pid, 0);
     return true;
   } catch (error) {
-    return (error as { code?: string }).code === "EPERM";
+    // Only an absent PID proves death; permission and unexpected failures do not.
+    return (error as { code?: string }).code !== "ESRCH";
   }
 }
 
@@ -1126,6 +1127,7 @@ export interface TelegramLockedPollingRuntime<
   ) => Promise<TelegramLockedPollingStartResult>;
   stop: () => Promise<string>;
   suspend: () => Promise<void>;
+  isSuspended: () => boolean;
   onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
   onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
   registerFollowerWithOwner?: (
@@ -1190,6 +1192,9 @@ export function createTelegramLockedPollingRuntime<
   let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
   let pollingGeneration = 0;
+  let suspendedGeneration: number | undefined;
+  let suspensionsInFlight = 0;
+  let startupsInFlight = 0;
   const ownershipCheckMs =
     deps.ownershipCheckMs ?? TELEGRAM_OWNERSHIP_CHECK_MS;
   const ownershipRefreshMs =
@@ -1201,20 +1206,29 @@ export function createTelegramLockedPollingRuntime<
     ownershipRefreshInterval = undefined;
   };
   const suspendPolling = async () => {
-    pollingGeneration += 1;
-    activeContext = undefined;
-    deps.transportMonitor?.stop();
-    deps.stopFollowerRegistration?.();
-    stopOwnershipWatcher();
-    if (sessionAutoStartRun) {
-      await sessionAutoStartRun;
+    const generation = ++pollingGeneration;
+    suspensionsInFlight += 1;
+    try {
+      activeContext = undefined;
+      deps.transportMonitor?.stop();
       deps.stopFollowerRegistration?.();
+      stopOwnershipWatcher();
+      if (sessionAutoStartRun) {
+        await sessionAutoStartRun;
+        deps.stopFollowerRegistration?.();
+      }
+      if (ownershipStop) {
+        await ownershipStop;
+        return;
+      }
+      await deps.stopPolling();
+      // Unsettled starts, overlapping stops or stale completion cannot certify quiescence.
+      if (generation === pollingGeneration && suspensionsInFlight === 1 && startupsInFlight === 0) {
+        suspendedGeneration = generation;
+      }
+    } finally {
+      suspensionsInFlight -= 1;
     }
-    if (ownershipStop) {
-      await ownershipStop;
-      return;
-    }
-    await deps.stopPolling();
   };
   const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
@@ -1261,6 +1275,7 @@ export function createTelegramLockedPollingRuntime<
     if (!isCurrent()) return false;
     activeContext = ctx;
     startOwnershipWatcher(ctx);
+    startupsInFlight += 1;
     try {
       if (!deps.lock.refresh(snapshotLockContext(ctx))) {
         stopOwnershipWatcher();
@@ -1283,6 +1298,8 @@ export function createTelegramLockedPollingRuntime<
       deps.lock.release();
       deps.onTransportAvailabilityChanged?.();
       throw error;
+    } finally {
+      startupsInFlight -= 1;
     }
     if (!isCurrent()) return false;
     if (deps.lock.owns(ctx)) {
@@ -1421,6 +1438,8 @@ export function createTelegramLockedPollingRuntime<
       return "Telegram bridge disconnected.";
     },
     suspend: suspendPolling,
+    isSuspended: () => suspendedGeneration === pollingGeneration &&
+      suspensionsInFlight === 0 && startupsInFlight === 0 && !sessionAutoStartRun && !ownershipStop,
     onPersistentConflict: async (ctx, count) => {
       if (activeContext === undefined || ownershipStop) return;
       if (!(deps.isContextCurrent?.(ctx) ?? activeContext === ctx)) return;

package/lib/paths.ts

@@ -9,7 +9,7 @@
  */
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 
 export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 
@@ -43,6 +43,20 @@ export function resolveAgentDir(
   return join(homedir(), ".pi", "agent");
 }
 
+/**
+ * Pure reference preflight against an independently approved resource path.
+ * Reject aliases; never repair relative historical references or redirect storage.
+ * Equality proves spelling only, not file identity, consumer closure or migration readiness.
+ */
+export function requireTelegramStoragePathReference(path: string, expectedPath: string): string {
+  if (typeof path !== "string" || typeof expectedPath !== "string" ||
+      !isAbsolute(path) || resolve(path) !== path ||
+      !isAbsolute(expectedPath) || resolve(expectedPath) !== expectedPath || path !== expectedPath) {
+    throw new Error("Telegram storage reference does not match its approved absolute path.");
+  }
+  return path;
+}
+
 /** Telegram bridge configuration file (<agentDir>/telegram.json). */
 export function resolveTelegramConfigPath(): string {
   return join(resolveAgentDir(), "telegram.json");
@@ -100,6 +114,13 @@ export function resolveTelegramWorkspaceAdmissionPath(
   );
 }
 
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export function resolveTelegramWorkspaceAdmissionPathForProfile(
+  profileName?: string,
+): string {
+  return resolveTelegramWorkspaceAdmissionPath(resolveAgentDir(), profileName);
+}
+
 /** Durable inactive Thread cleanup work-set journal. */
 export function resolveTelegramThreadCleanupWorkPath(
   agentDir = resolveAgentDir(),
@@ -129,6 +150,13 @@ export function resolveTelegramUpdateJournalPath(
   );
 }
 
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export function resolveTelegramUpdateJournalPathForProfile(
+  profileName?: string,
+): string {
+  return resolveTelegramUpdateJournalPath(resolveAgentDir(), profileName);
+}
+
 /** Durable follower delivery journal, isolated by stable recipient binding. */
 export function resolveTelegramFollowerJournalPath(
   recipientBindingKey: string,

package/lib/polling.ts

@@ -28,8 +28,8 @@ const TELEGRAM_GET_UPDATES_CONFLICT_SLOW_RETRY_MS = 3_000;
 const TELEGRAM_POLLING_RETRY_MS = 3_000;
 export const TELEGRAM_GET_UPDATES_GRACE_MS = 10_000;
 
-// Standard Telegram DM polling does not expose ordinary message-deletion events,
-// so queue removal stays reaction-driven while delete-like business updates remain defensive-only.
+// Standard Telegram DM polling does not expose ordinary message-deletion events.
+// Business deletions belong to a separate namespace and default routing ignores them.
 export const TELEGRAM_ALLOWED_UPDATES = [
   "message",
   "edited_message",