@llblab/pi-telegram 0.51.6 → 0.52.1

package/dist/lib/queue.js

@@ -5,6 +5,7 @@
  */
 import { createHash } from "node:crypto";
 import { isVoiceTurn } from "./voice.js";
+import { isWireRecord as isQueuePayloadRecord } from "./wire.js";
 import { isTelegramApiCommitUnknownError } from "./telegram-api.js";
 export const TELEGRAM_QUEUE_LANE_CONTRACTS = [
     // Control lane intentionally accepts both direct controls and resume prompts.
@@ -30,7 +31,67 @@ export const TELEGRAM_QUEUE_LANE_CONTRACTS = [
     },
 ];
 export const TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES = 8 * 1024 * 1024;
-export const TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS = 256;
+const TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS = 256;
+function parseQueuePayloadReceipt(value, kind) {
+    if (!isQueuePayloadRecord(value) || value.queueKind !== kind ||
+        typeof value.receiptId !== "string" || !value.receiptId ||
+        (value.journalBindingKey !== undefined && (typeof value.journalBindingKey !== "string" || !value.journalBindingKey.trim())) ||
+        !Array.isArray(value.sourceUpdateIds) || value.sourceUpdateIds.length === 0 ||
+        value.sourceUpdateIds.some((id, index) => !Number.isSafeInteger(id) || id < 0 ||
+            (index > 0 && id <= value.sourceUpdateIds[index - 1])))
+        return undefined;
+    return { queueKind: kind, receiptId: value.receiptId, sourceUpdateIds: value.sourceUpdateIds,
+        ...(typeof value.journalBindingKey === "string" ? { journalBindingKey: value.journalBindingKey } : {}) };
+}
+/** Data decoder shared by authenticated IPC and cold storage; decoding grants no admission. */
+export function parseTelegramQueueHandoffPayload(value) {
+    if (!isQueuePayloadRecord(value) || (value.kind !== "prompt" && value.kind !== "control"))
+        return undefined;
+    const target = isQueuePayloadRecord(value.target) && typeof value.target.chatId === "number"
+        ? { chatId: value.target.chatId, ...(typeof value.target.threadId === "number" ? { threadId: value.target.threadId } : {}) } : undefined;
+    const transportStamp = isQueuePayloadRecord(value.transportStamp) &&
+        typeof value.transportStamp.profile === "string" && typeof value.transportStamp.generation === "string"
+        ? { profile: value.transportStamp.profile, generation: value.transportStamp.generation } : undefined;
+    if (!Number.isSafeInteger(value.chatId) || (value.target !== undefined && !target) ||
+        (value.transportStamp !== undefined && !transportStamp) || !Number.isSafeInteger(value.replyToMessageId) ||
+        (value.guestQueryId !== undefined && typeof value.guestQueryId !== "string") ||
+        (value.guestInlineMessageId !== undefined && typeof value.guestInlineMessageId !== "string") ||
+        !Number.isSafeInteger(value.queueOrder) || (value.queueLane !== "control" && value.queueLane !== "priority" && value.queueLane !== "default") ||
+        !Number.isSafeInteger(value.laneOrder) || typeof value.statusSummary !== "string" || !Array.isArray(value.admissionReceipts))
+        return undefined;
+    const admissionReceipts = value.admissionReceipts.map(receipt => parseQueuePayloadReceipt(receipt, value.kind));
+    if (admissionReceipts.length === 0 || admissionReceipts.length > TELEGRAM_QUEUE_HANDOFF_MAX_RECEIPTS ||
+        admissionReceipts.some(receipt => !receipt))
+        return undefined;
+    const base = { chatId: value.chatId, ...(target ? { target } : {}), ...(transportStamp ? { transportStamp } : {}),
+        replyToMessageId: value.replyToMessageId,
+        ...(typeof value.guestQueryId === "string" ? { guestQueryId: value.guestQueryId } : {}),
+        ...(typeof value.guestInlineMessageId === "string" ? { guestInlineMessageId: value.guestInlineMessageId } : {}),
+        queueOrder: value.queueOrder, queueLane: value.queueLane,
+        laneOrder: value.laneOrder, statusSummary: value.statusSummary,
+        admissionReceipts: admissionReceipts };
+    if (value.kind === "control") {
+        return value.queueLane === "control" && (value.controlType === "status" || value.controlType === "model")
+            ? { kind: "control", controlType: value.controlType, ...base } : undefined;
+    }
+    if (value.queueLane === "control" || !Array.isArray(value.sourceMessageIds) || value.sourceMessageIds.some(id => !Number.isSafeInteger(id)) ||
+        !Array.isArray(value.queuedAttachments) || value.queuedAttachments.some(attachment => !isQueuePayloadRecord(attachment) ||
+        typeof attachment.path !== "string" || typeof attachment.fileName !== "string") ||
+        !Array.isArray(value.content) || value.content.some(content => !isQueuePayloadRecord(content) ||
+        (content.type === "text" ? typeof content.text !== "string" : content.type === "image"
+            ? typeof content.data !== "string" || typeof content.mimeType !== "string" : true)) ||
+        typeof value.historyText !== "string" || (value.priorityEmoji !== undefined && typeof value.priorityEmoji !== "string") ||
+        (value.reactionSuppressionEmoji !== undefined && typeof value.reactionSuppressionEmoji !== "string") ||
+        (value.voiceReplyPreferred !== undefined && typeof value.voiceReplyPreferred !== "boolean") ||
+        (value.voiceReplyRequired !== undefined && typeof value.voiceReplyRequired !== "boolean"))
+        return undefined;
+    return { kind: "prompt", ...base, sourceMessageIds: value.sourceMessageIds,
+        queuedAttachments: value.queuedAttachments, content: value.content, historyText: value.historyText,
+        ...(typeof value.priorityEmoji === "string" ? { priorityEmoji: value.priorityEmoji } : {}),
+        ...(typeof value.reactionSuppressionEmoji === "string" ? { reactionSuppressionEmoji: value.reactionSuppressionEmoji } : {}),
+        ...(typeof value.voiceReplyPreferred === "boolean" ? { voiceReplyPreferred: value.voiceReplyPreferred } : {}),
+        ...(typeof value.voiceReplyRequired === "boolean" ? { voiceReplyRequired: value.voiceReplyRequired } : {}) };
+}
 export function createTelegramQueueAdmissionReceipt(options) {
     if (options.sourceUpdateIds.length === 0)
         return undefined;
@@ -100,7 +161,7 @@ export function assertTelegramQueueItemAdmissionValid(item) {
 function getTelegramQueueLaneRank(lane) {
     return getTelegramQueueLaneContract(lane).dispatchRank;
 }
-export function isPendingTelegramTurn(item) {
+function isPendingTelegramTurn(item) {
     return item.kind === "prompt";
 }
 export function createTelegramQueueStore(initialItems = []) {
@@ -148,7 +209,7 @@ export function createTelegramTransportStampedQueueStore(store, getTransportStam
         },
     };
 }
-export function isTelegramQueueItemSkipped(item) {
+function isTelegramQueueItemSkipped(item) {
     return item.kind === "prompt" && Boolean(item.reactionSuppressionEmoji);
 }
 export function countExecutableTelegramQueueItems(items) {
@@ -503,7 +564,7 @@ export function removeTelegramQueueItemsByMessageIds(items, messageIds, scope) {
         removedCount: removedItems.length,
     };
 }
-export function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
+function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
     const index = items.findIndex((item) => {
         return isPendingTelegramTurn(item) &&
             item.guestQueryId !== undefined &&
@@ -521,7 +582,7 @@ export function removeTelegramQueuedGuestPromptByOrder(items, queueOrder) {
 export function applyTelegramQueuePromptReactionDisposition(items, messageId, disposition, destinationLaneOrder, scope) {
     let nextItems = items;
     for (const [index, item] of items.entries()) {
-        if (!isPendingTelegramTurn(item) ||
+        if (!isPendingTelegramTurn(item) || item.queueLane === "control" ||
             !isTelegramQueueItemInMessageScope(item, scope) ||
             !item.sourceMessageIds.includes(messageId)) {
             continue;
@@ -1489,7 +1550,15 @@ function updateTelegramQueueStatusRuntime(deps) {
     }
 }
 function commitReorderedTelegramQueueItemsRuntime(items, deps) {
-    deps.setQueuedItems([...items].sort(compareTelegramQueueItems));
+    const pendingHead = deps.hasPendingDispatch?.() ? deps.getQueuedItems()[0] : undefined;
+    const ordered = [...items].sort(compareTelegramQueueItems);
+    if (pendingHead) {
+        const index = ordered.findIndex(item => item.queueOrder === pendingHead.queueOrder && item.kind === pendingHead.kind &&
+            item.chatId === pendingHead.chatId && item.replyToMessageId === pendingHead.replyToMessageId);
+        if (index > 0)
+            ordered.unshift(ordered.splice(index, 1)[0]);
+    }
+    deps.setQueuedItems(ordered);
     updateTelegramQueueStatusRuntime(deps);
 }
 function appendTelegramQueueItemRuntime(item, deps) {
@@ -1499,7 +1568,7 @@ function appendTelegramQueueItemRuntime(item, deps) {
         return;
     commitReorderedTelegramQueueItemsRuntime(nextItems, deps);
 }
-export function reorderTelegramQueueItemsRuntime(deps) {
+function reorderTelegramQueueItemsRuntime(deps) {
     commitReorderedTelegramQueueItemsRuntime(deps.getQueuedItems(), deps);
 }
 export function clearTelegramQueueItemsRuntime(deps) {
@@ -1528,7 +1597,7 @@ export function removeTelegramQueueItemsByMessageIdsRuntime(messageIds, deps, sc
     updateTelegramQueueStatusRuntime(deps);
     return removedCount;
 }
-export function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
+function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps) {
     const { items, removedItems, removedCount } = removeTelegramQueuedGuestPromptByOrder(deps.getQueuedItems(), queueOrder);
     if (removedCount === 0)
         return false;
@@ -1541,8 +1610,22 @@ export function removeTelegramQueuedGuestPromptByOrderRuntime(queueOrder, deps)
 }
 export function applyTelegramQueuePromptReactionDispositionRuntime(messageId, disposition, deps, scope) {
     const queuedItems = deps.getQueuedItems();
+    const suppression = disposition.kind === "reaction-transition" ? disposition.suppressionEmoji :
+        disposition.kind === "suppressed" ? disposition.emoji : disposition.kind === "priority-suppressed" ? disposition.suppressionEmoji : undefined;
+    // Source-addressed control-lane prompts are explicit continuations. Synthetic model-switch turns have no source IDs.
+    // A Pi-owned dispatched head cannot be removed: agent_start must consume that exact item, not its successor.
+    const cancelled = suppression && deps.hasPendingDispatch ? queuedItems.filter((item, index) => isPendingTelegramTurn(item) && item.queueLane === "control" && isTelegramQueueItemInMessageScope(item, scope) &&
+        item.sourceMessageIds.includes(messageId) && !(index === 0 && deps.hasPendingDispatch())) : [];
+    if (cancelled.length) {
+        if (cancelled.some(item => (item.admissionReceipts?.length ?? 0) > 0) && !deps.onItemsDiscarded)
+            return false;
+        deps.onItemsDiscarded?.(cancelled, deps.ctx);
+        deps.setQueuedItems(queuedItems.filter(item => !cancelled.includes(item)));
+        updateTelegramQueueStatusRuntime(deps);
+        return true;
+    }
     const changesLane = queuedItems.some((item) => {
-        if (!isPendingTelegramTurn(item) ||
+        if (!isPendingTelegramTurn(item) || item.queueLane === "control" ||
             !isTelegramQueueItemInMessageScope(item, scope) ||
             !item.sourceMessageIds.includes(messageId)) {
             return false;
@@ -1639,7 +1722,7 @@ export async function executeTelegramControlItemRuntime(item, deps) {
  * Production debounce for deferred queue dispatch; the factory defaults to this
  * so the entrypoint wires ports instead of policy constants.
  */
-export const TELEGRAM_DEFERRED_DISPATCH_DELAY_MS = 50;
+const TELEGRAM_DEFERRED_DISPATCH_DELAY_MS = 50;
 export function createTelegramDeferredQueueDispatchRuntime(deps = {}) {
     let boundContext;
     let generation = 0;
@@ -2004,7 +2087,7 @@ export function createTelegramQueueDispatchController(deps) {
                 const announcementGeneration = nextDispatchAnnouncementGeneration;
                 const dispatchGeneration = deps.getDispatchGeneration?.();
                 deps.updateStatus(ctx);
-                void deps.sendTextReply(dispatchPlan.item.chatId, dispatchPlan.item.replyToMessageId, "<b>⏩ Dispatching next queued turn.</b>", { target: dispatchPlan.item.target }).catch((error) => {
+                void deps.sendTextReply(dispatchPlan.item.chatId, dispatchPlan.item.replyToMessageId, "<b>⏩ Dispatching next queued turn.</b>", { target: dispatchPlan.item.target, parseMode: "HTML" }).catch((error) => {
                     deps.recordRuntimeEvent?.("dispatch", error, {
                         phase: "next-announcement",
                     });

package/dist/lib/recovery.d.ts

@@ -3,7 +3,6 @@
  * Zones: filesystem diagnostics, unclean-shutdown recovery
  * Owns fail-safe classification of temporary ownership and routing artifacts
  */
-import { renameSync } from "node:fs";
 import { type TelegramFileTransactionOptions } from "./locks.ts";
 export type TelegramRuntimeArtifactKind = "owners" | "state" | "transaction";
 export interface TelegramRuntimeCorruptArtifact {
@@ -35,19 +34,19 @@ export type TelegramRuntimeRecoveryResult = {
 } | {
     kind: "blocked-live-owner";
     livePids: number[];
-    quarantineDir?: string;
+    deletedPaths?: string[];
 } | {
     kind: "recovered";
     artifacts: TelegramRuntimeCorruptArtifact[];
-    quarantineDir: string;
+    /** Damaged disposable artifacts deleted per the approved corruption policy; nothing is quarantined. */
+    deletedPaths: string[];
 };
 export interface TelegramRuntimeRecoveryOptions extends TelegramRuntimeRecoveryClassificationOptions {
     recoveryTransactionPath?: string;
-    quarantineRoot?: string;
     pid?: number;
     getNowMs?: () => number;
-    quarantineRename?: typeof renameSync;
-    quarantineRenameRetryDelayMs?: number;
+    /** Fault-injection seam; production uses bounded-retry recursive removal. */
+    removePath?: (path: string) => void;
     transactionOptions?: TelegramFileTransactionOptions;
 }
 export type TelegramPollingStartRecoveryDecision = {
@@ -74,13 +73,34 @@ export interface TelegramPollingStartRecoveryHandlerDeps {
  */
 export declare function classifyTelegramRuntimeRecovery(options: TelegramRuntimeRecoveryClassificationOptions): TelegramRuntimeRecoveryClassification;
 /**
- * Quarantine classifier-approved disposable corruption under two guards.
+ * Delete classifier-approved disposable corruption under two guards.
  *
  * A dedicated recovery transaction serializes recoverers. The ownership
  * transaction then prevents a new Telegram owner from appearing between the
- * final classification and mutation. Every artifact is renamed within its
- * filesystem; durable config and diagnostics never enter the candidate set.
+ * final classification and mutation. Damaged ownership debris and canonical
+ * state are deleted (operator policy: unfinished Restores in unreadable state
+ * are acceptable loss). Durable config and diagnostics never enter the set.
  */
 export declare function recoverTelegramRuntimeState(options: TelegramRuntimeRecoveryOptions): TelegramRuntimeRecoveryResult;
+/**
+ * Remove recovery folders written by earlier releases (runtime root and session folders).
+ * Current releases delete damaged files instead of quarantining them; nothing reads these copies.
+ */
+export declare function removeTelegramLegacyRecoveryStorage(runtimeDir: string): string[];
+export interface TelegramSessionFolderSweeperDeps {
+    getSessionsDir: () => string;
+    getProfileName: () => string | undefined;
+    /** Sessions holding a Workspace slot binding, live registrations and this process's own session. */
+    getKeptSessionIds: () => Iterable<string | undefined>;
+    getNowMs?: () => number;
+    intervalMs?: number;
+}
+/**
+ * Leader housekeeping (operator policy): a session without a Workspace slot loses its
+ * current-profile journal family; the folder disappears once no profile uses it.
+ */
+export declare function createTelegramSessionFolderSweeper(deps: TelegramSessionFolderSweeperDeps): {
+    sweep: () => string[];
+};
 /** Build the `/telegram-connect` recovery boundary around runtime artifacts. */
 export declare function createTelegramPollingStartRecoveryHandler(deps: TelegramPollingStartRecoveryHandlerDeps): () => Promise<TelegramPollingStartRecoveryDecision>;

package/dist/lib/recovery.js

@@ -3,10 +3,10 @@
  * Zones: filesystem diagnostics, unclean-shutdown recovery
  * Owns fail-safe classification of temporary ownership and routing artifacts
  */
-import { randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { isProcessAlive as defaultIsProcessAlive, parseTelegramLockEntry, renameTelegramPathWithRetry, TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, withTelegramFileTransaction, } from "./locks.js";
+import { decodeTelegramSessionDirectoryName, getTelegramProfilePathSuffix } from "./paths.js";
+import { isProcessAlive as defaultIsProcessAlive, parseTelegramLockEntry, TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, withTelegramFileTransaction, } from "./locks.js";
 const OWNER_FILE_PATTERN = /^owner\.([A-Za-z0-9-]+)\.json$/u;
 const RECLAIM_FILE_PATTERN = /^owner\.reclaim\.(\d+)\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$/u;
 function corruption(kind, path, reason) {
@@ -40,6 +40,9 @@ function inspectState(path) {
     if (!existsSync(path))
         return { source: "state", ownerPids: [] };
     try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 8 * 1024 * 1024)
+            return corruption("state", path, `${basename(path)} cannot be safely inspected`);
         JSON.parse(readFileSync(path, "utf8"));
         return { source: "state", ownerPids: [] };
     }
@@ -136,19 +139,19 @@ export function classifyTelegramRuntimeRecovery(options) {
         : { kind: "recoverable-corruption", artifacts };
 }
 /**
- * Quarantine classifier-approved disposable corruption under two guards.
+ * Delete classifier-approved disposable corruption under two guards.
  *
  * A dedicated recovery transaction serializes recoverers. The ownership
  * transaction then prevents a new Telegram owner from appearing between the
- * final classification and mutation. Every artifact is renamed within its
- * filesystem; durable config and diagnostics never enter the candidate set.
+ * final classification and mutation. Damaged ownership debris and canonical
+ * state are deleted (operator policy: unfinished Restores in unreadable state
+ * are acceptable loss). Durable config and diagnostics never enter the set.
  */
 export function recoverTelegramRuntimeState(options) {
-    const pid = options.pid ?? process.pid;
     const transactionPath = options.transactionPath ?? `${options.ownersPath}.transaction`;
     const recoveryTransactionPath = options.recoveryTransactionPath ??
         join(dirname(options.ownersPath), "runtime-recovery.transaction");
-    const quarantineRoot = options.quarantineRoot ?? join(dirname(options.ownersPath), "recovery");
+    const removePath = options.removePath ?? ((path) => rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 }));
     const classificationOptions = {
         ownersPath: options.ownersPath,
         statePaths: options.statePaths,
@@ -167,29 +170,18 @@ export function recoverTelegramRuntimeState(options) {
                 livePids: initial.livePids,
             };
         }
-        let quarantineDir;
+        const deletedPaths = [];
         const recoveredArtifacts = [];
-        const ensureQuarantineDir = () => {
-            if (quarantineDir)
-                return quarantineDir;
-            quarantineDir = join(quarantineRoot, `${options.getNowMs?.() ?? Date.now()}-${pid}-${randomUUID()}`);
-            mkdirSync(quarantineDir, { recursive: true, mode: 0o700 });
-            return quarantineDir;
-        };
-        const quarantineArtifact = (artifact) => {
+        const deleteArtifact = (artifact) => {
             if (!existsSync(artifact.path))
                 return;
-            const destination = join(ensureQuarantineDir(), basename(artifact.path));
-            if (renameTelegramPathWithRetry(artifact.path, destination, {
-                rename: options.quarantineRename,
-                retryDelayMs: options.quarantineRenameRetryDelayMs,
-            })) {
-                recoveredArtifacts.push(artifact);
-            }
+            removePath(artifact.path);
+            deletedPaths.push(artifact.path);
+            recoveredArtifacts.push(artifact);
         };
         for (const artifact of initial.artifacts) {
             if (artifact.kind === "transaction")
-                quarantineArtifact(artifact);
+                deleteArtifact(artifact);
         }
         return withTelegramFileTransaction(transactionPath, () => {
             const current = classifyTelegramRuntimeRecovery({
@@ -200,25 +192,107 @@ export function recoverTelegramRuntimeState(options) {
                 return {
                     kind: "blocked-live-owner",
                     livePids: current.livePids,
-                    quarantineDir,
+                    ...(deletedPaths.length > 0 ? { deletedPaths } : {}),
                 };
             }
             if (current.kind === "recoverable-corruption") {
                 for (const artifact of current.artifacts) {
                     if (artifact.kind !== "transaction")
-                        quarantineArtifact(artifact);
+                        deleteArtifact(artifact);
                 }
             }
-            return recoveredArtifacts.length > 0 && quarantineDir
+            return recoveredArtifacts.length > 0
                 ? {
                     kind: "recovered",
                     artifacts: recoveredArtifacts,
-                    quarantineDir,
+                    deletedPaths,
                 }
                 : { kind: "not-needed" };
         }, options.transactionOptions);
     }, options.transactionOptions);
 }
+/**
+ * Remove recovery folders written by earlier releases (runtime root and session folders).
+ * Current releases delete damaged files instead of quarantining them; nothing reads these copies.
+ */
+export function removeTelegramLegacyRecoveryStorage(runtimeDir) {
+    const removed = [];
+    const remove = (path) => {
+        try {
+            if (!lstatSync(path).isDirectory())
+                return;
+            rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+            removed.push(path);
+        }
+        catch {
+            // Best-effort housekeeping; a later startup retries.
+        }
+    };
+    remove(join(runtimeDir, "recovery"));
+    let sessions = [];
+    try {
+        sessions = readdirSync(join(runtimeDir, "sessions"));
+    }
+    catch { /* no sessions yet */ }
+    for (const session of sessions)
+        remove(join(runtimeDir, "sessions", session, "recovery"));
+    return removed;
+}
+const TELEGRAM_SESSION_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+/**
+ * Leader housekeeping (operator policy): a session without a Workspace slot loses its
+ * current-profile journal family; the folder disappears once no profile uses it.
+ */
+export function createTelegramSessionFolderSweeper(deps) {
+    const getNowMs = deps.getNowMs ?? Date.now;
+    const intervalMs = deps.intervalMs ?? TELEGRAM_SESSION_SWEEP_INTERVAL_MS;
+    let lastSweepAtMs;
+    return {
+        sweep() {
+            const now = getNowMs();
+            if (lastSweepAtMs !== undefined && now - lastSweepAtMs < intervalMs)
+                return [];
+            lastSweepAtMs = now;
+            const sessionsDir = deps.getSessionsDir();
+            const kept = new Set(deps.getKeptSessionIds());
+            const suffix = getTelegramProfilePathSuffix(deps.getProfileName()).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+            const family = new RegExp(`^journal\\.[a-f0-9]{16}${suffix}\\.json(?:\\.segments|\\.retained)?$`, "u");
+            const removed = [];
+            let names;
+            try {
+                names = readdirSync(sessionsDir);
+            }
+            catch {
+                return removed;
+            }
+            for (const name of names) {
+                const sessionId = decodeTelegramSessionDirectoryName(name);
+                if (sessionId === undefined || kept.has(sessionId))
+                    continue;
+                const folder = join(sessionsDir, name);
+                try {
+                    if (!lstatSync(folder).isDirectory())
+                        continue;
+                    for (const entry of readdirSync(folder)) {
+                        if (!family.test(entry))
+                            continue;
+                        const path = join(folder, entry);
+                        rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+                        removed.push(path);
+                    }
+                    if (readdirSync(folder).length === 0) {
+                        rmdirSync(folder);
+                        removed.push(folder);
+                    }
+                }
+                catch {
+                    // Best-effort housekeeping; the next sweep retries.
+                }
+            }
+            return removed;
+        },
+    };
+}
 /** Build the `/telegram-connect` recovery boundary around runtime artifacts. */
 export function createTelegramPollingStartRecoveryHandler(deps) {
     return async () => {
@@ -257,10 +331,7 @@ export function createTelegramPollingStartRecoveryHandler(deps) {
             });
         }
         try {
-            const recovery = recoverTelegramRuntimeState({
-                ownersPath,
-                statePaths,
-            });
+            const recovery = recoverTelegramRuntimeState({ ownersPath, statePaths });
             if (recovery.kind === "blocked-live-owner") {
                 return {
                     kind: "blocked",

package/dist/lib/replies.d.ts

@@ -117,10 +117,6 @@ export declare function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
 }, options?: TelegramReplyTargetOptions & {
     replyMarkup?: TReplyMarkup;
 }): Promise<number | undefined>;
-export declare function sendTelegramNativeRichMessage(chatId: number, richMessage: TelegramInputRichMessage, deps: {
-    recordOwnership?: TelegramReplyOwnershipRecorder["record"];
-    sendRichMessage: (body: TelegramSendRichMessageBody) => Promise<TelegramSentMessage>;
-}, options?: TelegramReplyTargetOptions): Promise<number>;
 export type TelegramAssistantRenderingMode = "rich" | "html";
 export interface TelegramRenderedMessageRuntimeDeps<TReplyMarkup> {
     renderTelegramMessage: (text: string, options?: {

package/dist/lib/replies.js

@@ -498,7 +498,7 @@ export async function sendTelegramNativeMarkdownReply(chatId, replyToMessageId,
     }
     return lastMessageId;
 }
-export async function sendTelegramNativeRichMessage(chatId, richMessage, deps, options) {
+async function sendTelegramNativeRichMessage(chatId, richMessage, deps, options) {
     const sent = await deps.sendRichMessage({
         chat_id: chatId,
         rich_message: richMessage,

package/dist/lib/routing.d.ts

@@ -7,6 +7,7 @@ import * as Bus from "./bus.ts";
 import * as Commands from "./commands.ts";
 import type { TelegramConfigStore } from "./config.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound.ts";
+import type { TelegramUpdateJournalQueuedCompletion, TelegramUpdateJournalQueuedReceiptEvidence } from "./journal.ts";
 import * as Media from "./media.ts";
 import * as Menu from "./menu.ts";
 import * as Model from "./model.ts";
@@ -15,11 +16,12 @@ import * as PromptTemplates from "./prompt-templates.ts";
 import * as Queue from "./queue.ts";
 import type { TelegramBridgeRuntime } from "./runtime.ts";
 import type { TelegramSectionRegistry } from "./sections.ts";
-import type { TelegramInputRichMessage } from "./telegram-api.ts";
+import type { TelegramApiCallOptions, TelegramInputRichMessage } from "./telegram-api.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import type { TelegramInstanceThreadIdentityCandidate, TelegramTopicTargetRecord } from "./threads.ts";
 import * as Turns from "./turns.ts";
+import type { createTelegramWorkspaceExternalProtectionCapture } from "./workspace-retirement.ts";
 interface TelegramPromptPeerView {
     id?: unknown;
     is_bot?: unknown;
@@ -37,9 +39,37 @@ export declare function resolveTelegramGuestPromptPeer(input: {
     guestBotCallerChat?: TelegramPromptPeerView;
     ownerUserId?: number;
 }): string | undefined;
+/** Stable file scope of the remote Guest Mode peer: username, else numeric id; never the bot's own scope. */
+export declare function resolveTelegramGuestFileScope(input: Parameters<typeof resolveTelegramGuestPromptPeer>[0]): string;
 import * as Threads from "./threads.ts";
 import * as Updates from "./updates.ts";
+/** One admitted Restore attempt through recipient readiness, never source dispatch or cleanup. */
+export declare function advanceTelegramWorkspaceRestore(input: {
+    request: Threads.TelegramWorkspaceRestoreRequest;
+    authority: Threads.TelegramWorkspaceRestoreAuthority;
+    restoreStore: Threads.TelegramWorkspaceRestore;
+    getRecipient: () => Threads.TelegramWorkspaceRestoreRecipient | undefined;
+    /** Adapter proves current canonical ownership and authenticates observations; apply needs a fresh issuance. */
+    runRecipient: (input: {
+        intent: Threads.TelegramWorkspaceRestoreIntent;
+        mode: "apply" | "inspect";
+        isCurrent: () => boolean;
+    }) => Promise<{
+        operationId: string;
+        recipient: Threads.TelegramWorkspaceRestoreRecipient;
+        target: Threads.TelegramWorkspaceRestoreRequest["target"];
+        slot: string;
+        ready: boolean;
+    } | undefined>;
+    /**
+     * Recovery for a same-session successor already on the relocated target: it may receive the first grant, but only
+     * read-only inspection runs. It never commits a new relocation or applies a target.
+     */
+    inspectOnly?: true;
+}): Promise<Threads.TelegramWorkspaceRestoreIntent | undefined>;
 export declare const TELEGRAM_ALL_TAB_COMMAND_MAX_AGE_MS: number;
+/** One user-facing answer for expired or previous-process routing controls. */
+export declare const TELEGRAM_ROUTING_CHOICE_EXPIRED = "\u231B Routing choice expired.";
 export declare function isTelegramAllTabCommandExpired(message: {
     date?: number;
     message_thread_id?: number;
@@ -66,7 +96,7 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     configStore: Pick<TelegramConfigStore, "get" | "getAllowedUserId" | "persistAllowedUserId" | "persist"> & {
         set?: TelegramConfigStore["set"];
     };
-    callApi?: <TResponse>(method: string, body: Record<string, unknown>) => Promise<TResponse>;
+    callApi?: <TResponse>(method: string, body: Record<string, unknown>, options?: TelegramApiCallOptions) => Promise<TResponse>;
     getCurrentInstanceId?: () => string | undefined;
     getAdmissionScope?: () => string | undefined;
     getAdmissionJournalBinding?: () => string | undefined;
@@ -87,11 +117,33 @@ export interface TelegramInboundRouteRuntimeDeps<TMessage extends TelegramRouted
     handleTelegramTopicLifecycleUpdate?: (lifecycle: Updates.TelegramTopicLifecycleUpdate<TMessage>, ctx: TContext) => Promise<void> | void;
     handleTelegramThreadTargetObserved?: (target: Threads.TelegramTopicTargetRecord["target"], ctx: TContext) => Promise<void> | void;
     foreignOwnedUpdateForwarder?: Updates.TelegramForeignOwnedUpdateForwarder<TContext, Updates.TelegramMessageReactionUpdated, TCallbackQuery, TMessage>;
-    replaceFollowerThreadTarget?: (input: {
-        record: Threads.TelegramTopicTargetRecord;
-        target: Threads.TelegramTopicTargetRecord["target"];
-        oldTarget: Threads.TelegramTopicTargetRecord["target"];
-    }) => Promise<boolean>;
+    getWorkspaceRestoreStore?: () => Threads.TelegramWorkspaceRestore | undefined;
+    captureWorkspaceExternalProtection?: ReturnType<typeof createTelegramWorkspaceExternalProtectionCapture>;
+    /** Strict committed abandonment plus retained original; shared by Restore and temporary-input cancellation. */
+    inspectRestoreSourceAbandonment?: (updateId: number, journalBindingKey: string) => Threads.TelegramTemporaryThreadCancellationEvidence | undefined;
+    inspectRoutingInputGroupExpiry?: (input: Threads.TelegramTemporaryThreadInput) => readonly Threads.TelegramTemporaryThreadCancellationEvidence[] | undefined;
+    /** Strict active-journal observation only; a hint or missing source never substitutes for this ACK. */
+    inspectRestoreSourceCompletion?: (expected: Updates.TelegramDeferredSourceEvidence & {
+        completionSha256: string;
+    }) => (Updates.TelegramDeferredSourceEvidence & {
+        completionSha256: string;
+    }) | undefined;
+    inspectRestoreQueuedReceipt?: (expected: TelegramUpdateJournalQueuedCompletion & {
+        journalBindingKey: string;
+    }) => TelegramUpdateJournalQueuedReceiptEvidence | undefined;
+    hasWorkspaceRestoreAuthority?: () => boolean;
+    /** Strict complete namespace plus exact current/historical references; only an empty result clears journal protection. */
+    inspectTemporaryThreadSources?: (target: Queue.TelegramQueueTarget, requiredJournalBindingKeys: readonly string[]) => readonly number[] | undefined;
+    /** Quiet period after the last cancelled input before one cleanup attempt; defaults to 1000 ms. */
+    temporaryThreadCleanupDelayMs?: number;
+    getSessionGeneration?: () => number;
+    workspaceRestoreRecipient?: {
+        getSessionId: (ctx: TContext) => string | undefined;
+        getCwd: (ctx: TContext) => string | undefined;
+        getLeaderIdentity: Threads.TelegramLeaderThreadStateRuntime["getIdentity"];
+        followerRegistry: Pick<Bus.TelegramBusFollowerRegistry, "get" | "register">;
+        runFollower: ReturnType<typeof Bus.createTelegramBusWorkspaceRestoreController>;
+    };
     bridgeRuntime: TelegramBridgeRuntime;
     activeTurnRuntime: Queue.TelegramActiveTurnStore;
     mediaGroupRuntime: Media.TelegramMediaGroupController<TMessage, TContext>;
@@ -183,7 +235,21 @@ export declare function createTelegramInboundRouteRuntime<TUpdate extends Update
     message?: TMessage;
     edited_message?: TMessage;
     callback_query?: TCallbackQuery;
-}, TMessage extends TelegramRoutedMessage, TCallbackQuery extends TelegramRoutedCallbackQuery, TContext, TModel extends Model.MenuModel>(deps: TelegramInboundRouteRuntimeDeps<TMessage, TCallbackQuery, TContext, TModel>): Updates.TelegramUpdateRuntimeController<TContext, TUpdate>;
+}, TMessage extends TelegramRoutedMessage, TCallbackQuery extends TelegramRoutedCallbackQuery, TContext, TModel extends Model.MenuModel>(deps: TelegramInboundRouteRuntimeDeps<TMessage, TCallbackQuery, TContext, TModel>): Updates.TelegramUpdateRuntimeController<TContext, TUpdate> & {
+    expireRoutingInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["expireRoutingInput"]>;
+    shouldReviewHistoricalInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["shouldReviewHistoricalInput"]>;
+    shouldHoldPendingInput: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["shouldHoldPendingInput"]>;
+    forgetPreviousWorld(input: Updates.TelegramHeldSourcePreparation<TContext>, captureTransport?: (ctx: TContext) => (() => boolean) | undefined): Promise<{
+        forgotten: number;
+        deleted: number;
+    }>;
+    beforeQueueReceiptPublished: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["beforeQueueReceiptPublished"]>;
+    onQueueReceiptCommitted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onQueueReceiptCommitted"]>;
+    onQueueReceiptCompleted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onQueueReceiptCompleted"]>;
+    onUpdateCompleted: NonNullable<Updates.TelegramUpdateWorkerRuntimeDeps<TContext>["onUpdateCompleted"]>;
+    onWorkspaceRestoreRecipientObserved(follower: Bus.TelegramBusFollowerView, isCurrent: () => boolean, ctx: TContext | undefined): Promise<void> | undefined;
+    waitForRestoreSettlement(): Promise<void>;
+};
 export interface TelegramAssistantOutputAuthority<TTransportStamp> {
     transportStamp: TTransportStamp;
     route: "direct" | "follower" | "none";