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

{cli_agent_runner-0.2.12 → cli_agent_runner-0.2.14}/.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,34 @@ 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
 
-# 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 +179,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 +196,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 +247,12 @@ vcs
 dirty_action
 stash_idempotency_s
 
+# agent_runner.host_health.Pressure
+severity
+signal
+message
+context
+
 # agent_runner.lifecycle.PIDFile
 path
 
@@ -247,18 +260,13 @@ path
 detect
 apply
 describe
+advisory
 
 # agent_runner.migrations.MigrationResult
 new_text
 applied
 manual
-
-# agent_runner.monitor.LocalSource
-log_dir
-
-# agent_runner.monitor._EventTail
-offsets
-buffer
+advisory
 
 # agent_runner.phase_select.Selection
 phase

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

@@ -5,6 +5,40 @@ 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.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
+- Config validation now rejects unknown keys in base `[agent]`/`[runtime]`/`[vcs]`/`[monitor]`, a table given as a scalar, unknown per-phase `[phases.<name>.prompt]` keys, and an argv `prompt_arg_template` missing `{prompt}`. **Run `agent-runner migrate` before `upgrade`**, as in 0.2.12.
+- systemd `serve` units grow `TimeoutStopSec` (now `round_timeout_s + 210`, up from `+60`) — re-render after upgrading.
+
+### Fixed
+- Round-child exit codes are classified by permanence, not a type whitelist: a config break stays 78, a self-healing environmental failure (lock contention, a git-status timeout, an unwritable log dir) now reliably reaches retryable 76, and everything else still falls to 1 so the crash-loop breaker bounds a genuine bug; serve itself still never exits 76.
+- `kill` reaps the whole round-and-agent process group; `stop`/`restart`/`uninstall` are drain-aware so a mid-round stop no longer leaves a systemd serve stopped or raises; service-mode detection checks systemd `is-active` instead of guessing; and `monitor_auto_stop_triggered` fires only after a confirmed stop.
+- `install --system` rejects control characters in `work_dir`/`log_dir`/config path, closing a root-injection path through the rendered unit.
+- `read_json`/orphan-state reads survive a non-UTF-8 byte or a directory instead of crashing serve; a git-status timeout mid-round no longer drops the round's own bookkeeping (`dirty_check_failed`).
+- Throttle readers (serve's loop-top gate, the skip path, `peek`, monitor) converge on one reset source; the back-off sleep now wakes early on an NTP clock jump.
+
+### Notes
+- New event kind: `dirty_check_failed`. `peek --json` schema is unchanged this release.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.12] - 2026-08-31
 
 ### Breaking

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

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

@@ -21,10 +21,13 @@ __all__ = [
     "emit_fresh_eyes_round_triggered",
     "emit_max_rounds_reached",
     "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",
@@ -54,7 +57,8 @@ def emit_max_rounds_reached(log_dir: Path, *, rounds_completed: int, max_rounds:
 
 
 def emit_config_broken(log_dir: Path, *, reason: str) -> None:
-    """Emit config_broken (serve stopped on a permanent startup-battery failure)."""
+    """Emit config_broken (serve gave up on a permanent, non-self-healing failure —
+    a startup-battery check, or any other ConfigError-classified round exit)."""
     from agent_runner.events import CONFIG_BROKEN, emit
 
     emit(log_dir, CONFIG_BROKEN, reason=reason)
@@ -70,7 +74,7 @@ def emit_crash_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path
     from agent_runner.events import CRASH_LOOP, emit
 
     try:
-        reason = redact_secrets(log_path.read_text(errors="replace")[-2000:])
+        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)
@@ -149,6 +153,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:
@@ -315,8 +349,11 @@ def emit_agent_usage_recorded(
     - ``models_breakdown``: only populated when a round used multiple models
       (gemini multi-model rounds). None for claude (always single-model).
     - ``cache_creation_tokens``: claude only — ``usage.cache_creation_input_tokens``,
-      independent count from ``cached_tokens`` (cache_read). Billed at ~25% premium
-      over fresh input per Anthropic pricing. Gemini has no equivalent → 0.
+      independent count from ``cached_tokens`` (cache_read). Priced differently
+      from fresh input by the provider; the framework records the count only and
+      never interprets cost (no price tables here — see ``cost_usd`` above for the
+      one cost figure the framework passes through verbatim). Gemini has no
+      equivalent → 0.
     - ``tool_call_count``: number of tool invocations the agent made in the round.
       Claude: count of ``tool_use`` content blocks across all assistant events.
       Gemini: ``stats.tool_calls``.