@jungjaehoon/mama-os 0.53.1 → 0.58.0

package/dist/gateways/telegram.js

@@ -1,1056 +1,543 @@
 "use strict";
-/**
- * Telegram Gateway for MAMA Standalone
- *
- * Production-hardened Telegram bot integration using grammY:
- * - Telegram message_id dedup without dropping repeated short replies
- * - Photo/document/caption ingestion through MAMA content blocks
- * - Group chat filtering (mention/command/reply-to-bot only)
- * - Sticker receive/send with emotion mapping
- * - Single-message streaming presenter (placeholder → final answer)
- * - Typing indicator, error handling
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TelegramGateway = void 0;
-const promises_1 = require("node:fs/promises");
+const node_async_hooks_1 = require("node:async_hooks");
 const node_crypto_1 = require("node:crypto");
-const node_os_1 = require("node:os");
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const node_async_hooks_1 = require("node:async_hooks");
 const grammy_1 = require("grammy");
 const base_gateway_js_1 = require("./base-gateway.js");
-const memory_logger_js_1 = require("../memory/memory-logger.js");
-const untrusted_content_js_1 = require("../utils/untrusted-content.js");
-const attachment_utils_js_1 = require("./attachment-utils.js");
 const telegram_text_entities_js_1 = require("./telegram-text-entities.js");
-const telegram_media_js_1 = require("./telegram-media.js");
-const telegram_response_presenter_js_1 = require("./telegram-response-presenter.js");
 const telegram_format_js_1 = require("./telegram-format.js");
 const telegram_message_ledger_js_1 = require("./telegram-message-ledger.js");
-const member_candidate_store_js_1 = require("./member-candidate-store.js");
-const principal_js_1 = require("./principal.js");
-const security_monitor_js_1 = require("../security/security-monitor.js");
-const debugLogger = __importStar(require("@jungjaehoon/mama-core/debug-logger"));
-const { DebugLogger } = debugLogger;
-const telegramLogger = new DebugLogger('telegram');
+const telegram_response_presenter_js_1 = require("./telegram-response-presenter.js");
+const file_delivery_js_1 = require("../api/file-delivery.js");
+const telegram_errors_js_1 = require("./telegram-errors.js");
+const telegram_attachments_js_1 = require("./telegram-attachments.js");
 const TELEGRAM_MAX_LENGTH = 4096;
 const MESSAGE_DEDUP_TTL_MS = 60_000;
-const REJECTED_CHAT_WARN_INTERVAL_MS = 60_000;
-const TYPING_INTERVAL_MS = 4_000;
-function parseOutboundChunkProgress(value) {
-    const parsed = JSON.parse(value);
-    if (!parsed || typeof parsed !== 'object')
-        throw new Error('Invalid Telegram outbound progress');
-    const record = parsed;
-    if (record.version !== 1 ||
-        !Number.isSafeInteger(record.nextIndex) ||
-        record.nextIndex < 0 ||
-        typeof record.uncertain !== 'boolean') {
-        throw new Error('Invalid Telegram outbound progress');
-    }
-    return { nextIndex: record.nextIndex, uncertain: record.uncertain };
-}
-function isDefiniteTelegramApiRejection(error) {
-    if (!error || typeof error !== 'object')
-        return false;
-    const record = error;
-    if (Number.isSafeInteger(record.error_code))
-        return true;
-    const response = record.response;
-    return (Boolean(response) &&
-        typeof response === 'object' &&
-        Number.isSafeInteger(response.error_code));
-}
-/**
- * Report-delivery terminal classifier (design Decision 3): ONLY a definite
- * Telegram non-acceptance may park a report as `prepared_definite_rejection`.
- * 429 and 5xx (and anything carrying `retry_after`) remain retryable - a
- * routine rate limit must never permanently silence owner reporting. This is
- * deliberately narrower than isDefiniteTelegramApiRejection, which answers a
- * different question (was the chunk send outcome unambiguous?).
- */
-function isTerminalTelegramRejection(error) {
-    if (!isDefiniteTelegramApiRejection(error))
-        return false;
-    const record = error;
-    const errorCode = Number.isSafeInteger(record.error_code)
-        ? record.error_code
-        : Number.isSafeInteger(record.response?.error_code)
-            ? record.response.error_code
-            : null;
-    if (errorCode === null)
-        return false;
-    const parameters = record.parameters;
-    if (parameters && Number.isSafeInteger(parameters.retry_after))
-        return false;
-    if (errorCode === 429 || errorCode >= 500)
-        return false;
-    return errorCode >= 400;
+const INTERRUPTED_RESPONSE = 'The previous processing attempt was interrupted. It was not rerun because its external ' +
+    'side effects could not be proven safe to repeat. Please send a new message if you want to ' +
+    'retry it.';
+function entityOptions(entities) {
+    return { entities };
 }
-function telegramRejectionReason(error) {
-    if (error && typeof error === 'object') {
-        const record = error;
-        if (typeof record.description === 'string' && record.description.length > 0) {
-            return record.description;
-        }
-        const response = record.response;
-        if (response && typeof response === 'object') {
-            const description = response.description;
-            if (typeof description === 'string' && description.length > 0)
-                return description;
-        }
-    }
+function telegramErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-/**
- * Telegram's own MessageEntity union is narrower than the structural entity the
- * formatter produces; the wire shape is identical.
- */
-function entityOptions(entities) {
-    return { entities };
+function sendErrorIsEntityOnly(error) {
+    return (0, telegram_format_js_1.isTelegramEntityRejection)(telegramErrorMessage(error));
 }
-/**
- * Send one formatted chunk. If Telegram rejects the entity list, resend the
- * same text unstyled: losing the styling is acceptable, losing the answer is
- * not. Any other failure stays a failure so the delivery ledger sees it.
- * Unstyled text is sent exactly as before, without an options argument.
- */
 async function sendFormattedMessage(api, chatId, message) {
-    if (!message.entities.length) {
-        return await api.sendMessage(chatId, message.text);
-    }
+    if (message.entities.length === 0)
+        return api.sendMessage(chatId, message.text);
     try {
         return await api.sendMessage(chatId, message.text, entityOptions(message.entities));
     }
     catch (error) {
-        if (!(0, telegram_format_js_1.isTelegramEntityRejection)(telegramRejectionReason(error)))
+        if (!sendErrorIsEntityOnly(error))
             throw error;
-        return await api.sendMessage(chatId, message.text);
+        return api.sendMessage(chatId, message.text);
     }
 }
-/** Edit one formatted chunk, with the same styling-only fallback. */
 async function editFormattedMessage(api, chatId, messageId, message) {
-    if (!message.entities.length) {
+    if (message.entities.length === 0) {
         await api.editMessageText(chatId, messageId, message.text);
         return;
     }
     try {
         await api.editMessageText(chatId, messageId, message.text, entityOptions(message.entities));
-        return;
     }
     catch (error) {
-        if (!(0, telegram_format_js_1.isTelegramEntityRejection)(telegramRejectionReason(error)))
+        if (!sendErrorIsEntityOnly(error))
             throw error;
+        await api.editMessageText(chatId, messageId, message.text);
     }
-    await api.editMessageText(chatId, messageId, message.text);
 }
-const EMOTION_EMOJI = {
-    happy: ['😊', '😀', '😄', '🙂'],
-    laugh: ['😂', '🤣', '😆'],
-    love: ['❤️', '😍', '🥰', '💕'],
-    sad: ['😢', '😞', '😔'],
-    cry: ['😭', '😿'],
-    angry: ['😠', '😡', '🤬'],
-    surprised: ['😮', '😲', '😯', '🤯'],
-    ok: ['👌', '👍', '✅'],
-    thanks: ['🙏', '🤗'],
-    sorry: ['🙇', '😓', '💦'],
-    hello: ['👋', '🙋', '✋'],
-    bye: ['👋', '🫡'],
-    thinking: ['🤔', '💭'],
-    excited: ['🎉', '🥳', '✨'],
-    tired: ['😫', '😩', '😴'],
-};
-const DEFAULT_STICKER_SET = 'HotCherry';
-/**
- * Telegram Gateway class
- */
+function sourceMessageRef(chatId, messageId) {
+    return `telegram:${chatId}:${messageId}`;
+}
+function chatIdFromSourceMessageRef(value) {
+    const prefix = 'telegram:';
+    if (!value.startsWith(prefix))
+        throw new Error('Telegram source message reference is invalid');
+    const rest = value.slice(prefix.length);
+    const separator = rest.lastIndexOf(':');
+    if (separator <= 0 || !/^\d+$/.test(rest.slice(separator + 1))) {
+        throw new Error('Telegram source message reference is invalid');
+    }
+    return rest.slice(0, separator);
+}
+function outboundLedgerKey(idempotencyKey) {
+    return `outbound:${(0, node_crypto_1.createHash)('sha256').update(`text\0${idempotencyKey}`).digest('hex')}`;
+}
+/** Telegram owner ingress and its durable response transport. */
 class TelegramGateway extends base_gateway_js_1.BaseGateway {
     source = 'telegram';
-    principalResolver;
     token;
     config;
-    bot = null;
-    botId = 0;
-    botUsername = '';
-    lastError = null;
-    lastMessageAt;
-    mediaRoot;
-    fetchImpl;
+    filesRoot;
+    downloadsDir;
+    log;
+    onFatalError;
     messageLedger;
     chatTails = new Map();
-    inboundTails = new Map();
-    activeInboundMessages = new Set();
-    activeChat = new node_async_hooks_1.AsyncLocalStorage();
-    // Telegram update dedup
+    activePresenters = new Map();
     recentMessageIds = new Map();
-    rejectedChatWarnAt = new Map();
-    // Dedup cleanup timer
-    dedupCleanupTimer = null;
-    // Sticker cache
-    stickerCache = new Map();
-    stickerSetLoaded = false;
+    activeChat = new node_async_hooks_1.AsyncLocalStorage();
+    bot = null;
+    lastError = null;
+    lastMessageAt;
     get mentionPattern() {
-        return null; // Group filtering handled explicitly in handleMessage
+        return null;
     }
     constructor(options) {
-        // The seam lives on the shared surface role, not on this gateway.
-        super({ turnProcessor: options.turnProcessor });
+        super({ intake: options.intake });
         this.token = options.token;
-        this.principalResolver = options.principalResolver;
         this.config = {
-            enabled: true,
-            token: options.token,
-            allowedChats: options.config?.allowedChats || [],
-            ownerUserIds: options.config?.ownerUserIds,
+            enabled: options.config?.enabled ?? true,
+            allowedChats: options.config?.allowedChats ?? [],
+            ...(options.config?.ownerUserIds === undefined
+                ? {}
+                : { ownerUserIds: options.config.ownerUserIds }),
+            ...(options.config?.ownerChatId === undefined
+                ? {}
+                : { ownerChatId: options.config.ownerChatId }),
+            ...(options.config?.polling === undefined ? {} : { polling: options.config.polling }),
         };
-        this.mediaRoot =
-            options.mediaRoot ??
-                (0, node_path_1.join)(process.env.MAMA_WORKSPACE || (0, node_path_1.join)((0, node_os_1.homedir)(), '.mama', 'workspace'), 'media', 'inbound', 'telegram');
-        this.fetchImpl = options.fetchImpl;
-        this.messageLedger = new telegram_message_ledger_js_1.TelegramMessageLedger(options.messageLedgerPath ??
-            process.env.MAMA_TELEGRAM_MESSAGE_LEDGER_PATH ??
-            `${this.mediaRoot}.processed-message-ids.json`, { log: (line) => console.error(line) });
+        this.filesRoot = options.filesRoot;
+        this.downloadsDir = options.downloadsDir;
+        this.onFatalError =
+            options.onFatalError ??
+                ((error) => {
+                    queueMicrotask(() => {
+                        throw error;
+                    });
+                });
+        this.log = options.log ?? ((line) => console.log(line));
+        const ledgerPath = options.messageLedgerPath ?? process.env.MAMA_TELEGRAM_MESSAGE_LEDGER_PATH;
+        if (!options.messageLedger && !ledgerPath?.trim()) {
+            throw new Error('Telegram message ledger path is required');
+        }
+        this.messageLedger =
+            options.messageLedger ?? new telegram_message_ledger_js_1.TelegramMessageLedger(ledgerPath, { log: this.log });
     }
     async start() {
-        if (this.connected) {
-            console.log('Telegram gateway already connected');
+        if (this.connected)
             return;
-        }
         if (!this.config.allowedChats?.some((chatId) => chatId.trim().length > 0)) {
             throw new Error('telegram gateway disabled: allowed_chats is not set. Run: mama status');
         }
+        if (!this.token.trim())
+            throw new Error('telegram gateway requires a token');
         try {
             this.bot = new grammy_1.Bot(this.token);
             this.bot.on('message', async (ctx) => {
-                try {
-                    if (ctx.message) {
-                        await this.handleMessage(ctx.message);
-                    }
-                }
-                catch (error) {
-                    console.error('[Telegram] Error handling message:', error);
-                    this.emitEvent({
-                        type: 'error',
-                        source: 'telegram',
-                        timestamp: new Date(),
-                        data: { error: error instanceof Error ? error.message : String(error) },
-                    });
-                    // Let grammY treat the update as failed. The durable message ledger
-                    // prevents unsafe turn re-execution and replays a ready outbox response.
-                    throw error;
-                }
+                if (ctx.message)
+                    await this.handleMessage(ctx.message);
             });
-            this.bot.catch((err) => {
-                this.lastError = err.message ?? String(err);
-                console.error(`[Telegram] error: ${this.lastError}`);
+            this.bot.catch((error) => {
+                this.lastError = telegramErrorMessage(error);
+                console.error(`telegram handler failed error=${this.lastError}`);
             });
             await this.bot.init();
-            this.botId = this.bot.botInfo.id;
-            this.botUsername = this.bot.botInfo.username || '';
-            console.log(`Telegram bot logged in as @${this.botUsername}`);
-            await this.recoverPendingInboundDeliveries();
-            console.log(`[Telegram] Inbound allowlist active: ${this.config.allowedChats.length} chat(s)`);
             this.connected = true;
             this.lastError = null;
-            await (0, telegram_media_js_1.pruneTelegramMediaRoot)(this.mediaRoot);
-            // Periodic dedup cleanup
-            this.dedupCleanupTimer = setInterval(() => {
-                const now = Date.now();
-                for (const [key, ts] of this.recentMessageIds) {
-                    if (now - ts > MESSAGE_DEDUP_TTL_MS)
-                        this.recentMessageIds.delete(key);
-                }
-                for (const [key, ts] of this.rejectedChatWarnAt) {
-                    if (now - ts > REJECTED_CHAT_WARN_INTERVAL_MS) {
-                        this.rejectedChatWarnAt.delete(key);
-                    }
-                }
-                void (0, telegram_media_js_1.pruneTelegramMediaRoot)(this.mediaRoot).catch((error) => {
-                    console.error(`[Telegram] media retention cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+            this.emitEvent({ type: 'connected', source: 'telegram', timestamp: new Date() });
+            await this.recoverPendingResponses();
+            if (this.config.polling !== false) {
+                // Polling runs for the life of the process; a failure here means no owner message
+                // is ever received, so it is logged, not swallowed.
+                this.bot.start().catch((error) => {
+                    this.lastError = telegramErrorMessage(error);
+                    this.connected = false;
+                    console.error(`telegram polling stopped error=${this.lastError}`);
+                    this.onFatalError(error);
                 });
-                void this.recoverPendingInboundDeliveries().catch((error) => {
-                    console.error(`[Telegram] pending response recovery failed: ${error instanceof Error ? error.message : String(error)}`);
-                });
-            }, 60_000);
-            this.emitEvent({
-                type: 'connected',
-                source: 'telegram',
-                timestamp: new Date(),
-                data: { username: this.botUsername },
-            });
-            // Start long polling (non-blocking)
-            this.bot.start();
+                console.log(`telegram polling started polling=${this.config.polling ?? 'default'}`);
+            }
+            else {
+                console.log('telegram polling disabled by config');
+            }
         }
         catch (error) {
-            if (this.bot) {
-                try {
-                    await this.bot.stop();
-                }
-                catch {
-                    /* ignore */
-                }
-                this.bot = null;
-            }
-            this.lastError = error instanceof Error ? error.message : String(error);
-            console.error('Telegram connection failed:', error);
+            this.lastError = telegramErrorMessage(error);
+            if (this.bot)
+                await this.bot.stop().catch(() => { });
+            this.bot = null;
+            this.connected = false;
             throw error;
         }
     }
     async stop() {
-        if (this.dedupCleanupTimer) {
-            clearInterval(this.dedupCleanupTimer);
-            this.dedupCleanupTimer = null;
-        }
-        if (this.bot) {
-            try {
-                await this.bot.stop();
-            }
-            catch {
-                /* ignore */
-            }
-            this.bot = null;
-            this.stickerCache.clear();
-            this.stickerSetLoaded = false;
-        }
-        this.rejectedChatWarnAt.clear();
+        if (this.bot)
+            await this.bot.stop().catch(() => { });
+        this.bot = null;
         this.connected = false;
-        this.emitEvent({
-            type: 'disconnected',
-            source: 'telegram',
-            timestamp: new Date(),
-        });
-    }
-    async handleMessage(msg) {
-        if (!msg.from || !msg.chat)
+        this.recentMessageIds.clear();
+        this.emitEvent({ type: 'disconnected', source: 'telegram', timestamp: new Date() });
+    }
+    /** Delivered inbound identities; message and answer text stay in the durable runtime journal. */
+    recentDeliveredMessageRefs() {
+        return this.messageLedger.recentDeliveredMessageRefs();
+    }
+    /** Final response callback used by the owner runtime after a native turn settles. */
+    async deliverResponse(sourceRef, response) {
+        const chatId = chatIdFromSourceMessageRef(sourceRef);
+        this.requireAllowedChat(chatId);
+        const existing = this.messageLedger.get(sourceRef);
+        if (!existing)
+            throw new Error(`Telegram response has no accepted message ${sourceRef}`);
+        if (existing.deliveryTarget && existing.deliveryTarget !== `telegram:${chatId}`) {
+            throw new Error('Telegram response destination conflicts with its accepted message');
+        }
+        if (existing.state === 'delivered')
             return;
-        const now = Date.now();
-        const messageKey = `${msg.chat.id}:${msg.message_id}`;
-        if (this.messageLedger.get(messageKey)?.state === 'delivered')
+        if (existing.state === 'ready' && existing.response !== response) {
+            throw new Error('Telegram response conflicts with its durable ledger entry');
+        }
+        if (existing.state === 'processing')
+            this.messageLedger.markReady(sourceRef, response, 'html-v1');
+        if (!this.bot || !this.connected)
             return;
-        if (this.recentMessageIds.has(messageKey))
+        await this.deliverReadyEntry(sourceRef);
+    }
+    async sendMessage(chatId, text, idempotencyKey) {
+        if (!this.bot || !this.connected)
+            throw new Error('Telegram gateway not connected');
+        this.requireAllowedChat(chatId);
+        const trimmed = text.trim();
+        if (!trimmed)
             return;
-        this.recentMessageIds.set(messageKey, now);
-        for (const [key, ts] of this.recentMessageIds) {
-            if (now - ts > MESSAGE_DEDUP_TTL_MS)
-                this.recentMessageIds.delete(key);
-        }
-        const chatId = String(msg.chat.id);
-        if (this.config.allowedChats && this.config.allowedChats.length > 0) {
-            if (!this.config.allowedChats.includes(chatId)) {
-                const lastWarn = this.rejectedChatWarnAt.get(chatId) ?? 0;
-                if (now - lastWarn > REJECTED_CHAT_WARN_INTERVAL_MS) {
-                    this.rejectedChatWarnAt.set(chatId, now);
-                    console.warn(`[Telegram] Dropped message from non-allowlisted chat ${msg.chat.id} (user ${msg.from.id})`);
-                }
-                return;
-            }
-        }
-        let principal = (0, principal_js_1.resolveTelegramPrincipal)({
-            userId: String(msg.from.id),
-            chatId,
-            chatType: msg.chat.type,
-            allowedChats: new Set(this.config.allowedChats ?? []),
-            ownerUserIds: this.config.ownerUserIds === undefined ? undefined : new Set(this.config.ownerUserIds),
-        });
-        if (this.principalResolver) {
-            principal = (0, principal_js_1.overlayMemberPrincipal)(principal, this.principalResolver('telegram', 'global', String(msg.from.id)));
-        }
-        if (principal.class === 'owner' &&
-            principal.consoleEligible &&
-            msg.forward_origin?.type === 'user' &&
-            Boolean(msg.forward_origin.sender_user)) {
-            (0, member_candidate_store_js_1.getMemberCandidateStore)().upsert({
-                connector: 'telegram',
-                namespace: 'global',
-                externalId: String(msg.forward_origin.sender_user.id),
-                displayName: msg.forward_origin.sender_user.first_name,
-                firstSeen: now,
-                expiresAt: now + member_candidate_store_js_1.MEMBER_CANDIDATE_TTL_MS,
-            });
-        }
-        if (principal.lane === 'divert') {
-            (0, security_monitor_js_1.logSecurityEventOnly)({
-                type: 'telegram_principal_diverted',
-                severity: 'warn',
-                message: 'Telegram ingress diverted before processing',
-                details: { source: 'telegram', chatType: msg.chat.type },
+        await this.runInChatQueue(chatId, () => this.sendMessageNow(chatId, trimmed, idempotencyKey));
+    }
+    async sendToOwner(text, idempotencyKey) {
+        const ownerChatId = this.config.ownerChatId?.trim();
+        if (!ownerChatId)
+            throw new Error('telegram.owner_chat_id is required for delta delivery');
+        await this.sendMessage(ownerChatId, text, idempotencyKey);
+    }
+    async sendFile(path, caption, operationId) {
+        if (!this.bot || !this.connected)
+            throw new Error('Telegram gateway not connected');
+        if (operationId.trim() === '')
+            throw new Error('Telegram file operation id is required');
+        const ownerChatId = this.config.ownerChatId?.trim();
+        if (!ownerChatId)
+            throw new Error('telegram.owner_chat_id is required for file delivery');
+        this.requireAllowedChat(ownerChatId);
+        if (!this.filesRoot)
+            throw new Error('Telegram workspace files root is not configured');
+        const validated = (0, file_delivery_js_1.openWorkspaceFile)(this.filesRoot, path);
+        try {
+            const payloadIdentity = (0, file_delivery_js_1.workspaceFileIdentity)(validated.fd, caption);
+            const claim = this.messageLedger.claim(`file:${operationId}`, {
+                deliveryTarget: `telegram:${ownerChatId}`,
+                payloadIdentity,
             });
-            return;
-        }
-        const laneKey = (0, principal_js_1.laneChannelId)(chatId, principal.lane);
-        await this.runInQueue(this.inboundTails, laneKey, async () => {
-            this.activeInboundMessages.add(messageKey);
-            try {
-                await this.processMessage(msg, messageKey, principal);
-            }
-            finally {
-                this.activeInboundMessages.delete(messageKey);
+            if (!claim.claimed) {
+                if (claim.entry.state === 'delivered') {
+                    return {
+                        sentAs: validated.sentAs,
+                        size: validated.size,
+                        idempotent: true,
+                    };
+                }
+                throw new Error('Telegram file delivery operation is already in progress or uncertain');
             }
-        });
-    }
-    async runInChatQueue(chatKey, work, allowReentrant = false) {
-        const active = this.activeChat.getStore();
-        if (allowReentrant && active?.active && active.key === chatKey)
-            return work();
-        return this.runInQueue(this.chatTails, chatKey, async () => {
-            const lease = { key: chatKey, active: true };
+            const upload = new grammy_1.InputFile((0, file_delivery_js_1.readWorkspaceFile)(validated.fd), (0, node_path_1.basename)(validated.path));
             try {
-                return await this.activeChat.run(lease, work);
+                const sent = validated.sentAs === 'photo'
+                    ? await this.bot.api.sendPhoto(ownerChatId, upload, caption === undefined ? undefined : { caption })
+                    : await this.bot.api.sendDocument(ownerChatId, upload, caption === undefined ? undefined : { caption });
+                this.messageLedger.markDelivered(`file:${operationId}`);
+                return {
+                    messageId: sent.message_id,
+                    sentAs: validated.sentAs,
+                    size: validated.size,
+                };
             }
-            finally {
-                // Async work inherited from a completed send cannot bypass a later batch.
-                lease.active = false;
+            catch (error) {
+                this.messageLedger.markFailed(`file:${operationId}`);
+                throw error;
             }
-        });
-    }
-    /** Inbound ordering and outbound atomic batches have separate lifetimes. */
-    async runInQueue(tails, key, work) {
-        const previous = tails.get(key);
-        let release;
-        const gate = new Promise((resolve) => {
-            release = resolve;
-        });
-        const currentTail = (previous ?? Promise.resolve()).catch(() => { }).then(() => gate);
-        tails.set(key, currentTail);
-        try {
-            if (previous)
-                await previous.catch(() => { });
-            return await work();
         }
         finally {
-            release();
-            if (tails.get(key) === currentTail)
-                tails.delete(key);
+            (0, node_fs_1.closeSync)(validated.fd);
+        }
+    }
+    getLastError() {
+        return this.lastError;
+    }
+    getLastMessageAt() {
+        return this.lastMessageAt;
+    }
+    ownerAllowed(chatId, userId) {
+        if (!this.config.allowedChats?.includes(chatId))
+            return false;
+        if (this.config.ownerUserIds !== undefined)
+            return this.config.ownerUserIds.includes(userId);
+        return this.config.allowedChats.length === 1 && this.config.allowedChats[0] === userId;
+    }
+    requireAllowedChat(chatId) {
+        if (!this.config.allowedChats?.includes(chatId)) {
+            throw new Error('Telegram destination is not allowlisted');
         }
     }
-    async processMessage(msg, messageKey, principal) {
-        if (!msg.from || !msg.chat)
+    async handleMessage(message) {
+        if (!message.chat || !message.from)
             return;
-        const now = Date.now();
-        const hasMedia = Boolean((msg.photo && msg.photo.length > 0) || msg.document);
-        if (hasMedia && (!this.config.allowedChats || this.config.allowedChats.length === 0)) {
-            const lastWarn = this.rejectedChatWarnAt.get(String(msg.chat.id)) ?? 0;
-            if (now - lastWarn > REJECTED_CHAT_WARN_INTERVAL_MS) {
-                this.rejectedChatWarnAt.set(String(msg.chat.id), now);
-                console.warn('[Telegram] Dropped media because telegram.allowed_chats is not configured');
-            }
+        const chatId = String(message.chat.id);
+        const userId = String(message.from.id);
+        if (message.from.is_bot || !this.ownerAllowed(chatId, userId)) {
+            const chatHash = (0, node_crypto_1.createHash)('sha256').update(`chat\0${chatId}`).digest('hex');
+            const senderHash = (0, node_crypto_1.createHash)('sha256').update(`sender\0${userId}`).digest('hex');
+            console.warn(`telegram message dropped reason=non_owner chat_hash=${chatHash} sender_hash=${senderHash}`);
             return;
         }
-        // Task G: text pairs with `entities`, caption with `caption_entities`. The
-        // selected field is the ORIGINAL reference frame for every entity offset
-        // (UTF-16 code units); later host adjustments never rewrite it.
-        const { field: selectedField, text: selectedText, entities: selectedEntities, } = (0, telegram_text_entities_js_1.selectTelegramTextEntities)(msg);
-        const telegramFormatting = msg.sticker
-            ? undefined
-            : (0, telegram_text_entities_js_1.captureTelegramTextFormatting)(selectedField, selectedText, selectedEntities);
-        // Group chat filtering
-        const isGroup = msg.chat.type === 'group' || msg.chat.type === 'supergroup';
-        if (isGroup) {
-            const isMention = this.botUsername &&
-                selectedEntities?.some((e) => e.type === 'mention' &&
-                    selectedText.slice(e.offset, e.offset + e.length).toLowerCase() ===
-                        `@${this.botUsername.toLowerCase()}`);
-            const isBotCommand = selectedEntities?.some((e) => e.type === 'bot_command');
-            const isReplyToBot = msg.reply_to_message?.from?.id === this.botId;
-            if (!isMention && !isBotCommand && !isReplyToBot)
-                return;
-        }
-        let text = selectedText;
-        if (msg.sticker) {
-            text = `[sticker: ${msg.sticker.emoji || '😊'}]`;
-        }
-        if (isGroup && this.botUsername) {
-            const escaped = this.botUsername.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-            text = text.replace(new RegExp(`@${escaped}\\b`, 'gi'), '').trim();
-        }
-        // Provenance labeling: a FORWARDED message is third-party content the
-        // owner relayed, not the owner speaking. Selection and mention removal
-        // happen first so caption provenance follows the same trust boundary.
-        const isForwarded = Boolean(msg.forward_origin);
-        const durableEntry = this.messageLedger.get(messageKey);
-        const numChatId = msg.chat.id;
-        const api = this.bot.api;
-        let initialResponseMessageId = null;
-        const presenter = this.createResponsePresenter(numChatId, messageKey, durableEntry?.nextChunkIndex ?? 0, (messageId) => {
-            initialResponseMessageId = messageId;
-        });
-        if (durableEntry?.state !== 'ready')
-            await presenter.start();
-        if (durableEntry?.state === 'ready' && durableEntry.response !== undefined) {
-            try {
-                await presenter.finalize(durableEntry.response);
-                this.messageLedger.markDelivered(messageKey);
-            }
-            catch (error) {
-                this.recentMessageIds.delete(messageKey);
-                throw error;
-            }
+        const ref = sourceMessageRef(chatId, message.message_id);
+        const now = Date.now();
+        const previous = this.recentMessageIds.get(ref);
+        if (previous !== undefined && now - previous <= MESSAGE_DEDUP_TTL_MS)
             return;
+        this.recentMessageIds.set(ref, now);
+        for (const [key, timestamp] of this.recentMessageIds) {
+            if (now - timestamp > MESSAGE_DEDUP_TTL_MS)
+                this.recentMessageIds.delete(key);
         }
-        if (durableEntry?.state === 'processing') {
-            const interruptedNotice = 'The previous processing attempt was interrupted. It was not rerun because its external ' +
-                'side effects could not be proven safe to repeat. Please send a new message if you want ' +
-                'to retry it.';
-            this.messageLedger.markReady(messageKey, interruptedNotice, 'html-v1');
-            try {
-                await presenter.finalize(interruptedNotice);
-                this.messageLedger.markDelivered(messageKey);
-            }
-            catch (error) {
-                this.recentMessageIds.delete(messageKey);
-                throw error;
-            }
+        const durable = this.messageLedger.get(ref);
+        if (durable?.state === 'delivered')
             return;
-        }
-        const attachments = [];
-        const contentBlocks = [];
-        let transientMediaPath;
-        // The public lane is conversation-only: a non-owner's attachment is never
-        // downloaded with the bot's credentials and never becomes a model-visible
-        // content block. Text/caption still flows.
-        const mediaAllowed = principal.lane === 'owner';
-        try {
-            if (mediaAllowed && msg.photo && msg.photo.length > 0) {
-                const photo = msg.photo[msg.photo.length - 1];
-                const downloaded = await (0, telegram_media_js_1.downloadTelegramMedia)({
-                    botToken: this.token,
-                    fileId: photo.file_id,
-                    fileUniqueId: photo.file_unique_id,
-                    declaredSize: photo.file_size,
-                    kind: 'photo',
-                    mediaRoot: this.mediaRoot,
-                    getFile: (fileId) => api.getFile(fileId),
-                    fetchImpl: this.fetchImpl,
-                });
-                transientMediaPath = downloaded.localPath;
-                const detectedType = (0, attachment_utils_js_1.detectImageType)(await (0, promises_1.readFile)(downloaded.localPath));
-                if (!detectedType) {
-                    await presenter.fail('This image format is not supported.');
-                    return;
-                }
-                const attachment = {
-                    type: 'image',
-                    sourceRef: downloaded.sourceRef,
-                    localPath: downloaded.localPath,
-                    filename: downloaded.filename,
-                    contentType: detectedType,
-                    size: downloaded.size,
-                };
-                attachments.push(attachment);
-                const builtBlocks = await (0, attachment_utils_js_1.buildContentBlocks)([attachment]);
-                const imageBlocks = builtBlocks.filter((block) => block.type === 'image');
-                if (imageBlocks.length === 0) {
-                    await presenter.fail('This image format is not supported.');
-                    return;
-                }
-                for (const block of imageBlocks) {
-                    contentBlocks.push({ type: 'image', source: block.source });
-                }
-                // Keep the private local path for bounded OCR/overlay follow-ups. The
-                // media retention sweeper removes it after the configured TTL/quota.
-                transientMediaPath = undefined;
-                if (!text.trim()) {
-                    text = '[Image]';
-                }
-            }
-            else if (mediaAllowed && msg.document) {
-                const downloaded = await (0, telegram_media_js_1.downloadTelegramMedia)({
-                    botToken: this.token,
-                    fileId: msg.document.file_id,
-                    fileUniqueId: msg.document.file_unique_id,
-                    filename: msg.document.file_name,
-                    mimeType: msg.document.mime_type,
-                    declaredSize: msg.document.file_size,
-                    kind: 'document',
-                    mediaRoot: this.mediaRoot,
-                    getFile: (fileId) => api.getFile(fileId),
-                    fetchImpl: this.fetchImpl,
-                });
-                transientMediaPath = downloaded.localPath;
-                const detectedType = (0, attachment_utils_js_1.detectImageType)(await (0, promises_1.readFile)(downloaded.localPath));
-                if (downloaded.mimeType.startsWith('image/') && !detectedType) {
-                    await presenter.fail('This image format is not supported.');
-                    return;
-                }
-                const attachment = {
-                    type: detectedType ? 'image' : 'file',
-                    sourceRef: downloaded.sourceRef,
-                    localPath: downloaded.localPath,
-                    filename: downloaded.filename,
-                    contentType: detectedType ?? downloaded.mimeType,
-                    size: downloaded.size,
-                };
-                attachments.push(attachment);
-                if (detectedType) {
-                    const builtBlocks = await (0, attachment_utils_js_1.buildContentBlocks)([attachment]);
-                    const imageBlocks = builtBlocks.filter((block) => block.type === 'image');
-                    if (imageBlocks.length === 0) {
-                        await presenter.fail('This image format is not supported.');
-                        return;
-                    }
-                    for (const block of imageBlocks) {
-                        contentBlocks.push({ type: 'image', source: block.source });
-                    }
-                    if (!text.trim()) {
-                        text = `[Image: ${downloaded.filename}]`;
-                    }
-                    transientMediaPath = undefined;
-                }
-                else {
-                    contentBlocks.push({
-                        type: 'text',
-                        text: `[File: ${downloaded.filename}, type: ${downloaded.mimeType}]`,
-                    });
-                    if (!text.trim()) {
-                        text = `[File: ${downloaded.filename}]`;
-                    }
-                    // Documents remain in the private inbound workspace so the routed
-                    // turn and a bounded follow-up can read the actual attachment.
-                    transientMediaPath = undefined;
-                }
-            }
-        }
-        catch {
-            await presenter.fail(msg.document ? 'The file could not be downloaded.' : 'The image could not be downloaded.');
+        if (durable?.state === 'ready') {
+            await this.deliverReadyEntry(ref);
             return;
         }
-        finally {
-            if (transientMediaPath) {
-                await (0, promises_1.unlink)(transientMediaPath).catch(() => { });
-            }
+        if (durable?.state === 'processing' && this.activePresenters.has(ref))
+            return;
+        if (durable?.state === 'processing' && this.intake.isPending?.(ref))
+            return;
+        if (durable?.state === 'processing') {
+            this.messageLedger.markReady(ref, INTERRUPTED_RESPONSE, 'html-v1');
+            await this.deliverReadyEntry(ref);
+            return;
         }
-        if (!text.trim()) {
-            await presenter.fail('This Telegram message type is not supported.');
+        const selected = (0, telegram_text_entities_js_1.selectTelegramTextEntities)(message);
+        const files = (0, telegram_attachments_js_1.telegramFiles)(message);
+        if (!selected.text.trim() && files.length === 0)
             return;
+        const formatting = (0, telegram_text_entities_js_1.captureTelegramTextFormatting)(selected.field, selected.text, selected.entities);
+        const inputIdentity = (0, node_crypto_1.createHash)('sha256')
+            .update(`${selected.text}\0${files.map(({ file }) => file.file_unique_id).join(',')}`)
+            .digest('hex');
+        const ledgerEntry = this.messageLedger.claim(ref, {
+            deliveryTarget: `telegram:${chatId}`,
+            payloadIdentity: inputIdentity,
+        }).entry;
+        const presenter = this.createResponsePresenter(ref, Number(message.chat.id));
+        this.activePresenters.set(ref, presenter);
+        try {
+            if (ledgerEntry.state !== 'ready')
+                await presenter.start();
+            const attachments = await (0, telegram_attachments_js_1.downloadTelegramFiles)(files, {
+                api: this.bot.api,
+                token: this.token,
+                downloadsDir: this.downloadsDir,
+                messageId: message.message_id,
+            });
+            const input = {
+                id: ref,
+                channelKey: chatId,
+                occurredAt: message.date * 1000,
+                text: selected.text.trim()
+                    ? selected.text
+                    : attachments.map(({ name }) => `[file: ${name}]`).join('\n'),
+                ...(formatting === undefined && attachments.length === 0
+                    ? {}
+                    : {
+                        payload: {
+                            ...(formatting === undefined ? {} : { telegramFormatting: formatting }),
+                            ...(attachments.length === 0 ? {} : { attachments }),
+                        },
+                    }),
+            };
+            this.intake.acceptOwnerMessage(input);
+            this.emitEvent({
+                type: 'message_received',
+                source: 'telegram',
+                timestamp: new Date(),
+                data: { sourceMessageRef: ref },
+            });
         }
-        if (isForwarded) {
-            text = (0, untrusted_content_js_1.wrapUntrustedContent)('telegram-forward', text);
+        catch (error) {
+            this.activePresenters.delete(ref);
+            throw error;
         }
-        const sender = msg.from.username || String(msg.from.id);
-        console.log(`[Telegram] Message from ${sender} (${text.length} chars)`);
-        const memoryLogger = (0, memory_logger_js_1.getMemoryLogger)();
-        memoryLogger.logMessage('Telegram', sender, text, false);
-        this.emitEvent({
-            type: 'message_received',
-            source: 'telegram',
-            timestamp: new Date(),
-            data: { chatId: String(msg.chat.id), userId: String(msg.from.id) },
-        });
-        const normalizedMessage = {
-            source: 'telegram',
-            channelId: String(msg.chat.id),
-            userId: String(msg.from.id),
-            text,
-            principal,
-            contentBlocks: contentBlocks.length > 0 ? contentBlocks : undefined,
-            metadata: {
-                username: msg.from.username,
-                messageId: String(msg.message_id),
-                chatType: msg.chat.type,
-                attachments: attachments.length > 0 ? attachments : undefined,
-                // Trusted provenance flag: downstream strips untrusted blocks ONLY
-                // when the GATEWAY wrapped them - sender-typed markers are not a
-                // security boundary (forgeable in-band data).
-                untrustedWrapped: isForwarded,
-                // Sender styling as data. Offsets stay bound to originalText, so the
-                // mention removal / placeholder / wrapper applied to `text` above
-                // cannot shift them. A forwarded body's formatting is fenced by the
-                // router under the same untrustedWrapped flag.
-                ...(telegramFormatting ? { telegramFormatting } : {}),
+    }
+    createResponsePresenter(sourceRef, chatId) {
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        return new telegram_response_presenter_js_1.TelegramResponsePresenter({
+            send: (content) => sendFormattedMessage(this.bot.api, chatId, content).then((sent) => String(sent.message_id)),
+            edit: (handle, content) => editFormattedMessage(this.bot.api, chatId, Number(handle), content),
+            delete: async (handle) => {
+                await this.bot.api.deleteMessage(chatId, Number(handle));
             },
-        };
-        // Typing indicator
-        const chatId = String(msg.chat.id);
-        const sendTyping = () => this.bot?.api.sendChatAction(numChatId, 'typing').catch(() => { });
-        sendTyping();
-        const typingInterval = setInterval(sendTyping, TYPING_INTERVAL_MS);
-        try {
-            // Process through message router
-            let result;
-            this.messageLedger.claim(messageKey);
-            try {
-                result = await this.turnProcessor.processTurn(normalizedMessage, {
-                    onStream: presenter.callbacks(),
-                    onQueued: () => presenter.markQueued(),
-                });
-            }
-            catch (error) {
-                const failureNotice = 'An error occurred while processing the message.';
-                this.messageLedger.markReady(messageKey, failureNotice, 'html-v1');
-                try {
-                    await presenter.fail(failureNotice);
-                    this.messageLedger.markDelivered(messageKey);
-                }
-                catch {
-                    this.recentMessageIds.delete(messageKey);
-                }
-                throw error;
-            }
-            if (result.outcome === 'external_divert') {
-                if (initialResponseMessageId !== null) {
-                    await api.deleteMessage(numChatId, initialResponseMessageId).catch(() => { });
+        }, {
+            resumeFromChunk: this.messageLedger.get(sourceRef)?.nextChunkIndex ?? 0,
+            chunkFormat: this.messageLedger.get(sourceRef)?.chunkFormat ?? 'html-v1',
+            withDelivery: (send) => this.runInChatQueue(String(chatId), send, true),
+            onChunkProgress: (nextIndex, uncertain) => {
+                const entry = this.messageLedger.get(sourceRef);
+                if (entry?.state === 'ready') {
+                    this.messageLedger.markDeliveryProgress(sourceRef, nextIndex, uncertain);
                 }
-                this.messageLedger.markReady(messageKey, '', 'html-v1');
-                this.messageLedger.markDelivered(messageKey);
-                telegramLogger.info('[Telegram] Turn externally diverted; no response sent');
+            },
+        });
+    }
+    async deliverReadyEntry(sourceRef) {
+        const entry = this.messageLedger.get(sourceRef);
+        if (!entry || entry.state === 'delivered')
+            return;
+        if (entry.response === undefined)
+            throw new Error('Telegram ready entry has no response');
+        const chatId = Number(chatIdFromSourceMessageRef(sourceRef));
+        await this.runInChatQueue(String(chatId), async () => {
+            const current = this.messageLedger.get(sourceRef);
+            if (!current || current.state === 'delivered')
                 return;
-            }
-            this.messageLedger.markReady(messageKey, result.response, 'html-v1');
+            if (current.deliveryUncertain)
+                throw new Error('Telegram response delivery is uncertain');
+            const presenter = this.activePresenters.get(sourceRef) ?? this.createResponsePresenter(sourceRef, chatId);
             try {
-                await presenter.finalize(result.response);
-                this.messageLedger.markDelivered(messageKey);
+                await presenter.finalize(current.response);
             }
-            catch (error) {
-                this.recentMessageIds.delete(messageKey);
-                throw error;
+            finally {
+                this.activePresenters.delete(sourceRef);
             }
+            this.messageLedger.markDelivered(sourceRef);
             this.lastMessageAt = Date.now();
-            memoryLogger.logMessage('Telegram', 'MAMA', result.response, true);
             this.emitEvent({
                 type: 'message_sent',
                 source: 'telegram',
                 timestamp: new Date(),
-                data: {
-                    chatId,
-                    responseLength: result.response.length,
-                    duration: result.duration,
-                },
+                data: { sourceMessageRef: sourceRef },
             });
-        }
-        finally {
-            clearInterval(typingInterval);
-        }
-    }
-    async sendMessage(chatId, text, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        if (!text.trim())
-            return;
-        await this.runInChatQueue(chatId, () => this.sendMessageNow(chatId, text, idempotencyKey));
-    }
-    /** Detached system work must wait behind the normal per-chat delivery queue. */
-    async sendSystemMessage(chatId, text, deliveryId) {
-        await this.sendMessage(chatId, text, deliveryId);
+        });
     }
-    /**
-     * TG-05/TG-06: narrow owner-report delivery surface for the report
-     * coordinator. Pins the delivery-ID-bound ledger entry before the first
-     * send so a confirmed-send proof cannot be pruned while the report-context
-     * SQLite row remains nonterminal, and classifies send failures with the
-     * gateway's own definite-rejection test.
-     */
-    createReportDeliveryControl() {
-        const pinnedTargets = new Map();
-        const ledgerKey = (deliveryId) => this.outboundLedgerKey(deliveryId, 'text');
-        return {
-            claimAndPin: async (binding) => {
-                const key = ledgerKey(binding.deliveryId);
-                this.messageLedger.claim(key, {
-                    deliveryTarget: `telegram:${binding.target.channelId}`,
-                    payloadIdentity: (0, node_crypto_1.createHash)('sha256').update(binding.text).digest('hex'),
-                });
-                this.messageLedger.pin(key);
-                pinnedTargets.set(binding.deliveryId, {
-                    chatId: binding.target.channelId,
-                    text: binding.text,
-                });
-                return { deliveryId: binding.deliveryId };
-            },
-            sendPinned: async (lease) => {
-                const pinned = pinnedTargets.get(lease.deliveryId);
-                if (!pinned) {
-                    throw new Error(`Owner report delivery ${lease.deliveryId} was not pinned by this control`);
-                }
-                try {
-                    await this.sendMessage(pinned.chatId, pinned.text, lease.deliveryId);
-                    return { kind: 'confirmed' };
+    async recoverPendingResponses() {
+        for (const entry of this.messageLedger.listUndelivered()) {
+            try {
+                if (entry.deliveryUncertain) {
+                    this.log(`telegram delivery requires reconciliation key=${entry.key} state=${entry.state} next_chunk_index=${entry.nextChunkIndex ?? 0}`);
+                    continue;
                 }
-                catch (error) {
-                    if (isTerminalTelegramRejection(error)) {
-                        return { kind: 'definite_rejection', reason: telegramRejectionReason(error) };
+                if (entry.key.startsWith('outbound:') && entry.state === 'ready') {
+                    const chatId = entry.deliveryTarget?.slice('telegram:'.length);
+                    if (!entry.deliveryTarget?.startsWith('telegram:') || !chatId) {
+                        throw new Error('Telegram outbound entry has no valid destination');
                     }
-                    return {
-                        kind: 'retryable',
-                        detail: error instanceof Error ? error.message : String(error),
-                    };
+                    if (!this.config.allowedChats?.includes(chatId))
+                        continue;
+                    await this.runInChatQueue(chatId, () => this.deliverOutboundEntry(entry.key, chatId));
+                    continue;
                 }
-            },
-            releasePin: async (deliveryId) => {
-                this.messageLedger.unpin(ledgerKey(deliveryId));
-                pinnedTargets.delete(deliveryId);
-            },
-            reconcilePins: async (nonterminalIds, terminalIds) => {
-                for (const deliveryId of nonterminalIds) {
-                    const key = ledgerKey(deliveryId);
-                    if (this.messageLedger.get(key))
-                        this.messageLedger.pin(key);
+                if (!entry.key.startsWith('telegram:'))
+                    continue;
+                const chatId = chatIdFromSourceMessageRef(entry.key);
+                if (!this.config.allowedChats?.includes(chatId))
+                    continue;
+                if (entry.state === 'ready' && entry.response !== undefined) {
+                    await this.deliverReadyEntry(entry.key);
+                    continue;
                 }
-                for (const deliveryId of terminalIds) {
-                    this.messageLedger.unpin(ledgerKey(deliveryId));
+                if (entry.state === 'processing' && !this.intake.isPending?.(entry.key)) {
+                    this.messageLedger.markReady(entry.key, INTERRUPTED_RESPONSE, 'html-v1');
+                    await this.deliverReadyEntry(entry.key);
                 }
-            },
-        };
-    }
-    async sendMessageFromActiveTurn(chatId, text, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        if (!text.trim())
-            return;
-        await this.runInChatQueue(chatId, () => this.sendMessageNow(chatId, text, idempotencyKey), true);
+            }
+            catch (error) {
+                // Delivery already recorded its progress; one entry must not keep polling from starting.
+                this.log(`telegram recovery failed key=${entry.key} error=${telegramErrorMessage(error)}`);
+            }
+        }
     }
     async sendMessageNow(chatId, text, idempotencyKey) {
-        const bot = this.bot;
-        if (!bot)
+        if (!this.bot)
             throw new Error('Telegram gateway not connected');
-        const ledgerKey = idempotencyKey ? this.outboundLedgerKey(idempotencyKey, 'text') : undefined;
-        const pending = ledgerKey ? this.messageLedger.get(ledgerKey) : null;
-        const chunkFormat = pending?.state === 'ready' ? (pending.chunkFormat ?? 'plain-v1') : 'html-v1';
-        const chunks = (0, telegram_format_js_1.formatTelegramMessage)(text, TELEGRAM_MAX_LENGTH, chunkFormat);
-        // Zero chunks means zero API calls. Claiming the ledger and marking it
-        // delivered would record a send that never happened and suppress every
-        // retry of it, so refuse before touching the ledger at all.
-        if (chunks.length === 0)
-            throw new Error('Refusing to record an empty Telegram delivery');
-        const numChatId = Number(chatId);
-        if (!ledgerKey) {
+        const chunks = (0, telegram_format_js_1.formatTelegramMessage)(text, TELEGRAM_MAX_LENGTH, 'html-v1');
+        if (!idempotencyKey) {
             for (const chunk of chunks)
-                await sendFormattedMessage(bot.api, numChatId, chunk);
+                await sendFormattedMessage(this.bot.api, Number(chatId), chunk);
             return;
         }
+        const key = outboundLedgerKey(idempotencyKey);
         const binding = {
             deliveryTarget: `telegram:${chatId}`,
             payloadIdentity: (0, node_crypto_1.createHash)('sha256').update(text).digest('hex'),
+            idempotencyKey,
+            keepDeliveredOnPayloadChange: true,
         };
-        const { entry: existing } = this.messageLedger.claim(ledgerKey, binding);
-        if (existing?.state === 'delivered')
+        const existing = this.messageLedger.claim(key, binding).entry;
+        if (existing.state === 'delivered')
             return;
-        let nextIndex = 0;
-        if (existing?.state === 'ready' && existing.response) {
-            const progress = parseOutboundChunkProgress(existing.response);
-            nextIndex = progress.nextIndex;
-            if (progress.uncertain) {
-                console.warn(`[Telegram] Retrying delivery ${ledgerKey} from chunk ${nextIndex} after an ` +
-                    'ambiguous prior acceptance; at-least-once delivery may duplicate that chunk');
-            }
-        }
-        for (let index = nextIndex; index < chunks.length; index += 1) {
-            this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index, uncertain: true }), chunkFormat);
+        if (existing.state !== 'ready')
+            this.messageLedger.markReady(key, text, 'html-v1');
+        await this.deliverOutboundEntry(key, chatId);
+    }
+    async deliverOutboundEntry(key, chatId) {
+        const entry = this.messageLedger.get(key);
+        if (!entry)
+            throw new Error(`Telegram outbound entry is missing: ${key}`);
+        if (entry.state === 'delivered')
+            return;
+        if (entry.deliveryUncertain)
+            throw new Error('Telegram outbound delivery is uncertain');
+        if (!this.bot)
+            throw new Error('Telegram gateway not connected');
+        if (entry.response === undefined)
+            throw new Error('Telegram outbound entry has no response');
+        // markReady persists both fields; inventing them could resend chunks or change their formatting.
+        if (entry.chunkFormat === undefined || entry.nextChunkIndex === undefined) {
+            throw new Error('Telegram outbound entry has incomplete delivery metadata');
+        }
+        const chunks = (0, telegram_format_js_1.formatTelegramMessage)(entry.response, TELEGRAM_MAX_LENGTH, entry.chunkFormat);
+        const start = entry.nextChunkIndex;
+        for (let index = start; index < chunks.length; index += 1) {
+            this.messageLedger.markDeliveryProgress(key, index, true);
             try {
-                await sendFormattedMessage(bot.api, numChatId, chunks[index]);
+                const sent = await sendFormattedMessage(this.bot.api, Number(chatId), chunks[index]);
+                this.messageLedger.markDeliveryProgress(key, index + 1, false, sent.message_id);
             }
             catch (error) {
-                if (isDefiniteTelegramApiRejection(error)) {
-                    this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index, uncertain: false }), chunkFormat);
+                if ((0, telegram_errors_js_1.isDefinitiveTelegramRejection)(error)) {
+                    this.messageLedger.markDeliveryProgress(key, index, false);
                 }
                 throw error;
             }
-            this.messageLedger.markReady(ledgerKey, JSON.stringify({ version: 1, nextIndex: index + 1, uncertain: false }), chunkFormat);
-        }
-        this.messageLedger.markDelivered(ledgerKey);
-    }
-    async sendFile(chatId, filePath, caption, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        const { InputFile } = await import('grammy');
-        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'file', chatId, `${filePath}\0${caption ?? ''}`, () => this.bot.api.sendDocument(Number(chatId), new InputFile(filePath), { caption }).then(() => { })));
-    }
-    async sendFileFromActiveTurn(chatId, filePath, caption, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        const { InputFile } = await import('grammy');
-        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'file', chatId, `${filePath}\0${caption ?? ''}`, () => this.bot.api.sendDocument(Number(chatId), new InputFile(filePath), { caption }).then(() => { })), true);
-    }
-    async sendImage(chatId, imagePath, caption, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        const { InputFile } = await import('grammy');
-        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'image', chatId, `${imagePath}\0${caption ?? ''}`, () => this.bot.api.sendPhoto(Number(chatId), new InputFile(imagePath), { caption }).then(() => { })));
-    }
-    async sendImageFromActiveTurn(chatId, imagePath, caption, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        const { InputFile } = await import('grammy');
-        await this.runInChatQueue(chatId, () => this.sendOutboundOnce(idempotencyKey, 'image', chatId, `${imagePath}\0${caption ?? ''}`, () => this.bot.api.sendPhoto(Number(chatId), new InputFile(imagePath), { caption }).then(() => { })), true);
-    }
-    async sendOutboundOnce(idempotencyKey, kind, chatId, payload, send) {
-        if (!idempotencyKey) {
-            await send();
-            return;
         }
-        const ledgerKey = this.outboundLedgerKey(idempotencyKey, kind);
-        const { entry: existing } = this.messageLedger.claim(ledgerKey, {
-            deliveryTarget: `telegram:${chatId}`,
-            payloadIdentity: (0, node_crypto_1.createHash)('sha256').update(payload).digest('hex'),
-        });
-        if (existing.state === 'delivered')
-            return;
-        await send();
-        this.messageLedger.markDelivered(ledgerKey);
+        this.messageLedger.markDelivered(key);
+        this.log(`telegram outbound delivered idempotency_key=${JSON.stringify(entry.idempotencyKey)} message_ids=${JSON.stringify(this.messageLedger.get(key).messageIds ?? [])}`);
     }
-    async recoverPendingInboundDeliveries() {
-        for (const snapshot of this.messageLedger.listUndelivered()) {
-            if (snapshot.key.startsWith('outbound:'))
-                continue;
-            const separator = snapshot.key.lastIndexOf(':');
-            if (separator <= 0)
-                continue;
-            const chatId = snapshot.key.slice(0, separator);
-            await this.runInChatQueue(chatId, async () => {
-                const entry = this.messageLedger.get(snapshot.key);
-                // The live presenter owns ready as well as processing until it settles.
-                // Recovery must not jump ahead while that presenter drains a streaming edit.
-                if (this.activeInboundMessages.has(snapshot.key))
-                    return;
-                if (!entry || entry.state === 'delivered')
-                    return;
-                if (entry.state === 'processing' && this.messageLedger.isOwnedByCurrentProcess(entry)) {
-                    return;
-                }
-                const response = entry.state === 'ready' && entry.response !== undefined
-                    ? entry.response
-                    : 'The previous processing attempt was interrupted. It was not rerun because its ' +
-                        'external side effects could not be proven safe to repeat. Please send a new message ' +
-                        'if you want to retry it.';
-                if (entry.state !== 'ready')
-                    this.messageLedger.markReady(entry.key, response, 'html-v1');
-                if (entry.deliveryUncertain) {
-                    console.warn(`[Telegram] Resuming inbound delivery ${entry.key} from uncertain chunk ` +
-                        `${entry.nextChunkIndex ?? 0}; that chunk may appear twice`);
-                }
-                const presenter = this.createResponsePresenter(Number(chatId), entry.key, entry.nextChunkIndex ?? 0);
-                await presenter.finalize(response);
-                this.messageLedger.markDelivered(entry.key);
-            });
-        }
-    }
-    createResponsePresenter(chatId, messageKey, resumeFromChunk = 0, onInitialSend) {
-        const api = this.bot.api;
-        return new telegram_response_presenter_js_1.TelegramResponsePresenter({
-            send: async (content) => {
-                const sent = await this.runInChatQueue(String(chatId), () => sendFormattedMessage(api, chatId, content), true);
-                onInitialSend?.(sent.message_id);
-                return String(sent.message_id);
-            },
-            edit: async (handle, content) => {
-                await this.runInChatQueue(String(chatId), () => editFormattedMessage(api, chatId, Number(handle), content), true);
-            },
-            delete: async (handle) => {
-                await this.runInChatQueue(String(chatId), () => api.deleteMessage(chatId, Number(handle)), true);
-            },
-        }, {
-            resumeFromChunk,
-            chunkFormat: this.messageLedger.get(messageKey)?.state === 'ready'
-                ? (this.messageLedger.get(messageKey)?.chunkFormat ?? 'plain-v1')
-                : 'html-v1',
-            withDelivery: (send) => this.runInChatQueue(String(chatId), send, true),
-            onChunkProgress: (nextIndex, uncertain) => {
-                if (this.messageLedger.get(messageKey)?.state === 'ready') {
-                    this.messageLedger.markDeliveryProgress(messageKey, nextIndex, uncertain);
-                }
-            },
+    async runInChatQueue(chatId, work, allowReentrant = false) {
+        const active = this.activeChat.getStore();
+        if (allowReentrant && active?.active && active.chatId === chatId)
+            return work();
+        const previous = this.chatTails.get(chatId);
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
         });
-    }
-    outboundLedgerKey(idempotencyKey, kind) {
-        const digest = (0, node_crypto_1.createHash)('sha256').update(`${kind}\0${idempotencyKey}`).digest('hex');
-        return `outbound:${digest}`;
-    }
-    /** Read the existing durable proof for one exact outbound delivery occurrence. */
-    readOutboundDeliveryReceipt(deliveryId, variant) {
-        const entry = this.messageLedger.get(this.outboundLedgerKey(deliveryId, variant));
-        if (entry?.state !== 'delivered' ||
-            typeof entry.payloadIdentity !== 'string' ||
-            !/^[a-f0-9]{64}$/.test(entry.payloadIdentity)) {
-            return null;
-        }
-        return {
-            deliveryId,
-            variant,
-            state: 'delivered',
-            payloadIdentity: entry.payloadIdentity,
-            confirmedAt: entry.updatedAt,
-        };
-    }
-    async sendSticker(chatId, emotion, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        return this.runInChatQueue(String(chatId), () => this.sendStickerNow(chatId, emotion, idempotencyKey));
-    }
-    async sendStickerFromActiveTurn(chatId, emotion, idempotencyKey) {
-        if (!this.bot)
-            throw new Error('Telegram gateway not connected');
-        return this.runInChatQueue(String(chatId), () => this.sendStickerNow(chatId, emotion, idempotencyKey), true);
-    }
-    async sendStickerNow(chatId, emotion, idempotencyKey) {
-        const bot = this.bot;
-        if (!bot)
-            throw new Error('Telegram gateway not connected');
-        await this.loadStickerSet();
-        const candidates = EMOTION_EMOJI[emotion] ?? EMOTION_EMOJI.happy;
-        const numChatId = typeof chatId === 'string' ? Number(chatId) : chatId;
-        for (const emoji of candidates) {
-            const fileId = this.stickerCache.get(emoji);
-            if (fileId) {
-                await this.sendOutboundOnce(idempotencyKey, 'sticker', String(chatId), `${emotion}\0${fileId}`, () => bot.api.sendSticker(numChatId, fileId).then(() => { }));
-                return true;
-            }
-        }
-        await this.sendOutboundOnce(idempotencyKey, 'sticker', String(chatId), `${emotion}\0${candidates[0]}`, () => bot.api.sendMessage(numChatId, candidates[0]).then(() => { }));
-        return false;
-    }
-    getLastError() {
-        return this.lastError;
-    }
-    getLastMessageAt() {
-        return this.lastMessageAt;
-    }
-    async loadStickerSet() {
-        if (this.stickerSetLoaded || !this.bot)
-            return;
+        const current = (previous ?? Promise.resolve()).catch(() => { }).then(() => gate);
+        this.chatTails.set(chatId, current);
         try {
-            const set = await this.bot.api.getStickerSet(DEFAULT_STICKER_SET);
-            for (const sticker of set.stickers) {
-                if (sticker.emoji && !this.stickerCache.has(sticker.emoji)) {
-                    this.stickerCache.set(sticker.emoji, sticker.file_id);
-                }
-            }
-            this.stickerSetLoaded = true;
+            if (previous)
+                await previous.catch(() => { });
+            return await this.activeChat.run({ chatId, active: true }, work);
         }
-        catch {
-            this.stickerSetLoaded = true;
+        finally {
+            release();
+            if (this.chatTails.get(chatId) === current)
+                this.chatTails.delete(chatId);
         }
     }
 }