cli-agent-runner 0.2.14__tar.gz → 0.2.15__tar.gz

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/.vulture-whitelist.py

@@ -148,6 +148,8 @@ supervisor_stale_threshold_s
 mem_avail_min_mb
 disk_warning_pct
 disk_critical_pct
+swap_sout_noise_floor_mb
+mem_free_low_mb
 
 # agent_runner.config.models.PhaseOverride
 round_timeout_s

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.15] - 2026-09-04
+
+### Added
+- `[monitor.host_health]` gains two config floors — `swap_sout_noise_floor_mb` (default 32) and `mem_free_low_mb` (default 16) — making the 0.2.14 mem-pressure ladder's thresholds operator-tunable; defaults are byte-identical to the prior hardcoded behavior.
+- `serve` now gives up after `MEM_LOOP_THRESHOLD` (5) consecutive mem-terminated rounds instead of retrying forever: emits a new `mem_loop` event and exits `71` — deliberately excluded from the systemd unit's `RestartPreventExitStatus` so the service restarts fresh (break-then-restart).
+
+### Fixed
+- The mem-pressure warning no longer claims "active paging" it can't confirm; it now says only that swap-out crossed the configured noise floor.
+
+### Notes
+- New event kind: `mem_loop`. Not breaking: no `agent-runner migrate` needed this release — nothing that used to load is rejected. `peek --json` schema is unchanged.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.14] - 2026-09-03
 
 ### Breaking

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.14
+Version: 0.2.15
 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
@@ -94,7 +94,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-13 named defenses, structured as data — see `agent-runner peek --select defenses`.
+14 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/README.md

@@ -58,7 +58,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-13 named defenses, structured as data — see `agent-runner peek --select defenses`.
+14 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/_emit.py

@@ -20,6 +20,7 @@ __all__ = [
     "emit_config_migrated",
     "emit_fresh_eyes_round_triggered",
     "emit_max_rounds_reached",
+    "emit_mem_loop",
     "emit_rate_limit_stop",
     "emit_round_deferred",
     "emit_round_grace_extended",
@@ -64,20 +65,49 @@ def emit_config_broken(log_dir: Path, *, reason: str) -> None:
     emit(log_dir, CONFIG_BROKEN, reason=reason)
 
 
-def emit_crash_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path: Path) -> None:
-    """Emit crash_loop (serve stopped after consecutive unknown short crashes).
-
-    Captures the failure reason — a redacted tail of the round log — so a
-    recurring unknown crash can later be classified into a transient bucket.
+def _emit_giveup(
+    log_dir: Path, kind: str, *, consecutive: int, exit_code: int, log_path: Path
+) -> None:
+    """Shared body for the give-up events (serve stopped/broke after consecutive
+    failures of one kind): capture a redacted tail of the round log as ``reason``
+    so the recurring failure can be inspected (or later classified into a
+    transient bucket), and emit ``kind`` with the standard give-up payload.
     """
     from agent_runner._redact import redact_secrets
-    from agent_runner.events import CRASH_LOOP, emit
+    from agent_runner.events import emit
 
     try:
         reason = redact_secrets(log_path.read_text(encoding="utf-8", errors="replace")[-2000:])
     except OSError:
         reason = ""
-    emit(log_dir, CRASH_LOOP, consecutive=consecutive, exit_code=exit_code, reason=reason)
+    emit(log_dir, kind, consecutive=consecutive, exit_code=exit_code, reason=reason)
+
+
+def emit_crash_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path: Path) -> None:
+    """Emit crash_loop (serve stopped after consecutive unknown short crashes).
+
+    Captures the failure reason — a redacted tail of the round log — so a
+    recurring unknown crash can later be classified into a transient bucket.
+    """
+    from agent_runner.events import CRASH_LOOP
+
+    _emit_giveup(
+        log_dir, CRASH_LOOP, consecutive=consecutive, exit_code=exit_code, log_path=log_path
+    )
+
+
+def emit_mem_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path: Path) -> None:
+    """Emit mem_loop (serve gave up after consecutive mid-round memory-pressure
+    terminations — the 0.2.15 coma-preventer's give-up cap). Distinct from
+    crash_loop: this is a break-then-restart, not a deliberate stop, so it is
+    deliberately absent from the unit's RestartPreventExitStatus.
+
+    Captures the failure reason — a redacted tail of the round log — same as
+    crash_loop, so an operator can see what the round was doing when the host
+    ran out of memory."""
+    from agent_runner.events import MEM_LOOP
+
+    _emit_giveup(log_dir, MEM_LOOP, consecutive=consecutive, exit_code=exit_code, log_path=log_path)
 
 
 def emit_config_migrated(

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/_serve_policy.py

@@ -43,6 +43,17 @@ CRASH_LOOP_THRESHOLD = 5
 CRASH_LOOP_SHORT_EXIT_S = 60  # mirrors monitor.SHORT_EXIT_THRESHOLD_S
 CRASH_LOOP_MAX_DELAY_S = 1800  # cap the escalating restart delay (30 min)
 
+# Exit code for the mem-loop give-up cap (0.2.15 coma-preventer, Task 4): serve
+# gives up after MEM_LOOP_THRESHOLD consecutive mid-round memory-terminated
+# rounds rather than retrying forever. Distinct from CRASH_LOOP_EXIT (75) on
+# purpose: this is a "break-then-restart", NOT a deliberate stop — the host
+# memory condition may have cleared by the time systemd respawns a fresh serve
+# process, so unlike config_broken/crash_loop this code is deliberately absent
+# from the unit's RestartPreventExitStatus. 71 = EX_OSERR (sysexits).
+MEM_LOOP_EXIT = 71
+# Consecutive mem-terminated rounds before serve gives up (break-then-restart).
+MEM_LOOP_THRESHOLD = 5
+
 
 class EnvironmentalError(Exception):
     """Marks a round-child failure as ENVIRONMENTAL (recoverable) rather than a
@@ -106,6 +117,25 @@ def post_round_decision(
     return ("continue", delay, 0)
 
 
+def _mem_loop_decision(
+    *, mem_terminated: bool, consecutive: int
+) -> tuple[Literal["mem_loop", "continue"], int]:
+    """Mem-loop give-up cap (0.2.15 Task 4) — a NEW, SEPARATE, private counter
+    from ``post_round_decision``'s crash-loop breaker, not a widening of its
+    3-tuple contract. A mem-terminated round already sets ``throttle_active``
+    for ``post_round_decision`` (never counted as a crash), so without this
+    cap a sustained memory-pressure host would retry forever instead of
+    eventually giving up. Returns ``("mem_loop", consecutive)`` once
+    ``consecutive`` reaches ``MEM_LOOP_THRESHOLD``; a non-mem-terminated round
+    resets the counter to 0, same reset shape as the crash-loop breaker."""
+    if not mem_terminated:
+        return ("continue", 0)
+    consecutive += 1
+    if consecutive >= MEM_LOOP_THRESHOLD:
+        return ("mem_loop", consecutive)
+    return ("continue", consecutive)
+
+
 def classify_round_exit(exc: BaseException) -> int:
     """The round-child exit-code CLASSIFIER (Group A) — permanence, not exception
     identity, decides serve's response. Replaces the old exception *whitelist*

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/_throttle.py

@@ -277,21 +277,20 @@ def _active_throttles(
 def round_was_mem_terminated(log_dir: Path) -> bool:
     """True iff the round that JUST ran was killed by ``_spawn_round``'s
     mid-round memory-pressure hard floor (``round_mem_terminated``) rather
-    than a genuine crash — so ``serve_cmd._ran_agent_throttled`` can excuse it
-    from the crash-loop breaker exactly like an active throttle (flat
-    back-off, ``consecutive`` reset to 0), the same treatment
-    ``ENV_BATTERY_EXIT`` already gets. A mem-terminated round can be killed
-    within the first ~10s (the mid-round check's own cadence) — far under the
-    crash-loop breaker's 60s "short crash" window — so, unlike a wall-clock-
-    ceiling wedge (whose long duration alone dodges the breaker), this needs
-    an explicit signal.
+    than a genuine crash — so ``serve_cmd.cmd`` can excuse it from the
+    crash-loop breaker exactly like an active throttle (flat back-off,
+    ``consecutive`` reset to 0), the same treatment ``ENV_BATTERY_EXIT``
+    already gets. A mem-terminated round can be killed within the first ~10s
+    (the mid-round check's own cadence) — far under the crash-loop breaker's
+    60s "short crash" window — so, unlike a wall-clock-ceiling wedge (whose
+    long duration alone dodges the breaker), this needs an explicit signal.
 
     Scoped to "this round" (not some earlier one) by comparing the newest
     ``round_mem_terminated`` event's timestamp against the newest
     ``round_substrate_before``'s: ``round_substrate_before(N)`` always
     precedes round N's own attempt, and no later round's
     ``round_substrate_before(N+1)`` has been emitted yet at the point
-    ``_ran_agent_throttled`` runs (right after ``_spawn_round`` returns) —
+    ``cmd()`` runs this check (right after ``_spawn_round`` returns) —
     ``round_substrate_after``, also emitted before this check runs, cannot
     serve as that boundary, since it always comes AFTER any
     ``round_mem_terminated`` within the very round it is scoping. ``>=``, not

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/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.14'
-__version_tuple__ = version_tuple = (0, 2, 14)
+__version__ = version = '0.2.15'
+__version_tuple__ = version_tuple = (0, 2, 15)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/api.py

@@ -28,6 +28,7 @@ from agent_runner._serve_policy import (  # noqa: F401 — public re-export
     CRASH_LOOP_SHORT_EXIT_S,
     CRASH_LOOP_THRESHOLD,
     ENV_BATTERY_EXIT,
+    MEM_LOOP_EXIT,
     PERMANENT_CONFIG_EXIT,
     post_round_decision,
 )
@@ -629,6 +630,8 @@ def _poll_once(
         mem_avail_min_mb=cfg.monitor.host_health.mem_avail_min_mb,
         disk_warning_pct=cfg.monitor.host_health.disk_warning_pct,
         disk_critical_pct=cfg.monitor.host_health.disk_critical_pct,
+        swap_sout_noise_floor_mb=cfg.monitor.host_health.swap_sout_noise_floor_mb,
+        mem_free_low_mb=cfg.monitor.host_health.mem_free_low_mb,
         log_dir=cfg.runtime.log_dir,
     )
     if not monitor._PLUGIN_DETECTORS:
@@ -784,6 +787,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_crash_loop,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
+    emit_mem_loop,
     emit_rate_limit_stop,
     emit_round_deferred,
     emit_round_grace_extended,

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/cli/serve_cmd.py

@@ -22,7 +22,9 @@ from typing import Literal
 from agent_runner import host_health, metrics, phase_select, schedule
 from agent_runner._serve_policy import (
     CRASH_LOOP_EXIT,
+    MEM_LOOP_EXIT,
     PERMANENT_CONFIG_EXIT,
+    _mem_loop_decision,
     post_round_decision,
 )
 from agent_runner._substrate import compute_git_head, compute_paths_hash
@@ -40,6 +42,7 @@ from agent_runner.api import (
     emit_crash_loop,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
+    emit_mem_loop,
     emit_rate_limit_stop,
     emit_round_deferred,
     emit_round_logs_prune_deferred,
@@ -432,22 +435,18 @@ def _throttle_skip_context(cfg, log_dir) -> tuple[frozenset[str], int | None]:
 
 
 def _ran_agent_throttled(cfg, phase_arg, log_dir) -> bool:
-    """Was the round that JUST ran throttled, or killed by the mid-round
-    memory-pressure hard floor? — so the crash-loop breaker excuses either a
-    fast throttle-induced exit or a mem-terminated round (round_mem_terminated
-    — a coma-preventer kill, not a crash) rather than counting it as a crash.
-    Checked first: a mem-terminated round can happen within ~10s, far under
-    the crash-loop breaker's 60s short-crash window, so — unlike a wall-clock
-    wedge kill, whose long duration alone dodges the breaker — it needs this
-    explicit exemption.
+    """Was the round that JUST ran throttled? — so the crash-loop breaker
+    excuses a fast throttle-induced exit rather than counting it as a crash.
+    A mem-terminated round (round_mem_terminated — a coma-preventer kill, not
+    a crash) is excused the same way, but that check is computed ONCE in
+    cmd() (``round_was_mem_terminated``) and OR'd into ``throttle_active``
+    there, not repeated here.
 
     When serve chose the phase (``phase_arg`` set) we check that exact agent. When the
     round self-rotated (``phase_arg`` None: no ``[phases]``, or ``--ignore-schedule``),
     serve does NOT know which agent ran, so fall back to "any agent throttled" — the
     pre-0.2.11 agent-agnostic check. Erring toward excusing keeps a real throttle from
     being misread as a crash (a false ``crash_loop`` permanent stop)."""
-    if round_was_mem_terminated(log_dir):
-        return True
     active = _active_throttles(log_dir)
     if phase_arg is None:
         return bool(active)
@@ -587,6 +586,14 @@ def _apply_round_num_env(round_env: dict, round_num: int) -> None:
     round_env["AGENT_RUNNER_ROUND_NUM"] = str(round_num)
 
 
+def _capture_substrate(work_dir, cfg, log_dir, round_num, *, when):
+    """Snapshot git-head + paths-hash and emit the round-substrate event for `when`."""
+    git_head = compute_git_head(work_dir)
+    paths_hash = compute_paths_hash(work_dir, cfg.runtime.substrate_fingerprint_paths)
+    emit = emit_round_substrate_before if when == "before" else emit_round_substrate_after
+    emit(log_dir, round_num=round_num, git_head=git_head, paths_hash=paths_hash)
+
+
 # Grace after TERMing a wedged round before killpg: the round's own SIGTERM handler
 # reaps its agent pgroup (agent_runtime.REAP_GRACE_S) then exits, so allow that plus
 # margin. Kept local to honor serve_cmd's import allowlist; test_spawn_round_wedged
@@ -645,9 +652,10 @@ def _spawn_round(
     (``prev`` passed to ``host_health.memory_pressure``), so the delta grows
     across the whole round rather than resetting each ~10s interval. A slow
     SD/USB-backed swap device pages only a few MB per interval — below the
-    32 MiB floor — but crosses it over a long round; a per-interval delta would
-    stay inert on exactly that host. PSI-full stays an independent immediate
-    critical path (it reads the current sample alone, no baseline needed)."""
+    configured swap-out floor (32 MiB by default) — but crosses it over a long
+    round; a per-interval delta would stay inert on exactly that host. PSI-full
+    stays an independent immediate critical path (it reads the current sample
+    alone, no baseline needed)."""
     log_dir = round_log_path.parent
     with round_log_path.open("w") as f:
         proc = subprocess.Popen(
@@ -665,10 +673,11 @@ def _spawn_round(
             # Baseline pinned at the first mid-round sample (round-start), held
             # fixed so the swap-out delta the floor tests is CUMULATIVE SINCE
             # ROUND-START, not per-interval: a slow SD/USB swap device trickles
-            # only a few MB per ~10s tick (below the 32 MiB floor) yet crosses
-            # it over a long round, so a per-interval comparison stayed inert on
-            # exactly the field host this floor exists for. PSI-full stays an
-            # independent immediate path (it reads the current sample alone).
+            # only a few MB per ~10s tick (below the configured swap-out floor,
+            # 32 MiB by default) yet crosses it over a long round, so a
+            # per-interval comparison stayed inert on exactly the field host
+            # this floor exists for. PSI-full stays an independent immediate
+            # path (it reads the current sample alone).
             round_start_sample: dict | None = None
             while True:
                 try:
@@ -776,6 +785,7 @@ def cmd(args) -> int:
     work_dir = cfg.runtime.work_dir
     rounds_completed = 0
     consecutive_crashes = 0  # b12: consecutive UNKNOWN short crashes (crash-loop breaker)
+    consecutive_mem_terminations = 0  # 0.2.15: consecutive mem-terminated rounds (mem-loop cap)
     # Give-up stops (config_broken/crash_loop) return a distinct non-zero code the
     # systemd unit lists in RestartPreventExitStatus so they stay stopped; every
     # other stop (sentinel/stop_file/max_rounds/SIGTERM/once) is a clean exit 0.
@@ -823,16 +833,7 @@ def cmd(args) -> int:
                 continue
             if stop["requested"]:
                 break  # SIGTERM landed during selection/back-off — don't spawn a round
-            git_head_before = compute_git_head(work_dir)
-            paths_hash_before = compute_paths_hash(
-                work_dir, cfg.runtime.substrate_fingerprint_paths
-            )
-            emit_round_substrate_before(
-                log_dir,
-                round_num=round_num,
-                git_head=git_head_before,
-                paths_hash=paths_hash_before,
-            )
+            _capture_substrate(work_dir, cfg, log_dir, round_num, when="before")
             _apply_fresh_eyes(cfg, log_dir, round_num, round_env)
             _apply_round_num_env(round_env, round_num)
             round_log_path = log_dir / f"round-{round_num}.log"
@@ -856,27 +857,28 @@ def cmd(args) -> int:
             )
             round_duration_s = SYSTEM_CLOCK.monotonic() - round_started
             atomic_relink(log_dir / ROUND_CURRENT_LINK, round_log_path)
-            git_head_after = compute_git_head(work_dir)
-            paths_hash_after = compute_paths_hash(work_dir, cfg.runtime.substrate_fingerprint_paths)
-            emit_round_substrate_after(
-                log_dir,
-                round_num=round_num,
-                git_head=git_head_after,
-                paths_hash=paths_hash_after,
-            )
+            _capture_substrate(work_dir, cfg, log_dir, round_num, when="after")
             rounds_completed += 1
             # Restart policy (config_broken / crash_loop / continue) lives in the
             # tested api.post_round_decision helper so this loop stays thin. Those
             # strings are that enum, not events.py kinds — do not normalize them.
+            # mem_terminated computed ONCE here and OR'd into throttle_active so
+            # crash_loop never double-counts a mem-terminated round; _mem_loop_decision
+            # (a separate, private cap) tracks it on its own counter below.
+            mem_terminated = round_was_mem_terminated(log_dir)
             action, delay, consecutive_crashes = post_round_decision(
                 returncode=r_returncode,
                 duration_s=round_duration_s,
-                # Crash-loop breaker excuses a fast exit only when the agent that just
-                # ran is throttled (agent-agnostic when the round self-rotated the phase).
-                throttle_active=_ran_agent_throttled(cfg, phase_arg, log_dir),
+                # Crash-loop breaker excuses a fast exit when the agent that just ran is
+                # throttled (agent-agnostic when the round self-rotated the phase) or
+                # mem-terminated.
+                throttle_active=mem_terminated or _ran_agent_throttled(cfg, phase_arg, log_dir),
                 consecutive=consecutive_crashes,
                 restart_delay_s=cfg.runtime.restart_delay_s,
             )
+            mem_action, consecutive_mem_terminations = _mem_loop_decision(
+                mem_terminated=mem_terminated, consecutive=consecutive_mem_terminations
+            )
             if action == "config_broken":
                 # classify_round_exit maps ANY ConfigError to this exit code (Group
                 # A) — not only a startup-battery check failure (e.g. _phase_for's
@@ -888,6 +890,19 @@ def cmd(args) -> int:
                 )
                 exit_code = PERMANENT_CONFIG_EXIT
                 break
+            if mem_action == "mem_loop":
+                # Checked before crash_loop: a mem-terminated round always has
+                # throttle_active=True above, so post_round_decision never returns
+                # crash_loop for it anyway — this ordering just makes the precedence
+                # explicit (config_broken > mem_loop > crash_loop).
+                emit_mem_loop(
+                    log_dir,
+                    consecutive=consecutive_mem_terminations,
+                    exit_code=r_returncode,
+                    log_path=round_log_path,
+                )
+                exit_code = MEM_LOOP_EXIT
+                break
             if action == "crash_loop":
                 emit_crash_loop(
                     log_dir,

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/config/models.py

@@ -160,6 +160,8 @@ class MonitorHostHealthConfig:
     mem_avail_min_mb: int = 200  # mem_pressure fires when mem_available_mb < this
     disk_warning_pct: float = 90.0  # disk_warning fires when disk_used_pct >= this
     disk_critical_pct: float = 95.0  # disk_critical fires when disk_used_pct >= this
+    swap_sout_noise_floor_mb: int = 32  # tier-2 swap-out noise floor (MiB); compare uses *1024*1024
+    mem_free_low_mb: int = 16  # tier-3 MemFree floor (MB)
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/config/parsers.py

@@ -462,6 +462,14 @@ def _parse_monitor(monitor_d: dict) -> MonitorConfig:
             hh_d.get("disk_critical_pct", 95.0),
             field="monitor.host_health.disk_critical_pct",
         ),
+        swap_sout_noise_floor_mb=_require_positive_int(
+            hh_d.get("swap_sout_noise_floor_mb", 32),
+            field="monitor.host_health.swap_sout_noise_floor_mb",
+        ),
+        mem_free_low_mb=_require_positive_int(
+            hh_d.get("mem_free_low_mb", 16),
+            field="monitor.host_health.mem_free_low_mb",
+        ),
     )
     monitor = MonitorConfig(
         auth_fail_patterns=_validate_regex_list(

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/defenses.py

@@ -103,6 +103,18 @@ def catalog(cfg: Config) -> list[Defense]:
             guarded_by=Path("tests/unit/test_serve_crash_loop.py"),
             current_state="active",
         ),
+        Defense(
+            name="mem_loop_breaker",
+            value="stop after 5 consecutive mid-round memory-terminated rounds (exit 71)",
+            codifies=(
+                "0.2.15 — a host stuck under sustained memory pressure could mem-terminate "
+                "every round forever with no give-up; break-then-restart cap added (exit 71 "
+                "stays outside RestartPreventExitStatus, so systemd restarts serve, which may "
+                "find the pressure has cleared)"
+            ),
+            guarded_by=Path("tests/unit/test_serve_crash_loop.py"),
+            current_state="active",
+        ),
         Defense(
             name="bulk_round_log_prune_guard",
             value="a prune deleting more files than it keeps deletes nothing",

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/events.py

@@ -46,6 +46,7 @@ DIRTY_DETECTED = "dirty_detected"
 FRESH_EYES_ROUND_TRIGGERED = "fresh_eyes_round_triggered"
 HOOK_FAILED = "hook_failed"
 MAX_ROUNDS_REACHED = "max_rounds_reached"
+MEM_LOOP = "mem_loop"
 MONITOR_ALERT_EMITTED = "monitor_alert_emitted"
 MONITOR_AUTO_STOP_FAILED = "monitor_auto_stop_failed"
 MONITOR_AUTO_STOP_TRIGGERED = "monitor_auto_stop_triggered"

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/host_health.py

@@ -11,8 +11,9 @@ defined signal ladder with graceful degrade:
 1. **PSI** (``psi_some_avg10``/``psi_full_avg10``) if readable — the kernel's
    own "reclaim is slowing progress" measure, immune to cache inflation.
 2. else **swap-out rate** — the delta of ``swap_sout`` (cumulative bytes) over
-   the ``prev_sample`` the caller passes; more than a noise floor (tens of MB)
-   means active paging, not benign startup/idle churn. Escalates to
+   the ``prev_sample`` the caller passes; more than the configured noise floor
+   (tens of MB by default) is flagged as pressure — above the noise floor, not
+   benign startup/idle churn. Escalates to
    **critical** when ``mem_free_mb`` is ALSO critically low (the same absolute
    floor tier 3 uses below) WHILE swap-out is positive — the unambiguous
    "actively dying" state. This is gated on MemFree, not on the swap-out
@@ -46,21 +47,22 @@ from typing import Any
 _PSI_SOME_AVG10_WARNING = 5.0
 _PSI_FULL_AVG10_CRITICAL = 1.0
 
-# Tier 2 -- swap-out delta (bytes) between two samples. Below this is noise:
-# tens of MB is ordinary startup/idle churn between successive samples (round
-# boundaries, or the mid-round loop's own ~10s ticks) and is NOT, on its own,
-# a real paging signal -- a single page (4096B, the old floor) is far too
-# sensitive and made the pre-round gate defer/resume on a few idle KB of
-# swap movement every round.
-_SWAP_SOUT_DELTA_NOISE_FLOOR_BYTES = 32 * 1024 * 1024  # 32 MiB
+# Tier 2 -- swap-out delta (bytes) between two samples. Below
+# cfg.swap_sout_noise_floor_mb is noise: tens of MB is ordinary startup/idle
+# churn between successive samples (round boundaries, or the mid-round loop's
+# own ~10s ticks) and is NOT, on its own, a real paging signal -- a single
+# page (4096B, the old floor) is far too sensitive and made the pre-round gate
+# defer/resume on a few idle KB of swap movement every round. Config-tunable
+# (``MonitorHostHealthConfig.swap_sout_noise_floor_mb``, default 32 MiB) so a
+# tiny host can lower it and a large host can raise it.
 
 # Tier 3 -- combined-low. MemFree alone is always low on a cache-heavy host
 # (the kernel prefers to keep it near-zero and use spare RAM for cache), so
 # it must never gate alone -- only together with a low MemAvailable (tier 3)
 # or an actual measured, above-floor swap-out delta (tier 2's critical
 # escalation, below). Also doubles as the critical-escalation MemFree floor:
-# "critically low" is the same absolute bar either way.
-_MEM_FREE_LOW_MB = 16
+# "critically low" is the same absolute bar either way. Config-tunable
+# (``MonitorHostHealthConfig.mem_free_low_mb``, default 16 MiB).
 
 
 @dataclass(frozen=True)
@@ -122,20 +124,20 @@ def memory_pressure(
         return None  # PSI is readable and says healthy -- trust it, no fall-through.
 
     delta = _swap_sout_delta(sample, prev_sample)
-    if delta is not None and delta > _SWAP_SOUT_DELTA_NOISE_FLOOR_BYTES:
+    if delta is not None and delta > cfg.swap_sout_noise_floor_mb * 1024 * 1024:
         mem_free = sample.get("mem_free_mb")
-        if mem_free is not None and mem_free < _MEM_FREE_LOW_MB:
+        if mem_free is not None and mem_free < cfg.mem_free_low_mb:
             return Pressure(
                 "critical",
                 "swap_out_rate",
                 f"swap sout +{delta}B since last sample while mem_free_mb {mem_free} "
-                f"< {_MEM_FREE_LOW_MB} (actively dying, independent of swap-device speed)",
+                f"< {cfg.mem_free_low_mb} (actively dying, independent of swap-device speed)",
                 {"swap_sout_delta": delta, "mem_free_mb": mem_free},
             )
         return Pressure(
             "warning",
             "swap_out_rate",
-            f"swap sout +{delta}B since last sample (active paging)",
+            f"swap sout +{delta}B since last sample (above the noise floor)",
             {"swap_sout_delta": delta},
         )
     # Swap tier gave no evidence either way (no data, or below the noise
@@ -146,11 +148,11 @@ def memory_pressure(
     mem_free = sample.get("mem_free_mb")
     mem_avail = sample.get("mem_available_mb")
     if mem_free is not None and mem_avail is not None:
-        if mem_free < _MEM_FREE_LOW_MB and mem_avail < cfg.mem_avail_min_mb:
+        if mem_free < cfg.mem_free_low_mb and mem_avail < cfg.mem_avail_min_mb:
             return Pressure(
                 "warning",
                 "combined_low",
-                f"mem_free_mb {mem_free} < {_MEM_FREE_LOW_MB} and "
+                f"mem_free_mb {mem_free} < {cfg.mem_free_low_mb} and "
                 f"mem_available_mb {mem_avail} < {cfg.mem_avail_min_mb}",
                 {"mem_free_mb": mem_free, "mem_available_mb": mem_avail},
             )

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/monitor.py

@@ -91,6 +91,8 @@ def run_all_detectors(
     mem_avail_min_mb: int = 200,
     disk_warning_pct: float = 90.0,
     disk_critical_pct: float = 95.0,
+    swap_sout_noise_floor_mb: int = 32,
+    mem_free_low_mb: int = 16,
     log_dir: Path | None = None,
 ) -> list[Alert]:
     """Run all 13 detectors; returns alerts (empty = healthy).
@@ -112,6 +114,8 @@ def run_all_detectors(
         mem_avail_min_mb=mem_avail_min_mb,
         disk_warning_pct=disk_warning_pct,
         disk_critical_pct=disk_critical_pct,
+        swap_sout_noise_floor_mb=swap_sout_noise_floor_mb,
+        mem_free_low_mb=mem_free_low_mb,
     )
     detectors: list[tuple[str, Callable[[], Alert | None]]] = [
         ("timeout_rate", lambda: detect_timeout_rate(events)),

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/agent_runner/service_unit.py

@@ -103,6 +103,8 @@ def render_serve_unit(
         f"Restart=on-failure\n"
         # 78 = api.PERMANENT_CONFIG_EXIT, 75 = api.CRASH_LOOP_EXIT (literal here to
         # avoid an api→service_unit→api import cycle; pinned by test_service_unit).
+        # NOTE: mem_loop (71) is deliberately absent here — it must restart
+        # (break-then-restart, not a deliberate stop; see api.MEM_LOOP_EXIT).
         f"RestartPreventExitStatus=78 75\n"
         f"RestartSec=3\n"
         f"KillMode=mixed\n"

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/docs/architecture.md

@@ -38,7 +38,7 @@ common to all three. Operator learns one mental model, three lenses.
 
 ## Defenses-as-data
 
-`agent_runner.defenses.catalog(cfg)` returns 13 structured `Defense` entries.
+`agent_runner.defenses.catalog(cfg)` returns 14 structured `Defense` entries.
 Each entry carries:
 
 - `name` — stable identifier
@@ -66,6 +66,7 @@ surfacing everywhere.
 | `critical_envs_injection` | Env injection via [agent.env] block — preset-supplied per CLI (e.g. DISABLE_AUTOUPDATER for claude prevents mid-loop self-updates) | `tests/unit/test_agent_runtime.py` |
 | `startup_smoke_check` | R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn; now halts serve (config_broken) instead of respawning a broken config | `tests/unit/test_serve_config_broken.py` |
 | `crash_loop_breaker` | Run 6 — crashing agent respawned ~100 empty rounds at a fixed 2x delay | `tests/unit/test_serve_crash_loop.py` |
+| `mem_loop_breaker` | 0.2.15 — a host stuck under sustained memory pressure could mem-terminate every round forever with no give-up; break-then-restart cap added (exit 71 stays outside RestartPreventExitStatus, so systemd restarts serve, which may find the pressure has cleared) | `tests/unit/test_serve_crash_loop.py` |
 | `bulk_round_log_prune_guard` | 0.2.4 — rounds/ pruning shipped against backlogs it never built; one deployment's first post-upgrade round would have deleted 12,193 of 12,293 transcripts silently | `tests/unit/test_round_log_helpers.py` |
 | `flock_concurrency` | Architectural — prevent concurrent supervisors corrupting state | `tests/unit/test_runner.py` |
 | `atomic_state_writes` | Data integrity — crashes never leave half-written state files | `tests/invariants/test_atomic_write_enforced.py` |
@@ -212,6 +213,7 @@ See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
 - `fresh_eyes_round_triggered`
 - `hook_failed`
 - `max_rounds_reached`
+- `mem_loop`
 - `monitor_alert_emitted`
 - `monitor_auto_stop_failed`
 - `monitor_auto_stop_triggered`
@@ -257,4 +259,4 @@ See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
 
 三层架构：Round（一轮 agent）/ Loop（serve 薄壳）/ Witness（monitor）。
 三视角对称：peek（快照）/ watch（快照循环）/ monitor（异常检测），共用下钻参数。
-防御以结构化目录形式存在（13 条），每条防御自描述「防的是哪条历史教训、被哪个 invariant test 守、当前状态」。
+防御以结构化目录形式存在（14 条），每条防御自描述「防的是哪条历史教训、被哪个 invariant test 守、当前状态」。

{cli_agent_runner-0.2.14 → cli_agent_runner-0.2.15}/docs/commands.md

@@ -283,7 +283,7 @@ The transforms `migrate` applies (generated from the registry):
 - unknown [phases.<name>.prompt] key(s) rejected in 0.2.13; delete them (allowed: ['files'])
 - [agent] prompt_arg_template has no {prompt} placeholder; the prompt is never delivered to the agent — add {prompt} to one of the argv tokens
 - a [phases.<name>.agent] prompt_arg_template has no {prompt} placeholder; add one, or set that phase's prompt.files = [] if it truly sends no prompt
-- unknown [monitor.host_health] key(s) rejected in 0.2.14; delete them (allowed: ['disk_critical_pct', 'disk_warning_pct', 'mem_avail_min_mb'])
+- unknown [monitor.host_health] key(s) rejected in 0.2.14; delete them (allowed: ['disk_critical_pct', 'disk_warning_pct', 'mem_avail_min_mb', 'mem_free_low_mb', 'swap_sout_noise_floor_mb'])
 <!-- /gen:migrate-transforms -->
 
 ## 中文摘要