cli-agent-runner 0.3.2__tar.gz → 0.3.3__tar.gz

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/.vulture-whitelist.py

@@ -23,6 +23,7 @@ dirty_handlers
 spawn_hooks
 detectors
 event_kinds
+sigterm_cooperative
 
 # agent_runner._round_outcome.RoundOutcome
 mem_terminated
@@ -156,6 +157,7 @@ checks
 overlaps
 plan
 sandbox
+cgroup
 
 # agent_runner.config.models.AgentConfig
 command

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.3.3] - 2026-09-14
+
+### Added
+- `host_cgroup_memory_limit` now reports whether the supervisor's own cgroup is delegated (its `cgroup.procs`/`memory.high` are writable); `doctor` shows it and advises adding `Delegate=yes` to the systemd unit when it isn't. Read-only — nothing is written to any cgroup.
+- Plugin presets can declare `sigterm_cooperative` (the built-in `gemini` preset does); an observability-only declaration surfaced in `peek --json` (schema `2.3`) and `doctor` — it does not change any termination behavior.
+
 ## [0.3.2] - 2026-09-14
 
 ### Added

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.2
+Version: 0.3.3
 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

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/_emit/memory.py

@@ -106,6 +106,7 @@ def emit_host_cgroup_memory_limit(
     swap_cap_pct: float | None = None,
     memory_high: int | None = None,
     advisory: str | None = None,
+    cgroup_delegated: bool | None = None,
 ) -> None:
     """Emit once at serve startup: this process's cgroup v2 memory budget
     (``metrics.cgroup_memory_limits``). ``None`` fields mean unlimited (or
@@ -128,7 +129,11 @@ def emit_host_cgroup_memory_limit(
     fire: a ``memory.swap.max`` that looks implausibly tight against host
     swap, and a ``memory.max`` set on this process's OWN cgroup without a
     ``memory.high``, which recommends adding one (below ``memory.max``) for
-    graceful pre-OOM throttling instead of a hard kill."""
+    graceful pre-OOM throttling instead of a hard kill. ``cgroup_delegated``
+    (``metrics.cgroup_delegated``) is the READ-ONLY delegation-readiness
+    probe: ``True``/``False`` when cgroup v2 is present, ``None`` when it
+    isn't or the leaf couldn't be resolved -- an append-only field, unrelated
+    to whether the floor defers."""
     from agent_runner.events import HOST_CGROUP_MEMORY_LIMIT, emit
 
     emit(
@@ -141,6 +146,7 @@ def emit_host_cgroup_memory_limit(
         swap_cap_pct=swap_cap_pct,
         memory_high=memory_high,
         advisory=advisory,
+        cgroup_delegated=cgroup_delegated,
     )
 
 

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/_plugin_manifest.py

@@ -36,6 +36,12 @@ class PluginManifest:
     spawn_hooks: tuple[SpawnHook, ...] = ()
     detectors: tuple[Detector, ...] = ()
     event_kinds: tuple[str, ...] = ()
+    sigterm_cooperative: bool = False
+    """Declares that this preset's CLI cooperatively drains/cleans up on
+    SIGTERM -- source-verified per preset, NEVER assumed from a CLI's
+    general reputation. Observability-only: surfaced via
+    cooperative_manifest_names() to `peek --json` and `doctor`. Does not
+    itself change any termination behavior."""
 
 
 _LOADED_MANIFESTS: list[PluginManifest] = []
@@ -48,6 +54,14 @@ def loaded_manifest_names() -> list[str]:
     return [m.name for m in _LOADED_MANIFESTS]
 
 
+def cooperative_manifest_names() -> list[str]:
+    """Names of every currently-registered manifest declaring
+    sigterm_cooperative=True (order-preserving). Mirrors
+    loaded_manifest_names; used by peek + doctor to answer "which presets
+    are cooperative" without either caller reaching into _LOADED_MANIFESTS."""
+    return [m.name for m in _LOADED_MANIFESTS if m.sigterm_cooperative]
+
+
 def register_manifest(
     manifest: PluginManifest,
     *,

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.3'
+__version_tuple__ = version_tuple = (0, 3, 3)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/builtin_plugins/gemini.py

@@ -162,4 +162,6 @@ def _extract_usage(stats: dict[str, Any]) -> dict[str, Any]:
     }
 
 
-PLUGIN = PluginManifest(name="gemini", post_round_hooks=(GeminiErrorDetector(),))
+PLUGIN = PluginManifest(
+    name="gemini", post_round_hooks=(GeminiErrorDetector(),), sigterm_cooperative=True
+)

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/cli/_serve_cgroup.py

@@ -190,6 +190,16 @@ def _maybe_emit_oom_killed(
 # report ask #3). Advisory only -- never changes the operator's cgroup/unit.
 _SWAP_CAP_ADVISORY_PCT = 25.0
 
+# The delegation-readiness advisory: memory.max/memory.high are bound on this
+# cgroup, but metrics.cgroup_delegated found the leaf is NOT delegated
+# (systemd Delegate=yes) -- a future release that wants to write memory.high
+# on a round-scoped nested cgroup needs delegation first. Advisory only; this
+# probe and its hint never write to the cgroup or the unit.
+_UNDELEGATED_HINT = (
+    "this cgroup is not delegated (systemd Delegate=yes) -- memory.high can be "
+    "read but not managed here until it is"
+)
+
 
 def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     """Probe this process's cgroup v2 memory budget once at serve startup,
@@ -252,6 +262,7 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     # `self_cgroup=limits["cgroup_path"]` dead-ends at the same place either
     # way as calling with no override would.
     memory_high = metrics.cgroup_memory_high(self_cgroup=limits["cgroup_path"])
+    delegated = metrics.cgroup_delegated(self_cgroup=limits["cgroup_path"])
     swap_max = limits["memory_swap_max"]
     swap_cap_pct = (
         round(100.0 * swap_max / swap_total, 1) if swap_max is not None and swap_total > 0 else None
@@ -288,6 +299,8 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
                 "throttle's PSI-full rise doesn't trip the mid-round floor"
             )
         advisories.append(hint)
+    if delegated is False and (memory_high is not None or own_scope):
+        advisories.append(_UNDELEGATED_HINT)
     advisory = "; ".join(advisories) or None
     if advisory is not None:
         print(f"agent-runner: {advisory}", file=sys.stderr)
@@ -300,5 +313,6 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
         swap_cap_pct=swap_cap_pct,
         memory_high=memory_high,
         advisory=advisory,
+        cgroup_delegated=delegated,
     )
     return defer

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/cli/common.py

@@ -19,7 +19,7 @@ from agent_runner.hooks import plugin_context_enrichers, post_round_hooks, pre_r
 from agent_runner.monitor import plugin_detectors
 from agent_runner.vcs_state import plugin_owned_paths
 
-PEEK_SCHEMA_VERSION = "2.2"
+PEEK_SCHEMA_VERSION = "2.3"
 
 
 def cfg_from_args(args) -> Config:
@@ -98,6 +98,7 @@ def emit(value: Any, *, json_mode: bool, cfg: Config | None = None) -> None:
     if json_mode:
         if isinstance(value, ProjectState):
             from agent_runner import _sandbox_probe, disabled_plugin_names
+            from agent_runner._plugin_manifest import cooperative_manifest_names
 
             plugins_block = {
                 "event_kinds": plugin_event_kinds(),
@@ -107,6 +108,7 @@ def emit(value: Any, *, json_mode: bool, cfg: Config | None = None) -> None:
                 "detectors": plugin_detectors(),
                 "owned_paths": plugin_owned_paths(),
                 "disabled": disabled_plugin_names(),
+                "sigterm_cooperative": cooperative_manifest_names(),
             }
             if cfg is not None:
                 plugins_block.update(_sandbox_probe.peek_snapshot(cfg))

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/cli/doctor_cmd.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from agent_runner import phase_select, startup_check
+from agent_runner import _plugin_manifest, phase_select, startup_check
 from agent_runner.cli.common import cfg_from_args, emit
 
 
@@ -16,6 +16,7 @@ class DoctorReport:
     overlaps: list[phase_select.WindowOverlap]
     plan: list[dict]
     sandbox: dict
+    cgroup: dict
 
 
 def add_parser(sub, parent) -> None:
@@ -43,6 +44,23 @@ def _plan(cfg, rounds: int) -> list[dict]:
     return out
 
 
+def _cgroup_report() -> dict:
+    """Read-only cgroup delegation-readiness snapshot for `doctor` -- never
+    emits an event (unlike serve's `_probe_and_emit_cgroup_defer`, which
+    shares the same underlying `metrics` probes but writes
+    `host_cgroup_memory_limit`). `doctor` never launches the agent or writes
+    anything; this section is the same discipline applied to cgroup state."""
+    from agent_runner import metrics
+
+    limits = metrics.cgroup_memory_limits()
+    return {
+        "cgroup_path": limits["cgroup_path"],
+        "memory_max": limits["memory_max"],
+        "memory_high": metrics.cgroup_memory_high(self_cgroup=limits["cgroup_path"]),
+        "delegated": metrics.cgroup_delegated(self_cgroup=limits["cgroup_path"]),
+    }
+
+
 def cmd_doctor(args) -> int:
     from agent_runner._sandbox_probe import doctor_snapshot
 
@@ -52,6 +70,7 @@ def cmd_doctor(args) -> int:
         overlaps=phase_select.find_phase_window_overlaps(cfg),
         plan=_plan(cfg, args.rounds),
         sandbox=doctor_snapshot(cfg),
+        cgroup=_cgroup_report(),
     )
     json_mode = getattr(args, "json", False)
     if json_mode:
@@ -101,4 +120,16 @@ def _format(report: DoctorReport) -> str:
         lines.append("  third-party plugin checksums (paste into [plugins.pin]):")
         for name, digest in sorted(hashes.items()):
             lines.append(f'    {name} = "{digest}"')
+    cooperative = _plugin_manifest.cooperative_manifest_names()
+    lines.append(f"cooperative presets: {', '.join(sorted(cooperative)) or '(none)'}")
+    cgroup = report.cgroup
+    lines.append("cgroup:")
+    lines.append(f"  cgroup_path: {cgroup['cgroup_path']}")
+    lines.append(f"  memory_max: {cgroup['memory_max']}")
+    lines.append(f"  memory_high: {cgroup['memory_high']}")
+    lines.append(f"  delegated: {cgroup['delegated']}")
+    if cgroup["delegated"] is False:
+        from agent_runner.cli._serve_cgroup import _UNDELEGATED_HINT
+
+        lines.append(f"  hint: {_UNDELEGATED_HINT}")
     return "\n".join(lines)

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/agent_runner/metrics.py

@@ -362,6 +362,39 @@ def cgroup_memory_high(
     return _min_ancestor_limit(root, ancestors, "memory.high")
 
 
+def cgroup_delegated(
+    *,
+    root: Path = _CGROUP_ROOT,
+    proc_self_cgroup: Path = _PROC_SELF_CGROUP,
+    self_cgroup: str | None = None,
+) -> bool | None:
+    """Whether THIS process's own cgroup v2 leaf is delegated to it: uid-owned
+    AND both cgroup.procs and memory.high are writable. Read-only -- tests
+    writability via os.access(path, os.W_OK) against the existing directory;
+    NEVER opens, creates, or writes either file. None when cgroup v2 is
+    unavailable or the leaf can't be resolved (mirrors cgroup_path=None
+    elsewhere in this module) -- distinct from False (cgroup v2 present,
+    but NOT delegated to this process).
+
+    Delegation (systemd's Delegate=yes) is the prerequisite a future release
+    needs before it may safely write memory.high on a round-scoped nested
+    cgroup -- this probe only ever answers the readiness question; it never
+    itself writes anything.
+    """
+    resolved = _resolve_cgroup(root, proc_self_cgroup, self_cgroup)
+    if resolved is None:
+        return None
+    cgroup_path, _ancestors = resolved
+    leaf_dir = root / cgroup_path.lstrip("/")
+    try:
+        uid_owned = leaf_dir.stat().st_uid == os.getuid()
+    except OSError:
+        return None
+    procs_writable = os.access(leaf_dir / "cgroup.procs", os.W_OK)
+    high_writable = os.access(leaf_dir / "memory.high", os.W_OK)
+    return uid_owned and procs_writable and high_writable
+
+
 def cgroup_memory_usage(
     *,
     root: Path = _CGROUP_ROOT,

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/docs/plugins.md

@@ -188,14 +188,15 @@ The round itself continues — a broken plugin must not crash the supervisor.
 
 ```json
 {
-  "schema_version": "2.2",
+  "schema_version": "2.3",
   "plugins": {
     "event_kinds": [...],
     "context_enrichers": ["current_branch"],
     "pre_round_hooks": [...],
     "post_round_hooks": [...],
     "detectors": [...],
-    "owned_paths": [...]
+    "owned_paths": [...],
+    "sigterm_cooperative": ["gemini"]
   },
   ...
 }
@@ -549,7 +550,7 @@ detector. Other plugin detectors and all builtins still run normally.
 
 ```json
 {
-  "schema_version": "2.2",
+  "schema_version": "2.3",
   "plugins": {
     "event_kinds": [...],
     "context_enrichers": [...],

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/tests/invariants/test_import_footprint.py

@@ -126,6 +126,11 @@ EXPECTED_STARTUP_PKG_MODULES = frozenset(
         # startup_check, cli.common) were ALL already in this allowlist -- it adds
         # no new transitive dependency, just this one module itself.
         "agent_runner.cli.doctor_cmd",
+        # _plugin_manifest: doctor_cmd's new module-level import (cooperative
+        # presets line). Its own imports (_registry, api_types, hooks) were ALL
+        # already in this allowlist -- adds no new transitive dependency, just
+        # this one module itself.
+        "agent_runner._plugin_manifest",
         "agent_runner.cli.events_cmd",
         "agent_runner.cli.init_cmd",
         "agent_runner.cli.install_cmd",

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/tests/invariants/test_no_version_refs.py

@@ -5,7 +5,7 @@ planning task added a piece of code, in two related shapes:
 
 - a release version number, e.g. "0.2.17 Task 1" / "pre-0.2.18"
 - a bare internal-dev tag with no version number at all, e.g. "Group C,
-  seam 3" / "Group A" / "Task 5" on its own
+  seam 3" / "Group A" / "Task 5" / "Component 3" on its own
 
 Neither shape ever drove any logic (no version comparisons or branches
 existed anywhere, and no code ever switched on a group/task/seam label), and
@@ -51,17 +51,18 @@ _REPO = Path(__file__).resolve().parents[2]
 # contains "0.0.1", which would otherwise match this pattern) -- OR a bare
 # SDD-planning tag. The SDD-tag alternatives are anchored on the exact shapes
 # actually used (a single capital letter after "Group"; a number after
-# "Task"/"seam") so ordinary English -- "a group of tests", "the task
-# queue", "process group", "a watertight seam" -- never matches: "Group
-# Alpha" fails because `\b` cannot land between the two word characters "A"
-# and "l", and a bare "task"/"seam" with no following digit never matches at
-# all.
+# "Task"/"seam"/"Component") so ordinary English -- "a group of tests", "the
+# task queue", "process group", "a watertight seam", "a component of the
+# system" -- never matches: "Group Alpha" fails because `\b` cannot land
+# between the two word characters "A" and "l", and a bare "task"/"seam"/
+# "component" with no following digit never matches at all.
 _BREADCRUMB_REF = re.compile(
     r"(?<![\d.])0\.[0-9]+\.[0-9]+\b"  # release version, e.g. "0.2.17"
     r"|(?<![\d.])pre-0\.[0-9]"  # "pre-0.2.18"
     r"|\bGroup [A-Z]\b"  # SDD group label, e.g. "Group C"
     r"|\bTask [0-9]+"  # SDD task label, e.g. "Task 5"
     r"|\bseam [0-9]+"  # SDD seam label, e.g. "seam 3"
+    r"|\bComponent [0-9]+"  # SDD component label, e.g. "Component 3"
 )
 
 _ALLOWLIST_FILES = {
@@ -138,6 +139,10 @@ def test_scanner_should_flag_reintroduced_sdd_tag_when_scanned(tmp_path: Path) -
     group_only.write_text('"""The round-child exit-code CLASSIFIER (Group A)."""\n')
     assert _scan([group_only]), "scanner failed to flag a reintroduced bare 'Group A' tag"
 
+    component = tmp_path / "component_module.py"
+    component.write_text('"""Read by wrapup_grace_s (cli/_serve_round.py, Component 3)."""\n')
+    assert _scan([component]), "scanner failed to flag a reintroduced 'Component 3' tag"
+
     clean = tmp_path / "clean_module.py"
     clean.write_text('"""The round-child exit-code CLASSIFIER."""\n')
     assert not _scan([clean]), "scanner false-positived on tag-free text"
@@ -158,8 +163,9 @@ def test_scanner_should_not_flag_ordinary_english_group_task_seam_when_scanned(
     """The SDD-tag patterns must not fire on genuine domain/English usage of
     the same words -- "process group" and "a group of X" (real usage
     elsewhere in this codebase, e.g. defenses.py's "process group reaping"),
-    a plain "task queue", and "seam" used as an ordinary noun with no
-    following digit."""
+    a plain "task queue", "seam" used as an ordinary noun with no following
+    digit, and "component" used as an ordinary noun (e.g. "a component of
+    the system") with no following digit."""
     english = tmp_path / "english_module.py"
     english.write_text(
         "\n".join(
@@ -168,6 +174,7 @@ def test_scanner_should_not_flag_ordinary_english_group_task_seam_when_scanned(
                 "",
                 "A group of background tasks share a task queue; the seam between",
                 "two panels must stay watertight. Group Alpha handles retries.",
+                "This module is a component of the larger system.",
                 '"""',
                 "",
             ]

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/tests/invariants/test_peek_schema_version.py

@@ -72,7 +72,7 @@ def test_peek_json_should_include_schema_version_when_emitted(tmp_path: Path) ->
         f"schema_version regressed: got {payload['schema_version']!r}, "
         f"expected >= {PEEK_SCHEMA_VERSION!r}"
     )
-    assert payload["schema_version"] == "2.2"
+    assert payload["schema_version"] == "2.3"
     assert "plugins" in payload
     assert isinstance(payload["plugins"], dict)
     assert "event_kinds" in payload["plugins"]

{cli_agent_runner-0.3.2 → cli_agent_runner-0.3.3}/tests/unit/test_api_observation.py

@@ -617,3 +617,28 @@ def test_emit_should_include_disabled_plugins_block_when_json_mode(
     assert "disabled" in out["plugins"]
     # Default empty list when no apply_plugin_disable was called
     assert isinstance(out["plugins"]["disabled"], list)
+
+
+def test_emit_should_include_sigterm_cooperative_plugins_block_when_json_mode(
+    tmp_git_repo: Path,
+    capsys,
+) -> None:
+    from agent_runner.api_types import ProjectState, ServiceMode, ServiceStatus, SystemMetrics
+    from agent_runner.cli.common import emit
+
+    state = ProjectState(
+        project="t",
+        status={},
+        defenses=[],
+        current_round=None,
+        recent_rounds=[],
+        orphan=None,
+        system=SystemMetrics(mem_total_mb=1, mem_available_mb=1, disk_used_pct=0.0),
+        service=ServiceStatus(mode=ServiceMode.NONE, active=False),
+    )
+
+    emit(state, json_mode=True)
+
+    out = json.loads(capsys.readouterr().out)
+    assert "sigterm_cooperative" in out["plugins"]
+    assert isinstance(out["plugins"]["sigterm_cooperative"], list)