diff --git a/docs/security-scanning.md b/docs/security-scanning.md
index 74e39f29..e5e09d5d 100644
--- a/docs/security-scanning.md
+++ b/docs/security-scanning.md
@@ -138,7 +138,7 @@ Response fields include:
 - scan task retries are handled by `AbstractStreamConsumer`
 - scanner connection failures, HTTP 429, and HTTP 5xx remain pending for automatic recovery
 - unavailable tasks older than `max-unavailable-age` are marked `SCAN_FAILED`, acknowledged, and removed from the Redis Stream
-- the timeout is evaluated on the pending reclaim cadence, so terminal handling can occur up to one `reclaim-interval` after the configured age
+- the timeout is evaluated during pending reclaim; terminal handling can occur roughly one `reclaim-min-idle` plus one `reclaim-interval` after the configured age
 - terminal failures retain a failure reason in the security audit response for operators and authorized users
 - other final failures mark the version as `SCAN_FAILED` after retry exhaustion
 - even after scan failure, a review task is still created so the package does not get stuck forever
diff --git a/server/skillhub-app/src/main/java/com/iflytek/skillhub/stream/ScanTaskConsumer.java b/server/skillhub-app/src/main/java/com/iflytek/skillhub/stream/ScanTaskConsumer.java
index ff0e12e2..548b28be 100644
--- a/server/skillhub-app/src/main/java/com/iflytek/skillhub/stream/ScanTaskConsumer.java
+++ b/server/skillhub-app/src/main/java/com/iflytek/skillhub/stream/ScanTaskConsumer.java
@@ -131,11 +131,13 @@ public class ScanTaskConsumer extends AbstractStreamConsumer<ScanTaskConsumer.Sc
 
     @Override
     protected String finalFailureReason(ScanTaskPayload payload, Exception error, int retryCount) {
+        log.error("Security scan failed after retries: taskId={}, versionId={}, scanner={}, retryCount={}",
+                payload.taskId(), payload.versionId(), payload.scannerType(), retryCount, error);
         if (isScannerUnavailable(error) && hasUnavailableRecoveryExpired(payload)) {
             return "Security scanner did not recover before the configured timeout. "
                     + "Retry after scanner availability is restored.";
         }
-        return super.finalFailureReason(payload, error, retryCount);
+        return "Security scan failed after automatic retries. Retry the scan or contact an administrator.";
     }
 
     @Override
diff --git a/server/skillhub-app/src/test/java/com/iflytek/skillhub/stream/ScanTaskConsumerLoggingTest.java b/server/skillhub-app/src/test/java/com/iflytek/skillhub/stream/ScanTaskConsumerLoggingTest.java
index 50e73da8..3f295be1 100644
--- a/server/skillhub-app/src/test/java/com/iflytek/skillhub/stream/ScanTaskConsumerLoggingTest.java
+++ b/server/skillhub-app/src/test/java/com/iflytek/skillhub/stream/ScanTaskConsumerLoggingTest.java
@@ -222,6 +222,13 @@ class ScanTaskConsumerLoggingTest {
         @Override
         public void processScanResult(Long versionId, ScannerType scannerType, SecurityScanResponse response) {
         }
+
+        @Override
+        public void processScanFailure(String taskId,
+                                       Long versionId,
+                                       ScannerType scannerType,
+                                       String reason) {
+        }
     }
 
     private static final class TestProducer implements ScanTaskProducer {