cli-agent-runner 0.2.16__tar.gz → 0.2.18__tar.gz

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/.github/workflows/ci.yml

@@ -92,7 +92,14 @@ jobs:
         # `| tail` would swallow the exit code and let dead code through.
         run: vulture
       - name: tests with coverage
-        run: pytest -q --ignore=tests/e2e --ignore=tests/literate --cov --cov-report=xml --cov-report=term
+        # Two passes so `serial` tests (install process-wide signal handlers /
+        # self-signals -- unsafe to share an xdist worker process) still run
+        # every time: parallel set + serial set == the full suite, mirroring
+        # ./build.sh test. pytest-cov 7.x auto-combines worker coverage data.
+        run: |
+          pytest -q --ignore=tests/e2e --ignore=tests/literate \
+            -n auto --dist worksteal -m "not serial" --cov --cov-report=xml --cov-report=term
+          pytest -q --ignore=tests/e2e --ignore=tests/literate -m serial --cov --cov-append --cov-report=xml --cov-report=term
       - name: docs CI gate
         run: |
           python -m agent_runner._docgen

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/.vulture-whitelist.py

@@ -13,6 +13,17 @@ log_dir
 offsets
 buffer
 
+# agent_runner._round_outcome.RoundOutcome
+mem_terminated
+usage_capable
+newest_usage_ts
+newest_substrate_before_ts
+latest_transient_per_agent
+ran_agent
+usage_capable_by_agent
+newest_usage_ts_by_agent
+backoff_exponent_by_agent
+
 # agent_runner.agent_runtime.RunResult
 exit_code
 duration_s

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.18] - 2026-09-08
+
+### Added
+- Cgroup pressure spine: `round_cgroup_memory` emits once per round (when this process's cgroup has a finite `memory.max`) with peak `memory.current`/`memory.swap.current` and `memory.events` counter deltas over the round — pressure becomes visible before it trips a give-up verdict.
+- `round_oom_killed`: a pointer-only event (never round-log content) when the kernel cgroup-OOM-kills a round; the round still exits 137 and counts toward the crash streak exactly as before — this only names the cause.
+- `host_cgroup_memory_limit` gains four advisory fields (`swap_total_bytes`, `swap_cap_pct`, `memory_high`, `advisory`) computed once at serve startup, plus a swap-plausibility guard on the cgroup-defer decision.
+- Docs: a real-RAM ledger, a zram worked example, and a commented `# MemoryHigh` hint (with the PSI-floor interaction warning).
+
+### Fixed
+- Per-agent no-progress verdict: a usageless round on a never-emits-usage CLI is no longer misread as stalled in a mixed `[phases]` config.
+- Fail-open hardening: the monitor no longer crashes on the stop/classify path (an emit error, a poisoned epoch field, or an unreapable round now degrade instead of raising).
+- `kill` now escalates SIGTERM to SIGKILL under systemd-user after the grace window, matching the docs.
+
+### Changed
+- Plugin discovery scans `entry_points.txt` directly with a metadata parity fallback, ahead of 0.3's group growth.
+- Internal cleanup: `RoundOutcome` carved into `_round_outcome`, constants single-sourced, lazy `hashlib`/`zoneinfo` behind an import-footprint gate, a tenet-3 price-blind invariant, plus test-speed work (parallel gate + faster inner loop).
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change; `peek --json` gains the two new event kinds above, existing kinds unchanged.
+
+See `docs/migrations/0.2.md`.
+
+## [0.2.17] - 2026-09-05
+
+### Changed
+- Internal refactor ("round-outcome unification"): per-round classification now does one events-tail scan per round (was up to three), the give-up decision is unified behind a single `post_round_verdicts` (precedence and exit codes `78`/`70`/`71`/`75` unchanged), and the `_serve_round`↔`serve_cmd` import cycle is removed. Behavior-preserving.
+- `round_mem_critical_sample` is now capped at `2 × mem_critical_consecutive_samples` emits per critical episode (any non-critical tick resets it), so a host stuck under sustained pressure no longer writes that calibration event unbounded for a whole round.
+
+### Fixed
+- Auto-stop no longer records `monitor_auto_stop_failed` for a stop that actually succeeds: under load a round can outlast the stop-confirmation window while draining, which was mis-reported as a failure. The monitor now recognizes a still-draining round and records the real outcome (triggered or failed) once it resolves on the next poll, instead of a false failure.
+
+### Notes
+- Not breaking: no `agent-runner migrate`, no systemd unit change, no new event kinds, `peek --json` schema unchanged. The only non-fix behavior change is the bounded `round_mem_critical_sample` above.
+
 ## [0.2.16] - 2026-09-05
 
 ### Added

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/CONTRIBUTING.md

@@ -105,7 +105,10 @@ drifts.
 
 ## Tests
 
-- Unit + integration: `pytest -q --ignore=tests/e2e --ignore=tests/literate`
+- Unit + integration (parallel gate): `./build.sh test` — pytest-xdist
+  (`-n $AR_TEST_JOBS`, default `auto`) plus a serial pass for tests that
+  install process-wide signal handlers. Never set `AR_TEST_JOBS` above 2 on a
+  constrained host (e.g. a 462MB Pi).
 - Literate quickstart: `./build.sh literate`
 - Pi e2e (opt-in): `AGENT_RUNNER_E2E_PI=1 pytest tests/e2e/` (needs a `pi`
   ssh alias; not run in CI).

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.16
+Version: 0.2.18
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme
@@ -27,6 +27,8 @@ Requires-Python: >=3.11
 Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Requires-Dist: vulture>=2.13; extra == 'dev'

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/README.zh.md

@@ -10,7 +10,7 @@ supervisor 重启 —— 这是核心模式。中间穿插一组防御，避开
 
 三层，每层都能独立运行，上层都是可选的：`round` 跑一次 agent 跑完即退；
 `serve` 捕获信号循环拉起 round；`monitor` 检测器 + 告警，critical 时自动停服
-（本机或 ssh 远程）。
+（本机）。
 
 ## 安装
 

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/agent_runner/__init__.py

@@ -27,16 +27,31 @@ def _load_plugins_from_group(group: str) -> None:
 
     Called at package import. A broken plugin must not crash the supervisor;
     each failure surfaces as a ``UserWarning``.
+
+    Discovery goes through the ``entry_points.txt`` scanner (cheaper than a
+    fresh ``importlib.metadata.entry_points()`` scan per group per process;
+    see ``_plugin_scan``), with a hard fallback to ``importlib.metadata`` on
+    any parse failure. Loading a plugin means only importing its module and
+    resolving its attribute — same as ``EntryPoint.load()`` — since every
+    built-in plugin registers itself as a module-top side effect (documented
+    in docs/plugins.md); this loader never instantiates or calls the target.
     """
+    import importlib
+    import sys
     import warnings
-    from importlib.metadata import entry_points
 
-    for ep in entry_points(group=group):
+    from agent_runner._plugin_scan import scan_entry_points
+
+    for name, value in scan_entry_points(sys.path, group):
         try:
-            ep.load()
+            module_path, _, attr_path = value.partition(":")
+            mod = importlib.import_module(module_path)
+            target = mod
+            for attr in filter(None, attr_path.split(".")):
+                target = getattr(target, attr)
         except Exception as e:
             warnings.warn(
-                f"failed to load {group} plugin {ep.name!r}: {e}",
+                f"failed to load {group} plugin {name!r}: {e}",
                 stacklevel=3,
             )
 
@@ -80,7 +95,7 @@ def apply_plugin_disable(names: list[str]) -> None:
     registered plugin (typo catcher; tolerates cross-env config drift).
 
     Plugin packages still load at import time — this removes from the registries
-    that the runner and peek consult. Side effects from ep.load() (module-level
+    that the runner and peek consult. Side effects from loading (module-level
     imports, etc.) have already happened by the time this runs.
 
     Known limitation: vcs_state._PLUGIN_OWNED_PATHS lacks per-plugin name

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/agent_runner/_emit.py

@@ -25,12 +25,14 @@ __all__ = [
     "emit_mem_loop_persistent",
     "emit_mem_pressure_deferred_to_cgroup",
     "emit_rate_limit_stop",
+    "emit_round_cgroup_memory",
     "emit_round_deferred",
     "emit_round_grace_extended",
     "emit_round_grace_kill",
     "emit_round_logs_prune_deferred",
     "emit_round_mem_critical_sample",
     "emit_round_mem_terminated",
+    "emit_round_oom_killed",
     "emit_round_progress",
     "emit_round_resumed",
     "emit_round_substrate_after",
@@ -296,18 +298,28 @@ def emit_round_mem_terminated(
 def emit_round_mem_critical_sample(
     log_dir: Path, *, round_num: int, consecutive: int, context: dict
 ) -> None:
-    """Emit on EACH critical host_health sample inside _spawn_round's mid-round
-    hard floor -- deliberately NOT deduped (unlike round_mem_terminated): the
-    point is calibration visibility into near-misses, so an operator watching
-    the event stream sees the critical_streak build (1, 2, ...) even on ticks
-    that never reach the terminate threshold (a healthy tick resets it before
-    3-in-a-row). ``context`` carries the same Pressure.context numbers as
+    """Emit on each critical host_health sample inside _spawn_round's mid-round
+    hard floor, up to the per-episode cap (0.2.17, below) -- unlike
+    round_mem_terminated (deduped to once-per-episode), this fires on every
+    critical tick within that cap: the point is calibration visibility into
+    near-misses, so an operator watching the event stream sees the
+    critical_streak build (1, 2, ...) even on ticks that never reach the
+    terminate threshold (a healthy tick resets it before 3-in-a-row).
+    ``context`` carries the same Pressure.context numbers as
     round_mem_terminated. Fires only during critical pressure -- never during
     warning/healthy -- so it adds no normal-operation noise, including while
     ``defer_to_cgroup`` steps back from terminating (the streak/context is
     still useful calibration there; this event stays scoped to the
     sample-level signal, distinct from mem_pressure_deferred_to_cgroup's
-    once-per-episode terminate-vs-defer notice)."""
+    once-per-episode terminate-vs-defer notice).
+
+    0.2.17: the caller caps this at ``2 * mem_critical_consecutive_samples``
+    consecutive ticks (1..6 at the default 3) -- a sustained-critical
+    don't-terminate run (cgroup-defer, or the off switch) would otherwise
+    write one event per ~10s tick for up to a whole ``round_timeout_s`` on a
+    permanently-deferred/off host. The cap is per streak-episode, not a
+    lifetime limit: any non-critical tick still resets the streak to 0, and
+    sampling resumes from 1 the next time critical pressure recurs."""
     from agent_runner.events import ROUND_MEM_CRITICAL_SAMPLE, emit
 
     emit(
@@ -320,13 +332,34 @@ def emit_round_mem_critical_sample(
 
 
 def emit_host_cgroup_memory_limit(
-    log_dir: Path, *, memory_max: int | None, memory_swap_max: int | None, cgroup_path: str | None
+    log_dir: Path,
+    *,
+    memory_max: int | None,
+    memory_swap_max: int | None,
+    cgroup_path: str | None,
+    swap_total_bytes: int | None = None,
+    swap_cap_pct: float | None = None,
+    memory_high: int | None = None,
+    advisory: str | None = None,
 ) -> None:
     """Emit once at serve startup: this process's cgroup v2 memory budget
     (``metrics.cgroup_memory_limits``). ``None`` fields mean unlimited (or
     cgroup v2 unavailable). Serve uses this once to decide whether the
     mid-round hard floor can defer to kernel cgroup-OOM -- see
-    ``emit_mem_pressure_deferred_to_cgroup`` below."""
+    ``emit_mem_pressure_deferred_to_cgroup`` below.
+
+    0.2.18 adds an optional startup swap-cap advisory
+    (``swap_total_bytes`` / ``swap_cap_pct`` / ``memory_high`` / ``advisory``)
+    as FIELDS on this SAME event -- never a separate event kind, and never an
+    auto-change to the operator's cgroup or unit. ``swap_total_bytes`` is the
+    host's total swap (``metrics.swap_total_bytes``); ``swap_cap_pct`` is
+    ``memory_swap_max`` as a percentage of it (``None`` when either side is
+    unknown); ``memory_high`` is the bounding ancestor's ``memory.high`` in
+    bytes (``metrics.cgroup_memory_high``) -- ``None`` means unset (the
+    cgroup read the literal ``"max"``, or no finite value at all), never the
+    raw ``"max"`` token, so a caller can't mistake "unset" for a real
+    ceiling; ``advisory`` is the human-readable warning text when the swap
+    cap looks implausibly tight, else ``None``."""
     from agent_runner.events import HOST_CGROUP_MEMORY_LIMIT, emit
 
     emit(
@@ -335,6 +368,91 @@ def emit_host_cgroup_memory_limit(
         memory_max=memory_max,
         memory_swap_max=memory_swap_max,
         cgroup_path=cgroup_path,
+        swap_total_bytes=swap_total_bytes,
+        swap_cap_pct=swap_cap_pct,
+        memory_high=memory_high,
+        advisory=advisory,
+    )
+
+
+def emit_round_cgroup_memory(
+    log_dir: Path,
+    *,
+    round_num: int,
+    memory_current_peak: int,
+    memory_swap_current_peak: int,
+    events_high_delta: int,
+    events_max_delta: int,
+    events_oom_delta: int,
+    events_oom_kill_delta: int,
+    bounding_cgroup_path: str | None,
+) -> None:
+    """Emit once per round: the round's peak cgroup ``memory.current`` (+swap) and
+    the ``memory.events`` DELTAS (high/max/oom/oom_kill) over the round, read at the
+    bounding ancestor. Deltas, never absolutes -- an operator sees pressure BUILDING
+    without SSH. Peak is the max over the existing ~10s mid-round tick (NOT
+    ``memory.peak``, which is cumulative since cgroup creation). No-op when this
+    host has no finite cgroup bound (``_serve_round._emit_round_cgroup_memory``
+    never calls this in that case).
+
+    ``bounding_cgroup_path`` is deliberately NOT named ``cgroup_path`` --
+    ``host_cgroup_memory_limit`` already uses that name for the LEAF (this
+    process's own) cgroup; here it names the BOUNDING ANCESTOR (the one whose
+    ``memory.max`` actually binds). Same key, two meanings across the two
+    events an operator correlates would be a trap -- events.md pins field
+    semantics permanently once shipped, so the distinct name is chosen now."""
+    from agent_runner.events import ROUND_CGROUP_MEMORY, emit
+
+    emit(
+        log_dir,
+        ROUND_CGROUP_MEMORY,
+        round_num=round_num,
+        memory_current_peak=memory_current_peak,
+        memory_swap_current_peak=memory_swap_current_peak,
+        events_high_delta=events_high_delta,
+        events_max_delta=events_max_delta,
+        events_oom_delta=events_oom_delta,
+        events_oom_kill_delta=events_oom_kill_delta,
+        bounding_cgroup_path=bounding_cgroup_path,
+    )
+
+
+def emit_round_oom_killed(
+    log_dir: Path,
+    *,
+    round_num: int,
+    log_path: Path,
+    log_bytes: int,
+    oom_kill_delta: int,
+    partial_log: bool,
+) -> None:
+    """Emit when the kernel cgroup-OOM-killed a round (``memory.events.oom_kill``
+    rose over the round, per ``_serve_round._maybe_emit_oom_killed`` -- folded
+    from the SAME ``cgroup_memory_usage()`` read ``round_cgroup_memory`` already
+    took, no second sysfs read). Symmetric with ``round_mem_terminated``
+    (supervisor-killed) -- this is the kernel-killed sibling.
+
+    POINTER-ONLY: ``log_path`` + ``log_bytes`` + ``oom_kill_delta`` -- NEVER the
+    round-log/transcript content itself (durability, secret-redaction, size all
+    argue against embedding it in events.jsonl). ``partial_log`` reports whether
+    the supervisor's own truncation trailer (see ``_mark_partial_log``) was
+    written onto the round log, so a later reader can tell the log's tail is
+    supervisor residue, not the agent's own output.
+
+    Classification is UNCHANGED by this event: the round still exits 137 and
+    counts toward the crash streak exactly as before -- this is pure
+    observability layered on top, computed and emitted after that decision is
+    already made."""
+    from agent_runner.events import ROUND_OOM_KILLED, emit
+
+    emit(
+        log_dir,
+        ROUND_OOM_KILLED,
+        round_num=round_num,
+        log_path=str(log_path),
+        log_bytes=log_bytes,
+        oom_kill_delta=oom_kill_delta,
+        partial_log=partial_log,
     )
 
 

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/agent_runner/_monitor_detectors.py

@@ -14,7 +14,7 @@ the plugin registry (``_monitor_registry``), and the cycle-edge wiring
 from __future__ import annotations
 
 import re
-from datetime import UTC, datetime, timedelta
+from datetime import datetime, timedelta
 from pathlib import Path
 from typing import Any
 
@@ -407,15 +407,21 @@ def detect_rate_limit_active(
         if kind == TRANSIENT_ERROR_RECOVERED:
             return None
         if kind == TRANSIENT_ERROR_DETECTED:
-            from agent_runner._throttle import _coerce_int, _events_derived_reset
+            from agent_runner._throttle import (
+                _coerce_epoch_int,
+                _events_derived_reset,
+                _safe_epoch_iso,
+            )
 
             agent = str(ev.get("agent", "unknown"))
             classification = ev.get("classification", "unknown")
-            reset = _coerce_int(ev.get("reset_at_epoch"), 0)
+            reset = _coerce_epoch_int(ev.get("reset_at_epoch"), 0, now_epoch=now)
             if log_dir is not None:
                 reset = _events_derived_reset(log_dir, agent, str(classification), reset)
             if reset > now:
-                iso = datetime.fromtimestamp(reset, UTC).isoformat()
+                iso = _safe_epoch_iso(reset)
+                if iso is None:
+                    return None  # poisoned epoch — don't blind-crash the detector
                 return _alert(
                     "rate_limit_active",
                     "warning",

{cli_agent_runner-0.2.16 → cli_agent_runner-0.2.18}/agent_runner/_monitor_state.py

@@ -9,15 +9,16 @@ cycle-edge wiring (``run_all_detectors``/``on_alert``) in ``monitor.py``.
 from __future__ import annotations
 
 from collections import deque
-from collections.abc import Iterable
+from collections.abc import Iterable, Iterator
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Protocol
 
 from agent_runner.api_types import ProjectState, ServiceMode, ServiceStatus, SystemMetrics
 from agent_runner.builtin_plugins._constants import _TAIL_LINES
+from agent_runner.clock import SYSTEM_CLOCK
 from agent_runner.context_store import read_json
-from agent_runner.events import _iter_parsed_lines, iter_event_dicts, open_events_jsonl
+from agent_runner.events import iter_event_dicts, read_new
 
 
 class StateSource(Protocol):
@@ -82,22 +83,41 @@ class _EventTail:
     )
 
     def read(self, files: list[Path]) -> list[dict[str, Any]]:
-        for path in files:
-            pos = self.offsets.get(path, 0)
+        new_events, self.offsets = read_new(files, self.offsets)
+        self.buffer.extend(new_events)
+        return list(self.buffer)
+
+
+def _tail_events_jsonl(
+    log_dir: Path,
+    *,
+    start_at_now: bool,
+    poll_interval_s: float,
+) -> Iterator[dict[str, Any]]:
+    """Polling tailer: yields parsed event dicts from events-*.jsonl files.
+
+    ``start_at_now``: if True, snapshot current file sizes at init so existing
+    events are skipped (machine-consumption use case). If False, yield from
+    byte 0 of every file present at start (human-narrate use case).
+
+    Follows file rotation transparently — when a new events-YYYY-MM.jsonl
+    appears, it is picked up from byte 0.
+    """
+    offsets: dict[Path, int] = {}
+    if start_at_now:
+        for path in sorted(log_dir.glob("events-*.jsonl")):
             try:
-                size = path.stat().st_size
+                offsets[path] = path.stat().st_size
             except FileNotFoundError:
                 continue
-            if size < pos:
-                pos = 0  # rotated/truncated underneath us
-            if size == pos:
-                continue
-            with open_events_jsonl(path) as f:
-                f.seek(pos)
-                for _, parsed in _iter_parsed_lines(f):
-                    self.buffer.append(parsed)
-                self.offsets[path] = f.tell()
-        return list(self.buffer)
+
+    while True:
+        files = sorted(log_dir.glob("events-*.jsonl"))
+        new_events, offsets = read_new(files, offsets)
+        if new_events:
+            yield from new_events
+        else:
+            SYSTEM_CLOCK.sleep(poll_interval_s)
 
 
 _MAX_TAIL_FILES = 20

cli_agent_runner-0.2.18/agent_runner/_plugin_scan.py

@@ -0,0 +1,109 @@
+"""Plugin discovery scanner — replaces per-group importlib.metadata.entry_points
+scans at startup with one cheap entry_points.txt parse. Hard-falls-back to
+importlib.metadata on any parse failure; AGENT_RUNNER_PLUGIN_DISCOVERY=metadata
+forces the fallback. Parity with importlib.metadata is pinned by
+tests/unit/test_plugin_scan_parity.py per group."""
+
+from __future__ import annotations
+
+import configparser
+import os
+import warnings
+from pathlib import Path
+
+
+def _metadata_entry_points(group: str) -> list[tuple[str, str]]:
+    """The old path: importlib.metadata's own distribution scan.
+
+    Imported lazily — importlib.metadata pulls in email.* (METADATA parsing)
+    at import time, which is most of the footprint this scanner exists to
+    avoid. Importing it at module top would tax every process even when the
+    fast path never falls back.
+    """
+    from importlib.metadata import entry_points
+
+    return [(ep.name, ep.value) for ep in entry_points(group=group)]
+
+
+# Parsed entry_points.txt contents, memoized per dist-info file for the life
+# of the process: {ep_file_path: {group: [(name, value), ...]}}. Package
+# import calls _parse_entry_points_files once per plugin group (7x today,
+# _HOOK_GROUPS + event_kinds + detectors) across the SAME sys.path, so every
+# call after the first re-walks the identical dist-info directories --
+# without this cache each one would re-open and re-parse (configparser) every
+# entry_points.txt found, 7x over, just to pull out a different [group]
+# section each time. Keyed by the file's path only (not mtime) -- a dist-info
+# is not expected to change under a running process.
+_PARSED_DIST_INFO_CACHE: dict[Path, dict[str, list[tuple[str, str]]]] = {}
+
+
+def _parsed_entry_points_by_group(ep_file: Path) -> dict[str, list[tuple[str, str]]]:
+    """One ``entry_points.txt``, parsed once and bucketed by ``[group]``
+    section: ``{group: [(name, value), ...]}``. Memoized in
+    :data:`_PARSED_DIST_INFO_CACHE` so a second call for the same file (a
+    different plugin group asking about the same dist-info) reuses the
+    parse instead of re-opening + re-running configparser over it."""
+    cached = _PARSED_DIST_INFO_CACHE.get(ep_file)
+    if cached is not None:
+        return cached
+    parser = configparser.ConfigParser(interpolation=None)
+    parser.optionxform = str  # preserve case -- entry-point names are case-sensitive
+    parser.read(ep_file, encoding="utf-8")
+    parsed = {section: list(parser[section].items()) for section in parser.sections()}
+    _PARSED_DIST_INFO_CACHE[ep_file] = parsed
+    return parsed
+
+
+def _parse_entry_points_files(sys_path: list[str], group: str) -> list[tuple[str, str]]:
+    """(name, value) pairs for ``group`` by parsing each ``*.dist-info/entry_points.txt``
+    found on ``sys_path``. A name seen in an earlier ``sys.path`` entry wins over a
+    later one — the same first-found precedence ``sys.path`` gives real imports.
+
+    A dropped duplicate emits a ``UserWarning`` naming the group, the duplicated
+    name, and which value won — the same diagnostic value the old
+    ``importlib.metadata`` + ``ensure_unique`` path gave operators (that path
+    let both entries load and had ``ensure_unique`` reject the second with a
+    warning); silently dropping it here would regress that visibility.
+    """
+    out: list[tuple[str, str]] = []
+    seen: dict[str, str] = {}
+    for entry in sys_path:
+        base = Path(entry) if entry else Path.cwd()
+        if not base.is_dir():
+            continue
+        for dist_info in base.glob("*.dist-info"):
+            ep_file = dist_info / "entry_points.txt"
+            if not ep_file.is_file():
+                continue
+            groups = _parsed_entry_points_by_group(ep_file)
+            if group not in groups:
+                continue
+            for name, value in groups[group]:
+                winner = seen.get(name)
+                if winner is None:  # dedup: first sys.path entry wins
+                    seen[name] = value
+                    out.append((name, value))
+                elif winner != value:
+                    warnings.warn(
+                        f"duplicate entry_point {name!r} in group {group!r}: "
+                        f"{value!r} dropped in favor of the earlier {winner!r} "
+                        f"(first sys.path entry wins)",
+                        stacklevel=2,
+                    )
+    return out
+
+
+def scan_entry_points(sys_path: list[str], group: str) -> list[tuple[str, str]]:
+    """(name, 'module:attr') pairs for ``group`` across ``sys_path``.
+
+    Hard-falls-back to ``importlib.metadata.entry_points`` on any parse
+    failure, or unconditionally when ``AGENT_RUNNER_PLUGIN_DISCOVERY=metadata``
+    is set (escape hatch for an environment where the scan and metadata
+    disagree).
+    """
+    if os.environ.get("AGENT_RUNNER_PLUGIN_DISCOVERY") == "metadata":
+        return _metadata_entry_points(group)
+    try:
+        return _parse_entry_points_files(sys_path, group)
+    except Exception:  # noqa: BLE001 — never let discovery crash import; fall back
+        return _metadata_entry_points(group)