📝 clarify async backlog docs

docs/api/async-logger-pending-count.md

@@ -2,8 +2,8 @@
 name: async-logger-pending-count
 group: api
 category: async
-update-time: 20260512
-description: Read the current number of queued records that have not yet been drained by the async logger worker.
+update-time: 20260614
+description: Read the current number of queued records that have not yet been drained or cleared from the async logger pipeline.
 key-word:
     - async
     - logger
@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 
 - The count increases when records are accepted into the queue.
 - The count decreases as the worker drains records.
+- The count is also reset to `0` when queued records are abandoned through clear-close paths such as `close(clear=true)`.
 - This is a point-in-time metric and may change immediately after it is read.
 - Use this helper when a single backlog number is enough and a full `state()` snapshot is unnecessary.
 
@@ -67,6 +68,8 @@ In this example, the queue backlog is checked directly.
 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.
+
 - If the queue is empty, the method simply returns `0`.
 
 ### Notes
@@ -74,3 +77,5 @@ e.g.:
 1. Use `state()` when you also need dropped counts, failure state, or runtime mode.
 
 2. This helper is useful for lightweight health checks and tests.
+
+3. Pair it with `is_running()` or `has_failed()` when backlog alone is not enough to explain whether the worker is actively draining, stopped, or failed.