fix: skip metadata-only JSONL entry types in role fallback path

Author: clean6378-max-it

tests/test_jsonl_parser.py

@@ -686,22 +686,6 @@ def test_empty_file_returns_skeleton(self):
         finally:
             os.unlink(path)
 
-    def test_unknown_entry_type_maps_to_system(self, caplog):
-        path = _write_jsonl(
-            [
-                {"type": "custom", "timestamp": "2026-01-01T00:00:00Z"},
-            ]
-        )
-        try:
-            with caplog.at_level("WARNING"):
-                s = parse_session(path)
-            assert len(s["messages"]) == 1
-            assert s["messages"][0]["role"] == "system"
-            assert s["metadata"]["entry_counts"].get("custom") == 1
-            assert "Unknown message role" in caplog.text
-        finally:
-            os.unlink(path)
-
     def test_is_sidechain_increments_counter(self):
         path = _write_jsonl(
             [
@@ -732,6 +716,7 @@ def test_file_history_snapshot_timestamp(self):
             s = parse_session(path)
             assert s["metadata"]["first_timestamp"] == "2026-01-02T12:00:00Z"
             assert s["metadata"]["last_timestamp"] == "2026-01-02T12:00:00Z"
+            assert len(s["messages"]) == 0
         finally:
             os.unlink(path)
 

tests/test_jsonl_validation.py

@@ -70,6 +70,12 @@ def test_valid_payload_returns_session_dict(self):
         assert result["session_id"] == "abc123"
         assert result["messages"][0]["role"] == "user"
 
+    def test_invalid_role_in_message(self):
+        with pytest.raises(SessionValidationError) as exc_info:
+            validate_session_dict(_valid_payload(messages=[{"role": "custom", "text": "x"}]))
+        assert exc_info.value.path == "messages[0].role"
+        assert "custom" in exc_info.value.detail
+
 
 class TestParseSessionValidationRegression:
     def test_session_minimal_fixture_unchanged(self):

utils/jsonl_parser.py

@@ -25,6 +25,7 @@
 __all__ = ["parse_session", "quick_session_info"]
 
 _HANDLED_ENTRY_TYPES = frozenset({"user", "assistant", "system", "progress"})
+_SKIP_ENTRY_TYPES = frozenset({"file-history-snapshot"})
 _VALID_ROLES = frozenset(get_args(RoleLiteral))
 
 
@@ -154,7 +155,7 @@ def parse_session(filepath: str) -> SessionDict:
                 _process_progress(entry, messages)
             elif entry_type:
                 type_str = entry_type if isinstance(entry_type, str) else str(entry_type)
-                if type_str not in _HANDLED_ENTRY_TYPES:
+                if type_str not in _HANDLED_ENTRY_TYPES and type_str not in _SKIP_ENTRY_TYPES:
                     messages.append(_fallback_message(entry, _coerce_role(type_str)))
 
     metadata["models_used"] = sorted(metadata["models_used"])

utils/validation.py

@@ -1,9 +1,11 @@
 """Runtime validation for TypedDict shapes at untrusted-data boundaries."""
 
-from typing import Any, cast
+from typing import Any, cast, get_args
 
 from models.errors import SessionValidationError
-from models.session import SessionDict
+from models.session import RoleLiteral, SessionDict
+
+_VALID_ROLES = frozenset(get_args(RoleLiteral))
 
 _ROOT_PATH = "(root)"
 
@@ -49,6 +51,11 @@ def validate_session_dict(data: dict[str, Any]) -> SessionDict:
     for index, message in enumerate(messages):
         path = f"messages[{index}]"
         msg_dict = _require_value(path, message, dict, "dict")
-        _require_field(msg_dict, "role", str, "str", path=f"{path}.role")
+        role = _require_field(msg_dict, "role", str, "str", path=f"{path}.role")
+        if role not in _VALID_ROLES:
+            raise SessionValidationError(
+                f"{path}.role",
+                f"expected one of {sorted(_VALID_ROLES)!r}, got {role!r}",
+            )
 
     return cast(SessionDict, data)