loghunter-cli 0.1.0.dev0__py3-none-any.whl

loghunter/outputs/text.py

@@ -0,0 +1,1422 @@
+"""Text output handler — default stdout format.
+
+Output is grouped by detector, each section with a header and ───── separator.
+Default output: title, severity tag, key evidence fields only.
+Verbose adds: description, full evidence dict, next_steps, data window.
+next_steps are never shown in default output.
+
+Looks crafted, not generated. Minimal ASCII decoration.
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any, TextIO
+
+from loghunter.common.display import (
+    TEXT_RULE,
+    TEXT_RULE_DOUBLE,
+    TEXT_RULE_WIDTH,
+    human_bytes,
+    paint,
+)
+from loghunter.common.finding import (
+    BlobCard,
+    DigestCard,
+    Finding,
+    MethodTag,
+    RunSummary,
+    Severity,
+)
+from loghunter.common.output import OutputHandler, register_handler
+
+_WIDTH = TEXT_RULE_WIDTH
+_SEP = TEXT_RULE
+_SEP_DOUBLE = TEXT_RULE_DOUBLE
+_SUMMARY_LABEL_WIDTH = 14
+
+# Minimum (requested_span − data_span) before the data-found line discloses an
+# underfilled window — below this the operator effectively got what they asked for.
+_UNDERFILL_TOLERANCE = timedelta(hours=1)
+
+
+def _fmt_window(window: tuple) -> str:
+    s, e = window
+    span = e - s
+    days = span.days + span.seconds / 86400
+    return (
+        f"{s.strftime('%Y-%m-%d %H:%M')}  →  {e.strftime('%Y-%m-%d %H:%M')}"
+        f"  ({days:.1f}d)"
+    )
+
+
+def _fmt_span(td: timedelta) -> str:
+    """Compact span for the data-found underfill parenthetical.
+
+    ``< 24h`` → integer hours (``"18h"``); ``>= 24h`` → days, integer when whole
+    else one decimal (``"2d"``, ``"1.5d"``). Rounding never crosses a unit
+    surprisingly: an hours value that rounds up to a full day prints ``"1d"``,
+    not ``"24h"``.
+    """
+    hours = td.total_seconds() / 3600
+    if hours < 24:
+        rounded = int(round(hours))
+        if rounded < 24:
+            return f"{rounded}h"
+        # rounded up to a full day — promote the unit rather than print "24h"
+        return "1d"
+    days = td.total_seconds() / 86400
+    if abs(days - round(days)) < 1e-9:
+        return f"{int(round(days))}d"
+    return f"{days:.1f}d"
+
+
+def _aws_span_str(seconds: float) -> str:
+    """Compact span used by burst rows: 45s / 7m / 3h / 2d."""
+    s = int(seconds)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        return f"{s // 60}m"
+    if s < 86400:
+        return f"{s // 3600}h"
+    return f"{s // 86400}d"
+
+
+# ── digest helpers (used by TextHandler.render_digest) ───────────────────────
+
+_HIST_GLYPHS = "▁▂▃▄▅▆▇█"   # U+2581..U+2588
+
+
+def _bar_glyph(value: int, peak: int) -> str:
+    """Map a per-bin count to one of 8 block-character glyphs.
+
+    Zero and below render as the lowest glyph (▁) — visual continuity beats
+    a blank space when the histogram band is meant to be read as a line.
+    Values at or above peak render as the highest glyph (█).
+    """
+    if peak <= 0 or value <= 0:
+        return _HIST_GLYPHS[0]
+    if value >= peak:
+        return _HIST_GLYPHS[-1]
+    idx = int((value / peak) * (len(_HIST_GLYPHS) - 1))
+    return _HIST_GLYPHS[max(0, min(len(_HIST_GLYPHS) - 1, idx))]
+
+
+def _format_count(n: int) -> str:
+    """Compact-number formatter for histogram peak anchors."""
+    if n < 1000:
+        return str(n)
+    if n < 1_000_000:
+        return f"{n / 1000:.1f}k"
+    if n < 1_000_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    return f"{n / 1_000_000_000:.1f}B"
+
+
+def _render_histogram(
+    counts: list[int], unit: str, peak: int, *, unavailable: bool = False,
+) -> str:
+    """Render the temporal histogram as a single-line band, flush-left.
+
+    The line carries BOTH an axis unit label ("hourly bins" / "daily bins")
+    AND a scale anchor ("peak: N"). Without both, a busy-flat and a
+    quiet-flat timeline render identically — the unit names the bar width
+    and the anchor names the bar height.
+
+    Three rendering branches, in precedence order:
+
+    1. ``unavailable=True`` → bare ``(timeline unavailable)`` — the caller
+       suppressed the histogram because timestamps in the source frame
+       could not be parsed with confidence. Distinct from "no events".
+       Both former failure modes (low-coverage / zero-span) render here
+       identically; the flat card has no footer to differentiate them.
+    2. ``peak <= 0`` or empty ``counts`` → ``(no events in window)`` — the
+       valid empty-timeline case: no records in the loaded window.
+    3. Otherwise → the bar render with unit label + peak anchor.
+    """
+    if unavailable:
+        return "(timeline unavailable)"
+    if peak <= 0 or not counts:
+        return "(no events in window)"
+    bars = "".join(_bar_glyph(c, peak) for c in counts)
+    unit_label = "hourly bins" if unit == "hr" else "daily bins"
+    return f"{bars}  {unit_label} · peak: {_format_count(peak)}"
+
+
+def _render_label_value_block(rows: list[tuple[str, str]]) -> list[str]:
+    """Flush-left ``label: value`` block with the value column aligned.
+
+    Shared by the ambient block (Zone 1) and the fields block (former
+    Zone 3) on every digest card. Label width is computed from the rows
+    in this block only — no cross-block alignment. The labels are
+    flush-left at column 0; alignment is in the value column.
+
+    Long entities (flows, domains) render in FULL — never truncated. The
+    text-output rail forbids truncating naturally-long values on schema
+    cards. Blob's wide-list slots use a separate blob-local clamp; see
+    ``_wrap_blob_slot_value`` below.
+    """
+    if not rows:
+        return []
+    label_w = max(len(label) for label, _ in rows)
+    return [
+        f"{(label + ':').ljust(label_w + 2)}{value}"
+        for label, value in rows
+    ]
+
+
+# ── Blob-only: two-line clamp for the wide-list slot (`fields:` / `tokens:`)
+#
+# Blob's `fields:` row carries a top-level-keys list that on a Zeek conn
+# log can easily run 20+ names; the `tokens:` row defensively shares the
+# same clamp so a degenerate token row cannot blow past the 80-col frame.
+# Schema cards keep rendering through ``_render_label_value_block`` and
+# are exempt from this clamp — long entities like flows/domains must
+# render in full per the text-output rail.
+
+def _wrap_blob_slot_value(
+    value: str, *, label_col: int, sep: str,
+) -> list[str]:
+    """Two-line clamp for blob's wide-list slot value.
+
+    Line 1 starts at column ``label_col`` (max blob-slot label width + 2,
+    matching ``_render_label_value_block``'s sizing exactly). Line 2 hang-
+    indents to ``label_col``. Splits ONLY on ``sep`` — never breaks a
+    part — so the "never split a field name" rule is honoured.
+
+    A list that fits one line renders one line, no suffix. When the full
+    list doesn't fit two lines, truncates to what fits on line 2 and
+    appends ``… +N more`` (N = total parts minus parts rendered). A part
+    longer than the available width lands on its own line and may exceed
+    the 80-col frame; the load-bearing rule is unbroken parts.
+    """
+    available = _WIDTH - label_col
+    parts = value.split(sep)
+
+    # Single-line short-circuit.
+    if len(value) <= available:
+        return [value]
+
+    # Greedy-pack line 1.
+    line1_parts: list[str] = []
+    line1_len = 0
+    i = 0
+    while i < len(parts):
+        part = parts[i]
+        added = len(part) if not line1_parts else len(sep) + len(part)
+        if line1_parts and line1_len + added > available:
+            break
+        line1_parts.append(part)
+        line1_len += added
+        i += 1
+    if not line1_parts:  # first part already too wide — emit it alone
+        line1_parts = [parts[0]]
+        i = 1
+    line1 = sep.join(line1_parts)
+
+    # Greedy-pack line 2, reserving suffix room only if MORE parts remain
+    # after a tentative full pack.
+    indent = " " * label_col
+    remaining = parts[i:]
+    suffix_template = f"{sep}… +{{n}} more"
+
+    # First pass: greedy pack remaining into line 2 without suffix reserve.
+    line2_parts: list[str] = []
+    line2_len = 0
+    j = 0
+    while j < len(remaining):
+        part = remaining[j]
+        added = len(part) if not line2_parts else len(sep) + len(part)
+        if line2_parts and line2_len + added > available:
+            break
+        line2_parts.append(part)
+        line2_len += added
+        j += 1
+    if not line2_parts and remaining:
+        line2_parts = [remaining[0]]
+        j = 1
+
+    truncated = j < len(remaining)
+    if truncated:
+        # Re-pack reserving room for `… +N more`. N is unknown until
+        # we know how many parts we kept, so iterate: each removed part
+        # bumps N (suffix grows by ~1 char per digit decade). Cap the
+        # re-pack loop trivially — at most len(remaining) iterations.
+        for _ in range(len(remaining) + 1):
+            n_remaining = len(remaining) - len(line2_parts)
+            if n_remaining <= 0:
+                break
+            suffix = suffix_template.format(n=n_remaining)
+            candidate_len = (
+                sum(len(p) for p in line2_parts)
+                + len(sep) * (len(line2_parts) - 1)
+                + len(suffix)
+            )
+            if candidate_len <= available:
+                break
+            if len(line2_parts) <= 1:
+                break  # can't shrink further — accept overflow
+            line2_parts.pop()
+        n_remaining = len(remaining) - len(line2_parts)
+        line2 = (
+            indent
+            + sep.join(line2_parts)
+            + suffix_template.format(n=n_remaining)
+        )
+    else:
+        line2 = indent + sep.join(line2_parts) if line2_parts else ""
+
+    return [line1, line2] if line2 else [line1]
+
+
+def _summary_line(label: str, value: object) -> list[str]:
+    """Render a wrapped run-summary row with continuation text aligned."""
+    prefix = f"{label:<{_SUMMARY_LABEL_WIDTH}} "
+    subsequent = " " * len(prefix)
+    text = str(value)
+    wrap_width = max(20, _WIDTH - len(prefix))
+    wrapped = textwrap.wrap(
+        text,
+        width=wrap_width,
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+    if not wrapped:
+        wrapped = [""]
+    return [
+        f"{prefix if i == 0 else subsequent}{part}"
+        for i, part in enumerate(wrapped)
+    ]
+
+
+# ── W2 card pipeline — structured findings before row formatting ────────────
+
+
+@dataclass
+class Section:
+    """One subsection of a detector's findings — already level-filtered,
+    severity-sorted, and post-cap. Renderers consume this — no filtering,
+    sorting, or capping happens inside per-detector row formatters.
+
+    ``label`` is None for a flat detector (no subsection line emitted).
+    ``pre_cap_count`` is this section's level-visible size BEFORE the cap;
+    the subsection label always reports the pre-cap count.
+    """
+
+    label: str | None
+    findings: list[Finding]
+    pre_cap_count: int
+
+
+@dataclass
+class DetectorRenderable:
+    """Per-detector pipeline result. Built by ``_build_renderable`` before any
+    row formatting. Carries pre-cap counts and severity breakdown as sidecars
+    so the group header NEVER re-reads severity from post-cap ``Section.findings``.
+    """
+
+    sections: list[Section]
+    level_visible_total: int
+    severity_breakdown: dict[Severity, int]
+    cap_truncated: int = 0
+
+
+_SEVERITY_ORDER: tuple[Severity, ...] = (
+    Severity.HIGH,
+    Severity.MEDIUM,
+    Severity.LOW,
+    Severity.INFO,
+)
+
+
+def _severity_sort_key(f: Finding) -> int:
+    """Stable severity-primary sort key (HIGH=0 … INFO=3). Within a band, the
+    detector's incoming secondary order survives (entropy desc, composite-z
+    desc, etc.) because Python's sort is stable."""
+    return _SEVERITY_ORDER.index(f.severity)
+
+
+def _partition_dns(findings: list[Finding]) -> list[Section]:
+    """DNS: singletons FIRST (no subdomain_count), then groups (Dave's call —
+    the singletons tier is consistently the more interesting one). Each
+    speaks-iff-non-empty: an empty subsection vanishes entirely."""
+    singletons = [f for f in findings if "subdomain_count" not in f.evidence]
+    groups = [f for f in findings if "subdomain_count" in f.evidence]
+    out: list[Section] = []
+    if singletons:
+        out.append(Section("singletons", singletons, len(singletons)))
+    if groups:
+        out.append(Section("groups", groups, len(groups)))
+    return out
+
+
+def _partition_aws(findings: list[Finding]) -> list[Section]:
+    """AWS: bursts first, then ranked (+ synthetic ranked_summary). The ranked
+    section bundles per-principal and the summary line together."""
+    bursts = [f for f in findings if f.evidence.get("tier") == "burst"]
+    ranked = [f for f in findings if f.evidence.get("tier") in ("ranked", "ranked_summary")]
+    out: list[Section] = []
+    if bursts:
+        out.append(Section("burst sweeps", bursts, len(bursts)))
+    if ranked:
+        out.append(Section("ranked principals", ranked, len(ranked)))
+    return out
+
+
+def _partition_flat(findings: list[Finding]) -> list[Section]:
+    """Flat detector — one section with no label."""
+    return [Section(None, findings, len(findings))]
+
+
+_PARTITIONERS = {
+    "dns": _partition_dns,
+    "aws": _partition_aws,
+}
+
+# Per-detector severity-sort opt-out (CR #2 from James). Severity sort is the
+# right DEFAULT — within a flat or per-section list, H → M → L → I reads as
+# urgency-first. But syslog's row order CARRIES meaning: the detector emits
+# chronologically so a synthetic reboot INFO annotation sits AMONG the rare
+# MEDIUM template events near it (the "these rare events cluster around this
+# reboot" narrative). Severity-sorting regroups all-MEDIUM-then-all-INFO and
+# divorces each reboot from its context. Detectors listed here keep their
+# incoming order.
+_SEVERITY_SORT_EXEMPT: frozenset[str] = frozenset({"syslog"})
+
+# Synthetic always-show finding tiers (CR #4 from James). These are
+# all-clear / quiet-summary rows the detector designed to render
+# unconditionally. They are exempt from the W5 cap budget — they neither
+# count against the budget nor get dropped when the budget runs out. Today
+# the only entry is aws's ``ranked_summary`` (the "nothing stood out" line).
+# New synthetic all-show tiers join this set; the renderer is otherwise
+# unchanged.
+_ALWAYS_SHOW_TIERS: frozenset[str] = frozenset({"ranked_summary"})
+
+
+def _is_always_show(finding: Finding) -> bool:
+    """True for synthetic always-show findings (CR #4). Exempt from the cap."""
+    return finding.evidence.get("tier") in _ALWAYS_SHOW_TIERS
+
+
+def _level_filter(detector: str, findings: list[Finding], verbose_level: int) -> list[Finding]:
+    """W2 pipeline step 1 — the one finding-visibility-by-level rule.
+
+    Duration hides LOW findings at verbose_level 0 (W6 moved this off the
+    detector's run() and into the text-render seam). Every other detector is
+    a no-op. The result-set returned to machine handlers is invariant; only
+    the text handler applies this filter.
+    """
+    if detector == "duration" and verbose_level == 0:
+        return [f for f in findings if f.severity != Severity.LOW]
+    return findings
+
+
+def _build_renderable(
+    detector: str,
+    findings: list[Finding],
+    verbose_level: int,
+    max_per_detector: int,
+) -> DetectorRenderable:
+    """Run the W2 pipeline on one detector's findings.
+
+    Order is binding:
+      1. level-filter (duration LOW at level 0)
+      2. partition into Sections (detector-specific)
+      3. capture pre-cap level_visible_total + severity_breakdown
+      4. severity-sort each section in place
+      5. cap walks sections in declared order; truncates findings; sets
+         cap_truncated; later sections may end up with findings=[] and
+         vanish at render time
+
+    Both ``level_visible_total`` and ``severity_breakdown`` are captured
+    BEFORE the cap so the group header NEVER drifts to post-cap counts —
+    the pre-cap regression test in tests/test_text_output.py guards this.
+    """
+    level_visible = _level_filter(detector, findings, verbose_level)
+
+    partition = _PARTITIONERS.get(detector, _partition_flat)
+    sections = partition(level_visible)
+
+    level_visible_total = len(level_visible)
+    breakdown: dict[Severity, int] = {}
+    for f in level_visible:
+        breakdown[f.severity] = breakdown.get(f.severity, 0) + 1
+
+    if detector not in _SEVERITY_SORT_EXEMPT:
+        for s in sections:
+            s.findings.sort(key=_severity_sort_key)
+
+    # CR #4: synthetic always-show findings are exempt from the cap. Pull
+    # them out per-section before the budget walk so they neither consume
+    # the budget nor risk being dropped, then re-append them at the tail
+    # of their section (preserving the existing aws renderer's
+    # per-principal-then-summary order). Renderer code is unchanged.
+    always_show_by_section: list[list[Finding]] = []
+    for s in sections:
+        always = [f for f in s.findings if _is_always_show(f)]
+        if always:
+            s.findings = [f for f in s.findings if not _is_always_show(f)]
+        always_show_by_section.append(always)
+
+    cap_truncated = 0
+    # Cap accounting runs against the cappable count only (always-show
+    # findings live outside the budget).
+    cappable_total = sum(len(s.findings) for s in sections)
+    if max_per_detector > 0 and cappable_total > max_per_detector:
+        remaining = max_per_detector
+        for s in sections:
+            if remaining <= 0:
+                cap_truncated += len(s.findings)
+                s.findings = []
+                continue
+            if len(s.findings) > remaining:
+                cap_truncated += len(s.findings) - remaining
+                s.findings = s.findings[:remaining]
+                remaining = 0
+            else:
+                remaining -= len(s.findings)
+
+    # Re-append the held-back always-show findings at the tail of their
+    # section. This preserves the existing aws renderer's "per-principal
+    # rows, then summary line" layout and keeps the all-clear visible even
+    # when the cap empties the cappable rows.
+    for s, always in zip(sections, always_show_by_section):
+        if always:
+            s.findings.extend(always)
+
+    return DetectorRenderable(
+        sections=sections,
+        level_visible_total=level_visible_total,
+        severity_breakdown=breakdown,
+        cap_truncated=cap_truncated,
+    )
+
+
+def _verbose_tail(finding: Finding, indent: str, extras: dict[str, Any] | None = None) -> list[str]:
+    """Curated 'why it scored' — level 1. Returns [] when no material to show.
+
+    Vanish discipline: a Finding with empty description / next_steps and an
+    empty curated-evidence subset renders the title line ALONE — no empty
+    headers, no dangling indents, NO trailing ``data window:`` line. The
+    data-window line appears only when at least one other body element is
+    present.
+    """
+    body: list[str] = []
+    if finding.description:
+        body.append(f"{indent}{finding.description}")
+    if extras:
+        body.append(f"{indent}evidence:")
+        for k, v in extras.items():
+            body.append(f"{indent}  {k}: {v}")
+    if finding.next_steps:
+        body.append(f"{indent}next steps:")
+        for step in finding.next_steps:
+            body.append(f"{indent}  · {step}")
+    if not body:
+        return []
+    body.append(f"{indent}data window: {_fmt_window(finding.data_window)}")
+    return body
+
+
+def _debug_tail(finding: Finding, indent: str) -> list[str]:
+    """Raw debug — level 2. Full evidence dict. Same vanish discipline as
+    ``_verbose_tail``: empty description / evidence / next_steps → ``[]``."""
+    body: list[str] = []
+    if finding.description:
+        body.append(f"{indent}{finding.description}")
+    if finding.evidence:
+        body.append(f"{indent}evidence:")
+        for k, v in finding.evidence.items():
+            body.append(f"{indent}  {k}: {v}")
+    if finding.next_steps:
+        body.append(f"{indent}next steps:")
+        for step in finding.next_steps:
+            body.append(f"{indent}  · {step}")
+    if not body:
+        return []
+    body.append(f"{indent}data window: {_fmt_window(finding.data_window)}")
+    return body
+
+
+# Per-detector curated-evidence subsets for level 1 — tolerant: omit absent
+# keys rather than printing ``None``. Per-variant lookup uses existing
+# evidence keys (scan's scan_type, dns's source, aws's tier, syslog by
+# template-vs-reboot shape).
+def _curated_evidence(finding: Finding) -> dict[str, Any]:
+    """Return ONLY the keys present on this Finding from the curated set for
+    its detector (and variant where applicable)."""
+    ev = finding.evidence
+    keys: tuple[str, ...] = ()
+    det = finding.detector
+
+    if det == "beacon":
+        keys = (
+            "beacon_score", "spectral_ratio", "prominence_norm",
+            "jitter_cv", "conn_count", "period_str",
+        )
+    elif det == "dns":
+        src = ev.get("source")
+        if "subdomain_count" in ev:  # group
+            base = ("sample_domains", "unique_sources", "min_entropy", "max_entropy")
+            extra = ("was_blocked", "block_ratio", "qtype_counts") if src == "pihole" else ()
+            keys = base + extra
+        elif src == "pihole":  # pihole singleton
+            keys = (
+                "unique_sources", "querier_ips",
+                "was_blocked", "block_ratio",
+                "cache_ratio", "forward_ratio", "qtype_counts",
+            )
+        else:  # zeek singleton (and both-mode Zeek with pihole enrichment)
+            base = ("rcode_distribution", "unique_sources", "querier_ips")
+            extra = ("was_blocked", "block_ratio") if "was_blocked" in ev else ()
+            keys = base + extra
+    elif det == "syslog":
+        if "template_str" in ev:
+            keys = ("template_str", "host", "count", "threshold")
+        else:  # reboot annotation
+            keys = ("host", "reboot_ts", "suppressed_window_seconds")
+    elif det == "scan":
+        keys = ("scan_state_ratio", "top_states", "direction", "pattern_tag")
+    elif det == "duration":
+        keys = ("avg_bytes_per_second", "conn_states", "connection_count")
+    elif det == "aws":
+        tier = ev.get("tier")
+        if tier == "burst":
+            keys = ("new_actions", "new_services", "error_rate", "mean_rarity")
+        else:  # ranked / ranked_summary
+            keys = (
+                "composite_z", "z_error_rate", "event_count",
+                "top_actions", "distinct_event_source",
+            )
+
+    return {k: ev[k] for k in keys if k in ev and not _is_empty(ev[k])}
+
+
+def _is_empty(value: Any) -> bool:
+    """numpy-safe emptiness test for curated evidence values.
+
+    The naive ``value not in (None, [], {})`` idiom evaluates ``value == []``
+    which a numpy scalar broadcasts into an empty boolean array; ``bool()`` of
+    that array raises ``ValueError`` and propagates straight out through
+    ``reporter.write``. ``aws`` burst ``error_rate``, ``scan``
+    ``scan_state_ratio`` (a rounded pandas mean), and beacon's spectral
+    scores all reach this path as numpy scalars under real data —
+    ``loghunter aws -v`` / ``scan -v`` died on every run.
+
+    Guard explicitly on the container types we want to omit (None / empty
+    str/list/tuple/dict). Anything else — including numpy scalars and
+    arrays — is treated as "has content" for display purposes; the renderer
+    formats them via the default ``f"{value}"`` path downstream.
+    """
+    if value is None:
+        return True
+    if isinstance(value, (list, tuple, dict, str)) and len(value) == 0:
+        return True
+    return False
+
+
+def _level_tail(finding: Finding, indent: str, verbose_level: int) -> list[str]:
+    """Dispatch to the right tail by level. Level 0 returns []; level 1 emits
+    the curated tail; level 2 emits the full debug tail. Both tails honor
+    vanish-don't-dash."""
+    if verbose_level <= 0:
+        return []
+    if verbose_level >= 2:
+        return _debug_tail(finding, indent)
+    return _verbose_tail(finding, indent, _curated_evidence(finding))
+
+
+def _render_group_header(detector: str, renderable: DetectorRenderable) -> list[str]:
+    """Header line: ``detector — N findings · 3 H  18 M  51 I`` + 80-col rule.
+
+    Counts and breakdown are PRE-CAP — read straight off the renderable's
+    ``level_visible_total`` and ``severity_breakdown`` sidecars, never
+    recomputed from ``Section.findings`` (which is post-cap)."""
+    total = renderable.level_visible_total
+    label = "findings" if total != 1 else "finding"
+    parts = [f"{detector} — {total} {label}"]
+    breakdown = renderable.severity_breakdown
+    cells = []
+    for sev in _SEVERITY_ORDER:
+        n = breakdown.get(sev, 0)
+        if n > 0:
+            cells.append(f"{n} {sev.value}")
+    if cells:
+        parts.append(" · " + "  ".join(cells))
+    return ["".join(parts), TEXT_RULE]
+
+
+def _render_cap_disclosure(detector: str, renderable: DetectorRenderable, cap: int) -> str:
+    """W5 disclosure: factual; deferred error-voice pass owns final wording.
+
+    Honesty rail (CR #3): the cap trims sections in DECLARED order, NOT
+    global severity. For a FLAT detector (one implicit section) the cap is
+    indeed by severity — sort-then-cap retains the highest tiers. For a
+    SUBSECTIONED detector (dns: singletons-first; aws: bursts-first) a
+    later section's HIGH row can be dropped while an earlier section's LOW
+    row survives the cap. So "by severity" is true only in the flat case.
+
+    Rather than spell out the cross-section non-guarantee in two arms, the
+    wording simply drops the severity claim. The hidden count and the cap
+    cap are what the operator needs to act on. Wording is placeholder-tier
+    pending the error-voice pass — the binding constraint is that we MUST
+    NOT claim severity-retention the cap doesn't provide.
+    """
+    hidden = renderable.cap_truncated
+    return (
+        f"… {hidden:,} more not shown (showing first {cap:,}). "
+        f"Unusually high — narrow with the allowlist, or this detector may be "
+        f"misbehaving."
+    )
+
+
+class TextHandler(OutputHandler):
+    """Write findings as aligned plain text to stdout (or a given stream)."""
+
+    def __init__(
+        self,
+        stream: TextIO = sys.stdout,
+        verbose_level: int = 0,
+        max_findings_per_detector: int = 100,
+    ) -> None:
+        self._stream = stream
+        self._verbose_level = verbose_level
+        self._max_findings_per_detector = max_findings_per_detector
+
+    def begin(self, run_summary: RunSummary) -> None:
+        """Print the run summary header before any findings."""
+        print(file=self._stream)
+        print(self._render_run_summary(run_summary), file=self._stream)
+
+    def write(self, findings: list[Finding]) -> None:
+        """Print findings grouped by detector with aligned columns.
+
+        Per detector, runs the W2 pipeline via ``_build_renderable`` (level-
+        filter → partition → pre-cap stats → severity-sort → cap). A detector
+        whose level-visible set is empty renders NOTHING — no header, no
+        rule, no label (the vanish rule). The disclosure line fires only
+        when the cap actually trimmed rows.
+        """
+        if not findings:
+            return
+
+        by_detector: dict[str, list[Finding]] = defaultdict(list)
+        for f in findings:
+            by_detector[f.detector].append(f)
+
+        for detector, group in by_detector.items():
+            renderable = _build_renderable(
+                detector, group, self._verbose_level, self._max_findings_per_detector,
+            )
+            if renderable.level_visible_total == 0:
+                continue
+            print(file=self._stream)
+            for line in _render_group_header(detector, renderable):
+                print(line, file=self._stream)
+            for line in self._render_group(detector, renderable.sections):
+                print(line, file=self._stream)
+            if renderable.cap_truncated > 0:
+                print(file=self._stream)
+                print(
+                    _render_cap_disclosure(detector, renderable, self._max_findings_per_detector),
+                    file=self._stream,
+                )
+            print(file=self._stream)
+
+    def end(self) -> None:
+        """No-op for text output — stdout needs no closing."""
+
+    def _render_run_summary(
+        self,
+        run_summary: RunSummary,
+        banner: str = "LogHunter  ·  Threat Hunt",
+    ) -> str:
+        """Render the detect-run banner.
+
+        Digest no longer flows through this helper — each digest card
+        carries its own identity block. This stays the single source of
+        truth for the detect-path banner; its output must be byte-identical
+        to its pre-flat-digest form on a normal detect run.
+        """
+        lines = [
+            banner,
+            _SEP_DOUBLE,
+        ]
+
+        if run_summary.data_window[0] and run_summary.data_window[1]:
+            lines.extend(_summary_line(
+                "Data found:", self._fmt_data_found(run_summary)
+            ))
+
+        if run_summary.record_counts:
+            counts_str = "  ·  ".join(
+                f"{v:,} {k}" for k, v in run_summary.record_counts.items()
+            )
+            lines.extend(_summary_line("Records:", counts_str))
+
+        if run_summary.detectors_run:
+            lines.extend(_summary_line(
+                "Detectors:",
+                self._render_detectors_value(run_summary),
+            ))
+
+        if run_summary.detectors_skipped:
+            for name, reason in run_summary.detectors_skipped.items():
+                lines.extend(_summary_line("Skipped:", f"{name} — {reason}"))
+
+        for note in run_summary.notes:
+            lines.extend(_summary_line("Note:", note))
+
+        lines.append(_SEP_DOUBLE)
+        return "\n".join(lines)
+
+    @staticmethod
+    def _fmt_data_found(run_summary: RunSummary) -> str:
+        """Render the data-found value.
+
+        Full / disjoint runs use ``_fmt_window`` UNCHANGED (the same helper feeds
+        the digest card and verbose finding tails — it must stay byte-identical).
+        Only an underfilled default/explicit window — data span short of the
+        requested span by at least ``_UNDERFILL_TOLERANCE`` — swaps in the
+        informative parenthetical (both spans via ``_fmt_span``).
+        """
+        s, e = run_summary.data_window
+        data_span = e - s
+        rs = run_summary.requested_span
+        if rs is not None and (rs - data_span) >= _UNDERFILL_TOLERANCE:
+            return (
+                f"{s.strftime('%Y-%m-%d %H:%M')}  →  {e.strftime('%Y-%m-%d %H:%M')}"
+                f"  ({_fmt_span(data_span)} data span in {_fmt_span(rs)} window)"
+            )
+        return _fmt_window(run_summary.data_window)
+
+    def _render_detectors_value(self, run_summary: RunSummary) -> str:
+        """Build the right-hand side of the Detectors: row.
+
+        Named methods (``MethodTag(named=True)``) render as ``name (label)``
+        with the label painted when ``self._stream`` is a real TTY (and
+        NO_COLOR / TERM=dumb don't opt out). Honest house badges
+        (``named=False``) render as ``name [label]`` plain. Detectors with
+        no ``DETECTOR_METHOD`` constant fall back to the bare name —
+        forward-compat for any future detector that ships without one.
+        Detectors joined by ``  ·  ``.
+        """
+        parts: list[str] = []
+        for name in run_summary.detectors_run:
+            tag: "MethodTag | None" = run_summary.detector_methods.get(name)
+            if tag is None:
+                parts.append(name)
+            elif tag.named:
+                parts.append(f"{name} ({paint(tag.label, stream=self._stream)})")
+            else:
+                parts.append(f"{name} [{tag.label}]")
+        return "  ·  ".join(parts)
+
+    def _render_group(self, detector: str, sections: list[Section]) -> list[str]:
+        """Render a detector's already-prepared sections (post level-filter,
+        sort, and cap). Per-detector renderers do pure row formatting only —
+        no filtering, sorting, counting, or capping leaks back here.
+        """
+        # Drop empty sections (cap may have emptied a later section — its label
+        # vanishes, no lonely label).
+        live = [s for s in sections if s.findings]
+        if not live:
+            return []
+        if detector == "beacon":
+            return self._render_beacon_group(live)
+        if detector == "dns":
+            return self._render_dns_group(live)
+        if detector == "scan":
+            return self._render_scan_group(live)
+        if detector == "syslog":
+            return self._render_syslog_group(live)
+        if detector == "duration":
+            return self._render_duration_group(live)
+        if detector == "aws":
+            return self._render_aws_group(live)
+        # Generic fallback — flat detector, one Section with label=None.
+        out: list[str] = []
+        for s in live:
+            for f in s.findings:
+                out.append(self._render_finding(f))
+        return out
+
+    def _render_beacon_group(self, sections: list[Section]) -> list[str]:
+        """Render beacon findings with fully aligned columns. Beacon is a flat
+        detector — one Section with label=None — so per-section column widths
+        match per-detector. → arrows align via independent sub-field padding."""
+        indent = "     "
+        out: list[str] = []
+        findings = sections[0].findings  # flat: single section
+
+        rows = []
+        for f in findings:
+            ev = f.evidence
+            src = ev.get("src_ip", "")
+            dst_str = f"{ev.get('dst_ip', '')}:{ev.get('dst_port', '')}/{ev.get('proto', '')}"
+            period_col = f"period={ev.get('period_str', '?')}"
+            score_col = f"score={ev.get('beacon_score', 0):.3f}"
+            conns_col = f"{ev.get('conn_count', 0):,} conns"
+            rows.append((str(f.severity), src, dst_str, period_col, score_col, conns_col, f))
+
+        src_w    = max(len(r[1]) for r in rows)
+        dst_w    = max(len(r[2]) for r in rows)
+        period_w = max(len(r[3]) for r in rows)
+        # score is always "score=0.XXX" — 11 chars, no padding needed
+        conns_w  = max(len(r[5]) for r in rows)
+
+        for tag, src, dst_str, period_col, score_col, conns_col, f in rows:
+            line = (
+                f"{tag}  {src:<{src_w}}  →  {dst_str:<{dst_w}}   "
+                f"{period_col:<{period_w}}   {score_col}   "
+                f"{conns_col:>{conns_w}}"
+            )
+            tail = _level_tail(f, indent, self._verbose_level)
+            if tail:
+                out.append(line + "\n" + "\n".join(tail))
+            else:
+                out.append(line)
+        return out
+
+    def _render_dns_group(self, sections: list[Section]) -> list[str]:
+        """Render DNS findings: singletons FIRST, then groups (Dave redline:
+        singletons-first preserved). Each section gets a plain lowercase
+        ``label (N)`` line (pre-cap count from the section) — no ── rules.
+        Column widths derived from the section's findings before any row is
+        formatted. blocked column omitted when no row in the section has
+        was_blocked=True — preserves the pre-pihole Zeek-only output exactly.
+        """
+        indent = "     "
+        out: list[str] = []
+
+        for si, section in enumerate(sections):
+            label_line = f"{section.label} ({section.pre_cap_count})"
+            if si > 0:
+                out.append("")
+            out.append(label_line)
+
+            if section.label == "singletons":
+                rows = []
+                for f in section.findings:
+                    ev = f.evidence
+                    tag = f"{str(f.severity):<4}"
+                    ent_col = f"ent={ev['entropy']:.2f}"
+                    qry_col = f"{ev['query_count']} qry"
+                    src_col = f"{ev['unique_sources']} src"
+                    blocked_col = "BLOCKED" if ev.get("was_blocked") else ""
+                    rows.append((tag, ent_col, qry_col, src_col, blocked_col, f.title, f))
+
+                ent_w     = max(len(r[1]) for r in rows)
+                qry_w     = max(len(r[2]) for r in rows)
+                src_w     = max(len(r[3]) for r in rows)
+                blocked_w = max(len(r[4]) for r in rows)
+
+                for tag, ent_col, qry_col, src_col, blocked_col, domain, f in rows:
+                    if blocked_w > 0:
+                        line = (
+                            f"  {tag}  {ent_col:<{ent_w}}  "
+                            f"{qry_col:>{qry_w}}  {src_col:>{src_w}}  "
+                            f"{blocked_col:<{blocked_w}}  {domain}"
+                        )
+                    else:
+                        line = (
+                            f"  {tag}  {ent_col:<{ent_w}}  "
+                            f"{qry_col:>{qry_w}}  {src_col:>{src_w}}  {domain}"
+                        )
+                    tail = _level_tail(f, indent, self._verbose_level)
+                    if tail:
+                        out.append(line + "\n" + "\n".join(tail))
+                    else:
+                        out.append(line)
+            else:  # "groups"
+                rows = []
+                for f in section.findings:
+                    ev = f.evidence
+                    tag = f"{str(f.severity):<4}"
+                    sub_col = f"{ev['subdomain_count']} sub"
+                    max_e, min_e = ev["max_entropy"], ev["min_entropy"]
+                    ent_col = (
+                        f"ent={max_e:.2f}"
+                        if max_e == min_e
+                        else f"ent={max_e:.2f}–{min_e:.2f}"
+                    )
+                    qry_col = f"{ev['total_queries']} qry"
+                    src_col = f"{ev['unique_sources']} src"
+                    blocked_col = "BLOCKED" if ev.get("was_blocked") else ""
+                    rows.append((tag, sub_col, ent_col, qry_col, src_col, blocked_col, ev["registrable_domain"], f))
+
+                sub_w     = max(len(r[1]) for r in rows)
+                ent_w     = max(len(r[2]) for r in rows)
+                qry_w     = max(len(r[3]) for r in rows)
+                src_w     = max(len(r[4]) for r in rows)
+                blocked_w = max(len(r[5]) for r in rows)
+
+                for tag, sub_col, ent_col, qry_col, src_col, blocked_col, domain, f in rows:
+                    if blocked_w > 0:
+                        line = (
+                            f"  {tag}  {sub_col:>{sub_w}}  {ent_col:<{ent_w}}  "
+                            f"{qry_col:>{qry_w}}  {src_col:>{src_w}}  "
+                            f"{blocked_col:<{blocked_w}}  {domain}"
+                        )
+                    else:
+                        line = (
+                            f"  {tag}  {sub_col:>{sub_w}}  {ent_col:<{ent_w}}  "
+                            f"{qry_col:>{qry_w}}  {src_col:>{src_w}}  {domain}"
+                        )
+                    tail = _level_tail(f, indent, self._verbose_level)
+                    if tail:
+                        out.append(line + "\n" + "\n".join(tail))
+                    else:
+                        out.append(line)
+
+        return out
+
+    def _render_scan_group(self, sections: list[Section]) -> list[str]:
+        """Render scan findings with aligned columns across all scan types. Flat
+        detector. Columns: severity | scan_type | ratio | src | type-specific
+        middle | metric. Widths derived from the section's findings before any
+        row is formatted."""
+        indent = "     "
+        out: list[str] = []
+        findings = sections[0].findings
+
+        rows = []
+        for f in findings:
+            ev        = f.evidence
+            tag       = f"{str(f.severity):<4}"
+            type_col  = ev.get("scan_type", "")
+            ratio_col = f"ratio={ev.get('scan_state_ratio', 0):.2f}"
+            src_col   = ev.get("src", "")
+            scan_type = ev.get("scan_type", "")
+
+            if scan_type == "vertical":
+                middle_col = f"→ {ev.get('dst', '')}"
+                metric_col = f"{ev.get('distinct_ports', 0)} ports"
+            elif scan_type == "horizontal":
+                middle_col = f"→ *:{ev.get('port', '')}"
+                metric_col = f"{ev.get('distinct_hosts', 0)} hosts"
+            elif scan_type == "block":
+                middle_col = "→ *"
+                metric_col = f"{ev.get('distinct_ports', 0)}p × {ev.get('distinct_hosts', 0)}h"
+            else:  # slow
+                middle_col = ""
+                metric_col = f"{ev.get('distinct_ports', 0)} ports/{ev.get('active_buckets', 0)} win"
+
+            rows.append((tag, type_col, ratio_col, src_col, middle_col, metric_col, f))
+
+        type_w   = max(len(r[1]) for r in rows)
+        ratio_w  = max(len(r[2]) for r in rows)
+        src_w    = max(len(r[3]) for r in rows)
+        middle_w = max(len(r[4]) for r in rows)
+        metric_w = max(len(r[5]) for r in rows)
+
+        for tag, type_col, ratio_col, src_col, middle_col, metric_col, f in rows:
+            line = (
+                f"{tag}  {type_col:<{type_w}}  {ratio_col:<{ratio_w}}  "
+                f"{src_col:<{src_w}}  {middle_col:<{middle_w}}  {metric_col:>{metric_w}}"
+            )
+            tail = _level_tail(f, indent, self._verbose_level)
+            if tail:
+                out.append(line + "\n" + "\n".join(tail))
+            else:
+                out.append(line)
+        return out
+
+    def _render_syslog_group(self, sections: list[Section]) -> list[str]:
+        """Render syslog findings. Flat detector. Default MEDIUM output is the
+        severity + raw event line; INFO reboot annotations are a compact single
+        line. Verbose tails are shared via ``_level_tail`` — for MEDIUM the
+        curated subset surfaces the template & count details (drain3 internals
+        that stay behind -v / -vv)."""
+        indent = "     "
+        out: list[str] = []
+        findings = sections[0].findings
+
+        host_w = max(len(f.evidence.get("host", "")) for f in findings)
+
+        for f in findings:
+            ev   = f.evidence
+            host = ev.get("host", "")
+            tag  = str(f.severity)
+
+            if f.severity == Severity.MEDIUM:
+                line = f"{tag}  {f.title}"
+            else:  # INFO — reboot annotation
+                reboot_ts = ev.get("reboot_ts") or "unknown"
+                window    = ev.get("suppressed_window_seconds", 0)
+                line = (
+                    f"{tag}  {host:<{host_w}}  reboot @ {reboot_ts}"
+                    f"   suppressed {window}s window"
+                )
+
+            tail = _level_tail(f, indent, self._verbose_level)
+            if tail:
+                out.append(line + "\n" + "\n".join(tail))
+            else:
+                out.append(line)
+
+        return out
+
+    def _render_duration_group(self, sections: list[Section]) -> list[str]:
+        """Render duration findings with aligned columns. Flat detector. Each
+        sub-field of the flow is padded independently so → arrows align
+        vertically. Columns: severity | src → dst:port/proto | max_dur_str |
+        avg_bps | N_conns | states."""
+        indent = "     "
+        out: list[str] = []
+        findings = sections[0].findings
+
+        rows = []
+        for f in findings:
+            ev    = f.evidence
+            src   = ev.get("src", "")
+            port  = ev.get("port")
+            proto = ev.get("proto", "")
+            port_str = str(port) if port is not None else "?"
+            dst_str  = f"{ev.get('dst', '')}:{port_str}/{proto}"
+            dur_str  = ev.get("max_duration_str", "")
+            bps      = ev.get("avg_bytes_per_second")
+            if bps is None:
+                bps_col = ""
+            elif bps >= 1_000_000:
+                bps_col = f"{bps / 1_000_000:.1f}mbps"
+            elif bps >= 1_000:
+                bps_col = f"{bps / 1_000:.1f}kbps"
+            else:
+                bps_col = f"{bps:.0f}bps"
+            count = ev.get("connection_count", 1)
+            conns_col = f"{count} conn" if count == 1 else f"{count} conns"
+            states = ev.get("conn_states", [])
+            state_col = ", ".join(states) if states else ""
+            rows.append((str(f.severity), src, dst_str, dur_str, bps_col, conns_col, state_col, f))
+
+        src_w    = max(len(r[1]) for r in rows)
+        dst_w    = max(len(r[2]) for r in rows)
+        dur_w    = max(len(r[3]) for r in rows)
+        bps_w    = max(len(r[4]) for r in rows)
+        conns_w  = max(len(r[5]) for r in rows)
+        state_w  = max(len(r[6]) for r in rows)
+
+        for tag, src, dst_str, dur_str, bps_col, conns_col, state_col, f in rows:
+            line = (
+                f"{tag}  {src:<{src_w}}  →  {dst_str:<{dst_w}}  "
+                f"{dur_str:<{dur_w}}  {bps_col:>{bps_w}}  {conns_col:>{conns_w}}  {state_col:>{state_w}}"
+            ).rstrip()
+            tail = _level_tail(f, indent, self._verbose_level)
+            if tail:
+                out.append(line + "\n" + "\n".join(tail))
+            else:
+                out.append(line)
+        return out
+
+    def _render_aws_group(self, sections: list[Section]) -> list[str]:
+        """Render AWS findings as subsections: burst sweeps, then ranked
+        principals. The ranked section already bundles per-principal
+        ``ranked`` rows + the synthetic ``ranked_summary`` quiet line (the
+        partitioner glued them together). Plain lowercase subsection labels
+        (no ── rules). Each tier computes its own column widths."""
+        indent = "     "
+        out: list[str] = []
+
+        for si, section in enumerate(sections):
+            label_line = f"{section.label} ({section.pre_cap_count})"
+            if si > 0:
+                out.append("")
+            out.append(label_line)
+
+            if section.label == "burst sweeps":
+                rows = []
+                for f in section.findings:
+                    ev = f.evidence
+                    tag = f"{str(f.severity):<4}"
+                    principal = str(ev.get("principal", ""))
+                    actions_col = f"{int(ev.get('new_action_count', 0))} new"
+                    svcs_col = f"{int(ev.get('new_service_count', 0))} svc"
+                    span_col = _aws_span_str(float(ev.get("span_seconds", 0.0)))
+                    err_col = f"err={float(ev.get('error_rate', 0.0)):.0%}"
+                    rows.append((tag, principal, actions_col, svcs_col, span_col, err_col, f))
+
+                principal_w = max(len(r[1]) for r in rows)
+                actions_w   = max(len(r[2]) for r in rows)
+                svcs_w      = max(len(r[3]) for r in rows)
+                span_w      = max(len(r[4]) for r in rows)
+                err_w       = max(len(r[5]) for r in rows)
+
+                for tag, principal, actions_col, svcs_col, span_col, err_col, f in rows:
+                    line = (
+                        f"  {tag}  {principal:<{principal_w}}  "
+                        f"{actions_col:>{actions_w}}  {svcs_col:>{svcs_w}}  "
+                        f"{span_col:>{span_w}}  {err_col:>{err_w}}"
+                    )
+                    tail = _level_tail(f, indent, self._verbose_level)
+                    if tail:
+                        out.append(line + "\n" + "\n".join(tail))
+                    else:
+                        out.append(line)
+            else:  # "ranked principals"
+                ranked = [f for f in section.findings if f.evidence.get("tier") == "ranked"]
+                summary = [f for f in section.findings if f.evidence.get("tier") == "ranked_summary"]
+
+                if ranked:
+                    rows = []
+                    for f in ranked:
+                        ev = f.evidence
+                        tag = f"{str(f.severity):<4}"
+                        principal = str(ev.get("principal", ""))
+                        z_col   = f"z={float(ev.get('composite_z', 0.0)):.2f}"
+                        err_col = f"err={float(ev.get('error_rate', 0.0)):.0%}"
+                        ev_col  = f"{int(ev.get('event_count', 0))} ev"
+                        ip_col  = f"{int(ev.get('distinct_source_ip', 0))} ip"
+                        rows.append((tag, principal, z_col, err_col, ev_col, ip_col, f))
+
+                    principal_w = max(len(r[1]) for r in rows)
+                    z_w   = max(len(r[2]) for r in rows)
+                    err_w = max(len(r[3]) for r in rows)
+                    ev_w  = max(len(r[4]) for r in rows)
+                    ip_w  = max(len(r[5]) for r in rows)
+
+                    for tag, principal, z_col, err_col, ev_col, ip_col, f in rows:
+                        line = (
+                            f"  {tag}  {principal:<{principal_w}}  "
+                            f"{z_col:>{z_w}}  {err_col:>{err_w}}  "
+                            f"{ev_col:>{ev_w}}  {ip_col:>{ip_w}}"
+                        )
+                        tail = _level_tail(f, indent, self._verbose_level)
+                        if tail:
+                            out.append(line + "\n" + "\n".join(tail))
+                        else:
+                            out.append(line)
+
+                for f in summary:
+                    ev = f.evidence
+                    tag = f"{str(f.severity):<4}"
+                    line = (
+                        f"  {tag}  {f.title}  "
+                        f"({int(ev.get('scorable_count', 0))} scored; "
+                        f"top {ev.get('top_principal', '')} "
+                        f"z={float(ev.get('top_composite_z', 0.0)):.2f})"
+                    )
+                    tail = _level_tail(f, indent, self._verbose_level)
+                    if tail:
+                        out.append(line + "\n" + "\n".join(tail))
+                    else:
+                        out.append(line)
+
+        return out
+
+    def _render_finding(self, finding: Finding) -> str:
+        tag = str(finding.severity)
+        line = f"{tag}  {finding.title}"
+
+        indent = "     "
+        tail = _level_tail(finding, indent, self._verbose_level)
+        if not tail:
+            return line
+        return line + "\n" + "\n".join(tail)
+
+    def render_digest(self, card: DigestCard) -> None:
+        """Render a digest schema card — flat, flush-left, no banner.
+
+        Order: 3-line identity block · ambient block · histogram · insights
+        · fields. Each block separated by one blank line. No header rule,
+        no N.B. footer, no trailing rule. The inter-card separator on a
+        multi-card run is emitted by the caller (run_digest) immediately
+        before invoking this method.
+
+        Called directly by ``runner.run_digest`` — bypassing the Finding-
+        shaped Reporter.begin/write/end lifecycle, because a digest run
+        produces ONE card. The Finding render path is intentionally
+        untouched.
+        """
+        # ── Identity block ────────────────────────────────────────────────
+        print(card.source_name, file=self._stream)
+        if card.data_window[0] and card.data_window[1]:
+            print(_fmt_window(card.data_window), file=self._stream)
+        else:
+            # Timeline unavailable: line 2 dashes; the histogram line
+            # below carries the descriptive "(timeline unavailable)".
+            print("—", file=self._stream)
+        print(
+            f"{card.schema} · {card.record_count:,} lines · "
+            f"{human_bytes(card.data_size_bytes)}",
+            file=self._stream,
+        )
+
+        # ── Ambient (former Zone 1) block ─────────────────────────────────
+        ambient = _render_label_value_block(card.zone1_extras)
+        if ambient:
+            print(file=self._stream)
+            for line in ambient:
+                print(line, file=self._stream)
+
+        # ── Histogram ─────────────────────────────────────────────────────
+        print(file=self._stream)
+        print(
+            _render_histogram(
+                card.histogram_counts,
+                card.histogram_unit,
+                card.histogram_peak,
+                unavailable=card.timeline_unavailable,
+            ),
+            file=self._stream,
+        )
+
+        # ── Insights ──────────────────────────────────────────────────────
+        if card.insights:
+            print(file=self._stream)
+            for insight in card.insights:
+                print(insight, file=self._stream)
+
+        # ── Fields (former Zone 3) block ──────────────────────────────────
+        field_rows = [
+            (slot.label, "  ".join(slot.cells))
+            for slot in card.fields
+            if slot.cells is not None
+        ]
+        field_lines = _render_label_value_block(field_rows)
+        if field_lines:
+            print(file=self._stream)
+            for line in field_lines:
+                print(line, file=self._stream)
+
+
+    def render_blob(self, card: BlobCard) -> None:
+        """Render a blob digest card — flat, flush-left, no banner.
+
+        Two-line identity block (blob has no window), labeled best-guess
+        headline, vanish-don't-dash slot list rendered through the shared
+        flat label/value helper. No footer, no inner separator, no
+        trailing rule. The inter-card separator on a multi-card run is
+        emitted by the caller (_render_blob_for_path) immediately before
+        invoking this method.
+        """
+        # ── Identity block (two lines — blob has no window) ───────────────
+        print(card.source_name, file=self._stream)
+        # Provenance line — blob's own; not the schema cards' rows/size line.
+        # Terminal-binary FIRST: a positive-magic ID has no line concept.
+        # For today's gzip-container path, file_type_guess is None —
+        # containers profile the content under decompression — so this
+        # ordering does not steal the compressed branch. The "binary,
+        # sampled from head" phrasing is card grammar, not a literal I/O
+        # trace: a large plain binary may have done seek reads before the
+        # terminal verdict held; the user-facing fact is "we ID'd it from
+        # the head and stopped looking for log content."
+        if card.file_type_guess is not None:
+            provenance = (
+                f"{human_bytes(card.byte_size)}  ·  binary, sampled from head"
+            )
+        elif card.is_compressed:
+            provenance = (
+                f"{human_bytes(card.byte_size)} compressed  ·  sampled from head"
+            )
+        else:
+            provenance = (
+                f"{human_bytes(card.byte_size)}  ·  "
+                f"sampled {card.sampled_line_count:,} lines across "
+                f"{card.sample_read_count} reads"
+            )
+        print(provenance, file=self._stream)
+        print(file=self._stream)
+
+        # ── Headline — labeled best-guess ─────────────────────────────────
+        if card.file_type_guess is not None:
+            headline = f"This looks like a {card.file_type_guess}, not a log."
+        else:
+            headline = (
+                f"Unrecognized source — but this looks like {card.shape_guess}."
+            )
+        print(headline, file=self._stream)
+        print(file=self._stream)
+
+        # ── Slot list (vanish-don't-dash) ─────────────────────────────────
+        slot_rows: list[tuple[str, str]] = []
+
+        # bytes: always present.
+        if card.file_type_guess is not None:
+            magic_repr = (
+                repr(card.file_type_magic)[2:-1]  # strip b'...' wrapper
+                if card.file_type_magic is not None else "?"
+            )
+            slot_rows.append((
+                "bytes",
+                f"binary ({card.printable_pct:.1f}% printable), "
+                f"magic {magic_repr}",
+            ))
+        else:
+            tail = ", UTF-8 clean" if card.utf8_clean else ""
+            slot_rows.append((
+                "bytes",
+                f"text ({card.printable_pct:.1f}% printable){tail}",
+            ))
+
+        # shape: text only.
+        if card.shape_guess is not None:
+            slot_rows.append(("shape", card.shape_guess))
+
+        # lines: text only; absent on binary terminal.
+        if card.mean_line_length is not None:
+            shape_tail = (
+                f", {card.line_length_shape}"
+                if card.line_length_shape else ""
+            )
+            slot_rows.append((
+                "lines",
+                f"mean {card.mean_line_length:.0f} chars, "
+                f"p95 {card.line_length_p95}, "
+                f"max {card.max_line_length}{shape_tail}",
+            ))
+
+        # fields: / tokens: — one or the other, never both. The summariser
+        # sets json_field_names on a JSON shape-guess (names-no-values),
+        # which the renderer prefers; otherwise the existing top-tokens
+        # row carries the literal-token spray. Vanish if neither populates.
+        wrap_label: str | None = None  # which label gets the two-line clamp
+        wrap_sep: str = ", "
+        if card.json_field_names:
+            slot_rows.append(("fields", ", ".join(card.json_field_names)))
+            wrap_label = "fields"
+            wrap_sep = ", "
+        elif card.top_tokens:
+            tokens_str = " ".join(f'"{tok}"' for tok, _ in card.top_tokens[:5])
+            slot_rows.append(("tokens", f"{tokens_str}  [literal]"))
+            wrap_label = "tokens"
+            wrap_sep = " "
+
+        # templates: text only; vanish on freeform floor / drain3 dormant.
+        if card.distinct_templates is not None:
+            slot_rows.append((
+                "templates",
+                f"~{card.distinct_templates} distinct structures over "
+                f"{card.sampled_line_count:,} sampled lines",
+            ))
+
+        # Render: single-line slots through the shared label/value shape
+        # (matching _render_label_value_block's sizing exactly so the two
+        # cannot drift); the wrap-label row through the blob-local
+        # _wrap_blob_slot_value clamp.
+        label_w = max(len(lbl) for lbl, _ in slot_rows)
+        label_col = label_w + 2
+        for lbl, val in slot_rows:
+            if lbl == wrap_label:
+                wrapped = _wrap_blob_slot_value(
+                    val, label_col=label_col, sep=wrap_sep,
+                )
+                print(
+                    f"{(lbl + ':').ljust(label_col)}{wrapped[0]}",
+                    file=self._stream,
+                )
+                for cont in wrapped[1:]:
+                    print(cont, file=self._stream)
+            else:
+                print(
+                    f"{(lbl + ':').ljust(label_col)}{val}",
+                    file=self._stream,
+                )
+
+
+register_handler("text", TextHandler)