cli-agent-runner 0.2.23__tar.gz → 0.2.24__tar.gz

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.24] - 2026-09-12
+
+### Added
+- `host_cgroup_memory_limit` now advises adding `MemoryHigh` when a cgroup has `memory.max` set without `memory.high` (graceful pre-OOM throttling) — only for a bound on the supervisor's own cgroup, with the PSI-floor caveat when the mid-round floor isn't already deferring.
+
+### Changed
+- `doctor`'s phase-plan preview now shows a paused phase's resume time.
+- Trimmed the grace-kill test wall-time (~80s faster suite; behavior-identical).
+
 ## [0.2.23] - 2026-09-12
 
 ### Added

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.23
+Version: 0.2.24
 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.2.23 → cli_agent_runner-0.2.24}/agent_runner/_emit/memory.py

@@ -113,7 +113,7 @@ def emit_host_cgroup_memory_limit(
     mid-round hard floor can defer to kernel cgroup-OOM -- see
     ``emit_mem_pressure_deferred_to_cgroup`` below.
 
-    This also carries an optional startup swap-cap advisory
+    This also carries an optional startup 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
@@ -123,8 +123,12 @@ def emit_host_cgroup_memory_limit(
     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``."""
+    ceiling; ``advisory`` is the human-readable warning text, else ``None`` --
+    it covers two independent conditions, joined with ``"; "`` when both
+    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."""
     from agent_runner.events import HOST_CGROUP_MEMORY_LIMIT, emit
 
     emit(

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.23'
-__version_tuple__ = version_tuple = (0, 2, 23)
+__version__ = version = '0.2.24'
+__version_tuple__ = version_tuple = (0, 2, 24)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/agent_runner/cli/_serve_cgroup.py

@@ -225,9 +225,18 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     memory.swap.max is bounded but far below the host's own available swap
     (``_SWAP_CAP_ADVISORY_PCT``): the operator capped the cgroup's swap well
     under what the host has, so the mid-round floor may terminate a round
-    the kernel would have contained on a wider cap. One line is also printed
-    to stderr in that case. The event also carries ``memory_high`` -- the
-    bounding ancestor's ``memory.high`` soft-throttle threshold
+    the kernel would have contained on a wider cap. A second, independent
+    advisory recommends ``memory.high`` when ``memory.max`` is set but
+    ``memory.high`` isn't -- ONLY when the bounding ancestor is the
+    operator's OWN leaf (``bounding_cgroup_path == cgroup_path``): since
+    ``memory.max`` is the MIN across every ancestor, "set" can also mean an
+    inherited parent slice or a container root, where "add MemoryHigh" is
+    noise the operator can't act on from their own unit. That hint also
+    appends a PSI-floor caveat, but only when the floor ISN'T already
+    deferring to kernel cgroup-OOM (a deferring host has no floor for the
+    throttle's PSI-full rise to trip). Both advisories join with ``"; "``
+    and print as one stderr line. The event also carries ``memory_high`` --
+    the bounding ancestor's ``memory.high`` soft-throttle threshold
     (``metrics.cgroup_memory_high``), ``None`` when unset -- for the same
     reason: an operator asking "is MemoryHigh even set" is exactly this
     release's field ask. Advisory only -- this never changes the operator's
@@ -247,13 +256,39 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     swap_cap_pct = (
         round(100.0 * swap_max / swap_total, 1) if swap_max is not None and swap_total > 0 else None
     )
-    advisory: str | None = None
+    advisories: list[str] = []
     if swap_cap_pct is not None and swap_cap_pct < _SWAP_CAP_ADVISORY_PCT:
-        advisory = (
+        advisories.append(
             "cgroup memory.swap.max is far below host swap; the mid-round floor may "
             "terminate rounds the kernel would have contained -- consider bounding "
             "both memory.max and memory.swap.max, or set in_round_mem_terminate=false"
         )
+    defer = (
+        limits["memory_max"] is not None
+        and swap_max is not None
+        and limits["memory_max"] < metrics.mem_total_bytes()
+        and swap_max <= swap_total  # 4th guard: a >> host-swap cap can't bind -> stay armed
+    )
+    own_scope = (
+        limits["memory_max"] is not None
+        and memory_high is None
+        and limits["bounding_cgroup_path"] == limits["cgroup_path"]
+    )
+    if own_scope:
+        hint = (
+            "memory.max is set on this cgroup without memory.high -- add "
+            "memory.high (below memory.max) for graceful throttling before an "
+            "OOM kill"
+        )
+        if not defer:
+            hint += (
+                "; bound memory.swap.max (at or below host swap) too, or set "
+                "in_round_mem_terminate=false, so the throttle's PSI-full rise "
+                "doesn't trip the mid-round floor"
+            )
+        advisories.append(hint)
+    advisory = "; ".join(advisories) or None
+    if advisory is not None:
         print(f"agent-runner: {advisory}", file=sys.stderr)
     emit_host_cgroup_memory_limit(
         log_dir,
@@ -265,9 +300,4 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
         memory_high=memory_high,
         advisory=advisory,
     )
-    return (
-        limits["memory_max"] is not None
-        and swap_max is not None
-        and limits["memory_max"] < metrics.mem_total_bytes()
-        and swap_max <= swap_total  # 4th guard: a >> host-swap cap can't bind -> stay armed
-    )
+    return defer

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/agent_runner/cli/doctor_cmd.py

@@ -33,6 +33,8 @@ def _plan(cfg, rounds: int) -> list[dict]:
                 "phase": sel.phase,
                 "paused": sel.paused,
                 "resume_phase": sel.resume_phase,
+                "resume_at": sel.resume_at.isoformat() if sel.resume_at else None,
+                "resume_timezone": sel.resume_timezone,
                 "skipped": sel.skipped,
                 "active_window": sel.active_window,
             }
@@ -72,6 +74,11 @@ def _format(report: DoctorReport) -> str:
             lines.append(f"  {o.phase_a} ({o.window_a}) vs {o.phase_b} ({o.window_b})")
     lines.append("phase plan:")
     for step in report.plan:
-        where = "paused" if step["paused"] else (step["phase"] or "base")
+        if step["paused"]:
+            where = "paused"
+            if step["resume_at"] is not None:
+                where += f" -> resumes {step['resume_phase']} at {step['resume_at']}"
+        else:
+            where = step["phase"] or "base"
         lines.append(f"  round {step['round']}: {where}")
     return "\n".join(lines)

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/agent_runner/metrics.py

@@ -297,6 +297,12 @@ def cgroup_memory_limits(
     host, or any host missing that file, has no reliable fixed-path budget
     file to read, so this returns all-``None`` rather than guessing.
 
+    ``cgroup_path`` is always the caller's OWN leaf; ``bounding_cgroup_path``
+    is the ancestor (possibly the leaf itself) that actually owns the
+    winning ``memory.max`` (see :func:`_bounding_ancestor_path`) -- callers
+    that need to tell "my own limit" from "an inherited parent/container
+    bound" compare the two.
+
     ``root`` and ``proc_self_cgroup`` default to the real paths and are
     injectable so tests can point at a fake ``/sys/fs/cgroup`` tree;
     ``self_cgroup`` lets a caller supply the resolved cgroup path directly,
@@ -307,12 +313,22 @@ def cgroup_memory_limits(
     """
     resolved = _resolve_cgroup(root, proc_self_cgroup, self_cgroup)
     if resolved is None:
-        return {"memory_max": None, "memory_swap_max": None, "cgroup_path": None}
+        return {
+            "memory_max": None,
+            "memory_swap_max": None,
+            "cgroup_path": None,
+            "bounding_cgroup_path": None,
+        }
     cgroup_path, ancestors = resolved
+    # One ancestor walk for memory.max, shared for both its value and its
+    # owning path (the "SAME winning ancestor" _min_ancestor_candidate's
+    # docstring promises) -- memory.swap.max is a distinct file, its own walk.
+    max_candidate = _min_ancestor_candidate(root, ancestors, "memory.max")
     return {
-        "memory_max": _min_ancestor_limit(root, ancestors, "memory.max"),
+        "memory_max": max_candidate[0] if max_candidate else None,
         "memory_swap_max": _min_ancestor_limit(root, ancestors, "memory.swap.max"),
         "cgroup_path": cgroup_path,
+        "bounding_cgroup_path": max_candidate[1] if max_candidate else None,
     }
 
 

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/docs/memory-efficiency.md

@@ -175,6 +175,49 @@ reads/round) weren't re-measured this release since neither's code path
 moved — re-running the full harness would report the same number as
 0.2.19 for a code path this release didn't touch, not new signal.
 
+## 0.2.23 → 0.2.24
+
+Measured the same way as the table above (see Methodology), same machine,
+comparing **v0.2.23**'s base — `60c666a` (one commit past the `v0.2.23` tag:
+a ruff-format-only fix, so equivalent to the shipped release for this
+purpose) — against **0.2.24**, the tip of this branch at measurement time.
+
+### Import/startup RSS
+
+| | v0.2.23 | 0.2.24 | delta |
+|---|---|---|---|
+| RSS (avg of 5 runs) | 24.0 MB | 24.1 MB | +0.03 MB (flat, within noise) |
+| RSS range | 23.9–24.1 MB | 24.0–24.3 MB | |
+| `sys.modules` count | 229 | 229 | +0 |
+
+### Module count, source LOC, largest module
+
+Tracked source only (`git ls-tree`, same convention as the row above).
+
+| | v0.2.23 | 0.2.24 | delta |
+|---|---|---|---|
+| `.py` files | 75 | 75 | +0 |
+| total LOC | 18,276 | 18,325 | +49 |
+| largest module | `api.py`, 990 | `api.py`, 990 | +0 |
+
+### Why it's flat
+
+This release's only startup-path-adjacent change is the second
+`host_cgroup_memory_limit` advisory (recommending `memory.high` when
+`memory.max` is set on the supervisor's own cgroup): it lives inside the
+probe function already called from the already-loaded `cli/_serve_cgroup`
+module, adds no new import, and only walks its extra branch when a real
+cgroup bound is present at startup. The `doctor` phase-plan resume-time
+addition and the grace-kill test wall-time trim touch neither the startup
+import graph nor any per-round allocation path.
+`tests/invariants/test_import_footprint.py` and
+`tests/invariants/test_round_alloc_growth.py` both stay green unmodified,
+confirming no new eager import and no new per-round leak.
+
+**Suite wall-time**: trimming the grace-kill negative test's sleep cuts
+roughly 80s off the test suite's wall-clock time — a test-only change, not
+reflected in any of the runtime numbers above.
+
 ## Methodology
 
 Machine: macOS 26.6.2, arm64, 16 KB pages. Python 3.11.3 (CPython, pyenv),

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/docs/runbook.md

@@ -748,7 +748,7 @@ host-safety needs are already in-core. Detector rows require a running
 | Runaway round | `[runtime] round_timeout_s` (default 1800) <!-- authored: default round_timeout_s; SSOT agent_runner/config/models.py --> | Wall-clock kill, emits `round_timeout_kill`. For a CLI with no self-timeout (pi has no turn cap, runtime timeout, or token budget) this is the **only** brake. Per-phase override: `[phases.<name>] round_timeout_s` |
 | Cap the agent process itself | `[agent.env]` | Passed verbatim into the round subprocess env and takes precedence over the inherited `os.environ`, so e.g. `NODE_OPTIONS = "--max-old-space-size=384"` reaches a Node-based CLI |
 | Host memory pressure | `mem_pressure` detector + serve-loop admission gate | `host_health`'s signal ladder (PSI → swap-out rate → combined MemFree+MemAvailable low → unavailable) reports `warning` or `critical` — a bare `mem_available_mb` gate is unreliable on cache-poor small-memory hosts. PSI's critical bar is `[monitor.host_health] psi_full_avg10_critical` (default 60.0, i.e. sustained ~60% avg10, not a single 1% blip); `psi_some_avg10_warning` (default 5.0) gates the warning tier. `mem_pressure_gate_inert` fires once if a cache-poor-valid signal shows real pressure while the configured `mem_avail_min_mb` (default 200) gate stays green; `mem_signal_unavailable` fires once when no tier is readable. The detector itself is notify-only (`auto_action="none"`), but `serve` separately **defers the next round** while `host_health` reports **`critical`** pressure only (`round_deferred`/`round_resumed` — a mere `warning` no longer delays a round) and, mid-round, **terminates a ballooning round** once pressure reads `critical` for `mem_critical_consecutive_samples` (default 3) consecutive ~10s ticks in a row (`round_mem_terminated`, `round_mem_critical_sample` per tick, capped at `2 × mem_critical_consecutive_samples` consecutive ticks — 1..6 at the default — so a sustained-critical deferred/off run doesn't write one event per tick for the whole round; any non-critical tick resets both the streak and the cap). `in_round_mem_terminate = false` keeps sampling and counting that streak without ever terminating a round. If this process's cgroup has both `memory.max` and `memory.swap.max` set (`host_cgroup_memory_limit` at startup), the mid-round floor defers to kernel cgroup-OOM instead (`mem_pressure_deferred_to_cgroup`) — the kernel will already contain the agent within that budget. Whole-host figures, not the agent's own share <!-- authored: default mem_avail_min_mb / psi_full_avg10_critical / psi_some_avg10_warning / mem_critical_consecutive_samples; SSOT agent_runner/config/models.py --> |
-| Cgroup swap cap set far below what the host actually has | `host_cgroup_memory_limit` startup event (advisory fields) + one stderr line | Computed once at serve startup, alongside the existing `memory_max`/`memory_swap_max`/`cgroup_path` fields on this SAME event (no new event kind): `swap_total_bytes` (the host's total swap), `swap_cap_pct` (`memory_swap_max` as a percentage of it, `null` when either side is unknown), `memory_high` (the cgroup's `memory.high` soft-throttle threshold in bytes, `null` when unset — the cgroup read the literal `"max"`, or the file/cgroup v2 itself is unavailable), and `advisory` (a warning string, else `null`). When a finite `memory.swap.max` sits under 25% of host swap, `advisory` is set and one `agent-runner: ...` line prints to stderr — this is the blind spot where the mid-round floor can terminate a round the kernel's own cgroup-OOM would have contained on a wider cap. Advisory only: nothing here ever edits the operator's cgroup or systemd unit. The auto-defer decision above also requires `memory_swap_max` to be at most `swap_total_bytes` — a cap far ABOVE host swap can't bind before host-wide swap exhaustion either, so it can't disarm the floor |
+| Cgroup memory bound missing graceful throttling, or a swap cap set far below what the host actually has | `host_cgroup_memory_limit` startup event (advisory fields) + one stderr line | Computed once at serve startup, alongside the existing `memory_max`/`memory_swap_max`/`cgroup_path` fields on this SAME event (no new event kind): `swap_total_bytes` (the host's total swap), `swap_cap_pct` (`memory_swap_max` as a percentage of it, `null` when either side is unknown), `memory_high` (the cgroup's `memory.high` soft-throttle threshold in bytes, `null` when unset — the cgroup read the literal `"max"`, or the file/cgroup v2 itself is unavailable), and `advisory` (one or two warning strings joined with `"; "`, else `null`). One advisory fires when a finite `memory.swap.max` sits under 25% of host swap — this is the blind spot where the mid-round floor can terminate a round the kernel's own cgroup-OOM would have contained on a wider cap. A second, independent advisory fires when `memory.max` is set on the supervisor's OWN cgroup (not an inherited parent slice or container root, where the operator couldn't act on the hint from their own unit anyway) without `memory.high`: it recommends adding `memory.high` below `memory.max` for graceful pre-OOM throttling, plus — only when the mid-round floor ISN'T already deferring to kernel cgroup-OOM — a caveat to also bound `memory.swap.max` or set `in_round_mem_terminate=false`, so the throttle's own PSI-full rise doesn't trip the floor mid-round. Either advisory prints its own `agent-runner: ...` line to stderr. Advisory only: nothing here ever edits the operator's cgroup or systemd unit. The auto-defer decision above also requires `memory_swap_max` to be at most `swap_total_bytes` — a cap far ABOVE host swap can't bind before host-wide swap exhaustion either, so it can't disarm the floor |
 | See cgroup memory pressure BUILDING (not just the terminate/defer verdict) | `round_cgroup_memory` event, once per round | Emitted once per round when this process's cgroup has a finite `memory.max` (see `host_cgroup_memory_limit` above): the round's peak `memory.current`/`memory.swap.current` (the max seen across the existing ~10s mid-round ticks, not the cumulative-since-startup `memory.peak`) and the `memory.events` counter DELTAS over the round (`events_high_delta`/`events_max_delta`/`events_oom_delta`/`events_oom_kill_delta`) — pressure an operator can watch build toward an OOM without SSH-ing in. Deltas, not absolutes: a nonzero `events_oom_kill_delta` means the kernel OOM-killed something inside this round specifically. `bounding_cgroup_path` names the ancestor these figures are read at (deliberately distinct from `host_cgroup_memory_limit`'s `cgroup_path`, which is this process's own leaf cgroup — the two can differ). No-op (nothing emitted) on a host with no finite cgroup bound, or if that bounding cgroup is no longer readable at round end |
 | A round dies to the kernel's own cgroup-OOM, not just a silent 137 | `round_oom_killed` event, folded from the same `round_cgroup_memory` scan | Emitted when `memory.events.oom_kill` rose over the round (the same delta `round_cgroup_memory` already computed — no second read). Pointer-only: `log_path`, `log_bytes`, and `oom_kill_delta`, never the round-log/transcript content itself. `partial_log` reports whether the supervisor appended its own truncation trailer to the round log (a residue marker, not content) so a later reader can tell the tail is supervisor-added. The round still exits 137 and counts toward the crash streak exactly as today — this event only makes the kill legible, it never changes the give-up decision |
 | Disk filling up | `disk_warning` at ≥90%, `disk_critical` at ≥95% | Sampled on `log_dir`'s partition. `disk_critical` auto-stops the service by default; `disk_warning` only alerts. Thresholds under `[monitor.host_health]` <!-- authored: disk_critical ships in the default auto_stop_on set; SSOT agent_runner/config/models.py --> |

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/tests/integration/test_serve_loop.py

@@ -17,7 +17,8 @@ def _write_toml(
     prompt = tmp_git_repo / "p.md"
     prompt.write_text("Body content for serve loop test. " * 50)
     log_dir = tmp_git_repo / "logs"
-    toml.write_text(f"""
+    toml.write_text(
+        f"""
 [agent]
 command = ["{fake_agent}"]
 prompt_arg_template = ["{{prompt}}"]
@@ -28,7 +29,9 @@ round_timeout_s = {round_timeout}
 restart_delay_s = 1
 [prompt]
 file = "{prompt}"
-""" + phases_block)
+"""
+        + phases_block
+    )
     (tmp_git_repo / ".gitignore").write_text("logs/\n")
     subprocess.run(["git", "add", "."], cwd=tmp_git_repo, check=True)
     subprocess.run(

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/tests/unit/test_agent_runtime_grace.py

@@ -165,15 +165,18 @@ def test_run_should_wait_for_ceiling_when_marker_never_matches(tmp_path, monkeyp
     starts a countdown, so the round rides out to the wall-clock ceiling exactly
     like a round that emitted nothing at all.
 
-    Childless (exec) + a generous 45s wall + the 0.1s patched scan interval, all
+    Childless (exec) + a 5s wall + the 0.1s patched scan interval, all
     mirroring test_run_should_start_grace_countdown_when_configured_marker_appears:
     if the match were ever broken (e.g. treating any marker as a hit), this round
-    would be reaped for grace at ~1s -- well before the 45s wall -- so the
+    would be reaped for grace at ~1s -- well before the 5s wall -- so the
     `killed_for_grace is False` below actually exercises the match, it doesn't
     just win a timing race against a 2s wall (see the T3 review finding this test
-    used to be vacuous under). The exec'd sleep must OUTLAST the wall (60s > 45s)
-    -- otherwise the sleep would just exit on its own before timeout_s ever
-    fires, making `timed_out is True` false-fail regardless of the marker logic."""
+    used to be vacuous under). The exec'd sleep is kept at a long 60s (must
+    OUTLAST the wall) -- a short sleep would let the child exit on its own
+    before timeout_s ever fires (a risk under `-n auto` contention, see
+    test_run_should_kill_for_grace_when_agent_has_no_live_children_after_result's
+    docstring above), making `timed_out is True` false-fail regardless of the
+    marker logic; only the wall (timeout_s) shrinks."""
     monkeypatch.setattr(agent_runtime, "_RESULT_SCAN_INTERVAL_S", 0.1)
     script = _write_fake_script(
         tmp_path,
@@ -186,7 +189,7 @@ def test_run_should_wait_for_ceiling_when_marker_never_matches(tmp_path, monkeyp
         command=[str(script)],
         prompt_arg_template=[],
         prompt="x",
-        timeout_s=45,
+        timeout_s=5,
         log_path=log_path,
         env_extra={},
         max_grace_after_result_s=1,
@@ -203,16 +206,19 @@ def test_run_should_disable_marker_grace_when_terminal_marker_empty(tmp_path, mo
     never runs (guarded by `and marker_bytes`) -- no empty-substring-matches-
     everything trap. The round rides out to the wall-clock ceiling.
 
-    Childless (exec) + a generous 45s wall + the 0.1s patched scan interval, all
+    Childless (exec) + a 5s wall + the 0.1s patched scan interval, all
     mirroring test_run_should_start_grace_countdown_when_configured_marker_appears:
     if the `and marker_bytes` guard were ever dropped, an empty marker_bytes is
     a substring of everything, so this round would be reaped for grace at ~1s --
-    well before the 45s wall -- so `killed_for_grace is False` below actually
+    well before the 5s wall -- so `killed_for_grace is False` below actually
     exercises the guard, it doesn't just win a timing race against a 2s wall (see
     the T3 review finding this test used to be vacuous under). The exec'd sleep
-    must OUTLAST the wall (60s > 45s) -- otherwise the sleep would just exit on
-    its own before timeout_s ever fires, making `timed_out is True` false-fail
-    regardless of the marker logic."""
+    is kept at a long 60s (must OUTLAST the wall) -- a short sleep would let the
+    child exit on its own before timeout_s ever fires (a risk under `-n auto`
+    contention, see
+    test_run_should_kill_for_grace_when_agent_has_no_live_children_after_result's
+    docstring above), making `timed_out is True` false-fail regardless of the
+    marker logic; only the wall (timeout_s) shrinks."""
     monkeypatch.setattr(agent_runtime, "_RESULT_SCAN_INTERVAL_S", 0.1)
     script = _write_fake_script(
         tmp_path,
@@ -225,7 +231,7 @@ def test_run_should_disable_marker_grace_when_terminal_marker_empty(tmp_path, mo
         command=[str(script)],
         prompt_arg_template=[],
         prompt="x",
-        timeout_s=45,
+        timeout_s=5,
         log_path=log_path,
         env_extra={},
         max_grace_after_result_s=1,

{cli_agent_runner-0.2.23 → cli_agent_runner-0.2.24}/tests/unit/test_cgroup_probe.py

@@ -97,6 +97,7 @@ def test_cgroup_memory_limits_should_return_both_limits_when_both_finite(
         "memory_max": 335544320,
         "memory_swap_max": 167772160,
         "cgroup_path": _LEAF,
+        "bounding_cgroup_path": _LEAF,
     }
 
 
@@ -141,6 +142,33 @@ def test_cgroup_memory_limits_should_pick_lower_of_leaf_and_ancestor_when_both_f
     assert lim["memory_max"] == 335544320
 
 
+def test_cgroup_memory_limits_should_report_bounding_path_as_the_min_max_owner_when_resolved(
+    fake_cgroup: _FakeCgroup,
+) -> None:
+    """The own leaf sets memory.max itself, so it's also the bounding
+    ancestor -- ``bounding_cgroup_path`` equals ``cgroup_path``."""
+    fake_cgroup(memory_max="335544320", memory_swap_max="167772160")
+
+    lim = metrics.cgroup_memory_limits(root=fake_cgroup.root, self_cgroup=fake_cgroup.self_cgroup)
+
+    assert lim["bounding_cgroup_path"] == lim["cgroup_path"]
+
+
+def test_cgroup_memory_limits_should_report_bounding_path_as_the_ancestor_when_leaf_unlimited(
+    fake_cgroup: _FakeCgroup,
+) -> None:
+    """The leaf itself is unlimited; a parent slice owns the real budget --
+    ``bounding_cgroup_path`` names that ancestor, NOT the (looser) leaf, so a
+    caller can tell an inherited bound from an own-scope one."""
+    fake_cgroup(memory_max="max", memory_swap_max="max")
+    fake_cgroup.set_limit("/system.slice", memory_max="335544320", memory_swap_max="167772160")
+
+    lim = metrics.cgroup_memory_limits(root=fake_cgroup.root, self_cgroup=fake_cgroup.self_cgroup)
+
+    assert lim["bounding_cgroup_path"] == "/system.slice"
+    assert lim["bounding_cgroup_path"] != lim["cgroup_path"]
+
+
 def test_cgroup_memory_limits_should_return_all_none_when_cgroup_v1_or_missing(
     fake_cgroup: _FakeCgroup,
 ) -> None:
@@ -151,7 +179,12 @@ def test_cgroup_memory_limits_should_return_all_none_when_cgroup_v1_or_missing(
 
     lim = metrics.cgroup_memory_limits(root=fake_cgroup.root, self_cgroup=fake_cgroup.self_cgroup)
 
-    assert lim == {"memory_max": None, "memory_swap_max": None, "cgroup_path": None}
+    assert lim == {
+        "memory_max": None,
+        "memory_swap_max": None,
+        "cgroup_path": None,
+        "bounding_cgroup_path": None,
+    }
 
 
 def test_cgroup_memory_limits_should_parse_self_cgroup_from_proc_file(tmp_path: Path) -> None:
@@ -176,6 +209,7 @@ def test_cgroup_memory_limits_should_parse_self_cgroup_from_proc_file(tmp_path:
         "memory_max": 335544320,
         "memory_swap_max": 167772160,
         "cgroup_path": "/system.slice/example.service",
+        "bounding_cgroup_path": "/system.slice/example.service",
     }
 
 
@@ -190,7 +224,12 @@ def test_cgroup_memory_limits_should_return_all_none_when_proc_self_cgroup_missi
 
     lim = metrics.cgroup_memory_limits(root=root, proc_self_cgroup=tmp_path / "does-not-exist")
 
-    assert lim == {"memory_max": None, "memory_swap_max": None, "cgroup_path": None}
+    assert lim == {
+        "memory_max": None,
+        "memory_swap_max": None,
+        "cgroup_path": None,
+        "bounding_cgroup_path": None,
+    }
 
 
 # --- 0.2.18 T1c fix round 1: cgroup_memory_high, a REAL memory.high read ---
@@ -277,15 +316,22 @@ def _patch_probe(
     monkeypatch,
     *,
     memory_max: int | None,
-    memory_swap_max: int,
+    memory_swap_max: int | None,
     mem_total: int,
     swap_total: int,
     memory_high: int | None = None,
+    cgroup_path: str | None = "/x",
+    bounding_cgroup_path: str | None = "/x",
 ):
     monkeypatch.setattr(
         metrics,
         "cgroup_memory_limits",
-        lambda: {"memory_max": memory_max, "memory_swap_max": memory_swap_max, "cgroup_path": "/x"},
+        lambda: {
+            "memory_max": memory_max,
+            "memory_swap_max": memory_swap_max,
+            "cgroup_path": cgroup_path,
+            "bounding_cgroup_path": bounding_cgroup_path,
+        },
     )
     monkeypatch.setattr(metrics, "mem_total_bytes", lambda: mem_total)
     monkeypatch.setattr(metrics, "swap_total_bytes", lambda: swap_total)
@@ -369,7 +415,9 @@ def test_probe_and_emit_cgroup_defer_should_gate_on_limit_plausibility(
         pytest.param(
             200_000_000, 12.5, True, "swap.max is far below host swap", id="far_below_host"
         ),
-        pytest.param(1_280_000_000, 80.0, False, None, id="within_host"),
+        pytest.param(
+            1_280_000_000, 80.0, True, "memory.high", id="within_host_swap_but_memory_high_unset"
+        ),
     ],
 )
 def test_probe_and_emit_cgroup_defer_should_gate_advisory_on_swap_cap_pct(
@@ -383,8 +431,10 @@ def test_probe_and_emit_cgroup_defer_should_gate_advisory_on_swap_cap_pct(
 ) -> None:
     """swap.max below the 25% advisory floor (here 12.5% of host swap) rides
     as fields on the EXISTING host_cgroup_memory_limit event -- not a new
-    kind -- plus one stderr line; a plausible cap (80%) gets neither. Never
-    changes the cgroup/unit either way."""
+    kind -- plus one stderr line; a plausible cap (80%) gets no swap-cap
+    advisory, but BOTH cases still leave memory.high unset on the own leaf,
+    so both also carry the memory.high hint (joined onto the swap-cap one
+    for the far-below-host case). Never changes the cgroup/unit either way."""
     from agent_runner.cli._serve_cgroup import _probe_and_emit_cgroup_defer
 
     _patch_probe(
@@ -409,6 +459,7 @@ def test_probe_and_emit_cgroup_defer_should_gate_advisory_on_swap_cap_pct(
     assert ev["swap_cap_pct"] == expected_swap_cap_pct
     assert ev["memory_high"] is None
     assert (ev["advisory"] is not None) is expect_advisory
+    assert "memory.high" in ev["advisory"]
 
     captured = capsys.readouterr()
     if expected_stderr_substring is None:
@@ -446,3 +497,136 @@ def test_probe_and_emit_cgroup_defer_should_emit_real_memory_high_when_set(
         for line in f.read_text().splitlines()
     ]
     assert ev["memory_high"] == 192_000_000
+
+
+# --- 0.2.24 T1: the memory.high advisory, own-scope-gated + defer-aware ---
+#
+# memory.max set (anywhere on the ancestor chain) without memory.high means
+# the operator has a hard kill ceiling but no soft pre-OOM throttle -- worth
+# flagging. But cgroup_memory_limits reports memory.max as the MIN across
+# ALL ancestors, so "set" can also mean an inherited parent slice or a
+# container root, where "add MemoryHigh" is noise the operator can't act on
+# from their own unit. The hint fires ONLY when the bounding ancestor IS the
+# operator's own leaf (bounding_cgroup_path == cgroup_path), and only
+# appends the PSI-floor swap caveat when the mid-round floor isn't already
+# deferring to kernel cgroup-OOM. Advisory only -- never writes a cgroup or
+# unit file.
+
+
+def _run_probe(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, **kwargs) -> None:
+    from agent_runner.cli._serve_cgroup import _probe_and_emit_cgroup_defer
+
+    _patch_probe(monkeypatch, **kwargs)
+    log_dir = tmp_path / "logs"
+    log_dir.mkdir()
+    _probe_and_emit_cgroup_defer(log_dir)
+
+
+def _only_event(tmp_path: Path) -> dict:
+    log_dir = tmp_path / "logs"
+    [ev] = [
+        json.loads(line)
+        for f in sorted(log_dir.glob("events-*.jsonl"))
+        for line in f.read_text().splitlines()
+    ]
+    return ev
+
+
+def test_advisory_should_not_hint_memory_high_when_bound_is_an_inherited_ancestor(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # memory.max finite but owned by a PARENT slice, not the operator's leaf -> no hint
+
+    _run_probe(
+        monkeypatch,
+        tmp_path,
+        memory_max=256_000_000,
+        memory_swap_max=1_280_000_000,
+        mem_total=462_000_000,
+        swap_total=1_600_000_000,
+        memory_high=None,
+        bounding_cgroup_path="/system.slice",
+    )
+
+    ev = _only_event(tmp_path)
+    assert ev["advisory"] is None
+
+
+def test_advisory_should_omit_memory_high_hint_when_high_already_set(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # high already set -> no hint (and no swap-cap advisory here either)
+
+    _run_probe(
+        monkeypatch,
+        tmp_path,
+        memory_max=256_000_000,
+        memory_swap_max=1_280_000_000,
+        mem_total=462_000_000,
+        swap_total=1_600_000_000,
+        memory_high=224_000_000,
+    )
+
+    ev = _only_event(tmp_path)
+    assert ev["advisory"] is None
+
+
+def test_advisory_memory_high_hint_should_omit_swap_caveat_when_already_deferring(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # both-finite + plausible -> floor defers -> hint fires WITHOUT the "bound swap" caveat
+
+    _run_probe(
+        monkeypatch,
+        tmp_path,
+        memory_max=256_000_000,
+        memory_swap_max=1_280_000_000,
+        mem_total=462_000_000,
+        swap_total=1_600_000_000,
+        memory_high=None,
+    )
+
+    ev = _only_event(tmp_path)
+    assert "memory.high" in ev["advisory"]
+    assert "swap" not in ev["advisory"].lower()
+
+
+def test_advisory_memory_high_hint_should_include_swap_caveat_when_not_deferring(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # memory.max bounded but memory.swap.max UNBOUNDED -> floor stays armed (no defer) -> caveat
+
+    _run_probe(
+        monkeypatch,
+        tmp_path,
+        memory_max=256_000_000,
+        memory_swap_max=None,
+        mem_total=462_000_000,
+        swap_total=1_600_000_000,
+        memory_high=None,
+    )
+
+    ev = _only_event(tmp_path)
+    assert "memory.high" in ev["advisory"]
+    assert "swap" in ev["advisory"].lower()
+
+
+def test_advisory_should_be_none_when_cgroup_v2_unavailable(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    # no cgroup v2 -> memory_max/cgroup_path/bounding_cgroup_path all None -> own_scope stays inert
+
+    _run_probe(
+        monkeypatch,
+        tmp_path,
+        memory_max=None,
+        memory_swap_max=None,
+        mem_total=462_000_000,
+        swap_total=1_600_000_000,
+        memory_high=None,
+        cgroup_path=None,
+        bounding_cgroup_path=None,
+    )
+
+    ev = _only_event(tmp_path)
+    assert ev["advisory"] is None