pi-dev-team 0.2.0

package/hooks/lib/pricing.py

@@ -0,0 +1,118 @@
+"""Model-pricing loader, rate lookup, and cost computation (issue #2045,
+epic #2040).
+
+Shared by `hooks/lib/cost_meter.py` (the Stop-hook cost meter) and
+`session_report.py --profile maintainer` (originally a separate monorepo-only
+session digest extractor, retired in #2048; #2045 unified the two). Before
+this module existed each carried its
+own near-identical copy of `_load_pricing`/`_rate`/`_cost`, and the two had
+quietly drifted: cost_meter's loader raised on a missing/unreadable
+pricing file where the extractor's degraded to an empty table, and
+cost_meter's `_cost` required its caller to guard `if rate else 0.0` (it
+indexed `rate["input"]` directly) where the extractor's guarded internally
+and read `rate.get(...)`. Unified here on the more defensive shape throughout: an
+absent/corrupt/`None` pricing path yields `{}` rather than raising, and
+`cost()` itself returns `0.0` for an unpriced model rather than requiring
+every caller to remember the ternary — consistent with this file's own
+fail-open philosophy (see `cost_meter.py`'s `cmd_record`/`cmd_phase_mark`,
+which return 0 on a missing transcript rather than raising: a hook must
+never break a turn).
+
+Placement — NOT `plugins/dev-team/scripts/lib/session_log/`, despite that
+package's `__init__.py` briefly forward-declaring a `pricing` module for
+this issue (corrected in the same commit that adds this file). Reason:
+`hooks/lib/cost_meter.py` is a real Stop hook, registered in `settings.json`
+and run on every session in every installed project.
+`hooks/lib/review_agent_registry.py` and `hooks/lib/review_dispatch_ledger.py`
+already established the rule this module follows — "a hook must be
+import-safe without any `scripts/` module on its path; the dependency
+direction is scripts/ -> hooks/lib/, never the reverse" (#1461) — so a
+module a hook needs lives in `hooks/lib/`, and the `scripts/` side reaches
+into it, exactly mirroring how `scripts/check_review_agent_mcp_tools.py`
+already imports `review_agent_registry` from `hooks/lib/`. Putting pricing
+here instead of `session_log/` keeps that boundary intact rather than
+inverting it for this one module.
+
+Downstream-cost decision (#2045): `session_report.py --profile downstream`
+(originally a separate shipped script, retired in #2048; the shipped
+report a downstream user hands to the plugin
+maintainer) does NOT gain a cost figure as part of this issue, and does not
+import this module. ADR 0036 already decided this narrower question — "The extractors'
+divergent layers stay forked: discovery/CLI surface, **pricing and cost**,
+rollup, escalation, and the report shapes... cost/pricing/rollup/escalation
+exist only in the monorepo one. Divergence is not drift." — for exactly the
+reason issue #2045 itself names as the argument against: a pricing table
+shipped inside the plugin is unverifiable by the downstream user and goes
+stale between releases, so it's presented in `cost_meter.py`'s own reports
+(which run in the environment that produced the spend) rather than baked
+into a portable summary file.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+DEFAULT_CACHE_WRITE_MULTIPLIER = 1.25
+DEFAULT_CACHE_READ_MULTIPLIER = 0.1
+
+
+def _usage_field(usage: dict, field: str) -> int | float:
+    """`.get(field, 0) or 0` — the one canonical usage-field reader (matches
+    `scripts/lib/session_log/records.usage_field`'s null-handling contract;
+    duplicated here rather than imported, in service of the hooks/lib ->
+    scripts/ dependency direction described in the module docstring above —
+    this module must not reach INTO `scripts/lib/session_log/` any more than
+    `cost_meter.py` may)."""
+    return usage.get(field, 0) or 0
+
+
+def load_pricing(path: Path | None) -> dict:
+    """Load a model-pricing.json table. Defensive: an absent path, a `None`
+    path, or malformed JSON all degrade to `{}` (every model then prices at
+    $0.00 and is flagged `unpriced`) rather than raising."""
+    if not path or not Path(path).is_file():
+        return {}
+    try:
+        return json.loads(Path(path).read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def rate(pricing: dict, model: str) -> dict | None:
+    """Resolve one model id to its `{"input": .., "output": ..}` rate,
+    following a pricing table's `aliases` indirection when the model id has
+    no direct entry."""
+    models = pricing.get("models", {})
+    if model in models:
+        return models[model]
+    alias = pricing.get("aliases", {}).get(model)
+    if alias and alias in models:
+        return models[alias]
+    return None
+
+
+def cost(usage: dict, rate_entry: dict | None, pricing: dict) -> float:
+    """Dollar cost of one usage block at `rate_entry`. `0.0` when no rate is
+    known for the model — an unpriced model contributes $0, never raises."""
+    if not rate_entry:
+        return 0.0
+    input_tokens = _usage_field(usage, "input_tokens")
+    output_tokens = _usage_field(usage, "output_tokens")
+    cache_write_tokens = _usage_field(usage, "cache_creation_input_tokens")
+    cache_read_tokens = _usage_field(usage, "cache_read_input_tokens")
+    in_rate = rate_entry.get("input", 0)
+    return (
+        input_tokens / 1e6 * in_rate
+        + output_tokens / 1e6 * rate_entry.get("output", 0)
+        + cache_write_tokens
+        / 1e6
+        * in_rate
+        * pricing.get("cache_write_multiplier", DEFAULT_CACHE_WRITE_MULTIPLIER)
+        + cache_read_tokens
+        / 1e6
+        * in_rate
+        * pricing.get("cache_read_multiplier", DEFAULT_CACHE_READ_MULTIPLIER)
+    )

package/hooks/lib/report_pdf.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""Render a Markdown report to a styled PDF.
+
+Backs the ``/report-pdf`` command and the ``--pdf`` flag on report-producing
+skills. Stdlib only, (ADR 0014 / 0015). Detects a PDF engine via.
+runtime probes and converts Markdown -> PDF, **never raising for a missing
+engine** — callers get a structured :class:`RenderResult` and the underlying
+Markdown report is left untouched.
+
+Two pipelines sit behind one abstraction:
+
+- **pandoc-mediated** — Markdown -> self-contained HTML (with the bundled
+  ``report-print.css``) via pandoc, then HTML -> PDF via headless
+  Chrome/Chromium, weasyprint, or wkhtmltopdf.
+- **direct** — ``md-to-pdf`` consumes Markdown directly (no pandoc).
+
+Fallback order: Chrome/Chromium -> weasyprint -> wkhtmltopdf -> md-to-pdf. The
+first three require pandoc; md-to-pdf does not.
+
+State is read off a single :class:`RenderResult`:
+
+- success  -> ``rendered=True``, ``engine``/``out_path`` set, reason fields None
+- skip     -> ``rendered=False``, ``reason``+``install_hint`` set, ``error`` None
+- failure  -> ``rendered=False``, ``error`` set, ``reason``/``install_hint`` None
+
+CLI contract (``report_pdf.py <md> [--out <path>]``):
+
+    stdout : a ``Rendering …`` progress line, then one result line
+    exit 0 : rendered, or skipped (no engine) — the report is always safe
+    exit 1 : source file not found, or an engine was present but failed
+    exit 2 : usage error (no path given)
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+# Detection order. ``kind`` is the pipeline: "pandoc" engines consume HTML that
+# pandoc produces; "direct" engines consume Markdown themselves.
+_PANDOC = "pandoc"
+_DIRECT = "direct"
+
+# Upper bound (seconds) on any single engine/pandoc invocation. A wedged
+# headless Chrome must surface as an engine failure, never an indefinite hang.
+_TIMEOUT_SECONDS = 120
+
+# PATH names probed for a Chrome/Chromium binary, in preference order.
+_CHROME_NAMES = (
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "chrome",
+)
+
+
+@dataclass
+class Engine:
+    """A resolved PDF engine: its ``name``, pipeline ``kind``, and (for Chrome)
+    the concrete ``binary`` path a PATH/app-path probe found."""
+
+    name: str
+    kind: str
+    binary: str | None = None
+
+
+@dataclass
+class RenderResult:
+    """Outcome of a render attempt — the single contract both surfaces key off.
+
+    See the module docstring for the field discriminant across
+    success / skip / failure.
+    """
+
+    rendered: bool
+    engine: str | None = None
+    out_path: str | None = None
+    reason: str | None = None
+    install_hint: str | None = None
+    error: str | None = None
+
+
+def _chrome_binary() -> str | None:
+    """Locate a Chrome/Chromium binary via runtime probes only.
+
+    PATH names first (cross-OS), then OS-specific application paths chosen by
+    ``platform.system()`` so the probe stays a runtime decision (mockable in
+    tests) rather than a hard-coded constant.
+    """
+    for name in _CHROME_NAMES:
+        found = shutil.which(name)
+        if found:
+            return found
+    system = platform.system()
+    candidates: list[str] = []
+    if system == "Darwin":
+        candidates = [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        ]
+    elif system == "Windows":
+        for env in ("PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA"):
+            base = os.environ.get(env)
+            if base:
+                candidates.append(
+                    os.path.join(base, "Google", "Chrome", "Application", "chrome.exe")
+                )
+    for candidate in candidates:
+        if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+def detect_engine() -> Engine | None:
+    """Return the first available engine in fallback order, or ``None``.
+
+    Chrome/weasyprint/wkhtmltopdf are only offered when pandoc is present (they
+    consume pandoc's HTML). md-to-pdf is offered whether or not pandoc exists —
+    it must never be gated behind pandoc.
+    """
+    if shutil.which("pandoc"):
+        chrome = _chrome_binary()
+        if chrome:
+            return Engine("chrome", _PANDOC, binary=chrome)
+        if shutil.which("weasyprint"):
+            return Engine("weasyprint", _PANDOC)
+        if shutil.which("wkhtmltopdf"):
+            return Engine("wkhtmltopdf", _PANDOC)
+    if shutil.which("md-to-pdf"):
+        return Engine("md-to-pdf", _DIRECT)
+    return None
+
+
+def install_hint() -> str:
+    """A single, OS-appropriate install suggestion — one actionable path, not a
+    menu of every engine (the report is already saved; the PDF is the extra)."""
+    system = platform.system()
+    if system == "Darwin":
+        cmd = "brew install pandoc && brew install --cask google-chrome"
+    elif system == "Windows":
+        cmd = "install pandoc + Google Chrome, or `npm i -g md-to-pdf`"
+    else:
+        cmd = "apt-get install pandoc chromium  (or `pip install weasyprint`)"
+    return (
+        f"No PDF engine found. Install one, e.g.: {cmd}. "
+        "Markdown report saved; PDF skipped."
+    )
+
+
+def default_css_path() -> Path:
+    """The bundled print stylesheet shipped with the plugin."""
+    return Path(__file__).resolve().parents[2] / "knowledge" / "report-print.css"
+
+
+def _pandoc_html_cmd(src: Path, html: Path) -> list[str]:
+    # --sandbox blocks pandoc from fetching any external resource during
+    # conversion, so a report embedding an attacker-influenced remote URL
+    # (report content can quote code from a reviewed repo) cannot drive an
+    # outbound request at build time (SSRF). The stylesheet is injected in
+    # Python afterwards (_inject_css) — sandbox would otherwise block reading
+    # even an explicitly-passed --css file.
+    return [
+        "pandoc",
+        str(src),
+        "-f",
+        "gfm",
+        "-t",
+        "html5",
+        "--standalone",
+        "--sandbox",
+        "--metadata",
+        f"title={src.stem}",
+        "-o",
+        str(html),
+    ]
+
+
+def _inject_css(html: Path, css: Path | None) -> None:
+    """Inline the bundled stylesheet into the pandoc HTML head.
+
+    Done in Python (not via pandoc ``--css``) because ``--sandbox`` blocks
+    pandoc from reading the CSS file. No-op when no stylesheet is available.
+    """
+    if not (css and css.is_file()):
+        return
+    try:
+        css_text = css.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        # An unreadable/malformed stylesheet degrades to unstyled output —
+        # never raises, matching the module's graceful-degradation contract.
+        return
+    style = f"<style>\n{css_text}\n</style>"
+    doc = html.read_text(encoding="utf-8")
+    if "</head>" in doc:
+        doc = doc.replace("</head>", style + "\n</head>", 1)
+    else:
+        doc = style + "\n" + doc
+    html.write_text(doc, encoding="utf-8")
+
+
+def _engine_pdf_cmd(engine: Engine, html: Path, out: Path) -> list[str]:
+    # Absolute output paths so a value beginning with '-' can never be parsed
+    # as an option by a positional-arg engine (weasyprint/wkhtmltopdf).
+    out_abs = str(out.resolve())
+    if engine.name == "chrome":
+        return [
+            engine.binary or "google-chrome",
+            "--headless=new",
+            "--disable-gpu",
+            # No JavaScript: a Markdown-derived report never needs it, and it
+            # closes the headless-Chrome JS-execution vector on report content.
+            "--disable-javascript",
+            "--no-pdf-header-footer",
+            "--run-all-compositor-stages-before-draw",
+            "--virtual-time-budget=10000",
+            f"--print-to-pdf={out_abs}",
+            html.resolve().as_uri(),
+        ]
+    if engine.name == "weasyprint":
+        return ["weasyprint", str(html.resolve()), out_abs]
+    if engine.name == "wkhtmltopdf":
+        return ["wkhtmltopdf", str(html.resolve()), out_abs]
+    raise ValueError(f"not a pandoc-mediated engine: {engine.name}")
+
+
+def _mdtopdf_cmd(src: Path, css: Path | None) -> list[str]:
+    cmd = ["md-to-pdf", str(src)]
+    if css and css.is_file():
+        cmd += ["--stylesheet", str(css)]
+    return cmd
+
+
+def _run(runner: Callable, cmd: list[str]) -> subprocess.CompletedProcess:
+    return runner(cmd, capture_output=True, text=True, timeout=_TIMEOUT_SECONDS)
+
+
+def _fail(engine_name: str, msg: str) -> RenderResult:
+    return RenderResult(rendered=False, engine=engine_name, error=msg)
+
+
+def _step_error(label: str, proc: subprocess.CompletedProcess) -> str:
+    return f"{label} failed: {(proc.stderr or '').strip()}"
+
+
+def _render_pandoc(
+    engine: Engine, src: Path, out: Path, css: Path | None, runner: Callable
+) -> str | None:
+    """pandoc-mediated pipeline (Markdown → HTML+CSS → PDF). Returns an error
+    string on failure, or None on success. Always unlinks the temp HTML."""
+    with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as handle:
+        html = Path(handle.name)
+    try:
+        step1 = _run(runner, _pandoc_html_cmd(src, html))
+        if step1.returncode != 0:
+            return _step_error("pandoc", step1)
+        _inject_css(html, css)
+        step2 = _run(runner, _engine_pdf_cmd(engine, html, out))
+        if step2.returncode != 0:
+            return _step_error(engine.name, step2)
+        return None
+    finally:
+        html.unlink(missing_ok=True)
+
+
+def _render_direct(
+    engine: Engine, src: Path, out: Path, css: Path | None, runner: Callable
+) -> str | None:
+    """Direct md-to-pdf pipeline (no pandoc). Returns an error string on
+    failure, or None on success."""
+    produced = src.with_suffix(".pdf")
+    step = _run(runner, _mdtopdf_cmd(src, css))
+    if step.returncode != 0:
+        return _step_error(engine.name, step)
+    if produced.resolve() != out.resolve() and produced.is_file():
+        shutil.move(str(produced), str(out))
+    return None
+
+
+def render(
+    md_path: str,
+    out_path: str | None = None,
+    *,
+    engine: Engine | None = None,
+    css_path: str | None = None,
+    runner: Callable | None = None,
+) -> RenderResult:
+    """Render ``md_path`` to a PDF, returning a :class:`RenderResult`.
+
+    ``runner`` is injectable so tests never shell out to a real engine; it
+    defaults to the module's current ``subprocess.run`` (resolved at call time,
+    so a monkeypatch of it is honored).
+    """
+    if runner is None:
+        runner = subprocess.run
+    src = Path(md_path)
+    if not src.is_file():
+        return RenderResult(rendered=False, error=f"file not found: {md_path}")
+
+    if engine is None:
+        engine = detect_engine()
+    if engine is None:
+        return RenderResult(
+            rendered=False, reason="no PDF engine available", install_hint=install_hint()
+        )
+
+    out = Path(out_path) if out_path else src.with_suffix(".pdf")
+    try:
+        out.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return RenderResult(rendered=False, engine=engine.name, error=str(exc))
+
+    css = Path(css_path) if css_path else default_css_path()
+
+    try:
+        pipeline = _render_pandoc if engine.kind == _PANDOC else _render_direct
+        err = pipeline(engine, src, out, css, runner)
+        if err is not None:
+            return _fail(engine.name, err)
+    except subprocess.TimeoutExpired:
+        return _fail(engine.name, f"{engine.name} timed out after {_TIMEOUT_SECONDS}s")
+    except OSError as exc:
+        return _fail(engine.name, str(exc))
+
+    if not out.is_file():
+        return _fail(engine.name, f"{engine.name} reported success but no PDF was produced")
+    return RenderResult(rendered=True, engine=engine.name, out_path=str(out))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="report_pdf.py",
+        description="Render a Markdown report to a styled PDF.",
+    )
+    parser.add_argument("path", help="path to the Markdown report (.md)")
+    parser.add_argument(
+        "--out", dest="out", default=None, help="output PDF path (default: next to source)"
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    src = Path(args.path)
+    engine = detect_engine() if src.is_file() else None
+    if engine is not None:
+        print(f"Rendering PDF via {engine.name}…")
+    result = render(args.path, args.out, engine=engine)
+
+    if result.rendered:
+        print(f"PDF written: {result.out_path} (engine: {result.engine})")
+        return 0
+    if result.error is not None:
+        print(f"PDF not rendered: {result.error}", file=sys.stderr)
+        return 1
+    # skip (no engine) — non-fatal, the report is safe
+    print(result.install_hint or result.reason or "PDF skipped.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/lib/review_agent_registry.py

@@ -0,0 +1,142 @@
+"""hooks/lib/review_agent_registry.py — shared *-review agent glob discovery (#1461).
+
+Both `scripts/check_review_agent_mcp_tools.py` (MCP tool-grant auditing) and
+`hooks/agent_dispatch_ledger.py` (the dispatch-ledger PreToolUse hook, #1461)
+need the same closed set of registered review-agent names: every
+`agents/*-review.md` file's stem. This module is the single extraction point
+so a hook never reaches into `scripts/` — the correct dependency direction is
+`scripts/` -> `hooks/lib/`, never the reverse (a hook must be import-safe
+without any `scripts/` module on its path).
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# This plugin's own marketplace-qualified prefix. A real Agent-tool dispatch
+# of one of this plugin's registered review agents, once installed, is named
+# "dev-team:<agent-name>" (e.g. "dev-team:doc-review") — the closed set below
+# is built from bare `agents/*-review.md` file stems, so an unstripped
+# qualified name never matches it (#1461 follow-up: this silently dropped
+# every dispatch's ledger record for the plugin's normal, installed
+# invocation form). A prefix for a DIFFERENT plugin is left untouched — it
+# is never one of this registry's own agents.
+_PLUGIN_PREFIX = "dev-team:"
+
+
+def strip_plugin_prefix(subagent_type: str) -> str:
+    """Normalize a dispatch's `subagent_type` to the bare agent name this
+    registry's closed set uses, stripping only this plugin's own
+    `dev-team:` qualifier."""
+    if subagent_type.startswith(_PLUGIN_PREFIX):
+        return subagent_type[len(_PLUGIN_PREFIX) :]
+    return subagent_type
+
+
+def find_review_agent_files(agents_dir: Path) -> list[Path]:
+    """Return the read-only review agent files (agents/*-review.md), sorted.
+
+    Glob-discovery logic extracted verbatim from
+    `scripts/check_review_agent_mcp_tools.py::find_review_agents` (#1461) —
+    behavior-identical, so existing callers/tests of that function regress
+    against this implementation unchanged.
+    """
+    return sorted(Path(agents_dir).glob("*-review.md"))
+
+
+def registered_review_agent_names(agents_dir: Path) -> frozenset[str]:
+    """Return the closed set of registered review-agent names (file stems).
+
+    This is the authoritative closed vocabulary `hooks/agent_dispatch_ledger.py`
+    checks an Agent-tool dispatch's `subagent_type` against before recording a
+    ledger event — a name outside this set is never a real review agent, and
+    is never written to the ledger, not even as a rejected/flagged entry.
+    """
+    return frozenset(path.stem for path in find_review_agent_files(agents_dir))
+
+
+def default_agents_dir() -> Path:
+    """The plugin's own `agents/` directory (#1904 item 3) — the single
+    source of truth every review-agent registry consumer resolves against,
+    never the caller's own project `cwd`.
+
+    Always `.resolve()`d: several call sites that once built this path by
+    hand (`scripts/check_agent_tool_mapping.py`,
+    `scripts/check_review_agent_mcp_tools.py`,
+    `skills/code-review/scripts/repo_invariants.py`,
+    `scripts/check_agent_scope.py`) previously did so without `.resolve()` —
+    a latent behavioral difference under a symlinked checkout — now fixed by
+    construction, since each delegates here instead of re-deriving its own
+    copy. Not yet exhaustive: `scripts/verify_tier.py` still derives its own
+    `_AGENTS_DIR` independently (its `_PLUGIN_ROOT` is already resolved via
+    `Path(__file__).resolve()`, so it does not carry the same symlink bug,
+    but it remains a duplicate resolution path this module has not yet
+    absorbed).
+    """
+    # hooks/lib/review_agent_registry.py -> hooks/lib -> hooks -> plugin root
+    # -> agents
+    return Path(__file__).resolve().parents[2] / "agents"
+
+
+def is_registered_review_lens(subagent_type: str) -> bool:
+    """True when `subagent_type` (raw, or plugin-qualified like
+    `dev-team:security-review`) names a registered `agents/*-review.md`
+    review lens.
+
+    Encapsulates the repeated three-step check — `strip_plugin_prefix` ->
+    read the registered review-agent set via `default_agents_dir()` ->
+    membership test — previously hand-rolled independently in
+    `hooks/agent_dispatch_ledger.py`, `hooks/lib/boundary_events.py`, and
+    `hooks/review_verdict_recorder.py` (backstop review finding, #2166 +
+    #2171 — this repo's own `hooks/lib/review_dispatch_ledger.py` module
+    docstring already applied the identical consolidation lesson to a
+    sibling predicate).
+
+    An unreadable registry (`read_registered_review_agent_names()` returns
+    `None`) collapses to `False`, matching every prior call site's own
+    "don't record"/"skip" posture exactly: a lost registry read only
+    narrows what counts as a registered review lens, never widens it.
+    """
+    if not subagent_type:
+        return False
+    name = strip_plugin_prefix(subagent_type)
+    registered = read_registered_review_agent_names(default_agents_dir())
+    return bool(registered) and name in registered
+
+
+def read_registered_review_agent_names(agents_dir: Path) -> frozenset[str] | None:
+    """Checked variant of `registered_review_agent_names()` that owns the
+    read-failure-vs-empty distinction (#1904 item 1) instead of forcing every
+    consumer to reinvent it.
+
+    Returns `None` on a read failure (a missing or unreadable `agents_dir`);
+    a genuine `frozenset()` on a successful read that legitimately finds zero
+    `*-review.md` files. The two states require OPPOSITE treatment depending
+    on which side of a corroboration check consumes them: for POSITIVE
+    evidence (e.g. "which agents dispatched"), a caller may safely collapse
+    `None` to an empty set — narrowing corroboration can only ever narrow,
+    never widen, what counts as a passing gate. For NEGATIVE evidence (e.g.
+    "which agents have an unsuperseded dispatch failure"), collapsing `None`
+    to empty would WIDEN the result instead — every genuine negative-evidence
+    entry would be filtered out by an empty "registered" set, producing an
+    all-clear indistinguishable from "provably none". See
+    `hooks/lib/review_gate_corroboration.py`'s own docstring for the full
+    account of this asymmetry.
+
+    Two failure modes are checked EXPLICITLY here, not left to an exception:
+    `registered_review_agent_names()` globs `agents_dir.glob("*-review.md")`,
+    and `Path.glob()` does not raise for either — it silently yields nothing
+    for a missing directory and swallows a permission error. Without the
+    explicit `is_dir()` check, a missing/unreadable `agents_dir` would
+    produce an empty `frozenset()`, not `None`, defeating the very
+    distinction this function's contract promises.
+    """
+    path = Path(agents_dir)
+    if not path.is_dir():
+        return None
+    try:
+        return registered_review_agent_names(path)
+    except Exception:  # noqa: BLE001 - caller decides how to fail closed for its own evidence direction
+        return None