cli-agent-runner 0.3.6__tar.gz → 0.3.7__tar.gz

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/.vulture-whitelist.py

@@ -195,6 +195,7 @@ supervisor_stale_threshold_s
 disk
 memory
 pressure
+brake
 
 # agent_runner.config.models.PhaseOverride
 round_budget_s
@@ -255,6 +256,11 @@ pause_windows
 stash_idempotency_s
 dirty_action
 
+# agent_runner.config.models._HostHealthBrakeConfig
+memory_high
+memory_high_step_pct
+warning_consecutive_samples
+
 # agent_runner.config.models._HostHealthDiskConfig
 warning_pct
 critical_pct
@@ -270,6 +276,7 @@ some_avg10_warning
 critical_consecutive_samples
 in_round_terminate
 cgroup_growth_rate_warning_mb_per_min
+in_round_nudge
 
 # agent_runner.context_store.OrphanState
 round_num

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.7] - 2026-09-15
+
+### Added
+- Opt-in cgroup v2 `memory.high` soft-brake (`[monitor.host_health.brake] memory_high`, default off): under sustained warning-level memory pressure the supervisor reversibly writes `memory.high` on its OWN cgroup leaf to throttle a growing round before the host swaps, then restores it on recovery or at round end. `memory_high_step_pct` defaults to `0` = cap-at-current (throttle further growth with no synchronous reclaim burst — safe for SD-backed hosts); `step_pct >= 1` is opt-in aggressive reclaim that dumps ~step% of the leaf to swap at engage. Fail-open; arms only when the leaf is delegated.
+- Opt-in early cooperative SIGTERM (`[monitor.host_health.pressure] in_round_nudge`, default off): fires the hard floor's SIGTERM two samples earlier so a cooperative agent gets its wrap-up grace; recorded as `round_mem_terminated` with a new `tier` field so the mem-loop give-up still converges.
+- New events `memory_high_engaged` / `memory_high_released` / `memory_high_write_failed`; `doctor` and `peek --json` (schema `2.5`) report the brake as `off | armed | inert(<reason>)`.
+
 ## [0.3.6] - 2026-09-15
 
 ### Changed

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/PKG-INFO

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

@@ -32,6 +32,9 @@ from agent_runner._emit.memory import (  # noqa: F401 — public re-export
     emit_cgroup_growth_rate_warning,
     emit_host_cgroup_memory_limit,
     emit_mem_pressure_deferred_to_cgroup,
+    emit_memory_high_engaged,
+    emit_memory_high_released,
+    emit_memory_high_write_failed,
     emit_round_cgroup_memory,
     emit_round_deferred,
     emit_round_mem_critical_sample,
@@ -88,6 +91,9 @@ __all__ = [
     "emit_mem_loop",
     "emit_mem_loop_persistent",
     "emit_mem_pressure_deferred_to_cgroup",
+    "emit_memory_high_engaged",
+    "emit_memory_high_released",
+    "emit_memory_high_write_failed",
     "emit_plugin_builtin_name_squat",
     "emit_plugin_checksum_mismatch",
     "emit_plugin_sandbox_degraded",

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/_emit/memory.py

@@ -36,6 +36,7 @@ def emit_round_mem_terminated(
     message: str,
     consecutive: int,
     context: dict,
+    tier: str = "terminate",
 ) -> None:
     """Emit when _spawn_round's mid-round hard floor terminated a ballooning
     round on critical host_health pressure -- the actual coma-preventer (a
@@ -45,7 +46,15 @@ def emit_round_mem_terminated(
     ``consecutive`` (the critical_streak that crossed the threshold)
     and ``context`` (Pressure.context -- the actual psi/mem numbers, e.g.
     psi_full_avg10) make the kill legible from the event stream alone, so an
-    operator can retune host_health thresholds without SSH."""
+    operator can retune host_health thresholds without SSH.
+
+    ``tier`` (``"terminate"`` | ``"nudge"``) distinguishes the hard floor's
+    ``_terminate_round`` (TERM -> grace -> killpg) from the early cooperative
+    nudge (a bare ``proc.terminate()`` two samples earlier, no wait, no
+    killpg) -- both fire this SAME event kind so ``round_was_mem_terminated``
+    and the ``mem_loop`` give-up breaker count a nudged round exactly like a
+    hard-terminated one; the default keeps every existing caller byte-
+    compatible."""
     from agent_runner.events import ROUND_MEM_TERMINATED, emit
 
     emit(
@@ -57,6 +66,7 @@ def emit_round_mem_terminated(
         message=message,
         consecutive=consecutive,
         context=context,
+        tier=tier,
     )
 
 
@@ -246,6 +256,59 @@ def emit_mem_pressure_deferred_to_cgroup(
     emit(log_dir, MEM_PRESSURE_DEFERRED_TO_CGROUP, pid=pid, signal=signal, message=message)
 
 
+def emit_memory_high_engaged(
+    log_dir: Path,
+    *,
+    round_num: int,
+    previous: str,
+    written: int,
+    memory_current: int,
+    write_ms: int,
+    signal: str,
+    context: dict,
+    rate_mb_per_min: float | None,
+) -> None:
+    """Emit when the reversible cgroup memory.high soft-brake engaged on serve's
+    own leaf under sustained warning pressure. ``previous``/``written`` bracket
+    the reversible write; ``signal``/``context`` are the triggering Pressure;
+    ``rate_mb_per_min`` rides along as growth-rate context for Pi calibration."""
+    from agent_runner.events import MEMORY_HIGH_ENGAGED, emit
+
+    emit(
+        log_dir,
+        MEMORY_HIGH_ENGAGED,
+        round_num=round_num,
+        previous=previous,
+        written=written,
+        memory_current=memory_current,
+        write_ms=write_ms,
+        signal=signal,
+        context=context,
+        rate_mb_per_min=rate_mb_per_min,
+    )
+
+
+def emit_memory_high_released(log_dir: Path, *, round_num: int, reason: str) -> None:
+    """Emit when the soft-brake was restored to its stashed value. ``reason`` is
+    ``recovered`` (N healthy ticks) or ``round_end`` (the finally restore, which
+    covers every exit path out of the round incl. wedged/exception)."""
+    from agent_runner.events import MEMORY_HIGH_RELEASED, emit
+
+    emit(log_dir, MEMORY_HIGH_RELEASED, round_num=round_num, reason=reason)
+
+
+def emit_memory_high_write_failed(log_dir: Path, *, round_num: int, errno: int | None) -> None:
+    """Emit once when a memory.high write (engage or restore) hit an OSError --
+    fail-open: the brake disarms for the round and serve continues unthrottled,
+    exactly as when the brake is configured off. ``errno`` is the real OSError
+    code from the engage path; the restore path (which only sees a bool from
+    :func:`agent_runner.metrics.restore_leaf_memory_high`) passes ``None`` --
+    never ``0``, which conventionally reads as POSIX success."""
+    from agent_runner.events import MEMORY_HIGH_WRITE_FAILED, emit
+
+    emit(log_dir, MEMORY_HIGH_WRITE_FAILED, round_num=round_num, errno=errno)
+
+
 def emit_cgroup_growth_rate_warning(
     log_dir: Path,
     *,

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/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.6'
-__version_tuple__ = version_tuple = (0, 3, 6)
+__version__ = version = '0.3.7'
+__version_tuple__ = version_tuple = (0, 3, 7)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/api.py

@@ -41,6 +41,9 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_mem_loop,
     emit_mem_loop_persistent,
     emit_mem_pressure_deferred_to_cgroup,
+    emit_memory_high_engaged,
+    emit_memory_high_released,
+    emit_memory_high_write_failed,
     emit_plugin_builtin_name_squat,
     emit_plugin_checksum_mismatch,
     emit_plugin_sandbox_degraded,

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/cli/_serve_cgroup.py

@@ -22,6 +22,8 @@ from agent_runner import metrics
 from agent_runner._serve_policy import _ROUND_UNREAPED_RC
 from agent_runner.api import (
     emit_host_cgroup_memory_limit,
+    emit_memory_high_released,
+    emit_memory_high_write_failed,
     emit_round_cgroup_memory,
     emit_round_oom_killed,
 )
@@ -37,6 +39,27 @@ from agent_runner.api import (
 # round.
 _ROUND_CGROUP_STATE_BY_LOG_DIR: dict[Path, dict] = {}
 
+# Boot-armed soft-brake gate: True iff the brake is configured on AND this
+# process's own cgroup leaf is delegated (memory.high writable) -- probed ONCE
+# at serve boot (_probe_and_emit_cgroup_defer already reads cgroup_delegated),
+# read every mid-round tick by _serve_round via _brake_step_for. Same
+# per-log_dir stable-default pattern as _ROUND_CGROUP_STATE_BY_LOG_DIR (one
+# entry per serve process in production); cmd() cannot grow to thread it (145
+# budget), so it rides in a module dict, not an argument.
+_BRAKE_ARMED_BY_LOG_DIR: dict[Path, bool] = {}
+
+
+def _brake_step_for(log_dir: Path, host_health_cfg) -> int | None:
+    """The armed soft-brake step_pct for this log_dir, or None when the brake is
+    disarmed: config off, or the boot probe found the leaf undelegated / no
+    cgroup v2. The step itself is single-sourced from config; the dict only
+    carries the boot-time delegated-and-on decision."""
+    if not host_health_cfg.brake.memory_high:
+        return None
+    if not _BRAKE_ARMED_BY_LOG_DIR.get(log_dir, False):
+        return None
+    return host_health_cfg.brake.memory_high_step_pct
+
 
 def _stash_round_cgroup_state(
     log_dir: Path, cg_base: dict, peak_current: int, peak_swap: int
@@ -190,18 +213,69 @@ 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.
+# The delegation-readiness / brake-inert advisory. Fires in two DISTINCT
+# cases, both meaning "memory.high can't be written from here":
+#   (1) delegated is False (CONFIRMED not delegated -- systemd Delegate=yes
+#       is absent) AND memory.max/memory.high are already bound (memory_high
+#       set, or the own_scope "add memory.high" hint above just fired) --
+#       the existing config is informational-only without delegation.
+#   (2) the operator explicitly turned the soft-brake on
+#       ([monitor.host_health.brake] memory_high=true, threaded in here as
+#       brake_memory_high) but delegated is not True (False OR None) -- the
+#       brake will silently do nothing, worth announcing at boot even with
+#       no memory.max/memory.high configured yet.
+# Deliberately NOT ``delegated is not True`` across the board: cgroup_delegated
+# returns None for two different reasons -- cgroup v2 unavailable (harmless)
+# AND the leaf's own os.stat() raising OSError (delegation status genuinely
+# UNKNOWN, even though memory_high/own_scope's ancestor-walk resolved fine).
+# Broadening case (1) to None would assert "not writable" where we actually
+# don't know -- an overclaim this release can't afford. Case (2) is the one
+# exception: the operator asked for the brake, so ANY non-confirmed-delegated
+# state (False or unknown) is worth flagging as "may be inert" up front.
+# 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"
+    "memory.high on this cgroup is not writable by this process; the soft-brake "
+    "is inert. Run serve as a user-mode unit (`systemctl --user` + `loginctl "
+    "enable-linger`) or as a root system unit."
 )
 
 
-def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
+def brake_report_state(enabled: bool, delegated: bool | None) -> str:
+    """The operator-facing soft-brake state for doctor/peek: ``off`` (not
+    configured), ``armed`` (on AND the leaf is delegated so memory.high is
+    writable), or ``inert(<reason>)`` (on but the write path can't arm)."""
+    if not enabled:
+        return "off"
+    if delegated is True:
+        return "armed"
+    return "inert(undelegated)" if delegated is False else "inert(no cgroup v2)"
+
+
+def current_brake_state(cfg) -> str:
+    """Resolve the soft-brake state string for `cfg` from live cgroup facts --
+    the one-shot ``cgroup_memory_limits() -> cgroup_delegated(self_cgroup=...) ->
+    brake_report_state`` sequence, shared by peek (cli.common.emit) and doctor
+    so neither re-derives it inline."""
+    limits = metrics.cgroup_memory_limits()
+    delegated = metrics.cgroup_delegated(self_cgroup=limits["cgroup_path"])
+    return brake_report_state(cfg.monitor.host_health.brake.memory_high, delegated)
+
+
+def _release_brake(log_dir: Path, round_num: int, previous: str, *, reason: str) -> bool:
+    """Restore memory.high on serve's own leaf to `previous` and emit the
+    matching event: ``memory_high_released`` on success, ``memory_high_write_failed``
+    (errno None -- restore only yields a bool) on OSError. Returns whether the
+    restore succeeded; callers own their own brake_engaged/brake_previous/
+    brake_restore_failed transitions off that result. Shared by _spawn_round's
+    mid-round recovery-release site and its unconditional round-end finally."""
+    if metrics.restore_leaf_memory_high(previous):
+        emit_memory_high_released(log_dir, round_num=round_num, reason=reason)
+        return True
+    emit_memory_high_write_failed(log_dir, round_num=round_num, errno=None)
+    return False
+
+
+def _probe_and_emit_cgroup_defer(log_dir: Path, *, brake_memory_high: bool = False) -> bool:
     """Probe this process's cgroup v2 memory budget once at serve startup,
     emit host_cgroup_memory_limit for observability, and return whether the
     mid-round hard floor should defer to kernel cgroup-OOM: True only when
@@ -249,8 +323,22 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     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
-    cgroup or systemd unit."""
+    release's field ask.
+
+    A THIRD advisory, ``_UNDELEGATED_HINT``, reads ``brake_memory_high`` --
+    the caller-supplied ``[monitor.host_health.brake] memory_high`` config
+    switch -- alongside ``delegated``: when the operator turned that brake
+    on but this process's own cgroup leaf isn't confirmed delegated
+    (``delegated is not True``), the brake would silently write nothing, so
+    boot announces it up front even with no memory.max/memory.high
+    configured. Independently of the brake, the SAME hint also covers the
+    pre-existing "config is informational without delegation" case
+    (``delegated is False`` -- CONFIRMED not delegated, never the merely
+    unresolved ``None``) when memory_high is already set or the own_scope
+    hint above just fired. See the comment block above ``_UNDELEGATED_HINT``
+    for why those two triggers use different ``delegated`` strictness.
+    Advisory only -- this never changes the operator's cgroup or systemd
+    unit."""
     limits = metrics.cgroup_memory_limits()
     swap_total = metrics.swap_total_bytes()
     # Reuse the leaf cgroup_memory_limits already resolved above -- skips
@@ -263,6 +351,8 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     # 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"])
+    if brake_memory_high:
+        _BRAKE_ARMED_BY_LOG_DIR[log_dir] = delegated is True
     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
@@ -299,7 +389,9 @@ 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):
+    if (brake_memory_high and delegated is not True) or (
+        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:

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/cli/_serve_round.py

@@ -62,6 +62,8 @@ from agent_runner.api import (
     emit_mem_loop,
     emit_mem_loop_persistent,
     emit_mem_pressure_deferred_to_cgroup,
+    emit_memory_high_engaged,
+    emit_memory_high_write_failed,
     emit_plugin_spawn_decision,
     emit_plugin_spawn_override_ignored,
     emit_round_deferred,
@@ -74,8 +76,10 @@ from agent_runner.api import (
 )
 from agent_runner.api_types import SpawnDecision
 from agent_runner.cli._serve_cgroup import (
+    _brake_step_for,
     _emit_round_cgroup_memory,
     _maybe_emit_oom_killed,
+    _release_brake,
     _stash_round_cgroup_state,
 )
 from agent_runner.clock import SYSTEM_CLOCK, Clock
@@ -461,8 +465,8 @@ _MEM_CHECK_INTERVAL_S = 10
 
 
 def _mid_round_action(
-    cfg, defer_to_cgroup: bool, critical_streak: int
-) -> Literal["terminate", "defer", "count_only"]:
+    cfg, defer_to_cgroup: bool, critical_streak: int, nudged: bool
+) -> Literal["terminate", "defer", "count_only", "nudge"]:
     """Pure, subprocess-free verdict for a critical mid-round
     tick, once the caller has already incremented ``critical_streak`` and
     (when the streak is within the emit cap) emitted
@@ -484,13 +488,29 @@ def _mid_round_action(
     - ``"terminate"`` — sustained critical pressure, no cgroup containment to
       defer to: the caller ``_terminate_round``s and emits
       ``round_mem_terminated``.
+    - ``"nudge"`` -- ``in_round_nudge`` is on and this is the FIRST critical
+      sample (``critical_streak == 1``, ``nudged`` still False) of a streak whose
+      hard verdict WOULD be ``terminate`` (``in_round_terminate`` and not
+      ``defer_to_cgroup``): fire the hard floor's SIGTERM at the first critical
+      sample (not the sustained threshold) so a cooperative agent gets its
+      wrap-up grace. ``defer_to_cgroup`` disables the nudge (no terminate to
+      move earlier) but NOT the brake -- so does ``critical_consecutive_samples
+      == 1``, since the hard verdict above already matches at streak 1.
     """
-    if not (
+    if (
         cfg.pressure.in_round_terminate
         and critical_streak >= cfg.pressure.critical_consecutive_samples
     ):
-        return "count_only"
-    return "defer" if defer_to_cgroup else "terminate"
+        return "defer" if defer_to_cgroup else "terminate"
+    if (
+        cfg.pressure.in_round_nudge
+        and not nudged
+        and critical_streak == 1
+        and cfg.pressure.in_round_terminate
+        and not defer_to_cgroup
+    ):
+        return "nudge"
+    return "count_only"
 
 
 def _spawn_round(
@@ -586,6 +606,12 @@ def _spawn_round(
             stderr=subprocess.STDOUT,
             start_new_session=True,
         )
+        brake_engaged = False
+        brake_previous: str | None = None
+        brake_disarmed = False
+        brake_restore_failed = False
+        warning_streak = 0
+        none_streak = 0
         try:
             deadline = clock.monotonic() + timeout_s
             next_mem_check = (
@@ -600,6 +626,7 @@ def _spawn_round(
             # terminates the round.
             prev_tick_sample: dict | None = None
             critical_streak = 0
+            nudged = False
             cgroup_defer_notified = False
             prev_mem_bytes: int | None = None
             prev_mem_mono: float | None = None
@@ -644,6 +671,7 @@ def _spawn_round(
                         cur_sample, prev_tick_sample, host_health_cfg
                     )
                     prev_tick_sample = cur_sample
+                    rate_mb_per_min: float | None = None
                     if cg_base:
                         cg_now = metrics.cgroup_memory_usage(bounding_cgroup=cg_bounding)
                         cg_peak_current = max(cg_peak_current, cg_now.get("memory_current", 0))
@@ -655,7 +683,6 @@ def _spawn_round(
                         mem_source = "rss_sum"
                     now_mono = clock.monotonic()
                     if cur_mem_bytes is not None:
-                        rate_mb_per_min = None
                         if prev_mem_bytes is not None and prev_mem_mono is not None:
                             elapsed_s = max(now_mono - prev_mem_mono, 0.0)
                             rate_mb_per_min = (
@@ -692,6 +719,55 @@ def _spawn_round(
                     # (a {}/None source read). Keep prev_mem_bytes/prev_mem_mono
                     # untouched so the NEXT successful tick still diffs against
                     # the last real reading, not a spurious reset.
+                    if pressure is not None:
+                        warning_streak += 1
+                        none_streak = 0
+                    else:
+                        warning_streak = 0
+                        none_streak += 1
+                        if (
+                            brake_engaged
+                            and brake_previous is not None
+                            and not brake_restore_failed
+                            and none_streak >= host_health_cfg.brake.warning_consecutive_samples
+                        ):
+                            if _release_brake(
+                                log_dir, round_num, brake_previous, reason="recovered"
+                            ):
+                                brake_engaged = False
+                                brake_previous = None
+                            else:
+                                brake_restore_failed = True
+                    brake_step = _brake_step_for(log_dir, host_health_cfg)
+                    if (
+                        pressure is not None
+                        and brake_step is not None
+                        and not brake_disarmed
+                        and not brake_engaged
+                        and warning_streak >= host_health_cfg.brake.warning_consecutive_samples
+                    ):
+                        t0 = clock.monotonic()
+                        result = metrics.engage_leaf_memory_high(step_pct=brake_step)
+                        write_ms = int((clock.monotonic() - t0) * 1000)
+                        if result.get("engaged"):
+                            brake_engaged = True
+                            brake_previous = result["previous"]
+                            emit_memory_high_engaged(
+                                log_dir,
+                                round_num=round_num,
+                                previous=result["previous"],
+                                written=result["written"],
+                                memory_current=result["memory_current"],
+                                write_ms=write_ms,
+                                signal=pressure.signal,
+                                context=pressure.context,
+                                rate_mb_per_min=rate_mb_per_min,
+                            )
+                        elif "errno" in result:
+                            emit_memory_high_write_failed(
+                                log_dir, round_num=round_num, errno=result["errno"]
+                            )
+                            brake_disarmed = True
                     if pressure is not None and pressure.severity == "critical":
                         critical_streak += 1
                         if (
@@ -705,9 +781,22 @@ def _spawn_round(
                                 context=pressure.context,
                             )
                         action = _mid_round_action(
-                            host_health_cfg, defer_to_cgroup, critical_streak
+                            host_health_cfg, defer_to_cgroup, critical_streak, nudged
                         )
-                        if action == "terminate":
+                        if action == "nudge":
+                            nudged = True
+                            proc.terminate()  # bare SIGTERM to the leader -- NO wait, NO killpg
+                            emit_round_mem_terminated(
+                                log_dir,
+                                pid=proc.pid,
+                                severity=pressure.severity,
+                                signal=pressure.signal,
+                                message=pressure.message,
+                                consecutive=critical_streak,
+                                context=pressure.context,
+                                tier="nudge",
+                            )
+                        elif action == "terminate":
                             returncode = _terminate_round(proc, clock=clock)
                             emit_round_mem_terminated(
                                 log_dir,
@@ -717,10 +806,11 @@ def _spawn_round(
                                 message=pressure.message,
                                 consecutive=critical_streak,
                                 context=pressure.context,
+                                tier="terminate",
                             )
                             _stash_cgroup()
                             return returncode
-                        if action == "defer" and not cgroup_defer_notified:
+                        elif action == "defer" and not cgroup_defer_notified:
                             emit_mem_pressure_deferred_to_cgroup(
                                 log_dir,
                                 pid=proc.pid,
@@ -736,6 +826,17 @@ def _spawn_round(
             # exception-path cleanup: never orphan the round pgroup
             _terminate_round(proc, clock=clock)
             raise
+        finally:
+            # Unconditional restore (mirrors _stash_cgroup): runs on every exit path out of the try
+            # above -- both mid-loop returns, the exception re-raise, and the wedged fall-through
+            # below. A skipped write here leaves the cgroup throttled indefinitely. _release_brake's
+            # restore is fail-open (never raises); its best-effort emit is shielded here, so a
+            # disk-full OSError can never replace the ORIGINAL propagating exception.
+            if brake_engaged and brake_previous is not None:
+                try:
+                    _release_brake(log_dir, round_num, brake_previous, reason="round_end")
+                except Exception:
+                    pass
         # Safety kill BEFORE the observability write: the wedged round must not
         # keep burning wall-clock (and, if its own reap hangs, its agent's
         # budget) waiting on the least-reliable step (a disk write) to finish

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/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.4"
+PEEK_SCHEMA_VERSION = "2.5"
 
 
 def cfg_from_args(args) -> Config:
@@ -123,6 +123,10 @@ def emit(value: Any, *, json_mode: bool, cfg: Config | None = None) -> None:
                 "plugins": plugins_block,
                 **_to_jsonable(value),
             }
+            if cfg is not None:
+                from agent_runner.cli._serve_cgroup import current_brake_state
+
+                wrapped["brake"] = current_brake_state(cfg)
             print(json.dumps(wrapped, indent=2, default=str))
         else:
             print(json.dumps(_to_jsonable(value), indent=2, default=str))

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/cli/doctor_cmd.py

@@ -45,20 +45,23 @@ def _plan(cfg, rounds: int) -> list[dict]:
     return out
 
 
-def _cgroup_report() -> dict:
+def _cgroup_report(cfg) -> 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
+    from agent_runner.cli._serve_cgroup import brake_report_state
 
     limits = metrics.cgroup_memory_limits()
+    delegated = metrics.cgroup_delegated(self_cgroup=limits["cgroup_path"])
     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"]),
+        "delegated": delegated,
+        "brake": brake_report_state(cfg.monitor.host_health.brake.memory_high, delegated),
     }
 
 
@@ -79,7 +82,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(),
+        cgroup=_cgroup_report(cfg),
         sigterm_grace=sigterm_grace,
     )
     json_mode = getattr(args, "json", False)
@@ -143,7 +146,21 @@ def _format(report: DoctorReport) -> str:
     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:
+    lines.append(f"  brake: {cgroup['brake']}")
+    # Approximates serve's own advisory (_serve_cgroup._probe_and_emit_cgroup_defer):
+    # only surface the "soft-brake is inert" hint when it could actually apply --
+    # the brake is enabled (report.cgroup["brake"] != "off") or a memory_high/
+    # memory_max limit is already bound. Otherwise the brake is at its default
+    # (off) with nothing bound, and the hint would contradict "brake: off" above.
+    # Coarser than serve's own_scope (which additionally requires the bound to
+    # originate from the caller's OWN leaf, not an inherited ancestor) -- doctor's
+    # _cgroup_report never tracks the bounding cgroup path, so this errs toward
+    # showing the readiness hint in the ancestor-bound case.
+    if cgroup["delegated"] is False and (
+        cgroup["brake"] != "off"
+        or cgroup["memory_high"] is not None
+        or cgroup["memory_max"] is not None
+    ):
         from agent_runner.cli._serve_cgroup import _UNDELEGATED_HINT
 
         lines.append(f"  hint: {_UNDELEGATED_HINT}")

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/cli/serve_cmd.py

@@ -744,7 +744,8 @@ def cmd(args) -> int:
     work_dir = cfg.runtime.work_dir
     # Emitted exactly once per serve lifetime -- the per-round defer decision below
     # reuses this bool rather than re-probing/re-emitting every round.
-    cgroup_probe_defer = _probe_and_emit_cgroup_defer(log_dir)
+    brake_memory_high = cfg.monitor.host_health.brake.memory_high
+    cgroup_probe_defer = _probe_and_emit_cgroup_defer(log_dir, brake_memory_high=brake_memory_high)
     # Static config check -- phase-window collisions can't change mid-lifetime, so
     # (like the cgroup probe above) this runs once at boot, not once per round.
     overlaps = phase_select.find_phase_window_overlaps(cfg)

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.7}/agent_runner/config/__init__.py

@@ -49,6 +49,7 @@ from agent_runner.config.models import (  # noqa: F401 — public re-export
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
     _HostHealthPressureConfig,