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

{cli_agent_runner-0.2.10 → cli_agent_runner-0.2.12}/.vulture-whitelist.py

@@ -12,7 +12,6 @@ duration_s
 timed_out
 pid
 killed_for_grace
-grace_kill_children
 
 # agent_runner.api_types.Alert
 severity
@@ -58,6 +57,7 @@ limit_type
 agent
 since_round
 phase
+throttled_agents
 
 # agent_runner.api_types.RoundResult
 round_num
@@ -256,6 +256,10 @@ manual
 # agent_runner.monitor.LocalSource
 log_dir
 
+# agent_runner.monitor._EventTail
+offsets
+buffer
+
 # agent_runner.phase_select.Selection
 phase
 paused
@@ -286,6 +290,7 @@ name
 ok
 reason
 how_to_fix
+permanent
 
 # agent_runner.vcs_state.StashRef
 sha

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

@@ -5,6 +5,43 @@ 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.12] - 2026-08-31
+
+### Breaking
+- Config validation now hard-rejects footguns that used to load silently: a scalar where a list is required (`phases.list`, `[agent] command`, `prompt_arg_template`, `[prompt] files`), an empty `[agent] command` / empty top-level `[prompt] files`, unknown keys in `[schedule]`/`[prompt]`, and `threshold > window`. **Run `agent-runner migrate` BEFORE `upgrade`** — the orchestrated upgrade runs the old binary's migrate, which cannot self-cross this break. Every new error names `agent-runner migrate`.
+- systemd `serve` unit adds `StartLimitIntervalSec`/`StartLimitBurst`; re-render or hand-edit existing units.
+
+### Fixed
+- The monitor no longer dies on a non-UTF-8 byte or an odd plugin severity; each builtin detector is isolated (`detector_error` event) and a hung round is TERM→grace→killpg'd (`round_supervisor_wedged`) instead of orphaning the agent or latching `hung`.
+- Environmental startup failures (ENOSPC, mount hiccup, unclassified) exit 76 and keep serve retrying at a fixed back-off until they heal, instead of tripping the crash-loop breaker; deterministic config failures give up by name (exit 78).
+- A git-commit timeout leaves no surviving `.git/index.lock` (self-caused only; `stale_index_lock_cleared`); a stop-file lands within one back-off chunk.
+- `status`/`kill`/`restart` report and act on real service state: liveness falls back to `serve.pid` when `systemctl` is absent, and `restart` refuses on non-service modes before stopping.
+- `upgrade` runs the new binary's `migrate` before the smoke check, restores the config on rollback, and emits `upgrade_start_failed` with a remedy when the new version installs but won't start.
+- `json_tail` no longer lets a blank-line flood evict the terminal round-log record; `init` commits only its scaffold files.
+
+### Notes
+- New event kinds: `detector_error`, `round_supervisor_wedged`, `stale_index_lock_cleared`, `upgrade_start_failed`. `RestartPreventExitStatus` stays `78 75` — environmental failures (round exit 76) are retried inside serve rather than stopping it.
+
+See `docs/migrations/0.2.md`.
+
+## [0.2.11] - 2026-08-29
+
+### Changed
+- systemd `serve` unit now uses `Restart=on-failure` with `RestartPreventExitStatus=78 75`: a deliberate stop (sentinel / stop-file / max-rounds / SIGTERM) and a config give-up stay stopped, while a genuine crash still restarts. Re-render or hand-edit existing units.
+- Throttle-aware skip is keyed on the **agent** (binary basename of `command[0]`), not the phase: every phase sharing a rate-limited agent is stepped over together, so a multi-provider rotation no longer hammers one throttled key while a healthy provider keeps running.
+
+### Fixed
+- `round` exits non-zero on a genuine crash, so the crash-loop breaker (`crash_loop`, exit 75) sees crashes instead of a masked exit 0; a permanent config failure gives up with exit 78 (`config_broken`) instead of restart-looping.
+- Round deadlines and sleeps are measured on the monotonic clock — an NTP step no longer mis-fires or defers a hard-wall timeout.
+- Back-off and restart sleeps are chunked, so a SIGTERM lands within one chunk instead of after a multi-hour throttle window; an interrupted back-off leaves the throttle active (no false recovered).
+- A grace-killed round still dispatches its dirty work and is no longer miscounted as a timeout.
+- Only one `serve` loop runs per project (loop-lifetime lock); `serve.pid` records a start-time token so `stop`/`kill` never signals a recycled PID.
+
+### Notes
+- `peek --json` schema `1.10`: `rate_limit.throttled_agents` lists all currently-throttled agents. Additive; no config change.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.10] - 2026-08-29
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.10
+Version: 0.2.12
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme

{cli_agent_runner-0.2.10 → cli_agent_runner-0.2.12}/agent_runner/_docgen.py

@@ -157,10 +157,15 @@ def render_event_kinds_list() -> str:
 
 
 def _render_migrate_transforms() -> str:
-    """Bullet list of the transforms `agent-runner migrate` applies, from the registry."""
-    from agent_runner.migrations import MIGRATIONS
-
-    return "\n".join(f"- {m.describe}" for m in MIGRATIONS)
+    """Bullet list of the transforms `agent-runner migrate` applies, from the registry.
+    A few entries carry a `parsed -> str` describe (so the manual report can name the
+    exact offending key found in a real config); rendered here with `{}`, which degrades
+    to the same generic instruction since there's no config in hand."""
+    from agent_runner.migrations import MIGRATIONS, _describe
+
+    # No config in hand here, so pass an empty parsed dict: a `parsed -> str`
+    # describe degrades to its generic instruction, same rule as the manual report.
+    return "\n".join(f"- {_describe(m, {})}" for m in MIGRATIONS)
 
 
 def _subparser_action() -> argparse.Action:

{cli_agent_runner-0.2.10 → cli_agent_runner-0.2.12}/agent_runner/_emit.py

@@ -27,9 +27,11 @@ __all__ = [
     "emit_round_progress",
     "emit_round_substrate_after",
     "emit_round_substrate_before",
+    "emit_round_supervisor_wedged",
     "emit_schedule_paused",
     "emit_schedule_phase_skipped",
     "emit_schedule_resumed",
+    "emit_stale_index_lock_cleared",
     "emit_stop_file_detected",
     "emit_transient_error_backoff_capped",
     "emit_transient_error_detected",
@@ -98,6 +100,15 @@ def emit_stop_file_detected(
     )
 
 
+def emit_stale_index_lock_cleared(log_dir: Path, *, lock_path: str, round_num: int) -> None:
+    """Emit when serve removed a .git/index.lock that its own timed-out+killed git
+    call orphaned. Single-writer: serve holds the round lock, so any lock surviving
+    our kill is ours to clear."""
+    from agent_runner.events import STALE_INDEX_LOCK_CLEARED, emit
+
+    emit(log_dir, STALE_INDEX_LOCK_CLEARED, lock_path=lock_path, round_num=round_num)
+
+
 def emit_schedule_paused(
     log_dir: Path, *, active_window: str, resume_at: str, timezone: str, phase: str = ""
 ) -> None:
@@ -168,6 +179,18 @@ def emit_round_substrate_after(
     )
 
 
+def emit_round_supervisor_wedged(
+    log_dir: Path, *, pid: int, timeout_s: int, log_path: Path
+) -> None:
+    """Emit when the round subprocess blew past the outer ceiling and serve had to
+    TERM/kill it (the round supervisor was wedged — not doing its own bounded
+    post-round cleanup). Distinct from round_timeout_kill (the AGENT hit the inner
+    wall inside a healthy round)."""
+    from agent_runner.events import ROUND_SUPERVISOR_WEDGED, emit
+
+    emit(log_dir, ROUND_SUPERVISOR_WEDGED, pid=pid, timeout_s=timeout_s, log_path=str(log_path))
+
+
 def emit_fresh_eyes_round_triggered(log_dir: Path, *, round_num: int, every_n: int) -> None:
     """Emit fresh-eyes signal trigger event (only on triggered rounds)."""
     from agent_runner.events import FRESH_EYES_ROUND_TRIGGERED, emit

cli_agent_runner-0.2.12/agent_runner/_serve_policy.py

@@ -0,0 +1,89 @@
+"""Pure serve restart policy — no I/O, no clock, no events read.
+
+Extracted from api.py (0.2.12 Group G): serve_cmd imports the decision + exit
+codes from here directly (see the architecture allowlist); api.py re-exports
+them for external back-compat. Kept dependency-free so the serve loop stays a
+thin dispatcher and the policy is unit-testable in isolation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+# Exit code for a permanent (no-retry) startup-battery failure. A broken config
+# does not self-heal between rounds, so serve STOPS rather than respawning it
+# forever. 78 = EX_CONFIG (sysexits) — avoids argparse's 2 and the generic 1.
+PERMANENT_CONFIG_EXIT = 78
+
+# Exit code serve returns when the crash-loop breaker trips (a give-up stop, like
+# config_broken). Distinct from 78 so `systemctl status` / SuccessExitStatus can
+# tell the two "needs intervention" stops apart. 75 = EX_TEMPFAIL (sysexits).
+# The systemd unit lists both in RestartPreventExitStatus so a deliberate stop
+# stays stopped (and visibly failed) while an unexpected supervisor crash restarts.
+CRASH_LOOP_EXIT = 75
+
+# Exit code for an ENVIRONMENTAL startup-battery failure (ENOSPC, mount hiccup,
+# an unclassified check): recoverable, unlike a permanent config break. NOT in
+# the unit's RestartPreventExitStatus (stays "78 75") so 76 restarts; treated
+# exactly like an active throttle (post_round_decision), so serve keeps
+# retrying at a fixed doubled delay with the crash-loop breaker disarmed,
+# staying alive until the environment heals. StartLimit bounds only repeated
+# serve-PROCESS death, not this round-level path. 76 = EX_PROTOCOL (sysexits).
+ENV_BATTERY_EXIT = 76
+
+# Crash-loop circuit breaker (b12). The serve loop escalates the restart delay
+# on consecutive UNKNOWN short crashes (non-zero exit, short duration, no
+# classified transient) and STOPS after CRASH_LOOP_THRESHOLD of them — the Run 6
+# ~100-empty-rounds scar. Recoverable-slow failures (rate limit / 5h quota / 5xx
+# / timeout) are already handled by the transient-error throttle and never reach
+# this path. A clean (exit 0), long, or classified-transient round resets the run.
+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)
+
+
+# The action strings below are the restart-action enum, not events.py kinds:
+# "continue" has no constant, and a constant cannot sit inside Literal[...].
+def post_round_decision(
+    *,
+    returncode: int,
+    duration_s: float,
+    throttle_active: bool,
+    consecutive: int,
+    restart_delay_s: int,
+) -> tuple[Literal["config_broken", "crash_loop", "continue"], int, int]:
+    """Restart policy after one round — keeps the serve loop a thin dispatcher.
+
+    Returns ``(action, delay_s, consecutive)`` where action is:
+    - ``"config_broken"`` — permanent startup failure (b18): stop.
+    - ``"crash_loop"`` — CRASH_LOOP_THRESHOLD consecutive unknown short crashes
+      (b12): stop. An unknown short crash is a non-zero, fast exit with no
+      classified transient (rate-limit/5xx/timeout are handled by the throttle).
+    - ``"continue"`` — sleep ``delay_s`` then run the next round.
+
+    A clean (exit 0), long, or transient round resets ``consecutive`` to 0; an
+    unknown short crash escalates the delay (restart × 2ⁿ, capped) until the stop.
+    An ``ENV_BATTERY_EXIT`` (76, environmental startup-battery failure) is treated
+    exactly like an active throttle: it takes the flat ``restart_delay_s * 2``
+    delay below (never escalating) and resets ``consecutive`` to 0, so it never
+    counts toward the crash-loop breaker — a short environmental outage (ENOSPC,
+    mount hiccup) never trips ``crash_loop``. This always returns ``"continue"``,
+    so serve itself never exits 76 and systemd's StartLimit window never engages
+    for this path; a *persistent* environmental failure keeps serve alive
+    retrying at the doubled delay until the environment heals. StartLimit bounds
+    only repeated serve-PROCESS death, independent of this round-level path.
+    """
+    if returncode == PERMANENT_CONFIG_EXIT:
+        return ("config_broken", 0, consecutive)
+    throttle_active = throttle_active or returncode == ENV_BATTERY_EXIT
+    unknown_short_crash = (
+        returncode != 0 and duration_s < CRASH_LOOP_SHORT_EXIT_S and not throttle_active
+    )
+    if unknown_short_crash:
+        consecutive += 1
+        if consecutive >= CRASH_LOOP_THRESHOLD:
+            return ("crash_loop", 0, consecutive)
+        delay = min(restart_delay_s * 2**consecutive, CRASH_LOOP_MAX_DELAY_S)
+        return ("continue", delay, consecutive)
+    delay = restart_delay_s if returncode == 0 else restart_delay_s * 2
+    return ("continue", delay, 0)