📝 refine async failure helper docs

docs/api/async-logger-has-failed.md

@@ -2,8 +2,8 @@
 name: async-logger-has-failed
 group: api
 category: async
-update-time: 20260512
-description: Read whether the async logger worker has encountered a failure during queue drain.
+update-time: 20260614
+description: Read whether the async logger worker has recorded a runtime failure after run() startup reset and drain execution.
 key-word:
     - async
     - logger
@@ -34,6 +34,7 @@ pub fn[S] AsyncLogger::has_failed(self : AsyncLogger[S]) -> Bool {}
 Detailed rules explaining key parameters and behaviors
 
 - `run()` clears previous failure state at startup.
+- `run()` also clears the stored `last_error()` string at startup before drain work begins.
 - If the worker loop raises an error, the logger records that failure and exposes it through this flag.
 - This helper is intentionally compact and should usually be paired with `last_error()` for details.
 - Failure state is about runtime drain execution, not whether records were dropped due to overflow policy.
@@ -67,6 +68,8 @@ In this example, the helper exposes a simple pass-fail runtime indicator.
 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.
+
 - If `has_failed()` is `true`, callers should inspect `last_error()` or `state()` for more context.
 
 ### Notes
@@ -74,3 +77,5 @@ e.g.:
 1. This helper reports worker failure, not general queue stress.
 
 2. Pair it with `last_error()` when you need actionable detail.
+
+3. Pair it with `is_running()` or `state()` when you also need to know whether the worker has already exited and whether backlog remains.

docs/api/async-logger-is-running.md

@@ -2,8 +2,8 @@
 name: async-logger-is-running
 group: api
 category: async
-update-time: 20260512
-description: Read whether the async logger worker is currently running and draining the queue.
+update-time: 20260614
+description: Read whether the async logger worker loop is currently running, regardless of queue backlog or recorded failure state.
 key-word:
     - async
     - logger
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
 - The flag is cleared when the worker exits normally or after failure handling finishes.
 - A logger may be closed while still running briefly during final drain or shutdown processing.
 - This helper focuses on worker activity rather than queue size or failure details.
+- `is_running()` can be `false` even when `pending_count()` is still nonzero, for example if the worker was never started or if it exited after a recorded failure.
 
 ### How to Use
 
@@ -69,8 +70,12 @@ e.g.:
 
 - If callers need a one-shot lifecycle flow, `shutdown()` is usually better than manual polling.
 
+- If `is_running()` is `true`, that still does not guarantee healthy drain progress; callers may need `has_failed()` or `state()` for failure context.
+
 ### Notes
 
 1. Use this helper for worker activity checks, not as a complete health signal.
 
 2. Pair it with `has_failed()` or `state()` when diagnosing stalled pipelines.
+
+3. Pair it with `pending_count()` when you need to distinguish an idle worker from a stopped logger that still has backlog.

docs/api/async-logger-last-error.md

@@ -2,8 +2,8 @@
 name: async-logger-last-error
 group: api
 category: async
-update-time: 20260512
-description: Read the last error recorded by the async logger worker during runtime failure handling.
+update-time: 20260614
+description: Read the last error string recorded by the async logger worker after run() resets and runtime failure capture.
 key-word:
     - async
     - logger
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
 - If the worker loop fails, the error text is captured from the raised exception.
 - An empty string normally means no failure has been recorded.
 - This helper reports worker execution errors, not ordinary overflow or backpressure conditions.
+- A new successful `run()` attempt clears any previously stored error text before drain work begins again.
 
 ### How to Use
 
@@ -67,6 +68,8 @@ In this example, the helper provides the textual failure detail without building
 e.g.:
 - If no runtime failure has occurred, the method returns an empty string.
 
+- An empty string does not prove the queue is empty or the worker is idle; it only means no failure string is currently recorded.
+
 - If callers need broader context than just the error text, they should use `state()`.
 
 ### Notes
@@ -74,3 +77,5 @@ e.g.:
 1. Read this helper together with `has_failed()` when interpreting worker health.
 
 2. The stored value is a diagnostic string, not a typed error object.
+
+3. Pair it with `is_running()` or `pending_count()` when you need to know whether failure left the logger with unfinished backlog.