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

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

@@ -6,6 +6,13 @@
 # bare name below marks one field "used". SSOT = the @dataclass definitions in
 # agent_runner/; a new field is covered by regenerating, never by editing here.
 
+# agent_runner._monitor_state.LocalSource
+log_dir
+
+# agent_runner._monitor_state._EventTail
+offsets
+buffer
+
 # agent_runner.agent_runtime.RunResult
 exit_code
 duration_s
@@ -109,14 +116,14 @@ agent
 since_round
 phase
 
-# agent_runner.config.AgentConfig
+# agent_runner.config.models.AgentConfig
 command
 prompt_arg_template
 name
 env
 prompt_delivery
 
-# agent_runner.config.Config
+# agent_runner.config.models.Config
 agent
 runtime
 prompt
@@ -126,7 +133,7 @@ phases
 plugins
 schedule
 
-# agent_runner.config.MonitorConfig
+# agent_runner.config.models.MonitorConfig
 auth_fail_patterns
 auth_fail_hint
 auto_stop_on
@@ -137,34 +144,36 @@ host_health
 round_progress_interval_s
 supervisor_stale_threshold_s
 
-# agent_runner.config.MonitorHostHealthConfig
+# agent_runner.config.models.MonitorHostHealthConfig
 mem_avail_min_mb
 disk_warning_pct
 disk_critical_pct
+swap_sout_noise_floor_mb
+mem_free_low_mb
 
-# agent_runner.config.PhaseOverride
+# agent_runner.config.models.PhaseOverride
 round_timeout_s
 disable_pre_round_hooks
 prompt_files
 agent
 schedule
 
-# agent_runner.config.PhasesConfig
+# agent_runner.config.models.PhasesConfig
 list
 overrides
 phase_policy
 
-# agent_runner.config.PluginsConfig
+# agent_runner.config.models.PluginsConfig
 disable
 raw
 
-# agent_runner.config.Profile
+# agent_runner.config.models.Profile
 agent
 runtime
 schedule
 prompt_files
 
-# agent_runner.config.PromptConfig
+# agent_runner.config.models.PromptConfig
 file
 files
 inject_context
@@ -172,7 +181,7 @@ context_injection_mode
 concat_separator
 strip_yaml_frontmatter
 
-# agent_runner.config.RuntimeConfig
+# agent_runner.config.models.RuntimeConfig
 work_dir
 log_dir
 round_timeout_s
@@ -189,12 +198,12 @@ dry_run
 max_grace_after_result_s
 grace_kill_ignore_patterns
 
-# agent_runner.config.ScheduleConfig
+# agent_runner.config.models.ScheduleConfig
 timezone
 run_windows
 pause_windows
 
-# agent_runner.config.VcsConfig
+# agent_runner.config.models.VcsConfig
 stash_idempotency_s
 dirty_action
 
@@ -240,6 +249,12 @@ vcs
 dirty_action
 stash_idempotency_s
 
+# agent_runner.host_health.Pressure
+severity
+signal
+message
+context
+
 # agent_runner.lifecycle.PIDFile
 path
 
@@ -255,13 +270,6 @@ applied
 manual
 advisory
 
-# agent_runner.monitor.LocalSource
-log_dir
-
-# agent_runner.monitor._EventTail
-offsets
-buffer
-
 # agent_runner.phase_select.Selection
 phase
 paused

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

@@ -5,6 +5,36 @@ 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
+- `[monitor.host_health]` unknown keys are now rejected, and a nested table given as a scalar (`[agent] env = "x"`, `[monitor] host_health = 1`) now raises `ConfigError` instead of crashing. **Run `agent-runner migrate` before `upgrade`**, as in 0.2.12/0.2.13.
+
+### Fixed
+- `mem_pressure` now gates on a cache-poor-valid signal (PSI, then swap-out rate, then combined low `MemFree`+`MemAvailable`) instead of the inflated `MemAvailable` alone, and warns once when the configured `mem_avail_min_mb` gate is provably inert on the host; `serve` defers starting a new round while the host reports pressure and terminates a ballooning round mid-flight before it goes unresponsive.
+- An unreadable config (bad permissions, a directory) now fails cleanly with `ConfigError`/exit 78 instead of a raw traceback; a startup git-status timeout no longer crashes the check; a killed stash no longer strands `.git/index.lock`.
+- `transient_error_backoff_capped` reports the raw detector reset time, not the ladder-extended one.
+
+### Notes
+- New event kinds: `round_deferred`, `round_resumed`, `round_mem_terminated`; new alert kinds: `mem_signal_unavailable`, `mem_pressure_gate_inert`. `peek --json` schema is unchanged this release.
+- `config.py`/`monitor.py`/api's round-input helpers were reorganized into internal modules this release — no public API change.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.13] - 2026-09-02
 
 ### Breaking

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.13
+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
@@ -49,7 +49,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -86,7 +86,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | |
 
@@ -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:
 
@@ -111,11 +111,14 @@ Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
 `serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
 of [`docs/configuration.md`](docs/configuration.md).
 
-## Monitor: 11 detectors
+## Monitor: 13 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `network_fail`, `rate_limit_active`,
-`anomaly_repetitive_active`, `supervisor_stale`.
+`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`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`.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

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

@@ -13,7 +13,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -50,7 +50,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | |
 
@@ -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:
 
@@ -75,11 +75,14 @@ Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
 `serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
 of [`docs/configuration.md`](docs/configuration.md).
 
-## Monitor: 11 detectors
+## Monitor: 13 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `network_fail`, `rate_limit_active`,
-`anomaly_repetitive_active`, `supervisor_stale`.
+`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`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`.
 
 **Auto-stop the service** (continuing is harmful):
 - `oauth_fail` — burning API quota on auth-rejected rounds

{cli_agent_runner-0.2.13 → cli_agent_runner-0.2.15}/agent_runner/_docgen.py

@@ -255,10 +255,12 @@ RENDERERS: dict[str, Renderer] = {
     "defenses-table": Renderer(render_defenses_table, "agent_runner/defenses.py catalog()"),
     "detector-list": Renderer(
         render_detector_list,
-        "agent_runner/monitor.py KNOWN_ALERT_KINDS / AUTO_STOP_ALERTS",
+        "agent_runner/_monitor_registry.py KNOWN_ALERT_KINDS / AUTO_STOP_ALERTS",
     ),
     "event-kinds": Renderer(render_event_kinds_list, "agent_runner/events.py KNOWN_EVENT_KINDS"),
-    "config-schema": Renderer(render_config_schema_table, "agent_runner/config.py dataclasses"),
+    "config-schema": Renderer(
+        render_config_schema_table, "agent_runner/config/models.py dataclasses"
+    ),
     "verb-table": Renderer(render_verb_table, "agent_runner/cli argparse subparsers"),
     "migrate-transforms": Renderer(
         _render_migrate_transforms, "agent_runner/migrations.py MIGRATIONS"

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

@@ -20,11 +20,15 @@ __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",
     "emit_round_grace_kill",
     "emit_round_logs_prune_deferred",
+    "emit_round_mem_terminated",
     "emit_round_progress",
+    "emit_round_resumed",
     "emit_round_substrate_after",
     "emit_round_substrate_before",
     "emit_round_supervisor_wedged",
@@ -61,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(
@@ -150,6 +183,36 @@ def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
     emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
 
 
+def emit_round_deferred(log_dir: Path, *, severity: str, signal: str, message: str) -> None:
+    """Emit round_deferred when the pre-round admission gate defers the next
+    round under host_health memory pressure (Group 3 action half). Paired with
+    emit_round_resumed once pressure clears -- like schedule_paused/resumed --
+    so a long defer does not trip detect_supervisor_stale (see its suppression
+    set in _monitor_detectors.py)."""
+    from agent_runner.events import ROUND_DEFERRED, emit
+
+    emit(log_dir, ROUND_DEFERRED, severity=severity, signal=signal, message=message)
+
+
+def emit_round_resumed(log_dir: Path, *, deferred_for_s: int) -> None:
+    """Emit round_resumed when a memory-pressure round deferral clears."""
+    from agent_runner.events import ROUND_RESUMED, emit
+
+    emit(log_dir, ROUND_RESUMED, deferred_for_s=deferred_for_s)
+
+
+def emit_round_mem_terminated(
+    log_dir: Path, *, pid: int, severity: str, signal: str, message: str
+) -> None:
+    """Emit when _spawn_round's mid-round hard floor terminated a ballooning
+    round on critical host_health pressure -- the actual coma-preventer (a
+    pre-round-only gate can't stop a single round mid-flight). Distinct from
+    round_supervisor_wedged (a wall-clock ceiling breach, unrelated cause)."""
+    from agent_runner.events import ROUND_MEM_TERMINATED, emit
+
+    emit(log_dir, ROUND_MEM_TERMINATED, pid=pid, severity=severity, signal=signal, message=message)
+
+
 def emit_round_substrate_before(
     log_dir: Path, *, round_num: int, git_head: str | None, paths_hash: str | None
 ) -> None: