diff --git a/docs/api/async-logger-has-failed.md b/docs/api/async-logger-has-failed.md
index a827acd..5886c1e 100644
--- a/docs/api/async-logger-has-failed.md
+++ b/docs/api/async-logger-has-failed.md
@@ -70,6 +70,7 @@ e.g.:
 - If `has_failed()` is `false`, queue pressure or dropped records may still exist for non-failure reasons.
 
 - If `has_failed()` becomes `true`, `wait_idle()` may stop early while pending records still remain until a later close or clear path handles them.
+- In the current regression coverage, that later handling can be an explicit `close(clear=true)` that resets pending backlog immediately or a runtime-dependent `shutdown(...)` path that either clears pending into dropped records or leaves the closed-queue remainder visible.
 
 - If `has_failed()` is `true`, callers should inspect `last_error()` or `state()` for more context.
 
diff --git a/docs/api/async-logger-pending-count.md b/docs/api/async-logger-pending-count.md
index eef1ac6..170dd6a 100644
--- a/docs/api/async-logger-pending-count.md
+++ b/docs/api/async-logger-pending-count.md
@@ -70,6 +70,7 @@ e.g.:
 - If the worker is not running, `pending_count()` may stay above `0` until records are drained or cleared.
 
 - If `wait_idle()` returns early because `has_failed()` became `true`, `pending_count()` may still be above `0` until later cleanup or clear-close handling runs.
+- In the current tested split, that later cleanup can either force the leftover pending item into `dropped_count()` on native-worker shutdown paths or leave the closed-queue remainder visible in `pending_count()` on compatibility shutdown paths.
 
 - If the queue is empty, the method simply returns `0`.
 
diff --git a/docs/api/async-logger-wait-idle.md b/docs/api/async-logger-wait-idle.md
index 0b2680f..5fab69a 100644
--- a/docs/api/async-logger-wait-idle.md
+++ b/docs/api/async-logger-wait-idle.md
@@ -71,6 +71,7 @@ e.g.:
 - If the worker was never started, or if nothing is making pending records decrease, `wait_idle()` can block indefinitely.
 
 - If callers need backlog cleanup after a failure-short-circuit, they still need a later `close(clear=true)` or `shutdown(...)` path.
+- In the current direct coverage, `wait_idle()` can return with `pending_count() > 0` after a worker failure, and the later cleanup path may either clear that backlog explicitly or follow the runtime-dependent shutdown split documented on `shutdown(...)`.
 
 ### Notes