CHANGELOG: mention openat2 retry loop changes

Signed-off-by: Aleksa Sarai <[email protected]>

Author: cyphar

CHANGELOG.md

@@ -19,6 +19,25 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   and distributors can then opt-in to using `libpathrs` for the entire binary
   if they wish.
 
+### Changed ###
+- `openat2` can return `-EAGAIN` if it detects a possible attack in certain
+  scenarios (namely if there was a rename or mount while walking a path with a
+  `..` component). While this is necessary to avoid a denial-of-service in the
+  kernel, it does require retry loops in userspace. In previous versions,
+  `pathrs-lite` would retry `openat2` 32 times before returning an error, but
+  we've received user reports that this limit can be hit on systems with very
+  heavy load. We have improved the situation in two ways:
+
+  * We have now increased this limit to 128, which should be good enough for
+    most use-cases without becoming a denial-of-service vector (the number of
+    syscalls called by the `O_PATH` resolver in a typical case is within the
+    same ballpark).
+
+  * In addition, we now return a `unix.EAGAIN` error that is bubbled up and can
+    be detected by callers. This means that callers with stricter requirements
+    to avoid spurious errors can choose to do their own infinite `EAGAIN` retry
+    loop.
+
 ## [0.5.0] - 2025-09-26 ##
 
 > Let the past die. Kill it if you have to.