cli-agent-runner 0.2.17__tar.gz → 0.2.19__tar.gz

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/.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.17 → cli_agent_runner-0.2.19}/.vulture-whitelist.py

@@ -13,12 +13,16 @@ log_dir
 offsets
 buffer
 
-# agent_runner._throttle.RoundOutcome
+# 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

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/BACKLOG.md

@@ -88,3 +88,38 @@ just succeeded in the same repo).
 Deferred because closing it is a naming decision, not cleanup: no event kind
 carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
 — the stash exists). Left as-is until that kind is designed.
+
+## `_monitor_loop_iter`'s three fail-open guards are hand-duplicated
+
+`api._monitor_loop_iter` wraps the startup `monitor_started` emit, the
+per-tick poll, and `on_alert`'s per-alert dispatch each in its own
+`try/except Exception: warnings.warn(...)` block so a crash in any one of the
+three never ends monitor supervision. The three guards are structurally
+identical (catch, format a `type(e).__name__: {e}` warning, keep the loop
+alive) but hand-copied rather than sharing one implementation; `on_alert`'s
+own `emit()` closure already shows the pattern for factoring a shared guard.
+
+Collapsing them to one shared guard is behavior-preserving — it must not
+change which failures warn vs which propagate, nor the specific fallback
+each site takes on failure (sleep-and-retry after a poll failure,
+`verdict = "failed"` after an `on_alert` failure). Slated for 0.2.19.
+
+## `oom_kill_delta` is named differently on its two events — NEEDS_DESIGN, DEFERRED to 0.3
+
+The same cgroup `memory.events.oom_kill` delta is emitted under two
+different field names depending on which event carries it: `round_cgroup_memory`
+reports it as `events_oom_kill_delta` (matching its sibling counters
+`events_high_delta`/`events_max_delta`/`events_oom_delta`), while
+`round_oom_killed` — folded from the same scan, no second sysfs read —
+reports the identical value as bare `oom_kill_delta`. A reader correlating
+the two events for the same round has to know the same quantity carries two
+names.
+
+Renaming either side is a change to a published event field name — part of
+the peek/event JSON contract — so which name becomes canonical (and whether
+it lands as a rename or an additive alias) needs a decision, not a silent
+swap. Tagged NEEDS_DESIGN. Deferred to 0.3's event-model canonicalization
+(see [[project-03-direction]]) rather than reconciled standalone in 0.2.19 —
+0.3 is already renaming/unifying event fields wholesale, and settling this
+name now risks a double-rename (once here, again when 0.3's canonical model
+lands). No field name changes in code until that decision is made.

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.19] - 2026-09-09
+
+### Changed
+- `monitor --host` relay now drains cleanly on SIGTERM — tears down its ssh child group and exits 0 — instead of dying immediately, matching `serve`'s stop-signal behavior.
+- Internal structure, behavior-identical: `_emit.py` split into an `_emit/` package (domain submodules behind a facade); the cgroup-pressure spine carved out of `cli/_serve_round.py` into `cli/_serve_cgroup.py`.
+- The give-up exit-code table in the runbook is now generated from code instead of hand-copied; detector/defense counts and the `peek` schema version are now invariant-pinned against the same source.
+- Internal hardening: the monitor's fail-open guards are unified into one implementation; `kill`'s systemd-user SIGKILL escalation shares the same bounded poll `serve` uses; the cgroup pressure spine resolves its bounding ancestor once per round instead of on every tick; a single-implementation `Protocol` was collapsed to its concrete type; a process's stored child-name no longer passes an attacker-rewritable `argv[0]` through unbounded; plugin discovery now scans legacy egg-info installs and handles entry points with an extras suffix.
+
+### Fixed
+- Docs: the `agent_usage_recorded` plugin list corrected to claude/gemini/codewhale/pi (kimi's built-in plugin emits no token counters).
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change. The relay's SIGTERM-drain above is the one behavior change in this release — anyone relying on the relay's old immediate-exit-on-SIGTERM will now see it drain instead.
+- `oom_kill_delta`'s two-different-field-names inconsistency is deferred to 0.3's event-model work rather than reconciled here, to avoid a double-rename.
+
+## [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

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/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.17 → cli_agent_runner-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.17
+Version: 0.2.19
 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'
@@ -150,6 +152,7 @@ your laptop closed. Full relay + SSH-trust mechanics:
 - [`docs/configuration.md`](docs/configuration.md) — `agent-runner.toml` schema
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
+- [`docs/memory-efficiency.md`](docs/memory-efficiency.md) — supervisor memory footprint, measured release over release
 
 ## Development
 

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/README.md

@@ -114,6 +114,7 @@ your laptop closed. Full relay + SSH-trust mechanics:
 - [`docs/configuration.md`](docs/configuration.md) — `agent-runner.toml` schema
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
+- [`docs/memory-efficiency.md`](docs/memory-efficiency.md) — supervisor memory footprint, measured release over release
 
 ## Development
 

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/README.zh.md

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

{cli_agent_runner-0.2.17 → cli_agent_runner-0.2.19}/agent_runner/__init__.py

@@ -27,16 +27,36 @@ 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()
+            # An entry-point value may carry a trailing extras marker
+            # (``module:attr [extra1,extra2]``); importlib.metadata.EntryPoint's
+            # own module/attr grammar excludes "[", so anything from the first
+            # "[" onward is always extras, never part of the path — strip it
+            # before resolving, or it glues onto attr_path and breaks getattr().
+            module_path, _, attr_path = value.partition("[")[0].rstrip().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 +100,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.17 → cli_agent_runner-0.2.19}/agent_runner/_docgen.py

@@ -16,6 +16,7 @@ import typing
 from collections.abc import Callable
 from pathlib import Path
 
+from agent_runner import _serve_policy
 from agent_runner.cli.init_cmd import _preset_names
 from agent_runner.config import (
     AgentConfig,
@@ -30,7 +31,14 @@ from agent_runner.config import (
     VcsConfig,
 )
 from agent_runner.defenses import catalog
-from agent_runner.events import KNOWN_EVENT_KINDS
+from agent_runner.events import (
+    CONFIG_BROKEN,
+    CRASH_LOOP,
+    KNOWN_EVENT_KINDS,
+    MEM_LOOP,
+    MEM_LOOP_PERSISTENT,
+    STALLED_NO_PROGRESS,
+)
 from agent_runner.monitor import AUTO_STOP_ALERTS, KNOWN_ALERT_KINDS
 
 # (toml_section_name, dataclass, nested_sub_sections). Nesting is an EXPLICIT
@@ -156,6 +164,84 @@ def render_event_kinds_list() -> str:
     return "\n".join(f"- `{k}`" for k in sorted(KNOWN_EVENT_KINDS))
 
 
+def _giveup_verdict_rows() -> list[tuple[str, int, bool]]:
+    """``(verdict, exit_code, in_restart_prevent)`` rows for serve's five
+    give-up verdicts, in the order the runbook's Symptom section lists them.
+
+    The verdict->code mapping itself is CONTROL FLOW in
+    ``cli/_serve_round.post_round_verdicts`` (a chain of ``if``/``return``,
+    not a dict), so it is mirrored here by hand rather than imported — the
+    four exit-code integers are imported from ``_serve_policy``, the actual
+    code SSOT, so a constant change here is caught by ``./build.sh docs``
+    producing a diff. The third column is DERIVED from
+    ``_serve_policy.RESTART_PREVENT_EXIT_CODES`` (the same single source
+    ``service_unit.py`` renders from) rather than hand-typed per row.
+    """
+    verdict_codes = [
+        (CONFIG_BROKEN, _serve_policy.PERMANENT_CONFIG_EXIT),
+        (CRASH_LOOP, _serve_policy.CRASH_LOOP_EXIT),
+        (STALLED_NO_PROGRESS, _serve_policy.CRASH_LOOP_EXIT),
+        (MEM_LOOP_PERSISTENT, _serve_policy.MEM_LOOP_PERSISTENT_EXIT),
+        (MEM_LOOP, _serve_policy.MEM_LOOP_EXIT),
+    ]
+    return [
+        (verdict, code, code in _serve_policy.RESTART_PREVENT_EXIT_CODES)
+        for verdict, code in verdict_codes
+    ]
+
+
+def render_giveup_exit_codes_table() -> str:
+    """Verdict -> exit-code -> ``RestartPreventExitStatus`` membership table
+    for serve's give-up breakers. 5 verdicts map to only 4 distinct codes:
+    ``stalled_no_progress`` reuses ``crash_loop``'s 75 rather than minting its
+    own (same give-up verdict — "an unknown failure kept recurring, stop for
+    real" — reached via a different signal)."""
+    lines = ["| Verdict | Exit code | `RestartPreventExitStatus`? |", "|---|---|---|"]
+    seen_codes: dict[int, str] = {}
+    for verdict, code, stays_stopped in _giveup_verdict_rows():
+        shares = f" (shares `{seen_codes[code]}`'s exit code)" if code in seen_codes else ""
+        seen_codes.setdefault(code, verdict)
+        behavior = "yes — stays stopped" if stays_stopped else "no — restarts (break-then-restart)"
+        lines.append(f"| `{verdict}` | `{code}`{shares} | {behavior} |")
+    return "\n".join(lines)
+
+
+def render_giveup_systemd_example() -> str:
+    """The ``systemd unit pattern recommendations`` fenced example.
+
+    ``RestartPreventExitStatus`` lists the three DELIBERATE give-up codes
+    (config_broken/crash_loop/mem_loop_persistent), derived from
+    ``_serve_policy.RESTART_PREVENT_EXIT_CODES`` — the same single source
+    ``service_unit.py`` renders from; ``mem_loop``'s 71 is deliberately
+    excluded so systemd respawns to retry. The second comment line's
+    leading padding is derived from the first line's own length (not
+    hand-counted) so the two ``#`` columns always line up even if a future
+    exit code changes ``prevent``'s width."""
+    prevent = " ".join(str(c) for c in _serve_policy.RESTART_PREVENT_EXIT_CODES)
+    header = f"RestartPreventExitStatus={prevent}   "
+    return (
+        "```ini\n"
+        "# Prod (infinite supervisor) — current default\n"
+        "[Service]\n"
+        "ExecStart=... serve --config /etc/agent-runner.toml\n"
+        "Restart=on-failure\n"
+        f"{header}"
+        f"# config_broken ({_serve_policy.PERMANENT_CONFIG_EXIT}) / "
+        f"crash_loop ({_serve_policy.CRASH_LOOP_EXIT}) / "
+        f"mem_loop_persistent ({_serve_policy.MEM_LOOP_PERSISTENT_EXIT}) stay stopped\n"
+        f"{' ' * len(header)}"
+        f"# mem_loop ({_serve_policy.MEM_LOOP_EXIT}) is NOT listed here — it restarts\n"
+        "RestartSec=3\n"
+        "\n"
+        "# Bounded job\n"
+        "[Service]\n"
+        "ExecStart=... serve --config /etc/test.toml --max-rounds 10\n"
+        "Restart=on-failure\n"
+        "RestartSec=5\n"
+        "```"
+    )
+
+
 def _render_migrate_transforms() -> str:
     """Bullet list of the transforms `agent-runner migrate` applies, from the registry.
     A few entries carry a `parsed -> str` describe (so the manual report can name the
@@ -265,6 +351,16 @@ RENDERERS: dict[str, Renderer] = {
     "migrate-transforms": Renderer(
         _render_migrate_transforms, "agent_runner/migrations.py MIGRATIONS"
     ),
+    "giveup-exit-codes": Renderer(
+        render_giveup_exit_codes_table,
+        "agent_runner/_serve_policy.py exit-code constants + "
+        "cli/_serve_round.py post_round_verdicts's verdict->code map",
+    ),
+    "giveup-systemd-example": Renderer(
+        render_giveup_systemd_example,
+        "agent_runner/_serve_policy.py exit-code constants "
+        "(service_unit.py's RestartPreventExitStatus mirrors these same three)",
+    ),
 }
 RENDERERS.update(
     {

cli_agent_runner-0.2.19/agent_runner/_emit/__init__.py

@@ -0,0 +1,103 @@
+"""Event emission wrappers — extracted from api.py for module-size hygiene.
+
+Public facade over the ``_emit`` package: every sibling module in
+``agent_runner`` (and every test) imports from ``agent_runner._emit``
+directly, never from ``agent_runner._emit.<submodule>`` — this file is the
+one place a name crosses that boundary. All wrappers are re-exported from
+agent_runner.api for backward compatibility; plugins and supervisor should
+continue importing from agent_runner.api (e.g.
+``from agent_runner.api import emit_transient_error_detected``).
+
+Each wrapper exists to keep cli/serve_cmd.py from importing agent_runner.events
+directly — preserves the module-boundary architecture invariant. Local-import pattern
+inside each wrapper body keeps agent_runner.api import-cheap.
+
+Submodules are organised by domain: ``serve`` (supervisor control plane +
+config/schedule lifecycle), ``rounds`` (one round's own lifecycle),
+``memory`` (host/cgroup memory pressure), ``agent`` (the agent axis — plugin
+reports + throttle response).
+"""
+
+from __future__ import annotations
+
+from agent_runner._emit.agent import (  # noqa: F401 — public re-export
+    emit_agent_auth_error_detected,
+    emit_agent_usage_recorded,
+    emit_anomaly_repetitive_tool,
+    emit_transient_error_backoff_capped,
+    emit_transient_error_detected,
+    emit_transient_error_recovered,
+)
+from agent_runner._emit.memory import (  # noqa: F401 — public re-export
+    emit_host_cgroup_memory_limit,
+    emit_mem_pressure_deferred_to_cgroup,
+    emit_round_cgroup_memory,
+    emit_round_deferred,
+    emit_round_mem_critical_sample,
+    emit_round_mem_terminated,
+    emit_round_oom_killed,
+    emit_round_resumed,
+)
+from agent_runner._emit.rounds import (  # noqa: F401 — public re-export
+    emit_fresh_eyes_round_triggered,
+    emit_round_grace_extended,
+    emit_round_grace_kill,
+    emit_round_logs_prune_deferred,
+    emit_round_progress,
+    emit_round_substrate_after,
+    emit_round_substrate_before,
+    emit_round_supervisor_wedged,
+    emit_stale_index_lock_cleared,
+)
+from agent_runner._emit.serve import (  # noqa: F401 — public re-export
+    emit_config_broken,
+    emit_config_migrated,
+    emit_crash_loop,
+    emit_max_rounds_reached,
+    emit_mem_loop,
+    emit_mem_loop_persistent,
+    emit_rate_limit_stop,
+    emit_schedule_paused,
+    emit_schedule_phase_skipped,
+    emit_schedule_resumed,
+    emit_stalled_no_progress,
+    emit_stop_file_detected,
+)
+
+__all__ = [
+    "emit_agent_auth_error_detected",
+    "emit_agent_usage_recorded",
+    "emit_anomaly_repetitive_tool",
+    "emit_config_broken",
+    "emit_config_migrated",
+    "emit_crash_loop",
+    "emit_fresh_eyes_round_triggered",
+    "emit_host_cgroup_memory_limit",
+    "emit_max_rounds_reached",
+    "emit_mem_loop",
+    "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",
+    "emit_round_substrate_before",
+    "emit_round_supervisor_wedged",
+    "emit_schedule_paused",
+    "emit_schedule_phase_skipped",
+    "emit_schedule_resumed",
+    "emit_stale_index_lock_cleared",
+    "emit_stalled_no_progress",
+    "emit_stop_file_detected",
+    "emit_transient_error_backoff_capped",
+    "emit_transient_error_detected",
+    "emit_transient_error_recovered",
+]