poolprobe 1.0.0__py3-none-any.whl

poolprobe/cli.py

@@ -0,0 +1,1008 @@
+"""Command line surface: one report in, three renderers out, honest exit codes.
+
+Every subcommand ends in the same shape — measure, fold into ``Report``, hand it
+to the renderers — so the terminal, JSON and HTML views can never disagree about
+what happened. The commands differ only in what they measure and in which of the
+five prune guards they are allowed to act on.
+
+Exit codes are a cron contract::
+
+    0  nothing dead (or nothing that met every guard)
+    1  something dead / a fallback chain is broken
+    2  usage error, unreadable config, missing PyYAML
+    3  the gateway itself could not be reached or published an empty catalog
+  130  interrupted
+
+``1`` is deliberately burst-confirmed: with the default ``--attempts 5`` a model
+only reports dead after five consecutive failures inside one run, so a red exit
+is a finding, not weather.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+import sys
+import threading
+import time
+from argparse import Namespace
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import NoReturn
+
+from . import __version__, bench, chains, safewrite, taxonomy
+from .adapter import ConfigError, build_adapter
+from .probe import (
+    DEFAULT_MAX_TOKENS,
+    DEFAULT_PROMPT,
+    DEFAULT_TIMEOUT,
+    Gateway,
+    GatewayError,
+    list_models,
+    sweep,
+)
+from .report import (
+    VERDICT_STYLE,
+    Palette,
+    Prunable,
+    Report,
+    RunMeta,
+    render_html,
+    render_json,
+    render_terminal,
+    summarize_probes,
+)
+from .safewrite import write_atomic
+from .state import State
+
+__all__ = ["main", "build_parser", "selfcheck"]
+
+# --- exit codes -------------------------------------------------------------
+
+EXIT_OK = 0
+EXIT_DEAD = 1
+EXIT_USAGE = 2
+EXIT_GATEWAY = 3
+EXIT_INTERRUPT = 130
+
+#: A sweep is I/O-bound (five attempts, dozens of models); a bench contends
+#: inside the gateway, which is why ``bench`` keeps its own lower default.
+SWEEP_THREADS = 8
+#: Doctrine: one observation is not a verdict. Five attempts inside one run is
+#: the floor below which a red row means nothing.
+SWEEP_ATTEMPTS = 5
+#: Consecutive *runs* a model must stay dead before it becomes prunable.
+DEFAULT_STREAK_MIN = 2
+#: Above this many published models a ``ping`` stops listing names.
+LIST_LIMIT = 60
+#: Progress glyphs per stderr line.
+TICK_WIDTH = 40
+
+_SECRET_FLAGS = frozenset({"-k", "--api-key"})
+#: argv[0] is ``poolprobe`` for a console script but ``__main__.py`` under
+#: ``python -m``; the report echoes the program name, not the launcher file.
+_PROGRAM = "poolprobe"
+
+_EPILOG = """\
+examples:
+  poolprobe ping    --base-url http://127.0.0.1:8317/v1
+  poolprobe sweep   --base-url http://127.0.0.1:8317/v1 --attempts 5 --html out.html
+  poolprobe sweep   --base-url ... --state ~/.cache/poolprobe.json gpt-5.4 glm-5.3-flash
+  poolprobe bench   --base-url ... --repeat 3
+  poolprobe prune   --base-url ... --adapter cliproxy --config ~/.config/gateway.yaml
+  poolprobe chains  ~/.hermes/config.yaml
+  poolprobe selfcheck
+
+A run without --state has no memory: every fail streak reads 0, so `prune` can
+list candidates but nothing passes the streak guard. That is the safe default.
+"""
+
+
+def _die(message: str, code: int) -> NoReturn:
+    sys.stderr.write(f"poolprobe: error: {message}\n")
+    raise SystemExit(code)
+
+
+def _note(message: str) -> None:
+    sys.stderr.write(f"poolprobe: {message}\n")
+
+
+def _silence_pipes() -> None:
+    """``poolprobe sweep | head`` must not kill the run with a traceback."""
+    try:
+        sys.stdout.flush()
+    except (BrokenPipeError, ValueError):
+        pass
+    finally:
+        try:
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        except OSError:
+            pass
+
+
+# --- argument plumbing ------------------------------------------------------
+
+
+def _redacted_argv(argv: object = None) -> list:
+    """The command line as typed, with the bearer key masked.
+
+    Reports get pasted into issues and attached to posts; an argv echo is the
+    easiest secret in the whole tool to leak by accident.
+    """
+    items = list(sys.argv if argv is None else argv)
+    out: list = []
+    mask_next = False
+    for index, item in enumerate(items):
+        text = str(item)
+        if mask_next:
+            out.append("***")
+            mask_next = False
+            continue
+        if index == 0:
+            out.append(_PROGRAM)
+            continue
+        if text in _SECRET_FLAGS:
+            out.append(text)
+            mask_next = True
+            continue
+        if text.startswith("--api-key="):
+            out.append("--api-key=***")
+            continue
+        out.append(text)
+    return out
+
+
+def _common_parser() -> argparse.ArgumentParser:
+    """Options every measuring command shares.
+
+    Measurement defaults are ``None`` here and resolved in ``_measure_args``:
+    a sweep and a bench want different threads, token budgets and prompts, and
+    argparse cannot express "default depends on the subcommand".
+    """
+    common = argparse.ArgumentParser(add_help=False)
+
+    conn = common.add_argument_group("connection")
+    conn.add_argument(
+        "-u",
+        "--base-url",
+        metavar="URL",
+        default=os.environ.get("POOLPROBE_BASE_URL", ""),
+        help="OpenAI-compatible base URL, e.g. http://127.0.0.1:8317/v1 (env POOLPROBE_BASE_URL)",
+    )
+    conn.add_argument(
+        "-k",
+        "--api-key",
+        default=os.environ.get("POOLPROBE_API_KEY") or os.environ.get("OPENAI_API_KEY") or "",
+        help="bearer key (env POOLPROBE_API_KEY, then OPENAI_API_KEY)",
+    )
+    conn.add_argument(
+        "--adapter",
+        choices=("auto", "cliproxy", "generic"),
+        default="auto",
+        help="where model->provider attribution comes from; 'auto' reads --config when it "
+        "parses and degrades to read-only, 'cliproxy' demands it, 'generic' skips it",
+    )
+    conn.add_argument(
+        "--config",
+        metavar="PATH",
+        default="",
+        help="gateway config to attribute (and prune) against: cliproxy-style YAML",
+    )
+
+    meas = common.add_argument_group("measurement")
+    meas.add_argument(
+        "--threads",
+        type=int,
+        metavar="N",
+        help=f"parallel requests (sweep {SWEEP_THREADS}, bench {bench.DEFAULT_THREADS})",
+    )
+    meas.add_argument(
+        "--timeout",
+        type=float,
+        metavar="S",
+        help=f"per-request timeout in seconds (default {DEFAULT_TIMEOUT:g})",
+    )
+    meas.add_argument(
+        "--max-tokens",
+        type=int,
+        metavar="N",
+        help=f"token budget (sweep {DEFAULT_MAX_TOKENS}, bench {bench.DEFAULT_BENCH_MAX_TOKENS}); "
+        "a floor, not a cap — reasoning models spend it on thinking and answer EMPTY-LENGTH",
+    )
+    meas.add_argument("--prompt", help="override the probe prompt")
+
+    mem = common.add_argument_group("memory")
+    mem.add_argument(
+        "--state",
+        metavar="PATH",
+        default=os.environ.get("POOLPROBE_STATE", ""),
+        help="JSON history file for fail streaks (env POOLPROBE_STATE); without it nothing "
+        "can pass the streak guard, so `prune` only lists candidates",
+    )
+    mem.add_argument(
+        "--streak-min",
+        type=int,
+        default=DEFAULT_STREAK_MIN,
+        metavar="N",
+        help=f"consecutive dead runs required before a model is prunable (default {DEFAULT_STREAK_MIN})",
+    )
+    mem.add_argument(
+        "--protect",
+        action="append",
+        default=[],
+        metavar="MODEL",
+        help="never prune this model (repeatable, comma-separated); the base name of a "
+        "namespaced alias is matched too",
+    )
+
+    out = common.add_argument_group("output")
+    out.add_argument("--json", metavar="PATH", default="", help="also write the report as JSON")
+    out.add_argument("--html", metavar="PATH", default="", help="also write a self-contained HTML report")
+    out.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="ANSI policy; 'auto' honours NO_COLOR, FORCE_COLOR, TERM=dumb and isatty",
+    )
+    out.add_argument("-q", "--quiet", action="store_true", help="suppress the terminal report and progress glyphs")
+    return common
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="poolprobe",
+        description="Doctor for OpenAI-compatible LLM gateways: probe the pool, classify every "
+        "failure, and only then talk about pruning.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"poolprobe {__version__}",
+        help="print the version and exit",
+    )
+    common = _common_parser()
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    ping = sub.add_parser(
+        "ping",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="can the gateway be reached, and what does it publish?",
+        description="Reach the gateway, list the published catalog and break it down by provider. "
+        "No chat request is sent, so this is the cheapest possible liveness check.",
+    )
+    ping.set_defaults(func=cmd_ping)
+
+    p_sweep = sub.add_parser(
+        "sweep",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="probe every model (or the named ones) and classify the failures",
+        description="One burst-confirmed chat probe per model. Each result carries a verdict "
+        "(OK/EMPTY/EMPTY-LENGTH/ERR/TIMEOUT) and a kind (ALIVE/ALIVE-STARVED/PERMANENT/"
+        "TRANSIENT/CREDENTIAL/MODALITY/UNKNOWN); only PERMANENT is ever a prune candidate.",
+    )
+    p_sweep.add_argument("models", nargs="*", help="restrict the sweep to these models (default: the whole catalog)")
+    p_sweep.add_argument(
+        "--attempts",
+        type=int,
+        default=SWEEP_ATTEMPTS,
+        metavar="N",
+        help=f"burst size per model — the best answer wins (default {SWEEP_ATTEMPTS})",
+    )
+    p_sweep.add_argument("--gap", type=float, default=0.0, metavar="S", help="sleep between burst attempts")
+    p_sweep.set_defaults(func=cmd_sweep)
+
+    p_bench = sub.add_parser(
+        "bench",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="measure latency and throughput instead of liveness",
+        description="Throughput is reported only when the gateway's own usage block supplies a "
+        "token count; otherwise it is a lower bound or a dash. Never estimated from SSE chunk counts.",
+    )
+    p_bench.add_argument("models", nargs="*", help="restrict the bench to these models (default: the whole catalog)")
+    p_bench.add_argument("--repeat", type=int, default=1, metavar="N", help="samples per model; the median is reported")
+    p_bench.add_argument("--stream", action="store_true", help="stream the reply to measure time-to-first-token")
+    p_bench.set_defaults(func=cmd_bench)
+
+    p_prune = sub.add_parser(
+        "prune",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="list models that passed all five prune guards, and plan the config edit",
+        description="Five guards have to agree before a model is called prunable: a dead verdict, "
+        "kind PERMANENT, a fail streak of at least --streak-min runs, not in --protect, and not a "
+        "generation modality (image/video/tts models legitimately fail a chat probe). Without "
+        "--apply nothing on disk changes; the diff is shown either way.",
+    )
+    p_prune.add_argument("models", nargs="*", help="restrict the sweep to these models (default: the whole catalog)")
+    p_prune.add_argument(
+        "--attempts",
+        type=int,
+        default=SWEEP_ATTEMPTS,
+        metavar="N",
+        help=f"burst size per model — the best answer wins (default {SWEEP_ATTEMPTS})",
+    )
+    p_prune.add_argument("--gap", type=float, default=0.0, metavar="S", help="sleep between burst attempts")
+    p_prune.add_argument("--apply", action="store_true", help="write the planned edit (previous copy kept as .bak)")
+    p_prune.add_argument("--diff-out", metavar="PATH", default="", help="write the unified diff to PATH instead of only showing it")
+    p_prune.set_defaults(func=cmd_prune)
+
+    p_chains = sub.add_parser(
+        "chains",
+        parents=[common],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        help="validate agent fallback chains against the lane rules that read them",
+        description="A fallback chain that parses is not a fallback chain that runs. Bare strings, "
+        "rungs missing a field the lane requires, duplicates the runtime dedupes away, a rung equal "
+        "to its own primary, and keys nothing reads are all reported. Exit 1 when any chain has issues.",
+    )
+    p_chains.add_argument("path", help="agent config to read (YAML)")
+    p_chains.add_argument(
+        "--cross-check",
+        action="store_true",
+        help="also fetch the gateway catalog and flag rungs naming a model the upstream no longer serves",
+    )
+    p_chains.set_defaults(func=cmd_chains)
+
+    p_self = sub.add_parser(
+        "selfcheck",
+        help="run the offline gate: no network, no config, nothing written",
+        description="Exercises the prune guards, the report renderers, the argv redaction and the "
+        "measurement defaults. This is what CI runs.",
+    )
+    p_self.set_defaults(func=cmd_selfcheck)
+    return parser
+
+
+# --- shared helpers ---------------------------------------------------------
+
+
+def _palette(args: object) -> Palette:
+    pal = Palette.detect()
+    choice = str(getattr(args, "color", "auto") or "auto")
+    if choice == "always":
+        return dataclasses.replace(pal, color=True)
+    if choice == "never":
+        return dataclasses.replace(pal, color=False)
+    return pal
+
+
+class _Ticker:
+    """One glyph per finished request, on stderr, from worker threads.
+
+    Progress belongs on stderr so ``--json -`` style piping and the report itself
+    stay clean; the lock is real because ``on_result`` fires inside the pool.
+    """
+
+    def __init__(self, pal: Palette, width: int = TICK_WIDTH) -> None:
+        self._pal = pal
+        self._width = max(1, int(width))
+        self._lock = threading.Lock()
+        self._n = 0
+
+    def __call__(self, item: object) -> None:
+        verdict = getattr(item, "verdict", "") or (
+            taxonomy.OK if getattr(item, "ok", False) else taxonomy.ERR
+        )
+        glyph = self._pal.paint(self._pal.glyph(verdict), *VERDICT_STYLE.get(verdict, ("white",)))
+        with self._lock:
+            self._n += 1
+            sys.stderr.write(glyph)
+            if self._n % self._width == 0:
+                sys.stderr.write("\n")
+            sys.stderr.flush()
+
+    def close(self) -> None:
+        with self._lock:
+            if self._n and self._n % self._width:
+                sys.stderr.write("\n")
+            sys.stderr.flush()
+
+
+def _ticker(args: object, pal: Palette) -> "_Ticker | None":
+    if getattr(args, "quiet", False):
+        return None
+    try:
+        if not sys.stderr.isatty():
+            return None
+    except (AttributeError, ValueError):
+        return None
+    return _Ticker(pal)
+
+
+def _gateway(args: object) -> Gateway:
+    base = str(getattr(args, "base_url", "") or "").strip()
+    if not base:
+        _die("no gateway: pass --base-url URL or set POOLPROBE_BASE_URL", EXIT_USAGE)
+    return Gateway(base, api_key=str(getattr(args, "api_key", "") or ""))
+
+
+def _adapter(args: object, gateway: Gateway, warnings: list) -> object:
+    kind = str(getattr(args, "adapter", "auto") or "auto")
+    config = str(getattr(args, "config", "") or "").strip()
+    try:
+        # build_adapter treats None as "no config"; an empty string would become
+        # Path('.') and produce a "config not found: ." message that misleads.
+        return build_adapter(kind, gateway, Path(config).expanduser() if config else None)
+    except ConfigError as exc:
+        _die(str(exc), EXIT_USAGE)
+
+
+def _catalog(args: object, adapter: object, warnings: list) -> list:
+    named = list(getattr(args, "models", None) or [])
+    if named:
+        return list(dict.fromkeys(named))
+    try:
+        models = adapter.models()
+    except GatewayError as exc:
+        _die(f"gateway catalog failed: {exc}", EXIT_GATEWAY)
+    if not models:
+        # An empty pool would make every gate vacuously green — refuse it.
+        _die("gateway published an empty catalog — nothing to probe", EXIT_GATEWAY)
+    return list(models)
+
+
+def _attributions(adapter: object, models: list, warnings: list) -> dict:
+    try:
+        known = adapter.attribution_map()
+    except ConfigError as exc:
+        warnings.append(f"attribution unavailable, provider column will be empty: {exc}")
+        return {}
+    return {name: known[name] for name in models if name in known}
+
+
+def _attach_providers(results: list, attrs: dict) -> None:
+    """``sweep`` cannot know providers; the adapter can. Fill the gap in place."""
+    for item in results:
+        attr = attrs.get(item.model)
+        if attr is not None and attr.provider and not getattr(item, "provider", ""):
+            item.provider = attr.provider
+
+
+def _protect(args: object) -> set:
+    out: set = set()
+    for chunk in getattr(args, "protect", None) or []:
+        for name in str(chunk).split(","):
+            name = name.strip()
+            if name:
+                out.add(name)
+    return out
+
+
+def _measure_args(args: object, bench_mode: bool = False) -> tuple:
+    threads = getattr(args, "threads", None) or (bench.DEFAULT_THREADS if bench_mode else SWEEP_THREADS)
+    timeout = getattr(args, "timeout", None) or DEFAULT_TIMEOUT
+    max_tokens = getattr(args, "max_tokens", None) or (
+        bench.DEFAULT_BENCH_MAX_TOKENS if bench_mode else DEFAULT_MAX_TOKENS
+    )
+    prompt = getattr(args, "prompt", None) or (bench.DEFAULT_BENCH_PROMPT if bench_mode else DEFAULT_PROMPT)
+    return int(threads), float(timeout), int(max_tokens), str(prompt)
+
+
+def _load_state(args: object, warnings: list) -> "State | None":
+    path = str(getattr(args, "state", "") or "").strip()
+    if not path:
+        return None
+    try:
+        state = State(path).load()
+    except OSError as exc:  # load() is fail-open by design, but the open itself can still raise
+        warnings.append(f"state not readable, starting empty: {exc}")
+        return State(path)
+    warnings.extend(state.warnings)
+    return state
+
+
+def _save_state(state: "State | None", warnings: list) -> int:
+    if state is None:
+        return 0
+    try:
+        state.save()
+    except OSError as exc:
+        warnings.append(f"state not saved: {exc}")
+    return int(state.run_count)
+
+
+def _streak_map(state: "State | None", results: list) -> dict:
+    if state is None:
+        return {}
+    out: dict = {}
+    for item in results:
+        entry = state.get(item.model)
+        if entry is not None:
+            out[item.model] = (int(entry.fail_streak), int(entry.ok_streak))
+    return out
+
+
+def _prunable_rows(results: list, state: object, args: object, attrs: dict) -> list:
+    """The five guards, applied in one place so report and prune cannot drift."""
+    streak_min = int(getattr(args, "streak_min", DEFAULT_STREAK_MIN) or 0)
+    protect = _protect(args)
+    rows: list = []
+    for item in results:
+        streak = int(state.streak(item.model)) if state is not None else 0
+        if not taxonomy.prunable(item.model, item.verdict, item.kind, streak, streak_min, protect):
+            continue
+        attr = attrs.get(item.model)
+        rows.append(
+            Prunable(
+                model=item.model,
+                kind=item.kind,
+                verdict=item.verdict,
+                streak=streak,
+                attempts=int(getattr(item, "attempts", 1) or 1),
+                provider=(attr.provider if attr is not None and attr.provider else getattr(item, "provider", "")),
+                note=item.note,
+                advice=item.advice,
+            )
+        )
+    return rows
+
+
+def _meta(args: object, command: str, **kwargs) -> RunMeta:
+    """Build the header. Every field is read defensively so an empty
+    ``Namespace()`` works — the selfcheck depends on that."""
+    started = kwargs.get("started")
+    gateway = kwargs.get("gateway")
+    adapter = kwargs.get("adapter")
+    warnings = kwargs.get("warnings") or []
+    notes = kwargs.get("notes") or []
+    return RunMeta(
+        command=command,
+        gateway=str(getattr(gateway, "root", "") or "") if gateway is not None else "",
+        adapter=str(adapter.describe()) if adapter is not None else "",
+        generated_at=datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+        duration_s=round(time.monotonic() - float(started), 2) if started is not None else 0.0,
+        pool=int(kwargs.get("pool") or 0),
+        run_count=int(kwargs.get("run_count") or 0),
+        state_path=str(getattr(args, "state", "") or ""),
+        attempts=int(getattr(args, "attempts", 1) or 1),
+        threads=int(kwargs.get("threads") or 1),
+        timeout=float(kwargs.get("timeout") or 0.0),
+        max_tokens=int(kwargs.get("max_tokens") or 0),
+        stream=bool(kwargs.get("stream", False)),
+        repeat=int(kwargs.get("repeat", 1) or 1),
+        argv=_redacted_argv(),
+        # Kept as the live lists, not copies: commands append to warnings/notes
+        # after the report exists and the renderers must see the final state.
+        warnings=list(warnings) if not isinstance(warnings, list) else warnings,
+        notes=list(notes) if not isinstance(notes, list) else notes,
+        version=__version__,
+    )
+
+
+def _emit(report: Report, args: object, *, dead: bool) -> int:
+    """Terminal always (unless --quiet), JSON/HTML only when a path was given."""
+    if not getattr(args, "quiet", False):
+        try:
+            sys.stdout.write(render_terminal(report, palette=_palette(args)) + "\n")
+            sys.stdout.flush()
+        except BrokenPipeError:
+            _silence_pipes()
+            return EXIT_OK
+    for flag, renderer in (("json", render_json), ("html", render_html)):
+        path = str(getattr(args, flag, "") or "")
+        if not path:
+            continue
+        try:
+            write_atomic(path, renderer(report) + "\n", backup=False)
+        except OSError as exc:
+            _note(f"could not write {path}: {exc}")
+            continue
+        _note(f"wrote {path}")
+    return EXIT_DEAD if dead else EXIT_OK
+
+
+# --- commands ---------------------------------------------------------------
+
+
+def cmd_ping(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    warnings: list = []
+    notes: list = []
+    started = time.monotonic()
+    gateway = _gateway(args)
+    adapter = _adapter(args, gateway, warnings)
+    try:
+        models = list_models(gateway, timeout=float(getattr(args, "timeout", None) or 20.0))
+    except GatewayError as exc:
+        _die(f"gateway unreachable: {exc}", EXIT_GATEWAY)
+    notes.append(f"{len(models)} model(s) published")
+    attrs = _attributions(adapter, models, warnings)
+    per_provider: dict = {}
+    for name in models:
+        attr = attrs.get(name)
+        if attr is not None and attr.provider:
+            per_provider[attr.provider] = per_provider.get(attr.provider, 0) + 1
+    if per_provider:
+        ranked = sorted(per_provider.items(), key=lambda kv: (-kv[1], kv[0]))
+        notes.append("providers: " + ", ".join(f"{provider}\u00d7{count}" for provider, count in ranked))
+    disabled = sorted(name for name, attr in attrs.items() if attr.disabled)
+    if disabled:
+        notes.append(f"{len(disabled)} configured model(s) marked disabled: {', '.join(disabled[:8])}")
+    if len(models) <= LIST_LIMIT:
+        notes.append("models: " + ", ".join(models))
+    else:
+        notes.append(f"models: {len(models)} published, too many to list here \u2014 run `poolprobe sweep` for the table")
+    report = Report()
+    report.meta = _meta(
+        args, "ping", gateway=gateway, adapter=adapter, started=started,
+        pool=len(models), warnings=warnings, notes=notes,
+    )
+    return _emit(report, args, dead=False)
+
+
+def cmd_sweep(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    warnings: list = []
+    notes: list = []
+    started = time.monotonic()
+    gateway = _gateway(args)
+    adapter = _adapter(args, gateway, warnings)
+    models = _catalog(args, adapter, warnings)
+    attrs = _attributions(adapter, models, warnings)
+    threads, timeout, max_tokens, prompt = _measure_args(args)
+    tick = _ticker(args, _palette(args))
+    results = sweep(
+        gateway,
+        models,
+        threads=threads,
+        timeout=timeout,
+        max_tokens=max_tokens,
+        prompt=prompt,
+        attempts=int(args.attempts),
+        gap_s=float(args.gap),
+        on_result=tick,
+    )
+    if tick is not None:
+        tick.close()
+    _attach_providers(results, attrs)
+
+    state = _load_state(args, warnings)
+    if state is not None:
+        stats = state.record(results, full_sweep=not getattr(args, "models", None))
+        if stats.dropped:
+            notes.append(
+                f"dropped {len(stats.dropped)} model(s) unseen in this full sweep: "
+                f"{', '.join(sorted(stats.dropped)[:8])}"
+            )
+    run_count = _save_state(state, warnings)
+
+    report = Report(
+        probes=results,
+        prunable=_prunable_rows(results, state, args, attrs),
+        streaks=_streak_map(state, results),
+        attribution={name: attr.as_dict() for name, attr in attrs.items()},
+    )
+    summary = _summarize(results)
+    report.meta = _meta(
+        args, "sweep", gateway=gateway, adapter=adapter, started=started,
+        threads=threads, timeout=timeout, max_tokens=max_tokens,
+        pool=len(models), run_count=run_count, warnings=warnings, notes=notes,
+    )
+    return _emit(report, args, dead=bool(summary["dead"]))
+
+
+def cmd_bench(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    warnings: list = []
+    notes: list = []
+    started = time.monotonic()
+    gateway = _gateway(args)
+    adapter = _adapter(args, gateway, warnings)
+    models = _catalog(args, adapter, warnings)
+    attrs = _attributions(adapter, models, warnings)
+    threads, timeout, max_tokens, prompt = _measure_args(args, bench_mode=True)
+    tick = _ticker(args, _palette(args))
+    results = bench.bench_many(
+        gateway,
+        models,
+        threads=threads,
+        prompt=prompt,
+        max_tokens=max_tokens,
+        timeout=timeout,
+        stream=bool(getattr(args, "stream", False)),
+        repeat=int(getattr(args, "repeat", 1) or 1),
+        providers={name: attr.provider for name, attr in attrs.items()},
+        on_result=tick,
+    )
+    if tick is not None:
+        tick.close()
+
+    report = Report(
+        bench=results,
+        bench_summary=bench.summarize(results),
+        attribution={name: attr.as_dict() for name, attr in attrs.items()},
+    )
+    summary = report.bench_summary
+    exact = int(summary.get("with_exact_tokens") or 0)
+    if exact < len(results):
+        notes.append(
+            f"{len(results) - exact} of {len(results)} model(s) gave no usable token count \u2014 "
+            "their throughput is a lower bound or a dash, not a measurement"
+        )
+    report.meta = _meta(
+        args, "bench", gateway=gateway, adapter=adapter, started=started,
+        threads=threads, timeout=timeout, max_tokens=max_tokens,
+        stream=bool(getattr(args, "stream", False)), repeat=int(getattr(args, "repeat", 1) or 1),
+        pool=len(models), warnings=warnings, notes=notes,
+    )
+    return _emit(report, args, dead=bool(int(summary.get("dead") or 0)))
+
+
+def cmd_prune(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    warnings: list = []
+    notes: list = []
+    started = time.monotonic()
+    gateway = _gateway(args)
+    adapter = _adapter(args, gateway, warnings)
+    models = _catalog(args, adapter, warnings)
+    attrs = _attributions(adapter, models, warnings)
+    threads, timeout, max_tokens, prompt = _measure_args(args)
+
+    state = _load_state(args, warnings)
+    if state is None:
+        warnings.append(
+            "no --state path: every fail streak reads 0, so nothing can pass the streak guard \u2014 "
+            "pass --state PATH across runs to make prune decisive"
+        )
+
+    tick = _ticker(args, _palette(args))
+    results = sweep(
+        gateway,
+        models,
+        threads=threads,
+        timeout=timeout,
+        max_tokens=max_tokens,
+        prompt=prompt,
+        attempts=int(args.attempts),
+        gap_s=float(args.gap),
+        on_result=tick,
+    )
+    if tick is not None:
+        tick.close()
+    _attach_providers(results, attrs)
+
+    if state is not None:
+        state.record(results, full_sweep=not getattr(args, "models", None))
+    run_count = _save_state(state, warnings)
+    rows = _prunable_rows(results, state, args, attrs)
+
+    report = Report(
+        probes=results,
+        prunable=rows,
+        streaks=_streak_map(state, results),
+        attribution={name: attr.as_dict() for name, attr in attrs.items()},
+    )
+    summary = _summarize(results)
+
+    if not rows:
+        notes.append("nothing passed all five guards \u2014 no edit planned")
+    elif not getattr(adapter, "removable", False):
+        warnings.append(
+            f"adapter {getattr(adapter, 'name', '?')!r} is read-only: {len(rows)} candidate(s) listed, "
+            "config not touched (use --adapter cliproxy --config PATH)"
+        )
+    else:
+        _plan_edit(args, adapter, rows, report, warnings, notes)
+
+    report.meta = _meta(
+        args, "prune", gateway=gateway, adapter=adapter, started=started,
+        threads=threads, timeout=timeout, max_tokens=max_tokens,
+        pool=len(models), run_count=run_count, warnings=warnings, notes=notes,
+    )
+    return _emit(report, args, dead=bool(summary["dead"]))
+
+
+def _plan_edit(args: Namespace, adapter: object, rows: list, report: Report, warnings: list, notes: list) -> None:
+    """Turn candidates into a text-surgical edit plan; write only on --apply."""
+    try:
+        plan = adapter.plan_removal([row.model for row in rows])
+    except ConfigError as exc:
+        warnings.append(f"no edit planned: {exc}")
+        return
+    report.diff = plan.diff()
+    report.edit_path = str(plan.path)
+    report.edit_removed = list(plan.removed)
+    report.edit_not_found = list(plan.not_found)
+    warnings.extend(plan.warnings)
+    if not plan.changed:
+        warnings.append("planned edit is a no-op \u2014 no model entry matched in the config text")
+        return
+    if getattr(args, "apply", False):
+        try:
+            write_atomic(plan.path, plan.after)
+        except OSError as exc:
+            warnings.append(f"apply failed, config untouched: {exc}")
+            return
+        notes.append(
+            f"applied: removed {len(plan.removed)} model entr"
+            f"{'y' if len(plan.removed) == 1 else 'ies'} from {plan.path} (previous copy kept as .bak)"
+        )
+        return
+    notes.append("dry run: nothing written \u2014 re-run with --apply to make this edit")
+    diff_out = str(getattr(args, "diff_out", "") or "")
+    if diff_out:
+        try:
+            write_atomic(diff_out, plan.diff(), backup=False)
+        except OSError as exc:
+            warnings.append(f"could not write {diff_out}: {exc}")
+        else:
+            _note(f"wrote {diff_out}")
+
+
+def cmd_chains(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    warnings: list = []
+    notes: list = []
+    started = time.monotonic()
+    gateway = None
+    adapter = None
+    live = None
+    if getattr(args, "cross_check", False):
+        gateway = _gateway(args)
+        adapter = _adapter(args, gateway, warnings)
+        try:
+            live = set(adapter.models())
+        except GatewayError as exc:
+            warnings.append(f"cross-check skipped, catalog unavailable: {exc}")
+    try:
+        found = chains.validate_file(Path(args.path).expanduser(), live_models=live)
+    except ConfigError as exc:
+        _die(str(exc), EXIT_USAGE)
+    broken = [chain for chain in found if chain.get("issues")]
+    if not found:
+        notes.append(f"no fallback chains found in {args.path}")
+    elif not broken:
+        notes.append(f"{len(found)} chain(s) clean")
+    else:
+        # A finding, not a footnote: warnings render loud, notes render dim.
+        warnings.append(f"{len(broken)} of {len(found)} chain(s) carry issues")
+    report = Report(chains=found)
+    report.meta = _meta(
+        args, "chains", gateway=gateway, adapter=adapter, started=started,
+        warnings=warnings, notes=notes,
+    )
+    return _emit(report, args, dead=bool(broken))
+
+
+def cmd_selfcheck(args: Namespace, parser: argparse.ArgumentParser) -> int:
+    try:
+        selfcheck()
+    except AssertionError as exc:
+        _die(f"selfcheck failed: {exc}", EXIT_DEAD)
+    except ConfigError as exc:
+        _die(f"selfcheck failed: {exc}", EXIT_DEAD)
+    sys.stdout.write("poolprobe selfcheck ok\n")
+    return EXIT_OK
+
+
+def _summarize(results: list) -> dict:
+    return summarize_probes(results)
+
+
+# --- offline gate -----------------------------------------------------------
+
+
+def selfcheck() -> None:
+    """Assert-based gate with no network, no config file and no state on disk.
+
+    Covers the two places this module owns logic the renderers do not: the prune
+    guards (a report that says prunable while the prune cycle removes something
+    else is the worst failure mode this tool has) and the header plumbing.
+    """
+    from .probe import ProbeResult
+
+    chains.selfcheck()
+    safewrite.selfcheck()
+
+    class _StubState:
+        def __init__(self, streak: int) -> None:
+            self._streak = int(streak)
+
+        def streak(self, model: str) -> int:
+            return self._streak
+
+    def _row(model: str, verdict: str, kind: str, note: str = "note") -> ProbeResult:
+        return ProbeResult(model=model, verdict=verdict, kind=kind, note=note)
+
+    dead = _row("dead-model", taxonomy.ERR, taxonomy.PERMANENT)
+    alive = _row("live-model", taxonomy.OK, taxonomy.ALIVE)
+    starved = _row("thinker", taxonomy.EMPTY_LENGTH, taxonomy.ALIVE_STARVED)
+    transient = _row("flaky", taxonomy.ERR, taxonomy.TRANSIENT)
+    painter = _row("some-image-model", taxonomy.ERR, taxonomy.PERMANENT)
+
+    strict = Namespace(streak_min=DEFAULT_STREAK_MIN, protect=[])
+    picked = [row.model for row in _prunable_rows([dead, alive, starved, transient, painter], _StubState(3), strict, {})]
+    assert picked == ["dead-model"], picked
+    assert not _prunable_rows([dead], _StubState(1), strict, {}), "streak 1 must not clear streak_min 2"
+    assert not _prunable_rows([dead], None, strict, {}), "no state means no streak means no prune"
+    assert not _prunable_rows([alive, starved, transient], _StubState(9), strict, {}), "only PERMANENT is prunable"
+    assert not _prunable_rows([painter], _StubState(9), strict, {}), "generation modalities are never prunable"
+
+    guarded = Namespace(streak_min=DEFAULT_STREAK_MIN, protect=["dead-model"])
+    assert not _prunable_rows([dead], _StubState(9), guarded, {}), "--protect outranks a perfect streak"
+    namespaced = _row("Lite/dead-model", taxonomy.ERR, taxonomy.PERMANENT)
+    assert not _prunable_rows([namespaced], _StubState(9), guarded, {}), "protect must match the base name too"
+    comma = Namespace(streak_min=1, protect=["a, b ,, c"])
+    assert _protect(comma) == {"a", "b", "c"}, _protect(comma)
+
+    rows = _prunable_rows([dead], _StubState(4), Namespace(streak_min=1, protect=[]), {})
+    assert len(rows) == 1 and rows[0].streak == 4 and rows[0].verdict == taxonomy.ERR, rows
+
+    # Header plumbing on an empty Namespace: no attribute may be assumed present.
+    meta = _meta(Namespace(), "selfcheck")
+    assert meta.version == __version__ and meta.command == "selfcheck", meta
+    assert meta.stamp(), "a report without a timestamp is undatable"
+
+    masked = _redacted_argv(["/usr/bin/poolprobe", "sweep", "-k", "sk-live-123", "--api-key=sk-x", "-u", "http://h/v1"])
+    assert masked[0] == "poolprobe" and "sk-live-123" not in " ".join(masked), masked
+    assert "sk-x" not in " ".join(masked) and masked.count("***") == 1, masked
+    # ``python -m poolprobe`` sets argv[0] to __main__.py; the echo must not leak it.
+    assert _redacted_argv(["/x/poolprobe/__main__.py", "ping"])[0] == "poolprobe"
+
+    # A sweep and a bench must not share measurement defaults.
+    sweep_args = _measure_args(Namespace(), bench_mode=False)
+    bench_args = _measure_args(Namespace(), bench_mode=True)
+    assert sweep_args[0] == SWEEP_THREADS and bench_args[0] == bench.DEFAULT_THREADS, (sweep_args, bench_args)
+    assert sweep_args[2] == DEFAULT_MAX_TOKENS and bench_args[2] == bench.DEFAULT_BENCH_MAX_TOKENS, (sweep_args, bench_args)
+    pinned = _measure_args(Namespace(threads=2, timeout=5.0, max_tokens=9, prompt="hi"))
+    assert pinned == (2, 5.0, 9, "hi"), pinned
+
+    # All three renderers must accept both a probe report and a chains-only one.
+    probe_report = Report(probes=[dead, alive], prunable=rows, streaks={"dead-model": (4, 0)})
+    probe_report.meta = _meta(Namespace(), "sweep", warnings=["a warning"], notes=["a note"])
+    chain_report = Report(
+        chains=[
+            {"label": "main", "rungs": ["p/m"], "issues": []},
+            {"label": "aux:x", "rungs": ["bare"], "issues": ["rung 1 is a bare str"]},
+        ]
+    )
+    chain_report.meta = _meta(Namespace(), "chains")
+    for report in (probe_report, chain_report):
+        for text in (render_terminal(report, palette=Palette(color=False)), render_json(report), render_html(report)):
+            assert text.strip(), "renderer produced an empty document"
+        assert "poolprobe" in render_html(report)
+    terminal = render_terminal(probe_report, palette=Palette(color=False))
+    assert "dead-model" in terminal and "live-model" in terminal, terminal
+    assert "a warning" in terminal and "a note" in terminal, terminal
+    painted = render_terminal(probe_report, palette=Palette(color=True))
+    assert "\033[" in painted, "colour policy ignored an explicit palette"
+    assert "\033[" not in render_terminal(probe_report, palette=Palette(color=False))
+
+    assert len({EXIT_OK, EXIT_DEAD, EXIT_USAGE, EXIT_GATEWAY, EXIT_INTERRUPT}) == 5
+    assert _palette(Namespace(color="always")).color is True
+    assert _palette(Namespace(color="never")).color is False
+
+
+# --- entry point ------------------------------------------------------------
+
+
+def main(argv: "list | None" = None) -> int:
+    parser = build_parser()
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if not raw:
+        parser.print_help(sys.stderr)
+        return EXIT_USAGE
+    args = parser.parse_args(raw)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help(sys.stderr)
+        return EXIT_USAGE
+    try:
+        return int(func(args, parser))
+    except KeyboardInterrupt:
+        sys.stderr.write("\npoolprobe: interrupted\n")
+        return EXIT_INTERRUPT
+    except BrokenPipeError:
+        _silence_pipes()
+        return EXIT_OK
+    except ConfigError as exc:
+        _die(str(exc), EXIT_USAGE)
+    except GatewayError as exc:
+        _die(str(exc), EXIT_GATEWAY)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())