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

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

@@ -5,6 +5,15 @@ 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
@@ -866,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.42 → cli_agent_runner-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.42
+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
@@ -109,7 +109,7 @@ Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 ## 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.42 → cli_agent_runner-0.2.0}/README.md

@@ -72,7 +72,7 @@ Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 ## 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.42 → cli_agent_runner-0.2.0}/README.zh.md

@@ -99,7 +99,7 @@ agent-runner monitor              # 实时异常检测，OAuth/磁盘 critical
 
 **只告警**（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.42 → 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.42 → 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.42'
-__version_tuple__ = version_tuple = (0, 1, 42)
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
 
 __commit_id__ = commit_id = None

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

@@ -799,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.42 → 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.42 → cli_agent_runner-0.2.0}/agent_runner/events.py

@@ -34,6 +34,7 @@ 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.42 → 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.
 

{cli_agent_runner-0.1.42 → cli_agent_runner-0.2.0}/agent_runner/runner.py

@@ -423,6 +423,10 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         dry_run=cfg.runtime.dry_run,
         anomaly_repetitive_window=cfg.monitor.anomaly_repetitive_window,
         anomaly_repetitive_threshold=cfg.monitor.anomaly_repetitive_threshold,
+        vcs=hooks.VcsHookView(
+            dirty_action=cfg.vcs.dirty_action,
+            stash_idempotency_s=cfg.vcs.stash_idempotency_s,
+        ),
     )
     _run_pre_round_hooks(
         hook_ctx,
@@ -512,54 +516,12 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
     if dirty:
         events.emit(log_dir, "dirty_detected", round_num=round_num, files=dirty[:20])
 
-    stashed = False
-    action = cfg.vcs.dirty_action
+    dirty_outcome = None
     if dirty and not result.timed_out and result.exit_code == 0:
-        if action == "stash":
-            ref = vcs_state.stash_orphan(
-                cfg.runtime.work_dir,
-                round_num=round_num,
-                phase=phase,
-                idempotency_s=cfg.vcs.stash_idempotency_s,
-                log_dir=cfg.runtime.log_dir,
-            )
-            if ref is not None:
-                context_store.write_orphan_state(
-                    log_dir,
-                    context_store.OrphanState(
-                        round_num=round_num,
-                        files=dirty,
-                        stashed_ref=ref.sha,
-                        stash_message=ref.message,
-                        timestamp=now_iso_ms(),
-                        phase=phase,
-                    ),
-                )
-                events.emit(
-                    log_dir,
-                    "orphan_stashed",
-                    round_num=round_num,
-                    ref=ref.sha,
-                    reason="clean_exit_with_dirty_tree",
-                )
-                stashed = True
-        elif action == "ignore":
-            # Leave tree dirty for next round; dirty_detected already emitted
-            pass
-        elif action == "auto_commit":
-            err = vcs_state.try_auto_commit(
-                cfg.runtime.work_dir, round_num, phase, log_dir=cfg.runtime.log_dir
-            )
-            if err is not None:
-                events.emit(
-                    log_dir,
-                    events.DIRTY_COMMIT_FAILED,
-                    round_num=round_num,
-                    phase=phase,
-                    reason=err,
-                )
+        dirty_outcome = hooks.dispatch_dirty(hook_ctx, dirty, log_dir=log_dir)
     elif not dirty:
         context_store.clear_orphan_state(log_dir)
+    stashed = bool(dirty_outcome and dirty_outcome.kind == "stashed")
 
     if result.killed_for_grace:
         api.emit_round_grace_kill(
@@ -609,6 +571,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         log_path=log_path,
         dirty_files=dirty,
         stashed=stashed,
+        dirty_outcome=dirty_outcome,
         killed_for_grace=result.killed_for_grace,
     )
     _run_post_round_hooks(hook_ctx, round_result, log_dir)

{cli_agent_runner-0.1.42 → cli_agent_runner-0.2.0}/agent_runner/vcs_state.py

@@ -72,6 +72,10 @@ def _matches_owned_path(path: str) -> bool:
     return False
 
 
+class AutoCommitError(RuntimeError):
+    """git add/commit failed during try_auto_commit (reason capped at 200 chars)."""
+
+
 @dataclass(frozen=True)
 class StashRef:
     sha: str  # full commit SHA — IMMUTABLE under concurrent stash
@@ -322,20 +326,13 @@ def try_auto_commit(
     phase: str | None,
     *,
     log_dir: Path | None = None,
-) -> str | None:
-    """Auto-commit dirty tree with hardcoded subject. Return None on success, error on failure.
-
-    Subject: ``agent-runner auto-commit: R<N> <phase>`` (phase part omitted if None).
-    Uses ``git -c commit.gpgsign=false`` to skip GPG; honors pre-commit hooks
-    (no ``--no-verify``). DOES NOT push — local commit only.
+) -> str:
+    """Auto-commit the dirty tree with a hardcoded subject; return the commit SHA.
 
-    ``log_dir`` (when under ``work_dir``) is excluded from the add so a zero-work
-    round that only churned the runner's own bookkeeping (lock/pid/event logs)
-    does not advance ``git_head``. The agent's work and ``.evolving/`` live
-    outside ``log_dir`` and are still committed. If nothing remains staged after
-    the exclusion, this is a no-op (returns None, leaves HEAD untouched).
-
-    Callers (runner.py) emit ``dirty_commit_failed`` event when return value is not None.
+    Returns "" when nothing remained staged after excluding log_dir (no-op;
+    HEAD untouched). Raises AutoCommitError on git failure. DOES NOT push.
+    Subject: ``agent-runner auto-commit: R<N> <phase>``. Uses
+    ``git -c commit.gpgsign=false``; honors pre-commit hooks (no --no-verify).
     """
     phase_part = f" {phase}" if phase else ""
     subject = f"agent-runner auto-commit: R{round_num}{phase_part}"
@@ -343,13 +340,13 @@ def try_auto_commit(
     exclude = _log_dir_exclude_pathspec(work_dir, log_dir)
     add_result = _git(work_dir, "add", "-A", *exclude)
     if add_result.returncode != 0:
-        return (add_result.stderr or "git add failed")[:200]
+        raise AutoCommitError((add_result.stderr or "git add failed")[:200])
 
     # Only the exclusion can leave nothing staged (a zero-work round that churned
     # only log_dir); without it the tree was dirty so there is always something to
     # commit. Skip the extra git call on the common (no-exclusion) path.
     if exclude and _git(work_dir, "diff", "--cached", "--quiet").returncode == 0:
-        return None
+        return ""
 
     commit_result = _git(
         work_dir,
@@ -359,6 +356,7 @@ def try_auto_commit(
         pre_flags=("-c", "commit.gpgsign=false"),
     )
     if commit_result.returncode != 0:
-        return (commit_result.stderr or "git commit failed")[:200]
+        raise AutoCommitError((commit_result.stderr or "git commit failed")[:200])
 
-    return None
+    head = _git(work_dir, "rev-parse", "HEAD")
+    return head.stdout.strip()

{cli_agent_runner-0.1.42 → cli_agent_runner-0.2.0}/docs/architecture.md

@@ -72,8 +72,8 @@ Three categories by `auto_action`:
 
 **Notify only** (severity `warning`):
 `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`, `mem_pressure`,
-`smoke_fail_rate`, `network_fail`, `rate_limit_active`,
-`anomaly_repetitive_active`, `supervisor_stale`.
+`network_fail`, `rate_limit_active`, `anomaly_repetitive_active`,
+`supervisor_stale`.
 
 **Auto-stop service** (severity `critical`, `auto_action="stop_service"`):
 `oauth_fail`, `disk_critical`. Continuing in either state is harmful (burning
@@ -142,6 +142,29 @@ Setting `inject_context = false` does NOT disable PreRoundHooks. Setting
 If you want neither injection: set both. If you want to disable a specific plugin
 hook (vs ALL pre-round hooks), use `[plugins] disable = ["that_entry_point_name"]`.
 
+## Dirty-handler seam (0.2.0+)
+
+After a round exits cleanly with a dirty working tree, the runner dispatches a
+priority-ordered chain of registered `DirtyHandler` plugins. The first to return
+a non-`None` `DirtyOutcome` wins; remaining handlers are skipped.
+
+This makes dirty-tree policy fully pluggable. The `default_dirty_handler` plugin
+(bundled, default-on, priority 1000) implements the `stash` / `ignore` /
+`auto_commit` policy from `[vcs] dirty_action` — so the external behavior is
+identical to pre-0.2.0 unless a consumer plugin intervenes first.
+
+**Lifecycle-hook family** (4 groups, run in this order per round):
+
+1. `serve_startup_hooks` — once at `agent-runner serve` boot, before the loop
+2. `pre_round_hooks` — after lock acquire, before context is written
+3. `post_round_hooks` (+ `context_enrichers`) — after agent exits, before `round_end`
+4. `dirty_handler_hooks` — after post_round, if the tree is dirty on a clean exit
+
+The stash *mechanism* (SHA lock, idempotency guard, `stash_orphan` /
+`try_auto_commit` primitives) stays in core. The stash *policy* is plugin-provided.
+
+See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
+
 ## Known event kinds
 
 <!-- gen:event-kinds -->
@@ -153,6 +176,7 @@ hook (vs ALL pre-round hooks), use `[plugins] disable = ["that_entry_point_name"
 - `anomaly_repetitive_tool`
 - `config_broken`
 - `crash_loop`
+- `dirty_auto_committed`
 - `dirty_commit_failed`
 - `dirty_detected`
 - `fresh_eyes_round_triggered`

{cli_agent_runner-0.1.42 → cli_agent_runner-0.2.0}/docs/configuration.md

@@ -90,13 +90,17 @@ Type: string, one of `"stash"`, `"ignore"`, `"auto_commit"`
 Default: `"stash"`
 
 Controls supervisor behavior when round subprocess exits with a dirty
-working tree:
+working tree. This config is read by the bundled `default_dirty_handler` plugin
+(0.2.0+, default-on). Existing behavior and TOML are unchanged.
 
 | Value | Behavior |
 |---|---|
 | `"stash"` | Auto-stash dirty tree with ORPHAN-prefix message. `dirty_detected` + `orphan_stashed` events emitted. |
 | `"ignore"` | Emit `dirty_detected` event only. Working tree left dirty for next round. |
-| `"auto_commit"` | Supervisor commits with subject `agent-runner auto-commit: R<N> <phase>`. No push. On failure, emits `dirty_commit_failed`, leaves tree dirty. |
+| `"auto_commit"` | Supervisor commits with subject `agent-runner auto-commit: R<N> <phase>`. No push. On success, emits `dirty_auto_committed`. On failure, emits `dirty_commit_failed`, leaves tree dirty. |
+
+To replace this policy entirely, disable the bundled plugin and register your own
+`DirtyHandler` — see `docs/plugins.md` and `docs/migrations/0.2.0.md`.
 
 ## `[agent.env]` (optional)