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

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/.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.8/BACKLOG.md

@@ -0,0 +1,43 @@
+# Backlog
+
+Known follow-ups that are real design or behavior decisions, not defects. Each
+entry carries enough context to act on without re-deriving it.
+
+Items marked **NEEDS_DESIGN** change user-visible behavior and are held for an
+explicit decision — they are not shipped silently in a maintenance release.
+
+**Ordered by priority** (highest first). The number is a rank, not a stable id.
+
+## 1. `_tail_events` / `_tail_events_jsonl` duplication
+
+Three event-stream tailers now exist at deliberately different scopes, and they
+are not accidental copies:
+
+- `cli/events_cmd.py:_tail_events` — current-month-scoped
+  (`_current_month_events_file`), resets its offset to `0` on truncation.
+- `_monitor_state.py:_tail_events_jsonl` — globs every `events-*.jsonl`;
+  re-exported through the `monitor.py` facade. It moved out of `api.py` in the
+  0.3.0 api split (`_install`/`_lifecycle`/`_observe`).
+- `_throttle.py:_tail_events` — the newest two monthly files
+  (`glob("events-*.jsonl")[-2:]`).
+
+Collapsing them means first deciding which scope is correct for each caller — a
+structural decision, not a literal swap. (The older "character-identical
+kind-read loop in `_throttle.py` and `monitor.py`" sub-concern has evaporated:
+`monitor.py` no longer carries that loop — it moved to `_monitor_detectors.py`
+and grew its own reset-ladder logic — and `_throttle.py` iterates forward over
+the tailer generator, so the only shared text left is the single line
+`kind = ev.get("event")`.)
+
+## 2. `stash_orphan` loses the ref when the post-push listing fails
+
+`vcs_state.stash_orphan` returns `None` in three cases; two are true no-ops. The
+third — `git stash push` succeeded but the follow-up `git stash list` failed —
+means the WIP *is* stashed yet callers read "nothing stashed" and report the
+tree as ignored. It is already documented in-code as a KNOWN GAP and judged
+effectively unreachable (a listing that fails microseconds after a push that
+just succeeded in the same repo).
+
+Deferred because closing it is a naming decision, not cleanup: no event kind
+carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
+— the stash exists). Left as-is until that kind is designed.

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

@@ -5,6 +5,22 @@ 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.8] - 2026-09-16
+
+### Changed
+- `try_auto_commit` (`vcs.dirty_action = "auto_commit"`) now honors the plugin-owned-paths registry, matching `stash_orphan`: paths registered via `register_plugin_owned_paths` are excluded from the auto-commit, so a plugin's deliverables no longer land in the agent's git history.
+- `round_oom_killed` now also carries `events_oom_kill_delta` — the canonical name, sibling-consistent with `round_cgroup_memory`'s counters; the original bare `oom_kill_delta` is retained as an alias (a future breaking release drops it).
+
+### Added
+- The `claude` preset arms the repetitive-tool-call anomaly detector (`[monitor] anomaly_repetitive_window = 30`, `anomaly_repetitive_threshold = 15`) — trips only on an egregious stuck loop (the same tool+target ≥15× within 30 calls). The global default stays opt-in (disabled).
+
+## [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.8}/CONTRIBUTING.md

@@ -75,10 +75,11 @@ into `docs/commands.md` from the registry) plus `CHANGELOG.md`. Between them
 they carry a config rewrite and per-version notes; a doc that only restates the
 changelog is upkeep with no reader.
 
-`docs/migrations/0.2.md` is the one surviving guide: it collects the few manual
-steps a config rewrite can't do (recovery procedures, a systemd regen, a mode
-switch). Keep the relevant CHANGELOG entries terse and link it
-(`See docs/migrations/0.2.md.`).
+`docs/migrations/0.2.md` and `docs/migrations/0.3.md` are the two surviving
+guides: they collect the few manual steps a config rewrite can't do (recovery
+procedures, a systemd regen, a mode switch, the 0.3.0 breaking-release port).
+Keep the relevant CHANGELOG entries terse and link the matching one
+(`See docs/migrations/0.3.md.`).
 
 Migration guides are **not** append-only. A per-version guide is pruned once its
 content becomes executable (`migrate`), generated (the transform list),

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.6
+Version: 0.3.8
 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
@@ -93,7 +93,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
-| `upgrade` / `migrate` | |
+| `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
@@ -123,7 +123,9 @@ Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
 `network_fail`, `rate_limit_active`, `anomaly_repetitive_active`,
 `supervisor_stale`. `mem_pressure` also drives a separate serve-loop
 admission gate that defers or terminates rounds under real memory pressure —
-see `docs/architecture.md`.
+see `docs/architecture.md`. An opt-in soft-brake (`[monitor.host_health.brake]`,
+default off) can additionally cap the serve leaf's `memory.high` under sustained
+pressure on a delegated cgroup.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/README.md

@@ -52,7 +52,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
-| `upgrade` / `migrate` | |
+| `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
@@ -82,7 +82,9 @@ Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
 `network_fail`, `rate_limit_active`, `anomaly_repetitive_active`,
 `supervisor_stale`. `mem_pressure` also drives a separate serve-loop
 admission gate that defers or terminates rounds under real memory pressure —
-see `docs/architecture.md`.
+see `docs/architecture.md`. An opt-in soft-brake (`[monitor.host_health.brake]`,
+default off) can additionally cap the serve leaf's `memory.high` under sustained
+pressure on a delegated cgroup.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/agent_runner/_docgen.py

@@ -29,6 +29,7 @@ from agent_runner.config import (
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
     _HostHealthPressureConfig,
@@ -66,6 +67,7 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
             ("monitor.host_health.disk", _HostHealthDiskConfig),
             ("monitor.host_health.memory", _HostHealthMemoryConfig),
             ("monitor.host_health.pressure", _HostHealthPressureConfig),
+            ("monitor.host_health.brake", _HostHealthBrakeConfig),
         ],
     ),
     ("phases", PhasesConfig, []),

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/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.8}/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,
     )
 
 
@@ -207,13 +217,20 @@ def emit_round_oom_killed(
     took, no second sysfs read). Symmetric with ``round_mem_terminated``
     (supervisor-killed) -- this is the kernel-killed sibling.
 
-    POINTER-ONLY: ``log_path`` + ``log_bytes`` + ``oom_kill_delta`` -- NEVER the
+    POINTER-ONLY: ``log_path`` + ``log_bytes`` + the oom-kill delta -- NEVER the
     round-log/transcript content itself (durability, secret-redaction, size all
     argue against embedding it in events.jsonl). ``partial_log`` reports whether
     the supervisor's own truncation trailer (see ``_mark_partial_log``) was
     written onto the round log, so a later reader can tell the log's tail is
     supervisor residue, not the agent's own output.
 
+    The oom-kill delta rides under TWO field names with the identical value:
+    ``events_oom_kill_delta`` is the canonical name (sibling-consistent with
+    ``round_cgroup_memory``'s ``events_oom_kill_delta``); ``oom_kill_delta`` is
+    the retained legacy alias. The append-only event contract keeps both until a
+    future breaking release drops the bare alias -- so a single ``oom_kill_delta``
+    argument single-sources both fields, which can never diverge.
+
     Classification is UNCHANGED by this event: the round still exits 137 and
     counts toward the crash streak exactly as before -- this is pure
     observability layered on top, computed and emitted after that decision is
@@ -226,6 +243,7 @@ def emit_round_oom_killed(
         round_num=round_num,
         log_path=str(log_path),
         log_bytes=log_bytes,
+        events_oom_kill_delta=oom_kill_delta,
         oom_kill_delta=oom_kill_delta,
         partial_log=partial_log,
     )
@@ -246,6 +264,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.8}/agent_runner/_monitor_state.py

@@ -14,11 +14,12 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from agent_runner import event_log
+from agent_runner._notify import NULL_LISTENER
 from agent_runner.api_types import ProjectState, ServiceMode, ServiceStatus, SystemMetrics
 from agent_runner.builtin_plugins._constants import _TAIL_LINES
-from agent_runner.clock import SYSTEM_CLOCK
 from agent_runner.context_store import read_json
-from agent_runner.events import iter_event_dicts, read_new
+from agent_runner.events import iter_event_dicts
 
 
 @dataclass(frozen=True)
@@ -29,7 +30,7 @@ class LocalSource:
     log_dir: Path
 
     def events_files(self) -> list[Path]:
-        return sorted(self.log_dir.glob("events-*.jsonl"))
+        return event_log.all_month_files(self.log_dir)
 
     def metrics_files(self) -> list[Path]:
         return sorted(self.log_dir.glob("metrics-*.jsonl"))
@@ -75,7 +76,7 @@ class _EventTail:
     )
 
     def read(self, files: list[Path]) -> list[dict[str, Any]]:
-        new_events, self.offsets = read_new(files, self.offsets)
+        new_events, self.offsets = event_log.read_new(files, self.offsets)
         self.buffer.extend(new_events)
         return list(self.buffer)
 
@@ -93,23 +94,22 @@ def _tail_events_jsonl(
     byte 0 of every file present at start (human-narrate use case).
 
     Follows file rotation transparently — when a new events-YYYY-MM.jsonl
-    appears, it is picked up from byte 0.
+    appears, it is picked up from byte 0. A thin client over the shared
+    :func:`event_log.follow` loop (also used by ``events --tail``); polls
+    (``NULL_LISTENER`` -- no doorbell) rather than a live FIFO listener.
     """
-    offsets: dict[Path, int] = {}
+    seed: dict[Path, int] = {}
     if start_at_now:
-        for path in sorted(log_dir.glob("events-*.jsonl")):
-            try:
-                offsets[path] = path.stat().st_size
-            except FileNotFoundError:
-                continue
-
-    while True:
-        files = sorted(log_dir.glob("events-*.jsonl"))
-        new_events, offsets = read_new(files, offsets)
-        if new_events:
-            yield from new_events
-        else:
-            SYSTEM_CLOCK.sleep(poll_interval_s)
+        seed = event_log.seed_at_eof(event_log.all_month_files(log_dir))
+
+    for _line, obj in event_log.follow(
+        log_dir,
+        event_log.all_month_files,
+        wake=NULL_LISTENER,
+        timeout_s=poll_interval_s,
+        offsets=seed,
+    ):
+        yield obj
 
 
 _MAX_TAIL_FILES = 20

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/agent_runner/_throttle.py

@@ -18,6 +18,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
+from agent_runner import event_log
 from agent_runner._notify import NULL_LISTENER, Listener, NullListener
 from agent_runner.api_types import TransientErrorState
 from agent_runner.clock import SYSTEM_CLOCK, Clock
@@ -152,9 +153,10 @@ def _tail_events(log_dir: Path) -> Iterator[dict[str, Any]]:
 
     Forward, OLD-then-NEW order matters (INVARIANT 2 for callers that merge a
     per-key "latest wins" map: iterating oldest file first means a later event
-    for the same key naturally overwrites an earlier one)."""
-    for path in sorted(log_dir.glob("events-*.jsonl"))[-2:]:
-        yield from _iter_events(path)
+    for the same key naturally overwrites an earlier one). STATELESS full
+    re-scan by design (see :func:`event_log.scan`'s docstring) -- never the
+    offset-carrying ``follow``/``read_new`` path."""
+    yield from event_log.scan(log_dir, event_log.newest_scope(2))
 
 
 def _scan_events_for_transient(path: Path):
@@ -185,8 +187,7 @@ def _latest_unrecovered_detected(log_dir: Path) -> dict[str, Any] | None:
     Scans the newest monthly ``events-*.jsonl`` and, only if it holds no transient
     event yet, the previous month's — so a throttle that spans a month boundary
     (detected in the old file, cleared in the new) is not orphaned."""
-    candidates = sorted(log_dir.glob("events-*.jsonl"))
-    for path in reversed(candidates[-2:]):
+    for path in reversed(event_log.newest_month_files(log_dir, 2)):
         result = _scan_events_for_transient(path)
         if result is not _NO_TRANSIENT:
             return result  # a detected dict, or None (latest transient was recovered)

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

{cli_agent_runner-0.3.6 → cli_agent_runner-0.3.8}/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.8}/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: