fix: harden dispatch id validation and priority docs

Author: clean6378-max-it

docs/architecture.md

@@ -105,7 +105,7 @@ The UI is a **hash-routed** SPA with ES modules under `static/js/`:
 
 - `app.js` — routing and boot
 - `projects.js`, `sessions.js`, `search.js`, `export.js` — route handlers
-- `render/registry.js` — **tool dispatch registry** for session UI: `TOOL_USE_RENDERERS` and `TOOL_RESULT_RENDERERS` map tool name / `result_type` → render function (one module per type under `render/tool_use/` and `render/tool_result/`). Parallels backend `utils/tool_dispatch.py` (backend uses ordered predicates; frontend uses direct key lookup + fallback).
+- `render/registry.js` — **tool dispatch registry** for session UI: `TOOL_USE_RENDERERS` and `TOOL_RESULT_RENDERERS` map tool name / `result_type` → render function (one module per type under `render/tool_use/` and `render/tool_result/`). Parallels backend `utils/tool_dispatch.py` (backend uses priority-based predicate matching; frontend uses direct key lookup + fallback).
 - `static/tool_types.json` — generated manifest of backend tool-use names (`python scripts/gen_tool_types_manifest.py` from `KNOWN_TOOL_TYPES`). Fetched non-blocking at boot by `render/tool_types_manifest.js` (`void initToolTypesManifest()` in `app.js`), which cross-checks `TOOL_USE_RENDERERS` and logs `console.warn` on drift.
 - `shared/markdown.js` — markdown + **DOMPurify** sanitization (do not render raw LLM HTML)
 - `shared/state.js`, `shared/utils.js`, `shared/theme.js` — shared UI state and helpers

tests/test_real_session_fixtures.py

@@ -142,11 +142,12 @@ def test_task_retrieval_not_misclassified_as_task_message() -> None:
 
 
 def test_task_completed_with_message_key_matches_task_message_first() -> None:
-    """Legacy dispatch: broad task_message runs before task_completed when ``message`` present.
+    """task_message outranks task_completed when ``message`` key is present.
 
     ``is_task_message_tool_result`` matches any dict with a ``message`` or ``task_id``
-    key. Future tool shapes that add ``message`` for status text (e.g. web-fetch) would
-    be misclassified as task until dispatch order is refined — this test locks that
+    key and holds priority 1, beating the narrower task predicates at priority 0.
+    Future tool shapes that add ``message`` for status text (e.g. web-fetch) would
+    be misclassified as task unless given higher priority — this test locks that
     known false-positive surface.
     """
     tr = {

utils/tool_dispatch.py

@@ -187,7 +187,8 @@ def _tool_result_build_task_retrieval(
     tr: ToolResultDict, base: dict[str, object]
 ) -> dict[str, object]:
     result = dict(base)
-    task_obj = tr["task"] if isinstance(tr["task"], dict) else {}
+    raw_task = tr.get("task")
+    task_obj = raw_task if isinstance(raw_task, dict) else {}
     result["result_type"] = "task"
     result["retrieval_status"] = tr.get("retrieval_status")
     result["task_id"] = task_obj.get("task_id")
@@ -266,7 +267,23 @@ def _tool_result_build_user_input(tr: ToolResultDict, base: dict[str, object]) -
     ToolResultDispatchEntry("user_input", is_user_input_tool_result, _tool_result_build_user_input),
 )
 
-_DISPATCH_ORDER = {entry.id: index for index, entry in enumerate(_TOOL_RESULT_DISPATCH)}
+
+def _validate_dispatch_ids(
+    table: tuple[ToolResultDispatchEntry, ...],
+) -> dict[str, int]:
+    """Fail fast on duplicate entry IDs and return the registration-order index."""
+    order: dict[str, int] = {}
+    for index, entry in enumerate(table):
+        if entry.id in order:
+            raise ValueError(
+                f"duplicate ToolResultDispatchEntry id {entry.id!r} "
+                f"(indices {order[entry.id]} and {index})"
+            )
+        order[entry.id] = index
+    return order
+
+
+_DISPATCH_ORDER = _validate_dispatch_ids(_TOOL_RESULT_DISPATCH)
 
 # Claude Code assistant tool_use ``name`` values coordinated across parser file
 # activity, Markdown export, and the SPA ``TOOL_USE_RENDERERS`` map.
@@ -343,9 +360,10 @@ def _winning_dispatch_entry(tr: ToolResultDict) -> ToolResultDispatchEntry | Non
     matches = _matching_dispatch_entries(tr)
     if not matches:
         return None
+    order = _validate_dispatch_ids(_TOOL_RESULT_DISPATCH)
     return max(
         matches,
-        key=lambda entry: (entry.priority, -_DISPATCH_ORDER[entry.id]),
+        key=lambda entry: (entry.priority, -order[entry.id]),
     )