poolprobe 1.0.0__py3-none-any.whl

poolprobe/report.py

@@ -0,0 +1,1096 @@
+"""Rendering: terminal table, JSON payload, and a self-contained HTML page.
+
+One dataset, three renderers, no logic in any of them. Every number shown here
+was measured by :mod:`poolprobe.bench` or :mod:`poolprobe.probe`; the renderers
+only decide how to lay it out and where a caveat belongs.
+
+Two honesty rules the renderers enforce:
+
+* Throughput from SSE chunk counts is always prefixed with ``>=`` and titled as
+  a lower bound. Throughput with no token evidence at all renders as ``-``,
+  never as ``0.0 tok/s``, because a zero reads like a measurement.
+* A burst history renders as one glyph per attempt, so "recovered on attempt 3"
+  is visible in the table instead of being folded into a green tick.
+"""
+
+from __future__ import annotations
+
+import html as html_module
+import json
+import os
+import shutil
+import sys
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+
+from . import taxonomy
+
+# --- palette ----------------------------------------------------------------
+
+_CODES = {
+    "reset": "0",
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "magenta": "35",
+    "cyan": "36",
+    "white": "37",
+}
+
+VERDICT_STYLE = {
+    taxonomy.OK: ("green", "bold"),
+    taxonomy.EMPTY_LENGTH: ("yellow",),
+    taxonomy.EMPTY: ("red",),
+    taxonomy.ERR: ("red", "bold"),
+    taxonomy.TIMEOUT: ("magenta",),
+}
+
+KIND_STYLE = {
+    taxonomy.ALIVE: ("green",),
+    taxonomy.ALIVE_STARVED: ("yellow",),
+    taxonomy.PERMANENT: ("red", "bold"),
+    taxonomy.TRANSIENT: ("cyan",),
+    taxonomy.CREDENTIAL: ("yellow",),
+    taxonomy.MODALITY: ("magenta",),
+    taxonomy.UNKNOWN: ("white", "dim"),
+}
+
+#: One glyph per verdict, so a burst history fits in a few columns.
+GLYPHS = {
+    taxonomy.OK: "\u2713",
+    taxonomy.EMPTY_LENGTH: "\u25d0",
+    taxonomy.EMPTY: "\u2205",
+    taxonomy.ERR: "\u2717",
+    taxonomy.TIMEOUT: "\u23f1",
+}
+ASCII_GLYPHS = {
+    taxonomy.OK: "o",
+    taxonomy.EMPTY_LENGTH: "~",
+    taxonomy.EMPTY: "0",
+    taxonomy.ERR: "x",
+    taxonomy.TIMEOUT: "T",
+}
+
+# Separators and marks as constants: Python 3.10 refuses a backslash inside the
+# expression part of an f-string, and these are all non-ASCII.
+_SEP = "  \u00b7  "
+_ARROW = " \u2192 "
+_ELLIPSIS = "\u2026"
+_CROSS = "\u2717"
+_DASH = " \u2014 "
+
+
+def _terminal_wants_color(stream: object) -> bool:
+    """NO_COLOR wins, then FORCE_COLOR, then "is this actually a tty"."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    if os.environ.get("TERM") == "dumb":
+        return False
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def _terminal_is_unicode(stream: object) -> bool:
+    """Glyph check, not a locale sermon: an unknown encoding on POSIX is
+    assumed capable, on Windows it is assumed not to be."""
+    encoding = str(getattr(stream, "encoding", "") or "").lower()
+    if "utf" in encoding:
+        return True
+    return encoding in ("", "ansi_x3.4-1968") and sys.platform != "win32"
+
+
+@dataclass
+class Palette:
+    """Colour and glyph decisions in one place, so renderers stay declarative."""
+
+    color: bool = False
+    unicode: bool = True
+
+    @classmethod
+    def detect(cls, stream: object | None = None) -> "Palette":
+        out = stream if stream is not None else sys.stdout
+        return cls(color=_terminal_wants_color(out), unicode=_terminal_is_unicode(out))
+
+    def paint(self, text: str, *styles: str) -> str:
+        if not self.color or not styles:
+            return text
+        codes = ";".join(_CODES[s] for s in styles if s in _CODES)
+        return f"\033[{codes}m{text}\033[0m" if codes else text
+
+    def verdict(self, text: str) -> str:
+        return self.paint(text, *VERDICT_STYLE.get(text, ("white",)))
+
+    def kind(self, text: str) -> str:
+        return self.paint(text, *KIND_STYLE.get(text, ("white", "dim")))
+
+    def glyph(self, verdict: str) -> str:
+        table = GLYPHS if self.unicode else ASCII_GLYPHS
+        return table.get(verdict, "?")
+
+    def burst(self, history: list, limit: int = 0) -> str:
+        """``[(verdict, note), ...]`` -> a coloured glyph run.
+
+        ``limit`` keeps the *tail*: attempt order is chronological, so the last
+        glyph is the one the verdict came from. Truncating the list rather than
+        the rendered string is what keeps the escape sequences intact.
+        """
+        if not history:
+            return self.paint("-", "dim")
+        if limit and len(history) > limit:
+            history = history[-limit:]
+        return "".join(
+            self.paint(self.glyph(verdict), *VERDICT_STYLE.get(verdict, ("white",)))
+            for verdict, _note in history
+        )
+
+
+# --- dataset ----------------------------------------------------------------
+
+
+@dataclass
+class RunMeta:
+    """Everything a report header needs about the run itself."""
+
+    command: str = "sweep"
+    gateway: str = ""
+    adapter: str = ""
+    generated_at: str = ""
+    duration_s: float = 0.0
+    pool: int = 0
+    run_count: int = 0
+    state_path: str = ""
+    attempts: int = 1
+    threads: int = 1
+    timeout: float = 0.0
+    max_tokens: int = 0
+    stream: bool = False
+    repeat: int = 1
+    argv: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    tool: str = "poolprobe"
+    version: str = ""
+
+    def stamp(self) -> str:
+        return self.generated_at or datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+@dataclass
+class Prunable:
+    """A model that survived every guard and is therefore a prune candidate."""
+
+    model: str
+    kind: str = taxonomy.PERMANENT
+    verdict: str = taxonomy.ERR
+    streak: int = 0
+    attempts: int = 1
+    provider: str = ""
+    note: str = ""
+    advice: str = ""
+
+
+@dataclass
+class Report:
+    """One finished run. Renderers take this and nothing else."""
+
+    meta: RunMeta = field(default_factory=RunMeta)
+    probes: list = field(default_factory=list)  # list[ProbeResult]
+    bench: list = field(default_factory=list)  # list[BenchResult]
+    prunable: list = field(default_factory=list)  # list[Prunable]
+    streaks: dict = field(default_factory=dict)  # model -> (fail_streak, ok_streak)
+    attribution: dict = field(default_factory=dict)  # model -> Attribution.as_dict()
+    bench_summary: dict = field(default_factory=dict)
+    diff: str = ""  # unified diff of a planned config edit, if any
+    edit_path: str = ""
+    edit_removed: list = field(default_factory=list)
+    edit_not_found: list = field(default_factory=list)
+    chains: list = field(default_factory=list)  # list[dict] from chains.validate
+
+    def streak_of(self, model: str) -> tuple[int, int]:
+        pair = self.streaks.get(model)
+        return tuple(pair) if isinstance(pair, (list, tuple)) and len(pair) == 2 else (0, 0)
+
+
+def summarize_probes(probes: list) -> dict:
+    """Roll probe results into counts a header can show."""
+    by_verdict: dict[str, int] = {}
+    by_kind: dict[str, int] = {}
+    alive = 0
+    starved = 0
+    dead = 0
+    latencies: list[float] = []
+    recovered = 0
+    flaky = 0
+
+    for item in probes:
+        by_verdict[item.verdict] = by_verdict.get(item.verdict, 0) + 1
+        by_kind[item.kind] = by_kind.get(item.kind, 0) + 1
+        if item.verdict == taxonomy.OK:
+            alive += 1
+            latencies.append(item.latency_s)
+        elif item.verdict == taxonomy.EMPTY_LENGTH:
+            starved += 1
+            latencies.append(item.latency_s)
+        else:
+            dead += 1
+        history = [verdict for verdict, _note in getattr(item, "history", [])]
+        if len(history) > 1:
+            saw_dead = any(verdict in taxonomy.DEAD for verdict in history)
+            saw_live = any(verdict not in taxonomy.DEAD for verdict in history)
+            if saw_dead and not item.dead:
+                recovered += 1
+            if saw_dead and saw_live:
+                flaky += 1
+
+    latencies.sort()
+    return {
+        "total": len(probes),
+        "alive": alive,
+        "starved": starved,
+        "dead": dead,
+        "recovered": recovered,
+        "flaky": flaky,
+        "by_verdict": dict(sorted(by_verdict.items())),
+        "by_kind": dict(sorted(by_kind.items())),
+        "median_latency_s": round(_median(latencies), 2),
+        "p95_latency_s": round(_percentile(latencies, 0.95), 2),
+    }
+
+
+def _median(values: list) -> float:
+    if not values:
+        return 0.0
+    middle = len(values) // 2
+    if len(values) % 2:
+        return float(values[middle])
+    return (float(values[middle - 1]) + float(values[middle])) / 2.0
+
+
+def _percentile(values: list, fraction: float) -> float:
+    if not values:
+        return 0.0
+    index = min(len(values) - 1, max(0, int(round(fraction * (len(values) - 1)))))
+    return float(values[index])
+
+
+# --- terminal ---------------------------------------------------------------
+
+
+def _clip(text: str, width: int) -> str:
+    if width <= 0:
+        return ""
+    if len(text) <= width:
+        return text
+    if width == 1:
+        return text[:1]
+    return text[: width - 1] + _ELLIPSIS
+
+
+def _pad_row(plain: list, painted: list, widths: list, aligns: list) -> str:
+    """Lay one row out: pad on the plain text, then drop the colour in.
+
+    An ANSI escape has a length that is not a width, so every measurement here
+    is made on the uncoloured cell. A cell that still does not fit loses its
+    colour instead of being sliced — cutting a painted string can halve an
+    escape sequence and leak ``[31m`` into the rest of the line.
+    """
+    cells = []
+    for text, styled, width, align in zip(plain, painted, widths, aligns):
+        if len(text) > width:
+            text = _clip(text, width)
+            styled = text
+        padding = max(0, width - len(text))
+        if align == "r":
+            cells.append(" " * padding + styled)
+        elif padding:
+            cells.append(styled + " " * padding)
+        else:
+            cells.append(styled)
+    return "  ".join(cells).rstrip()
+
+
+def _latency(seconds: float) -> str:
+    if seconds <= 0:
+        return "-"
+    if seconds < 10:
+        return f"{seconds:.2f}s"
+    return f"{seconds:.1f}s"
+
+
+def _footer_parts(meta: RunMeta) -> list[str]:
+    """The provenance line, shared by the terminal and HTML footers.
+
+    One helper for both views so they cannot disagree about what a run recorded.
+    A field the command never set is dropped rather than printed as a zero:
+    ``chains`` sends no request at all, so ``timeout 0s · max_tokens 0`` would
+    read like a setting the run used.
+    """
+    parts = [meta.stamp(), f"{_latency(meta.duration_s)} wall"]
+    if meta.pool:
+        parts.append(f"pool {meta.pool}")
+    if meta.run_count:
+        parts.append(f"run {meta.run_count}")
+    if meta.threads > 1:
+        parts.append(f"threads {meta.threads}")
+    if meta.attempts > 1:
+        parts.append(f"attempts {meta.attempts}")
+    if meta.repeat > 1:
+        parts.append(f"repeat {meta.repeat}")
+    if meta.timeout:
+        parts.append(f"timeout {meta.timeout:g}s")
+    if meta.max_tokens:
+        parts.append(f"max_tokens {meta.max_tokens}")
+    if meta.stream:
+        parts.append("stream")
+    if meta.state_path:
+        parts.append(f"state {meta.state_path}")
+    return parts
+
+
+def render_terminal(report: Report, palette: Palette | None = None, width: int | None = None) -> str:
+    """The whole run as text. Never emits ANSI when the palette says no."""
+    pal = palette or Palette.detect()
+    total_width = width or shutil.get_terminal_size((118, 24)).columns
+    total_width = max(72, min(int(total_width), 220))
+    meta = report.meta
+    lines: list[str] = []
+
+    title = f"{meta.tool} {meta.version}".strip()
+    lines.append(pal.paint(title, "bold") + pal.paint(f"  \u00b7  {meta.command}", "dim"))
+    header_bits = [bit for bit in (meta.gateway, meta.adapter) if bit]
+    if header_bits:
+        lines.append(pal.paint(" \u00b7 ".join(header_bits), "dim"))
+
+    if report.probes:
+        summary = summarize_probes(report.probes)
+        lines.append("")
+        lines.append(
+            pal.paint(
+                f"{summary['total']} models  \u00b7  ",
+                "dim",
+            )
+            + pal.paint(f"{summary['alive']} alive", "green")
+            + pal.paint("  \u00b7  ", "dim")
+            + pal.paint(f"{summary['starved']} starved", "yellow")
+            + pal.paint("  \u00b7  ", "dim")
+            + pal.paint(f"{summary['dead']} dead", "red" if summary["dead"] else "dim")
+            + pal.paint("  \u00b7  ", "dim")
+            + pal.paint(
+                f"{len(report.prunable)} prunable",
+                "red" if report.prunable else "dim",
+            )
+            + pal.paint(
+                f"  \u00b7  median {_latency(summary['median_latency_s'])}", "dim"
+            )
+            + pal.paint(f"  \u00b7  run #{meta.run_count}", "dim")
+        )
+        if summary["recovered"]:
+            lines.append(
+                pal.paint(
+                    f"{summary['recovered']} model(s) recovered inside the burst "
+                    f"({summary['flaky']} flaky) \u2014 a single probe would have called them dead",
+                    "cyan",
+                )
+            )
+
+        lines.append("")
+        lines.extend(_probe_table(report, pal, total_width))
+
+    if report.bench:
+        lines.append("")
+        lines.append(pal.paint("bench", "bold"))
+        lines.extend(_bench_table(report, pal, total_width))
+
+    if report.prunable:
+        lines.append("")
+        lines.append(pal.paint("prunable", "bold"))
+        lines.append(
+            pal.paint(
+                "passed every guard: dead + PERMANENT + streak + not protected + chat modality",
+                "dim",
+            )
+        )
+        for row in report.prunable:
+            streak = row.streak
+            lines.append(
+                "  "
+                + pal.paint(_clip(row.model, 34), "red", "bold")
+                + pal.paint(f"  streak {streak}  ", "dim")
+                + pal.paint(_clip(row.note, 60), "white")
+            )
+    elif report.probes:
+        lines.append("")
+        lines.append(
+            pal.paint(
+                "prunable: none \u2014 nothing met all five guards (dead, PERMANENT, "
+                f"streak, unprotected, chat modality)",
+                "dim",
+            )
+        )
+
+    advice_lines = _advice_lines(report)
+    if advice_lines:
+        lines.append("")
+        lines.append(pal.paint("what to do", "bold"))
+        lines.extend(advice_lines)
+
+    if report.chains:
+        lines.append("")
+        lines.append(pal.paint("fallback chains", "bold"))
+        lines.extend(_chain_lines(report, pal))
+
+    if report.diff:
+        lines.append("")
+        lines.append(pal.paint(f"planned edit \u00b7 {report.edit_path}", "bold"))
+        if report.edit_not_found:
+            lines.append(
+                pal.paint("not found in config (left alone): ", "dim")
+                + ", ".join(report.edit_not_found)
+            )
+        for line in report.diff.splitlines():
+            if line.startswith("+") and not line.startswith("+++"):
+                lines.append(pal.paint(line, "green"))
+            elif line.startswith("-") and not line.startswith("---"):
+                lines.append(pal.paint(line, "red"))
+            elif line.startswith("@@"):
+                lines.append(pal.paint(line, "cyan"))
+            else:
+                lines.append(pal.paint(line, "dim"))
+
+    warnings = list(meta.warnings)
+    if warnings:
+        lines.append("")
+        for warning in warnings:
+            lines.append(pal.paint(f"! {warning}", "yellow"))
+
+    if meta.notes:
+        lines.append("")
+        for note in meta.notes:
+            lines.append(pal.paint(note, "dim"))
+
+    lines.append("")
+    # The provenance line is the only part of the report that grows with the
+    # options used -- `--state` alone outgrows 80 columns -- so it wraps at
+    # separator boundaries instead of breaking mid-field.
+    row = ""
+    for part in _footer_parts(meta):
+        if row and len(row) + len(_SEP) + len(part) > total_width:
+            lines.append(pal.paint(row, "dim"))
+            row = part
+        else:
+            row = f"{row}{_SEP}{part}" if row else part
+    lines.append(pal.paint(row, "dim"))
+    return "\n".join(lines)
+
+
+def _probe_table(report: Report, pal: Palette, total_width: int) -> list[str]:
+    """One row per probe.
+
+    The column set depends on ``--attempts``: a burst history only exists when a
+    model was probed more than once, and an empty BURST column on a single-probe
+    run would be a column that says nothing. Every index below is derived from
+    ``headers`` rather than hardcoded, so the two layouts cannot drift apart.
+    """
+    meta = report.meta
+    show_burst = meta.attempts > 1
+    columns = [
+        ("VERDICT", 12, "l"),
+        ("MODEL", 28, "l"),
+        ("PROVIDER", 13, "l"),
+        ("LAT", 7, "r"),
+    ]
+    if show_burst:
+        longest = max((len(item.history) for item in report.probes), default=meta.attempts)
+        columns.append(("BURST", max(5, min(longest, 16)), "l"))
+    columns.extend(
+        [
+            ("STREAK", 6, "r"),
+            ("KIND", 13, "l"),
+            ("NOTE", 0, "l"),
+        ]
+    )
+
+    headers = [name for name, _w, _a in columns]
+    aligns = [align for _n, _w, align in columns]
+    fixed = sum(width for _h, width, _a in columns if width) + 2 * (len(columns) - 1)
+    widths = [width if width else max(12, total_width - fixed) for _h, width, _a in columns]
+    i_burst = headers.index("BURST") if show_burst else -1
+    i_note = len(headers) - 1
+    i_kind = i_note - 1
+
+    out = ["  ".join(h.ljust(w)[:w] for h, w in zip(headers, widths))]
+    out.append("  ".join("-" * w for w in widths))
+
+    for item in report.probes:
+        fail, ok = report.streak_of(item.model)
+        streak = f"x{fail}" if fail else (f"ok{ok}" if ok else "-")
+        kind = item.kind if item.kind != taxonomy.ALIVE else "-"
+        plain = [
+            _clip(item.verdict, widths[0]),
+            _clip(item.model, widths[1]),
+            _clip(item.provider or "-", widths[2]),
+            _latency(item.latency_s),
+        ]
+        if show_burst:
+            glyphs = "".join(pal.glyph(verdict) for verdict, _n in item.history) or "-"
+            plain.append(_clip(glyphs, widths[i_burst]))
+        plain.extend(
+            [
+                streak,
+                _clip(kind, widths[i_kind]),
+                _clip(item.note or "-", widths[i_note]),
+            ]
+        )
+
+        painted = [
+            pal.verdict(plain[0]),
+            pal.paint(plain[1], "bold"),
+            pal.paint(plain[2], "dim"),
+            plain[3],
+        ]
+        if show_burst:
+            painted.append(pal.burst(item.history, limit=widths[i_burst]))
+        painted.extend(
+            [
+                pal.paint(streak, "red" if fail else "dim"),
+                pal.kind(plain[i_kind]),
+                pal.paint(plain[i_note], "white" if item.dead else "dim"),
+            ]
+        )
+        out.append(_pad_row(plain, painted, widths, aligns))
+    return out
+
+
+def _bench_table(report: Report, pal: Palette, total_width: int) -> list[str]:
+    columns = [
+        ("MODEL", 28, "l"),
+        ("PROVIDER", 13, "l"),
+        ("LAT", 8, "r"),
+        ("TTFT", 7, "r"),
+        ("TOK", 6, "r"),
+        ("TOK/S", 10, "r"),
+        ("SOURCE", 8, "l"),
+        ("NOTE", 0, "l"),
+    ]
+    aligns = [align for _n, _w, align in columns]
+    fixed = sum(w for _h, w, _a in columns if w) + 2 * (len(columns) - 1)
+    widths = [w if w else max(10, total_width - fixed) for _h, w, _a in columns]
+
+    out = ["  ".join(h.ljust(w)[:w] for (h, _w, _a), w in zip(columns, widths))]
+    out.append("  ".join("-" * w for w in widths))
+    for item in report.bench:
+        if item.ok:
+            throughput = f"{item.tok_s:.1f}" if item.tok_s_exact else (
+                f">={item.tok_s:.1f}" if item.tok_s > 0 else "-"
+            )
+            note = "-"
+            style = ("green",)
+        else:
+            throughput = "-"
+            note = item.error or item.verdict or "dead"
+            style = ("red",)
+        plain = [
+            _clip(item.model, widths[0]),
+            _clip(item.provider or "-", widths[1]),
+            _latency(item.latency_s),
+            _latency(item.ttft_s),
+            str(item.tokens) if item.tokens else "-",
+            throughput,
+            item.token_source if item.token_source != "none" else "-",
+            _clip(note, widths[7]),
+        ]
+        painted = [
+            pal.paint(plain[0], "bold"),
+            pal.paint(plain[1], "dim"),
+            plain[2],
+            plain[3],
+            plain[4],
+            pal.paint(plain[5], *style),
+            pal.paint(plain[6], "dim"),
+            pal.paint(plain[7], "dim" if item.ok else "white"),
+        ]
+        out.append(_pad_row(plain, painted, widths, aligns))
+
+    summary = report.bench_summary
+    if summary:
+        exact = summary.get("with_exact_tokens", 0)
+        out.append(
+            pal.paint(
+                f"{summary.get('alive', 0)}/{summary.get('total', 0)} answered  \u00b7  "
+                f"median latency {_latency(float(summary.get('median_latency_s', 0.0)))}  \u00b7  "
+                f"{exact} with exact token counts (usage), "
+                f"{summary.get('alive', 0) - exact} lower-bound (chunks) or unmeasured",
+                "dim",
+            )
+        )
+        if exact < summary.get("alive", 0):
+            out.append(
+                pal.paint(
+                    "tok/s marked >= is counted from SSE chunks, a transport artifact: "
+                    "a hard lower bound, not a measurement. Ranking uses latency, which is exact.",
+                    "yellow",
+                )
+            )
+    return out
+
+
+def _advice_lines(report: Report) -> list[str]:
+    seen: dict[str, int] = {}
+    order: list[str] = []
+    for item in report.probes:
+        if item.kind == taxonomy.ALIVE:
+            continue
+        seen[item.kind] = seen.get(item.kind, 0) + 1
+        if item.kind not in order:
+            order.append(item.kind)
+    lines = []
+    for kind in order:
+        text = taxonomy.advice(kind)
+        if not text:
+            continue
+        lines.append(f"  {kind} ({seen[kind]}): {text}")
+    return lines
+
+
+def _chain_lines(report: Report, pal: Palette) -> list[str]:
+    lines: list[str] = []
+    for chain in report.chains:
+        label = chain.get("label", "?")
+        issues = chain.get("issues") or []
+        rungs = chain.get("rungs") or []
+        head = (f"  {label}: " + _ARROW.join(rungs)) if rungs else f"  {label}: (empty)"
+        if issues:
+            lines.append(pal.paint(head, "yellow"))
+            for issue in issues:
+                lines.append(pal.paint(f"      - {issue}", "yellow"))
+        else:
+            lines.append(pal.paint(head, "green"))
+    return lines
+
+
+# --- json -------------------------------------------------------------------
+
+
+def render_json(report: Report, indent: int | None = 2) -> str:
+    """Machine-readable form of the same run. Stable key order, no ANSI."""
+    summary = summarize_probes(report.probes) if report.probes else {}
+    payload = {
+        "tool": report.meta.tool,
+        "version": report.meta.version,
+        "generated_at": report.meta.stamp(),
+        "command": report.meta.command,
+        "gateway": report.meta.gateway,
+        "adapter": report.meta.adapter,
+        "duration_s": round(report.meta.duration_s, 3),
+        "settings": {
+            "attempts": report.meta.attempts,
+            "threads": report.meta.threads,
+            "timeout": report.meta.timeout,
+            "max_tokens": report.meta.max_tokens,
+            "stream": report.meta.stream,
+            "repeat": report.meta.repeat,
+        },
+        "summary": summary,
+        "prunable": [asdict(row) for row in report.prunable],
+        "results": [],
+        "bench": [],
+        "bench_summary": report.bench_summary,
+        "chains": report.chains,
+        "edit": {
+            "path": report.edit_path,
+            "removed": report.edit_removed,
+            "not_found": report.edit_not_found,
+            "diff": report.diff,
+        }
+        if report.diff or report.edit_path
+        else {},
+        "warnings": list(report.meta.warnings),
+        "notes": list(report.meta.notes),
+        "state": {
+            "path": report.meta.state_path,
+            "run_count": report.meta.run_count,
+            "pool": report.meta.pool,
+        },
+    }
+    for item in report.probes:
+        row = item.as_dict()
+        fail, ok = report.streak_of(item.model)
+        row["fail_streak"] = fail
+        row["ok_streak"] = ok
+        attr = report.attribution.get(item.model)
+        if isinstance(attr, dict):
+            row["attribution"] = attr
+        payload["results"].append(row)
+    for item in report.bench:
+        payload["bench"].append(item.as_dict())
+    return json.dumps(payload, indent=indent, ensure_ascii=False, sort_keys=False)
+
+
+# --- html -------------------------------------------------------------------
+
+_CSS = """
+:root{--bg:#0d1117;--panel:#151b23;--line:#232c37;--fg:#e6edf3;--dim:#8b98a5;
+--green:#3fb950;--yellow:#d29922;--red:#f85149;--cyan:#39c5cf;--magenta:#bc8cff;--accent:#58a6ff}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+font:14px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+.wrap{max-width:1180px;margin:0 auto;padding:28px 20px 56px}
+header{display:flex;flex-wrap:wrap;gap:10px 18px;align-items:baseline;
+border-bottom:1px solid var(--line);padding-bottom:16px;margin-bottom:22px}
+h1{font-size:20px;margin:0;letter-spacing:.2px}
+h1 .v{color:var(--dim);font-weight:400;font-size:13px;margin-left:8px}
+.sub{color:var(--dim);font-size:12.5px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.tiles{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:10px;margin-bottom:22px}
+.tile{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:12px 14px}
+.tile .n{font-size:24px;font-weight:650;line-height:1.1}
+.tile .l{color:var(--dim);font-size:11.5px;text-transform:uppercase;letter-spacing:.7px;margin-top:3px}
+.tile.good .n{color:var(--green)}.tile.warn .n{color:var(--yellow)}
+.tile.bad .n{color:var(--red)}.tile.info .n{color:var(--cyan)}
+h2{font-size:13px;text-transform:uppercase;letter-spacing:.9px;color:var(--dim);
+margin:26px 0 10px;font-weight:600}
+.filters{display:flex;flex-wrap:wrap;gap:6px;margin-bottom:10px}
+.filters button{background:var(--panel);border:1px solid var(--line);color:var(--dim);
+border-radius:999px;padding:4px 12px;font-size:12px;cursor:pointer;font-family:inherit}
+.filters button:hover{color:var(--fg);border-color:#33414f}
+.filters button[aria-pressed="true"]{color:var(--fg);border-color:var(--accent);background:#12233a}
+.panel{background:var(--panel);border:1px solid var(--line);border-radius:10px;overflow:auto}
+table{border-collapse:collapse;width:100%;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12.5px}
+thead th{position:sticky;top:0;background:#111820;color:var(--dim);text-align:left;
+font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:.6px;
+padding:9px 12px;border-bottom:1px solid var(--line);white-space:nowrap}
+tbody td{padding:7px 12px;border-bottom:1px solid #1b232d;vertical-align:top;white-space:nowrap}
+tbody tr:last-child td{border-bottom:0}
+tbody tr:hover{background:#131a22}
+td.note{white-space:normal;color:var(--dim);min-width:220px}
+td.num,th.num{text-align:right;font-variant-numeric:tabular-nums}
+td.model{color:var(--fg);font-weight:600}
+td.prov{color:var(--dim)}
+.badge{display:inline-block;padding:1px 8px;border-radius:999px;font-size:11px;
+font-weight:600;letter-spacing:.3px;border:1px solid transparent}
+.b-OK{color:var(--green);background:#0f2417;border-color:#1d4429}
+.b-EMPTY-LENGTH{color:var(--yellow);background:#241f0f;border-color:#4d3f1a}
+.b-EMPTY{color:var(--red);background:#2a1416;border-color:#5a2429}
+.b-ERR{color:var(--red);background:#2a1416;border-color:#5a2429}
+.b-TIMEOUT{color:var(--magenta);background:#20162c;border-color:#3f2a5c}
+.k-ALIVE{color:var(--green)}.k-ALIVE-STARVED{color:var(--yellow)}
+.k-PERMANENT{color:var(--red);font-weight:600}.k-TRANSIENT{color:var(--cyan)}
+.k-CREDENTIAL{color:var(--yellow)}.k-MODALITY{color:var(--magenta)}.k-UNKNOWN{color:var(--dim)}
+.burst{letter-spacing:1px;font-size:13px}
+.g-OK{color:var(--green)}.g-EMPTY-LENGTH{color:var(--yellow)}.g-EMPTY{color:var(--red)}
+.g-ERR{color:var(--red)}.g-TIMEOUT{color:var(--magenta)}
+.streak{font-variant-numeric:tabular-nums}
+.streak.bad{color:var(--red);font-weight:600}
+ul.advice{margin:0;padding-left:18px}ul.advice li{margin:4px 0}
+ul.advice code{color:var(--accent)}
+pre{background:#0a0e13;border:1px solid var(--line);border-radius:10px;padding:14px;
+overflow:auto;font-size:12px;line-height:1.55;margin:0}
+pre .add{color:var(--green)}pre .del{color:var(--red)}
+pre .hunk{color:var(--cyan)}pre .ctx{color:var(--dim)}
+.warn{background:#241f0f;border:1px solid #4d3f1a;border-radius:10px;padding:10px 14px;color:var(--yellow)}
+.foot{color:var(--dim);font-size:11.5px;margin-top:26px;border-top:1px solid var(--line);
+padding-top:14px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.empty{color:var(--dim);padding:16px}
+"""
+
+_JS = """
+(function(){
+  var buttons=document.querySelectorAll('.filters button');
+  function apply(filter){
+    document.querySelectorAll('tbody tr[data-v]').forEach(function(tr){
+      tr.style.display=(filter==='all'||tr.getAttribute('data-v')===filter)?'':'none';
+    });
+    buttons.forEach(function(b){b.setAttribute('aria-pressed',String(b.getAttribute('data-f')===filter));});
+  }
+  buttons.forEach(function(b){b.addEventListener('click',function(){apply(b.getAttribute('data-f'));});});
+})();
+"""
+
+
+def _esc(value: object) -> str:
+    return html_module.escape("" if value is None else str(value), quote=True)
+
+
+def render_html(report: Report) -> str:
+    """A single self-contained page: inline CSS, no fonts, no network, no build."""
+    meta = report.meta
+    summary = summarize_probes(report.probes) if report.probes else {}
+    parts: list[str] = []
+    parts.append("<!doctype html>")
+    parts.append('<html lang="en"><head><meta charset="utf-8">')
+    parts.append('<meta name="viewport" content="width=device-width,initial-scale=1">')
+    parts.append(f"<title>{_esc(meta.tool)} {_esc(meta.version)} \u00b7 {_esc(meta.command)}</title>")
+    parts.append(f"<style>{_CSS}</style></head><body><div class='wrap'>")
+
+    parts.append("<header>")
+    parts.append(f"<h1>{_esc(meta.tool)}<span class='v'>{_esc(meta.version)}</span></h1>")
+    bits = [meta.command, meta.gateway, meta.adapter, meta.stamp()]
+    parts.append(f"<div class='sub'>{_esc(_SEP.join(b for b in bits if b))}</div>")
+    parts.append("</header>")
+
+    if report.probes:
+        parts.append("<div class='tiles'>")
+        parts.append(_tile(summary.get("total", 0), "models probed", ""))
+        parts.append(_tile(summary.get("alive", 0), "alive", "good"))
+        parts.append(_tile(summary.get("starved", 0), "starved", "warn"))
+        parts.append(_tile(summary.get("dead", 0), "dead", "bad" if summary.get("dead") else ""))
+        parts.append(
+            _tile(len(report.prunable), "prunable", "bad" if report.prunable else "info")
+        )
+        parts.append(_tile(_latency(summary.get("median_latency_s", 0.0)), "median latency", "info"))
+        parts.append(_tile(f"#{meta.run_count}", "run", ""))
+        parts.append("</div>")
+
+        if summary.get("recovered"):
+            parts.append(
+                "<div class='warn'>"
+                f"{_esc(summary['recovered'])} model(s) answered inside the burst after failing "
+                f"an attempt ({_esc(summary['flaky'])} flaky in total). A single-probe gate would "
+                "have marked them dead \u2014 this is the measurement, not an opinion.</div>"
+            )
+
+        parts.append(f"<h2>probes <span class='sub'>attempts {_esc(meta.attempts)}</span></h2>")
+        verdict_counts = summary.get("by_verdict", {})
+        parts.append("<div class='filters'><button data-f='all' aria-pressed='true'>all</button>")
+        for verdict in taxonomy.VERDICTS:
+            count = verdict_counts.get(verdict, 0)
+            if not count:
+                continue
+            parts.append(
+                f"<button data-f='{_esc(verdict)}'>{_esc(verdict)} {_esc(count)}</button>"
+            )
+        parts.append("</div>")
+        parts.extend(_html_probe_table(report))
+
+    if report.bench:
+        parts.append("<h2>bench</h2>")
+        parts.extend(_html_bench_table(report))
+
+    if report.prunable:
+        parts.append("<h2>prune candidates</h2>")
+        parts.append("<div class='panel'><table><thead><tr>"
+                     "<th>model</th><th>provider</th><th class='num'>streak</th>"
+                     "<th class='num'>attempts</th><th>evidence</th></tr></thead><tbody>")
+        for row in report.prunable:
+            parts.append(
+                "<tr>"
+                f"<td class='model'>{_esc(row.model)}</td>"
+                f"<td class='prov'>{_esc(row.provider or '-')}</td>"
+                f"<td class='num'>{_esc(row.streak)}</td>"
+                f"<td class='num'>{_esc(row.attempts)}</td>"
+                f"<td class='note'>{_esc(row.note or '-')}</td>"
+                "</tr>"
+            )
+        parts.append("</tbody></table></div>")
+
+    advice = _advice_html(report)
+    if advice:
+        parts.append("<h2>what to do</h2>")
+        parts.append(f"<div class='panel' style='padding:14px 18px'>{advice}</div>")
+
+    if report.chains:
+        parts.append("<h2>fallback chains</h2>")
+        parts.append("<div class='panel'><table><thead><tr>"
+                     "<th>chain</th><th>rungs</th><th>issues</th></tr></thead><tbody>")
+        for chain in report.chains:
+            issues = chain.get("issues") or []
+            rungs = chain.get("rungs") or []
+            issue_html = (
+                "<br>".join(_esc(i) for i in issues) if issues else "<span class='k-ALIVE'>ok</span>"
+            )
+            parts.append(
+                "<tr>"
+                f"<td class='model'>{_esc(chain.get('label', '?'))}</td>"
+                f"<td>{_esc(_ARROW.join(rungs) or '(empty)')}</td>"
+                f"<td class='note'>{issue_html}</td>"
+                "</tr>"
+            )
+        parts.append("</tbody></table></div>")
+
+    if report.diff:
+        parts.append(f"<h2>planned edit \u00b7 {_esc(report.edit_path)}</h2>")
+        if report.edit_not_found:
+            parts.append(
+                "<div class='warn'>not found in config, left alone: "
+                f"{_esc(', '.join(report.edit_not_found))}</div>"
+            )
+        parts.append("<pre>")
+        for line in report.diff.splitlines():
+            css = "ctx"
+            if line.startswith("+") and not line.startswith("+++"):
+                css = "add"
+            elif line.startswith("-") and not line.startswith("---"):
+                css = "del"
+            elif line.startswith("@@"):
+                css = "hunk"
+            parts.append(f"<span class='{css}'>{_esc(line)}</span>")
+        parts.append("</pre>")
+
+    if meta.warnings:
+        parts.append("<h2>warnings</h2>")
+        for warning in meta.warnings:
+            parts.append(f"<div class='warn' style='margin-bottom:8px'>{_esc(warning)}</div>")
+
+    # argv is HTML-only: the terminal footer would wrap, and HTML is the
+    # artefact that gets shared — with the bearer key already masked by the CLI.
+    foot = _footer_parts(meta)
+    if meta.argv:
+        foot.append(" ".join(str(a) for a in meta.argv))
+    # Escaped once, here: two of the items above used to escape themselves and
+    # then get escaped again, which renders an ampersand as ``&amp;amp;``.
+    parts.append(f"<div class='foot'>{_esc(_SEP.join(str(f) for f in foot))}</div>")
+    parts.append(f"<script>{_JS}</script>")
+    parts.append("</div></body></html>")
+    return "\n".join(parts)
+
+
+def _tile(value: object, label: str, tone: str) -> str:
+    css = f"tile {tone}".strip()
+    return f"<div class='{css}'><div class='n'>{_esc(value)}</div><div class='l'>{_esc(label)}</div></div>"
+
+
+def _html_probe_table(report: Report) -> list[str]:
+    show_burst = report.meta.attempts > 1
+    pal = Palette(unicode=True)
+    out = ["<div class='panel'><table><thead><tr>"]
+    for name in ("verdict", "model", "provider", "latency"):
+        out.append(f"<th class='{'num' if name == 'latency' else ''}'>{name}</th>")
+    if show_burst:
+        out.append("<th>burst</th>")
+    for name in ("streak", "kind", "note"):
+        out.append(f"<th>{name}</th>")
+    out.append("</tr></thead><tbody>")
+
+    for item in report.probes:
+        fail, ok = report.streak_of(item.model)
+        streak = f"{_CROSS}{fail}" if fail else (f"ok{ok}" if ok else "-")
+        streak_css = "streak bad" if fail else "streak"
+        attr = report.attribution.get(item.model) or {}
+        upstream = attr.get("upstream") if isinstance(attr, dict) else ""
+        title = f" upstream={_esc(upstream)}" if upstream and upstream != item.model else ""
+        out.append(f"<tr data-v='{_esc(item.verdict)}'>")
+        out.append(
+            f"<td><span class='badge b-{_esc(item.verdict)}'>{_esc(item.verdict)}</span></td>"
+        )
+        out.append(f"<td class='model'{title}>{_esc(item.model)}</td>")
+        out.append(f"<td class='prov'>{_esc(item.provider or '-')}</td>")
+        out.append(f"<td class='num'>{_esc(_latency(item.latency_s))}</td>")
+        if show_burst:
+            glyphs = "".join(
+                f"<span class='g-{_esc(verdict)}'>{_esc(pal.glyph(verdict))}</span>"
+                for verdict, _note in item.history
+            )
+            # Recovery is a property of the burst, not of the state file: a model
+            # that failed attempt 1 and answered on attempt 2 is the whole reason
+            # the burst exists, and a persisted streak knows nothing about it.
+            failed_inside = any(verdict in taxonomy.DEAD for verdict, _n in item.history)
+            recovered = " \u00b7 recovered inside burst" if failed_inside and not item.dead else ""
+            out.append(
+                f"<td class='burst' title='{_esc(str(item.attempts))} attempts{recovered}'>"
+                f"{glyphs or '-'}</td>"
+            )
+        out.append(f"<td class='{streak_css}'>{_esc(streak)}</td>")
+        kind = item.kind if item.kind != taxonomy.ALIVE else "-"
+        out.append(f"<td class='k-{_esc(item.kind)}'>{_esc(kind)}</td>")
+        note = item.note or "-"
+        if item.dead and item.advice:
+            note = f"{note}{_DASH}{item.advice}"
+        out.append(f"<td class='note'>{_esc(note)}</td>")
+        out.append("</tr>")
+
+    if not report.probes:
+        span = 8 if show_burst else 7
+        out.append(f"<tr><td colspan='{span}' class='empty'>nothing probed</td></tr>")
+    out.append("</tbody></table></div>")
+    return out
+
+
+def _html_bench_table(report: Report) -> list[str]:
+    out = ["<div class='panel'><table><thead><tr>"]
+    out.append("<th>model</th><th>provider</th>")
+    for name in ("latency", "ttft", "tokens", "tok/s", "source"):
+        out.append(f"<th class='num'>{name}</th>")
+    out.append("<th>note</th></tr></thead><tbody>")
+
+    for item in report.bench:
+        if item.ok:
+            throughput = f"{item.tok_s:.1f}" if item.tok_s_exact else (
+                f"&gt;={item.tok_s:.1f}" if item.tok_s > 0 else "-"
+            )
+            title = (
+                "exact: usage.completion_tokens from the reply"
+                if item.tok_s_exact
+                else "lower bound: counted SSE chunks, a transport artifact"
+                if item.tok_s > 0
+                else "no token evidence: refused to guess"
+            )
+            note = "-"
+        else:
+            throughput = "-"
+            title = ""
+            note = item.error or item.verdict or "dead"
+        # Hoisted out of the f-string: a three-way ternary inside an attribute
+        # is unreadable, and the tone is a claim about evidence, not decoration.
+        if not item.ok:
+            tone = "PERMANENT"
+        elif item.tok_s_exact:
+            tone = "ALIVE"
+        else:
+            tone = "ALIVE-STARVED"
+        out.append("<tr>")
+        out.append(f"<td class='model'>{_esc(item.model)}</td>")
+        out.append(f"<td class='prov'>{_esc(item.provider or '-')}</td>")
+        out.append(f"<td class='num'>{_esc(_latency(item.latency_s))}</td>")
+        out.append(f"<td class='num'>{_esc(_latency(item.ttft_s))}</td>")
+        out.append(f"<td class='num'>{_esc(item.tokens or '-')}</td>")
+        out.append(f"<td class='num k-{tone}' title='{_esc(title)}'>{throughput}</td>")
+        out.append(f"<td class='num prov'>{_esc(item.token_source)}</td>")
+        out.append(f"<td class='note'>{_esc(note)}</td>")
+        out.append("</tr>")
+
+    if not report.bench:
+        out.append("<tr><td colspan='8' class='empty'>nothing measured</td></tr>")
+    out.append("</tbody></table></div>")
+
+    summary = report.bench_summary
+    if summary:
+        alive = summary.get("alive", 0)
+        exact = summary.get("with_exact_tokens", 0)
+        out.append(
+            "<p class='sub' style='margin-top:10px'>"
+            f"{_esc(alive)}/{_esc(summary.get('total', 0))} answered \u00b7 median latency "
+            f"{_esc(_latency(float(summary.get('median_latency_s', 0.0))))} \u00b7 "
+            f"{_esc(exact)} exact token counts, {_esc(alive - exact)} lower-bound or unmeasured."
+            " Ranked by latency, which is always measured exactly; tok/s from chunk counts is a "
+            "hard lower bound and is never comparable to a usage-based figure.</p>"
+        )
+    return out
+
+
+def _advice_html(report: Report) -> str:
+    seen: dict[str, int] = {}
+    order: list[str] = []
+    for item in report.probes:
+        if item.kind == taxonomy.ALIVE:
+            continue
+        seen[item.kind] = seen.get(item.kind, 0) + 1
+        if item.kind not in order:
+            order.append(item.kind)
+    items = []
+    for kind in order:
+        text = taxonomy.advice(kind)
+        if not text:
+            continue
+        items.append(
+            f"<li><code class='k-{_esc(kind)}'>{_esc(kind)}</code> "
+            f"({_esc(seen[kind])}) \u2014 {_esc(text)}</li>"
+        )
+    if report.prunable:
+        items.append(
+            f"<li><code>{_esc(len(report.prunable))}</code> model(s) passed every prune guard. "
+            "Nothing is written without <code>--apply</code>.</li>"
+        )
+    return f"<ul class='advice'>{''.join(items)}</ul>" if items else ""