Feature: Redesign the task system (#12584)

* feat(tasks): replace PaperlessTask model with structured redesign Drop the old string-based PaperlessTask table and recreate it with Status/TaskType/TriggerSource enums, JSONField result storage, and duration tracking fields. Update all call sites to use the new API. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): rewrite signal handlers to track all task types Replace the old consume_file-only handler with a full rewrite that tracks 6 task types (consume_file, train_classifier, sanity_check, index_optimize, llm_index, mail_fetch) with proper trigger source detection, input data extraction, legacy result string parsing, duration/wait time recording, and structured error capture on failure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): add traceback and revoked state coverage to signal tests * refactor(tasks): remove manual PaperlessTask creation and scheduled/auto params All task records are now created exclusively via Celery signals (Task 2). Removed PaperlessTask creation/update from train_classifier, sanity_check, llmindex_index, and check_sanity. Removed scheduled= and auto= parameters from all 7 call sites. Updated apply_async callers to use trigger_source headers instead. Exceptions now propagate naturally from task functions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): auto-inject trigger_source=scheduled header for all beat tasks Inject `headers: {"trigger_source": "scheduled"}` into every Celery beat schedule entry so signal handlers can identify scheduler-originated tasks without per-task instrumentation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): update serializer, filter, and viewset with v9 backwards compat - Replace TasksViewSerializer/RunTaskViewSerializer with TaskSerializerV10 (new field names), TaskSerializerV9 (v9 compat), TaskSummarySerializer, and RunTaskSerializer - Add AcknowledgeTasksViewSerializer unchanged (kept existing validation) - Expand PaperlessTaskFilterSet with MultipleChoiceFilter for task_type, trigger_source, status; add is_complete, date_created_after/before filters - Replace TasksViewSet.get_serializer_class() to branch on request.version - Add get_queryset() v9 compat for task_name/type query params - Add acknowledge_all, summary, active actions to TasksViewSet - Rewrite run action to use apply_async with trigger_source header - Add timedelta import to views.py; add MultipleChoiceFilter/DateTimeFilter to filters.py imports Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(tasks): add read_only_fields to TaskSerializerV9, enforce admin via permission_classes on run action * test(tasks): rewrite API task tests for redesigned model and v9 compat Replaces the old Django TestCase-based tests with pytest-style classes using PaperlessTaskFactory. Covers v10 field names, v9 backwards-compat field mapping, filtering, ordering, acknowledge, acknowledge_all, summary, active, and run endpoints. Also adds PaperlessTaskFactory to factories.py and fixes a redundant source= kwarg in TaskSerializerV10.related_document_ids. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): fix two spec gaps in task API test suite Move test_list_is_owner_aware to TestGetTasksV10 (it tests GET /api/tasks/, not acknowledge). Add test_related_document_ids_includes_duplicate_of to cover the duplicate_of path in the related_document_ids property. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): address code quality review findings Remove trivial field-existence tests per project conventions. Fix potentially flaky ordering test to use explicit date_created values. Add is_complete=false filter test, v9 type filter input direction test, and tighten TestActive second test to target REVOKED specifically. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): update TaskAdmin for redesigned model Add date_created, duration_seconds to list_display; add trigger_source to list_filter; add input_data, duration_seconds, wait_time_seconds to readonly_fields. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): update Angular types and service for task redesign Replace PaperlessTaskName/PaperlessTaskType/PaperlessTaskStatus enums with new PaperlessTaskType, PaperlessTaskTriggerSource, PaperlessTaskStatus enums. Update PaperlessTask interface to new field names (task_type, trigger_source, input_data, result_message, related_document_ids). Update TasksService to filter by task_type instead of task_name. Update tasks component and system-status-dialog to use new field names. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(tasks): remove django-celery-results PaperlessTask now tracks all task results via Celery signals. The django-celery-results DB backend was write-only -- nothing reads from it. Drop the package and add a migration to clean up the orphaned tables. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: fix remaining tests broken by task system redesign Update all tests that created PaperlessTask objects with old field names to use PaperlessTaskFactory and new field names (task_type, trigger_source, status, result_message). Use apply_async instead of delay where mocked. Drop TestCheckSanityTaskRecording — tests PaperlessTask creation that was intentionally removed from check_sanity(). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): improve test_api_tasks.py structure and add api marker - Move admin_client, v9_client, user_client fixtures to conftest.py so they can be reused by other API tests; all three now build on the rest_api_client fixture instead of creating APIClient() directly - Move regular_user fixture to conftest.py (was already done, now also used by the new client fixtures) - Add docstrings to every test method describing the behaviour under test - Move timedelta/timezone imports to module level - Register 'api' pytest marker in pyproject.toml and apply pytestmark to the entire file so all 40 tests are selectable via -m api Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor(tasks): simplify task tracking code after redesign - Extract COMPLETE_STATUSES as a class constant on PaperlessTask, eliminating the repeated status tuple across models.py, views.py (3×), and filters.py - Extract _CELERY_STATE_TO_STATUS as a module-level constant instead of rebuilding the dict on every task_postrun - Extract _V9_TYPE_TO_TRIGGER_SOURCE and _RUNNABLE_TASKS as class constants on TasksViewSet instead of rebuilding on every request - Extract _TRIGGER_SOURCE_TO_V9_TYPE as a class constant on TaskSerializerV9 instead of rebuilding per serialized object - Extract _get_consume_args helper to deduplicate identical arg extraction logic in _extract_input_data, _determine_trigger_source, and _extract_owner_id - Move inline imports (re, traceback) and Avg to module level - Fix _DOCUMENT_SOURCE_TO_TRIGGER type annotation key type to DocumentSource instead of Any - Remove redundant truthiness checks in SystemStatusView branches already guarded by an is-None check Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * refactor(tasks): add docstrings and rename _parse_legacy_result - Add docstrings to _extract_input_data, _determine_trigger_source, _extract_owner_id explaining what each helper does and why - Rename _parse_legacy_result -> _parse_consume_result: the function parses current consume_file string outputs (consumer.py returns "New document id N created" and "It is a duplicate of X (#N)"), not legacy data; the old name was misleading Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(tasks): extend and harden the task system redesign - TaskType: add EMPTY_TRASH, CHECK_WORKFLOWS, CLEANUP_SHARE_LINKS; remove INDEX_REBUILD (no backing task — beat schedule uses index_optimize) - TRACKED_TASKS: wire up all nine task types including the three new ones and llmindex_index / process_mail_accounts - Add task_revoked_handler so cancelled/expired tasks are marked REVOKED - Fix double-write: task_postrun_handler no longer overwrites result_data when status is already FAILURE (task_failure_handler owns that write) - v9 serialiser: map EMAIL_CONSUME and FOLDER_CONSUME to AUTO_TASK - views: scope task list to owner for regular users, admins see all; validate ?days= query param and return 400 on bad input - tests: add test_list_admin_sees_all_tasks; rename/fix test_parses_duplicate_string (duplicates produce SUCCESS, not FAILURE); use PaperlessTaskFactory in modified tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(tasks): fix MAIL_FETCH null input_data and postrun double-query - _extract_input_data: return {} instead of {"account_ids": None} when process_mail_accounts is called without an explicit account list (the normal beat-scheduled path); add test to cover this path - task_postrun_handler: replace filter().first() + filter().update() with get() + save(update_fields=[...]) — single fetch, single write, consistent with task_prerun_handler Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(tasks): add queryset stub to satisfy drf-spectacular schema generation TasksViewSet.get_queryset() accesses request.user, which drf-spectacular cannot provide during static schema generation. Adding a class-level queryset = PaperlessTask.objects.none() gives spectacular a model to introspect without invoking get_queryset(), eliminating both warnings and the test_valid_schema failure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): fill coverage gaps in task system - test_task_signals: add TestTaskRevokedHandler (marks REVOKED, ignores None request, ignores unknown id); switch existing direct PaperlessTask.objects.create calls to PaperlessTaskFactory; import pytest_mock and use MockerFixture typing on mocker params - test_api_tasks: add test_rejects_invalid_days_param to TestSummary - tasks.service.spec: add dismissAllTasks test (POST acknowledge_all + reload) - models: add pragma: no cover to __str__, is_complete, and related_document_ids (trivial delegates, covered indirectly) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Well, that was a bad push. * Fixes v9 API compatability with testing coverage * fix(tasks): restore INDEX_OPTIMIZE enum and remove no-op run button INDEX_OPTIMIZE was dropped from the TaskType enum but still referenced in _RUNNABLE_TASKS (views.py) and the frontend system-status-dialog, causing an AttributeError at import time. Restore the enum value in the model and migration so the serializer accepts it, but remove it from _RUNNABLE_TASKS since index_optimize is a Tantivy no-op. Remove the frontend "Run Task" button for index optimization accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(tasks): v9 type filter now matches all equivalent trigger sources The v9 ?type= query param mapped each value to a single TriggerSource, but the serializer maps multiple sources to the same v9 type value. A task serialized as "auto_task" would not appear when filtering by ?type=auto_task if its trigger_source was email_consume or folder_consume. Same issue for "manual_task" missing web_ui and api_upload sources. Changed to trigger_source__in with the full set of sources for each v9 type value. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(tasks): give task_failure_handler full ownership of FAILURE path task_postrun_handler now early-returns for FAILURE states instead of redundantly writing status and date_done. task_failure_handler now computes duration_seconds and wait_time_seconds so failed tasks get complete timing data. This eliminates a wasted .get() + .save() round trip on every failed task and gives each handler a clean, non-overlapping responsibility. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(tasks): resolve trigger_source header via TriggerSource enum lookup Replace two hardcoded string comparisons ("scheduled", "system") with a single TriggerSource(header_source) lookup so the enum values are the single source of truth. Any valid TriggerSource DB value passed in the header is accepted; invalid values fall through to the document-source / MANUAL logic. Update tests to pass enum values in headers rather than raw strings, and add a test for the invalid-header fallback path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(tasks): use TriggerSource enum values at all apply_async call sites Replace raw strings ("system", "manual") with PaperlessTask.TriggerSource enum values in the three callers that can import models. The settings file remains a raw string (models cannot be imported at settings load time) with a comment pointing to the enum value it must match. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test(tasks): parametrize repetitive test cases in task test files test_api_tasks.py: - Collapse six trigger_source->v9-type tests into one parametrized test, adding the previously untested API_UPLOAD case - Collapse three task_name mapping tests (two remaps + pass-through) into one parametrized test - Collapse two acknowledge_all status tests into one parametrized test - Collapse two run-endpoint 400 tests into one parametrized test - Update run/ assertions to use TriggerSource enum values test_task_signals.py: - Collapse three trigger_source header tests into one parametrized test - Collapse two DocumentSource->TriggerSource mapping tests into one parametrized test - Collapse two prerun ignore-invalid-id tests into one parametrized test All parametrize cases use pytest.param with descriptive ids. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Handle JSON serialization for datetime and Path. Further restrist the v9 permissions as Copilot suggests * That should fix the generated schema/browser * Use XSerializer for the schema * A few more basic cases I see no value in covering * Drops the migration related stuff too. Just in case we want it again or it confuses people * fix: annotate tasks_summary_retrieve as array of TaskSummarySerializer Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: annotate tasks_active_retrieve as array of TaskSerializerV10 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Restore task running to superuser only * Removes the acknowledge/dismiss all stuff * Aligns v10 and v9 task permissions with each other * Short blurb just to warn users about the tasks being cleared --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-09-05 09:25:03 +00:00 · 2026-04-20 09:28:41 -07:00
parent 20aa0937e8
commit 8e67828bd7
41 changed files with 2613 additions and 1230 deletions
@@ -13,6 +13,8 @@ from rest_framework.test import APIClient

 from documents.tests.factories import DocumentFactory

+UserModelT = get_user_model()
+
 if TYPE_CHECKING:
    from documents.models import Document

@@ -126,15 +128,34 @@ def rest_api_client():
    yield APIClient()


-@pytest.fixture
-def authenticated_rest_api_client(rest_api_client: APIClient):
-    """
-    The basic DRF ApiClient which has been authenticated
-    """
-    UserModel = get_user_model()
-    user = UserModel.objects.create_user(username="testuser", password="password")
-    rest_api_client.force_authenticate(user=user)
-    yield rest_api_client
+@pytest.fixture()
+def regular_user(django_user_model: type[UserModelT]) -> UserModelT:
+    """Unprivileged authenticated user for permission boundary tests."""
+    return django_user_model.objects.create_user(username="regular", password="regular")
+
+
+@pytest.fixture()
+def admin_client(rest_api_client: APIClient, admin_user: UserModelT) -> APIClient:
+    """Admin client pre-authenticated and sending the v10 Accept header."""
+    rest_api_client.force_authenticate(user=admin_user)
+    rest_api_client.credentials(HTTP_ACCEPT="application/json; version=10")
+    return rest_api_client
+
+
+@pytest.fixture()
+def v9_client(rest_api_client: APIClient, admin_user: UserModelT) -> APIClient:
+    """Admin client pre-authenticated and sending the v9 Accept header."""
+    rest_api_client.force_authenticate(user=admin_user)
+    rest_api_client.credentials(HTTP_ACCEPT="application/json; version=9")
+    return rest_api_client
+
+
+@pytest.fixture()
+def user_client(rest_api_client: APIClient, regular_user: UserModelT) -> APIClient:
+    """Regular-user client pre-authenticated and sending the v10 Accept header."""
+    rest_api_client.force_authenticate(user=regular_user)
+    rest_api_client.credentials(HTTP_ACCEPT="application/json; version=10")
+    return rest_api_client


@pytest.fixture(scope="session", autouse=True)
@@ -11,6 +11,7 @@ from documents.models import Correspondent
 from documents.models import Document
 from documents.models import DocumentType
 from documents.models import MatchingModel
+from documents.models import PaperlessTask
 from documents.models import StoragePath
 from documents.models import Tag

@@ -65,3 +66,17 @@ class DocumentFactory(DjangoModelFactory):
    correspondent = None
    document_type = None
    storage_path = None
+
+
+class PaperlessTaskFactory(DjangoModelFactory):
+    class Meta:
+        model = PaperlessTask
+
+    task_id = factory.Faker("uuid4")
+    task_type = PaperlessTask.TaskType.CONSUME_FILE
+    trigger_source = PaperlessTask.TriggerSource.WEB_UI
+    status = PaperlessTask.Status.PENDING
+    input_data = factory.LazyFunction(dict)
+    result_data = None
+    result_message = None
+    acknowledged = False
@@ -831,7 +831,7 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
        config.save()

        with (
-            patch("documents.tasks.llmindex_index.delay") as mock_update,
+            patch("documents.tasks.llmindex_index.apply_async") as mock_update,
            patch("paperless_ai.indexing.vector_store_file_exists") as mock_exists,
        ):
            mock_exists.return_value = False
@@ -1,5 +1,7 @@
+import pytest
 from django.core.management import call_command
 from django.core.management.base import CommandError
+from drf_spectacular.generators import SchemaGenerator
 from rest_framework import status
 from rest_framework.test import APITestCase

@@ -66,3 +68,57 @@ class TestApiSchema(APITestCase):
            "delete_pages",
        ]:
            self.assertIn(action_method, advertised_methods)
+
+
+# ---- session-scoped fixture: generate schema once for all TestXxx classes ----
+
+
+@pytest.fixture(scope="session")
+def api_schema():
+    generator = SchemaGenerator()
+    return generator.get_schema(request=None, public=True)
+
+
+class TestTasksSummarySchema:
+    """tasks_summary_retrieve: response must be an array of TaskSummarySerializer."""
+
+    def test_summary_response_is_array(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/summary/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        assert resp_200["type"] == "array", (
+            "tasks_summary_retrieve response must be type:array"
+        )
+
+    def test_summary_items_have_total_count(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/summary/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        items = resp_200.get("items", {})
+        ref = items.get("$ref", "")
+        component_name = ref.split("/")[-1] if ref else ""
+        if component_name:
+            props = api_schema["components"]["schemas"][component_name]["properties"]
+        else:
+            props = items.get("properties", {})
+        assert "total_count" in props, (
+            "summary items must have 'total_count' (TaskSummarySerializer)"
+        )
+
+
+class TestTasksActiveSchema:
+    """tasks_active_retrieve: response must be an array of TaskSerializerV10."""
+
+    def test_active_response_is_array(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/active/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        assert resp_200["type"] == "array", (
+            "tasks_active_retrieve response must be type:array"
+        )
+
+    def test_active_items_ref_named_schema(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/active/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        items = resp_200.get("items", {})
+        ref = items.get("$ref", "")
+        component_name = ref.split("/")[-1] if ref else ""
+        assert component_name, "items should be a $ref to a named schema"
+        assert component_name in api_schema["components"]["schemas"]
@@ -4,7 +4,6 @@ import tempfile
 from pathlib import Path
 from unittest import mock

-from celery import states
 from django.contrib.auth.models import Permission
 from django.contrib.auth.models import User
 from django.test import override_settings
@@ -13,6 +12,7 @@ from rest_framework.test import APITestCase

 from documents.models import PaperlessTask
 from documents.permissions import has_system_status_permission
+from documents.tests.factories import PaperlessTaskFactory
 from paperless import version


@@ -258,10 +258,10 @@ class TestSystemStatus(APITestCase):
        THEN:
            - The response contains an OK classifier status
        """
-        PaperlessTask.objects.create(
-            type=PaperlessTask.TaskType.SCHEDULED_TASK,
-            status=states.SUCCESS,
-            task_name=PaperlessTask.TaskName.TRAIN_CLASSIFIER,
+        PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.TRAIN_CLASSIFIER,
+            trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+            status=PaperlessTask.Status.SUCCESS,
        )
        self.client.force_login(self.user)
        response = self.client.get(self.ENDPOINT)
@@ -295,11 +295,11 @@ class TestSystemStatus(APITestCase):
        THEN:
            - The response contains an ERROR classifier status
        """
-        PaperlessTask.objects.create(
-            type=PaperlessTask.TaskType.SCHEDULED_TASK,
-            status=states.FAILURE,
-            task_name=PaperlessTask.TaskName.TRAIN_CLASSIFIER,
-            result="Classifier training failed",
+        PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.TRAIN_CLASSIFIER,
+            trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+            status=PaperlessTask.Status.FAILURE,
+            result_message="Classifier training failed",
        )
        self.client.force_login(self.user)
        response = self.client.get(self.ENDPOINT)
@@ -319,10 +319,10 @@ class TestSystemStatus(APITestCase):
        THEN:
            - The response contains an OK sanity check status
        """
-        PaperlessTask.objects.create(
-            type=PaperlessTask.TaskType.SCHEDULED_TASK,
-            status=states.SUCCESS,
-            task_name=PaperlessTask.TaskName.CHECK_SANITY,
+        PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.SANITY_CHECK,
+            trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+            status=PaperlessTask.Status.SUCCESS,
        )
        self.client.force_login(self.user)
        response = self.client.get(self.ENDPOINT)
@@ -356,11 +356,11 @@ class TestSystemStatus(APITestCase):
        THEN:
            - The response contains an ERROR sanity check status
        """
-        PaperlessTask.objects.create(
-            type=PaperlessTask.TaskType.SCHEDULED_TASK,
-            status=states.FAILURE,
-            task_name=PaperlessTask.TaskName.CHECK_SANITY,
-            result="5 issues found.",
+        PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.SANITY_CHECK,
+            trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+            status=PaperlessTask.Status.FAILURE,
+            result_message="5 issues found.",
        )
        self.client.force_login(self.user)
        response = self.client.get(self.ENDPOINT)
@@ -405,10 +405,10 @@ class TestSystemStatus(APITestCase):
            self.assertEqual(response.status_code, status.HTTP_200_OK)
            self.assertEqual(response.data["tasks"]["llmindex_status"], "WARNING")

-            PaperlessTask.objects.create(
-                type=PaperlessTask.TaskType.SCHEDULED_TASK,
-                status=states.SUCCESS,
-                task_name=PaperlessTask.TaskName.LLMINDEX_UPDATE,
+            PaperlessTaskFactory(
+                task_type=PaperlessTask.TaskType.LLM_INDEX,
+                trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+                status=PaperlessTask.Status.SUCCESS,
            )
            response = self.client.get(self.ENDPOINT)
            self.assertEqual(response.status_code, status.HTTP_200_OK)
@@ -425,11 +425,11 @@ class TestSystemStatus(APITestCase):
            - The response contains the correct AI status
        """
        with override_settings(AI_ENABLED=True, LLM_EMBEDDING_BACKEND="openai"):
-            PaperlessTask.objects.create(
-                type=PaperlessTask.TaskType.SCHEDULED_TASK,
-                status=states.FAILURE,
-                task_name=PaperlessTask.TaskName.LLMINDEX_UPDATE,
-                result="AI index update failed",
+            PaperlessTaskFactory(
+                task_type=PaperlessTask.TaskType.LLM_INDEX,
+                trigger_source=PaperlessTask.TriggerSource.SCHEDULED,
+                status=PaperlessTask.Status.FAILURE,
+                result_message="AI index update failed",
            )
            self.client.force_login(self.user)
            response = self.client.get(self.ENDPOINT)
@@ -211,7 +211,7 @@ class TestCreateClassifier:

        call_command("document_create_classifier", skip_checks=True)

-        m.assert_called_once_with(scheduled=False, status_callback=mocker.ANY)
+        m.assert_called_once_with(status_callback=mocker.ANY)
        assert callable(m.call_args.kwargs["status_callback"])

    def test_create_classifier_callback_output(self, mocker: MockerFixture) -> None:
@@ -1,7 +1,7 @@
 """Tests for the sanity checker module.

 Tests exercise ``check_sanity`` as a whole, verifying document validation,
-orphan detection, task recording, and the iter_wrapper contract.
+orphan detection, and the iter_wrapper contract.
 """

 from __future__ import annotations
@@ -12,13 +12,12 @@ from typing import TYPE_CHECKING

 import pytest

-from documents.models import Document
-from documents.models import PaperlessTask
 from documents.sanity_checker import check_sanity

 if TYPE_CHECKING:
    from collections.abc import Iterable

+    from documents.models import Document
    from documents.tests.conftest import PaperlessDirs


@@ -229,35 +228,6 @@ class TestCheckSanityIterWrapper:
        assert not messages.has_error


-@pytest.mark.django_db
-class TestCheckSanityTaskRecording:
-    @pytest.mark.parametrize(
-        ("expected_type", "scheduled"),
-        [
-            pytest.param(PaperlessTask.TaskType.SCHEDULED_TASK, True, id="scheduled"),
-            pytest.param(PaperlessTask.TaskType.MANUAL_TASK, False, id="manual"),
-        ],
-    )
-    @pytest.mark.usefixtures("_media_settings")
-    def test_task_type(self, expected_type: str, *, scheduled: bool) -> None:
-        check_sanity(scheduled=scheduled)
-        task = PaperlessTask.objects.latest("date_created")
-        assert task.task_name == PaperlessTask.TaskName.CHECK_SANITY
-        assert task.type == expected_type
-
-    def test_success_status(self, sample_doc: Document) -> None:
-        check_sanity()
-        task = PaperlessTask.objects.latest("date_created")
-        assert task.status == "SUCCESS"
-
-    def test_failure_status(self, sample_doc: Document) -> None:
-        Path(sample_doc.source_path).unlink()
-        check_sanity()
-        task = PaperlessTask.objects.latest("date_created")
-        assert task.status == "FAILURE"
-        assert "Check logs for details" in task.result
-
-
@pytest.mark.django_db
 class TestCheckSanityLogMessages:
    def test_logs_doc_issues(
@@ -1,250 +1,390 @@
+import datetime
+import sys
 import uuid
+from pathlib import Path
 from unittest import mock

-import celery
-from django.contrib.auth import get_user_model
-from django.test import TestCase
+import pytest
+import pytest_mock
+from django.utils import timezone

 from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
 from documents.data_models import DocumentSource
-from documents.models import Document
 from documents.models import PaperlessTask
-from documents.signals.handlers import add_to_index
 from documents.signals.handlers import before_task_publish_handler
 from documents.signals.handlers import task_failure_handler
 from documents.signals.handlers import task_postrun_handler
 from documents.signals.handlers import task_prerun_handler
-from documents.tests.test_consumer import fake_magic_from_file
-from documents.tests.utils import DirectoriesMixin
+from documents.signals.handlers import task_revoked_handler
+from documents.tests.factories import PaperlessTaskFactory


-@mock.patch("documents.consumer.magic.from_file", fake_magic_from_file)
-class TestTaskSignalHandler(DirectoriesMixin, TestCase):
-    @classmethod
-    def setUpTestData(cls) -> None:
-        super().setUpTestData()
-        cls.user = get_user_model().objects.create_user(username="testuser")
+@pytest.fixture
+def consume_input_doc():
+    doc = mock.MagicMock(spec=ConsumableDocument)
+    # original_file is a Path; configure the nested mock so .name works
+    doc.original_file = mock.MagicMock()
+    doc.original_file.name = "invoice.pdf"
+    doc.original_path = None
+    doc.mime_type = "application/pdf"
+    doc.mailrule_id = None
+    doc.source = DocumentSource.WebUI
+    return doc

-    def util_call_before_task_publish_handler(
+
+@pytest.fixture
+def consume_overrides(django_user_model):
+    user = django_user_model.objects.create_user(username="testuser")
+    overrides = mock.MagicMock(spec=DocumentMetadataOverrides)
+    overrides.owner_id = user.id
+    return overrides
+
+
+def send_publish(
+    task_name: str,
+    args: tuple,
+    kwargs: dict,
+    headers: dict | None = None,
+) -> str:
+
+    task_id = str(uuid.uuid4())
+    hdrs = {"task": task_name, "id": task_id, **(headers or {})}
+    before_task_publish_handler(sender=task_name, headers=hdrs, body=(args, kwargs, {}))
+    return task_id
+
+
+@pytest.mark.django_db
+class TestBeforeTaskPublishHandler:
+    def test_creates_task_for_consume_file(self, consume_input_doc, consume_overrides):
+        task_id = send_publish(
+            "documents.tasks.consume_file",
+            (consume_input_doc, consume_overrides),
+            {},
+        )
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.task_type == PaperlessTask.TaskType.CONSUME_FILE
+        assert task.status == PaperlessTask.Status.PENDING
+        assert task.trigger_source == PaperlessTask.TriggerSource.WEB_UI
+        assert task.input_data["filename"] == "invoice.pdf"
+        assert task.owner_id == consume_overrides.owner_id
+
+    def test_creates_task_for_train_classifier(self):
+        task_id = send_publish("documents.tasks.train_classifier", (), {})
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.task_type == PaperlessTask.TaskType.TRAIN_CLASSIFIER
+        assert task.trigger_source == PaperlessTask.TriggerSource.MANUAL
+
+    def test_creates_task_for_sanity_check(self):
+        task_id = send_publish("documents.tasks.sanity_check", (), {})
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.task_type == PaperlessTask.TaskType.SANITY_CHECK
+
+    def test_creates_task_for_process_mail_accounts(self):
+        task_id = send_publish(
+            "paperless_mail.tasks.process_mail_accounts",
+            (),
+            {"account_ids": [1, 2]},
+        )
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.task_type == PaperlessTask.TaskType.MAIL_FETCH
+        assert task.input_data["account_ids"] == [1, 2]
+
+    def test_mail_fetch_no_account_ids_stores_empty_input(self):
+        """Beat-scheduled mail checks pass no account_ids; input_data should be {} not {"account_ids": None}."""
+        task_id = send_publish("paperless_mail.tasks.process_mail_accounts", (), {})
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.input_data == {}
+
+    def test_overrides_date_serialized_as_iso_string(self, consume_input_doc):
+        """A datetime.date in overrides is stored as an ISO string so input_data is JSON-safe."""
+        overrides = DocumentMetadataOverrides(created=datetime.date(2024, 1, 15))
+
+        task_id = send_publish(
+            "documents.tasks.consume_file",
+            (consume_input_doc, overrides),
+            {},
+        )
+
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.input_data["overrides"]["created"] == "2024-01-15"
+
+    def test_overrides_path_serialized_as_string(self, consume_input_doc):
+        """A Path value in overrides is stored as a plain string so input_data is JSON-safe."""
+        overrides = DocumentMetadataOverrides()
+        overrides.filename = Path("/uploads/invoice.pdf")  # type: ignore[assignment]
+
+        task_id = send_publish(
+            "documents.tasks.consume_file",
+            (consume_input_doc, overrides),
+            {},
+        )
+
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.input_data["overrides"]["filename"] == "/uploads/invoice.pdf"
+
+    @pytest.mark.parametrize(
+        ("header_value", "expected_trigger_source"),
+        [
+            pytest.param(
+                PaperlessTask.TriggerSource.SCHEDULED,
+                PaperlessTask.TriggerSource.SCHEDULED,
+                id="scheduled",
+            ),
+            pytest.param(
+                PaperlessTask.TriggerSource.SYSTEM,
+                PaperlessTask.TriggerSource.SYSTEM,
+                id="system",
+            ),
+            pytest.param(
+                "bogus_value",
+                PaperlessTask.TriggerSource.MANUAL,
+                id="invalid-falls-back-to-manual",
+            ),
+        ],
+    )
+    def test_trigger_source_header_resolution(
        self,
-        headers_to_use,
-        body_to_use,
+        header_value: str,
+        expected_trigger_source: PaperlessTask.TriggerSource,
    ) -> None:
-        """
-        Simple utility to call the pre-run handle and ensure it created a single task
-        instance
-        """
-        self.assertEqual(PaperlessTask.objects.all().count(), 0)
-
-        before_task_publish_handler(headers=headers_to_use, body=body_to_use)
-
-        self.assertEqual(PaperlessTask.objects.all().count(), 1)
-
-    def test_before_task_publish_handler_consume(self) -> None:
-        """
-        GIVEN:
-            - A celery task is started via the consume folder
-        WHEN:
-            - Task before publish handler is called
-        THEN:
-            - The task is created and marked as pending
-        """
-        headers = {
-            "id": str(uuid.uuid4()),
-            "task": "documents.tasks.consume_file",
-        }
-        body = (
-            # args
-            (
-                ConsumableDocument(
-                    source=DocumentSource.ConsumeFolder,
-                    original_file="/consume/hello-999.pdf",
-                ),
-                DocumentMetadataOverrides(
-                    title="Hello world",
-                    owner_id=self.user.id,
-                ),
-            ),
-            # kwargs
+        """trigger_source header maps to the expected TriggerSource; invalid values fall back to MANUAL."""
+        task_id = send_publish(
+            "documents.tasks.train_classifier",
+            (),
            {},
-            # celery stuff
-            {"callbacks": None, "errbacks": None, "chain": None, "chord": None},
-        )
-        self.util_call_before_task_publish_handler(
-            headers_to_use=headers,
-            body_to_use=body,
+            headers={"trigger_source": header_value},
        )
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.trigger_source == expected_trigger_source

-        task = PaperlessTask.objects.get()
-        self.assertIsNotNone(task)
-        self.assertEqual(headers["id"], task.task_id)
-        self.assertEqual("hello-999.pdf", task.task_file_name)
-        self.assertEqual(PaperlessTask.TaskName.CONSUME_FILE, task.task_name)
-        self.assertEqual(self.user.id, task.owner_id)
-        self.assertEqual(celery.states.PENDING, task.status)
+    def test_ignores_untracked_task(self):
+        send_publish("documents.tasks.some_untracked_task", (), {})
+        assert PaperlessTask.objects.count() == 0

-    def test_task_prerun_handler(self) -> None:
-        """
-        GIVEN:
-            - A celery task is started via the consume folder
-        WHEN:
-            - Task starts execution
-        THEN:
-            - The task is marked as started
-        """
+    def test_ignores_none_headers(self):

-        headers = {
-            "id": str(uuid.uuid4()),
-            "task": "documents.tasks.consume_file",
-        }
-        body = (
-            # args
-            (
-                ConsumableDocument(
-                    source=DocumentSource.ConsumeFolder,
-                    original_file="/consume/hello-99.pdf",
-                ),
-                None,
+        before_task_publish_handler(sender=None, headers=None, body=None)
+        assert PaperlessTask.objects.count() == 0
+
+    @pytest.mark.parametrize(
+        ("document_source", "expected_trigger_source"),
+        [
+            pytest.param(
+                DocumentSource.ConsumeFolder,
+                PaperlessTask.TriggerSource.FOLDER_CONSUME,
+                id="folder_consume",
            ),
-            # kwargs
-            {},
-            # celery stuff
-            {"callbacks": None, "errbacks": None, "chain": None, "chord": None},
-        )
-
-        self.util_call_before_task_publish_handler(
-            headers_to_use=headers,
-            body_to_use=body,
-        )
-
-        task_prerun_handler(task_id=headers["id"])
-
-        task = PaperlessTask.objects.get()
-
-        self.assertEqual(celery.states.STARTED, task.status)
-
-    def test_task_postrun_handler(self) -> None:
-        """
-        GIVEN:
-            - A celery task is started via the consume folder
-        WHEN:
-            - Task finished execution
-        THEN:
-            - The task is marked as started
-        """
-        headers = {
-            "id": str(uuid.uuid4()),
-            "task": "documents.tasks.consume_file",
-        }
-        body = (
-            # args
-            (
-                ConsumableDocument(
-                    source=DocumentSource.ConsumeFolder,
-                    original_file="/consume/hello-9.pdf",
-                ),
-                None,
+            pytest.param(
+                DocumentSource.MailFetch,
+                PaperlessTask.TriggerSource.EMAIL_CONSUME,
+                id="email_consume",
            ),
-            # kwargs
+        ],
+    )
+    def test_consume_document_source_maps_to_trigger_source(
+        self,
+        consume_input_doc,
+        consume_overrides,
+        document_source: DocumentSource,
+        expected_trigger_source: PaperlessTask.TriggerSource,
+    ) -> None:
+        """DocumentSource on the input doc maps to the correct TriggerSource."""
+        consume_input_doc.source = document_source
+        task_id = send_publish(
+            "documents.tasks.consume_file",
+            (consume_input_doc, consume_overrides),
            {},
-            # celery stuff
-            {"callbacks": None, "errbacks": None, "chain": None, "chord": None},
        )
-        self.util_call_before_task_publish_handler(
-            headers_to_use=headers,
-            body_to_use=body,
+        task = PaperlessTask.objects.get(task_id=task_id)
+        assert task.trigger_source == expected_trigger_source
+
+
+@pytest.mark.django_db
+class TestTaskPrerunHandler:
+    def test_marks_task_started(self):
+        task = PaperlessTaskFactory(status=PaperlessTask.Status.PENDING)
+
+        task_prerun_handler(task_id=task.task_id)
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.STARTED
+        assert task.date_started is not None
+
+    @pytest.mark.parametrize(
+        "task_id",
+        [
+            pytest.param("nonexistent-id", id="unknown"),
+            pytest.param(None, id="none"),
+        ],
+    )
+    def test_ignores_invalid_task_id(self, task_id: str | None) -> None:
+
+        task_prerun_handler(task_id=task_id)  # must not raise
+
+
+@pytest.mark.django_db
+class TestTaskPostrunHandler:
+    def _started_task(self) -> PaperlessTask:
+
+        return PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.TRAIN_CLASSIFIER,
+            status=PaperlessTask.Status.STARTED,
+            date_started=timezone.now(),
        )

+    def test_records_success_with_dict_result(self):
+        task = self._started_task()
+
        task_postrun_handler(
-            task_id=headers["id"],
-            retval="Success. New document id 1 created",
-            state=celery.states.SUCCESS,
+            task_id=task.task_id,
+            retval={"document_id": 42},
+            state="SUCCESS",
        )
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.SUCCESS
+        assert task.result_data == {"document_id": 42}
+        assert task.date_done is not None
+        assert task.duration_seconds is not None
+        assert task.wait_time_seconds is not None

-        task = PaperlessTask.objects.get()
+    def test_skips_failure_state(self):
+        """postrun skips FAILURE; task_failure_handler owns that path."""
+        task = self._started_task()

-        self.assertEqual(celery.states.SUCCESS, task.status)
+        task_postrun_handler(task_id=task.task_id, retval="some error", state="FAILURE")
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.STARTED

-    def test_task_failure_handler(self) -> None:
-        """
-        GIVEN:
-            - A celery task is started via the consume folder
-        WHEN:
-            - Task failed execution
-        THEN:
-            - The task is marked as failed
-        """
-        headers = {
-            "id": str(uuid.uuid4()),
-            "task": "documents.tasks.consume_file",
-        }
-        body = (
-            # args
-            (
-                ConsumableDocument(
-                    source=DocumentSource.ConsumeFolder,
-                    original_file="/consume/hello-9.pdf",
-                ),
-                None,
-            ),
-            # kwargs
-            {},
-            # celery stuff
-            {"callbacks": None, "errbacks": None, "chain": None, "chord": None},
+    def test_parses_legacy_new_document_string(self):
+        task = self._started_task()
+
+        task_postrun_handler(
+            task_id=task.task_id,
+            retval="New document id 42 created",
+            state="SUCCESS",
        )
-        self.util_call_before_task_publish_handler(
-            headers_to_use=headers,
-            body_to_use=body,
+        task.refresh_from_db()
+        assert task.result_data["document_id"] == 42
+        assert task.result_message == "New document id 42 created"
+
+    def test_parses_duplicate_string(self):
+        """Duplicate detection returns a string with SUCCESS state (StopConsumeTaskError is caught and returned, not raised)."""
+        task = self._started_task()
+
+        task_postrun_handler(
+            task_id=task.task_id,
+            retval="It is a duplicate of some document (#99).",
+            state="SUCCESS",
+        )
+        task.refresh_from_db()
+        assert task.result_data["duplicate_of"] == 99
+        assert task.result_data["duplicate_in_trash"] is False
+
+    def test_ignores_unknown_task_id(self):
+
+        task_postrun_handler(
+            task_id="nonexistent",
+            retval=None,
+            state="SUCCESS",
+        )  # must not raise
+
+    def test_records_revoked_state(self):
+        task = self._started_task()
+
+        task_postrun_handler(task_id=task.task_id, retval=None, state="REVOKED")
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.REVOKED
+
+
+@pytest.mark.django_db
+class TestTaskFailureHandler:
+    def test_records_failure_with_exception(self):
+
+        task = PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.CONSUME_FILE,
+            status=PaperlessTask.Status.STARTED,
+            date_started=timezone.now(),
        )

        task_failure_handler(
-            task_id=headers["id"],
-            exception="Example failure",
+            task_id=task.task_id,
+            exception=ValueError("PDF parse failed"),
+            traceback=None,
+        )
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.FAILURE
+        assert task.result_data["error_type"] == "ValueError"
+        assert task.result_data["error_message"] == "PDF parse failed"
+        assert task.date_done is not None
+
+    def test_records_traceback_when_provided(self):
+
+        task = PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.CONSUME_FILE,
+            status=PaperlessTask.Status.STARTED,
+            date_started=timezone.now(),
+        )
+        try:
+            raise ValueError("test error")
+        except ValueError:
+            tb = sys.exc_info()[2]
+
+        from documents.signals.handlers import task_failure_handler
+
+        task_failure_handler(
+            task_id=task.task_id,
+            exception=ValueError("test error"),
+            traceback=tb,
+        )
+        task.refresh_from_db()
+        assert "traceback" in task.result_data
+        assert len(task.result_data["traceback"]) <= 5000
+
+    def test_computes_duration_and_wait_time(self):
+
+        now = timezone.now()
+        task = PaperlessTaskFactory(
+            task_type=PaperlessTask.TaskType.CONSUME_FILE,
+            status=PaperlessTask.Status.STARTED,
+            date_created=now - timezone.timedelta(seconds=10),
+            date_started=now - timezone.timedelta(seconds=5),
        )

-        task = PaperlessTask.objects.get()
-
-        self.assertEqual(celery.states.FAILURE, task.status)
-
-    def test_add_to_index_indexes_root_once_for_root_documents(self) -> None:
-        root = Document.objects.create(
-            title="root",
-            checksum="root",
-            mime_type="application/pdf",
+        task_failure_handler(
+            task_id=task.task_id,
+            exception=ValueError("boom"),
+            traceback=None,
        )
+        task.refresh_from_db()
+        assert task.duration_seconds == pytest.approx(5.0, abs=1.0)
+        assert task.wait_time_seconds == pytest.approx(5.0, abs=1.0)

-        with mock.patch("documents.search.get_backend") as mock_get_backend:
-            mock_backend = mock.MagicMock()
-            mock_get_backend.return_value = mock_backend
-            add_to_index(sender=None, document=root)
+    def test_ignores_none_task_id(self):

-        mock_backend.add_or_update.assert_called_once_with(root, effective_content="")
+        task_failure_handler(task_id=None, exception=ValueError("x"), traceback=None)

-    def test_add_to_index_reindexes_root_for_version_documents(self) -> None:
-        root = Document.objects.create(
-            title="root",
-            checksum="root",
-            mime_type="application/pdf",
-        )
-        version = Document.objects.create(
-            title="version",
-            checksum="version",
-            mime_type="application/pdf",
-            root_document=root,
-        )

-        with mock.patch("documents.search.get_backend") as mock_get_backend:
-            mock_backend = mock.MagicMock()
-            mock_get_backend.return_value = mock_backend
-            add_to_index(sender=None, document=version)
+@pytest.mark.django_db
+class TestTaskRevokedHandler:
+    def test_marks_task_revoked(self, mocker: pytest_mock.MockerFixture):
+        """task_revoked_handler moves a queued task to REVOKED and stamps date_done."""
+        task = PaperlessTaskFactory(status=PaperlessTask.Status.PENDING)
+        request = mocker.MagicMock()
+        request.id = task.task_id

-        self.assertEqual(mock_backend.add_or_update.call_count, 1)
-        self.assertEqual(
-            mock_backend.add_or_update.call_args_list[0].args[0].id,
-            version.id,
-        )
-        self.assertEqual(
-            mock_backend.add_or_update.call_args_list[0].kwargs,
-            {"effective_content": version.content},
-        )
+        task_revoked_handler(request=request)
+        task.refresh_from_db()
+        assert task.status == PaperlessTask.Status.REVOKED
+        assert task.date_done is not None
+
+    def test_ignores_none_request(self):
+        """task_revoked_handler must not raise when request is None."""
+
+        task_revoked_handler(request=None)  # must not raise
+
+    def test_ignores_unknown_task_id(self, mocker: pytest_mock.MockerFixture):
+        """task_revoked_handler must not raise for a task_id not in the database."""
+        request = mocker.MagicMock()
+        request.id = "nonexistent-id"
+
+        task_revoked_handler(request=request)  # must not raise
@@ -4,7 +4,6 @@ from pathlib import Path
 from unittest import mock

 import pytest
-from celery import states
 from django.conf import settings
 from django.test import TestCase
 from django.test import override_settings
@@ -14,7 +13,6 @@ from documents import tasks
 from documents.models import Correspondent
 from documents.models import Document
 from documents.models import DocumentType
-from documents.models import PaperlessTask
 from documents.models import Tag
 from documents.sanity_checker import SanityCheckFailedException
 from documents.sanity_checker import SanityCheckMessages
@@ -40,7 +38,8 @@ class TestClassifier(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
    def test_train_classifier_with_auto_tag(self, load_classifier) -> None:
        load_classifier.return_value = None
        Tag.objects.create(matching_algorithm=Tag.MATCH_AUTO, name="test")
-        tasks.train_classifier()
+        with self.assertRaises(ValueError):
+            tasks.train_classifier()
        load_classifier.assert_called_once()
        self.assertIsNotFile(settings.MODEL_FILE)

@@ -48,7 +47,8 @@ class TestClassifier(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
    def test_train_classifier_with_auto_type(self, load_classifier) -> None:
        load_classifier.return_value = None
        DocumentType.objects.create(matching_algorithm=Tag.MATCH_AUTO, name="test")
-        tasks.train_classifier()
+        with self.assertRaises(ValueError):
+            tasks.train_classifier()
        load_classifier.assert_called_once()
        self.assertIsNotFile(settings.MODEL_FILE)

@@ -56,7 +56,8 @@ class TestClassifier(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
    def test_train_classifier_with_auto_correspondent(self, load_classifier) -> None:
        load_classifier.return_value = None
        Correspondent.objects.create(matching_algorithm=Tag.MATCH_AUTO, name="test")
-        tasks.train_classifier()
+        with self.assertRaises(ValueError):
+            tasks.train_classifier()
        load_classifier.assert_called_once()
        self.assertIsNotFile(settings.MODEL_FILE)

@@ -298,7 +299,7 @@ class TestAIIndex(DirectoriesMixin, TestCase):
        WHEN:
            - llmindex_index task is called
        THEN:
-            - update_llm_index is called, and the task is marked as success
+            - update_llm_index is called and its result is returned
        """
        Document.objects.create(
            title="test",
@@ -308,13 +309,9 @@ class TestAIIndex(DirectoriesMixin, TestCase):
        # lazy-loaded so mock the actual function
        with mock.patch("paperless_ai.indexing.update_llm_index") as update_llm_index:
            update_llm_index.return_value = "LLM index updated successfully."
-            tasks.llmindex_index()
+            result = tasks.llmindex_index()
            update_llm_index.assert_called_once()
-            task = PaperlessTask.objects.get(
-                task_name=PaperlessTask.TaskName.LLMINDEX_UPDATE,
-            )
-            self.assertEqual(task.status, states.SUCCESS)
-            self.assertEqual(task.result, "LLM index updated successfully.")
+            self.assertEqual(result, "LLM index updated successfully.")

    @override_settings(
        AI_ENABLED=True,
@@ -325,9 +322,9 @@ class TestAIIndex(DirectoriesMixin, TestCase):
        GIVEN:
            - Document exists, AI is enabled, llm index backend is set
        WHEN:
-            - llmindex_index task is called
+            - llmindex_index task is called and update_llm_index raises an exception
        THEN:
-            - update_llm_index raises an exception, and the task is marked as failure
+            - the exception propagates to the caller
        """
        Document.objects.create(
            title="test",
@@ -337,13 +334,9 @@ class TestAIIndex(DirectoriesMixin, TestCase):
        # lazy-loaded so mock the actual function
        with mock.patch("paperless_ai.indexing.update_llm_index") as update_llm_index:
            update_llm_index.side_effect = Exception("LLM index update failed.")
-            tasks.llmindex_index()
+            with self.assertRaisesRegex(Exception, "LLM index update failed."):
+                tasks.llmindex_index()
            update_llm_index.assert_called_once()
-            task = PaperlessTask.objects.get(
-                task_name=PaperlessTask.TaskName.LLMINDEX_UPDATE,
-            )
-            self.assertEqual(task.status, states.FAILURE)
-            self.assertIn("LLM index update failed.", task.result)

    def test_update_document_in_llm_index(self) -> None:
        """