cli-agent-runner 0.1.41__tar.gz → 0.2.0__tar.gz

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.0] - 2026-07-02
+
+### Changed
+- Dirty-tree handling is now pluggable. The clean-exit-dirty policy moved out of core into a `dirty_handler` hook; `stash` / `ignore` / `auto_commit` now ship as the bundled, default-on `default_dirty_handler` plugin. **No behavior or config change for existing users** — `[vcs] dirty_action` works exactly as before.
+
+### Added
+- `dirty_handler` plugin seam (4th lifecycle hook) + `DirtyOutcome` on `RoundResult`; `stash_orphan` / `try_auto_commit` are now public `api` primitives. Consumers can fully own dirty-tree policy — see `docs/migrations/0.2.0.md`.
+- `dirty_auto_committed` event (emitted when a handler auto-commits).
+
+## [0.1.42] - 2026-06-25
+
+### Added
+- `crash_loop` defense — serve stops after 5 consecutive *unknown* short crashes (non-zero exit, <60s, no classified transient), escalating the restart delay and recording the failure reason. Ends the respawn-forever crash loop; recoverable-slow failures (rate-limit / quota / 5xx / timeout) still ride the transient-error backoff unchanged.
+- `config_broken` defense — a permanent startup-battery failure now halts serve (distinct no-retry exit code `78`) instead of respawning a broken config every round.
+
+### Fixed
+- `vcs.dirty_action` no longer sweeps the runner's own `log_dir` bookkeeping when `log_dir` is inside `work_dir`: `auto_commit` excludes it from the commit (no more phantom `git_head` advance on a zero-work round) and `stash` excludes it from `git stash push -u` (logs no longer vanish). `.evolving/` and agent work are unaffected.
+
+### Removed
+- The inert `smoke_fail_rate` monitor alert (could never fire — superseded by the always-on `config_broken` stop). Monitor now ships 11 detectors.
+
+### Docs
+- `thesis.md`: the stuck-loop defense is described honestly as a notify-level, opt-in-to-auto-stop monitor detector (`anomaly_repetitive_active`), not a default hard-stop; fixed the `stuck_loop_detected` naming drift.
+
 ## [0.1.41] - 2026-06-07
 
 ### Added
@@ -851,7 +875,8 @@ Initial public release on PyPI as `cli-agent-runner`.
 - Tag-triggered release publishing to PyPI via Trusted Publishing OIDC,
   gated by a manual approval on the `pypi` GitHub environment.
 
-[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.26...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.42...v0.2.0
 [0.1.26]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.25...v0.1.26
 [0.1.25]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.24...v0.1.25
 [0.1.24]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.23...v0.1.24

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.41
+Version: 0.2.0
 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)           │  12 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -86,14 +86,14 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 12 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-11 named defenses, structured as data — see `agent-runner peek --select defenses`.
+12 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:
 
@@ -106,10 +106,10 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
-## Monitor: 12 detectors
+## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`,
+`mem_pressure`, `network_fail`, `rate_limit_active`,
 `anomaly_repetitive_active`, `supervisor_stale`.
 
 **Auto-stop the service** (continuing is harmful):

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/README.md

@@ -12,7 +12,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  12 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -49,14 +49,14 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 12 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-11 named defenses, structured as data — see `agent-runner peek --select defenses`.
+12 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:
 
@@ -69,10 +69,10 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
-## Monitor: 12 detectors
+## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `smoke_fail_rate`, `network_fail`, `rate_limit_active`,
+`mem_pressure`, `network_fail`, `rate_limit_active`,
 `anomaly_repetitive_active`, `supervisor_stale`.
 
 **Auto-stop the service** (continuing is harmful):

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/README.zh.md

@@ -6,7 +6,7 @@
 
 把任意 CLI agent（Claude Code、自研 agent、任何长跑命令）包装成可被
 systemd / launchd 拉起、能被远程观测的服务。**每轮跑完进程退出**，外层
-supervisor 重启 —— 这是核心模式。中间穿插 11 条防御，避开 production 上
+supervisor 重启 —— 这是核心模式。中间穿插 12 条防御，避开 production 上
 最容易翻车的几条路：
 
 - 轮卡死、Tool 调用空转 → 硬墙 timeout
@@ -20,7 +20,7 @@ supervisor 重启 —— 这是核心模式。中间穿插 11 条防御，避开
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3：Witness（monitor）              │  12 个检测器 + 自动停服
+│ Layer 3：Witness（monitor）              │  11 个检测器 + 自动停服
 ├──────────────────────────────────────────┤
 │ Layer 2：Loop（serve，~120 LOC 薄壳）    │  捕获信号，循环拉起 round
 ├──────────────────────────────────────────┤
@@ -63,7 +63,7 @@ agent-runner monitor              # 实时异常检测，OAuth/磁盘 critical
 |---|---|
 | `init` / `install` / `uninstall` | `peek` —— 项目状态快照 |
 | `start` / `stop` / `kill` / `cancel` | `watch` —— peek 在刷新循环里 |
-| `restart` / `status` | `monitor` —— 12 个检测器 + 告警 + 自动停服 |
+| `restart` / `status` | `monitor` —— 11 个检测器 + 告警 + 自动停服 |
 | `round` / `serve` / `upgrade` | `events` —— 查询 / 流式订阅 events.jsonl |
 
 **停服三动词**有清晰的语义分层：
@@ -73,7 +73,7 @@ agent-runner monitor              # 实时异常检测，OAuth/磁盘 critical
 
 动词参考：[`docs/commands.md`](docs/commands.md)。
 
-## 内置防御（11 条）
+## 内置防御（12 条）
 
 防御以数据形式定义在 `agent_runner/defenses.py`，可通过
 `agent-runner peek --select defenses` 直接拿到。每条防御自带：
@@ -95,11 +95,11 @@ agent-runner monitor              # 实时异常检测，OAuth/磁盘 critical
 
 完整列表 + 历史出处：[`docs/architecture.md`](docs/architecture.md)。
 
-## Monitor：12 个检测器
+## Monitor：11 个检测器
 
 **只告警**（warning 级，服务继续跑）：
 `timeout_rate` / `hung` / `orphan_chain` / `disk_warning` /
-`mem_pressure` / `smoke_fail_rate` / `network_fail` / `rate_limit_active` /
+`mem_pressure` / `network_fail` / `rate_limit_active` /
 `anomaly_repetitive_active` / `supervisor_stale`
 
 **自动停服**（critical 级，继续是 net negative）：

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/__init__.py

@@ -14,6 +14,7 @@ _HOOK_GROUPS = (
     "agent_runner.context_enrichers",
     "agent_runner.post_round_hooks",
     "agent_runner.serve_startup_hooks",
+    "agent_runner.dirty_handler_hooks",
 )
 
 # Tracks the names passed to the most recent ``apply_plugin_disable`` call.
@@ -111,6 +112,9 @@ def apply_plugin_disable(names: list[str]) -> None:
     # Serve-startup hooks
     _prune_by_name(hooks._SERVE_STARTUP_HOOKS, desired, found)
 
+    # Dirty handlers
+    _prune_by_name(hooks._DIRTY_HANDLERS, desired, found)
+
     # Plugin event kinds
     for name in list(events._PLUGIN_KINDS):
         if name in desired:

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/_emit.py

@@ -45,6 +45,29 @@ def emit_max_rounds_reached(log_dir: Path, *, rounds_completed: int, max_rounds:
     emit(log_dir, MAX_ROUNDS_REACHED, rounds_completed=rounds_completed, max_rounds=max_rounds)
 
 
+def emit_config_broken(log_dir: Path, *, reason: str) -> None:
+    """Emit config_broken (serve stopped on a permanent startup-battery failure)."""
+    from agent_runner.events import CONFIG_BROKEN, emit
+
+    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.
+    """
+    from agent_runner._redact import redact_secrets
+    from agent_runner.events import CRASH_LOOP, emit
+
+    try:
+        reason = redact_secrets(log_path.read_text(errors="replace")[-2000:])
+    except OSError:
+        reason = ""
+    emit(log_dir, CRASH_LOOP, consecutive=consecutive, exit_code=exit_code, reason=reason)
+
+
 def emit_stop_file_detected(
     log_dir: Path, *, stop_file: Path, content: str, rounds_completed: int
 ) -> None:

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.41'
-__version_tuple__ = version_tuple = (0, 1, 41)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/api.py

@@ -18,7 +18,7 @@ import sysconfig
 import time
 from collections.abc import Iterator
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from agent_runner import events, lifecycle
 from agent_runner.api_types import (
@@ -45,6 +45,59 @@ from agent_runner.service_unit import (
     serve_unit_filename,
 )
 
+# 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.
+# Lives here (not runner.py) so serve_cmd can import it from the sanctioned api
+# facade without coupling to runner (runner imports api, not the reverse).
+PERMANENT_CONFIG_EXIT = 78
+
+# 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)
+
+
+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.
+    """
+    if returncode == PERMANENT_CONFIG_EXIT:
+        return ("config_broken", 0, consecutive)
+    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)
+
+
 _PROJECT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
 
 _LINGER_HINT = (
@@ -730,6 +783,8 @@ def check_self_terminated_sentinel(log_dir: Path) -> bool:
 from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-export
     emit_agent_usage_recorded,
     emit_anomaly_repetitive_tool,
+    emit_config_broken,
+    emit_crash_loop,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
@@ -744,6 +799,12 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_transient_error_recovered,
 )
 
+# Re-export git primitives so external callers can reach them via the api facade.
+from agent_runner.vcs_state import (  # noqa: E402,F401 — public primitives
+    stash_orphan,
+    try_auto_commit,
+)
+
 
 def narrate_events(log_dir: Path, *, poll_interval_s: float = 0.5) -> Iterator[str]:
     """Tail events-*.jsonl files in log_dir, yielding one formatted line per event.

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/api_types.py

@@ -28,6 +28,18 @@ class ServiceMode(StrEnum):
     NONE = "none"
 
 
+@dataclass(frozen=True)
+class DirtyOutcome:
+    """What a dirty tree resolved to, reported on RoundResult and via events.
+
+    ``ref`` is the stash SHA (kind="stashed") or commit SHA (kind="committed");
+    None for "ignored".
+    """
+
+    kind: Literal["stashed", "committed", "ignored"]
+    ref: str | None = None
+
+
 @dataclass(frozen=True)
 class RateLimitState:
     """Public: surfaced via peek --json when supervisor is currently throttled."""
@@ -158,6 +170,7 @@ class RoundResult:
     log_path: Path
     dirty_files: list[str]
     stashed: bool
+    dirty_outcome: DirtyOutcome | None = None
     killed_for_grace: bool = False
 
 

cli_agent_runner-0.2.0/agent_runner/builtin_plugins/default_dirty_handler.py

@@ -0,0 +1,83 @@
+"""Bundled default dirty-tree handler — reproduces the pre-0.2.0 built-in
+behavior (stash / ignore / auto_commit per [vcs] dirty_action) as a plugin.
+Ships enabled; disable via [plugins] disable = ["default_dirty_handler"]."""
+
+from __future__ import annotations
+
+from agent_runner import api, context_store, events, vcs_state
+from agent_runner.api_types import DirtyOutcome
+from agent_runner.events import now_iso_ms  # match the helper runner.py uses
+from agent_runner.hooks import HookContext, register_dirty_handler
+from agent_runner.vcs_state import AutoCommitError
+
+
+class DefaultDirtyHandler:
+    name = "default_dirty_handler"
+    priority = 1000  # last-resort fallback
+
+    def handle_dirty(self, ctx: HookContext, dirty_files) -> DirtyOutcome | None:
+        action = ctx.vcs.dirty_action if ctx.vcs else "stash"
+        if action == "ignore":
+            return DirtyOutcome(kind="ignored")
+        if action == "auto_commit":
+            try:
+                sha = api.try_auto_commit(
+                    ctx.work_dir, ctx.round_num, ctx.phase, log_dir=ctx.log_dir
+                )
+            except AutoCommitError as exc:
+                # Parity with runner.py: emit failure event, leave tree dirty
+                # (no stash fallback). Dirty tree carries into the next round.
+                events.emit(
+                    ctx.log_dir,
+                    events.DIRTY_COMMIT_FAILED,
+                    round_num=ctx.round_num,
+                    phase=ctx.phase,
+                    reason=str(exc),
+                )
+                return DirtyOutcome(kind="ignored")
+            if not sha:
+                return DirtyOutcome(kind="ignored")
+            events.emit(
+                ctx.log_dir,
+                events.DIRTY_AUTO_COMMITTED,
+                round_num=ctx.round_num,
+                files=dirty_files[:20],
+                ref=sha,
+            )
+            return DirtyOutcome(kind="committed", ref=sha)
+        return self._stash(ctx, dirty_files)
+
+    def _stash(self, ctx: HookContext, dirty_files) -> DirtyOutcome:
+        # via vcs_state (not api): test_runner.py monkeypatches vcs_state.stash_orphan;
+        # the api re-export is a separate binding a patch wouldn't intercept.
+        ref = vcs_state.stash_orphan(
+            ctx.work_dir,
+            round_num=ctx.round_num,
+            phase=ctx.phase,
+            idempotency_s=ctx.vcs.stash_idempotency_s if ctx.vcs else 5,
+            log_dir=ctx.log_dir,
+        )
+        if ref is None:
+            return DirtyOutcome(kind="ignored")
+        context_store.write_orphan_state(
+            ctx.log_dir,
+            context_store.OrphanState(
+                round_num=ctx.round_num,
+                files=dirty_files,
+                stashed_ref=ref.sha,
+                stash_message=ref.message,
+                timestamp=now_iso_ms(),
+                phase=ctx.phase,
+            ),
+        )
+        events.emit(
+            ctx.log_dir,
+            events.ORPHAN_STASHED,
+            round_num=ctx.round_num,
+            ref=ref.sha,
+            reason="clean_exit_with_dirty_tree",
+        )
+        return DirtyOutcome(kind="stashed", ref=ref.sha)
+
+
+register_dirty_handler(DefaultDirtyHandler())

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/cli/serve_cmd.py

@@ -23,12 +23,15 @@ from agent_runner._throttle import _check_throttle_state
 from agent_runner._throttle import reset_counters as _reset_counters
 from agent_runner.api import (
     check_self_terminated_sentinel,
+    emit_config_broken,
+    emit_crash_loop,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
     emit_round_substrate_after,
     emit_round_substrate_before,
     emit_stop_file_detected,
+    post_round_decision,
 )
 from agent_runner.cli.common import cfg_from_args
 from agent_runner.hooks import run_serve_startup_hooks
@@ -135,6 +138,7 @@ def cmd(args) -> int:
     stop_file = cfg.runtime.stop_file  # cache: same pattern as effective_max_rounds
     work_dir = cfg.runtime.work_dir
     rounds_completed = 0
+    consecutive_crashes = 0  # b12: consecutive UNKNOWN short crashes (crash-loop breaker)
 
     try:
         pid_file.write(os.getpid())
@@ -197,6 +201,7 @@ def cmd(args) -> int:
                     every_n=cfg.runtime.fresh_eyes_every_n,
                 )
             round_log_path = log_dir / f"round-{round_num}.log"
+            round_started = time.monotonic()
             with round_log_path.open("w") as f:
                 r = subprocess.run(
                     [
@@ -211,6 +216,7 @@ def cmd(args) -> int:
                     stdout=f,
                     stderr=subprocess.STDOUT,
                 )
+            round_duration_s = time.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)
@@ -221,13 +227,28 @@ def cmd(args) -> int:
                 paths_hash=paths_hash_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.
+            action, delay, consecutive_crashes = post_round_decision(
+                returncode=r.returncode,
+                duration_s=round_duration_s,
+                throttle_active=_check_throttle_state(log_dir) is not None,
+                consecutive=consecutive_crashes,
+                restart_delay_s=cfg.runtime.restart_delay_s,
+            )
+            if action == "config_broken":
+                emit_config_broken(log_dir, reason="startup battery permanent failure")
+                break
+            if action == "crash_loop":
+                emit_crash_loop(
+                    log_dir,
+                    consecutive=consecutive_crashes,
+                    exit_code=r.returncode,
+                    log_path=round_log_path,
+                )
+                break
             if args.once or stop["requested"]:
                 break
-            delay = (
-                cfg.runtime.restart_delay_s
-                if r.returncode == 0
-                else cfg.runtime.restart_delay_s * 2
-            )
             time.sleep(delay)
     finally:
         pid_file.unlink()

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/defenses.py

@@ -83,8 +83,18 @@ def catalog(cfg: Config) -> list[Defense]:
         Defense(
             name="startup_smoke_check",
             value="6 checks (config / log_dir / agent_cli / git / prompt_file / prompt_smoke)",
-            codifies="R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn",
-            guarded_by=None,
+            codifies=(
+                "R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn; "
+                "now halts serve (config_broken) instead of respawning a broken config"
+            ),
+            guarded_by=Path("tests/unit/test_serve_config_broken.py"),
+            current_state="active",
+        ),
+        Defense(
+            name="crash_loop_breaker",
+            value="stop after 5 consecutive short crashes; exp-escalating delay",
+            codifies="Run 6 — crashing agent respawned ~100 empty rounds at a fixed 2x delay",
+            guarded_by=Path("tests/unit/test_serve_crash_loop.py"),
             current_state="active",
         ),
         Defense(

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/events.py

@@ -32,6 +32,9 @@ ANOMALY_REPETITIVE_TOOL = "anomaly_repetitive_tool"
 AGENT_NETWORK_BLIP = "agent_network_blip"
 AGENT_SPAWN = "agent_spawn"
 AGENT_USAGE_RECORDED = "agent_usage_recorded"
+CONFIG_BROKEN = "config_broken"
+CRASH_LOOP = "crash_loop"
+DIRTY_AUTO_COMMITTED = "dirty_auto_committed"
 DIRTY_COMMIT_FAILED = "dirty_commit_failed"
 DIRTY_DETECTED = "dirty_detected"
 FRESH_EYES_ROUND_TRIGGERED = "fresh_eyes_round_triggered"

{cli_agent_runner-0.1.41 → cli_agent_runner-0.2.0}/agent_runner/hooks.py

@@ -30,6 +30,7 @@ Public API:
 from __future__ import annotations
 
 import sys
+import traceback as tb_mod
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
@@ -43,6 +44,14 @@ _TAIL_BYTES = 1024
 _TRUNC_MARKER = "\n... [truncated] ...\n"
 
 
+@dataclass(frozen=True)
+class VcsHookView:
+    """Minimal vcs config a dirty handler needs (keeps HookContext narrow)."""
+
+    dirty_action: str
+    stash_idempotency_s: int
+
+
 @dataclass(frozen=True)
 class HookContext:
     """Narrow per-round context passed to all hook callbacks.
@@ -86,6 +95,26 @@ class HookContext:
     """Count threshold for repetitive-tool anomaly (0 = disabled).
     Populated from ``[monitor] anomaly_repetitive_threshold`` (0.1.31+).
     """
+    vcs: VcsHookView | None = None
+    """Narrowed vcs config slice populated by the runner for all per-round hooks
+    (pre-round, enrichers, post-round, dirty-handler) (0.2.0+).
+    May be None only when a HookContext is constructed without it (e.g. tests).
+    """
+
+
+@runtime_checkable
+class DirtyHandler(Protocol):
+    """Resolves a clean-exit dirty tree. Runs ascending by ``priority``; the
+    first to return a DirtyOutcome wins. Return None to pass to the next."""
+
+    name: str
+    priority: int
+
+    def handle_dirty(
+        self,
+        ctx: HookContext,
+        dirty_files: list[str],
+    ) -> Any | None: ...
 
 
 @runtime_checkable
@@ -148,6 +177,7 @@ _PRE_ROUND_HOOKS: list[PreRoundHook] = []
 _CONTEXT_ENRICHERS: list[ContextEnricher] = []
 _POST_ROUND_HOOKS: list[PostRoundHook] = []
 _SERVE_STARTUP_HOOKS: list[ServeStartupHook] = []
+_DIRTY_HANDLERS: list[DirtyHandler] = []
 
 
 def register_pre_round_hook(hook: PreRoundHook) -> None:
@@ -191,6 +221,43 @@ def plugin_context_enrichers() -> list[str]:
     return sorted(e.name for e in _CONTEXT_ENRICHERS)
 
 
+def register_dirty_handler(handler: DirtyHandler) -> None:
+    ensure_unique(handler.name, _DIRTY_HANDLERS, "dirty_handler")
+    _DIRTY_HANDLERS.append(handler)
+
+
+def dirty_handlers() -> list[DirtyHandler]:
+    return list(_DIRTY_HANDLERS)
+
+
+def dispatch_dirty(
+    ctx: HookContext,
+    dirty_files: list[str],
+    log_dir: Path,
+) -> Any | None:
+    """Run registered DirtyHandlers ascending by priority; first non-None wins.
+
+    A handler that raises is isolated — emits ``hook_failed`` with
+    ``hook_kind="dirty_handler"`` and treated as pass (continue to next).
+    """
+    ordered = sorted(_DIRTY_HANDLERS, key=lambda h: getattr(h, "priority", 0))
+    for h in ordered:
+        try:
+            outcome = h.handle_dirty(ctx, dirty_files)
+        except Exception as exc:  # noqa: BLE001 — isolate; fall through to next
+            events.emit(
+                log_dir,
+                events.HOOK_FAILED,
+                hook_name=h.name,
+                hook_kind="dirty_handler",
+                **_summarize_error(exc, tb=tb_mod.format_exc()),
+            )
+            continue
+        if outcome is not None:
+            return outcome
+    return None
+
+
 def run_serve_startup_hooks(cfg: Any, log_dir: Path) -> bool:
     """Run all serve_startup_hooks. Returns True on success, False on abort.