trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/notifications/tasks.py

@@ -0,0 +1,711 @@
+"""Celery tasks for the notifications app (ADR-0075 §F durable-execution).
+
+Three Beat-scheduled tasks:
+
+- ``drain_notification_emails`` — every 30 s, finds Notification rows with
+  ``email_pending=True`` older than the 5-min orphan window, renders an email
+  for each, sends via SMTP, and updates delivery state. Best-effort — broker
+  outage logs but doesn't propagate. Re-checks the recipient's account and
+  project-membership status at drain time, not just at creation time (#3523,
+  #3675) — a row queued before an off-boarding or a project removal is
+  retired unsent rather than delivered on a stale grant.
+
+- ``archive_old_notifications`` — nightly, sets ``is_archived=True`` on any
+  Notification older than 90 days that has ``is_read=True``. Keeps the
+  index on ``(recipient, is_read, -created_at)`` shallow for the unread
+  query path.
+
+- ``detect_stale_tasks`` — nightly (ADR-0200), scans every project for
+  non-terminal tasks that have sat in their current status past the project's
+  ``stale_task_threshold_days`` (default 7) and nudges the assignee via the
+  #639 event-notification rail. Idempotent: dedupes against existing unread
+  ``task.stale`` notifications, so a re-run creates zero duplicates.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import html
+import logging
+import textwrap
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from trueppm_api.core.idempotent import idempotent_task
+
+from .delivery_limits import (
+    EMAIL_MAX_BATCH_SIZE,
+    beat_ticks_per_minute,
+    per_tick_cap,
+    reserve_send_budget,
+)
+
+if TYPE_CHECKING:
+    from django.core.mail.backends.base import BaseEmailBackend
+
+logger = logging.getLogger(__name__)
+
+
+# Locked constants for email delivery — kept in this module so they're
+# adjacent to the drain task that owns them.
+EMAIL_MAX_RETRIES = 3
+EMAIL_ORPHAN_WINDOW_MINUTES = 5  # ADR-0075 §F durable-execution checklist item 3
+# Fallback cap per drain tick, when no operator limit applies. Re-exported from
+# delivery_limits, which every mail path now shares (#2887 item 3).
+EMAIL_BATCH_SIZE = EMAIL_MAX_BATCH_SIZE
+# Beat task name — also the key the per-minute throttle divisor is derived from, so
+# the cadence and the throttle can no longer disagree (#2887 item 4).
+DRAIN_TASK_NAME = "notifications.drain_notification_emails"
+ARCHIVE_AFTER_DAYS = 90  # ADR-0075 §F item 6 — outbox cleanup
+
+# Snippet rendering (#574, security review !306 LOW-1). SNIPPET_MAX_CHARS bounds
+# the raw comment text before it's embedded in the email body; SNIPPET_WRAP_WIDTH
+# hard-wraps it so a long unbroken string (a pasted URL, log line, or base64 blob)
+# can't render as a single unbounded line in the recipient's mail client.
+SNIPPET_MAX_CHARS = 280
+SNIPPET_WRAP_WIDTH = 72  # classic plain-text convention; keeps quoted replies readable
+
+
+@idempotent_task(
+    lock_key_template="drain_notification_emails",
+    lock_ttl=60,
+    on_contention="skip",
+    soft_time_limit=25,
+    time_limit=30,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="notifications.drain_notification_emails",
+)
+def drain_notification_emails(self: object) -> None:
+    """Send queued email notifications.
+
+    Runs every 30 seconds via Celery Beat. Finds Notification rows where
+    ``email_pending=True`` and ``email_sent_at IS NULL`` and ``email_attempts
+    < EMAIL_MAX_RETRIES`` and ``created_at < (now - orphan_window)``.
+
+    The orphan-window filter prevents racing the comment-create transaction —
+    a Notification inserted inside a still-open atomic block isn't visible
+    to this drain until commit AND has aged past the window. The 5-min value
+    matches the webhook drain (ADR-0019).
+
+    The singleton lock + ``on_contention="skip"`` ensures at most one drain
+    runs at a time; the next Beat tick picks up anything missed.
+    """
+    _do_drain_emails()
+
+
+@idempotent_task(
+    lock_key_template="archive_old_notifications",
+    lock_ttl=120,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="notifications.archive_old_notifications",
+)
+def archive_old_notifications(self: object) -> None:
+    """Archive read notifications older than 90 days.
+
+    Runs nightly via Celery Beat. Sets ``is_archived=True`` on Notifications
+    where ``is_read=True`` and ``created_at < (now - ARCHIVE_AFTER_DAYS)``.
+
+    Archive is a soft state — rows stay in the table, are excluded from
+    default list queries, and remain reachable via the explicit ``archived``
+    filter. A future hard-purge for archived rows older than 365 days is
+    operational concern (not in 0.2).
+    """
+    _do_archive()
+
+
+@idempotent_task(
+    lock_key_template="detect_stale_tasks",
+    lock_ttl=300,
+    on_contention="skip",
+    soft_time_limit=110,
+    time_limit=120,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="notifications.detect_stale_tasks",
+)
+def detect_stale_tasks(self: object) -> None:
+    """Nudge assignees of stale non-terminal tasks (ADR-0200).
+
+    Runs nightly via Celery Beat. Delegates to
+    :func:`notifications.services.create_stale_task_notifications`, which owns the
+    per-project threshold query, the unread dedupe, and the preference-gated fan-out.
+
+    Idempotent by construction: the dedupe against existing unread ``task.stale``
+    notifications means a broker retry, a manual re-queue, or the next nightly tick
+    all create zero duplicates. The singleton lock (``on_contention="skip"``) also
+    prevents two overlapping runs. A failed run is not retried — the tasks are still
+    stale tomorrow, so silent re-attempt on the next tick is correct and avoids a
+    retry storm (ADR-0200 §Durable Execution item 8).
+    """
+    from .services import create_stale_task_notifications
+
+    created = create_stale_task_notifications()
+    if created:
+        logger.info("detect_stale_tasks: created %d stale-task notification(s)", created)
+
+
+@idempotent_task(
+    lock_key_template="send_scheduled_digests",
+    lock_ttl=300,
+    on_contention="skip",
+    soft_time_limit=280,
+    time_limit=300,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    max_retries=0,
+    name="notifications.send_scheduled_digests",
+)
+def send_scheduled_digests(self: object) -> None:
+    """Send weekly digests whose per-user slot matches this hour (ADR-0663).
+
+    Runs **hourly** via Beat even though the digests are weekly: the send time is
+    a per-user property (``UserNotificationSettings.digest_*``) in the user's own
+    timezone, so the sweep has to look every hour and match slots rather than fire
+    on one cluster-wide schedule.
+
+    ``max_retries=0`` — retrying is pointless here. The next tick is 60 minutes
+    away and re-evaluates from current state, and the ledger row is already written,
+    so a retry would either no-op or mail a stale snapshot. A failed run means one
+    skipped weekly digest, which the reader can recover by logging in
+    (ADR-0663 §Durable Execution item 8).
+    """
+    from .digests import send_due_digests
+
+    created = send_due_digests()
+    if created:
+        logger.info("send_scheduled_digests: created %d digest notification(s)", created)
+
+
+@idempotent_task(
+    lock_key_template="purge_old_digest_runs",
+    lock_ttl=300,
+    on_contention="skip",
+    soft_time_limit=55,
+    time_limit=90,
+    acks_late=True,
+    reject_on_worker_lost=True,
+    name="notifications.purge_old_digest_runs",
+)
+def purge_old_digest_runs(self: object) -> None:
+    """Delete digest ledger rows past the retention window (ADR-0663 item 6).
+
+    Retention is 90 days rather than the 7-day per-request outbox convention: the
+    ledger exists to remember a *weekly* send, so a 7-day window would forget a
+    fortnight-old run it must not repeat.
+    """
+    from .digests import purge_old_digest_runs as _purge
+
+    deleted = _purge()
+    if deleted:
+        logger.info("purge_old_digest_runs: deleted %d ledger row(s)", deleted)
+
+
+# ---------------------------------------------------------------------------
+# Drain — extracted for direct testability without Celery in the loop
+# ---------------------------------------------------------------------------
+
+
+def _drain_batch_size(email_settings: Any) -> int:
+    """Rows to drain this tick, honoring the operator's delivery limits (#2860).
+
+    Thin wrapper over :func:`delivery_limits.per_tick_cap` that supplies this drain's
+    beat cadence. The interpretation of both controls, and the shared per-minute budget
+    that spans every mail path, live in ``delivery_limits`` (#2887 item 3).
+    """
+    return per_tick_cap(
+        email_settings,
+        ticks_per_minute=beat_ticks_per_minute(DRAIN_TASK_NAME),
+        fallback=EMAIL_MAX_BATCH_SIZE,
+    )
+
+
+def _current_project_membership_exists() -> Any:
+    """Correlated ``EXISTS(ProjectMembership …)`` for a notification's (recipient, project).
+
+    Shared by :func:`_retire_pending_for_revoked_membership` and the pending-row
+    query in :func:`_do_drain_emails` so both express the same boundary
+    ``NotificationSerializer._recipient_can_see_project`` (#3510) enforces on
+    read — as one correlated subquery attached to whatever outer
+    ``Notification`` queryset calls this, never a per-row Python-side lookup
+    (#3675 review note: this drain processes a whole batch per 30 s tick, so an
+    N+1 here scales with backlog size).
+
+    ``is_deleted=False`` matches the serializer predicate exactly: a soft-deleted
+    (revoked) ``ProjectMembership`` row does not count as current membership.
+    """
+    from django.db.models import Exists, OuterRef
+
+    from trueppm_api.apps.access.models import ProjectMembership
+
+    return Exists(
+        ProjectMembership.objects.filter(
+            user_id=OuterRef("recipient_id"),
+            project_id=OuterRef("project_id"),
+            is_deleted=False,
+        )
+    )
+
+
+def _retire_pending_for_revoked_membership() -> int:
+    """Retire queued emails whose recipient has since lost project membership (#3675).
+
+    Mirrors :func:`_retire_pending_for_deactivated_recipients` (#3523) for the
+    membership axis rather than the account-active axis. ``_render_email`` /
+    ``_send_email_for_notification`` read ``Notification.subject``/``.body``
+    straight off the frozen row and mail them via SMTP without ever consulting
+    ``NotificationSerializer._recipient_can_see_project`` (#3510) — so a member
+    removed from ``obj.project`` during the orphan-window-plus-retry gap between
+    a notification's creation and its eventual successful send still received a
+    plaintext email naming a project/task they can no longer see through the API.
+    Fixing the REST read path (#3510) does not reach this channel because it
+    never goes through the serializer at all.
+
+    A row with no project (``project_id IS NULL`` — the ADR-0663 account-scoped
+    digest shape) has no membership boundary to check and is left untouched,
+    matching ``_recipient_can_see_project``'s own "falls open with no project"
+    rule.
+
+    **Retired, not failed** — same terminal-state reasoning as #3523: only
+    ``email_pending`` is cleared here. ``email_attempts`` and ``email_failed_at``
+    are deliberately left untouched, so ``observability.selectors.
+    notification_email_signals``'s ``failed_recent`` signal (``email_pending=
+    False`` AND ``email_attempts >= EMAIL_MAX_RETRIES`` AND a recent
+    ``email_failed_at``) never reports a deliberate privacy suppression as an
+    SMTP/mail-relay failure, and the row does not sit in ``queued_aging`` forever
+    either (it reaches a terminal state instead of parking in the backlog).
+
+    Resolved as a single ``UPDATE … WHERE NOT EXISTS (…)`` rather than one
+    membership query per row — the drain runs every 30 s over the whole pending
+    backlog, so a per-row check would multiply with backlog size.
+
+    Returns:
+        The number of rows retired — 0 on every tick where no pending recipient
+        has lost project access, the steady state.
+    """
+    from .models import Notification
+
+    retired: int = (
+        Notification.objects.filter(
+            email_pending=True,
+            email_sent_at__isnull=True,
+            project_id__isnull=False,
+        )
+        .exclude(_current_project_membership_exists())
+        .update(email_pending=False)
+    )
+    if retired:
+        logger.info(
+            "drain_notification_emails: retired %d queued email(s) for recipient(s) "
+            "no longer a member of the notification's project",
+            retired,
+        )
+    return retired
+
+
+def _retire_pending_for_deactivated_recipients() -> int:
+    """Retire queued emails whose recipient has since been deactivated (#3523).
+
+    The digest sweep now excludes deactivated users at the audience (see
+    ``digests._opted_in_user_ids``), but rows queued *before* off-boarding are already
+    in the outbox — and every notification email in OSS leaves through this one drain,
+    so this is the single chokepoint at which the account axis covers the mention,
+    stale-task, event and digest rails at once.
+
+    **Retired, not merely skipped.** Excluding these rows from the candidate query
+    alone would leave them ``email_pending=True`` forever, and
+    ``observability.selectors.notification_email_signals`` reads exactly that as its
+    ``queued_aging`` signal — rows pending past an hour mean "Beat is dead, the worker
+    is gone, or the transport cannot be built". A permanent false alarm on the System
+    Health card is the over-claiming that selector's docstring exists to prevent, so
+    the row must reach a terminal state instead of parking in the backlog.
+
+    The terminal state written here is ``email_pending=False`` **only**.
+    ``email_attempts`` and ``email_failed_at`` are deliberately left untouched: the
+    same selector derives ``failed_recent`` from ``email_pending=False`` **and**
+    ``email_attempts >= EMAIL_MAX_RETRIES`` **and** a recent ``email_failed_at``, so
+    stamping either would report an off-boarding as a mail-relay failure. This is not
+    a delivery failure — there is no longer anyone to deliver to.
+
+    The durable in-app ``Notification`` row is left alone. It is the inbox record, and
+    a deactivated account cannot authenticate to read it (JWT, session and PAT all
+    close on ``is_active``); the email is the only channel that reaches outward.
+
+    Reactivation does not resurrect a retired row, which is the intended trade: an
+    off-boarding is not expected to reverse, and a week-old digest replayed on
+    reinstatement would state program health that has since moved on.
+
+    Returns:
+        The number of rows retired — 0 on every tick of a workspace with no pending
+        mail for a deactivated user, which is the steady state.
+    """
+    from .models import Notification
+
+    retired: int = Notification.objects.filter(
+        email_pending=True,
+        email_sent_at__isnull=True,
+        recipient__is_active=False,
+    ).update(email_pending=False)
+    if retired:
+        logger.info(
+            "drain_notification_emails: retired %d queued email(s) for deactivated "
+            "recipient(s) without sending",
+            retired,
+        )
+    return retired
+
+
+def _do_drain_emails() -> None:
+    from django.utils import timezone
+
+    from .models import Notification, WorkspaceEmailSettings
+
+    now = timezone.now()
+    orphan_cutoff = now - timedelta(minutes=EMAIL_ORPHAN_WINDOW_MINUTES)
+
+    _retire_pending_for_deactivated_recipients()
+    _retire_pending_for_revoked_membership()
+
+    # Read the operator's delivery limits BEFORE the query, because they bound it
+    # (#2860). max_recipients and throttle_per_min persisted, validated and rendered
+    # back in Workspace → Email for three releases while this task capped every
+    # drain at a hardcoded 50 regardless — a control that looked applied and was not.
+    email_settings = WorkspaceEmailSettings.load()
+    # Two-stage: the per-tick cap smooths within a minute, the shared budget bounds
+    # the minute across *every* mail path (invite drain, password reset, export-ready)
+    # so no single path can spend the whole allowance (#2887 item 3).
+    budget = reserve_send_budget(
+        int(email_settings.throttle_per_min or 0), _drain_batch_size(email_settings)
+    )
+    granted = budget.granted
+    if granted <= 0:
+        return
+
+    from django.db.models import Q
+
+    pending = list(
+        Notification.objects.filter(
+            email_pending=True,
+            email_sent_at__isnull=True,
+            email_attempts__lt=EMAIL_MAX_RETRIES,
+            created_at__lt=orphan_cutoff,
+            # Fail closed on the account axis (#3523). The retirement pass above has
+            # already cleared these rows, so this predicate normally matches nothing;
+            # it is here for the row deactivated in the gap between that UPDATE and
+            # this SELECT, where the only safe default is not to send.
+            recipient__is_active=True,
+        )
+        # Fail closed on the membership axis (#3675), same reasoning: the retirement
+        # pass above already cleared rows whose recipient lost project access, this
+        # is the backstop for a revocation landing in the gap between that UPDATE and
+        # this SELECT. A row with no project (account-scoped digests) has no
+        # membership boundary and always passes.
+        .filter(_current_project_membership_exists() | Q(project_id__isnull=True))
+        .select_related("recipient", "mention", "mention__task_comment", "mention__mentioner")
+        .order_by("created_at")[:granted]
+    )
+
+    # Hand back what this tick will not spend, or an idle drain starves the other
+    # paths for the rest of the minute.
+    budget.release(granted - len(pending))
+
+    if not pending:
+        return
+
+    # Resolve the workspace transport + From identity ONCE per batch — the config
+    # is constant across the batch, so building it per message would be N SMTP
+    # connections + N single-row reads per tick (#712 perf, ADR-0213).
+    from .email_backend import (
+        EmailTransportError,
+        resolve_email_connection,
+        resolve_from_email,
+        resolve_reply_to,
+    )
+
+    try:
+        connection = resolve_email_connection(email_settings)
+    except EmailTransportError:
+        # The workspace has a transport configured that cannot be built — an
+        # undecryptable credential or a host the egress guard rejects (#2886 item 2).
+        # Deliberately return WITHOUT touching the rows: this is a configuration fault
+        # an operator fix clears, and burning three retries per row would permanently
+        # discard notifications for it. The rows stay pending, which is what the
+        # System Health card's aging-backlog signal reports on, and
+        # ``transport_status`` names the cause directly.
+        logger.error(
+            "drain_notification_emails: the configured mail transport is unusable — "
+            "%d row(s) left pending, no retries burned. Fix the transport in "
+            "Workspace -> Email.",
+            len(pending),
+        )
+        budget.release(len(pending))
+        return
+    from_email = resolve_from_email(email_settings)
+    reply_to = resolve_reply_to(email_settings)
+
+    # Open the shared connection once so all N sends reuse one socket/TLS
+    # handshake. Best-effort: if the transport is down, each per-message send
+    # still attempts (and fails) on its own, preserving the attempt/retry count.
+    try:
+        connection.open()
+    except Exception:
+        logger.warning("drain_notification_emails: could not open mail transport", exc_info=True)
+
+    sent = 0
+    failed = 0
+    try:
+        for notif in pending:
+            try:
+                ok = _send_email_for_notification(
+                    notif,
+                    connection=connection,
+                    from_email=from_email,
+                    reply_to=reply_to,
+                )
+            except Exception:
+                logger.exception(
+                    "drain_notification_emails: unexpected error for notif %s", notif.pk
+                )
+                ok = False
+
+            if ok:
+                Notification.objects.filter(pk=notif.pk).update(
+                    email_pending=False,
+                    email_sent_at=timezone.now(),
+                )
+                sent += 1
+            else:
+                # Increment attempts atomically; on attempt N=max, clear
+                # email_pending so the row is no longer eligible for retry.
+                from django.db.models import F
+
+                new_attempts = notif.email_attempts + 1
+                update_fields: dict[str, object] = {
+                    "email_attempts": F("email_attempts") + 1,
+                    "email_failed_at": timezone.now(),
+                }
+                if new_attempts >= EMAIL_MAX_RETRIES:
+                    update_fields["email_pending"] = False
+                Notification.objects.filter(pk=notif.pk).update(**update_fields)
+                failed += 1
+    finally:
+        with contextlib.suppress(Exception):
+            connection.close()
+
+    logger.info(
+        "drain_notification_emails: sent=%d failed=%d candidates=%d",
+        sent,
+        failed,
+        len(pending),
+    )
+
+
+def _do_archive() -> None:
+    from django.utils import timezone
+
+    from .models import Notification
+
+    cutoff = timezone.now() - timedelta(days=ARCHIVE_AFTER_DAYS)
+    archived = Notification.objects.filter(
+        is_read=True,
+        is_archived=False,
+        created_at__lt=cutoff,
+    ).update(is_archived=True)
+    if archived:
+        logger.info(
+            "archive_old_notifications: archived %d row(s) older than %dd",
+            archived,
+            ARCHIVE_AFTER_DAYS,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Email rendering — minimal Diátaxis-friendly subject + plain-text body
+# ---------------------------------------------------------------------------
+
+
+def _send_email_for_notification(
+    notif: object,
+    *,
+    connection: BaseEmailBackend | None = None,
+    from_email: str | None = None,
+    reply_to: list[str] | None = None,
+) -> bool:
+    """Render and send the email for a single Notification.
+
+    Returns True on successful SMTP delivery, False on any failure (SMTP error,
+    missing user email, missing source mention). The caller increments the
+    attempt counter — this function is pure-attempt, no state mutation.
+
+    The workspace transport (``connection``), ``from_email``, and ``reply_to``
+    are resolved **once per drain batch** and passed in (#712 perf: the config is
+    constant across a batch, so a per-message ``load()`` + SMTP connect would be
+    50 redundant DB reads and SMTP/TLS handshakes per tick). When omitted they are
+    resolved here so a direct/one-off caller still works.
+    """
+    from django.core.mail import EmailMessage
+
+    from .email_backend import (
+        resolve_email_connection,
+        resolve_from_email,
+        resolve_reply_to,
+    )
+    from .models import Notification
+
+    notif_obj: Notification = notif  # type: ignore[assignment]
+    recipient = notif_obj.recipient
+    recipient_email = getattr(recipient, "email", "") or ""
+    if not recipient_email:
+        logger.warning(
+            "drain_notification_emails: recipient %s has no email, skipping notif %s",
+            getattr(recipient, "pk", "?"),
+            notif_obj.pk,
+        )
+        return False
+
+    # A notification is mention-sourced OR event-sourced (#639, ADR-0085 §3);
+    # _render_email handles both shapes and returns ("", "") if neither yields
+    # renderable content (e.g. the source comment was deleted).
+    subject, body = _render_email(notif_obj)
+    if not subject or not body:
+        return False
+
+    # Dynamic transport + From identity from the workspace SMTP config (#712,
+    # ADR-0213). Falls back to the global backend / DEFAULT_FROM_EMAIL when the
+    # workspace transport is unconfigured (cloud), so this is a no-op for installs
+    # that never touch the writable config.
+    if connection is None:
+        connection = resolve_email_connection()
+    if from_email is None:
+        from_email = resolve_from_email()
+    if reply_to is None:
+        reply_to = resolve_reply_to()
+    msg = EmailMessage(
+        subject=subject,
+        body=body,
+        from_email=from_email,
+        to=[recipient_email],
+        reply_to=reply_to or None,
+        headers=_unsubscribe_headers() or None,
+        connection=connection,
+    )
+    try:
+        msg.send(fail_silently=False)
+    except Exception:
+        logger.warning(
+            "drain_notification_emails: SMTP send failed for notif %s",
+            notif_obj.pk,
+            exc_info=True,
+        )
+        return False
+    return True
+
+
+def _render_email(notif: object) -> tuple[str, str]:
+    """Render a Notification into (subject, body) plain-text strings.
+
+    Kept deliberately minimal — the UI is the primary surface; email is a
+    secondary "ping the inbox" channel for users who opt in (default OFF).
+    A richer HTML template lands when the executive-digest issue ships
+    (trueppm-enterprise#112).
+    """
+    from .models import Notification
+
+    notif_obj: Notification = notif  # type: ignore[assignment]
+    mention = notif_obj.mention
+    if mention is None:
+        # Event-sourced notification (#639): the subject/body were rendered at
+        # dispatch time and frozen on the row. Empty subject => nothing to send.
+        return notif_obj.subject, notif_obj.body
+
+    mentioner = mention.mentioner
+    mentioner_name = (
+        mentioner.get_full_name() or mentioner.username if mentioner is not None else "Someone"
+    )
+
+    comment = mention.task_comment
+    if comment is None or comment.is_deleted:
+        return "", ""
+
+    task = comment.task
+    task_name = task.name if task else "a task"
+    snippet = _sanitize_snippet(comment.body or "")
+
+    if mention.mentioned_group_key:
+        subject = f"{mentioner_name} mentioned @{mention.mentioned_group_key} on {task_name}"
+    else:
+        subject = f"{mentioner_name} mentioned you on {task_name}"
+
+    body_lines = [
+        f'{mentioner_name} mentioned you in a comment on "{task_name}":',
+        "",
+        snippet,
+        "",
+        "Open the task in TruePPM to reply or acknowledge.",
+        "",
+        "—",
+        "You can change which notifications send email at /me/settings/notifications/.",
+    ]
+    body = "\n".join(body_lines)
+    return subject, body
+
+
+def _sanitize_snippet(raw: str) -> str:
+    """Bound and format a comment snippet for embedding in the plain-text email body.
+
+    Truncates to ``SNIPPET_MAX_CHARS``, HTML-escapes as defense-in-depth (the
+    body is sent as ``text/plain`` today, so this isn't an XSS vector, but
+    escaping now means a future HTML template — e.g. the executive-digest work
+    in trueppm-enterprise#112 — can reuse this helper without introducing a new
+    escaping gap), and hard-wraps at ``SNIPPET_WRAP_WIDTH`` so a long unbroken
+    string (a pasted URL, log line, or base64 blob) can't render as a single
+    unbounded line in the recipient's mail client (#574, security review !306
+    LOW-1). ``quote=False`` on the escape leaves straight/curly quotes and
+    apostrophes untouched — those are common in ordinary prose and carry no
+    markup risk in body text, only ``&``/``<``/``>`` do.
+    """
+    text = (raw or "").strip()
+    if len(text) > SNIPPET_MAX_CHARS:
+        text = text[:SNIPPET_MAX_CHARS].rstrip() + "..."
+    escaped = html.escape(text, quote=False)
+    return textwrap.fill(
+        escaped,
+        width=SNIPPET_WRAP_WIDTH,
+        break_long_words=True,
+        break_on_hyphens=False,
+    )
+
+
+def _unsubscribe_headers() -> dict[str, str]:
+    """Build the RFC 2369 ``List-Unsubscribe`` header.
+
+    Points at the user's notification-preferences page — TruePPM has no
+    per-notification unsubscribe token today, so this is "one click to the
+    login-gated preferences page" rather than a true no-auth unsubscribe. That is a
+    valid ``List-Unsubscribe`` on its own; RFC 2369 does not require the target to be
+    unauthenticated.
+
+    ``List-Unsubscribe-Post: List-Unsubscribe=One-Click`` is deliberately **not**
+    emitted (#2887 item 6). That header is an RFC 8058 promise that an unauthenticated
+    ``POST`` to the URL unsubscribes the recipient with no further interaction, and
+    there is no such handler anywhere in this app — the URL is a login-gated SPA route.
+    Gmail's and Yahoo's bulk-sender requirements are checked by *exercising* the POST,
+    so advertising it without a conforming endpoint is a deliverability liability,
+    inverting the reason it was added. Re-add it in the same change that ships a signed
+    unsubscribe token and its endpoint, never before.
+
+    Returns an empty dict — omitting the header entirely — when the deployer hasn't
+    configured ``FRONTEND_BASE_URL``, since a bare relative path is not a valid header
+    value.
+    """
+    from django.conf import settings
+
+    base = getattr(settings, "FRONTEND_BASE_URL", "").rstrip("/")
+    if not base:
+        return {}
+    prefs_url = f"{base}/me/settings/notifications"
+    return {"List-Unsubscribe": f"<{prefs_url}>"}