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

loghunter/runner.py

@@ -0,0 +1,1895 @@
+"""Orchestrates detector execution: discovery, log loading, context assembly, and output.
+
+Responsibilities:
+- Auto-discover detectors by scanning loghunter/detectors/ for modules with DETECTOR_NAME
+- Resolve the detect= selection (all, explicit list, exclusion syntax)
+- Check REQUIRED_LOGS availability; skip with warning if missing
+- Load logs and assemble DetectorContext for each detector
+- Collect list[Finding] from each detector's run()
+- Hand findings to Reporter
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Sequence
+
+import pandas as pd
+
+import loghunter.detectors as _detectors_pkg
+from loghunter.common.config import get_detector_config, parse_window_span
+from loghunter.common.display import (
+    TEXT_RULE,
+    TEXT_RULE_DOUBLE,
+    TEXT_RULE_WIDTH,
+    liveness,
+)
+from loghunter.common.errors import DigestEmpty, ExportAborted
+from loghunter.common.finding import DetectorContext, Finding, RunSummary
+from loghunter.common.output import OutputHandler, Reporter
+from loghunter.common.sources import (
+    resolve_digest_source,
+    resolve_sources,
+)
+
+_WIDTH = TEXT_RULE_WIDTH
+_SEP = TEXT_RULE
+_SEP_DOUBLE = TEXT_RULE_DOUBLE
+
+# Full-fidelity DNS source labels. When any of these are in data_sources the
+# Zeek evangelization nudge is suppressed. BIND9 and others join this set when
+# their parsers land.
+_RICH_DNS_SOURCES = {"zeek_dns"}
+
+
+@dataclass(frozen=True)
+class RunPlan:
+    """Detector execution plan produced before loading any log data."""
+
+    detectors: dict[str, Any]
+    selected: list[str]
+    will_run: list[str]
+    skipped: dict[str, str]
+    needed_logs: dict[str, str]
+
+
+def run(
+    config: dict[str, Any],
+    detect: str | None = None,
+    zeek_dir: str | Path | Sequence[str | Path] | None = None,
+    syslog_dir: str | Path | Sequence[str | Path] | None = None,
+    pihole_dir: str | Path | Sequence[str | Path] | None = None,
+    cloudtrail_dir: str | Path | Sequence[str | Path] | None = None,
+    since: datetime | None = None,
+    until: datetime | None = None,
+    output_format: str = "text",
+    output_dir: Path | None = None,
+    verbose_level: int = 0,
+    dry_run: bool = False,
+    export_allowlist: bool = False,
+    load_all: bool = False,
+    skip_confirm: bool = False,
+    output_file: Path | None = None,
+    scope: frozenset[str] | None = None,
+) -> None:
+    """Main entry point for a detection run. Called by CLI dispatch functions.
+
+    Source-dir parameters (``zeek_dir`` / ``syslog_dir`` / ``pihole_dir`` /
+    ``cloudtrail_dir``) are EXPLICIT OVERRIDES accepting either a scalar
+    (``str`` / ``Path``) or a sequence of scalars (multi-positional analyze).
+    ``None`` means "no override." Scalar callers are degenerate one-element
+    lists downstream — byte-identical with the prior single-Path contract.
+    Resolution happens inside ``loghunter.common.sources.resolve_sources``
+    via the single ``_resolve_one`` site (per-element). CLI callers thread
+    raw parsed strings or per-family lists; programmatic callers can pass
+    already-resolved ``Path``s, lists thereof, or let ``None`` fall back to
+    ``config["loghunter"][key]`` (LH_ROOT applied).
+
+    ``scope`` is the SOLE scoping signal. ``None`` = unconstrained (every
+    configured source-dir is eligible). A ``frozenset`` of source-dir keys
+    restricts config-fallback to those keys — sibling source-dirs stay
+    ``None`` and are NOT loaded. An override outside ``scope`` still wins
+    (operator widening). The CLI sets ``scope`` from a positional PATH's
+    routed source; the previous ``None``-as-scoped-out wire shape is
+    retired.
+
+    ``skip_confirm`` bypasses the advisory large-dataset prompt (controlled by
+    ``[loghunter].warn_above``). Threaded from the CLI's ``--yes`` / ``-y`` flag.
+    Has no effect on safety-critical actions — there are none today; advisory
+    prompts only.
+
+    ``output_file`` is the be_like_water FILE verdict — an exact file path for
+    the report. When set it takes precedence over ``output_dir``; when both
+    are None, the runner streams to stdout (text/json/csv) or writes
+    ``loghunter-report.html`` in CWD (html). This preserves the bare-case
+    behavior exactly.
+    """
+    cfg_lh = config.get("loghunter", {})
+
+    # Single owner of source resolution: resolve_sources runs the four-key
+    # truth table (override / scope / config fallback) and is the SOLE site
+    # that converts a source-dir string to a Path. Runs BEFORE dry_run so
+    # _print_dry_run sees resolved dirs (provenance rail).
+    resolved = resolve_sources(
+        config,
+        overrides={
+            "zeek_dir": zeek_dir,
+            "syslog_dir": syslog_dir,
+            "pihole_dir": pihole_dir,
+            "cloudtrail_dir": cloudtrail_dir,
+        },
+        scope=scope,
+    )
+    zeek_dirs = resolved.zeek_dir
+    syslog_dirs = resolved.syslog_dir
+    pihole_dirs = resolved.pihole_dir
+    cloudtrail_dirs = resolved.cloudtrail_dir
+
+    plan = build_run_plan(
+        detect_spec=detect if detect is not None else cfg_lh.get("detect", "all"),
+        zeek_dir=zeek_dirs,
+        syslog_dir=syslog_dirs,
+        pihole_dir=pihole_dirs,
+        cloudtrail_dir=cloudtrail_dirs,
+    )
+
+    if dry_run:
+        _print_dry_run(
+            zeek_dir=zeek_dirs,
+            syslog_dir=syslog_dirs,
+            pihole_dir=pihole_dirs,
+            cloudtrail_dir=cloudtrail_dirs,
+            since=since,
+            until=until,
+            load_all=load_all,
+            will_run=plan.will_run,
+            skipped=plan.skipped,
+        )
+        return
+
+    if export_allowlist:
+        raise ValueError(
+            "--export-allowlist is not yet implemented — planned for a future release"
+        )
+
+    # Emit per-detector skip warnings to stderr
+    for name, reason in plan.skipped.items():
+        _warn_skipped(name, reason)
+
+    if not plan.will_run:
+        print(
+            "No detectors could run — check required log source paths in config "
+            "or CLI overrides.",
+            file=sys.stderr,
+        )
+        return
+
+    # ── Load logs ─────────────────────────────────────────────────────────────
+    from loghunter.common import loader
+    from loghunter.common.allowlist import build_matcher
+
+    source_dirs: dict[str, list[Path]] = {}
+    if zeek_dirs:
+        source_dirs["zeek_dir"] = zeek_dirs
+    if syslog_dirs:
+        source_dirs["syslog_dir"] = syslog_dirs
+    if pihole_dirs:
+        source_dirs["pihole_dir"] = pihole_dirs
+    if cloudtrail_dirs:
+        source_dirs["cloudtrail_dir"] = cloudtrail_dirs
+
+    # Resolve the UNIVERSAL default window. default_window governs every source
+    # family (no longer Zeek-only): each family anchors on its OWN max-ts, with the
+    # per-family load/trim strategy encoded in a single LoadWindow per family. The
+    # loader owns the window policy now — resolve_load_windows is the SINGLE entry
+    # point (shared with run_digest); each family's strategy declares its own
+    # resolver. Engages only on an unqualified, non---all, unbounded, in-plan,
+    # configured, eligible family.
+    _default_spec: str = cfg_lh.get("default_window", "1d")
+    load_windows = loader.resolve_load_windows(
+        plan.needed_logs, source_dirs, _default_spec,
+        load_all=load_all, since=since, until=until,
+    )
+    default_window_active = bool(load_windows)
+    # source_windows: precise dated-Zeek window or conservative flat (floor, None);
+    # families with select_window=None load full and are trimmed post-load.
+    source_windows = (
+        {w.source: w.select_window for w in load_windows if w.select_window is not None}
+        or None
+    )
+
+    if default_window_active:
+        # PLACEHOLDER VOICE (flag for the qmail error-voice pass). One pre-load
+        # line above the loader's `loaded <file>` progress lines.
+        print(
+            f"Default window: last {_default_spec} of available data. "
+            "Use --all for the full archive, or --since/--days to widen.",
+            file=sys.stderr,
+        )
+
+    load_result = loader.load_required_logs(
+        plan.needed_logs,
+        source_dirs,
+        since,
+        until,
+        verbose=(verbose_level >= 1),
+        source_windows=source_windows,
+    )
+
+    # Post-load precise trim for every family whose default window engaged with a
+    # load-full / conservative select-window (flat peek-prune, cloudtrail
+    # load-full, flat/mixed Zeek). Dated-Zeek families carry trim_span=None — their
+    # select_window already cut exactly at load. keep_null is wired from the
+    # source's loader policy, so keep-policy families (syslog/pihole) retain
+    # unparseable-ts rows through the implicit window exactly as through an
+    # explicit one. Mixed file+dir trims the named file's rows WITH the bucket.
+    for w in load_windows:
+        if w.trim_span is None:
+            continue
+        family_patterns = [
+            p for p, src in plan.needed_logs.items() if src == w.source
+        ]
+        load_result = loader.apply_default_window(
+            load_result, family_patterns, w.trim_span, keep_null=w.keep_null,
+        )
+    logs = load_result.logs
+
+    for warning in load_result.warnings:
+        print(f"Warning: {warning}", file=sys.stderr)
+
+    # ONE captured `now` for both the data-window fallback and requested_span,
+    # so they cannot drift across separate clock reads.
+    now = datetime.now(timezone.utc)
+    if load_result.data_window is not None:
+        data_window = load_result.data_window
+    elif since or until:
+        data_window = (since or now, until or now)
+    else:
+        data_window = (now, now)
+
+    # The window the operator asked for, used by the data-found underfill
+    # parenthetical. Default-window active → the configured spec; explicit
+    # since&until → their span; since only → since→now; until-only / --all /
+    # bounded full-load → None (unconstrained).
+    requested_span: timedelta | None
+    if default_window_active:
+        requested_span = parse_window_span(_default_spec)
+    elif since is not None and until is not None:
+        requested_span = until - since
+    elif since is not None:
+        requested_span = now - since
+    else:
+        requested_span = None
+    # No real data window (load yielded nothing the renderer can place — e.g. all
+    # rows unparseable-ts under keep policy) → run() fabricated a (now, now) window.
+    # Force requested_span None so the underfill parenthetical cannot render a
+    # confident comparison over data that does not exist. The legitimate single-event
+    # case keeps a real (ts, ts) data_window and is unaffected.
+    if load_result.data_window is None:
+        requested_span = None
+
+    # Large-dataset warning. Suppressed when skip_confirm is set (--yes / -y).
+    total_records = sum(load_result.record_counts.values())
+    warn_above: int = cfg_lh.get("warn_above", 5_000_000)
+    if total_records > warn_above and not skip_confirm:
+        try:
+            answer = input(
+                f"{total_records:,} records found. This may take a while. Continue? [y/N] "
+            )
+        except (EOFError, KeyboardInterrupt):
+            answer = ""
+        if answer.strip().lower() not in ("y", "yes"):
+            raise ExportAborted("loghunter: aborted by user")
+
+    # Build run summary and begin output before the detector loop so the banner
+    # ("Data found:", "Records:", "Detectors:") appears before analysis starts.
+    data_sources = _derive_data_sources(plan.needed_logs, load_result.record_counts)
+    # The default window is now announced pre-load on stderr (and the data-found
+    # parenthetical carries the data-vs-requested span), so no prose default-window
+    # note rides the run summary. The old "only X hours" short-window note is gone.
+    notes: list[str] = []
+    nudge = _dns_nudge(data_sources)
+    if nudge:
+        notes.append(nudge)
+    aws_below_note = _aws_below_floor_note(plan, logs, config)
+    if aws_below_note:
+        notes.append(aws_below_note)
+    # The aws --all riders key on CloudTrail ACTUALLY being narrowed (an explicit
+    # window) — NOT run-level default-window activity. CloudTrail opts out of the
+    # auto-default window, so a mixed unqualified run (dns/syslog windowed) loads
+    # it FULL and must not be told to widen.
+    cloudtrail_narrowed = since is not None or until is not None
+    aws_window_note = _aws_window_note(plan, cloudtrail_narrowed=cloudtrail_narrowed)
+    if aws_window_note:
+        notes.append(aws_window_note)
+    aws_no_interactive_note = _aws_no_interactive_note(
+        plan, logs, cloudtrail_narrowed=cloudtrail_narrowed
+    )
+    if aws_no_interactive_note:
+        notes.append(aws_no_interactive_note)
+    home_net_note = _home_net_note(plan, config)
+    if home_net_note:
+        notes.append(home_net_note)
+    # Source-dir overlap disclosure: when two IN-PLAN families resolve to the
+    # same directory, flat discovery globs cross-read it (one log surfaced as
+    # another's finding). Derives from already-resolved source_dirs + plan, like
+    # the home_net note above. Appended before the coverage/rotation extends,
+    # which are deliberately last.
+    notes.extend(_source_overlap_notes(source_dirs, plan))
+    # Source-coverage disclosure: for each planned source that contributed 0
+    # in-window rows, append a note (SPAN / BARE / silent per the parse-gap
+    # vs window-gap tri-state in CoverageTracker). Appended LAST so the
+    # existing notes' relative order is preserved and the disclosure is
+    # additive only. Reads the merged coverage written by the runner-side
+    # flat-default block above (when fired).
+    notes.extend(_zero_window_coverage_notes(load_result, plan))
+    # Flat rotation-peek disclosure: one note per windowed pattern that fell back
+    # to a full read or skipped out-of-window rotation files. Additive, appended last.
+    notes.extend(_rotation_skip_notes(load_result, plan))
+    detector_methods = {
+        name: getattr(plan.detectors[name], "DETECTOR_METHOD", None)
+        for name in plan.will_run
+    }
+    run_summary = RunSummary(
+        data_window=data_window,
+        record_counts=load_result.record_counts,
+        data_size_bytes=load_result.data_size_bytes,
+        detectors_run=plan.will_run,
+        detectors_skipped=plan.skipped,
+        notes=notes,
+        data_sources=data_sources,
+        detector_methods=detector_methods,
+        requested_span=requested_span,
+    )
+
+    max_per_detector = int(
+        config.get("loghunter", {}).get("max_findings_per_detector", 100)
+    )
+    handler, close_handler = _build_output_handler(
+        output_format, output_dir, output_file, verbose_level,
+        max_findings_per_detector=max_per_detector,
+    )
+    reporter = Reporter([handler])
+    reporter.begin(run_summary)
+
+    # ── Run detectors ─────────────────────────────────────────────────────────
+    allowlist = build_matcher(config)
+    home_net = list(config.get("loghunter", {}).get("home_net", []))
+    all_findings: list[Finding] = []
+
+    for name in plan.will_run:
+        mod = plan.detectors[name]
+        det_cfg = get_detector_config(config, name, getattr(mod, "DEFAULT_CONFIG", {}))
+
+        # Per-detector prep + run, scoped to honest error labels. Prep
+        # (filter_df + DetectorContext construction) is the runner's
+        # responsibility; a prep failure is "prep error", NOT "detector
+        # error" — separation-of-powers detail. For the non-syslog
+        # branch, both prep and run live INSIDE liveness(...) so the
+        # spinner appears as soon as the operator-visible work begins
+        # (the "Detector liveness starts too late" bug — see docs/BUGS.md
+        # — was the prep running silently before the liveness block
+        # opened).
+        #
+        # syslog stays outside the outer spinner branch: its inner
+        # drain3 tqdm bar owns its stderr line, and an outer spinner
+        # would fight for the same row. Prep moves into the syslog
+        # branch too for consistency but stays outside its own
+        # liveness wrapper.
+        if name == "syslog":
+            try:
+                ctx = _prepare_detector_context(
+                    mod, name, logs, allowlist, det_cfg,
+                    data_window, data_sources, home_net,
+                )
+            except Exception as exc:
+                print(f"{name}: prep error — {exc}", file=sys.stderr)
+                continue
+            try:
+                findings = mod.run(ctx)
+            except Exception as exc:
+                print(f"{name}: detector error — {exc}", file=sys.stderr)
+                findings = []
+        else:
+            with liveness(f"running {name}") as _ln:
+                try:
+                    ctx = _prepare_detector_context(
+                        mod, name, logs, allowlist, det_cfg,
+                        data_window, data_sources, home_net,
+                    )
+                except Exception as exc:
+                    # Prep failed BEFORE the detector even started — no
+                    # seal (the "no false seal" path from
+                    # tests/test_display.py:120-130); liveness's normal
+                    # teardown clears the spinner line.
+                    print(f"{name}: prep error — {exc}", file=sys.stderr)
+                    continue
+                try:
+                    findings = mod.run(ctx)
+                    # The seal is a terse live completion record — "this
+                    # detector finished" — NOT a tally. The report header
+                    # (W2) is the single authoritative count surface
+                    # (carries the H/M/L/I breakdown, survives redirect).
+                    # Empty case stays informative: the detector ran and
+                    # found nothing. ASCII-only per display.py's spinner
+                    # discipline. Wording is a PLACEHOLDER pending the
+                    # error-voice pass.
+                    _ln.seal(
+                        f"{name}: done"
+                        if findings
+                        else f"{name}: nothing"
+                    )
+                except Exception as exc:
+                    print(f"{name}: detector error — {exc}", file=sys.stderr)
+                    findings = []
+
+        all_findings.extend(findings)
+
+    try:
+        reporter.write(all_findings)
+        reporter.end()
+    finally:
+        close_handler()
+
+
+def _prepare_detector_context(
+    mod: Any,
+    name: str,
+    logs: dict[str, Any],
+    allowlist: Any,
+    det_cfg: dict[str, Any],
+    data_window: tuple[datetime, datetime],
+    data_sources: list[str],
+    home_net: list[str],
+) -> DetectorContext:
+    """Build the per-detector filtered view + DetectorContext.
+
+    Pure extraction of the previously inline prep at the detector loop:
+    each detector gets its own filtered copy of the shared log frames
+    (so independent ``filter_df`` results never mutate the shared dict),
+    keyed by the patterns the detector itself declares via
+    ``REQUIRED_LOGS`` + ``OPTIONAL_LOGS``.
+
+    Lives in the runner — NOT moved into detector code — because
+    ``allowlist.filter_df`` is suppression, and suppression stays in the
+    runner per the filter-before-analyze rail (CODE.md "Allowlist
+    Architecture").
+
+    Verbose is intentionally absent (W6): detector context carries no
+    verbosity; the result set is verbosity-invariant by construction.
+    """
+    det_patterns = {
+        req["pattern"]
+        for req in list(getattr(mod, "REQUIRED_LOGS", []))
+        + list(getattr(mod, "OPTIONAL_LOGS", []))
+    }
+    filtered_logs: dict[str, Any] = {}
+    for pattern, df in logs.items():
+        if pattern in det_patterns and not df.empty:
+            filtered_logs[pattern] = allowlist.filter_df(df, name)
+        else:
+            filtered_logs[pattern] = df
+    return DetectorContext(
+        logs=filtered_logs,
+        config=det_cfg,
+        allowlist=allowlist,
+        data_window=data_window,
+        data_sources=data_sources,
+        home_net=home_net,
+    )
+
+
+def discover_detectors() -> dict[str, Any]:
+    """Scan loghunter/detectors/ and return available detector modules by name."""
+    detectors: dict[str, Any] = {}
+    for _finder, name, _ispkg in pkgutil.iter_modules(_detectors_pkg.__path__):
+        try:
+            mod = importlib.import_module(f"loghunter.detectors.{name}")
+        except ImportError:
+            continue
+        if hasattr(mod, "DETECTOR_NAME") and getattr(mod, "STATUS", "available") == "available":
+            detectors[mod.DETECTOR_NAME] = mod
+    return detectors
+
+
+def _as_path_list(value: Path | list[Path] | None) -> list[Path]:
+    """Normalize a build_run_plan / _print_dry_run source-dir param.
+
+    Accepts None (absent), a scalar Path (degenerate one-element list), or a
+    list of Paths (the canonical multi-input shape). Returns a list — empty
+    means absent. Lets callers and tests pass either form without juggling
+    the boundary; the internal pipeline operates on lists only. SAME
+    normalization shape as ``runner.run`` accepting ``str | Path | Sequence
+    | None`` at its outer boundary, propagated inward.
+    """
+    if value is None:
+        return []
+    if isinstance(value, Path):
+        return [value]
+    return list(value)
+
+
+def build_run_plan(
+    detect_spec: str | None,
+    zeek_dir: Path | list[Path] | None = None,
+    syslog_dir: Path | list[Path] | None = None,
+    pihole_dir: Path | list[Path] | None = None,
+    cloudtrail_dir: Path | list[Path] | None = None,
+    detectors: dict[str, Any] | None = None,
+) -> RunPlan:
+    """Resolve detector selection, required-log skips, and log patterns to load.
+
+    Each source-dir parameter accepts ``None`` (absent), a scalar ``Path``
+    (degenerate one-element list), or a list of ``Path``s (the canonical
+    multi-input shape from the resolver). Plan-time satisfiability uses the
+    SAME discovery helpers the loader uses (``discover_zeek_files``,
+    ``discover_cloudtrail_files``, ``_syslog_files``); plan and loader MUST
+    discover the same universe.
+    """
+    all_detectors = detectors or discover_detectors()
+    selected = resolve_detect(str(detect_spec or "all"), sorted(all_detectors.keys()))
+
+    source_map: dict[str, list[Path]] = {}
+    zeek_paths = _as_path_list(zeek_dir)
+    syslog_paths = _as_path_list(syslog_dir)
+    pihole_paths = _as_path_list(pihole_dir)
+    cloudtrail_paths = _as_path_list(cloudtrail_dir)
+    if zeek_paths:
+        source_map["zeek_dir"] = zeek_paths
+    if syslog_paths:
+        source_map["syslog_dir"] = syslog_paths
+    if pihole_paths:
+        source_map["pihole_dir"] = pihole_paths
+    if cloudtrail_paths:
+        source_map["cloudtrail_dir"] = cloudtrail_paths
+
+    will_run: list[str] = []
+    skipped: dict[str, str] = {}
+    for name in selected:
+        reason = _check_required_logs(all_detectors[name], source_map)
+        if reason:
+            skipped[name] = reason
+        else:
+            will_run.append(name)
+
+    # Only include OPTIONAL_LOGS patterns that are actually satisfiable, to avoid
+    # loading empty frames for optional sources that happen to be configured but have
+    # no matching files (e.g. zeek_dir present but no dns*.log* when pihole satisfied).
+    needed_logs: dict[str, str] = {}
+    for name in will_run:
+        mod = all_detectors[name]
+        for req in getattr(mod, "REQUIRED_LOGS", []):
+            if req["pattern"] not in needed_logs:
+                needed_logs[req["pattern"]] = req["source"]
+        for req in getattr(mod, "OPTIONAL_LOGS", []):
+            if _is_optional_satisfiable(req, source_map) and req["pattern"] not in needed_logs:
+                needed_logs[req["pattern"]] = req["source"]
+
+    return RunPlan(
+        detectors=all_detectors,
+        selected=selected,
+        will_run=will_run,
+        skipped=skipped,
+        needed_logs=needed_logs,
+    )
+
+
+def _build_output_handler(
+    output_format: str,
+    output_dir: Path | None,
+    output_file: Path | None,
+    verbose_level: int,
+    stream: Any = None,
+    *,
+    max_findings_per_detector: int = 100,
+) -> tuple[OutputHandler, Any]:
+    """Create the requested output handler and a callback that closes any file stream.
+
+    ``output_file`` is the be_like_water FILE verdict — an exact file path.
+    When set it takes precedence over ``output_dir`` (which is the DIRECTORY
+    verdict; runner auto-names inside it). With both None, text/json/csv stream
+    to stdout and html writes ``loghunter-report.html`` in CWD.
+
+    ``stream`` is the caller-owned TextIO seam used by the digest fan-out: the
+    CLI resolves a shared `--out` target once and passes the open stream here
+    so N cards concatenate into one file. Stream-backed formats only (text
+    today); HTML/CSV/etc. carry different writer shapes and are not routed
+    through this seam. Caller owns stream lifetime; close callback is a no-op.
+
+    ``verbose_level`` is the single 0/1/2 dial. ONLY the text handler distinguishes
+    all three levels; json is invariant; csv/html collapse to level >= 1 for
+    description gating. ``max_findings_per_detector`` is the W5 cap (text only;
+    machine formats never truncate). Constructed format-branched so json/csv/html
+    receive only the cap-agnostic signature.
+    """
+    from loghunter.common.output import get_handler
+
+    handler_cls = get_handler(output_format)
+
+    def _build(target_stream=None, output_path=None):
+        if output_format == "text":
+            if output_path is not None:
+                # HTML uses output_path; text never does — this branch unreachable
+                # for text but kept for symmetry.
+                raise RuntimeError("text handler does not accept output_path")
+            return handler_cls(
+                stream=target_stream,
+                verbose_level=verbose_level,
+                max_findings_per_detector=max_findings_per_detector,
+            )
+        if output_format == "html":
+            return handler_cls(output_path=output_path, verbose_level=verbose_level)
+        return handler_cls(stream=target_stream, verbose_level=verbose_level)
+
+    if stream is not None:
+        # Caller owns the stream; don't open, don't close. output_dir and
+        # output_file are expected to be None at this seam (digest fan-out
+        # resolves the target once in the CLI). Text format only.
+        return _build(target_stream=stream), lambda: None
+
+    # output_file (FILE verdict) wins — caller has decided the exact path.
+    if output_file is not None:
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        if output_format == "html":
+            return _build(output_path=output_file), lambda: None
+        opened = output_file.open("w", encoding="utf-8", newline="")
+        return _build(target_stream=opened), opened.close
+
+    if output_format == "html":
+        if output_dir is None:
+            output_path = Path("loghunter-report.html")
+        else:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            output_path = output_dir / _report_filename(output_format)
+        return _build(output_path=output_path), lambda: None
+
+    target = sys.stdout
+    close_handler = lambda: None
+    if output_dir is not None:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        target = (output_dir / _report_filename(output_format)).open("w", encoding="utf-8", newline="")
+        close_handler = target.close
+
+    return _build(target_stream=target), close_handler
+
+
+def _report_filename(output_format: str) -> str:
+    """Return a timestamped report filename used when --out (or report_dir) resolves to a directory."""
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    suffix = "html" if output_format == "html" else output_format
+    return f"loghunter-{stamp}.{suffix}"
+
+
+def resolve_detect(spec: str, available: list[str]) -> list[str]:
+    """Resolve a detect= spec (all, list, exclusions) against available detector names.
+
+    Examples:
+      "all"              → all available names (sorted)
+      "dns, beacon"      → ["dns", "beacon"]
+      "all, !syslog"     → all except "syslog"
+      "all,!syslog,!ssl" → all except syslog and ssl
+    """
+    # Tokenise: split on commas and whitespace, handle "all, !syslog" etc.
+    tokens = [t.strip() for t in spec.replace(",", " ").split() if t.strip()]
+
+    inclusions: list[str] = []
+    exclusions: set[str] = set()
+
+    for token in tokens:
+        if token.startswith("!"):
+            exclusions.add(token[1:])
+        elif token == "all":
+            inclusions = list(available)  # replace with all available
+        elif token in available:
+            inclusions.append(token)
+        # unknown detector names in spec are silently ignored
+
+    # Deduplicate while preserving order, then apply exclusions
+    seen: set[str] = set()
+    result: list[str] = []
+    for name in inclusions:
+        if name not in seen and name not in exclusions:
+            seen.add(name)
+            result.append(name)
+
+    return result
+
+
+def _any_input_yields_files(
+    source: str, paths: list[Path], pattern: str,
+) -> bool:
+    """Plan-time discovery lockstep with the LOADER for one family.
+
+    Per-family mapping (matches ``load_required_logs``):
+
+    - ``zeek_dir``      → ``discover_zeek_files(input, pattern)`` per input
+    - ``cloudtrail_dir``→ ``discover_cloudtrail_files(input)`` per input
+    - ``syslog_dir``    → ``_discover_syslog_files(input)`` per input — the LOADER
+      content-sniffs syslog DIRECTORY candidates (RHEL/Fedora streams carry no
+      ``.log`` suffix; ``dnf.log`` etc. would be mis-claimed by a filename glob),
+      so plan-time MUST too (one-universe rail). A ``/var/log`` holding only
+      ``dnf.log`` reports syslog NOT satisfiable → the detector skips with its
+      actionable "not found" message instead of garbage.
+    - ``pihole_dir``    → ``_syslog_files(input, pattern)`` per input — the LOADER
+      threads the detector's pattern (``pihole*.log*``) into ``_syslog_files``
+      for DIRECTORY discovery, so plan-time MUST too. An explicit FILE still
+      routes as ``[path]`` regardless of pattern, so a content-routed Pi-hole
+      input named e.g. ``events.log`` is NOT plan-rejected.
+
+    Returns True iff ANY input yields at least one file.
+    """
+    from loghunter.common.loader import (
+        _discover_syslog_files,
+        _syslog_files,
+        discover_cloudtrail_files,
+        discover_zeek_files,
+    )
+    for p in paths:
+        if not p.exists():
+            continue
+        if source == "zeek_dir":
+            if discover_zeek_files(p, pattern):
+                return True
+        elif source == "cloudtrail_dir":
+            if discover_cloudtrail_files(p):
+                return True
+        elif source == "syslog_dir":
+            if _discover_syslog_files(p):
+                return True
+        elif source == "pihole_dir":
+            if _syslog_files(p, pattern):
+                return True
+        else:
+            # Defensive: unknown source key. Fall back to plain glob over
+            # directories so an unrecognized future family doesn't silently
+            # plan-skip. The loader will raise the actionable error.
+            if p.is_file():
+                return True
+            if list(p.glob(pattern)):
+                return True
+    return False
+
+
+def _is_optional_satisfiable(
+    req: dict[str, str],
+    source_map: dict[str, Path | list[Path]],
+) -> bool:
+    """Return True if an OPTIONAL_LOGS entry has files available to load."""
+    source = req["source"]
+    paths = _as_path_list(source_map.get(source))
+    if not paths:
+        return False
+    return _any_input_yields_files(source, paths, req["pattern"])
+
+
+def _check_required_logs(
+    detector_module: Any,
+    source_map: dict[str, Path | list[Path]],
+) -> str | None:
+    """Return None if all REQUIRED_LOGS are available, or a human-readable reason if not."""
+    for req in getattr(detector_module, "REQUIRED_LOGS", []):
+        source = req["source"]
+        pattern = req["pattern"]
+
+        paths = _as_path_list(source_map.get(source))
+        if not paths:
+            return f"{source} not configured"
+
+        # Existence skip-reason mirrors single-input behavior on a one-element
+        # list: report the missing path. With multiple inputs, satisfiability
+        # is "ANY input yields files" — _any_input_yields_files handles
+        # per-input existence checks (skips non-existent), so we only emit a
+        # not-found skip when NO input yields anything.
+        if not _any_input_yields_files(source, paths, pattern):
+            if len(paths) == 1:
+                p = paths[0]
+                if not p.exists():
+                    return f"{source} {p} not found"
+                if source == "cloudtrail_dir":
+                    # Preserve the family-specific wording for the no-events
+                    # skip path — recursive AWSLogs/<acct>/CloudTrail/<region>/
+                    # discovery means a plain "pattern not found" reads
+                    # confusingly.
+                    return f"no CloudTrail JSON logs found in {p}"
+                return f"{pattern} not found in {p}"
+            # Multi-input — name the family rather than a single path.
+            return f"{pattern} not found in any configured {source} input"
+
+    if getattr(detector_module, "REQUIRES_ONE_OF_OPTIONAL", False):
+        for opt in getattr(detector_module, "OPTIONAL_LOGS", []):
+            if _is_optional_satisfiable(opt, source_map):
+                return None
+        return getattr(
+            detector_module,
+            "REQUIRES_ONE_OF_OPTIONAL_REASON",
+            f"{getattr(detector_module, 'DETECTOR_NAME', 'detector')} — no source available",
+        )
+
+    return None
+
+
+def _warn_skipped(detector_name: str, reason: str) -> None:
+    """Print a skip warning to stderr in the canonical format."""
+    print(f"{reason} — skipping {detector_name} detection", file=sys.stderr)
+
+
+def _zeek_entry_display(p: Path) -> str:
+    """Render one zeek_dir input for the dry-run block.
+
+    Mirrors the single-input format that has shipped: a DIRECTORY shows
+    ``{path}  (N files, X.X MB)`` (counting only its immediate file children
+    — same iteration the prior helper did, NOT recursive); a FILE shows
+    ``{path}  (X.X MB)``; a non-existent path shows ``{path}  — not found``.
+    Single-input dry-run is byte-identical with the prior format.
+    """
+    if not p.exists():
+        return f"{p}  — not found"
+    if p.is_dir():
+        log_files = [f for f in p.iterdir() if f.is_file()]
+        size_mb = sum(f.stat().st_size for f in log_files) / 1_048_576
+        return f"{p}  ({len(log_files)} files, {size_mb:.1f} MB)"
+    try:
+        size_mb = p.stat().st_size / 1_048_576
+        return f"{p}  ({size_mb:.1f} MB)"
+    except OSError:
+        return f"{p}"
+
+
+def _status_entry_display(p: Path) -> str:
+    """Render one syslog/pihole/cloudtrail input for the dry-run block."""
+    status = "found" if p.exists() else "not found"
+    return f"{p}  ({status})"
+
+
+def _print_family_block(label: str, paths: list[Path], formatter) -> None:
+    """Render one source-family block in the dry-run output.
+
+    Empty list  → ``{label:>15}  not configured`` (byte-identical with prior
+    single-Path-None case).
+    One input   → ``{label:>15}  {formatter(input)}`` (byte-identical with
+    the prior single-input format — Glenn's preserve-byte-identical rail).
+    Multi-input → the first entry rides the label line, subsequent entries
+    indent under it at the same value column (17 chars: 15-char right-
+    justified label + 2-space gutter). NEVER emits a Python list repr.
+    """
+    head = f"{label + ':':>15}"
+    indent = " " * 15  # matches the right-justified label width
+    if not paths:
+        print(f"{head}  not configured")
+        return
+    entries = [formatter(p) for p in paths]
+    print(f"{head}  {entries[0]}")
+    for e in entries[1:]:
+        print(f"{indent}  {e}")
+
+
+def _print_dry_run(
+    zeek_dir: Path | list[Path] | None,
+    syslog_dir: Path | list[Path] | None,
+    pihole_dir: Path | list[Path] | None,
+    cloudtrail_dir: Path | list[Path] | None,
+    since: datetime | None,
+    until: datetime | None,
+    load_all: bool,
+    will_run: list[str],
+    skipped: dict[str, str],
+) -> None:
+    print("LogHunter  ·  Threat Hunt  [dry run]")
+    print(_SEP_DOUBLE)
+
+    # Right-justified 15-char label field (width of the widest label,
+    # "cloudtrail_dir:") plus a two-space gutter. Colons AND value starts align
+    # in a single clean column for all four source-dir lines. Multi-input
+    # buckets stack additional entries under the label's value column.
+    # Boundary accepts scalar Path / list / None — same normalization shape
+    # as build_run_plan, so test callers passing scalar Path or None work
+    # without juggling the wire shape.
+    _print_family_block("zeek_dir", _as_path_list(zeek_dir), _zeek_entry_display)
+    _print_family_block("syslog_dir", _as_path_list(syslog_dir), _status_entry_display)
+    _print_family_block("pihole_dir", _as_path_list(pihole_dir), _status_entry_display)
+    _print_family_block(
+        "cloudtrail_dir", _as_path_list(cloudtrail_dir), _status_entry_display,
+    )
+
+    if load_all:
+        print("Window:        all available data (--all)")
+    elif since or until:
+        since_str = since.strftime("%Y-%m-%d %H:%M UTC") if since else "beginning of data"
+        until_str = until.strftime("%Y-%m-%d %H:%M UTC") if until else "end of data"
+        print(f"Window:        {since_str}  →  {until_str}")
+    else:
+        print("Window:        all available data")
+
+    if will_run:
+        print(f"Detectors:     {'  '.join(will_run)}")
+    else:
+        print("Detectors:     (none — required logs unavailable)")
+
+    # Group detectors by skip reason for compact display
+    by_reason: dict[str, list[str]] = {}
+    for name, reason in skipped.items():
+        by_reason.setdefault(reason, []).append(name)
+
+    for reason, names in by_reason.items():
+        print(f"Skipped:       {', '.join(names)} — {reason}")
+
+    print(_SEP_DOUBLE)
+    print("Dry run complete. Remove --dry-run to analyze.")
+
+
+def _derive_data_sources(
+    needed_logs: dict[str, str],
+    record_counts: dict[str, int],
+) -> list[str]:
+    """Return sorted data_source labels for patterns that produced non-empty data."""
+    from loghunter.common.loader import _log_type
+
+    labels: set[str] = set()
+    for pattern, count in record_counts.items():
+        if count <= 0:
+            continue
+        source = needed_logs.get(pattern)
+        if source is None:
+            continue
+        if source == "zeek_dir":
+            lt = _log_type(pattern)
+            if lt is not None:
+                labels.add(f"zeek_{lt}")
+        elif source == "syslog_dir":
+            labels.add("syslog_raw")
+        elif source == "pihole_dir":
+            labels.add("dnsmasq_dns")
+        elif source == "cloudtrail_dir":
+            labels.add("cloudtrail_raw")
+    return sorted(labels)
+
+
+def _pattern_human_label(source_key: str, pattern: str) -> str:
+    """Operator-language label for one (source_key, pattern) tuple.
+
+    USED BY: the source-coverage disclosure note (``_zero_window_coverage_notes``).
+    DISTINCT FROM: ``_derive_data_sources``, which emits internal
+    ``data_sources`` tokens (``"zeek_dns"`` / ``"dnsmasq_dns"`` / ``"syslog_raw"``
+    / ``"cloudtrail_raw"``) consumed by the Zeek-evangelization nudge matcher and
+    other internal channels — those token strings stay byte-identical there.
+
+    Labels: ``Pi-hole`` / ``syslog`` / ``CloudTrail`` / ``Zeek <log_type>``.
+    """
+    from loghunter.common.loader import _log_type
+
+    if source_key == "pihole_dir":
+        return "Pi-hole"
+    if source_key == "syslog_dir":
+        return "syslog"
+    if source_key == "cloudtrail_dir":
+        return "CloudTrail"
+    if source_key == "zeek_dir":
+        lt = _log_type(pattern)
+        return f"Zeek {lt}" if lt is not None else "Zeek"
+    return source_key
+
+
+def _zero_window_coverage_notes(
+    load_result: "loader.LoadResult",
+    plan: RunPlan,
+) -> list[str]:
+    """Return disclosure notes for planned sources that contributed 0 in-window rows.
+
+    Honesty rail — coverage counts VALID-ts rows only:
+      - ``full_rows > 0`` → SPAN note (count + span + widen suggestion), or
+        count-only when no valid span survived (degenerate; defensive).
+      - ``full_rows is None`` and ``source_key == "zeek_dir"`` → BARE note
+        ("files found, 0 records …"). The BARE arm is **zeek_dir-only**: for
+        syslog/pihole/cloudtrail, "no files read" means a wrong-family skip
+        or an empty directory — neither is a window gap the operator can fix
+        with ``--since/--days``, and the existing per-source warnings already
+        cover it.
+      - ``full_rows == 0`` → NO note (parse gap; widen advice would mislead).
+      - Pattern not loaded at all (source unconfigured) → NO note (the
+        loader already warns ``"{source} not configured — {pattern} not loaded"``).
+    """
+    out: list[str] = []
+    for pattern, source_key in plan.needed_logs.items():
+        if load_result.record_counts.get(pattern, 0) != 0:
+            continue
+        if pattern not in load_result.logs:
+            # Source unconfigured for this pattern — loader already warned.
+            continue
+        cov = load_result.coverage.get(pattern)
+        # Parse gap → silent (would otherwise tell the operator to widen
+        # the window on a file with no valid timestamps — misleading).
+        if cov is not None and cov.full_rows == 0:
+            continue
+        label = _pattern_human_label(source_key, pattern)
+        if cov is None or cov.full_rows is None:
+            if source_key != "zeek_dir":
+                continue
+            out.append(
+                f"{label}: files found, 0 records in the selected window. "
+                "Widen with --since/--days, or --all."
+            )
+            continue
+        if cov.full_span is not None:
+            start, end = cov.full_span
+            out.append(
+                f"{label}: {cov.full_rows:,} rows loaded, 0 in the selected "
+                f"window — data spans {start.isoformat()} → {end.isoformat()}. "
+                "Widen with --since/--days, or --all."
+            )
+        else:
+            out.append(
+                f"{label}: {cov.full_rows:,} rows loaded, 0 in the selected "
+                "window. Widen with --since/--days, or --all."
+            )
+    return out
+
+
+def _rotation_skip_notes(
+    load_result: "loader.LoadResult",
+    plan: RunPlan,
+) -> list[str]:
+    """Return disclosure notes for flat patterns windowed by rotation-peek.
+
+    The loader records a ``RotationSkipInfo`` per windowed pattern; the runner
+    formats the prose (the loader never imports the runner). Reuses
+    ``_pattern_human_label`` for the operator-language source name.
+
+    - ``fallback`` → reason-aware "read the full archive (windowing skipped)."
+      wording: "rotation order not monotonic" for the first-ts disorder fallback
+      (reason ``None`` or that string — byte-identical to before), "overlapping
+      export windows" for the Family-2 export-window conflict, and "duplicate
+      rotation files" for a same-rank duplicate slot. Fallback WINS: it is
+      data-true at the pattern level (``skipped == 0``), so the skip-summary cannot
+      also fire.
+    - else ``skipped > 0`` → "loaded L of L+S rotation files; S skipped outside
+      the selected window (by rotation order)." NEUTRAL "outside" is truthful
+      for both the ``--since`` older-tail skip and the ``--until`` too-new
+      leading skip (a bounded run can skip both under one count).
+    - else → no note.
+    """
+    out: list[str] = []
+    for pattern, info in load_result.rotation_skips.items():
+        label = _pattern_human_label(plan.needed_logs[pattern], pattern)
+        if info.fallback:
+            if info.fallback_reason == "overlapping export windows":
+                out.append(
+                    f"{label}: overlapping export windows — read the full archive "
+                    "(windowing skipped)."
+                )
+            elif info.fallback_reason == "duplicate rotation files":
+                out.append(
+                    f"{label}: duplicate rotation files — read the full archive "
+                    "(windowing skipped)."
+                )
+            else:  # "rotation order not monotonic" or None → existing wording
+                out.append(
+                    f"{label}: rotation order not monotonic — read the full archive "
+                    "(windowing skipped)."
+                )
+        elif info.skipped > 0:
+            out.append(
+                f"{label}: loaded {info.loaded} of {info.loaded + info.skipped} "
+                f"rotation files; {info.skipped} skipped outside the selected "
+                "window (by rotation order)."
+            )
+    return out
+
+
+def _dns_nudge(data_sources: list[str]) -> str | None:
+    """Return the Zeek evangelization note when only low-fidelity DNS data was loaded."""
+    ds = set(data_sources)
+    if "dnsmasq_dns" in ds and ds.isdisjoint(_RICH_DNS_SOURCES):
+        return (
+            "running on Pi-hole/dnsmasq logs — RTT, TTL, and connection correlation "
+            "unavailable. Add Zeek for richer DNS analysis and conn.log correlation."
+        )
+    return None
+
+
+def _aws_below_floor_note(
+    plan: RunPlan,
+    logs: dict[str, pd.DataFrame],
+    config: dict[str, Any],
+) -> str | None:
+    """RunSummary note disclosing principals below the aws min_events floor.
+
+    Pure derivation from the loaded CloudTrail frame via the detector's
+    public ``below_floor_count`` helper. Called BEFORE the detector loop —
+    detector-side state (a module cache populated inside run()) would be
+    stale at this point. Returns None when aws is not in the plan, when the
+    helper is missing (defensive), when no frame is loaded, or when count == 0.
+    """
+    if "aws" not in plan.will_run:
+        return None
+    mod = plan.detectors.get("aws")
+    if mod is None or not hasattr(mod, "below_floor_count"):
+        return None
+    df = logs.get("*.json*")
+    if df is None or df.empty:
+        return None
+    aws_cfg = get_detector_config(config, "aws", getattr(mod, "DEFAULT_CONFIG", {}))
+    default_min = getattr(mod, "DEFAULT_CONFIG", {}).get("min_events", 50)
+    min_events = aws_cfg.get("min_events", default_min)
+    count = mod.below_floor_count(df, min_events)
+    if count <= 0:
+        return None
+    return (
+        f"aws: {count} interactive principal(s) below the min_events floor were "
+        "not scored — the quiet tail of low-volume actors was not examined."
+    )
+
+
+def _aws_window_note(
+    plan: RunPlan, *, cloudtrail_narrowed: bool = False
+) -> str | None:
+    """First-seen labels are relative to the loaded window — name the limitation.
+
+    Fires whenever aws ran, regardless of whether any bursts were emitted. The
+    methodology limitation is worth knowing even if this run produced no
+    burst findings, because the absence is itself window-dependent.
+
+    The ``--all`` rider is keyed to CLOUDTRAIL ACTUALLY being narrowed (an
+    explicit --since/--until), NOT run-level default-window activity: CloudTrail
+    opts out of the auto-default window, so on a mixed unqualified run
+    (dns/syslog windowed) it loaded FULL and widening would not help. Rides the
+    EXISTING note (no new note, no position change) — placeholder voice, flag
+    for the qmail error-voice pass.
+    """
+    if "aws" not in plan.will_run:
+        return None
+    note = (
+        "aws: first-seen actions are first-seen within this loaded window — an "
+        "action that is routinely used but absent earlier in the window reads "
+        "as first-seen."
+    )
+    if cloudtrail_narrowed:
+        note += " Run with --all for a full-baseline analysis."
+    return note
+
+
+def _aws_no_interactive_note(
+    plan: RunPlan,
+    logs: dict[str, pd.DataFrame],
+    *,
+    cloudtrail_narrowed: bool,
+) -> str | None:
+    """Disclose the silent aws "nothing" when events loaded but zero are
+    interactive-lane (aws.run returns [] with no finding).
+
+    Pure derivation via the detector's public ``interactive_count`` helper
+    (mirrors ``_aws_below_floor_note``). Fires when aws is planned, the
+    ``*.json*`` frame is non-empty, and no event is interactive-lane. The
+    ``--all`` suffix is conditional on ``cloudtrail_narrowed`` — widening only
+    helps when an explicit window narrowed the load; on an unqualified run
+    CloudTrail already loaded full, so widening cannot surface interactive
+    events that do not exist. Placeholder voice (flag for the qmail pass).
+    """
+    if "aws" not in plan.will_run:
+        return None
+    mod = plan.detectors.get("aws")
+    if mod is None or not hasattr(mod, "interactive_count"):
+        return None
+    df = logs.get("*.json*")
+    if df is None or df.empty:
+        return None
+    if mod.interactive_count(df) != 0:
+        return None
+    note = (
+        f"aws: {len(df)} CloudTrail events loaded but none are interactive-lane — "
+        "aws scores only interactive activity, so nothing was analyzed."
+    )
+    if cloudtrail_narrowed:
+        note += " Run with --all for full history."
+    return note
+
+
+def _home_net_note(plan: RunPlan, config: dict[str, Any]) -> str | None:
+    """RunSummary note disclosing the internal networks in effect for scan.
+
+    Fires only when scan is in plan.will_run. Distinguishes default-vs-declared
+    by reading the ``__user_set__`` provenance sidecar attached by the config
+    loader — a pure value comparison would misclassify a user who declares the
+    RFC1918 list verbatim as "default". When the operator did not declare
+    home_net (no config file, or config file omits the key), the parenthetical
+    fires; when they did declare it, the note states their value plainly.
+    """
+    if "scan" not in plan.will_run:
+        return None
+    home_net = list(config.get("loghunter", {}).get("home_net", []))
+    if not home_net:
+        return None
+    rendered = ", ".join(home_net)
+    user_set = config.get("__user_set__", {}).get("loghunter", set())
+    if "home_net" in user_set:
+        return f"Internal networks: {rendered}."
+    return (
+        f"Internal networks: {rendered} "
+        "(RFC1918 default — set home_net in config to override)."
+    )
+
+
+def _source_overlap_notes(
+    source_dirs: dict[str, list[Path]], plan: RunPlan,
+) -> list[str]:
+    """RunSummary notes when two IN-PLAN source families resolve to one directory.
+
+    The contamination vector: flat discovery globs overlap (``syslog`` discovers
+    with the catch-all ``*.log*``), so a directory shared by two families has its
+    files parsed by each front-end — one log can surface as another's finding.
+    This is a plan-time disclosure, derived from already-resolved sources (same
+    posture as ``_home_net_note``), not a load-time check.
+
+    Binding rails:
+
+    - **Eligibility = in-plan families only.** Derived from
+      ``set(plan.needed_logs.values())``, NOT every non-empty resolved bucket.
+      A family configured-and-resolved but not selected (no detector in the run
+      reads it) cannot contaminate, so two dirs colliding while only one family
+      is planned does NOT warn. Optional multi-source detectors add only their
+      satisfiable patterns to ``needed_logs``, so the note follows what the
+      loader will actually read.
+    - **Directories only.** Explicit FILE inputs are out of scope — the vector
+      is dir-glob overlap, not a shared named file. Per-family duplicate inputs
+      collapse (a key is recorded once per directory).
+    - **Equal-dir ONLY (v1).** Flat discovery is non-recursive, so the shipped
+      default (``syslog_dir=/var/log`` containing ``zeek_dir=/var/log/zeek``)
+      does NOT contaminate and MUST NOT warn — nesting is deliberately out of
+      scope. (CloudTrail's ``rglob`` makes nested cloudtrail an acknowledged
+      deferred edge.)
+    - **Deterministic ordering.** ``source_dirs`` is built in canonical key order
+      by ``run`` (zeek, syslog, pihole, cloudtrail); first-seen preservation here
+      keeps the rendered family list deterministic. ≥3 families at one dir → one
+      note listing all.
+
+    Placeholder voice (pending the qmail error-voice pass).
+    """
+    in_plan = set(plan.needed_logs.values())
+    by_dir: dict[Path, list[str]] = {}
+    for key, paths in source_dirs.items():
+        if key not in in_plan:
+            continue
+        for p in paths:
+            if not p.is_dir():            # explicit files out of scope
+                continue
+            try:
+                resolved = p.resolve()
+            except OSError:
+                continue
+            families = by_dir.setdefault(resolved, [])
+            if key not in families:       # collapse per-family duplicate inputs
+                families.append(key)
+
+    notes: list[str] = []
+    for resolved, families in by_dir.items():
+        if len(families) >= 2:
+            notes.append(
+                f"{', '.join(families)} resolve to the same directory "
+                f"({resolved}): files there matching more than one source's "
+                "patterns are parsed by each, which can surface one log as "
+                "another's finding. Point them at separate directories — global "
+                "exports now auto-segment per source."
+            )
+    return notes
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# digest verb — orient-before-the-hunt
+#
+# run_digest() and the helpers below are a parallel entry point to run(). They
+# share the loader, output-handler-building, and _derive_data_sources. Default-
+# window resolution now goes through the SAME loader.resolve_load_windows +
+# loader.apply_default_window that run() uses — the digest twin engine is gone.
+# Digest default-windowing stays Zeek-ONLY (the caller-side gate below): non-Zeek
+# digest directories continue to load full, exactly as before. Pinned by the
+# Zeek-directory golden plus the programmatic non-Zeek load-full tests.
+# ─────────────────────────────────────────────────────────────────────────────
+
+_HISTOGRAM_HOURLY_THRESHOLD_HOURS = 48
+_HISTOGRAM_MAX_BINS = 60
+
+
+# Timestamp-confidence floor for digest cards. When the parseable-ts fraction
+# falls below this floor (or the non-NaN span is zero), the digest banner
+# window dashes and the histogram line renders "(timeline unavailable)" —
+# the card refuses to draw a timeline it cannot trust. Set at 80% per the
+# confident-but-wrong defects gate: lower risks rendering a confident
+# timeline on junk timestamps; higher would erase orientation when a small
+# fraction of a syslog batch is corrupt.
+_DIGEST_TS_CONFIDENCE_FLOOR: float = 0.80
+
+
+def _ts_confidence(frame: pd.DataFrame) -> bool:
+    """True iff the frame's ``ts`` column can support an honest timeline.
+
+    Both conditions must hold:
+
+    1. ``parsed / total >= _DIGEST_TS_CONFIDENCE_FLOOR`` (default 0.80) —
+       the parseable-ts fraction is high enough that the histogram bins
+       reflect the bulk of the records.
+    2. ``max(ts) - min(ts) > 0`` — the non-NaN timestamps span more than a
+       single instant; otherwise the histogram collapses to one bin and
+       lies about the timeline.
+
+    Both failure modes (low-coverage AND zero-span) render the same bare
+    ``(timeline unavailable)`` line — there is no footer disclosure in the
+    flat card grammar, so the differentiation that the old reason sentinels
+    enabled has no consumer.
+    """
+    total = int(len(frame))
+    if "ts" not in frame.columns or total == 0:
+        return False
+    ts = frame["ts"].dropna()
+    parsed = int(len(ts))
+    if parsed / total < _DIGEST_TS_CONFIDENCE_FLOOR:
+        return False
+    if parsed == 0:
+        return False
+    span = float(ts.max()) - float(ts.min())
+    if span <= 0:
+        return False
+    return True
+
+
+def _compute_histogram(
+    ts: pd.Series,
+    data_window: tuple[datetime, datetime],
+) -> tuple[list[int], str, int]:
+    """Adaptive-binning temporal histogram over a timestamp series.
+
+    Returns ``(counts, unit, peak)``:
+
+    - ``counts`` is a list of per-bin event counts spanning data_window.
+    - ``unit`` is ``"hr"`` for spans <= 48 hours, else ``"day"``.
+    - ``peak`` is the maximum bin value (0 when there are no events).
+
+    Without unit-aware binning, a 30-day window with hourly bars produces
+    720 useless bars; a 1-hour window with daily bars produces one. Both
+    fail to communicate shape — hence the adaptive switch.
+
+    The right edge is INCLUSIVE: the window is treated as ``[start, end]``
+    so that an event at exactly ``data_window[1]`` (the max-ts event when
+    ``data_window`` is derived from ``min(ts)/max(ts)``) lands in the
+    final bin instead of being silently dropped when the span lands on an
+    exact bin boundary. Callers must pass ``data_window`` such that
+    ``data_window[1] >= max(ts)``; the lone production caller (run_digest)
+    satisfies this by deriving ``data_window`` from the same loaded frame.
+
+    A zero-span window (``start == end``) with non-empty ``ts`` emits a
+    single bin holding the full count — appropriate for single-record
+    digests, or frames whose events all share one timestamp.
+    """
+    start, end = data_window
+    span_seconds = (end - start).total_seconds()
+
+    cleaned = ts.dropna().astype(float)
+    if cleaned.empty or span_seconds < 0:
+        return [], "hr", 0
+    if span_seconds == 0:
+        # All events share a single timestamp — emit one bin holding the count.
+        n = int(len(cleaned))
+        return [n], "hr", n
+
+    span_hours = span_seconds / 3600.0
+    if span_hours <= _HISTOGRAM_HOURLY_THRESHOLD_HOURS:
+        unit = "hr"
+        bin_seconds = 3600
+    else:
+        unit = "day"
+        bin_seconds = 86400
+
+    bin_count = max(1, -(-int(span_seconds) // bin_seconds))  # ceiling division
+    start_epoch = start.timestamp()
+    offsets = ((cleaned - start_epoch) // bin_seconds).astype("int64")
+    # Drop pre-window events, then collapse the inclusive right edge: events
+    # at exactly data_window[1] yield offset == bin_count when the span is an
+    # exact multiple of bin_seconds — fold those into the final bin instead
+    # of filtering them out.
+    offsets = offsets[offsets >= 0]
+    offsets = offsets.where(offsets < bin_count, bin_count - 1)
+    value_counts = offsets.value_counts().sort_index()
+    counts = [int(value_counts.get(i, 0)) for i in range(bin_count)]
+    if len(counts) > _HISTOGRAM_MAX_BINS:
+        # Cap output width by folding adjacent bins by sum. The unit label
+        # stays nominal — each glyph now spans several hr/day — but the peak
+        # anchor recomputed below stays truthful to the drawn bars.
+        group_size = -(-len(counts) // _HISTOGRAM_MAX_BINS)
+        counts = [
+            sum(counts[i:i + group_size])
+            for i in range(0, len(counts), group_size)
+        ]
+    peak = max(counts) if counts else 0
+    return counts, unit, peak
+
+
+_DNS_ZEEK_EMPTY_COLUMNS = [
+    "ts", "src", "query", "rtt", "ttl", "rcode", "answer", "tc", "qtype",
+]
+_DNS_PIHOLE_EMPTY_COLUMNS = [
+    "ts", "src", "query", "event_type", "qtype", "dst", "answer",
+    "validation", "host", "raw", "message",
+]
+_CONN_EMPTY_COLUMNS = [
+    "src", "dst", "port", "proto", "ts", "bytes", "conn_state", "local_orig",
+]
+_SYSLOG_EMPTY_COLUMNS = ["ts", "host", "program", "raw", "message"]
+_CLOUDTRAIL_EMPTY_COLUMNS = [
+    "ts", "principal", "lane", "read_write",
+    "event_source", "event_name", "identity_type",
+    "source_ip", "error_code", "aws_region", "event_id", "raw",
+]
+
+
+# (schema, source_key) → (loader glob pattern, empty-frame column set).
+# Mechanical mapping kept inline alongside run_digest because it's runner
+# plumbing — pattern + columns are runner/loader concerns, NOT source-
+# resolution ownership (DigestSource just carries the directory + feed +
+# source_key). See plan: "_PATTERN_AND_EMPTY[(schema, source_key)] inline".
+_DIGEST_PATTERN_AND_EMPTY: dict[tuple[str, str], tuple[str, list[str]]] = {
+    ("conn",       "zeek_dir"):       ("conn*.log*",   _CONN_EMPTY_COLUMNS),
+    ("dns",        "zeek_dir"):       ("dns*.log*",    _DNS_ZEEK_EMPTY_COLUMNS),
+    ("dns",        "pihole_dir"):     ("pihole*.log*", _DNS_PIHOLE_EMPTY_COLUMNS),
+    ("syslog",    "syslog_dir"):      ("*.log*",       _SYSLOG_EMPTY_COLUMNS),
+    ("syslog",    "zeek_dir"):        ("syslog*.log*", _SYSLOG_EMPTY_COLUMNS),
+    ("cloudtrail", "cloudtrail_dir"): ("*.json*",      _CLOUDTRAIL_EMPTY_COLUMNS),
+}
+
+
+# Inter-card separator emitted between adjacent rendered cards on a multi-card
+# run (stdout fan-out or --out concatenation). 40 columns of U+2500 BOX
+# DRAWINGS LIGHT HORIZONTAL, flush-left, with one blank line above and one
+# blank line below. Single-card runs (one positional, or a multi-positional
+# run where only one path reaches render-commit) draw no rule at all — the
+# emit fires only when ``leading_separator=True``, which the CLI sets from
+# ``rendered > 0`` AFTER a prior card's run_digest return.
+_DIGEST_INTER_CARD_RULE: str = "─" * 40
+
+
+def _emit_inter_card_separator(stream: Any) -> None:
+    """Emit the 40-col inter-card rule with bracketing blank lines."""
+    target = stream if stream is not None else sys.stdout
+    print(file=target)
+    print(_DIGEST_INTER_CARD_RULE, file=target)
+    print(file=target)
+
+
+def _render_blob_for_path(
+    blob_path: Path,
+    *,
+    stream: Any = None,
+    output_dir: Path | None = None,
+    output_file: Path | None = None,
+    verbose_level: int = 0,
+    leading_separator: bool = False,
+) -> None:
+    """Profile a single file via the blob digest path and render the card.
+
+    Shared by the canonical blob branch (schema == "blob": sniff routed a
+    path to the blob floor) and the defensive fallback in the recognised-
+    schema path (item 2: a summariser raise on a recognised schema falls
+    through to a blob card for the same file instead of aborting the fan-
+    out).
+
+    Caller verifies that ``blob_path`` is a regular file before invoking.
+    Output routing (stream / output_dir / output_file / verbose) is the
+    same shape ``run_digest`` itself uses; the fallback caller threads its
+    own values so the blob card lands on the same fan-out stream and
+    --out target as the original card would have.
+
+    ``leading_separator`` is the single-owner emission seam for blob cards.
+    This function owns the rule for BOTH the top-level blob route AND the
+    summariser-failure fallback — ``run_digest`` never emits when handing
+    off to the fallback, it just threads the flag here. Emission happens
+    immediately before ``handler.render_blob(card)`` so a separator only
+    ever precedes a card that reaches its render call.
+    """
+    from loghunter.digest import blob as _blob_summarizer
+    card = _blob_summarizer.summarize_blob(blob_path)
+
+    handler, close_handler = _build_output_handler(
+        "text", output_dir, output_file, verbose_level, stream=stream,
+    )
+    try:
+        from loghunter.outputs.text import TextHandler
+        if not isinstance(handler, TextHandler):
+            raise RuntimeError(
+                "digest blob: _build_output_handler did not return a "
+                f"TextHandler (got {type(handler).__name__})"
+            )
+        if leading_separator:
+            _emit_inter_card_separator(stream)
+        handler.render_blob(card)
+    finally:
+        close_handler()
+
+
+def run_digest(
+    config: dict[str, Any],
+    zeek_dir: str | Path | None = None,
+    pihole_dir: str | Path | None = None,
+    syslog_dir: str | Path | None = None,
+    cloudtrail_dir: str | Path | None = None,
+    blob_path: Path | None = None,
+    since: datetime | None = None,
+    until: datetime | None = None,
+    output_format: str = "text",
+    output_dir: Path | None = None,
+    output_file: Path | None = None,
+    stream: Any = None,
+    verbose_level: int = 0,
+    dry_run: bool = False,
+    load_all: bool = False,
+    skip_confirm: bool = False,
+    schema: str = "conn",
+    fallback_blob_path: Path | None = None,
+    leading_separator: bool = False,
+    show_progress: bool = True,
+) -> None:
+    """Digest entry point — orient-before-the-hunt for a single schema.
+
+    Loads the source frame, computes spine ambient facts and a temporal
+    histogram, dispatches to the schema summariser, assembles a DigestCard,
+    and renders it. Does NOT build a RunPlan, does NOT run the allowlist
+    loop, does NOT produce Findings.
+
+    Pre-allowlist tap: the loaded frame is consumed BEFORE the allowlist
+    seam. Allowlisted infrastructure (resolvers, pollers) is part of what's
+    in the pile and stays on the sonar. This function MUST NOT call
+    build_matcher or AllowlistMatcher.filter_df.
+
+    Source-dir parameters (``zeek_dir`` / ``pihole_dir`` / ``syslog_dir`` /
+    ``cloudtrail_dir``) are EXPLICIT OVERRIDES with ``None`` meaning
+    "no override." Pass a string or ``Path``;
+    ``loghunter.common.sources.resolve_digest_source`` owns the per-schema
+    candidate ladder, wrong-key + XOR + not-configured errors (byte-preserved
+    from the previous in-line strings), and is the SOLE site that converts
+    a source-dir string to a Path. CLI callers thread raw parsed strings;
+    programmatic callers can pass already-resolved ``Path``s or let ``None``
+    fall back to ``config["loghunter"][candidate]`` (LH_ROOT applied).
+
+    ``leading_separator`` drives the multi-card inter-card rule. The CLI
+    fan-out sets it from ``rendered > 0`` after a previous card committed
+    to render. Single-owner emission: run_digest emits for schema cards
+    (immediately before handler.render_digest); on the summariser-failure
+    fallback arm it threads the flag through to _render_blob_for_path
+    (which owns blob emission) and does NOT emit itself.
+    """
+    if output_format != "text":
+        raise ValueError(
+            f"digest currently supports only --output=text (got {output_format!r})"
+        )
+    if schema not in ("conn", "dns", "syslog", "cloudtrail", "blob"):
+        raise ValueError(f"digest: unsupported schema {schema!r}")
+
+    # The blob path is reached ONLY via the CLI sniff router, never via an
+    # operator token (the `digest blob PATH` token is gone). The blob
+    # terminal branch is small by design: profile the single file and hand
+    # off to _render_blob_for_path, which builds + renders the card. No
+    # loader, no allowlist, no histogram, no DigestCard — blob has no
+    # parsed frame.
+    if schema == "blob":
+        if blob_path is None:
+            raise ValueError(
+                "digest blob: PATH not provided — pass a positional PATH"
+            )
+        if not blob_path.is_file():
+            raise ValueError(f"digest blob: not a file: {blob_path}")
+
+        if dry_run:
+            print("LogHunter  ·  digest dry run")
+            print(_SEP)
+            print("  schema:       blob")
+            print(f"  path:         {blob_path}")
+            print("  window:       (none — blob extracts no fields)")
+            print(_SEP)
+            return
+
+        _render_blob_for_path(
+            blob_path,
+            stream=stream,
+            output_dir=output_dir,
+            output_file=output_file,
+            verbose_level=verbose_level,
+            leading_separator=leading_separator,
+        )
+        return
+
+    if blob_path is not None:
+        raise ValueError(
+            f"digest {schema}: blob_path is only valid for the blob schema"
+        )
+
+    cfg_lh = config.get("loghunter", {})
+
+    # Single owner of digest source resolution. resolve_digest_source runs the
+    # per-schema candidate ladder + wrong-key / XOR / not-configured guards
+    # with byte-preserved error strings, and is the SOLE site that converts
+    # a source-dir string to a Path on the digest path.
+    ds = resolve_digest_source(
+        config, schema,
+        overrides={
+            "zeek_dir": zeek_dir,
+            "syslog_dir": syslog_dir,
+            "pihole_dir": pihole_dir,
+            "cloudtrail_dir": cloudtrail_dir,
+        },
+    )
+    feed = ds.feed
+    source_dir = ds.directory
+    source_key = ds.source_key
+    pattern, empty_columns = _DIGEST_PATTERN_AND_EMPTY[(schema, source_key)]
+
+    from loghunter.common import loader
+
+    # Default-window resolution is Zeek-ONLY on the digest path (CODE.md
+    # boundedness rule): non-Zeek digest directories (pihole/syslog/cloudtrail)
+    # load full and filter by an explicit window only. The caller-side gate below
+    # IS the behavior-preservation point — digest invokes the SHARED resolver
+    # (loader.resolve_load_windows) for the Zeek source alone, NOT a duplicate
+    # engine. dated → precise (since, until); flat / mixed → post-load trim_span.
+    dated_window: tuple[datetime, datetime] | None = None
+    flat_span: timedelta | None = None
+    keep_null = False
+    default_note = None  # no banner on the flat digest card — never rendered
+    if source_key == "zeek_dir":
+        default_spec = cfg_lh.get("default_window", "1d")
+        _digest_windows = loader.resolve_load_windows(
+            {pattern: source_key}, {source_key: [source_dir]}, default_spec,
+            since=since, until=until, load_all=load_all,
+        )
+        if _digest_windows:
+            w = _digest_windows[0]
+            dated_window = w.select_window if w.trim_span is None else None
+            flat_span = w.trim_span
+            keep_null = w.keep_null
+
+    if dry_run:
+        print("LogHunter  ·  digest dry run")
+        print(_SEP)
+        print(f"  schema:       {schema}")
+        if feed is not None:
+            print(f"  feed:         {feed}")
+        print(f"  {source_key}:{' ' * max(0, 13 - len(source_key) - 1)} {source_dir}")
+        if dated_window is not None:
+            print(
+                f"  window:       {dated_window[0].isoformat()}  →  "
+                f"{dated_window[1].isoformat()}  (dated default)"
+            )
+        elif flat_span is not None:
+            print(f"  window:       last {cfg_lh.get('default_window', '1d')} of available data  (flat default)")
+        elif since is not None or until is not None:
+            since_str = since.isoformat() if since else "beginning of data"
+            until_str = until.isoformat() if until else "end of data"
+            print(f"  window:       {since_str}  →  {until_str}")
+        elif load_all:
+            print("  window:       all available data (--all)")
+        else:
+            print("  window:       all available data")
+        print(_SEP)
+        return
+
+    needed_logs = {pattern: source_key}
+    # Digest compat: load_required_logs is list-only. Wrap [source_dir] for
+    # the degenerate one-element case — card-per-file behavior unchanged,
+    # the union plumbing runs as a single-element passthrough.
+    source_dirs = {source_key: [source_dir]}
+    source_windows = (
+        {source_key: dated_window} if dated_window is not None else None
+    )
+
+    # Single-file Zeek bypass: the file was already content-identified by sniff;
+    # discover_zeek_files' fnmatch(basename, pattern) gate is meaningless for an
+    # explicitly-named single file and was dropping date-prefixed Zeek logs
+    # (e.g. 2026-06-09.conn.log) into zero-row cards. Pi-hole, syslog, and
+    # CloudTrail loaders already accept explicit files without a basename gate;
+    # only the Zeek path needs the bypass. discover_zeek_files itself is
+    # unchanged — the detect path still uses its single-file gate as a type
+    # check.
+    if source_key == "zeek_dir" and source_dir.is_file():
+        s_since, s_until = (
+            dated_window if dated_window is not None else (since, until)
+        )
+        warnings: list[str] = []
+        try:
+            data_size_bytes = source_dir.stat().st_size
+        except OSError:
+            data_size_bytes = 0
+        df = loader.load_logs(
+            source_dir.parent, pattern, s_since, s_until,
+            _files=[source_dir], _warnings=warnings,
+            show_progress=show_progress,
+        )
+        # Preserve schema-warning parity with load_required_logs so
+        # malformed-but-parseable Zeek single files behave identically on the
+        # bypass and directory paths.
+        schema_warning = loader._schema_warning(pattern, df)
+        if schema_warning:
+            warnings.append(schema_warning)
+        logs = {pattern: df}
+        record_counts = {pattern: len(df)} if not df.empty else {}
+        load_result = loader.LoadResult(
+            logs=logs,
+            record_counts=record_counts,
+            data_window=loader._data_window(logs),
+            warnings=warnings,
+            data_size_bytes=data_size_bytes,
+        )
+    else:
+        load_result = loader.load_required_logs(
+            needed_logs,
+            source_dirs,
+            since,
+            until,
+            verbose=(verbose_level >= 1),
+            source_windows=source_windows,
+            show_progress=show_progress,
+        )
+
+    if flat_span is not None:
+        load_result = loader.apply_default_window(
+            load_result, [pattern], flat_span, keep_null=keep_null,
+        )
+
+    for warning in load_result.warnings:
+        print(f"Warning: {warning}", file=sys.stderr)
+
+    total_records = sum(load_result.record_counts.values())
+    warn_above: int = cfg_lh.get("warn_above", 5_000_000)
+    if total_records > warn_above and not skip_confirm:
+        try:
+            answer = input(
+                f"{total_records:,} records found. This may take a while. "
+                "Continue? [y/N] "
+            )
+        except (EOFError, KeyboardInterrupt):
+            answer = ""
+        if answer.strip().lower() not in ("y", "yes"):
+            raise ExportAborted("loghunter: aborted by user")
+
+    if load_result.data_window is not None:
+        data_window = load_result.data_window
+    elif since or until:
+        data_window = (
+            since or datetime.now(timezone.utc),
+            until or datetime.now(timezone.utc),
+        )
+    else:
+        _now = datetime.now(timezone.utc)
+        data_window = (_now, _now)
+
+    # data_sources / notes were the RunSummary banner inputs; the flat
+    # digest card has no banner so they are no longer consumed here.
+    # default_note is the unbounded-source default-window note — same
+    # provenance disclosure, no card surface to attach it to under the new
+    # grammar. Reference both so unused-arg checkers stay quiet.
+    _ = _derive_data_sources(needed_logs, load_result.record_counts)
+    _ = default_note
+
+    # Identity line 1 always carries the source's name — file or directory.
+    # Directory-mode bare-config digest gets a sensible identity even though
+    # the source is a multi-file load.
+    source_name = source_dir.name
+
+    # Pre-allowlist tap — pull the frame straight out of load_result.
+    # NO build_matcher. NO AllowlistMatcher.filter_df. Digest is the orient
+    # step; allowlisted infrastructure (resolvers, pollers) is part of
+    # what's in here and stays on the sonar.
+    #
+    # Frame is the source of truth for whether a schema card can render.
+    # Empty frame → DigestEmpty (control signal, NOT a ValueError). The
+    # file was understood — it simply had no parseable records. The CLI
+    # narrates this distinctly from a real per-path failure. Applies ONLY
+    # to the recognized-schema path; blob has its own terminal branch
+    # above and an empty FILE was already caught at sniff time as
+    # state="empty" in the CLI fan-out.
+    frame = load_result.logs.get(pattern)
+    if frame is None or frame.empty:
+        raise DigestEmpty(basename=source_dir.name, schema=schema)
+    # empty_columns reserved for any future tolerant-load path; the
+    # current contract is "recognized schema must have at least one row
+    # to render a card", enforced by the raise above.
+    _ = empty_columns
+
+    # Timestamp-confidence gate (now boolean). Below the floor OR with a
+    # zero non-NaN span, the timeline cannot be drawn honestly — dash the
+    # identity-line window AND signal timeline_unavailable to the
+    # renderer, which emits the bare "(timeline unavailable)" histogram
+    # replacement. Both former failure modes (low coverage AND zero span)
+    # render identically; the flat card has no footer surface to
+    # differentiate them.
+    if _ts_confidence(frame):
+        histogram_counts, histogram_unit, histogram_peak = _compute_histogram(
+            frame["ts"], data_window,
+        )
+        timeline_unavailable = False
+    else:
+        data_window = (None, None)
+        histogram_counts = []
+        histogram_unit = "hr"
+        histogram_peak = 0
+        timeline_unavailable = True
+
+    from loghunter import digest
+    from loghunter.common.finding import DigestCard
+
+    # Narrow defence-in-depth wrap (item 2): summariser dispatch + body +
+    # DigestCard construction. If the summariser raises on a pathological
+    # frame (e.g. a duplicate `src` column producing pandas' "Grouper for
+    # 'src' not 1-dimensional"), fall through to a blob card for the same
+    # file rather than aborting the fan-out. Glenn's scope discipline:
+    #   - DOES catch summariser raises and DigestCard-construction raises.
+    #   - DOES NOT catch loader/parser errors (above this wrap).
+    #   - DOES NOT catch DigestEmpty (raised above; control signal).
+    #   - DOES NOT catch handler/render errors (below this wrap).
+    #   - DOES NOT catch BaseException — KeyboardInterrupt / SystemExit
+    #     propagate.
+    # Bare-config callers (no single-file fallback path available) pass
+    # fallback_blob_path=None and the exception re-raises to the caller's
+    # existing ValueError arm.
+    try:
+        summarizer = digest.get_summarizer(schema)
+        if schema in ("dns", "syslog"):
+            body = summarizer(frame, feed)
+        else:
+            body = summarizer(frame)
+        card = DigestCard(
+            schema=schema,
+            source_name=source_name,
+            data_window=data_window,
+            record_count=total_records,
+            histogram_counts=histogram_counts,
+            histogram_unit=histogram_unit,
+            histogram_peak=histogram_peak,
+            zone1_extras=body["zone1_extras"],
+            insights=body["insights"],
+            fields=body["fields"],
+            data_size_bytes=load_result.data_size_bytes,
+            timeline_unavailable=timeline_unavailable,
+        )
+    except Exception as exc:
+        if fallback_blob_path is None:
+            raise
+        # One-line stderr breadcrumb — verbose-gated so the raw exception
+        # text does not leak to default-mode users (the "actionable
+        # messages, never raw exceptions" rail). Default runs see the
+        # blob card as the whole story; --verbose retains the breadcrumb
+        # for debugging. The error-voice pass will tune the phrasing;
+        # voice is PLACEHOLDER.
+        if verbose_level >= 1:
+            print(
+                f"digest: {fallback_blob_path.name}: summariser failed "
+                f"({type(exc).__name__}: {exc}); falling back to blob",
+                file=sys.stderr,
+            )
+        # Separator single-owner: _render_blob_for_path owns blob-card
+        # emission. We thread the flag and do NOT emit here, or the run
+        # would print two rules around the same fallback card.
+        _render_blob_for_path(
+            fallback_blob_path,
+            stream=stream,
+            output_dir=output_dir,
+            output_file=output_file,
+            verbose_level=verbose_level,
+            leading_separator=leading_separator,
+        )
+        return
+
+    handler, close_handler = _build_output_handler(
+        "text", output_dir, output_file, verbose_level, stream=stream,
+    )
+    try:
+        from loghunter.outputs.text import TextHandler
+        if not isinstance(handler, TextHandler):
+            raise RuntimeError(
+                "digest: _build_output_handler did not return a TextHandler "
+                f"(got {type(handler).__name__})"
+            )
+        if leading_separator:
+            _emit_inter_card_separator(stream)
+        handler.render_digest(card)
+    finally:
+        close_handler()