~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
fix(notifications): map delivery failures to webhook_failed, invalid URLs to invalid_url (#5113)
LearningCircuit985f752d7059
diff --git a/changelog.d/5110.bugfix.md b/changelog.d/5110.bugfix.mdnew file mode 100644index 0000000000..ddc2562a01--- /dev/null+++ b/changelog.d/5110.bugfix.md@@ -0,0 +1,11 @@+Notification drop reasons are now accurate for delivery failures: a+webhook that actually fails (dead endpoint, HTTP error, network down)+is reported as `webhook_failed` instead of the generic `exception`,+and a service URL rejected before dispatch (unparseable, or blocked+by URL security validation) is reported as the new `invalid_url`+reason. `egress_denied` details now distinguish "policy refused every+URL" from "policy could not be evaluated" (including in the+test-notification endpoint), and the `server_disabled` detail no+longer claims the env var "is not set" when it is explicitly+disabled. `NotificationResult`/`NotificationReason` are exported from+the `notifications` package.diff --git a/docs/NOTIFICATIONS.md b/docs/NOTIFICATIONS.mdindex 77d40b4c89..fb04347461 100644--- a/docs/NOTIFICATIONS.md+++ b/docs/NOTIFICATIONS.md@@ -14,7 +14,7 @@ The notification system uses [Apprise](https://github.com/caronc/apprise) to sup> LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true> ```>-> Without this, every `send_notification` call returns `False` and the "Send Test Notification" button returns an error. This applies to **all** users on the deployment.+> Without this, every `send_notification` call returns a falsy `NotificationResult` (`reason=server_disabled`) and the "Send Test Notification" button returns an error. This applies to **all** users on the deployment.### Why?diff --git a/docs/NOTIFICATION_FLOW.md b/docs/NOTIFICATION_FLOW.mdindex 2c9483ff9f..22a3fab69f 100644--- a/docs/NOTIFICATION_FLOW.md+++ b/docs/NOTIFICATION_FLOW.md@@ -120,25 +120,25 @@ def _send_research_notification(- **Context Building**: Includes query, research_id, summary (truncated to 200 chars), full URL- **No Session Passed**: NotificationManager gets `settings_snapshot`, NOT session (thread-safe)-### 5. NotificationManager Checks Settings (`manager.py:91-126`)+### 5. NotificationManager Checks Settings (`manager.py`)```python-# src/local_deep_research/notifications/manager.py:91-126+# src/local_deep_research/notifications/manager.py (simplified)def send_notification(self,event_type: EventType,context: Dict[str, Any],- user_id: Optional[str] = None,force: bool = False,-) -> bool:+) -> NotificationResult:# Check if notifications are enabled for this event type- should_notify = self._should_notify(event_type, user_id)+ should_notify = self._should_notify(event_type)if not force and not should_notify:- logger.debug(f"Notifications disabled for event type: {event_type.value}")- return False+ return NotificationResult(+ sent=False, reason=NotificationReason.EVENT_DISABLED, detail="..."+ )# Check rate limit- rate_limit_ok = self._rate_limiter.allow(user_id or "default")+ rate_limit_ok = self._rate_limiter.is_allowed(self._user_id)if not force and not rate_limit_ok:raise RateLimitError("Notification rate limit exceeded")@@ -146,15 +146,24 @@ def send_notification(service_urls = self._get_setting("notifications.service_url", default="")if not service_urls or not service_urls.strip():- logger.debug("No notification service URLs configured")- return False+ return NotificationResult(+ sent=False, reason=NotificationReason.UNCONFIGURED, detail="..."+ )- # Send notification with service URLs- result = self.service.send_event(event_type, context, service_urls=service_urls)+ # Send notification with service URLs (egress-filtered)+ sent = self.service.send_event(event_type, context, service_urls=service_urls)- return result+ return NotificationResult(sent=sent, reason=..., detail=...)```+`send_notification` returns a `NotificationResult` dataclass (`sent`,+`reason`, `detail`). It is truthy iff the notification was sent, so+`if manager.send_notification(...):` keeps working. `reason` is a+`NotificationReason` enum: `sent`, `server_disabled`, `event_disabled`,+`unconfigured`, `egress_denied`, `invalid_url` (URL rejected before+dispatch — unparseable, or blocked by URL security validation),+`webhook_failed` (delivery failed after retries), or `exception`.+**Settings Checked (from `settings_snapshot`):**1. **`notifications.on_research_completed`** - Is this event type enabled? (default: False for most events)2. **Per-User Rate Limits** - Check shared rate limiter with user-specific limits:@@ -493,7 +502,7 @@ except SendError as e:```pythonresult = notification_manager.send_notification(...)-# Returns: False (no error raised)+# Returns: falsy NotificationResult (reason=unconfigured, no error raised)# Log: "No notification service URLs configured for user {user_id}"```diff --git a/src/local_deep_research/error_handling/error_reporter.py b/src/local_deep_research/error_handling/error_reporter.pyindex 585e69d179..be3c4b4001 100644--- a/src/local_deep_research/error_handling/error_reporter.py+++ b/src/local_deep_research/error_handling/error_reporter.py@@ -350,7 +350,8 @@ class ErrorReporter:)detail = getattr(result, "detail", "") or ""if reason_value is None:- reason_value = "dropped" if not bool(result) else "sent"+ # Legacy bool-returning mocks/callers carry no reason.+ reason_value = "dropped"message = (f"{reason_value}: {detail}" if detail else reason_value)diff --git a/src/local_deep_research/notifications/__init__.py b/src/local_deep_research/notifications/__init__.pyindex 595e4dfee9..33bbf251e0 100644--- a/src/local_deep_research/notifications/__init__.py+++ b/src/local_deep_research/notifications/__init__.py@@ -15,7 +15,11 @@ from .exceptions import (RateLimitError,)from .service import NotificationService-from .manager import NotificationManager+from .manager import (+ NotificationManager,+ NotificationReason,+ NotificationResult,+)from .templates import NotificationTemplate, EventTypefrom .url_builder import build_notification_urlfrom ..security.url_validator import URLValidator, URLValidationError@@ -34,6 +38,8 @@ __all__ = ["RateLimitError","NotificationService","NotificationManager",+ "NotificationReason",+ "NotificationResult","NotificationTemplate","EventType","build_notification_url",diff --git a/src/local_deep_research/notifications/exceptions.py b/src/local_deep_research/notifications/exceptions.pyindex 1edc27b9d8..e5c4e4d0f1 100644--- a/src/local_deep_research/notifications/exceptions.py+++ b/src/local_deep_research/notifications/exceptions.py@@ -15,6 +15,22 @@ class ServiceError(NotificationError):pass+class SecurityBlockError(ServiceError):+ """A confirmed send-time SSRF/DNS-rebind block.++ Raised instead of the plain ``ServiceError`` used for pre-dispatch URL+ validation rejects. It is a ``ServiceError`` subclass so every existing+ ``except ServiceError`` / ``pytest.raises(ServiceError)`` still catches+ it and the non-transient INVALID_URL classification is unchanged — this+ subclass exists only so callers that want to tell "malformed/blocked+ URL at validation time" apart from "destination confirmed hostile at+ send time" (e.g. to pick a more accurate user-facing message) can do so+ without parsing exception text.+ """++ pass++class SendError(NotificationError):"""Error occurred while sending a notification."""diff --git a/src/local_deep_research/notifications/manager.py b/src/local_deep_research/notifications/manager.pyindex 397563c66d..bc2363967b 100644--- a/src/local_deep_research/notifications/manager.py+++ b/src/local_deep_research/notifications/manager.py@@ -16,7 +16,12 @@ from ..security.ssrf_validator import redact_url_for_logfrom ..settings.env_registry import get_env_settingfrom .service import NotificationServicefrom .templates import EventType-from .exceptions import RateLimitError+from .exceptions import (+ RateLimitError,+ SendError,+ ServiceError,+ SecurityBlockError,+)from ..utilities.type_utils import unwrap_settingfrom ..constants import DEFAULT_SEARCH_TOOL@@ -38,6 +43,7 @@ class NotificationReason(str, Enum):EVENT_DISABLED = "event_disabled"UNCONFIGURED = "unconfigured"EGRESS_DENIED = "egress_denied"+ INVALID_URL = "invalid_url"WEBHOOK_FAILED = "webhook_failed"EXCEPTION = "exception"@@ -262,7 +268,10 @@ class NotificationManager:return NotificationResult(sent=False,reason=NotificationReason.SERVER_DISABLED,- detail="LDR_NOTIFICATIONS_ALLOW_OUTBOUND is not set",+ detail=(+ "outbound notifications are disabled at the server "+ "level (LDR_NOTIFICATIONS_ALLOW_OUTBOUND)"+ ),)# Check if notifications are enabled for this event type@@ -317,15 +326,24 @@ class NotificationManager:# scopes pass plugin schemes to the service's URL validator.allowed_urls = self._filter_urls_by_egress_policy(service_urls)if not allowed_urls:+ # Distinguish "the policy was evaluated and refused every+ # URL" (empty string) from "the policy itself could not be+ # evaluated and we failed closed" (None) so the operator+ # fixes the right thing — see issue #5110.+ if allowed_urls is None:+ detail = "egress policy could not be evaluated"+ else:+ detail = "all configured URLs refused by egress policy"logger.bind(policy_audit=True).warning(- "all notification URLs refused by egress policy",+ "notification dropped: {}",+ detail,user=self._user_id,event=event_type.value,)return NotificationResult(sent=False,reason=NotificationReason.EGRESS_DENIED,- detail="all configured URLs refused by egress policy",+ detail=detail,)# Send notification with the allowed subset.@@ -346,23 +364,107 @@ class NotificationManager:reason=NotificationReason.SENT,detail="",)+ # A falsy return from send_event means Apprise accepted none+ # of the URLs (temp_apprise.add() failed — unparseable or+ # unsupported scheme). Actual delivery failures raise+ # SendError and are handled below — see issue #5110.logger.warning(f"Notification failed: {event_type.value} to user "+ f"{self._user_id} — Apprise accepted none of the "+ f"configured service URLs"+ )+ return NotificationResult(+ sent=False,+ reason=NotificationReason.INVALID_URL,+ detail="Apprise accepted none of the configured service URLs",+ )++ except SendError:+ # The delivery layer raises SendError ONLY from+ # _send_with_retry's own terminal raise once all retries are+ # exhausted (dead webhook, HTTP 4xx/5xx, network down) — a+ # transient, worth-retrying failure. NotificationService.send()+ # re-raises SendError unchanged (no re-wrapping) and does NOT+ # launder incidental/unexpected dispatch-time exceptions into+ # SendError — those fall through to the generic+ # ``except Exception`` branch below and get the EXCEPTION+ # reason instead, so this branch stays reserved for genuine+ # delivery failures. It also specifically does NOT mean a+ # confirmed SSRF/DNS-rebind block: NotificationService.send()+ # routes that non-retryable case through ServiceError instead+ # (see the except clause below) precisely so it is never+ # mislabeled as a retryable webhook failure here. Keep the+ # detail static — SendError's message wraps the underlying+ # error, which may contain webhook URLs with embedded tokens.+ logger.exception(+ f"Webhook delivery failed for {event_type.value} to user "f"{self._user_id}")return NotificationResult(sent=False,reason=NotificationReason.WEBHOOK_FAILED,- detail="Apprise dispatch returned False",+ detail="webhook delivery failed after retries",+ )++ except SecurityBlockError:+ # A ServiceError subclass NotificationService.send() raises+ # specifically for a confirmed send-time SSRF/DNS-rebind block+ # (destination resolved to an internal/private/metadata+ # address after dispatch started) — as opposed to the plain+ # ServiceError below, raised for a pre-dispatch validation+ # reject. Both are permanent, invalid-destination outcomes+ # that map to the same non-transient INVALID_URL reason, but+ # this one gets a distinct detail: the generic "check your+ # URL/settings" text below would misleadingly suggest a+ # config mistake when the true cause is an active security+ # block. Static detail — no URL or resolved IP — the+ # exception message can echo parts of the URL.+ logger.exception(+ f"Notification destination blocked by SSRF/egress "+ f"protection for {event_type.value} to user "+ f"{self._user_id}"+ )+ return NotificationResult(+ sent=False,+ reason=NotificationReason.INVALID_URL,+ detail=(+ "notification destination blocked by egress/SSRF protection"+ ),+ )++ except ServiceError:+ # The service raises ServiceError when the URL security+ # validator rejects a URL before any dispatch is attempted+ # (structurally invalid URLs, or valid URLs whose destination+ # is blocked, e.g. a LAN webhook without+ # LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS). A confirmed send-time+ # SSRF/DNS-rebind block is caught above as SecurityBlockError+ # (a ServiceError subclass) before reaching this branch. The+ # detail must not claim the URL itself is malformed. Static+ # detail: the exception message can echo parts of the URL.+ logger.exception(+ f"Service URL rejected for {event_type.value} to user "+ f"{self._user_id}"+ )+ return NotificationResult(+ sent=False,+ reason=NotificationReason.INVALID_URL,+ detail=(+ "service URL rejected by URL security validation "+ "(for a private/LAN webhook, check "+ "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS)"+ ),)except Exception as exc:- # The exception string may contain webhook URLs with embedded- # tokens, SMTP credentials, or payload content. Log the raw- # exception for operators via logger.exception above, but only- # expose the exception class name (and not the message) in the- # structured result so downstream callers can't echo it into- # logs or UI surfaces verbatim.+ # Reached for unexpected failures anywhere in the block above+ # (settings read, egress filtering, or dispatch). The exception+ # string may contain webhook URLs with embedded tokens, SMTP+ # credentials, or payload content. Log the raw exception for+ # operators via logger.exception, but only expose the exception+ # class name (and not the message) in the structured result so+ # downstream callers can't echo it into logs or UI surfaces+ # verbatim.logger.exception(f"Error sending notification for {event_type.value} to user "f"{self._user_id}"@@ -370,7 +472,7 @@ class NotificationManager:return NotificationResult(sent=False,reason=NotificationReason.EXCEPTION,- detail=f"dispatch raised {type(exc).__name__}",+ detail=f"unexpected {type(exc).__name__} while sending",)def test_service(self, url: str) -> Dict[str, Any]:@@ -386,6 +488,16 @@ class NotificationManager:# Egress policy precheck before forwarding to Apprise.# /api/notifications/test-url is a user-supplied URL endpoint.allowed = self._filter_urls_by_egress_policy(url)+ if allowed is None:+ # Fail-closed: the policy could not be evaluated at all, so+ # don't tell the user their scope refused the URL.+ return {+ "status": "error",+ "message": (+ "Egress policy could not be evaluated; check the "+ "egress policy settings (policy.egress_scope)."+ ),+ }if not allowed:return {"status": "error",@@ -396,12 +508,16 @@ class NotificationManager:}return self.service.test_service(allowed)- def _filter_urls_by_egress_policy(self, service_urls: str) -> str:+ def _filter_urls_by_egress_policy(self, service_urls: str) -> Optional[str]:"""Filter an Apprise URL string by the user's egress policy.Commas inside one service URL are preserved; commas or whitespace- followed by another scheme delimit URLs. When no snapshot / context is- available, return the input unchanged for backwards compatibility.+ followed by another scheme delimit URLs. Returns the joined string+ of allowed URLs (may be empty — every URL was refused), or ``None``+ when the policy itself could not be evaluated and we failed closed.+ Both are falsy; callers that care why nothing was allowed check for+ ``None``. When no snapshot / context is available, returns the+ input unchanged for backwards compatibility."""snapshot = getattr(self, "_settings_snapshot", None)if not snapshot:@@ -453,7 +569,7 @@ class NotificationManager:"not be evaluated",reason=str(exc),)- return ""+ return None# Apprise accepts space- or comma-separated URLs and has non-HTTP# schemes (discord://, slack://, tgram://, mailto://, msteams://,diff --git a/src/local_deep_research/notifications/queue_helpers.py b/src/local_deep_research/notifications/queue_helpers.pyindex 82b2b09a7c..7fc6a53afc 100644--- a/src/local_deep_research/notifications/queue_helpers.py+++ b/src/local_deep_research/notifications/queue_helpers.py@@ -70,6 +70,11 @@ def send_queue_notification(context=context,)if not result:+ # DEBUG on purpose: notifications.on_research_queued defaults+ # to off, so this drop is the steady state for every queued+ # research — WARNING here would spam once per submission.+ # Actionable causes (server gate, delivery failure) already+ # WARN inside send_notification itself.logger.debug(f"Queue notification not sent for {research_id} "f"{_format_reason(result)}"@@ -131,6 +136,10 @@ def send_queue_failed_notification(context=context,)if not result:+ # DEBUG on purpose: the from_session wrapper around this+ # helper already emits its own WARNING on a falsy return, so+ # a WARNING here would double-log every drop. The reason+ # string is still available at debug level.logger.debug(f"Failed-notification not sent for {research_id} "f"{_format_reason(result)}"diff --git a/src/local_deep_research/notifications/service.py b/src/local_deep_research/notifications/service.pyindex 4562e593b1..4a9aa14986 100644--- a/src/local_deep_research/notifications/service.py+++ b/src/local_deep_research/notifications/service.py@@ -17,7 +17,7 @@ from tenacity import (retry_if_not_exception_type,)-from .exceptions import ServiceError, SendError+from .exceptions import ServiceError, SendError, SecurityBlockErrorfrom .apprise_log_utils import install_apprise_log_record_factoryfrom .templates import EventType, NotificationTemplatefrom ..security import dns_pinning@@ -178,17 +178,22 @@ class NotificationService:``?redirect=yes`` cannot override the asset-level default.Raises:- RuntimeError: if either invariant is violated (excluded from- Tenacity retries so it fails fast).+ SecurityBlockError: if either invariant is violated — a+ deliberate fail-closed security refusal, not an incidental+ runtime error, so it is raised directly as this type+ (rather than a generic ``RuntimeError`` a caller would have+ to re-classify) and is excluded from Tenacity retries so it+ fails fast. See ``send()``'s docstring for why this must+ not be mistaken for a transient delivery failure."""if getattr(apprise_instance.asset, "async_mode", True) is True:- raise RuntimeError(+ raise SecurityBlockError("Guarded notification send requires async_mode=False; ""refusing to send (the thread-local DNS pin/block would not ""apply to Apprise's worker-thread fan-out).")if tag is not None:- raise RuntimeError(+ raise SecurityBlockError("Guarded notification send does not support tag targeting; ""refusing to send (a tag can fan delivery out to worker ""threads that bypass the thread-local DNS pin/block)."@@ -322,11 +327,17 @@ class NotificationService:# Retry transient delivery failures (SendError, connection errors,# …) but NOT deliberate security refusals: a ValueError is a# connect-time SSRF block (the pin's rebind-to-private/metadata catch,- # or the block-private window's send-time refusal surfaced below) and- # a RuntimeError is a fail-closed invariant violation (shim not- # installed, async_mode/tag guard). A confirmed-malicious or+ # or the block-private window's send-time refusal surfaced below); a+ # RuntimeError (specifically+ # ``dns_pinning.NotificationGuardUnavailableError``) is the DNS-pin+ # shim not being installed; and a SecurityBlockError is the+ # async_mode/tag fail-closed invariant guard+ # (``_enforce_guarded_send_invariants``), raised directly as that+ # type rather than a generic RuntimeError. A confirmed-malicious or# misconfigured destination must fail fast, not be retried 3x.- retry=retry_if_not_exception_type((ValueError, RuntimeError)),+ retry=retry_if_not_exception_type(+ (ValueError, RuntimeError, SecurityBlockError)+ ),reraise=True,)def _send_with_retry(@@ -363,6 +374,13 @@ class NotificationService:window refused a send-time resolution as an SSRF target —a confirmed security block, raised non-retryably so it failsfast instead of being retried.+ SecurityBlockError: Propagated non-retryably from+ ``_guarded_notify`` -> ``_enforce_guarded_send_invariants``+ if the async_mode/tag fail-closed invariant is violated.+ dns_pinning.NotificationGuardUnavailableError: Propagated+ non-retryably (a ``RuntimeError`` subclass) from+ ``_guarded_notify`` -> ``guard_factory`` if the DNS-pin+ shim is not installed."""logger.debug(f"Sending notification: title='{title[:50]}...', tag={tag}"@@ -423,7 +441,16 @@ class NotificationService:True if notification was sent successfully to at least one serviceRaises:- SendError: If sending fails after all retry attempts+ SendError: If sending fails after all retry attempts (transient+ — the endpoint refused/failed the dispatch).+ SecurityBlockError: If a send-time SSRF/DNS-rebind block+ confirmed the destination is internal/private/metadata+ (permanent — not worth retrying). A ``ServiceError``+ subclass — it still satisfies ``except ServiceError`` /+ ``pytest.raises(ServiceError)`` and shares the same+ non-retryable signal as pre-dispatch validation rejects,+ but is tagged distinctly so callers can give it a more+ accurate message than "invalid URL".Note:Temporary Apprise instances are created for each send operation@@ -491,12 +518,89 @@ class NotificationService:)return False- except Exception as e:- # Tenacity will retry, but if all retries fail, raise SendError+ except SecurityBlockError:+ # _enforce_guarded_send_invariants (called from _guarded_notify,+ # which _send_with_retry / _dispatch call) raises this DIRECTLY+ # — not a generic RuntimeError — for the async_mode/tag+ # fail-closed invariant guard: a deliberate security refusal,+ # not an incidental runtime error. It is already the precise,+ # final exception type (see its docstring), so propagate it+ # unchanged rather than re-wrapping: NotificationManager's+ # ``except SecurityBlockError`` maps it to the same+ # non-transient INVALID_URL reason as the confirmed-block paths+ # below.+ raise++ except ValueError as e:+ # _send_with_retry raises ValueError (excluded from Tenacity's+ # retry predicate) ONLY for a confirmed, non-retryable send-time+ # SSRF/DNS-rebind block — see its docstring and+ # dns_pinning.pinned_notification_send's own rebind catch. That+ # is a permanent, invalid-destination outcome, not a transient+ # delivery failure, so it must NOT be re-wrapped as SendError:+ # NotificationManager's ``except SendError`` maps to the+ # retryable WEBHOOK_FAILED reason, which would mislabel a+ # confirmed security block as "webhook delivery failed after+ # retries" and could invite a caller/monitor to retry a+ # malicious/rebinding destination. Route it through+ # SecurityBlockError — a ServiceError subclass, so it still+ # maps to INVALID_URL via NotificationManager's existing+ # ``except ServiceError`` handling — but tagged distinctly so+ # the manager can give this confirmed security block a more+ # accurate user-facing detail than the pre-dispatch+ # "check your URL/settings" text (see manager.py).logger.exception(- f"Failed to send notification after retries: '{title[:50]}...'"+ f"Notification send blocked (SSRF/DNS-rebind): "+ f"'{title[:50]}...'")- raise SendError(f"Failed to send notification: {str(e)}")+ raise SecurityBlockError(str(e)) from e++ except dns_pinning.NotificationGuardUnavailableError as e:+ # pinned_notification_send (via the guard_factory _dispatch+ # builds) raises this — a RuntimeError subclass defined in+ # security.dns_pinning, deliberately NOT imported/raised as a+ # notifications exception there so that general-purpose+ # security module stays free of a dependency on this+ # higher-level package — when the getaddrinfo shim it depends+ # on is not the active resolver. Also a deliberate fail-closed+ # security refusal, not a transient send failure (excluded from+ # Tenacity's retry predicate as a RuntimeError — see+ # _send_with_retry's decorator), so route it through+ # SecurityBlockError for the same reason as the ValueError+ # branch above: it must not be mislabeled as a retryable+ # WEBHOOK_FAILED.+ logger.exception(+ f"Notification send blocked (DNS-pin guard unavailable): "+ f"'{title[:50]}...'"+ )+ raise SecurityBlockError(str(e)) from e++ except SendError:+ # _send_with_retry's own terminal raise (line ~420, once all+ # retries are exhausted) is already the precise, final+ # exception for a confirmed webhook delivery failure.+ # Propagate unchanged — re-wrapping it here would just nest a+ # second SendError around the first for no benefit, and+ # routing it through the catch-all below would make it+ # indistinguishable from an incidental dispatch-time bug.+ raise++ except Exception:+ # Anything else reaching here is an incidental/unexpected+ # error from the dispatch machinery itself (e.g. a bug in+ # this method's call wiring, an Apprise internals exception+ # that isn't a genuine delivery failure) — NOT a confirmed+ # webhook delivery failure. Do NOT launder it into SendError:+ # NotificationManager maps SendError to the retryable+ # WEBHOOK_FAILED reason, which would mislabel an incidental+ # bug as "webhook delivery failed after retries" and would+ # make the manager's own ``except Exception`` -> EXCEPTION+ # branch unreachable for dispatch-time errors. Let it+ # propagate as-is so the manager's catch-all handles it.+ logger.exception(+ f"Unexpected error sending notification: '{title[:50]}...'"+ )+ raisedef _dispatch(self,diff --git a/src/local_deep_research/security/dns_pinning.py b/src/local_deep_research/security/dns_pinning.pyindex 13949bd16c..015ef2af01 100644--- a/src/local_deep_research/security/dns_pinning.py+++ b/src/local_deep_research/security/dns_pinning.py@@ -734,6 +734,30 @@ def pin_hosts(pins.pop(host, None)+class NotificationGuardUnavailableError(RuntimeError):+ """The DNS-pin shim required for a guarded notification send is not+ installed as the active ``socket.getaddrinfo`` resolver.++ Raised ONLY by :func:`pinned_notification_send` (never by+ :func:`pinned_request`, the general-purpose safe_get/safe_post guard,+ which does not depend on this pre-check). This is a deliberate+ fail-closed SECURITY REFUSAL, not an incidental runtime error: the+ pin/block-private window cannot be guaranteed without the shim, so the+ send is refused outright.++ Subclasses ``RuntimeError`` (not just ``Exception``) so any code that+ still generically catches ``RuntimeError`` around a guarded send+ continues to behave the same. It is a dedicated subclass — rather than+ a bare ``RuntimeError`` — so ``notifications.service`` can catch this+ specific refusal and re-raise it as its own ``SecurityBlockError``+ (non-retryable, INVALID_URL classification) without this general+ security module importing exception types from the higher-level+ ``notifications`` package (which would invert the module layering and+ risk a circular import — ``notifications.service`` imports this+ module).+ """++@contextlib.contextmanagerdef pinned_notification_send(urls,@@ -764,16 +788,18 @@ def pinned_notification_send(and the block-private window.Raises:- RuntimeError: if the ``getaddrinfo`` shim is not the active resolver- (see :func:`_shim_installed`). The pin/block cannot be- guaranteed in that state, so the send is REFUSED (fail closed)- rather than proceeding unguarded.+ NotificationGuardUnavailableError: if the ``getaddrinfo`` shim is not+ the active resolver (see :func:`_shim_installed`). The+ pin/block cannot be guaranteed in that state, so the send is+ REFUSED (fail closed) rather than proceeding unguarded. A+ ``RuntimeError`` subclass — see its docstring for why it is+ not a bare ``RuntimeError``."""# Fail closed if our shim is not installed: without it the pin registry# and the block-private window are never consulted, so proceeding would# send completely unguarded (silent fail-open). Refuse instead.if not _shim_installed():- raise RuntimeError(+ raise NotificationGuardUnavailableError("DNS pin shim is not the active socket.getaddrinfo; refusing the ""notification send (fail closed). The resolve-vs-connect pin and ""block-private window cannot be guaranteed — see "diff --git a/tests/error_handling/test_error_reporter.py b/tests/error_handling/test_error_reporter.pyindex 28cc394dda..879a35d8c3 100644--- a/tests/error_handling/test_error_reporter.py+++ b/tests/error_handling/test_error_reporter.py@@ -389,23 +389,24 @@ class TestSendErrorNotifications:"""When the notification is dropped, the debug log must show the``reason.value`` string (``unconfigured``) — not the enum repr(``NotificationReason.UNCONFIGURED``) — and must include the- operator-facing ``detail`` so the cause is visible. See PR #5082.+ operator-facing ``detail`` so the cause is visible. Uses the real+ ``NotificationResult`` so the assertion is falsifiable against+ the real enum's rendering (issue #5110). See PR #5082."""+ from local_deep_research.notifications.manager import (+ NotificationReason,+ NotificationResult,+ )- class FakeReason:- value = "unconfigured"-- class FakeResult:- sent = False- detail = "notifications.service_url is not configured"- reason = FakeReason()-- def __bool__(self) -> bool:- return self.sent+ result = NotificationResult(+ sent=False,+ reason=NotificationReason.UNCONFIGURED,+ detail="notifications.service_url is not configured",+ )with loguru_caplog.at_level("DEBUG"):self._run_notification_dropped(- error_reporter, mock_context_with_username, FakeResult()+ error_reporter, mock_context_with_username, result)messages = [rec.message for rec in loguru_caplog.records]@@ -423,21 +424,20 @@ class TestSendErrorNotifications:"""When detail is empty, the debug log must still show the reasonvalue without trailing colon whitespace."""+ from local_deep_research.notifications.manager import (+ NotificationReason,+ NotificationResult,+ )- class FakeReason:- value = "event_disabled"-- class FakeResult:- sent = False- detail = ""- reason = FakeReason()-- def __bool__(self) -> bool:- return self.sent+ result = NotificationResult(+ sent=False,+ reason=NotificationReason.EVENT_DISABLED,+ detail="",+ )with loguru_caplog.at_level("DEBUG"):self._run_notification_dropped(- error_reporter, mock_context_with_username, FakeResult()+ error_reporter, mock_context_with_username, result)debug_lines = [@@ -448,3 +448,21 @@ class TestSendErrorNotifications:assert len(debug_lines) == 1, debug_linesassert debug_lines[0].endswith("event_disabled")assert "NotificationReason." not in debug_lines[0]++ def test_logs_dropped_for_legacy_bool_result(+ self, error_reporter, mock_context_with_username, loguru_caplog+ ):+ """A legacy bool ``False`` (older callers / mocks) carries no+ reason — the fallback must log a plain ``dropped``."""+ with loguru_caplog.at_level("DEBUG"):+ self._run_notification_dropped(+ error_reporter, mock_context_with_username, False+ )++ debug_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Error notification not sent" in rec.message+ ]+ assert len(debug_lines) == 1, debug_lines+ assert debug_lines[0].endswith("dropped")diff --git a/tests/notifications/test_manager.py b/tests/notifications/test_manager.pyindex bd24d06b16..b090958e07 100644--- a/tests/notifications/test_manager.py+++ b/tests/notifications/test_manager.py@@ -13,7 +13,12 @@ from local_deep_research.notifications.manager import (NotificationResult,)from local_deep_research.notifications.templates import EventType-from local_deep_research.notifications.exceptions import RateLimitError+from local_deep_research.notifications.exceptions import (+ RateLimitError,+ SecurityBlockError,+ SendError,+ ServiceError,+)class TestNotificationManagerInit:@@ -451,6 +456,15 @@ class TestNotificationResultSemantics:result with a distinct :class:`NotificationReason` (issue #4877)."""+ @pytest.fixture(autouse=True)+ def _fresh_rate_limiter(self):+ """Tests here share user_id "u"; isolate them from the shared+ class-level limiter so ordering / xdist cannot trip+ RateLimitError (issue #5110)."""+ NotificationManager._shared_rate_limiter = None+ yield+ NotificationManager._shared_rate_limiter = None+def test_result_is_truthy_when_sent(self):r = NotificationResult(sent=True, reason=NotificationReason.SENT, detail=""@@ -474,6 +488,7 @@ class TestNotificationResultSemantics:assert NotificationReason.EVENT_DISABLED.value == "event_disabled"assert NotificationReason.UNCONFIGURED.value == "unconfigured"assert NotificationReason.EGRESS_DENIED.value == "egress_denied"+ assert NotificationReason.INVALID_URL.value == "invalid_url"assert NotificationReason.WEBHOOK_FAILED.value == "webhook_failed"assert NotificationReason.EXCEPTION.value == "exception"@@ -555,7 +570,34 @@ class TestNotificationResultSemantics:assert result.reason is NotificationReason.EGRESS_DENIEDassert "egress" in result.detail- def test_webhook_failed(self, mocker):+ def test_egress_policy_unevaluable(self, mocker):+ """Policy exists but cannot be evaluated (filter fails closed,+ returning None) → still ``egress_denied``, but the detail must+ say the policy was unevaluable, not that it refused the URLs+ (issue #5110)."""+ snapshot = {+ "notifications.service_url": "discord://x",+ "notifications.on_research_completed": True,+ }+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ with patch.object(+ manager,+ "_filter_urls_by_egress_policy",+ return_value=None,+ ):+ result = manager.send_notification(+ event_type=EventType.RESEARCH_COMPLETED,+ context={"query": "q"},+ force=True,+ )+ assert result.reason is NotificationReason.EGRESS_DENIED+ assert "could not be evaluated" in result.detail+ assert "refused" not in result.detail++ def test_invalid_url_when_apprise_accepts_no_urls(self, mocker):+ """A falsy return from ``send_event`` means Apprise rejected the+ URL string at parse time (dispatch never attempted) →+ ``invalid_url``, not ``webhook_failed`` (issue #5110)."""snapshot = {"notifications.service_url": "discord://x","notifications.on_research_completed": True,@@ -567,7 +609,113 @@ class TestNotificationResultSemantics:event_type=EventType.RESEARCH_COMPLETED,context={"query": "q"},)+ assert result.reason is NotificationReason.INVALID_URL++ def test_invalid_url_real_service_contract(self, mocker):+ """Same as above but through the REAL NotificationService, so the+ test breaks if the service's invalid-URL contract ever changes.+ An unrecognized scheme fails the SSRF URL validator, which raises+ ServiceError before any network I/O — that too must map to+ ``invalid_url``, not ``exception``."""+ snapshot = {+ "notifications.service_url": "not-a-real-scheme://nope",+ "notifications.on_research_completed": True,+ }+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)+ result = manager.send_notification(+ event_type=EventType.RESEARCH_COMPLETED,+ context={"query": "q"},+ )+ assert result.sent is False+ assert result.reason is NotificationReason.INVALID_URL++ def test_webhook_failed_when_delivery_raises_senderror(self, mocker):+ """The delivery layer signals a real dispatch failure (dead+ webhook, HTTP error, network down) by RAISING SendError — it+ never returns False for this. That contract must map to+ ``webhook_failed``, and the detail must not echo the exception+ message, which wraps URLs/tokens (issue #5110)."""+ snapshot = {+ "notifications.service_url": "discord://x",+ "notifications.on_research_completed": True,+ }+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ manager.service.send_event = mocker.MagicMock(+ side_effect=SendError(+ "Failed to send notification: POST discord://id/secret-token"+ )+ )+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)+ result = manager.send_notification(+ event_type=EventType.RESEARCH_COMPLETED,+ context={"query": "q"},+ )+ assert result.sent is Falseassert result.reason is NotificationReason.WEBHOOK_FAILED+ assert "secret-token" not in result.detail+ assert "discord://" not in result.detail++ def test_invalid_url_detail_does_not_leak_serviceerror_message(+ self, mocker+ ):+ """A ServiceError from URL security validation maps to+ ``invalid_url``. Its message wraps the offending URL (which can+ embed a token) — the static ``detail`` must never echo it, since+ downstream callers log ``detail`` verbatim (issue #5110)."""+ snapshot = {+ "notifications.service_url": "discord://x",+ "notifications.on_research_completed": True,+ }+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ manager.service.send_event = mocker.MagicMock(+ side_effect=ServiceError(+ "Invalid service URL: discord://id123/secret-token blocked"+ )+ )+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)+ result = manager.send_notification(+ event_type=EventType.RESEARCH_COMPLETED,+ context={"query": "q"},+ )+ assert result.sent is False+ assert result.reason is NotificationReason.INVALID_URL+ assert "secret-token" not in result.detail+ assert "id123" not in result.detail+ assert "discord://" not in result.detail++ def test_security_block_error_gets_distinct_detail(self, mocker):+ """A ``SecurityBlockError`` (confirmed send-time SSRF/DNS-rebind+ block — a ``ServiceError`` subclass NotificationService.send()+ raises for that case) must still map to ``invalid_url`` like a+ plain ``ServiceError``, but with a detail that says the+ destination was blocked by egress/SSRF protection rather than the+ generic "check your URL/settings" text — the latter is misleading+ for a confirmed security block, not a config mistake."""+ snapshot = {+ "notifications.service_url": "discord://x",+ "notifications.on_research_completed": True,+ }+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ manager.service.send_event = mocker.MagicMock(+ side_effect=SecurityBlockError(+ "Notification send refused: a send-time DNS resolution "+ "was blocked as internal/private/metadata (possible SSRF)"+ )+ )+ manager._rate_limiter.is_allowed = mocker.MagicMock(return_value=True)+ result = manager.send_notification(+ event_type=EventType.RESEARCH_COMPLETED,+ context={"query": "q"},+ )+ assert result.sent is False+ assert result.reason is NotificationReason.INVALID_URL+ assert "blocked by egress/SSRF protection" in result.detail+ # Must not repeat the pre-dispatch-validation wording, which+ # would misleadingly suggest a settings/URL-format mistake.+ assert "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS" not in result.detail+ # And must not leak the exception message or any resolved detail.+ assert "DNS resolution" not in result.detaildef test_exception(self, mocker):snapshot = {@@ -616,6 +764,19 @@ class TestNotificationResultSemantics:assert "discord://" not in result.detailassert "RuntimeError" in result.detail+ def test_test_service_distinguishes_unevaluable_policy(self, mocker):+ """test_service must not blame the egress scope when the policy+ could not be evaluated at all (filter returned None)."""+ snapshot = {"notifications.service_url": "discord://x"}+ manager = NotificationManager(settings_snapshot=snapshot, user_id="u")+ with patch.object(+ manager, "_filter_urls_by_egress_policy", return_value=None+ ):+ result = manager.test_service("discord://x")+ assert result["status"] == "error"+ assert "could not be evaluated" in result["message"]+ assert "refused" not in result["message"]+def test_rate_limit_still_raises(self, mocker):"""Backward compat: rate-limit refusal still raises, not returned."""snapshot = {diff --git a/tests/notifications/test_notification_webhook_dns_pin.py b/tests/notifications/test_notification_webhook_dns_pin.pyindex 6fe092f97f..f0dd05e696 100644--- a/tests/notifications/test_notification_webhook_dns_pin.py+++ b/tests/notifications/test_notification_webhook_dns_pin.py@@ -37,7 +37,11 @@ from cryptography.hazmat.primitives import hashes, serializationfrom cryptography.hazmat.primitives.asymmetric import rsafrom cryptography.x509.oid import NameOID-from local_deep_research.notifications.exceptions import SendError, ServiceError+from local_deep_research.notifications.exceptions import (+ SecurityBlockError,+ SendError,+ ServiceError,+)from local_deep_research.notifications.service import NotificationServicefrom local_deep_research.security import dns_pinningfrom local_deep_research.security.notification_validator import (@@ -342,13 +346,16 @@ def test_public_json_webhook_delivers_through_apprise():def test_rebind_to_metadata_blocked_through_apprise():"""Validation sees a public IP; the pin's connect-time re-validationcatches the rebind to cloud-metadata and refuses the send before any- connection is made."""+ connection is made. The pin's rebind catch raises a non-retryable+ ValueError, which ``send()`` surfaces as ServiceError (a confirmed+ security block, not a retryable SendError — see+ ``NotificationService.send``'s docstring)."""resolver = _Resolver({"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]})with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",@@ -363,7 +370,8 @@ def test_multi_url_batch_guards_every_host():"""A single notify() fans out to several raw-webhook URLs. EVERY host inthe batch is pinned/checked: one host that rebinds to metadata refusesthe whole batch (fail closed) and no connection to the metadata IP is- made — proving the guard is not applied to just the first URL."""+ made — proving the guard is not applied to just the first URL. The+ confirmed rebind raises ServiceError (non-retryable), not SendError."""server, port, _hits = _start_server()resolver = _Resolver({@@ -374,7 +382,7 @@ def test_multi_url_batch_guards_every_host():urls = f"json://a.example:{port}/x,json://b.example/y"with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t", body="b", service_urls=urls)try:assert not any(addr[0] == "169.254.169.254" for addr in targets)@@ -724,17 +732,22 @@ def test_guarded_send_refuses_async_mode_and_tag():"""The guarded-send invariants fail closed: async_mode must be off andtag must be None, or the thread-local pin/block would be bypassed byApprise's worker-thread fan-out. Teeth: drop the checks in- ``_enforce_guarded_send_invariants`` and neither raises."""+ ``_enforce_guarded_send_invariants`` and neither raises.++ Both violations raise ``SecurityBlockError`` directly (not a generic+ ``RuntimeError``) so ``send()`` cannot mislabel this deliberate+ security refusal as a retryable webhook failure — see the+ round-3 fix for #5113."""svc = _service()# Correct config: synchronous, no tag -> accepted.good = svc._new_apprise()svc._enforce_guarded_send_invariants(good, None)# async_mode=True -> refused.bad_async = apprise.Apprise(asset=apprise.AppriseAsset(async_mode=True))- with pytest.raises(RuntimeError, match="async_mode"):+ with pytest.raises(SecurityBlockError, match="async_mode"):svc._enforce_guarded_send_invariants(bad_async, None)# tag present -> refused.- with pytest.raises(RuntimeError, match="tag"):+ with pytest.raises(SecurityBlockError, match="tag"):svc._enforce_guarded_send_invariants(good, "urgent")@@ -743,14 +756,15 @@ def test_ssrf_block_is_not_retried():fail fast, not be retried 3x by Tenacity. The rebind host resolvespublic at validation (call #1) and metadata at the guarded pin (call#2), which raises the SSRF ValueError; with that excluded from retries- the guarded pin runs exactly ONCE. Teeth: restore+ the guarded pin runs exactly ONCE. ``send()`` surfaces this confirmed,+ non-retryable block as ServiceError, not SendError. Teeth: restore``retry_if_exception_type((Exception,))`` and the pin is retried, sorebind.example is resolved 4 times (1 validation + 3 pin attempts)."""resolver = _Resolver({"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]})with patch.object(dns_pinning, "_real_getaddrinfo", resolver):- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",@@ -839,15 +853,16 @@ def test_block_window_block_is_not_retried():re-raises it non-retryably. The rebind host resolves public at validation(call #1) and metadata at the send-time window resolution (call #2), sowith the block excluded from retries the host is resolved exactly TWICE.- Teeth: drop the ``consume_ssrf_block`` short-circuit in ``_send_with_retry``- and the send is retried, resolving the host 4 times (1 validation + 3- send attempts)."""+ ``send()`` surfaces the confirmed, non-retryable block as ServiceError,+ not SendError. Teeth: drop the ``consume_ssrf_block`` short-circuit in+ ``_send_with_retry`` and the send is retried, resolving the host 4 times+ (1 validation + 3 send attempts)."""resolver = _Resolver({"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]})with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",@@ -899,12 +914,21 @@ def test_ipv6_imds_refused_by_block_window():def test_send_with_tag_is_refused_end_to_end():"""send(..., tag=...) is refused end-to-end: a tag can fan delivery outto worker threads that bypass the thread-local pin/block, so the- guarded-send invariant rejects it (RuntimeError, wrapped as SendError)- before any connection — no socket is opened to the target."""+ guarded-send invariant rejects it before any connection — no socket is+ opened to the target.++ The invariant guard raises ``SecurityBlockError`` directly (not a+ generic ``RuntimeError``), and ``send()`` must propagate it unchanged+ rather than wrap it as ``SendError``: this is a deliberate security+ refusal, not a transient webhook failure, and NotificationManager maps+ ``SendError`` to the RETRYABLE ``webhook_failed`` reason — retrying a+ security refusal would be a bug. Round-3 fix for #5113 (the prior fix+ only re-routed the ValueError SSRF-block path, leaving this+ RuntimeError invariant-violation path mislabeled as webhook_failed)."""resolver = _Resolver({"good.example": [["93.184.216.34"]]})with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(SecurityBlockError):_service().send(title="t",body="b",@@ -1050,7 +1074,8 @@ def test_ipv6_imds_rebind_refused_through_send():``test_rebind_to_metadata_blocked_through_apprise``. The pin's connect-timere-validation catches the rebind (the cloud-metadata block is absolute evenunder allow_private_ips=True, which permits the fc00::/7 ULA the address- sits in) and raises the SSRF ValueError, wrapped as SendError.+ sits in) and raises the SSRF ValueError, which ``send()`` surfaces as+ ServiceError (confirmed, non-retryable security block — not SendError).Teeth: drop the ``is_ip_blocked`` check in``dns_pinning._resolve_and_validate`` (or remove ``fd00:ec2::254`` from@@ -1066,7 +1091,7 @@ def test_ipv6_imds_rebind_refused_through_send():)with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",@@ -1236,13 +1261,16 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition():leaving ``is_ip_blocked`` / the validator untouched) and this testfails — the rebind pins successfully and the connect spy sees169.254.42.42.++ The confirmed rebind raises ServiceError (non-retryable), not+ SendError."""resolver = _Resolver({"ll-rebind.example": [["93.184.216.34"], ["169.254.42.42"]]})with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",@@ -1258,7 +1286,8 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():public IPv6 (resolver call #1) but rebinds to a bare IPv6 link-localaddress ``fe80::1`` (fe80::/10, not an always-blocked literal) at``_dispatch``'s pin resolution (call #2). Same wiring lock —- refused only by ``_dispatch``'s ``block_link_local=True``."""+ refused only by ``_dispatch``'s ``block_link_local=True``. The+ confirmed rebind raises ServiceError (non-retryable), not SendError."""resolver = _Resolver({"ll-rebind6.example": [@@ -1269,7 +1298,7 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():)with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:- with pytest.raises(SendError):+ with pytest.raises(ServiceError):_service().send(title="t",body="b",diff --git a/tests/notifications/test_queue_helpers_extended.py b/tests/notifications/test_queue_helpers_extended.pyindex 93cd9159f3..7cdbb92c35 100644--- a/tests/notifications/test_queue_helpers_extended.py+++ b/tests/notifications/test_queue_helpers_extended.py@@ -539,7 +539,7 @@ class TestSendResearchFailedNotificationFromSession:# ---------------------------------------------------------------------------# Regression: minimal-details logging path must not double-log-# (see PR #5082 review feedback — bug introduced in ee606c791).+# (see PR #5082 review feedback).# ---------------------------------------------------------------------------@@ -754,3 +754,264 @@ class TestMinimalDetailsLoggingRegression:assert sent_lines == [], sent_linesassert len(warning_lines) == 1, warning_linesassert "egress_denied" in warning_lines[0]+++# ---------------------------------------------------------------------------+# Regression: the found-research warning paths must carry the precise+# reason. These are the PR #5082 headline hunks that previously had no+# coverage — reverting them to the old "(disabled)" literal must fail+# these tests (issue #5110).+# ---------------------------------------------------------------------------+++class TestFoundResearchReasonLogging:+ """Log assertions for the found-research (non-minimal) paths."""++ @patch(REPORT_STORAGE)+ @patch(URL_BUILDER)+ @patch(NOTIF_MGR)+ def test_completed_found_failure_warns_with_reason(+ self, mock_nm_class, mock_build_url, mock_get_storage, loguru_caplog+ ):+ from local_deep_research.notifications.queue_helpers import (+ send_research_completed_notification_from_session,+ )++ mock_db = MagicMock()+ mock_research = Mock()+ mock_research.query = "How does AI work?"+ mock_db.query.return_value.filter_by.return_value.first.return_value = (+ mock_research+ )+ mock_build_url.return_value = "https://app.test/research/r-found"+ mock_storage = Mock()+ mock_storage.get_report.return_value = "Short report"+ mock_get_storage.return_value = mock_storage++ mock_nm = Mock()+ mock_nm.send_notification.return_value = _result(+ sent=False,+ reason_value="unconfigured",+ detail="notifications.service_url is not configured",+ )+ mock_nm_class.return_value = mock_nm++ mock_settings = Mock()+ mock_settings.get_settings_snapshot.return_value = {}++ with patch(SETTINGS_MGR, return_value=mock_settings):+ with loguru_caplog.at_level("INFO"):+ send_research_completed_notification_from_session(+ username="alice",+ research_id="r-found",+ db_session=mock_db,+ )++ warning_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Completion notification not sent" in rec.message+ ]+ assert len(warning_lines) == 1, warning_lines+ assert "unconfigured" in warning_lines[0]+ assert "notifications.service_url" in warning_lines[0]+ assert "(disabled)" not in warning_lines[0]++ @patch(NOTIF_MGR)+ def test_failed_found_failure_warns_with_reason(+ self, mock_nm_class, loguru_caplog+ ):+ from local_deep_research.notifications.queue_helpers import (+ send_research_failed_notification_from_session,+ )++ mock_db = MagicMock()+ mock_research = Mock()+ mock_research.query = "What is quantum computing?"+ mock_db.query.return_value.filter_by.return_value.first.return_value = (+ mock_research+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = _result(+ sent=False,+ reason_value="egress_denied",+ detail="all configured URLs refused by egress policy",+ )+ mock_nm_class.return_value = mock_nm++ mock_settings = Mock()+ mock_settings.get_settings_snapshot.return_value = {}++ with patch(SETTINGS_MGR, return_value=mock_settings):+ with loguru_caplog.at_level("INFO"):+ send_research_failed_notification_from_session(+ username="alice",+ research_id="r-found",+ error_message="boom",+ db_session=mock_db,+ )++ warning_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Failure notification not sent" in rec.message+ ]+ assert len(warning_lines) == 1, warning_lines+ assert "egress_denied" in warning_lines[0]+ assert "(disabled)" not in warning_lines[0]+++# ---------------------------------------------------------------------------+# Coverage for the send_queue_notification / send_queue_failed_notification+# wrappers: drop-reason logging at DEBUG, bool coercion at the boundary, and+# _format_reason's legacy-bool fallback (issue #5110).+# ---------------------------------------------------------------------------+++class TestQueueWrapperHelpers:+ """Behavior of the thin queue wrappers around send_notification."""++ @patch(f"{HELPERS}.NotificationManager")+ def test_queued_drop_returns_false_and_logs_reason_at_debug(+ self, mock_nm_class, loguru_caplog+ ):+ from local_deep_research.notifications.queue_helpers import (+ send_queue_notification,+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = _result(+ sent=False,+ reason_value="unconfigured",+ detail="notifications.service_url is not configured",+ )+ mock_nm_class.return_value = mock_nm++ with loguru_caplog.at_level("DEBUG"):+ returned = send_queue_notification(+ username="alice",+ research_id="r-q",+ query="q",+ settings_snapshot={"any": "thing"},+ )++ assert returned is False+ reason_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Queue notification not sent" in rec.message+ ]+ assert len(reason_lines) == 1, reason_lines+ assert "unconfigured" in reason_lines[0]++ @patch(f"{HELPERS}.NotificationManager")+ def test_queued_success_returns_true_without_warning(+ self, mock_nm_class, loguru_caplog+ ):+ from local_deep_research.notifications.queue_helpers import (+ send_queue_notification,+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = _result(sent=True)+ mock_nm_class.return_value = mock_nm++ with loguru_caplog.at_level("DEBUG"):+ returned = send_queue_notification(+ username="alice",+ research_id="r-q",+ query="q",+ settings_snapshot={"any": "thing"},+ )++ assert returned is True+ assert not [+ rec.message+ for rec in loguru_caplog.records+ if "Queue notification not sent" in rec.message+ ]++ @patch(f"{HELPERS}.NotificationManager")+ def test_queued_legacy_bool_false_logs_dropped(+ self, mock_nm_class, loguru_caplog+ ):+ """Legacy mocks returning a bare bool must still coerce and log+ via _format_reason's fallback branch."""+ from local_deep_research.notifications.queue_helpers import (+ send_queue_notification,+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = False+ mock_nm_class.return_value = mock_nm++ with loguru_caplog.at_level("DEBUG"):+ returned = send_queue_notification(+ username="alice",+ research_id="r-q",+ query="q",+ settings_snapshot={"any": "thing"},+ )++ assert returned is False+ reason_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Queue notification not sent" in rec.message+ ]+ assert len(reason_lines) == 1, reason_lines+ assert "(dropped)" in reason_lines[0]++ @patch(f"{HELPERS}.NotificationManager")+ def test_queued_legacy_bool_true_returns_true(self, mock_nm_class):+ from local_deep_research.notifications.queue_helpers import (+ send_queue_notification,+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = True+ mock_nm_class.return_value = mock_nm++ returned = send_queue_notification(+ username="alice",+ research_id="r-q",+ query="q",+ settings_snapshot={"any": "thing"},+ )++ assert returned is True++ @patch(f"{HELPERS}.NotificationManager")+ def test_failed_drop_returns_false_and_logs_reason_at_debug(+ self, mock_nm_class, loguru_caplog+ ):+ from local_deep_research.notifications.queue_helpers import (+ send_queue_failed_notification,+ )++ mock_nm = Mock()+ mock_nm.send_notification.return_value = _result(+ sent=False,+ reason_value="server_disabled",+ detail="outbound notifications are disabled at the server level",+ )+ mock_nm_class.return_value = mock_nm++ with loguru_caplog.at_level("DEBUG"):+ returned = send_queue_failed_notification(+ username="alice",+ research_id="r-f",+ query="q",+ error_message="boom",+ settings_snapshot={"any": "thing"},+ )++ assert returned is False+ reason_lines = [+ rec.message+ for rec in loguru_caplog.records+ if "Failed-notification not sent" in rec.message+ ]+ assert len(reason_lines) == 1, reason_lines+ assert "server_disabled" in reason_lines[0]diff --git a/tests/security/test_egress_notifications_callsite.py b/tests/security/test_egress_notifications_callsite.pyindex a5c7f18383..b6c83aa7da 100644--- a/tests/security/test_egress_notifications_callsite.py+++ b/tests/security/test_egress_notifications_callsite.py@@ -153,8 +153,12 @@ def test_corrupt_scope_fails_closed():# A garbage scope makes context_from_snapshot raise PolicyDeniedError;# the PEP must refuse ALL urls rather than fall open to unfiltered send.+ # None is the unevaluable-policy signal (falsy, so callers still drop+ # everything) — distinct from "" which means "evaluated, all refused".deny_mgr = _build_manager(_snapshot("totally-not-a-scope"))- assert deny_mgr._filter_urls_by_egress_policy(url) == ""+ filtered = deny_mgr._filter_urls_by_egress_policy(url)+ assert filtered is None+ assert not filtered# Sanity pair: a valid permissive scope on the same input passes it.allow_mgr = _build_manager(_snapshot("both"))