@llblab/pi-telegram 0.50.0 → 0.51.0

package/dist/lib/paths.js

@@ -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";
 /**
  * Resolve the agent data directory for the current Pi-compatible runtime.
@@ -33,6 +33,19 @@ export function resolveAgentDir(input = {}) {
     }
     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, expectedPath) {
+    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() {
     return join(resolveAgentDir(), "telegram.json");
@@ -65,6 +78,10 @@ export function getTelegramDiagnosticsDisplayPaths(profileName) {
 export function resolveTelegramWorkspaceAdmissionPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("workspace-admission", "json", agentDir, profileName);
 }
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export function resolveTelegramWorkspaceAdmissionPathForProfile(profileName) {
+    return resolveTelegramWorkspaceAdmissionPath(resolveAgentDir(), profileName);
+}
 /** Durable inactive Thread cleanup work-set journal. */
 export function resolveTelegramThreadCleanupWorkPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("thread-cleanup", "json", agentDir, profileName);
@@ -77,6 +94,10 @@ export function resolveTelegramChannelPostJournalPath(agentDir = resolveAgentDir
 export function resolveTelegramUpdateJournalPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("inbox", "json", agentDir, profileName);
 }
+/** Profile-only callback shape; binds storage to the configured agent directory. */
+export function resolveTelegramUpdateJournalPathForProfile(profileName) {
+    return resolveTelegramUpdateJournalPath(resolveAgentDir(), profileName);
+}
 /** Durable follower delivery journal, isolated by stable recipient binding. */
 export function resolveTelegramFollowerJournalPath(recipientBindingKey, agentDir = resolveAgentDir(), profileName) {
     if (!recipientBindingKey) {

package/dist/lib/polling.js

@@ -16,8 +16,8 @@ const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_MS = 1_000;
 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/dist/lib/queue.d.ts

@@ -242,6 +242,11 @@ export declare function removeTelegramQueueItemsByMessageIds<TContext = unknown>
     removedItems: TelegramQueueItem<TContext>[];
     removedCount: number;
 };
+export declare function removeTelegramQueuedGuestPromptByOrder<TContext = unknown>(items: TelegramQueueItem<TContext>[], queueOrder: number): {
+    items: TelegramQueueItem<TContext>[];
+    removedItems: PendingTelegramTurn[];
+    removedCount: number;
+};
 export declare function applyTelegramQueuePromptReactionDisposition<TContext = unknown>(items: TelegramQueueItem<TContext>[], messageId: number, disposition: TelegramQueueReactionDisposition, destinationLaneOrder?: number, scope?: TelegramQueueMessageScope): {
     items: TelegramQueueItem<TContext>[];
     changed: boolean;
@@ -469,7 +474,7 @@ export interface TelegramAgentEndHookRuntimeDeps<TTurn extends PendingTelegramTu
     getActiveTurn: () => TTurn | undefined;
     loadConfig?: () => Promise<void>;
     extractAssistant: (messages: readonly TMessage[]) => TelegramAgentEndAssistantResult;
-    isRecoveredAssistantAlreadyPublished?: (assistant: TelegramAgentEndAssistantResult) => boolean;
+    isAssistantAlreadyPublished?: (assistant: TelegramAgentEndAssistantResult) => boolean;
     getFoldQueuedPromptsIntoHistory: () => boolean;
     resetRuntimeState: () => void;
     isSessionActive?: (ctx: TContext) => boolean;
@@ -624,6 +629,7 @@ export interface TelegramQueueMutationController<TContext> {
     reorder: (ctx: TContext) => void;
     clear: (ctx: TContext) => number;
     removeByMessageIds: (messageIds: number[], ctx: TContext, scope?: TelegramQueueMessageScope) => number;
+    removeGuestPromptByQueueOrder?: (queueOrder: number, ctx: TContext) => boolean;
     applyReactionByMessageId: (messageId: number, disposition: TelegramQueueReactionDisposition, ctx: TContext, scope?: TelegramQueueMessageScope) => boolean;
 }
 export interface TelegramControlQueueControllerDeps<TContext> {
@@ -673,6 +679,7 @@ export declare function createTelegramQueueMutationController<TContext>(deps: Te
 export declare function reorderTelegramQueueItemsRuntime<TContext>(deps: TelegramQueueMutationRuntimeDeps<TContext>): void;
 export declare function clearTelegramQueueItemsRuntime<TContext>(deps: TelegramQueueMutationRuntimeDeps<TContext>): number;
 export declare function removeTelegramQueueItemsByMessageIdsRuntime<TContext>(messageIds: number[], deps: TelegramQueueMutationRuntimeDeps<TContext>, scope?: TelegramQueueMessageScope): number;
+export declare function removeTelegramQueuedGuestPromptByOrderRuntime<TContext>(queueOrder: number, deps: TelegramQueueMutationRuntimeDeps<TContext>): boolean;
 export declare function applyTelegramQueuePromptReactionDispositionRuntime<TContext>(messageId: number, disposition: TelegramQueueReactionDisposition, deps: TelegramQueueMutationRuntimeDeps<TContext>, scope?: TelegramQueueMessageScope): boolean;
 export declare function enqueueTelegramPromptTurnRuntime<TMessage, TContext = unknown>(messages: TMessage[], deps: TelegramPromptEnqueueRuntimeDeps<TMessage, TContext>): Promise<PendingTelegramTurn>;
 export declare function createTelegramPromptEnqueueController<TMessage, TContext = unknown>(deps: TelegramPromptEnqueueControllerDeps<TMessage, TContext>): TelegramPromptEnqueueController<TMessage, TContext>;

package/dist/lib/queue.js

@@ -491,6 +491,21 @@ export function removeTelegramQueueItemsByMessageIds(items, messageIds, scope) {
         removedCount: removedItems.length,
     };
 }
+export function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
+    const index = items.findIndex((item) => {
+        return isPendingTelegramTurn(item) &&
+            item.guestQueryId !== undefined &&
+            item.queueOrder === queueOrder;
+    });
+    if (index < 0)
+        return { items, removedItems: [], removedCount: 0 };
+    const removedItem = items[index];
+    return {
+        items: [...items.slice(0, index), ...items.slice(index + 1)],
+        removedItems: [removedItem],
+        removedCount: 1,
+    };
+}
 export function applyTelegramQueuePromptReactionDisposition(items, messageId, disposition, destinationLaneOrder, scope) {
     let nextItems = items;
     for (const [index, item] of items.entries()) {
@@ -854,8 +869,7 @@ export function createTelegramAgentEndHook(deps) {
             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;
@@ -1440,6 +1454,7 @@ export function createTelegramQueueMutationController(deps) {
         reorder: (ctx) => reorderTelegramQueueItemsRuntime(buildRuntimeDeps(ctx)),
         clear: (ctx) => clearTelegramQueueItemsRuntime(buildRuntimeDeps(ctx)),
         removeByMessageIds: (messageIds, ctx, scope) => removeTelegramQueueItemsByMessageIdsRuntime(messageIds, buildRuntimeDeps(ctx), scope),
+        removeGuestPromptByQueueOrder: (queueOrder, ctx) => removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, buildRuntimeDeps(ctx)),
         applyReactionByMessageId: (messageId, disposition, ctx, scope) => applyTelegramQueuePromptReactionDispositionRuntime(messageId, disposition, buildRuntimeDeps(ctx), scope),
     };
 }
@@ -1492,6 +1507,17 @@ export function removeTelegramQueueItemsByMessageIdsRuntime(messageIds, deps, sc
     updateTelegramQueueStatusRuntime(deps);
     return removedCount;
 }
+export function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
+    const { items, removedItems, removedCount } = removeTelegramQueuedGuestPromptByOrder(deps.getQueuedItems(), queueOrder);
+    if (removedCount === 0)
+        return false;
+    // A menu Skip means permanent discard, so settle durable admission before
+    // removing the live item. A failed settlement keeps the prompt retryable.
+    deps.onItemsDiscarded?.(removedItems, deps.ctx);
+    deps.setQueuedItems(items);
+    updateTelegramQueueStatusRuntime(deps);
+    return true;
+}
 export function applyTelegramQueuePromptReactionDispositionRuntime(messageId, disposition, deps, scope) {
     const queuedItems = deps.getQueuedItems();
     const changesLane = queuedItems.some((item) => {

package/dist/lib/replies.d.ts

@@ -190,6 +190,7 @@ export declare const TELEGRAM_GUEST_PLACEHOLDER_FRAME_MS = 1000;
 export declare const TELEGRAM_GUEST_PLACEHOLDER_MIN_MS = 20000;
 export declare const TELEGRAM_GUEST_PLACEHOLDER_MAX_MS = 26000;
 export declare const TELEGRAM_GUEST_PLACEHOLDER_FRAMES: readonly ["<b>🌎 Working on it.</b>", "<b>🌍 Working on it.</b>", "<b>🌏 Working on it..</b>", "<b>🌎 Working on it..</b>", "<b>🌍 Working on it...</b>", "<b>🌏 Working on it...</b>"];
+export declare const TELEGRAM_DISMISSED_GUEST_PLACEHOLDER_TEXT = "\u2063";
 export declare function buildTelegramGuestPlaceholderFrame(step: number): string;
 export interface TelegramGuestPlaceholderRuntimeDeps {
     editGuestInlineMessage: (inlineMessageId: string, content: {
@@ -211,5 +212,7 @@ export interface TelegramGuestPlaceholderRuntime {
     stop: (inlineMessageId: string) => Promise<void>;
     /** Cancels every loop without waiting for in-flight edits (session shutdown). */
     stopAll: () => void;
+    /** Stops rotation and visually clears the inline placeholder. */
+    dismiss: (inlineMessageId: string) => Promise<void>;
 }
 export declare function createTelegramGuestPlaceholderRuntime(deps: TelegramGuestPlaceholderRuntimeDeps): TelegramGuestPlaceholderRuntime;

package/dist/lib/replies.js

@@ -612,6 +612,9 @@ export const TELEGRAM_GUEST_PLACEHOLDER_FRAMES = [
     "<b>🌍 Working on it...</b>",
     "<b>🌏 Working on it...</b>",
 ];
+// Telegram does not expose deletion for inline messages. This non-printing,
+// non-empty edit visually clears a guest placeholder after its query is skipped.
+export const TELEGRAM_DISMISSED_GUEST_PLACEHOLDER_TEXT = "\u2063";
 export function buildTelegramGuestPlaceholderFrame(step) {
     const frames = TELEGRAM_GUEST_PLACEHOLDER_FRAMES;
     const index = ((step % frames.length) + frames.length) % frames.length;
@@ -734,5 +737,19 @@ export function createTelegramGuestPlaceholderRuntime(deps) {
             }
             sessions.clear();
         },
+        async dismiss(inlineMessageId) {
+            await stop(inlineMessageId);
+            try {
+                await deps.editGuestInlineMessage(inlineMessageId, {
+                    text: TELEGRAM_DISMISSED_GUEST_PLACEHOLDER_TEXT,
+                    parseMode: "HTML",
+                });
+            }
+            catch (error) {
+                deps.recordRuntimeEvent?.("guest", error, {
+                    phase: "guest-placeholder-dismiss",
+                });
+            }
+        },
     };
 }

package/dist/lib/sync.d.ts

@@ -97,6 +97,15 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
 export declare function markTelegramConfigSyncChange<TSyncState extends TelegramSyncState>(state: TSyncState, action: string, options?: {
     nowMs?: number;
 }): TSyncState;
+export declare 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;
 export interface TelegramSessionRestartThreadCleanupDeps<TSyncState extends TelegramSyncState> extends Omit<TelegramManualThreadDisconnectDeps<TSyncState>, "stopPolling"> {
     suspendPolling: () => Promise<void>;
 }

package/dist/lib/sync.js

@@ -6,6 +6,7 @@
 import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from "./telegram-api.js";
 import { getTelegramTargetKey } from "./target.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
+import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
 import { createTelegramCleanupTargetProtection, commitTelegramWorkspaceProvisionBinding, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, normalizeTelegramWorkspacePath, provisionOwnBusTopic, } from "./threads.js";
 export function markTelegramConfigSyncChange(state, action, options) {
@@ -24,6 +25,42 @@ export function markTelegramConfigSyncChange(state, action, options) {
     });
     return nextState;
 }
+export function createTelegramPreservedLeaderQuitHandler(deps) {
+    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 function createTelegramSessionRestartThreadCleanupHandler(deps) {
     return createTelegramManualThreadDisconnectHandler({
         ...deps,
@@ -353,10 +390,13 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
     };
     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 })
+        ? deps.topicTargetStore.claimWorkspaceIdentity(normalizedLeaderCwd, deps.instanceId, legacyLeaderRecord?.instanceId, { 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 (result) => {
@@ -381,7 +421,14 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
         assertLeaderEpoch("before-workspace-persist");
         await deps.topicTargetStore.persist();
         assertLeaderEpoch("after-workspace-persist");
-        return { ...result, ...(committed.displayTitle ? { displayTitle: committed.displayTitle } : {}) };
+        const { target: _target, slot: _slot, threadName: _threadName, displayTitle: _displayTitle, ...rest } = result;
+        return {
+            ...rest,
+            target: { ...committed.target },
+            slot: committed.slot ?? result.slot,
+            ...(committed.threadName ? { threadName: committed.threadName } : {}),
+            ...(committed.displayTitle ? { displayTitle: committed.displayTitle } : {}),
+        };
     };
     try {
         const unavailableTargetKeys = new Set([

package/dist/lib/telegram-api.d.ts

@@ -484,6 +484,8 @@ export declare function getTelegramApiErrorRequestTarget(error: unknown): {
     threadId: number;
 } | undefined;
 export declare function isTelegramStaleTargetHttpError(error: unknown): boolean;
+/** Only a parsed Telegram rejection of this method proves a request had no effect. */
+export declare function isTelegramApiRequestRejected(error: unknown, method: string): boolean;
 export declare function isTelegramMessageNotModifiedError(error: unknown): boolean;
 export declare function isTelegramApiMethodRetrySafe(method: string): boolean;
 export declare function isRetryableTelegramApiError(error: unknown): boolean;
@@ -522,13 +524,19 @@ export declare function createTelegramAssistantDraftSender(deps: {
     sendRichMessageDraft: TelegramBridgeApiRuntime["sendRichMessageDraft"];
 }): TelegramBridgeApiRuntime["sendMessageDraft"];
 export declare function buildTelegramAnswerGuestQueryBody(guestQueryId: string, text?: string, options?: TelegramAnswerGuestQueryOptions): Record<string, unknown>;
+export type TelegramWorkspaceThreadDeletionTransport = (authorize: () => {
+    chatId: number;
+    threadId: number;
+}) => Promise<void>;
 export declare function createDefaultTelegramBridgeApiRuntime(deps: {
     getBotToken: () => string | undefined;
     recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
     captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
     targetActivity?: TelegramApiTargetActivityRuntime;
     workspaceAdmission?: TelegramApiWorkspaceAdmissionPort | (() => TelegramApiWorkspaceAdmissionPort | undefined);
-}): TelegramBridgeApiRuntime;
+}): TelegramBridgeApiRuntime & {
+    deleteWorkspaceThread: TelegramWorkspaceThreadDeletionTransport;
+};
 export declare function createTelegramBridgeApiRuntime(deps: TelegramBridgeApiRuntimeDeps): TelegramBridgeApiRuntime;
 /**
  * Creates a low-level Telegram Bot API client.

package/dist/lib/telegram-api.js

@@ -231,11 +231,13 @@ export function isTelegramApiCommitUnknownError(error) {
 class TelegramApiHttpError extends Error {
     status;
     retryAfterSeconds;
+    rejectedRequestMethod;
     requestTarget;
-    constructor(message, status, retryAfterSeconds) {
+    constructor(message, status, retryAfterSeconds, rejectedRequestMethod) {
         super(message);
         this.status = status;
         this.retryAfterSeconds = retryAfterSeconds;
+        this.rejectedRequestMethod = rejectedRequestMethod;
     }
 }
 function attachTelegramApiRequestTarget(error, body) {
@@ -267,6 +269,11 @@ export function isTelegramStaleTargetHttpError(error) {
         return false;
     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, method) {
+    return error instanceof TelegramApiHttpError && error.rejectedRequestMethod !== undefined &&
+        error.rejectedRequestMethod === method;
+}
 export function isTelegramMessageNotModifiedError(error) {
     return (error instanceof Error && error.message.includes("message is not modified"));
 }
@@ -398,7 +405,8 @@ async function parseTelegramApiResponse(response, method) {
         const retryAfterHeader = response.headers?.get("retry-after");
         const retryAfterSeconds = data?.parameters?.retry_after ??
             (retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined);
-        throw new TelegramApiHttpError(`Telegram API ${method} failed: ${status}${description}`, response.status, Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : undefined);
+        throw new TelegramApiHttpError(`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) {
         throw new TelegramApiMalformedSuccessError(method, "returned invalid JSON");
@@ -856,7 +864,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps) {
             },
         })
         : client;
-    return createTelegramBridgeApiRuntime({
+    const runtime = createTelegramBridgeApiRuntime({
         client: deps.targetActivity
             ? createTelegramApiTargetTrackingClient(admittedClient, deps.targetActivity)
             : admittedClient,
@@ -866,6 +874,18 @@ 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("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(deps) {
     const recoverRequestError = async (handler, error) => {

package/dist/lib/thread-cleanup-manager.js

@@ -342,7 +342,9 @@ export function createTelegramThreadCleanupWorkStore(options) {
                 return { confirmed: true, entry: structuredClone(entry) };
             });
         },
-        list() { return structuredClone(read().workSets); },
+        list() {
+            return structuredClone(withTelegramFileTransaction(`${options.path}.transaction`, () => read().workSets));
+        },
     };
 }
 export async function commitTelegramInactiveThreadCleanup(input) {
@@ -401,7 +403,10 @@ export function createTelegramThreadCleanupPermitRuntime(deps) {
             if (!deps.canAdoptFence(fence))
                 return undefined;
             try {
-                fence = deps.ledger.adoptThreadCleanupFence(fence, { owner, leaderEpoch });
+                const adopted = deps.ledger.adoptThreadCleanupFence(fence, { owner, leaderEpoch });
+                if (adopted.destructiveKind !== "manual-thread-cleanup")
+                    return undefined;
+                fence = adopted;
             }
             catch {
                 return undefined;

package/dist/lib/threads.d.ts

@@ -212,6 +212,8 @@ export interface TelegramTopicTargetStore {
     refresh?: () => Promise<void>;
     persist: () => Promise<void>;
     invalidateTarget: (target: TelegramTarget, isCurrent: () => boolean, lastSyncError: string) => Promise<boolean>;
+    /** Caller proves owner detachment; this does not assert Telegram Thread absence. */
+    detachTargetOwner: (expected: TelegramTopicTargetRecord, isCurrent: () => boolean) => Promise<boolean>;
     list: () => TelegramTopicTargetRecord[];
     getFollowerRecoveryHintByTarget?: (target: TelegramTarget) => {
         slot?: string;

package/dist/lib/threads.js

@@ -11,7 +11,7 @@ import { isDeepStrictEqual } from "node:util";
 import { isTelegramApiCommitUnknownError, TelegramApiCommitUnknownError, } from "./telegram-api.js";
 import { withTelegramFileTransaction } from "./locks.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
-import { planTelegramWorkspaceSlotAllocation, TELEGRAM_WORKSPACE_SLOTS, } from "./workspace-slots.js";
+import { planTelegramWorkspaceSlotAllocation, TELEGRAM_WORKSPACE_SLOTS, TelegramWorkspaceSlotUnavailableError, } from "./workspace-slots.js";
 import { resolveAgentDir, resolveTelegramProfileTempFilePath, } from "./paths.js";
 const TELEGRAM_WORKSPACE_KEY_MAX_LENGTH = 180;
 const TELEGRAM_SESSION_ID_MAX_LENGTH = 256;
@@ -1301,19 +1301,31 @@ export function createTelegramTopicTargetStore(options) {
         dirty = true;
         mutationRevision += 1;
     };
-    const persistSnapshot = (invalidation) => {
+    const markWorkspaceBindingInactiveByTarget = (target, inactiveSinceMs = getNowMs()) => {
+        if (!Number.isFinite(inactiveSinceMs) || inactiveSinceMs < 0)
+            return false;
+        for (const [key, binding] of workspaceBindings) {
+            if (!targetMatches(binding.target, target) || binding.inactiveSinceMs !== undefined)
+                continue;
+            workspaceBindings.set(key, { ...binding, inactiveSinceMs });
+            markDirty();
+            return true;
+        }
+        return false;
+    };
+    const persistSnapshot = (transition) => {
         const persist = persistQueue.then(async () => {
             const path = getPath();
             if (loadedPath !== path && !dirty)
                 resetForPath(path);
             if (options.canPersist && !options.canPersist()) {
-                if (!invalidation)
+                if (!transition)
                     await loadFromDisk();
                 return false;
             }
             if (!dirty || !loaded)
                 await loadFromDisk();
-            if (invalidation && !invalidation.isCurrent())
+            if (transition && !transition.isCurrent())
                 return false;
             const nowMs = getNowMs();
             reservations = reservations.filter((reservation) => reservation.expiresAtMs === undefined ||
@@ -1322,6 +1334,11 @@ export function createTelegramTopicTargetStore(options) {
             const currentRecords = Array.from(records.values())
                 .filter(isPersistedThreadRecord)
                 .map(cloneRecord);
+            if (transition?.kind === "detach") {
+                const owners = currentRecords.filter((record) => targetMatches(record.target, transition.target));
+                if (owners.length !== 1 || !isDeepStrictEqual(normalizeRecord(owners[0]), transition.owner))
+                    return false;
+            }
             records = new Map(currentRecords.map((record) => [
                 getRecordOwnerKey(record),
                 cloneRecord(record),
@@ -1358,21 +1375,34 @@ export function createTelegramTopicTargetStore(options) {
                     return serialized;
                 }),
             };
-            if (invalidation) {
-                const record = file.threads.find((record) => targetMatches(record.target, invalidation.target));
+            if (transition) {
+                const record = file.threads.find((record) => targetMatches(record.target, transition.target));
                 if (!record)
                     return false;
+                if (transition.kind === "detach") {
+                    const bindings = file.workspaceBindings.filter((binding) => targetMatches(binding.target, record.target));
+                    if (bindings.length !== 1 || !/^[A-Z]$/.test(record.slot ?? "") ||
+                        bindings[0].slot !== record.slot)
+                        return false;
+                }
                 file.threads = file.threads.filter((candidate) => candidate !== record);
-                file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
-                file.syncObservations.push({
-                    target: { ...record.target },
-                    syncStatus: "deleted",
-                    observedAtMs: nowMs,
-                    ...(record.instanceId ? { instanceId: record.instanceId } : {}),
-                    ...(record.slot ? { slot: record.slot } : {}),
-                    lastSyncError: invalidation.lastSyncError,
-                    lastReconcileAction: "mark-stale",
-                });
+                for (const binding of file.workspaceBindings) {
+                    if (targetMatches(binding.target, transition.target) && binding.inactiveSinceMs === undefined) {
+                        binding.inactiveSinceMs = nowMs;
+                    }
+                }
+                if (transition.kind === "invalidate") {
+                    file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
+                    file.syncObservations.push({
+                        target: { ...record.target },
+                        syncStatus: "deleted",
+                        observedAtMs: nowMs,
+                        ...(record.instanceId ? { instanceId: record.instanceId } : {}),
+                        ...(record.slot ? { slot: record.slot } : {}),
+                        lastSyncError: transition.lastSyncError,
+                        lastReconcileAction: "mark-stale",
+                    });
+                }
             }
             let persistedSemanticSnapshot;
             try {
@@ -1382,7 +1412,7 @@ export function createTelegramTopicTargetStore(options) {
                 /* missing or invalid snapshots must be replaced */
             }
             // Normalize optional fields to wire JSON; object key order is not a state change.
-            if (isDeepStrictEqual(persistedSemanticSnapshot, getTelegramStateSemanticSnapshot(JSON.parse(JSON.stringify(file)))) &&
+            if (!transition && isDeepStrictEqual(persistedSemanticSnapshot, getTelegramStateSemanticSnapshot(JSON.parse(JSON.stringify(file)))) &&
                 mutationRevision === persistedRevision &&
                 statusRevision === persistedStatusRevision) {
                 loadedPath = path;
@@ -1398,18 +1428,21 @@ export function createTelegramTopicTargetStore(options) {
             });
             await chmod(tempPath, 0o600);
             try {
-                if (invalidation) {
+                if (transition) {
                     let applied = false;
                     const commit = () => {
                         if (getPath() !== path || mutationRevision !== persistedRevision ||
-                            statusRevision !== persistedStatusRevision || !invalidation.isCurrent())
+                            statusRevision !== persistedStatusRevision || !transition.isCurrent())
                             return;
                         // Fence and rename share one synchronous commit boundary. No stale
-                        // invalidation enters the live projection before durable commit.
+                        // transition enters the live projection before durable commit.
                         renameSync(tempPath, path);
                         loadedPath = path;
-                        records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, invalidation.target)));
+                        records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, transition.target)));
                         syncObservations = file.syncObservations;
+                        workspaceBindings = new Map(file.workspaceBindings.map((binding) => [
+                            getWorkspaceBindingMapKey(binding), cloneWorkspaceBinding(binding),
+                        ]));
                         mutationRevision += 1;
                         dirty = false;
                         applied = true;
@@ -1465,7 +1498,13 @@ export function createTelegramTopicTargetStore(options) {
             await persistSnapshot();
         },
         invalidateTarget(target, isCurrent, lastSyncError) {
-            return persistSnapshot({ target, isCurrent, lastSyncError });
+            return persistSnapshot({ kind: "invalidate", target, isCurrent, lastSyncError });
+        },
+        detachTargetOwner(expected, isCurrent) {
+            const owner = normalizeRecord(expected);
+            if (!owner)
+                return Promise.resolve(false);
+            return persistSnapshot({ kind: "detach", owner, target: owner.target, isCurrent });
         },
         list() {
             return Array.from(records.values()).map(cloneRecord);
@@ -1994,18 +2033,7 @@ export function createTelegramTopicTargetStore(options) {
             markDirty();
             return true;
         },
-        markWorkspaceBindingInactiveByTarget(target, inactiveSinceMs = getNowMs()) {
-            if (!Number.isFinite(inactiveSinceMs) || inactiveSinceMs < 0)
-                return false;
-            for (const [key, binding] of workspaceBindings) {
-                if (!targetMatches(binding.target, target) || binding.inactiveSinceMs !== undefined)
-                    continue;
-                workspaceBindings.set(key, { ...binding, inactiveSinceMs });
-                markDirty();
-                return true;
-            }
-            return false;
-        },
+        markWorkspaceBindingInactiveByTarget,
         markWorkspaceBindingActiveByTarget(target) {
             if (hasWorkspaceRetirementConflict({ target }))
                 return false;
@@ -2419,8 +2447,11 @@ export function createTelegramTopicTargetStore(options) {
             const record = Array.from(records.values()).find((entry) => targetMatches(entry.target, target));
             const pending = syncStatus === "deleted" ? pendingProvisions.find((entry) => entry.target && targetMatches(entry.target, target)) : undefined;
             const source = record ?? pending;
+            // Confirmed absence ends this binding's active target lifetime, even after
+            // an earlier stale observation already removed its live record.
+            const inactive = syncStatus === "deleted" && markWorkspaceBindingInactiveByTarget(target);
             if (!source?.target)
-                return false;
+                return inactive;
             syncObservations = syncObservations.filter((entry) => !targetMatches(entry.target, target));
             syncObservations.push({
                 target: { ...source.target }, syncStatus, observedAtMs: getNowMs(),
@@ -3576,7 +3607,7 @@ export function createTelegramTopicTargetProvisioner(deps) {
         if (existing && isCurrentThreadRecord(existing)) {
             const slot = existing.slot ?? deps.store.allocateSlot(request.profileKey);
             if (!slot) {
-                throw new Error("Telegram Workspace slot reservation is unavailable.");
+                throw new TelegramWorkspaceSlotUnavailableError();
             }
             const occupied = listOccupiedTelegramThreadIdentities({
                 records: deps.store.list(),
@@ -3691,7 +3722,7 @@ export function createTelegramTopicTargetProvisioner(deps) {
                     (candidateThreadName ? undefined : identity?.slot) ??
                     preferredNameSlot), request.workspaceBindingKey);
         if (!slot) {
-            throw new Error("Telegram Workspace slot reservation is unavailable.");
+            throw new TelegramWorkspaceSlotUnavailableError();
         }
         const uniqueCandidate = candidateThreadName &&
             isTelegramTopicThreadNameValidForSlot(candidateThreadName, slot) &&