fix(export): cap X-Export-Warnings header and sanitize failure messages

Author: clean6378-max-it

api/export_api.py

@@ -37,6 +37,10 @@
 # Tests monkeypatch this path; keep in sync with utils.export_state_store.
 _STATE_FILE = EXPORT_STATE_FILE
 
+_EXPORT_WARNINGS_ZIP_NAME = "export-warnings.json"
+_EXPORT_WARNINGS_HEADER_MAX_ENTRIES = 20
+_EXPORT_WARNINGS_HEADER_MAX_BYTES = 8192
+
 
 def _state_lock() -> Any:
     return export_state_lock(_STATE_FILE)
@@ -66,6 +70,29 @@ def _serialize_export_failures(failures: list[ExportFailure]) -> list[dict[str,
     ]
 
 
+def _export_warnings_header_payload(
+    failures: list[ExportFailure],
+) -> dict[str, object]:
+    """Bounded summary for X-Export-Warnings; full list lives in export-warnings.json."""
+    entries = _serialize_export_failures(failures)
+    total = len(entries)
+    sample = entries[:_EXPORT_WARNINGS_HEADER_MAX_ENTRIES]
+    truncated = total > len(sample)
+    payload: dict[str, object] = {
+        "total_failures": total,
+        "truncated": truncated,
+        "failures": sample,
+    }
+    while (
+        len(json.dumps(payload, separators=(",", ":"))) > _EXPORT_WARNINGS_HEADER_MAX_BYTES
+        and len(sample) > 1
+    ):
+        sample = sample[:-1]
+        truncated = True
+        payload = {"total_failures": total, "truncated": truncated, "failures": sample}
+    return payload
+
+
 def _write_state(sessions_map: dict[str, float], count: int) -> None:
     """Persist merge of *sessions_map* and update last-export metadata (*count* = this run only)."""
     with _state_lock():
@@ -136,6 +163,12 @@ def _on_export_error(sid: str, exc: Exception) -> None:
             manifest_style="api",
             on_export_error=_on_export_error,
         )
+        if result.failures and result.exported_session_count > 0:
+            full_warnings = _serialize_export_failures(result.failures)
+            zf.writestr(
+                _EXPORT_WARNINGS_ZIP_NAME,
+                json.dumps(full_warnings, separators=(",", ":")) + "\n",
+            )
 
     count = result.exported_session_count
     new_sessions_map = result.new_sessions_map
@@ -178,7 +211,10 @@ def _on_export_error(sid: str, exc: Exception) -> None:
         download_name=f"claude-code-export{suffix}-{date_tag}.zip",  # type: ignore[call-arg]
     )
     if result.failures:
-        resp.headers["X-Export-Warnings"] = json.dumps(failure_payload)
+        resp.headers["X-Export-Warnings"] = json.dumps(
+            _export_warnings_header_payload(result.failures),
+            separators=(",", ":"),
+        )
     return resp
 
 

docs/api-reference.md

@@ -373,13 +373,14 @@ Filename pattern:
 
 Zip contains Markdown per session and optional `manifest.jsonl` metadata.
 
-When some sessions fail but at least one succeeds, the response is still **`200`** with the ZIP body (successful sessions only). Skipped sessions are listed in the response header:
+When some sessions fail but at least one succeeds, the response is still **`200`** with the ZIP body (successful sessions only). Skipped sessions are surfaced two ways:
 
-| Header | When | Value |
-|--------|------|--------|
-| `X-Export-Warnings` | Partial export (≥1 success, ≥1 failure) | JSON array of `{ "session_id", "code", "message" }` |
+| Channel | When | Value |
+|---------|------|--------|
+| `X-Export-Warnings` header | Partial export (≥1 success, ≥1 failure) | JSON object: `{ "total_failures", "truncated", "failures" }` where `failures` is a capped sample |
+| `export-warnings.json` in the ZIP | Same | Full array of `{ "session_id", "code", "message" }` |
 
-`code` uses the same strings as the error catalog (`PARSE_ERROR`, `INTERNAL_ERROR`, etc.).
+`message` is a stable generic string per `code` (no exception text or paths). `code` uses the same strings as the error catalog (`PARSE_ERROR`, `INTERNAL_ERROR`, etc.).
 
 #### Errors
 

tests/test_export_api_bulk.py

@@ -94,12 +94,19 @@ def flaky_parse(path: str):
     resp = client.post("/api/export", json={"since": "all"})
     assert resp.status_code == 200
     assert "X-Export-Warnings" in resp.headers
-    warnings = json.loads(resp.headers["X-Export-Warnings"])
-    assert len(warnings) == 1
-    assert warnings[0]["session_id"] == "session_def456"
-    assert warnings[0]["code"] == "PARSE_ERROR"
+    header = json.loads(resp.headers["X-Export-Warnings"])
+    assert header["total_failures"] == 1
+    assert header["truncated"] is False
+    assert len(header["failures"]) == 1
+    assert header["failures"][0]["session_id"] == "session_def456"
+    assert header["failures"][0]["code"] == "PARSE_ERROR"
+    assert header["failures"][0]["message"] == "Failed to parse session"
     zf = zipfile.ZipFile(io.BytesIO(resp.data))
     assert len([name for name in zf.namelist() if name.endswith(".md")]) == 1
+    zip_warnings = json.loads(zf.read("export-warnings.json").decode("utf-8"))
+    assert len(zip_warnings) == 1
+    assert zip_warnings[0]["session_id"] == "session_def456"
+    assert "bad" not in zip_warnings[0]["message"]
 
 
 def test_bulk_export_all_fail_returns_422(client, monkeypatch):
@@ -114,6 +121,7 @@ def always_fail(path: str):
     assert body["since"] == "all"
     assert len(body["failures"]) == 2
     assert {item["code"] for item in body["failures"]} == {"PARSE_ERROR"}
+    assert all(item["message"] == "Failed to parse session" for item in body["failures"])
 
 
 def test_bulk_export_partial_fail_excludes_failed_from_state(

utils/export_engine.py

@@ -80,6 +80,15 @@ def failure_code_for_exception(exc: Exception, *, phase: str = "parse") -> Error
     return ErrorCode.INTERNAL_ERROR
 
 
+def failure_message_for_code(code: ErrorCode) -> str:
+    """Stable client-facing message; never embed ``str(exc)`` (issue #25)."""
+    if code == ErrorCode.PARSE_ERROR:
+        return "Failed to parse session"
+    if code == ErrorCode.INTERNAL_ERROR:
+        return "Failed to export session"
+    return "Export failed"
+
+
 @dataclass
 class BulkExportResult:
     """Outcome of a bulk export run."""
@@ -286,11 +295,12 @@ def run_bulk_export(
 
     def _record_failure(sid: str, exc: Exception, *, phase: str = "parse") -> None:
         result.failure_count += 1
+        code = failure_code_for_exception(exc, phase=phase)
         result.failures.append(
             ExportFailure(
                 session_id=sid,
-                message=str(exc),
-                code=failure_code_for_exception(exc, phase=phase),
+                message=failure_message_for_code(code),
+                code=code,
             )
         )
         if on_export_error is not None: