@@ -122,18 +122,20 @@ jobs:
           args: ${{ env.LYCHEE_ARGS }}
           # The next step owns bounded retries and the final success gate.
           fail: false
-          failIfEmpty: true
-          format: markdown
+          # The action's empty-report guard only understands Markdown.
+          # Our helper validates the JSON report and rejects zero checked links.
+          failIfEmpty: false
+          format: json
           jobSummary: false
           lycheeVersion: ${{ env.LYCHEE_VERSION }}
-          output: lychee-${{ matrix.kind }}.md
+          output: lychee-${{ matrix.kind }}.json
           token: ${{ github.token }}
 
-      - name: Retry failed links using successful checks from each pass
+      - name: Retry transient link failures using cached successful checks
         if: ${{ steps.lychee.outcome == 'success' }}
         env:
           EXIT_CODE: ${{ steps.lychee.outputs.exit_code }}
-          REPORT: lychee-${{ matrix.kind }}.md
+          REPORT: lychee-${{ matrix.kind }}.json
           GITHUB_TOKEN: ${{ github.token }}
         run: |
           python ci/tools/retry_lychee.py --initial-exit-code "${EXIT_CODE}" \
@@ -153,7 +155,9 @@ jobs:
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: lychee-${{ matrix.kind }}-${{ github.run_id }}-${{ github.run_attempt }}
-          path: lychee-${{ matrix.kind }}*.md
+          path: |
+            lychee-${{ matrix.kind }}*.json
+            lychee-${{ matrix.kind }}*.md
           if-no-files-found: ignore
           retention-days: 7
 
 
@@ -1,107 +1,206 @@
 # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-"""Retry complete lychee passes while retaining successful checks in its cache."""
+"""Retry transient lychee failures while retaining successful checks in its cache."""
 
 from __future__ import annotations
 
 import argparse
+import html
+import json
 import os
 import re
 import shlex
 import shutil
 import subprocess
 import time
+from dataclasses import dataclass
 from pathlib import Path
+from urllib.parse import urlsplit
 
 LINK_CHECK_FAILURE = 2
 
 
-def read_report(path: Path) -> str:
-    """Reject missing, malformed, or empty-check reports instead of accepting them."""
-    text = path.read_text(encoding="utf-8")
-    total = re.search(r"^\|[^|\n]*\bTotal\s*\|\s*(\d+)\s*\|", text, re.MULTILINE)
-    if total is None:
-        raise ValueError(f"Lychee report has no Total count: {path}")
-    if int(total.group(1)) == 0:
+@dataclass(frozen=True)
+class Failure:
+    source: str
+    url: str
+    text: str
+    details: str | None
+    code: int | None
+    timed_out: bool
+
+    @property
+    def transient(self) -> bool:
+        try:
+            parsed = urlsplit(self.url)
+            is_http = parsed.scheme in ("http", "https") and bool(parsed.hostname)
+        except ValueError:
+            return False
+        return is_http and (
+            self.timed_out or self.code in (408, 429) or (self.code is not None and 500 <= self.code <= 599)
+        )
+
+
+@dataclass(frozen=True)
+class Report:
+    total: int
+    errors: int
+    timeouts: int
+    failures: tuple[Failure, ...]
+
+    @property
+    def transient(self) -> bool:
+        return bool(self.failures) and all(failure.transient for failure in self.failures)
+
+
+def read_report(path: Path, exit_code: int) -> Report:
+    """Validate the pinned lychee JSON schema and its agreement with the exit code."""
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"Lychee report must be a JSON object: {path}")
+    counts = {}
+    for name in ("total", "errors", "timeouts"):
+        value = data.get(name)
+        if type(value) is not int or value < 0:
+            raise ValueError(f"Lychee report {name} must be a nonnegative integer: {path}")
+        counts[name] = value
+    if counts["total"] == 0:
         raise ValueError(f"Lychee checked no links: {path}")
-    return text
+    if counts["errors"] + counts["timeouts"] > counts["total"]:
+        raise ValueError(f"Lychee failure counts exceed the total: {path}")
+
+    failures = []
+    for name, timed_out, count in (("error_map", False, counts["errors"]), ("timeout_map", True, counts["timeouts"])):
+        mapping = data.get(name)
+        if not isinstance(mapping, dict):
+            raise ValueError(f"Lychee report {name} must be an object: {path}")
+        entries = []
+        for source, responses in mapping.items():
+            if not isinstance(source, str) or not source or not isinstance(responses, list):
+                raise ValueError(f"Lychee report {name} must map source names to response lists: {path}")
+            for response in responses:
+                if not isinstance(response, dict) or not isinstance(response.get("url"), str) or not response["url"]:
+                    raise ValueError(f"Lychee report has a malformed failure URL: {path}")
+                status = response.get("status")
+                if not isinstance(status, dict) or not isinstance(status.get("text"), str) or not status["text"]:
+                    raise ValueError(f"Lychee report has a malformed failure status: {path}")
+                code = status.get("code")
+                details = status.get("details")
+                if "code" in status:
+                    if type(code) is not int or not 100 <= code <= 999:
+                        raise ValueError(f"Lychee report has a malformed HTTP status code: {path}")
+                elif not isinstance(details, str):
+                    raise ValueError(f"Lychee report non-HTTP status must contain string details: {path}")
+                if "details" in status and not isinstance(details, str):
+                    raise ValueError(f"Lychee report status details must be a string: {path}")
+                entries.append(Failure(source, response["url"], status["text"], details, code, timed_out))
+        # Counters count occurrences; response maps deduplicate equivalent checks.
+        if bool(count) != bool(entries):
+            raise ValueError(f"Lychee report {name} disagrees with its failure count: {path}")
+        failures.extend(entries)
+
+    if (exit_code == 0) != (not failures):
+        raise ValueError(f"Lychee report failures disagree with exit code {exit_code}: {path}")
+    return Report(counts["total"], counts["errors"], counts["timeouts"], tuple(failures))
+
+
+def escape_markdown(text: str) -> str:
+    text = html.escape(text).replace("\r", " ").replace("\n", " ")
+    return re.sub(r"([\\`*_~\[\]|])", r"\\\1", text)
+
+
+def render_report(report: Report) -> str:
+    result = (
+        "| Status | Count |\n| --- | --- |\n"
+        f"| Total | {report.total} |\n| Errors | {report.errors} |\n| Timeouts | {report.timeouts} |\n"
+    )
+    if report.failures:
+        result += "\n| Source | URL | Status | Details |\n| --- | --- | --- | --- |\n"
+        for failure in report.failures:
+            cells = (failure.source, failure.url, failure.text, failure.details or "")
+            result += "| " + " | ".join(escape_markdown(cell) for cell in cells) + " |\n"
+    return result
 
 
 def attempt_report(report: Path, attempt: int) -> Path:
     return report.with_name(f"{report.stem}-attempt-{attempt}{report.suffix}")
 
 
-def finish(report_text: str | None, exit_codes: list[int], message: str) -> None:
+def finish(report: Path, data: Report | None, exit_codes: list[int], message: str) -> None:
     """Publish the final result without presenting recovered failures as current."""
     summary = f"## Documentation links\n\n{message}\n\n| Attempt | Exit code |\n| --- | --- |\n"
     summary += "".join(f"| {attempt} | {code} |\n" for attempt, code in enumerate(exit_codes, start=1))
-    if report_text is not None:
-        summary += f"\n### Final attempt\n\n{report_text}\n"
+    if data is not None:
+        summary += f"\n### Final attempt\n\n{render_report(data)}\n"
     else:
         summary += (
             "\nThe final attempt did not produce a link-check report. Earlier reports are retained as artifacts.\n"
         )
+    report.with_suffix(".md").write_text(summary, encoding="utf-8")
     print(message, flush=True)
     if summary_path := os.environ.get("GITHUB_STEP_SUMMARY"):
         with Path(summary_path).open("a", encoding="utf-8") as stream:
             stream.write(summary)
 
 
 def retry_lychee(initial_exit_code: int, report: Path, max_attempts: int = 10) -> int:
-    """Count the action's first pass toward the limit, and retry only link failures."""
+    """Retry only if every remaining failure is a recognized transient HTTP error."""
     if initial_exit_code not in (0, 1, 2, 3):
         raise ValueError(f"Unexpected initial lychee exit code: {initial_exit_code}")
     if max_attempts < 1:
         raise ValueError("max_attempts must be positive")
     exit_codes = [initial_exit_code]
     if initial_exit_code not in (0, LINK_CHECK_FAILURE):
-        finish(None, exit_codes, f"Lychee stopped on attempt 1 with exit code {initial_exit_code}; no retry.")
+        finish(report, None, exit_codes, f"Lychee stopped on attempt 1 with exit code {initial_exit_code}; no retry.")
         return initial_exit_code
 
-    report_text = read_report(report)
+    data = read_report(report, initial_exit_code)
     shutil.copyfile(report, attempt_report(report, 1))
-    if initial_exit_code == 0:
-        finish(report_text, exit_codes, "Lychee passed on attempt 1.")
-        return 0
-    if max_attempts == 1:
-        finish(report_text, exit_codes, "Lychee still has broken links after 1 attempt.")
-        return LINK_CHECK_FAILURE
-
-    raw_args = os.environ.get("LYCHEE_ARGS")
-    if not raw_args or not (lychee_args := shlex.split(raw_args)):
-        raise ValueError("LYCHEE_ARGS must contain the same arguments used by the first lychee pass")
-
-    for attempt in range(2, max_attempts + 1):
-        cooldown = min(60 * (attempt - 1), 120)
+    lychee_args = None
+    while True:
+        attempt = len(exit_codes)
+        if exit_codes[-1] == 0:
+            finish(report, data, exit_codes, f"Lychee passed on attempt {attempt}/{max_attempts}.")
+            return 0
+        if not data.transient:
+            finish(
+                report,
+                data,
+                exit_codes,
+                f"Lychee has permanent or unclassified link failures on attempt {attempt}; no retry.",
+            )
+            return LINK_CHECK_FAILURE
+        if attempt >= max_attempts:
+            finish(report, data, exit_codes, f"Lychee still has transient link failures after {max_attempts} attempts.")
+            return LINK_CHECK_FAILURE
+        if lychee_args is None:
+            raw_args = os.environ.get("LYCHEE_ARGS")
+            if not raw_args or not (lychee_args := shlex.split(raw_args)):
+                raise ValueError("LYCHEE_ARGS must contain the same arguments used by the first lychee pass")
+
+        cooldown = min(60 * attempt, 120)
         print(
-            f"Lychee attempt {attempt - 1} failed; waiting {cooldown}s before attempt {attempt}/{max_attempts}.",
+            f"Lychee attempt {attempt} had transient failures; waiting {cooldown}s before attempt {attempt + 1}/{max_attempts}.",
             flush=True,
         )
         time.sleep(cooldown)
-        current_report = attempt_report(report, attempt)
+        current_report = attempt_report(report, attempt + 1)
         result = subprocess.run(  # noqa: S603
-            ["lychee", *lychee_args, "--mode", "task", "--format", "markdown", "--output", str(current_report)],  # noqa: S607
+            ["lychee", *lychee_args, "--mode", "task", "--format", "json", "--output", str(current_report)],  # noqa: S607
             check=False,
         )
         exit_codes.append(result.returncode)
         if result.returncode not in (0, LINK_CHECK_FAILURE):
             finish(
-                None, exit_codes, f"Lychee stopped on attempt {attempt} with exit code {result.returncode}; no retry."
+                report,
+                None,
+                exit_codes,
+                f"Lychee stopped on attempt {attempt + 1} with exit code {result.returncode}; no retry.",
             )
             return result.returncode if result.returncode > 0 else 1
-        report_text = read_report(current_report)
+        data = read_report(current_report, result.returncode)
         shutil.copyfile(current_report, report)
-        if result.returncode == 0:
-            finish(
-                report_text,
-                exit_codes,
-                f"Lychee passed on attempt {attempt}/{max_attempts}; successful checks were retained between passes.",
-            )
-            return 0
-
-    finish(report_text, exit_codes, f"Lychee still has broken links after {max_attempts} attempts.")
-    return LINK_CHECK_FAILURE
 
 
 def main() -> int: