@llblab/pi-kit 0.19.2 → 0.21.0

package/node_modules/@llblab/pi-telegram/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"; },
@@ -1410,6 +1455,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 +1602,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 +1665,7 @@ export default function (pi: Pi.ExtensionAPI) {
         capabilityMonitor: telegramThreadCapabilityMonitor,
         queueWatchdog: queueDispatchWatchdogRuntime,
         guestPlaceholder: { stopAll: guestPlaceholderRuntime.stopAll },
+        prepareThreadPreservationOnQuit,
       },
     });
   const sessionLifecycleRuntime =

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

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

@@ -1615,7 +1615,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   extractAssistant: (
     messages: readonly TMessage[],
   ) => TelegramAgentEndAssistantResult;
-  isRecoveredAssistantAlreadyPublished?: (assistant: TelegramAgentEndAssistantResult) => boolean;
+  isAssistantAlreadyPublished?: (assistant: TelegramAgentEndAssistantResult) => boolean;
   getFoldQueuedPromptsIntoHistory: () => boolean;
   resetRuntimeState: () => void;
   isSessionActive?: (ctx: TContext) => boolean;
@@ -1761,8 +1761,7 @@ export function createTelegramAgentEndHook<
     if (deps.isSessionActive?.(ctx) === false) return;
     const turn = deps.getActiveTurn();
     const extractedAssistant = assistantOverride ?? (turn ? deps.extractAssistant(event.messages) : {});
-    const assistant = extractedAssistant.recoveredFromEarlier &&
-        deps.isRecoveredAssistantAlreadyPublished?.(extractedAssistant)
+    const assistant = deps.isAssistantAlreadyPublished?.(extractedAssistant)
       ? { stopReason: extractedAssistant.stopReason }
       : extractedAssistant;
     const hasPublication = !!assistant.text || assistant.stopReason === "error" || !!turn?.queuedAttachments.length;

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

@@ -7,6 +7,7 @@
 import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from "./telegram-api.ts";
 import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
+import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.ts";
 import {
   createTelegramWorkspaceAdmissionOperationId,
   runWithTelegramWorkspaceAdmissionsAsync,
@@ -197,6 +198,47 @@ export function markTelegramConfigSyncChange<
   return nextState;
 }
 
+export function createTelegramPreservedLeaderQuitHandler(deps: {
+  instanceId: string;
+  topicTargetStore: Pick<TelegramTopicTargetStore,
+    "load" | "list" | "listPendingCleanups" | "detachTargetOwner">;
+  getCurrentLeaderEpoch: () => number | string | undefined;
+  getProfileName: () => string | undefined;
+  isPollingSuspended: () => boolean;
+  resolveAutomaticThreadCleanupEnabled: () => boolean | Promise<boolean>;
+  runWorkspaceOperation: TelegramSyncWorkspaceOperationRunner;
+}): (isSessionCurrent: () => boolean) => (() => Promise<void>) | undefined {
+  return (isSessionCurrent) => {
+    const epoch = deps.getCurrentLeaderEpoch();
+    const profile = deps.getProfileName();
+    if (epoch === undefined || !isSessionCurrent()) return undefined;
+    const isCurrent = () => isSessionCurrent() && deps.getCurrentLeaderEpoch() === epoch &&
+      deps.getProfileName() === profile && deps.isPollingSuspended();
+    return async () => {
+      if (!isCurrent() || await deps.resolveAutomaticThreadCleanupEnabled() !== false) return;
+      if (!isCurrent()) return;
+      await deps.runWorkspaceOperation({
+        operationId: createTelegramWorkspaceAdmissionOperationId(),
+        operationKind: "workspace.preserve-leader-quit",
+        scopes: [{ kind: "profile" }],
+      }, async () => {
+        if (!isCurrent()) return;
+        await deps.topicTargetStore.load();
+        if (!isCurrent()) return;
+        const records = deps.topicTargetStore.list().filter((record) =>
+          record.instanceId === deps.instanceId && (record.status === "active" || record.status === "starting"));
+        if (records.length !== 1) return;
+        const record = records[0]!;
+        if (deps.topicTargetStore.listPendingCleanups().some((intent) =>
+          intent.target.chatId === record.target.chatId && intent.target.threadId === record.target.threadId)) return;
+        if (!await deps.topicTargetStore.detachTargetOwner(record, isCurrent) && isCurrent()) {
+          throw new Error("Telegram preserved leader detachment was not committed.");
+        }
+      });
+    };
+  };
+}
+
 export interface TelegramSessionRestartThreadCleanupDeps<
   TSyncState extends TelegramSyncState,
 > extends Omit<TelegramManualThreadDisconnectDeps<TSyncState>, "stopPolling"> {
@@ -650,15 +692,17 @@ export async function ensureTelegramLeaderThreadBinding(
   const leaderProfileKey = getTelegramThreadOwnerKey(leaderOwner);
   const legacyLeaderRecord =
     deps.topicTargetStore.getByProfileKey(leaderProfileKey);
+  let capacityUnavailable = false;
   const workspaceIdentity = normalizedLeaderCwd
     ? deps.topicTargetStore.claimWorkspaceIdentity(
         normalizedLeaderCwd,
         deps.instanceId,
         legacyLeaderRecord?.instanceId,
-        { sessionId: deps.sessionId },
+        { sessionId: deps.sessionId, onCapacityUnavailable() { capacityUnavailable = true; } },
       )
     : undefined;
   if (deps.cwd && !workspaceIdentity) {
+    if (capacityUnavailable) throw new TelegramWorkspaceSlotUnavailableError();
     throw new Error("Telegram Workspace identity is already claimed.");
   }
   const commitWorkspaceBinding = async (

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

@@ -882,15 +882,18 @@ export function isTelegramApiCommitUnknownError(
 class TelegramApiHttpError extends Error {
   readonly status: number | undefined;
   readonly retryAfterSeconds: number | undefined;
+  readonly rejectedRequestMethod: string | undefined;
   requestTarget?: { chatId: number; threadId: number };
   constructor(
     message: string,
     status: number | undefined,
     retryAfterSeconds: number | undefined,
+    rejectedRequestMethod?: string,
   ) {
     super(message);
     this.status = status;
     this.retryAfterSeconds = retryAfterSeconds;
+    this.rejectedRequestMethod = rejectedRequestMethod;
   }
 }
 
@@ -934,6 +937,12 @@ export function isTelegramStaleTargetHttpError(error: unknown): boolean {
   return /^Telegram API \w+ failed: HTTP 400: Bad Request: (message thread not found|thread not found|topic not found|topic deleted|topic closed|thread closed|forum topic closed|message thread closed|topic_id_invalid|topic_closed)$/i.test(error.message);
 }
 
+/** Only a parsed Telegram rejection of this method proves a request had no effect. */
+export function isTelegramApiRequestRejected(error: unknown, method: string): boolean {
+  return error instanceof TelegramApiHttpError && error.rejectedRequestMethod !== undefined &&
+    error.rejectedRequestMethod === method;
+}
+
 export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   return (
     error instanceof Error && error.message.includes("message is not modified")
@@ -1106,6 +1115,8 @@ async function parseTelegramApiResponse<TResponse>(
       `Telegram API ${method} failed: ${status}${description}`,
       response.status,
       Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined,
+      data?.ok === false && data.error_code === response.status &&
+        [400, 401, 403, 404, 429].includes(response.status) ? method : undefined,
     );
   }
   if (!data) {
@@ -1785,6 +1796,10 @@ export function buildTelegramAnswerGuestQueryBody(
   return body;
 }
 
+export type TelegramWorkspaceThreadDeletionTransport = (
+  authorize: () => { chatId: number; threadId: number },
+) => Promise<void>;
+
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
@@ -1793,7 +1808,9 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
   workspaceAdmission?:
     | TelegramApiWorkspaceAdmissionPort
     | (() => TelegramApiWorkspaceAdmissionPort | undefined);
-}): TelegramBridgeApiRuntime {
+}): TelegramBridgeApiRuntime & {
+  deleteWorkspaceThread: TelegramWorkspaceThreadDeletionTransport;
+} {
   const client = createTelegramApiClient(deps.getBotToken, {
     recordRuntimeEvent: deps.recordRuntimeEvent,
   });
@@ -1807,7 +1824,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
         },
       })
     : client;
-  return createTelegramBridgeApiRuntime({
+  const runtime = createTelegramBridgeApiRuntime({
     client: deps.targetActivity
       ? createTelegramApiTargetTrackingClient(admittedClient, deps.targetActivity)
       : admittedClient,
@@ -1817,6 +1834,17 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
     recordRuntimeEvent: deps.recordRuntimeEvent,
     captureRequestErrorHandler: deps.captureRequestErrorHandler,
   });
+  return {
+    ...runtime,
+    async deleteWorkspaceThread(authorize) {
+      // The exclusive deletion permit replaces ordinary target admission.
+      const target = authorize();
+      const deleted = await client.call<boolean>("deleteForumTopic", {
+        chat_id: target.chatId, message_thread_id: target.threadId,
+      }, { maxAttempts: 1, retrySafety: "non-idempotent" });
+      if (deleted !== true) throw new Error("Telegram Workspace Thread deletion was not confirmed.");
+    },
+  };
 }
 
 export function createTelegramBridgeApiRuntime(

package/node_modules/@llblab/pi-telegram/lib/thread-cleanup-manager.ts

@@ -433,7 +433,12 @@ export function createTelegramThreadCleanupWorkStore(options: {
         publish(file); return { confirmed: true, entry: structuredClone(entry) };
       });
     },
-    list() { return structuredClone(read().workSets); },
+    list() {
+      return structuredClone(withTelegramFileTransaction(
+        `${options.path}.transaction`,
+        () => read().workSets,
+      ));
+    },
   };
 }
 
@@ -542,8 +547,11 @@ export function createTelegramThreadCleanupPermitRuntime(deps: {
     if (fence.leaderEpoch !== leaderEpoch || fence.owner.processId !== owner.processId ||
         fence.owner.processBirthId !== owner.processBirthId) {
       if (!deps.canAdoptFence(fence)) return undefined;
-      try { fence = deps.ledger.adoptThreadCleanupFence(fence,
-        { owner, leaderEpoch }); } catch { return undefined; }
+      try {
+        const adopted = deps.ledger.adoptThreadCleanupFence(fence, { owner, leaderEpoch });
+        if (adopted.destructiveKind !== "manual-thread-cleanup") return undefined;
+        fence = adopted;
+      } catch { return undefined; }
     }
     return deps.getLeaderEpoch() === leaderEpoch ? fence : undefined;
   };