@ouro.bot/cli 0.1.0-alpha.74 → 0.1.0-alpha.741

package/dist/senses/telegram.js

@@ -0,0 +1,1232 @@
+"use strict";
+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.telegramAcceptanceAuditOwnerDigest = telegramAcceptanceAuditOwnerDigest;
+exports.sanctuaryTelegramTurnReceiptDigest = sanctuaryTelegramTurnReceiptDigest;
+exports.sanctuaryTelegramTurnReceiptMac = sanctuaryTelegramTurnReceiptMac;
+exports.sanctuaryTelegramAuditLifecycleMac = sanctuaryTelegramAuditLifecycleMac;
+exports.sanctuaryTelegramUnauthorizedDropMac = sanctuaryTelegramUnauthorizedDropMac;
+exports.sanctuaryTelegramApprovalEvidenceMac = sanctuaryTelegramApprovalEvidenceMac;
+exports.readOrCreateTelegramIdentityKey = readOrCreateTelegramIdentityKey;
+exports.opaqueTelegramSubject = opaqueTelegramSubject;
+exports.migrateTelegramFriendIdentity = migrateTelegramFriendIdentity;
+exports.migrateTelegramSessionIdentity = migrateTelegramSessionIdentity;
+exports.parseTelegramSenseCredentials = parseTelegramSenseCredentials;
+exports.createTelegramSenseApp = createTelegramSenseApp;
+exports.loadTelegramSenseCredentials = loadTelegramSenseCredentials;
+exports.startTelegramSenseApp = startTelegramSenseApp;
+const node_crypto_1 = require("node:crypto");
+const node_async_hooks_1 = require("node:async_hooks");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const friends_1 = require("@ouro.bot/friends");
+const identity_1 = require("../heart/identity");
+const sanctuary_acceptance_marker_1 = require("../heart/daemon/sanctuary-acceptance-marker");
+const runtime_credentials_1 = require("../heart/runtime-credentials");
+const runtime_1 = require("../nerves/runtime");
+const nerves_1 = require("../nerves");
+const sanctuary_interactive_control_1 = require("./sanctuary-interactive-control");
+const shared_turn_1 = require("./shared-turn");
+const telegram_client_1 = require("./telegram-client");
+const sanctuary_runtime_1 = require("./sanctuary-runtime");
+const sanctuary_grounding_1 = require("./sanctuary-grounding");
+const telegram_approval_runtime_1 = require("./telegram-approval-runtime");
+const telegram_audit_ledger_1 = require("./telegram-audit-ledger");
+const APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS = 1_000;
+const TELEGRAM_SUBJECT_DOMAIN = "ouroboros.telegram.subject.v1";
+const TELEGRAM_IDENTITY_KEY = /^[A-Za-z0-9_-]{43}$/u;
+const TELEGRAM_SUBJECT = /^tg_[A-Za-z0-9_-]{43}$/u;
+const TELEGRAM_SUBJECT_INDEX = "identity-subjects.json";
+const TELEGRAM_ACCEPTANCE_AUDIT_EVENTS = new Set([
+    "approval.acceptance_continuation_transition",
+    "approval.acceptance_transition",
+    "senses.sanctuary_health_delivered",
+    "senses.sanctuary_read_receipt",
+    "senses.telegram_approved_restart_end",
+    "senses.telegram_approved_restart_error",
+    "senses.telegram_approved_restart_start",
+    "senses.telegram_approval_continuation_delivered",
+    "senses.telegram_approval_prompt_bound",
+    "senses.telegram_turn_end",
+    "senses.telegram_turn_error",
+    "senses.telegram_turn_start",
+    "telegram.approval_prompt_terminalized",
+    "telegram.approval_expiry_observed",
+    "telegram.approval_stale_callback_settled",
+    "telegram.callback_recovery_settled",
+    "telegram.callback_settled",
+    "telegram.update_dropped",
+]);
+const telegramAcceptanceAuditOwner = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAuditScenario = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAuditExplicitCommit = new node_async_hooks_1.AsyncLocalStorage();
+const telegramAcceptanceAudits = new Map();
+const TELEGRAM_TURN_RECEIPT_DOMAINS = {
+    "sanctuary-telegram-turn-receipt-v3": "ouroboros.telegram.turn-receipt.v3",
+    "sanctuary-telegram-turn-receipt-v4": "ouroboros.telegram.turn-receipt.v4",
+};
+const TELEGRAM_TURN_LEDGER_MAX_BYTES = 4 * 1024 * 1024;
+const TELEGRAM_TURN_LEDGER_MAX_ROWS = 500;
+const TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES = 16 * 1024;
+const telegramTurnLedgerTails = new Map();
+function telegramAcceptanceAuditOwnerDigest(identityKey, agentName, root) {
+    return (0, node_crypto_1.createHmac)("sha256", identityKey)
+        .update(`ouroboros.telegram.acceptance-audit-owner.v1\0${agentName}\0${root}`, "utf8")
+        .digest("hex");
+}
+function acquireTelegramAcceptanceAudit(root, agentName, identityKey, privateValues, scenarioHandleDigest, releaseHook, maxBytes) {
+    const existing = telegramAcceptanceAudits.get(root);
+    if (existing) {
+        if (existing.identityKey !== identityKey)
+            throw new Error("Telegram acceptance audit identity changed while active");
+        if (existing.scenarioHandleDigest !== scenarioHandleDigest)
+            throw new Error("Telegram acceptance audit scenario changed while active");
+        existing.ledger.assertHealthy();
+        existing.references += 1;
+        return { ledger: existing.ledger, ownerDigest: existing.ownerDigest, scenarioHandleDigest: existing.scenarioHandleDigest, release: () => {
+                existing.references -= 1;
+                if (existing.references === 0) {
+                    try {
+                        existing.unregister();
+                    }
+                    finally {
+                        telegramAcceptanceAudits.delete(root);
+                    }
+                    releaseHook?.();
+                }
+            } };
+    }
+    const ledger = (0, telegram_audit_ledger_1.createTelegramAuditLedger)({ root, identityKey, privateValues, _maxBytes: maxBytes });
+    const ownerDigest = telegramAcceptanceAuditOwnerDigest(identityKey, agentName, root);
+    let record;
+    const unregister = (0, nerves_1.registerGlobalLogSink)((event) => {
+        if (!TELEGRAM_ACCEPTANCE_AUDIT_EVENTS.has(event.event))
+            return;
+        if (telegramAcceptanceAuditExplicitCommit.getStore())
+            return;
+        const explicitOwner = event.meta.acceptanceAuditOwnerDigest;
+        const contextualOwner = telegramAcceptanceAuditOwner.getStore();
+        if (explicitOwner !== ownerDigest && contextualOwner !== ownerDigest)
+            return;
+        const scenario = event.meta.scenarioHandleDigest;
+        if (typeof scenario !== "string" || !/^[0-9a-f]{64}$/u.test(scenario) || record.scenarioHandleDigest !== scenario) {
+            ledger.poison(new Error("Telegram acceptance audit scenario ownership drift"));
+        }
+        ledger.append(event);
+    });
+    record = { agentName, identityKey, ledger, ownerDigest, references: 1, scenarioHandleDigest, unregister };
+    telegramAcceptanceAudits.set(root, record);
+    return { ledger, ownerDigest, scenarioHandleDigest, release: () => {
+            record.references -= 1;
+            if (record.references === 0) {
+                try {
+                    record.unregister();
+                }
+                finally {
+                    telegramAcceptanceAudits.delete(root);
+                }
+                releaseHook?.();
+            }
+        } };
+}
+function sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value) {
+    return (0, node_crypto_1.createHmac)("sha256", identityKey).update(`${TELEGRAM_TURN_RECEIPT_DOMAINS[schemaVersion]}\0${purpose}\0${value}`, "utf8").digest("hex");
+}
+function canonicalReceiptJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalReceiptJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalReceiptJson(record[key])}`).join(",")}}`;
+    }
+    const rendered = JSON.stringify(value);
+    if (rendered === undefined)
+        throw new Error("Telegram receipt contains an unsupported value");
+    return rendered;
+}
+function sanctuaryTelegramTurnReceiptMac(identityKey, value) {
+    const unsigned = Object.fromEntries(Object.entries(value).filter(([key]) => key !== "receiptMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, "sanctuary-telegram-turn-receipt-v4", "receipt", canonicalReceiptJson(unsigned));
+}
+function sanctuaryTelegramAuditLifecycleMac(identityKey, schemaVersion, event, meta) {
+    const unsigned = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== "lifecycleMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, "audit-lifecycle", canonicalReceiptJson({ event, meta: unsigned }));
+}
+function sanctuaryTelegramUnauthorizedDropMac(identityKey, schemaVersion, value) {
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, "unauthorized-drop", canonicalReceiptJson(value));
+}
+function sanctuaryTelegramApprovalEvidenceMac(identityKey, event, meta) {
+    const unsigned = Object.fromEntries(Object.entries(meta).filter(([key]) => key !== "evidenceMac"));
+    return sanctuaryTelegramTurnReceiptDigest(identityKey, "sanctuary-telegram-turn-receipt-v3", "approval-evidence", canonicalReceiptJson({ event, meta: unsigned }));
+}
+function sameTelegramLedgerMetadata(left, right) {
+    return left.dev === right.dev
+        && left.ino === right.ino
+        && left.mode === right.mode
+        && left.nlink === right.nlink
+        && left.uid === right.uid
+        && left.gid === right.gid
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+function readStableBoundedTelegramLedger(filePath, afterPreReadStat) {
+    let handle;
+    try {
+        handle = (0, node_fs_1.openSync)(filePath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const before = (0, node_fs_1.fstatSync)(handle, { bigint: true });
+        if (!before.isFile())
+            throw new Error("Telegram turn receipt ledger must be a regular file");
+        if (before.size > BigInt(TELEGRAM_TURN_LEDGER_MAX_BYTES))
+            throw new Error("Telegram turn receipt ledger exceeds its bound");
+        afterPreReadStat?.(filePath);
+        const expectedBytes = Number(before.size);
+        const content = Buffer.allocUnsafe(expectedBytes);
+        let offset = 0;
+        while (offset < expectedBytes) {
+            const bytesRead = (0, node_fs_1.readSync)(handle, content, offset, expectedBytes - offset, offset);
+            if (bytesRead === 0)
+                throw new Error("Telegram turn receipt ledger changed during read");
+            offset += bytesRead;
+        }
+        const overflow = Buffer.allocUnsafe(1);
+        const overflowBytes = (0, node_fs_1.readSync)(handle, overflow, 0, 1, expectedBytes);
+        const after = (0, node_fs_1.fstatSync)(handle, { bigint: true });
+        const pathAfter = (0, node_fs_1.lstatSync)(filePath, { bigint: true });
+        if (overflowBytes !== 0 || !sameTelegramLedgerMetadata(before, after)
+            || !pathAfter.isFile() || pathAfter.dev !== before.dev || pathAfter.ino !== before.ino) {
+            throw new Error("Telegram turn receipt ledger changed during read");
+        }
+        return content.toString("utf8");
+    }
+    finally {
+        (0, node_fs_1.closeSync)(handle);
+    }
+}
+function validateSanctuaryTurnReceipt(value) {
+    const grounded = value.schemaVersion === "sanctuary-telegram-turn-receipt-v4";
+    const exactKeys = ["completedAt", "deliveries", "deliveryCount", "errorCategory", "providerInvocationCount", "responseDigest", "scenarioHandleDigest", "schemaVersion", "sequenceDigest", "status", "toolInvocationCount", "toolResultDigests", "updateDigest", ...(grounded ? ["receiptMac", "toolGroundings"] : [])].sort();
+    const deliveries = value.deliveries;
+    if (JSON.stringify(Object.keys(value).sort()) !== JSON.stringify(exactKeys)
+        || (!grounded && value.schemaVersion !== "sanctuary-telegram-turn-receipt-v3")
+        || typeof value.scenarioHandleDigest !== "string" || !/^[0-9a-f]{64}$/u.test(value.scenarioHandleDigest)
+        || (value.status !== "success" && value.status !== "error")
+        || (value.status === "success"
+            ? value.errorCategory !== null
+            : typeof value.errorCategory !== "string" || value.errorCategory.length < 1 || value.errorCategory.length > 128)
+        || ![value.updateDigest, value.sequenceDigest, value.responseDigest].every((digest) => typeof digest === "string" && /^[0-9a-f]{64}$/u.test(digest))
+        || !Array.isArray(value.toolResultDigests) || value.toolResultDigests.length > 100 || !value.toolResultDigests.every((digest) => typeof digest === "string" && /^[0-9a-f]{64}$/u.test(digest))
+        || !Array.isArray(deliveries) || deliveries.length > 100 || !deliveries.every((delivery) => {
+        if (!delivery || typeof delivery !== "object" || Array.isArray(delivery))
+            return false;
+        const record = delivery;
+        return JSON.stringify(Object.keys(record).sort()) === JSON.stringify(grounded ? ["chunkDigest", "messageIdDigest", "redactedText", "utf16Units"] : ["chunkDigest", "messageIdDigest"])
+            && typeof record.chunkDigest === "string" && /^[0-9a-f]{64}$/u.test(record.chunkDigest)
+            && typeof record.messageIdDigest === "string" && /^[0-9a-f]{64}$/u.test(record.messageIdDigest)
+            && (!grounded || (typeof record.redactedText === "string" && record.redactedText.length === record.utf16Units && record.utf16Units <= 1_200));
+    })
+        || (grounded && (!Array.isArray(value.toolGroundings) || value.toolGroundings.length !== 1 || !value.toolGroundings.every((raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                return false;
+            const record = raw;
+            if (JSON.stringify(Object.keys(record).sort()) !== JSON.stringify(["facts", "groundingDigest", "observedAt", "resultDigest", "sourceIdentityDigest", "toolName"]) || (record.toolName !== "unraid_get_system" && record.toolName !== "unraid_get_storage")
+                || typeof record.resultDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.resultDigest) || typeof record.groundingDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.groundingDigest)
+                || typeof record.sourceIdentityDigest !== "string" || !/^[0-9a-f]{64}$/u.test(record.sourceIdentityDigest) || typeof record.observedAt !== "string" || !Number.isFinite(Date.parse(record.observedAt)) || new Date(Date.parse(record.observedAt)).toISOString() !== record.observedAt
+                || !record.facts || typeof record.facts !== "object" || Array.isArray(record.facts))
+                return false;
+            return (0, sanctuary_grounding_1.sanctuaryGroundingDigest)(record.facts) === record.groundingDigest && value.toolResultDigests.includes(record.resultDigest);
+        })))
+        || (grounded && (typeof value.receiptMac !== "string" || !/^[0-9a-f]{64}$/u.test(value.receiptMac)))
+        || ![value.providerInvocationCount, value.toolInvocationCount].every((count) => Number.isSafeInteger(count) && Number(count) >= 0 && Number(count) <= 1_000)
+        || !Number.isSafeInteger(value.deliveryCount) || value.deliveryCount !== deliveries.length
+        || typeof value.completedAt !== "string" || value.completedAt.length > 30 || !Number.isFinite(Date.parse(value.completedAt)) || new Date(Date.parse(value.completedAt)).toISOString() !== value.completedAt)
+        throw new Error("Telegram turn receipt ledger row is invalid");
+}
+async function appendSanctuaryTurnReceipt(agentRoot, receipt, afterPreReadStat) {
+    const filePath = path.join(agentRoot, "state", "acceptance", "telegram-turns.ndjson");
+    const previous = telegramTurnLedgerTails.get(filePath) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(() => {
+        (0, node_fs_1.mkdirSync)(path.dirname(filePath), { recursive: true, mode: 0o700 });
+        let existing = [];
+        const raw = readStableBoundedTelegramLedger(filePath, afterPreReadStat);
+        if (raw !== null) {
+            existing = raw.split("\n").filter(Boolean);
+            if (existing.length > TELEGRAM_TURN_LEDGER_MAX_ROWS || existing.some((line) => Buffer.byteLength(line) > TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES))
+                throw new Error("Telegram turn receipt ledger is invalid");
+            for (const line of existing) {
+                validateSanctuaryTurnReceipt(JSON.parse(line));
+            }
+        }
+        validateSanctuaryTurnReceipt(receipt);
+        const serialized = JSON.stringify(receipt);
+        if (Buffer.byteLength(serialized) > TELEGRAM_TURN_LEDGER_MAX_ROW_BYTES)
+            throw new Error("Telegram turn receipt exceeds its bound");
+        const lines = [...existing, serialized].slice(-TELEGRAM_TURN_LEDGER_MAX_ROWS);
+        let aggregateBytes = lines.reduce((total, line) => total + Buffer.byteLength(line) + 1, 0);
+        while (aggregateBytes > TELEGRAM_TURN_LEDGER_MAX_BYTES && lines.length > 1) {
+            aggregateBytes -= Buffer.byteLength(lines.shift()) + 1;
+        }
+        const temporary = `${filePath}.tmp-${process.pid}-${(0, node_crypto_1.randomUUID)()}`;
+        (0, node_fs_1.writeFileSync)(temporary, `${lines.join("\n")}\n`, { mode: 0o600, flag: "wx" });
+        const handle = (0, node_fs_1.openSync)(temporary, "r");
+        try {
+            (0, node_fs_1.fsyncSync)(handle);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(handle);
+        }
+        (0, node_fs_1.renameSync)(temporary, filePath);
+        const directory = (0, node_fs_1.openSync)(path.dirname(filePath), "r");
+        try {
+            (0, node_fs_1.fsyncSync)(directory);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(directory);
+        }
+    });
+    telegramTurnLedgerTails.set(filePath, current);
+    try {
+        await current;
+    }
+    finally {
+        if (telegramTurnLedgerTails.get(filePath) === current)
+            telegramTurnLedgerTails.delete(filePath);
+    }
+}
+function requiredText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`Telegram ${label} is missing`);
+    return value.trim();
+}
+function canonicalTelegramId(value, label) {
+    const text = requiredText(value, label);
+    if (!/^[1-9][0-9]*$/u.test(text))
+        throw new Error(`Telegram ${label} must be a canonical positive decimal string`);
+    return text;
+}
+function canonicalTelegramIdentityKey(value) {
+    const key = value.trim();
+    if (!TELEGRAM_IDENTITY_KEY.test(key) || Buffer.from(key, "base64url").length !== 32) {
+        throw new Error("Telegram opaque identity key is invalid");
+    }
+    return key;
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+function openSecureTelegramDirectory(directory, afterOpen) {
+    try {
+        const existing = (0, node_fs_1.lstatSync)(directory);
+        if (existing.isSymbolicLink())
+            throw new Error("Telegram state directory must not be a symbolic link");
+        if (!existing.isDirectory())
+            throw new Error("Telegram state directory is not a directory");
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+        (0, node_fs_1.mkdirSync)(directory, { recursive: true, mode: 0o700 });
+    }
+    const handle = (0, node_fs_1.openSync)(directory, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_DIRECTORY | node_fs_1.constants.O_NOFOLLOW);
+    try {
+        (0, node_fs_1.fchmodSync)(handle, 0o700);
+        afterOpen?.(handle);
+        const metadata = (0, node_fs_1.fstatSync)(handle);
+        if (!metadata.isDirectory() || (metadata.mode & 0o777) !== 0o700) {
+            throw new Error("Telegram state directory permissions are invalid");
+        }
+        return handle;
+    }
+    catch (error) {
+        (0, node_fs_1.closeSync)(handle);
+        throw error;
+    }
+}
+function readOrCreateTelegramIdentityKey(agentRoot, hooks = {}) {
+    const directory = path.join(agentRoot, "state", "senses", "telegram");
+    const keyPath = path.join(directory, "identity.key");
+    const directoryHandle = openSecureTelegramDirectory(directory, hooks.afterOpenDirectory);
+    const readKey = () => {
+        const handle = (0, node_fs_1.openSync)(keyPath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+        try {
+            const metadata = (0, node_fs_1.fstatSync)(handle);
+            if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600)
+                throw new Error("Telegram opaque identity key permissions are invalid");
+            return canonicalTelegramIdentityKey((0, node_fs_1.readFileSync)(handle, "utf8"));
+        }
+        finally {
+            (0, node_fs_1.closeSync)(handle);
+        }
+    };
+    try {
+        try {
+            return readKey();
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                throw error;
+        }
+        const key = (0, node_crypto_1.randomBytes)(32).toString("base64url");
+        hooks.beforeCreate?.(keyPath);
+        const temporaryPath = path.join(directory, `.identity.key.${(0, node_crypto_1.randomBytes)(12).toString("base64url")}.tmp`);
+        let temporaryHandle;
+        try {
+            temporaryHandle = (0, node_fs_1.openSync)(temporaryPath, node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_NOFOLLOW, 0o600);
+            hooks.afterCreateTemporary?.(temporaryPath, keyPath);
+            (0, node_fs_1.writeFileSync)(temporaryHandle, `${key}\n`);
+            (0, node_fs_1.fsyncSync)(temporaryHandle);
+            (0, node_fs_1.closeSync)(temporaryHandle);
+            temporaryHandle = undefined;
+            hooks.beforePublish?.(temporaryPath, keyPath);
+            try {
+                (0, node_fs_1.linkSync)(temporaryPath, keyPath);
+            }
+            catch (error) {
+                if (errorCode(error) !== "EEXIST")
+                    throw error;
+                return readKey();
+            }
+            (0, node_fs_1.fsyncSync)(directoryHandle);
+            return key;
+        }
+        finally {
+            if (temporaryHandle !== undefined)
+                (0, node_fs_1.closeSync)(temporaryHandle);
+            if ((0, node_fs_1.existsSync)(temporaryPath))
+                (0, node_fs_1.unlinkSync)(temporaryPath);
+            (0, node_fs_1.fsyncSync)(directoryHandle);
+        }
+    }
+    finally {
+        (0, node_fs_1.closeSync)(directoryHandle);
+    }
+}
+function opaqueTelegramSubject(identityKey, botToken, authorizedUserId, authorizedChatId) {
+    const payload = [
+        TELEGRAM_SUBJECT_DOMAIN,
+        `bot:${botToken.length}:${botToken}`,
+        `user:${authorizedUserId.length}:${authorizedUserId}`,
+        `chat:${authorizedChatId.length}:${authorizedChatId}`,
+    ].join("\0");
+    return `tg_${(0, node_crypto_1.createHmac)("sha256", identityKey).update(payload, "utf8").digest("base64url")}`;
+}
+function readTelegramSubjectIndex(agentRoot, subject) {
+    const indexPath = path.join(agentRoot, "state", "senses", "telegram", TELEGRAM_SUBJECT_INDEX);
+    let text;
+    let handle;
+    try {
+        handle = (0, node_fs_1.openSync)(indexPath, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW);
+        const metadata = (0, node_fs_1.fstatSync)(handle);
+        if (!metadata.isFile() || (metadata.mode & 0o777) !== 0o600)
+            throw new Error("Telegram identity subject index permissions are invalid");
+        text = (0, node_fs_1.readFileSync)(handle, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return [];
+        throw error;
+    }
+    finally {
+        if (handle !== undefined)
+            (0, node_fs_1.closeSync)(handle);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Telegram identity subject index is invalid");
+    const record = parsed;
+    if (record.version !== 1 || typeof record.subject !== "string" || !TELEGRAM_SUBJECT.test(record.subject) || !Array.isArray(record.legacySubjects)
+        || Object.keys(record).sort().join(",") !== "legacySubjects,subject,version") {
+        throw new Error("Telegram identity subject index is invalid");
+    }
+    const legacySubjects = record.legacySubjects;
+    if (!legacySubjects.every((candidate) => typeof candidate === "string" && TELEGRAM_SUBJECT.test(candidate))) {
+        throw new Error("Telegram identity subject index is invalid");
+    }
+    return record.subject === subject ? [] : [record.subject];
+}
+function discoverTelegramFilesystemSubjects(agentRoot) {
+    const subjects = new Set();
+    const addFriendDirectorySubjects = (root) => {
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)(root, { withFileTypes: true });
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT")
+                return;
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith("telegram-user:"))
+                continue;
+            const candidate = entry.name.slice("telegram-user:".length);
+            if (TELEGRAM_SUBJECT.test(candidate))
+                subjects.add(candidate);
+        }
+    };
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "sessions"));
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "pending"));
+    addFriendDirectorySubjects(path.join(agentRoot, "state", "pending-returns"));
+    const friendsRoot = path.join(agentRoot, "friends");
+    let friendFiles;
+    try {
+        friendFiles = (0, node_fs_1.readdirSync)(friendsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return [...subjects];
+        throw error;
+    }
+    for (const entry of friendFiles) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const friend = JSON.parse((0, node_fs_1.readFileSync)(path.join(friendsRoot, entry.name), "utf8"));
+        if (!friend || typeof friend !== "object" || !Array.isArray(friend.externalIds)) {
+            throw new Error("Telegram Friend identity record is invalid");
+        }
+        for (const external of friend.externalIds) {
+            if (!external || typeof external !== "object")
+                throw new Error("Telegram Friend external identity is invalid");
+            const identity = external;
+            if (identity.provider === "telegram-user" && typeof identity.externalId === "string" && TELEGRAM_SUBJECT.test(identity.externalId)) {
+                subjects.add(identity.externalId);
+            }
+        }
+    }
+    return [...subjects];
+}
+function writeTelegramSubjectIndex(agentRoot, subject, legacySubjects, hooks = {}) {
+    const directory = path.join(agentRoot, "state", "senses", "telegram");
+    const indexPath = path.join(directory, TELEGRAM_SUBJECT_INDEX);
+    const directoryHandle = openSecureTelegramDirectory(directory);
+    const temporaryPath = path.join(directory, `.identity-subjects.${(0, node_crypto_1.randomBytes)(12).toString("base64url")}.tmp`);
+    let temporaryHandle;
+    try {
+        temporaryHandle = (0, node_fs_1.openSync)(temporaryPath, node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_NOFOLLOW, 0o600);
+        hooks.afterCreateTemporary?.(temporaryPath);
+        const contents = `${JSON.stringify({ version: 1, subject, legacySubjects: [...legacySubjects] }, null, 2)}\n`;
+        (0, node_fs_1.writeFileSync)(temporaryHandle, contents);
+        (0, node_fs_1.fsyncSync)(temporaryHandle);
+        (0, node_fs_1.closeSync)(temporaryHandle);
+        temporaryHandle = undefined;
+        (0, node_fs_1.renameSync)(temporaryPath, indexPath);
+        (0, node_fs_1.fsyncSync)(directoryHandle);
+    }
+    finally {
+        if (temporaryHandle !== undefined)
+            (0, node_fs_1.closeSync)(temporaryHandle);
+        if ((0, node_fs_1.existsSync)(temporaryPath))
+            (0, node_fs_1.unlinkSync)(temporaryPath);
+        (0, node_fs_1.closeSync)(directoryHandle);
+    }
+}
+async function migrateTelegramFriendIdentity(agentRoot, legacyUserId, subject) {
+    const store = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
+    const legacy = await store.findByExternalId("telegram-user", legacyUserId);
+    if (!legacy)
+        return;
+    const current = await store.findByExternalId("telegram-user", subject);
+    if (current && current.id !== legacy.id)
+        throw new Error("Telegram friend identity migration is ambiguous");
+    legacy.externalIds = legacy.externalIds.map((external) => external.provider === "telegram-user" && external.externalId === legacyUserId
+        ? { ...external, externalId: subject }
+        : external);
+    if (legacy.name === `Telegram user ${legacyUserId}`)
+        legacy.name = `Telegram user ${subject}`;
+    legacy.updatedAt = new Date().toISOString();
+    await store.put(legacy.id, legacy);
+}
+function migrateTelegramSessionIdentity(agentRoot, legacyUserId, legacyChatId, subject) {
+    const legacyFriendId = `telegram-user:${legacyUserId}`;
+    const opaqueFriendId = `telegram-user:${subject}`;
+    const migrateDirectory = (root) => {
+        const legacy = path.join(root, legacyFriendId);
+        const opaque = path.join(root, opaqueFriendId);
+        if (!(0, node_fs_1.existsSync)(legacy))
+            return (0, node_fs_1.existsSync)(opaque) ? opaque : null;
+        if ((0, node_fs_1.existsSync)(opaque))
+            throw new Error("Telegram session identity migration is ambiguous");
+        (0, node_fs_1.mkdirSync)(root, { recursive: true });
+        (0, node_fs_1.renameSync)(legacy, opaque);
+        return opaque;
+    };
+    const sessions = migrateDirectory(path.join(agentRoot, "state", "sessions"));
+    if (sessions) {
+        const legacySession = path.join(sessions, "telegram", `telegram_${legacyChatId}.json`);
+        const opaqueSession = path.join(sessions, "telegram", `telegram_${subject}.json`);
+        if ((0, node_fs_1.existsSync)(legacySession)) {
+            if ((0, node_fs_1.existsSync)(opaqueSession))
+                throw new Error("Telegram session file migration is ambiguous");
+            (0, node_fs_1.renameSync)(legacySession, opaqueSession);
+        }
+    }
+    const pending = migrateDirectory(path.join(agentRoot, "state", "pending"));
+    if (pending) {
+        const legacyPending = path.join(pending, "telegram", `telegram:${legacyChatId}`);
+        const opaquePending = path.join(pending, "telegram", `telegram:${subject}`);
+        if ((0, node_fs_1.existsSync)(legacyPending)) {
+            if ((0, node_fs_1.existsSync)(opaquePending))
+                throw new Error("Telegram pending identity migration is ambiguous");
+            (0, node_fs_1.renameSync)(legacyPending, opaquePending);
+        }
+    }
+    migrateDirectory(path.join(agentRoot, "state", "pending-returns"));
+}
+function redactTelegramPrivateValues(error, privateValues) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const privateValue of privateValues)
+        message = message.split(privateValue).join("[redacted]");
+    return message;
+}
+function parseTelegramSenseCredentials(value) {
+    return {
+        botToken: requiredText(value.telegramBotToken, "bot token"),
+        authorizedUserId: canonicalTelegramId(value.telegramAuthorizedUserId, "authorized user id"),
+        authorizedChatId: canonicalTelegramId(value.telegramAuthorizedChatId, "authorized chat id"),
+    };
+}
+function createTelegramSenseApp(options) {
+    const botToken = requiredText(options.credentials.botToken, "bot token");
+    const authorizedUserId = canonicalTelegramId(options.credentials.authorizedUserId, "authorized user id");
+    const authorizedChatId = canonicalTelegramId(options.credentials.authorizedChatId, "authorized chat id");
+    const agentRoot = options._agentRoot ?? (0, identity_1.getAgentRoot)(options.agentName);
+    const identityKey = options.identityKey === undefined
+        ? readOrCreateTelegramIdentityKey(agentRoot)
+        : canonicalTelegramIdentityKey(options.identityKey);
+    const subject = opaqueTelegramSubject(identityKey, botToken, authorizedUserId, authorizedChatId);
+    const transportError = (error) => redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId]);
+    const api = options.api ?? (0, telegram_client_1.createTelegramBotApi)({ token: botToken });
+    const offsetStore = options.offsetStore ?? new telegram_client_1.FileTelegramOffsetStore(path.join(agentRoot, "state", "senses", "telegram", "offset.json"));
+    const inboxStore = options.inboxStore ?? new telegram_client_1.FileTelegramUpdateInboxStore(path.join(agentRoot, "state", "senses", "telegram", "inbox.json"));
+    const runTurn = options.runTurn ?? options._runTurn ?? shared_turn_1.runSenseTurn;
+    const collectToolReceipts = options._runWithToolReceiptCollection ?? sanctuary_runtime_1.runWithSanctuaryToolReceiptCollection;
+    const useSanctuaryRuntime = options.agentName === "sanctuary" && !options.runTurn;
+    const readScenarioHandleDigest = () => (options.acceptanceMarker
+        ? options.acceptanceMarker()
+        : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName))?.scenarioHandleDigest;
+    let acceptanceAuditLease;
+    const retireAcceptanceAudit = () => {
+        const lease = acceptanceAuditLease;
+        if (!lease)
+            return;
+        const errors = [];
+        try {
+            lease.ledger.assertHealthy();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            lease.release();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        finally {
+            acceptanceAuditLease = undefined;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "Telegram acceptance audit retirement failed");
+    };
+    const ensureAcceptanceAudit = () => {
+        if (!useSanctuaryRuntime)
+            return undefined;
+        const scenarioHandleDigest = readScenarioHandleDigest();
+        const effectScenarioHandleDigest = telegramAcceptanceAuditScenario.getStore();
+        if (effectScenarioHandleDigest !== undefined && (scenarioHandleDigest ?? null) !== effectScenarioHandleDigest) {
+            const error = new Error("Telegram acceptance audit scenario ownership drift");
+            acceptanceAuditLease?.ledger.poison(error);
+            throw error;
+        }
+        if (scenarioHandleDigest === undefined) {
+            if (acceptanceAuditLease) {
+                retireAcceptanceAudit();
+            }
+            return undefined;
+        }
+        if (!/^[0-9a-f]{64}$/u.test(scenarioHandleDigest))
+            throw new Error("Telegram acceptance audit scenario handle is invalid");
+        if (!acceptanceAuditLease) {
+            acceptanceAuditLease = acquireTelegramAcceptanceAudit(options.acceptanceReceiptRoot ?? agentRoot, options.agentName, identityKey, [botToken, authorizedUserId, authorizedChatId], scenarioHandleDigest, options._acceptanceAuditReleaseHook, options._acceptanceAuditMaxBytes);
+        }
+        else if (scenarioHandleDigest !== acceptanceAuditLease.scenarioHandleDigest) {
+            retireAcceptanceAudit();
+            acceptanceAuditLease = acquireTelegramAcceptanceAudit(options.acceptanceReceiptRoot ?? agentRoot, options.agentName, identityKey, [botToken, authorizedUserId, authorizedChatId], scenarioHandleDigest, options._acceptanceAuditReleaseHook, options._acceptanceAuditMaxBytes);
+        }
+        return acceptanceAuditLease;
+    };
+    ensureAcceptanceAudit();
+    const acceptanceAuditBarrier = () => {
+        const lease = ensureAcceptanceAudit();
+        if (!lease)
+            return;
+        lease.ledger.assertHealthy();
+        lease.ledger.assertCapacity(8);
+    };
+    const runWithAcceptanceAuditOwner = async (operation) => {
+        const scenarioHandleDigest = readScenarioHandleDigest() ?? null;
+        return telegramAcceptanceAuditScenario.run(scenarioHandleDigest, async () => {
+            acceptanceAuditBarrier();
+            const ownerDigest = acceptanceAuditLease?.ownerDigest ?? "";
+            return telegramAcceptanceAuditOwner.run(ownerDigest, async () => {
+                try {
+                    const result = await operation();
+                    acceptanceAuditBarrier();
+                    return result;
+                }
+                catch (error) {
+                    try {
+                        acceptanceAuditBarrier();
+                    }
+                    catch (auditError) {
+                        if (error === auditError)
+                            throw auditError;
+                        throw new AggregateError([error, auditError], "Telegram effect and acceptance audit verification failed");
+                    }
+                    throw error;
+                }
+            });
+        });
+    };
+    const emitDurableSettlementEvidence = async (event, meta) => {
+        if (event === "telegram.callback_settled") {
+            await (0, runtime_1.emitNervesEventDurable)({
+                component: "senses",
+                event: "telegram.callback_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else if (event === "telegram.callback_recovery_settled") {
+            await (0, runtime_1.emitNervesEventDurable)({
+                component: "senses",
+                event: "telegram.callback_recovery_settled",
+                message: "Telegram approval acceptance evidence durably recorded",
+                meta,
+            });
+        }
+        else {
+            throw new Error("Telegram durable acceptance settlement event is unsupported");
+        }
+    };
+    const commitAcceptanceEvidence = useSanctuaryRuntime ? async (event, meta) => {
+        acceptanceAuditBarrier();
+        const lease = acceptanceAuditLease;
+        if (!lease) {
+            await emitDurableSettlementEvidence(event, meta);
+            return;
+        }
+        await telegramAcceptanceAuditExplicitCommit.run(true, async () => {
+            await emitDurableSettlementEvidence(event, meta);
+        });
+        acceptanceAuditBarrier();
+        lease.ledger.append({
+            ts: new Date().toISOString(),
+            level: "info",
+            event,
+            trace_id: (0, node_crypto_1.randomUUID)(),
+            component: "senses",
+            message: "Telegram approval acceptance evidence durably recorded",
+            meta,
+        });
+        lease.ledger.assertHealthy();
+    } : undefined;
+    const releaseAcceptanceAudit = (primaryError) => {
+        try {
+            acceptanceAuditLease?.release();
+        }
+        catch (releaseError) {
+            throw new AggregateError([primaryError, releaseError], "Telegram sense construction and audit release failed");
+        }
+        throw primaryError;
+    };
+    let toolContext;
+    let approvalRuntime;
+    let approvalTransport;
+    let interactiveControl;
+    try {
+        toolContext = useSanctuaryRuntime ? (options._toolContext ?? (0, sanctuary_runtime_1.createSanctuaryToolContext)(options.agentName)) : undefined;
+        approvalRuntime = options.approvalRuntime ?? (useSanctuaryRuntime ? (options._createApprovalRuntime ?? telegram_approval_runtime_1.createTelegramApprovalRuntime)({
+            agentName: options.agentName,
+            api,
+            authorizedUserId,
+            authorizedChatId,
+            subject,
+            identityKey,
+            toolContext: toolContext ?? {},
+            effectBarrier: acceptanceAuditBarrier,
+            dependencies: {
+                acceptanceMarker: () => {
+                    const scenarioHandleDigest = readScenarioHandleDigest();
+                    return scenarioHandleDigest ? { scenarioHandleDigest } : null;
+                },
+                commitAcceptanceEvidence,
+            },
+        }) : undefined);
+        approvalTransport = options.approvalTransport ?? approvalRuntime?.transport;
+        interactiveControl = useSanctuaryRuntime && approvalTransport
+            ? (options._createInteractiveControl ?? sanctuary_interactive_control_1.createSanctuaryInteractiveControl)({
+                agentRoot,
+                transport: approvalTransport,
+                authorizedUserId,
+                authorizedChatId,
+                runRequest: runWithAcceptanceAuditOwner,
+            })
+            : undefined;
+    }
+    catch (error) {
+        releaseAcceptanceAudit(error);
+    }
+    const healthSweep = options.healthSweep;
+    const migrateIdentity = options.migrateIdentity ?? (async () => {
+        const legacySubjects = new Set([
+            ...readTelegramSubjectIndex(agentRoot, subject),
+            ...discoverTelegramFilesystemSubjects(agentRoot),
+            ...(approvalRuntime?.legacySubjects?.() ?? []),
+        ]);
+        legacySubjects.delete(subject);
+        if (legacySubjects.size > 1)
+            throw new Error("Telegram legacy identity subject migration is ambiguous");
+        const migrationSubjects = [...legacySubjects];
+        for (const legacySubject of migrationSubjects) {
+            acceptanceAuditBarrier();
+            migrateTelegramSessionIdentity(agentRoot, legacySubject, legacySubject, subject);
+            acceptanceAuditBarrier();
+            await migrateTelegramFriendIdentity(agentRoot, legacySubject, subject);
+        }
+        acceptanceAuditBarrier();
+        migrateTelegramSessionIdentity(agentRoot, authorizedUserId, authorizedChatId, subject);
+        acceptanceAuditBarrier();
+        await migrateTelegramFriendIdentity(agentRoot, authorizedUserId, subject);
+        acceptanceAuditBarrier();
+        approvalRuntime?.migrateIdentity?.(migrationSubjects);
+        acceptanceAuditBarrier();
+        writeTelegramSubjectIndex(agentRoot, subject, migrationSubjects, options.subjectIndexHooks);
+    });
+    let approvalReconcileTimer;
+    let approvalReconciliationActive = false;
+    const approvalReconciliationsInFlight = new Set();
+    let nextApprovalReconcileDeadline;
+    let stopPromise;
+    let runPromise;
+    const clearApprovalReconcileTimer = () => {
+        if (approvalReconcileTimer)
+            clearTimeout(approvalReconcileTimer);
+        approvalReconcileTimer = undefined;
+    };
+    const scheduleApprovalReconcile = () => {
+        if (!approvalTransport || !approvalReconciliationActive)
+            return;
+        const scheduledAt = nextApprovalReconcileDeadline ?? (Date.now() + APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS);
+        nextApprovalReconcileDeadline = scheduledAt + APPROVAL_EXPIRY_RECONCILE_INTERVAL_MS;
+        const delay = Math.max(0, scheduledAt - Date.now());
+        approvalReconcileTimer = setTimeout(() => {
+            approvalReconcileTimer = undefined;
+            scheduleApprovalReconcile();
+            const reconciliation = runWithAcceptanceAuditOwner(() => approvalTransport.reconcileExpired()).catch((error) => {
+                acceptanceAuditBarrier();
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.telegram_approval_reconcile_error",
+                    message: "Telegram approval expiry reconciliation failed",
+                    meta: { agentName: options.agentName, subject, error: transportError(error) },
+                });
+            }).finally(() => {
+                approvalReconciliationsInFlight.delete(reconciliation);
+            });
+            approvalReconciliationsInFlight.add(reconciliation);
+        }, delay);
+    };
+    const runHealthSweep = async () => {
+        if (!healthSweep)
+            return;
+        try {
+            acceptanceAuditBarrier();
+            const result = await healthSweep();
+            if (result.message) {
+                acceptanceAuditBarrier();
+                if (result.deliveryId)
+                    await healthSweep.markDeliveryAttempting?.(result.deliveryId);
+                const messageIds = await deliver(result.message);
+                acceptanceAuditBarrier();
+                if (result.deliveryId)
+                    await healthSweep.markDelivered?.(result.deliveryId, messageIds);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.sanctuary_health_delivered",
+                    message: "Sanctuary health notification was delivered",
+                    meta: { agentName: options.agentName, deliveryCount: messageIds.length, ...(0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(options.agentName) },
+                });
+            }
+        }
+        catch (error) {
+            acceptanceAuditBarrier();
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.sanctuary_health_error",
+                message: "Sanctuary deterministic health sweep failed",
+                meta: { agentName: options.agentName, subject, error: transportError(error) },
+            });
+        }
+    };
+    const deliver = async (text, signal, onMessageDelivered) => {
+        acceptanceAuditBarrier();
+        return (0, telegram_client_1.sendTelegramText)(api, authorizedChatId, text, signal, onMessageDelivered);
+    };
+    const onMessageBody = async (message) => {
+        const acceptanceMarker = options.acceptanceMarker ? options.acceptanceMarker() : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName);
+        const acceptanceMeta = (0, sanctuary_acceptance_marker_1.sanctuaryAcceptanceEventMeta)(options.agentName);
+        const groundedAcceptance = acceptanceMarker?.label === "unit-16d-whats-up" || acceptanceMarker?.label === "unit-16d-1-space";
+        const acceptanceSchema = groundedAcceptance ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+        const auditDigest = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, acceptanceSchema, purpose, value);
+        const lifecycleCoordinates = acceptanceMarker ? {
+            scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest,
+            turnDigest: auditDigest("turn", `${message.updateId}\0${message.messageId}`),
+            updateDigest: auditDigest("update", `${message.updateId}\0${message.messageId}`),
+            subject,
+            identityDigest: auditDigest("identity", subject),
+            sessionDigest: auditDigest("session", `telegram:${subject}`),
+            argumentDigest: auditDigest("argument", message.text),
+        } : {};
+        const lifecycleStartedAt = Date.now();
+        const lifecycleMeta = (event, meta, lifecycleAt) => acceptanceMarker
+            ? { ...meta, lifecycleAt, lifecycleMac: sanctuaryTelegramAuditLifecycleMac(identityKey, acceptanceSchema, event, { ...meta, lifecycleAt }) }
+            : meta;
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.telegram_turn_start",
+            message: "Telegram authorized turn started",
+            meta: lifecycleMeta("senses.telegram_turn_start", { agentName: options.agentName, subject, ...acceptanceMeta, ...lifecycleCoordinates }, lifecycleStartedAt),
+        });
+        acceptanceAuditBarrier();
+        let deliveryCount = 0;
+        const deliveredMessageIds = [];
+        const deliveredChunks = [];
+        let receiptStatus = "success";
+        let errorCategory = null;
+        const turnMetricsObserver = { providerInvocationCount: 0, toolInvocationCount: 0 };
+        const toolReceiptObserver = { toolResultDigests: [], toolGroundings: [] };
+        const normalizedRequest = message.text.normalize("NFKC").trim().toLocaleLowerCase("en-US");
+        const groundingIntentTool = /^(?:what['’]?s up|status)\??$/u.test(normalizedRequest) ? "unraid_get_system"
+            : /^how much (?:space|storage) is left\??$/u.test(normalizedRequest) ? "unraid_get_storage"
+                : null;
+        const bufferedGroundedDeliveries = [];
+        try {
+            acceptanceAuditBarrier();
+            const collected = await collectToolReceipts(() => runTurn({
+                agentName: options.agentName,
+                channel: "telegram",
+                sessionKey: `telegram:${subject}`,
+                friendId: `telegram-user:${subject}`,
+                identity: {
+                    provider: "telegram-user",
+                    externalId: subject,
+                    displayName: `Telegram user ${subject}`,
+                },
+                userMessage: message.text,
+                turnMetricsObserver,
+                deliverySink: {
+                    onDelivery: async (delivery) => {
+                        if (groundingIntentTool) {
+                            bufferedGroundedDeliveries.push(delivery.kind);
+                        }
+                        else {
+                            await deliver(delivery.text, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                            deliveryCount += 1;
+                        }
+                    },
+                },
+                ...(toolContext ? { toolContext } : {}),
+                ...(approvalRuntime ? { approvalCoordinatorFactory: approvalRuntime.coordinator } : {}),
+            }), toolReceiptObserver);
+            const result = collected.result;
+            turnMetricsObserver.providerInvocationCount = Math.max(turnMetricsObserver.providerInvocationCount, result.providerInvocationCount ?? 0);
+            turnMetricsObserver.toolInvocationCount = Math.max(turnMetricsObserver.toolInvocationCount, result.toolInvocationCount ?? 0);
+            if (groundingIntentTool) {
+                const grounding = toolReceiptObserver.toolGroundings?.length === 1 ? toolReceiptObserver.toolGroundings[0] : undefined;
+                if (!grounding || grounding.toolName !== groundingIntentTool || bufferedGroundedDeliveries.length > 1
+                    || (bufferedGroundedDeliveries.length === 1 && bufferedGroundedDeliveries[0] !== "settle"))
+                    throw new Error("Canonical Sanctuary query did not produce exactly one matching grounded settle");
+                const canonical = (0, sanctuary_grounding_1.renderSanctuaryGroundedResponse)(grounding.toolName, grounding.facts);
+                await deliver(canonical, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+                deliveryCount = 1;
+            }
+            else if (deliveryCount === 0 && result.response.trim()) {
+                await deliver(result.response, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.telegram_turn_end",
+                message: "Telegram authorized turn completed",
+                meta: lifecycleMeta("senses.telegram_turn_end", { agentName: options.agentName, subject, deliveryCount: Math.max(deliveryCount, result.response.trim() ? 1 : 0), ...acceptanceMeta, ...lifecycleCoordinates, ...(acceptanceMarker ? { outcome: "success", errorDigest: null } : {}) }, Math.max(Date.now(), lifecycleStartedAt + 1)),
+            });
+        }
+        catch (error) {
+            receiptStatus = "error";
+            errorCategory = (error instanceof Error && error.name.trim() ? error.name : "unknown").slice(0, 128);
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.telegram_turn_error",
+                message: "Telegram authorized turn failed",
+                meta: lifecycleMeta("senses.telegram_turn_error", {
+                    agentName: options.agentName,
+                    subject,
+                    ...acceptanceMeta,
+                    ...lifecycleCoordinates,
+                    ...(acceptanceMarker ? {
+                        outcome: "error",
+                        errorDigest: auditDigest("error", redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId])),
+                        deliveryCount: deliveredMessageIds.length,
+                    } : { error: redactTelegramPrivateValues(error, [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId]) }),
+                }, Math.max(Date.now(), lifecycleStartedAt + 1)),
+            });
+            const fallback = "I couldn't complete that turn. The failure was recorded; please try again.";
+            if (deliveredMessageIds.length === 0)
+                await deliver(fallback, undefined, (messageId, chunk) => { deliveredMessageIds.push(messageId); deliveredChunks.push(chunk); });
+        }
+        finally {
+            if (acceptanceMarker) {
+                acceptanceAuditBarrier();
+                const grounded = groundedAcceptance;
+                const schemaVersion = grounded ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+                const hmac = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value);
+                const redact = (value) => [botToken, authorizedUserId, authorizedChatId, String(message.updateId), message.messageId]
+                    .reduce((text, privateValue) => privateValue.length >= 5 ? text.replaceAll(privateValue, "[REDACTED]") : text, value);
+                const deliveries = deliveredMessageIds.map((messageId, index) => {
+                    const chunk = deliveredChunks[index];
+                    const redactedText = redact(chunk);
+                    return { messageIdDigest: hmac("delivery", String(messageId)), chunkDigest: hmac("chunk", grounded ? redactedText : chunk), ...(grounded ? { redactedText, utf16Units: redactedText.length } : {}) };
+                });
+                try {
+                    const receipt = {
+                        schemaVersion,
+                        scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest,
+                        status: receiptStatus,
+                        errorCategory,
+                        updateDigest: hmac("update", `${message.updateId}\0${message.messageId}`),
+                        sequenceDigest: hmac("sequence", String(message.updateId)),
+                        responseDigest: hmac("response", JSON.stringify(deliveries)),
+                        toolResultDigests: toolReceiptObserver.toolResultDigests,
+                        ...(grounded ? { toolGroundings: toolReceiptObserver.toolGroundings } : {}),
+                        providerInvocationCount: turnMetricsObserver.providerInvocationCount,
+                        toolInvocationCount: turnMetricsObserver.toolInvocationCount,
+                        deliveryCount: deliveries.length,
+                        deliveries,
+                        completedAt: new Date().toISOString(),
+                    };
+                    if (grounded)
+                        receipt.receiptMac = sanctuaryTelegramTurnReceiptMac(identityKey, receipt);
+                    await appendSanctuaryTurnReceipt(options.acceptanceReceiptRoot ?? agentRoot, receipt, options._afterAcceptanceLedgerPreReadStat);
+                }
+                catch (error) {
+                    (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.telegram_acceptance_receipt_error", message: "Telegram acceptance receipt persistence failed", meta: { agentName: options.agentName, scenarioHandleDigest: acceptanceMarker.scenarioHandleDigest, category: error instanceof Error ? error.name : "unknown" } });
+                }
+            }
+        }
+    };
+    const onMessage = (message) => runWithAcceptanceAuditOwner(() => onMessageBody(message));
+    const onUpdate = async (update) => {
+        if (!update.callback_query || !approvalTransport)
+            return false;
+        return runWithAcceptanceAuditOwner(async () => (await approvalTransport.handleUpdate(update)).handled);
+    };
+    let poll;
+    try {
+        poll = (options.createLongPoll ?? telegram_client_1.createTelegramLongPoll)({
+            api,
+            expectedUserId: authorizedUserId,
+            expectedChatId: authorizedChatId,
+            offsetStore,
+            inboxStore,
+            onMessage,
+            onUpdate,
+            acceptanceEventMeta: (update, distinctAccount) => {
+                const marker = options.acceptanceMarker ? options.acceptanceMarker() : (0, sanctuary_acceptance_marker_1.readSanctuaryAcceptanceMarker)(options.agentName);
+                if (!marker)
+                    return {};
+                const auditOwnerMeta = acceptanceAuditLease ? { acceptanceAuditOwnerDigest: acceptanceAuditLease.ownerDigest } : {};
+                const messageId = update?.message?.message_id ?? update?.callback_query?.message?.message_id;
+                const senderId = update?.message?.from?.id;
+                if (!update || messageId === undefined || senderId === undefined)
+                    return { scenarioHandleDigest: marker.scenarioHandleDigest, ...auditOwnerMeta };
+                const schemaVersion = marker.label === "unit-16d-whats-up" || marker.label === "unit-16d-1-space"
+                    ? "sanctuary-telegram-turn-receipt-v4" : "sanctuary-telegram-turn-receipt-v3";
+                const digest = (purpose, value) => sanctuaryTelegramTurnReceiptDigest(identityKey, schemaVersion, purpose, value);
+                const senderDistinct = String(senderId) !== authorizedUserId;
+                if (distinctAccount !== senderDistinct)
+                    throw new Error("Telegram dropped-update identity classification mismatch");
+                const binding = {
+                    scenarioHandleDigest: marker.scenarioHandleDigest,
+                    updateDigest: digest("update", `${update.update_id}\0${messageId}`),
+                    senderIdentityDigest: digest("sender-identity", String(senderId)),
+                    authorizedIdentityDigest: digest("sender-identity", authorizedUserId),
+                    senderDistinct,
+                    nextOffsetDigest: digest("next-update-id", String(update.update_id + 1)),
+                };
+                return { ...binding, ...auditOwnerMeta, dropMac: sanctuaryTelegramUnauthorizedDropMac(identityKey, schemaVersion, binding) };
+            },
+            onBeforeDispatch: acceptanceAuditBarrier,
+            onDispatchSettled: acceptanceAuditBarrier,
+        });
+    }
+    catch (error) {
+        releaseAcceptanceAudit(error);
+    }
+    return {
+        run(signal) {
+            if (runPromise)
+                return runPromise;
+            runPromise = (async () => {
+                await runWithAcceptanceAuditOwner(migrateIdentity);
+                await runWithAcceptanceAuditOwner(async () => { await approvalRuntime?.recover(); });
+                await runWithAcceptanceAuditOwner(async () => { await interactiveControl?.start(); });
+                try {
+                    await runWithAcceptanceAuditOwner(async () => { await approvalTransport?.reconcileExpired(); });
+                }
+                catch (error) {
+                    acceptanceAuditBarrier();
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "senses",
+                        event: "senses.telegram_approval_reconcile_error",
+                        message: "Telegram approval expiry reconciliation failed",
+                        meta: { agentName: options.agentName, subject, error: transportError(error) },
+                    });
+                }
+                await runWithAcceptanceAuditOwner(runHealthSweep);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.telegram_poll_start",
+                    message: "Telegram long poll started",
+                    meta: { agentName: options.agentName, subject },
+                });
+                approvalReconciliationActive = true;
+                nextApprovalReconcileDeadline = undefined;
+                scheduleApprovalReconcile();
+                try {
+                    await poll.run(signal);
+                }
+                finally {
+                    approvalReconciliationActive = false;
+                    nextApprovalReconcileDeadline = undefined;
+                    clearApprovalReconcileTimer();
+                    await Promise.all([...approvalReconciliationsInFlight]);
+                    try {
+                        await runWithAcceptanceAuditOwner(async () => { await approvalTransport?.reconcileExpired(); });
+                    }
+                    catch (error) {
+                        acceptanceAuditBarrier();
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "error",
+                            component: "senses",
+                            event: "senses.telegram_approval_reconcile_error",
+                            message: "Telegram approval expiry reconciliation failed",
+                            meta: { agentName: options.agentName, subject, error: transportError(error) },
+                        });
+                    }
+                    await interactiveControl?.stop();
+                }
+            })();
+            return runPromise;
+        },
+        async sendProactive(text, signal) {
+            await runWithAcceptanceAuditOwner(() => deliver(requiredText(text, "proactive message"), signal));
+        },
+        stop() {
+            if (stopPromise)
+                return stopPromise;
+            stopPromise = (async () => {
+                const errors = [];
+                const attempt = async (operation) => {
+                    try {
+                        await operation();
+                    }
+                    catch (error) {
+                        errors.push(error);
+                    }
+                };
+                await attempt(() => poll.stop());
+                await attempt(async () => { await runPromise?.catch(() => undefined); });
+                await attempt(async () => { await Promise.all([...approvalReconciliationsInFlight]); });
+                await attempt(async () => { await interactiveControl?.stop(); });
+                await attempt(() => api.stop());
+                await attempt(() => approvalRuntime?.close());
+                await attempt(() => runWithAcceptanceAuditOwner(() => {
+                    (0, runtime_1.emitNervesEvent)({
+                        component: "senses",
+                        event: "senses.telegram_poll_end",
+                        message: "Telegram long poll stopped",
+                        meta: { agentName: options.agentName, subject },
+                    });
+                }));
+                await attempt(retireAcceptanceAudit);
+                if (errors.length === 1)
+                    throw errors[0];
+                if (errors.length > 1)
+                    throw new AggregateError(errors, "Telegram sense cleanup failed");
+            })();
+            return stopPromise;
+        },
+    };
+}
+function loadTelegramSenseCredentials(agentName) {
+    const runtime = (0, runtime_credentials_1.readRuntimeCredentialConfig)(agentName);
+    if (!runtime.ok) {
+        throw new Error(`Telegram runtime config is ${runtime.reason}; actor: agent-runnable; run ouro connect telegram --agent ${agentName}`);
+    }
+    return parseTelegramSenseCredentials(runtime.config);
+}
+async function startTelegramSenseApp(agentName) {
+    const app = createTelegramSenseApp({ agentName, credentials: loadTelegramSenseCredentials(agentName) });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.telegram_app_ready",
+        message: "Telegram sense app is ready",
+        meta: { agentName },
+    });
+    return app;
+}