cli-agent-runner 0.1.7__tar.gz → 0.1.8__tar.gz

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-05-13
+
+### Acknowledgements
+
+Thanks to the argus-gateway team for Phase 4 dogfooding feedback that drove
+every item in this release. 3 audit memos (~90KB) silently swept into an
+orphan stash is a real-world failure mode; this release closes that loop.
+
+### Added
+
+- `agent_runner.vcs_state.register_plugin_owned_paths()` — plugins opt-out
+  files/dirs from orphan-stash defense. Matching: trailing-slash prefix or
+  `pathlib.PurePath.match` glob (recognizes `**` for recursive segments via
+  `fnmatch` fallback on Python 3.11). Call at module import (entry_point
+  side-effect).
+- `agent_runner.vcs_state.plugin_owned_paths()` — snapshot accessor for peek.
+- `ProjectState.recent_hook_failures: list[dict]` — last 10 `hook_failed`
+  events filtered from `recent_events` for debugging hook integration.
+- peek schema bumped 1.4 → 1.5. `plugins` block now includes
+  `pre_round_hooks`, `post_round_hooks`, `owned_paths` lists.
+
+### Changed
+
+- `docs/plugins.md` register-pattern examples corrected: registration must
+  happen as module-top side effect; entry_point loaders only import, they
+  do not invoke. Old `_register()` wrapper pattern silently didn't fire.
+- `docs/plugins.md` gained "Declaring plugin-owned paths" and "Plugin tests
+  + consumer pytest collision" sections.
+
+### Fixed
+
+- Plugin outputs in plugin-declared paths (e.g. `proposals/`,
+  `logs/plugins/my_plugin/`) no longer silently swept into orphan stashes
+  by `process_orphan_wip`. Previously: 90KB Argus audit memos invisible
+  after Phase 4 round; required stash archaeology to recover.
+
+### Migration
+
+No breaking changes. Plugin authors:
+
+- If your plugin writes files to `work_dir` and they keep getting stashed
+  between rounds, opt them out:
+  ```python
+  from agent_runner.vcs_state import register_plugin_owned_paths
+  register_plugin_owned_paths(["your-output-dir/", "logs/your-plugin/**/*"])
+  ```
+- If you followed the old `_register()` pattern from docs and noticed
+  registrations not firing: move the call to module top:
+  ```python
+  # was: def _register(): register_pre_round_hook(MyHook())
+  # now: register_pre_round_hook(MyHook())  # module-top side-effect
+  ```
+
 ## [0.1.7] - 2026-05-13
 
 ### Migration for existing 0.1.6 users (DOWNSTREAM CONSUMERS READ THIS)

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.7
+Version: 0.1.8
 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.1.7 → cli_agent_runner-0.1.8}/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.7'
-__version_tuple__ = version_tuple = (0, 1, 7)
+__version__ = version = '0.1.8'
+__version_tuple__ = version_tuple = (0, 1, 8)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/api.py

@@ -240,6 +240,9 @@ def _log_dir_for_project(project: str | Path) -> Path:
 # for callers that only use lifecycle verbs.
 
 from agent_runner import defenses, monitor  # noqa: E402
+from agent_runner.events import HOOK_FAILED  # noqa: E402
+
+_RECENT_HOOK_FAILURES_LIMIT = 10
 
 
 def peek(
@@ -266,6 +269,16 @@ def peek(
         if current is None:
             raise KeyError(f"round {round_num} not found under {log_dir}/rounds/")
     recent = parsed_events[-events:] if events else []
+    # Walk the tail in reverse so we stop as soon as the limit is filled.
+    # parsed_events grows unboundedly over a project's lifetime; a full-scan
+    # comprehension here would dominate watch-loop peek cost.
+    recent_hook_failures: list[dict[str, Any]] = []
+    for e in reversed(parsed_events):
+        if e.get("event") == HOOK_FAILED:
+            recent_hook_failures.append(e)
+            if len(recent_hook_failures) == _RECENT_HOOK_FAILURES_LIMIT:
+                break
+    recent_hook_failures.reverse()
 
     state = ProjectState(
         project=base_state.project,
@@ -286,6 +299,7 @@ def peek(
         system=base_state.system,
         service=status(project if project is not None else work_dir),
         recent_events=recent,
+        recent_hook_failures=recent_hook_failures,
     )
     return state if select is None else select_path(state, select)
 

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/api_types.py

@@ -72,6 +72,7 @@ class ProjectState:
     system: SystemMetrics
     service: ServiceStatus
     recent_events: list[dict[str, Any]] = field(default_factory=list)
+    recent_hook_failures: list[dict[str, Any]] = field(default_factory=list)
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/cli/common.py

@@ -12,10 +12,11 @@ from typing import Any
 from agent_runner.api_types import ProjectState
 from agent_runner.config import Config, load_config
 from agent_runner.events import plugin_event_kinds
-from agent_runner.hooks import plugin_context_enrichers
+from agent_runner.hooks import plugin_context_enrichers, post_round_hooks, pre_round_hooks
 from agent_runner.monitor import plugin_detectors
+from agent_runner.vcs_state import plugin_owned_paths
 
-PEEK_SCHEMA_VERSION = "1.4"
+PEEK_SCHEMA_VERSION = "1.5"
 
 
 def cfg_from_args(args) -> Config:
@@ -48,7 +49,10 @@ def emit(value: Any, *, json_mode: bool) -> None:
                 "plugins": {
                     "event_kinds": plugin_event_kinds(),
                     "context_enrichers": plugin_context_enrichers(),
+                    "pre_round_hooks": [h.name for h in pre_round_hooks()],
+                    "post_round_hooks": [h.name for h in post_round_hooks()],
                     "detectors": plugin_detectors(),
+                    "owned_paths": plugin_owned_paths(),
                 },
                 **_to_jsonable(value),
             }

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/events.py

@@ -22,6 +22,11 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
+# Cross-module event-kind constants. Most kinds are emitted in only one place
+# (runner.py), but kinds that are also CONSUMED elsewhere (filtered, surfaced
+# in peek, asserted in tests) earn a constant to keep the spelling honest.
+HOOK_FAILED = "hook_failed"
+
 _BUILTIN_KINDS: frozenset[str] = frozenset(
     {
         "round_start",
@@ -38,7 +43,7 @@ _BUILTIN_KINDS: frozenset[str] = frozenset(
         "round_end",
         "monitor_alert_emitted",
         "monitor_auto_stop_triggered",
-        "hook_failed",
+        HOOK_FAILED,
     }
 )
 

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/runner.py

@@ -95,7 +95,7 @@ def _stitch_enricher_slices(
             payload = hooks._summarize_error(exc, tb=tb_mod.format_exc())
             events.emit(
                 log_dir,
-                "hook_failed",
+                events.HOOK_FAILED,
                 hook_name=enricher.name,
                 hook_kind="context_enricher",
                 **payload,
@@ -114,7 +114,7 @@ def _run_pre_round_hooks(hook_ctx: hooks.HookContext, log_dir: Path) -> None:
             payload = hooks._summarize_error(exc, tb=tb_mod.format_exc())
             events.emit(
                 log_dir,
-                "hook_failed",
+                events.HOOK_FAILED,
                 hook_name=hook.name,
                 hook_kind="pre_round",
                 **payload,
@@ -136,7 +136,7 @@ def _run_post_round_hooks(
             payload = hooks._summarize_error(exc, tb=tb_mod.format_exc())
             events.emit(
                 log_dir,
-                "hook_failed",
+                events.HOOK_FAILED,
                 hook_name=hook.name,
                 hook_kind="post_round",
                 **payload,

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/agent_runner/vcs_state.py

@@ -7,14 +7,69 @@ Stash safety rules (R820 + §9 IMMUTABLE):
   design means external concurrent ``git stash push`` is not a defended scenario.
 - "Auto-tool change vs human change" detection uses set-based diff vs HEAD,
   not unified-diff +/-line parsing (R2110 lesson).
+- Also hosts the plugin-owned-paths registry consumed by
+  ``detect_dirty_files()`` so plugins can opt files/dirs out of the
+  orphan-stash defense (0.1.8+).
 """
 
 from __future__ import annotations
 
+import fnmatch
 import subprocess  # noqa: TID251 — vcs_state.py is the only sanctioned git CLI caller
 import time
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePath
+
+# Plugin-owned paths registry — set via register_plugin_owned_paths().
+# detect_dirty_files() filters its return through this list, so plugin-declared
+# paths are not flagged as orphan WIP and not stashed by the supervisor.
+_PLUGIN_OWNED_PATHS: list[str] = []
+
+
+def register_plugin_owned_paths(paths: list[str]) -> None:
+    """Register paths the plugin considers its own deliverables.
+
+    Paths are relative to the work_dir. Matching:
+
+      - Trailing ``/`` → prefix match (e.g. ``"proposals/"`` matches
+        ``"proposals/dev-round1.md"`` and the bare directory name).
+      - Anything else without ``**`` → ``pathlib.PurePath.match`` glob
+        (e.g. ``"reports/*.md"``). Single ``*`` does not cross slashes.
+      - Patterns containing ``**`` → ``fnmatch.fnmatch`` (e.g.
+        ``"logs/plugins/**/*"``). ``**`` matches recursive directory
+        segments. (``PurePath.full_match`` would handle this natively
+        but requires Python 3.13+; this project's minimum is 3.11.)
+
+    Plugins call this at module import time (entry_point side-effect) so the
+    paths are known before the first round runs.
+
+    Raises ValueError on non-string entries.
+    """
+    for p in paths:
+        if not isinstance(p, str):
+            raise ValueError(f"register_plugin_owned_paths: non-string entry {p!r}")
+    _PLUGIN_OWNED_PATHS.extend(paths)
+
+
+def plugin_owned_paths() -> list[str]:
+    """Snapshot of registered plugin-owned paths (for peek visibility)."""
+    return list(_PLUGIN_OWNED_PATHS)
+
+
+def _matches_owned_path(path: str) -> bool:
+    """True if `path` matches any registered plugin-owned pattern."""
+    for pattern in _PLUGIN_OWNED_PATHS:
+        if pattern.endswith("/"):
+            stripped = pattern.rstrip("/")
+            if path == stripped or path.startswith(pattern):
+                return True
+        elif "**" in pattern:
+            # fnmatch handles ** recursively; PurePath.match (3.11) does not.
+            if fnmatch.fnmatch(path, pattern):
+                return True
+        elif PurePath(path).match(pattern):
+            return True
+    return False
 
 
 @dataclass(frozen=True)
@@ -74,6 +129,10 @@ def detect_dirty_files(repo: Path) -> list[str]:
         else:
             out.append(path)
             i += 1
+    # Filter out plugin-declared paths (0.1.8+). Early-out preserves zero
+    # behavior change when no plugin has registered anything.
+    if _PLUGIN_OWNED_PATHS:
+        out = [p for p in out if not _matches_owned_path(p)]
     return out
 
 

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/docs/plugins.md

@@ -10,6 +10,12 @@ plugin code is observability/coordination glue, not workflow logic.
 
 ## Entry-points groups (0.1.3)
 
+> **Entry-point semantics:** agent-runner imports the target module when it
+> loads a plugin. It does **not** call the target as a function — registration
+> must happen as a module-top side effect (the `register_*` call at module
+> level). A `def _register():` wrapper around the call will NOT fire; the
+> loader only imports.
+
 | Group | Purpose | Available in |
 |---|---|---|
 | `agent_runner.event_kinds` | Register custom event kind names | 0.1.3+ |
@@ -22,7 +28,7 @@ detectors are reserved for 0.1.4 and 0.1.5.
 ```toml
 # my_plugin/pyproject.toml
 [project.entry-points."agent_runner.event_kinds"]
-my_workflow_stage_advanced = "my_plugin.events:_register"
+my_workflow_stage_advanced = "my_plugin.events"
 ```
 
 ```python
@@ -31,9 +37,9 @@ from agent_runner.events import register_event_kind
 
 STAGE_ADVANCED = "my_workflow_stage_advanced"
 
-
-def _register() -> None:
-    register_event_kind(STAGE_ADVANCED, source="my-plugin@1.0")
+# Module-top side effect: entry_point load imports this module, which
+# triggers the registration.
+register_event_kind(STAGE_ADVANCED, source="my-plugin@1.0")
 ```
 
 After installation, the registered kind:
@@ -84,7 +90,7 @@ Its field set is stable across 0.1.x (additions only).
 ```toml
 # my_plugin/pyproject.toml
 [project.entry-points."agent_runner.context_enrichers"]
-current_branch = "my_plugin.enrichers:_register"
+current_branch = "my_plugin.enrichers"
 ```
 
 ```python
@@ -104,8 +110,9 @@ class CurrentBranchEnricher:
         return {"branch": out.stdout.strip() or "(detached)"}
 
 
-def _register() -> None:
-    register_context_enricher(CurrentBranchEnricher())
+# Module-top side effect: entry_point load imports this module, which
+# triggers the registration.
+register_context_enricher(CurrentBranchEnricher())
 ```
 
 After installation, each round's `round-context.json` gains a `current_branch` key:
@@ -164,7 +171,7 @@ detectors that run alongside the 9 builtins on every monitor poll.
 
 ```toml
 [project.entry-points."agent_runner.detectors"]
-my_detector = "my_plugin.detectors:_register"
+my_detector = "my_plugin.detectors"
 ```
 
 ```python
@@ -191,8 +198,9 @@ class MyDetector:
         )
 
 
-def _register() -> None:
-    register_detector(MyDetector())
+# Module-top side effect: entry_point load imports this module, which
+# triggers the registration.
+register_detector(MyDetector())
 ```
 
 `Detector` is a `@runtime_checkable` Protocol — `isinstance(obj, Detector)` returns
@@ -309,3 +317,92 @@ class NoCommitsDetector:
 **Codifies the lesson:** "0 commits in N rounds" detectors mis-fire on
 retrospective/reflection phases that intentionally produce zero commits.
 Pass the set of phase names where the detector should NOT run.
+
+## Declaring plugin-owned paths (0.1.8+)
+
+If your plugin writes files inside the supervisor's `work_dir`
+(audit memos, generated reports, plugin-local state, etc.), declare them
+so the orphan-stash defense doesn't silently sweep them into a stash
+between rounds.
+
+```python
+# my_plugin/__init__.py
+from agent_runner.vcs_state import register_plugin_owned_paths
+
+# Module-top side effect — must register before the first round runs.
+register_plugin_owned_paths([
+    "proposals/",                  # trailing slash → prefix match
+    "logs/plugins/my_plugin/**/*", # recursive glob (fnmatch)
+    "reports/*.md",                # single-segment glob (PurePath.match)
+])
+```
+
+### Matching semantics
+
+| Pattern | Matches | Notes |
+|---|---|---|
+| `"proposals/"` | `proposals`, `proposals/foo.md`, `proposals/sub/bar.md` | Trailing `/` → prefix match. |
+| `"proposals"` (no slash) | `proposals` exactly | Single-segment literal. |
+| `"reports/*.md"` | `reports/dev.md` | `*` does not cross slashes. |
+| `"reports/**/*.md"` | `reports/dev.md`, `reports/sub/qa.md` | `**` matches across directory separators. |
+| `"logs/plugins/**/*"` | `logs/plugins/argus/state.json` | Same — `**` covers intermediate dirs. |
+
+### Caveat — this is NOT a "make work_dir messy" license
+
+Plugin-owned paths express *"these are the plugin's expected deliverable
+files; do not stash them"*. They are not permission to scatter scratch
+files. Operator owns cleanup of these paths.
+
+If your plugin writes ephemeral state that should be cleaned up between
+rounds, do the cleanup yourself in a `PostRoundHook` — don't rely on
+the orphan-stash defense to sweep it.
+
+### Visibility
+
+`agent-runner peek --select plugins.owned_paths` shows the currently
+registered list (peek schema v1.5+).
+
+## Plugin tests + consumer pytest collision
+
+Consumer projects often have their own `tests/` directory. If your plugin
+also has tests (e.g. `tools/my_agent_plugin/tests/`), pytest's testpaths
+walk can find both and fail with `ModuleNotFoundError` when the same
+package name lives in two locations.
+
+Two recommended patterns:
+
+### Pattern A — plugin tests inside the plugin package
+
+Plugin author owns this:
+
+```
+my_agent_plugin/
+├── __init__.py
+├── core.py
+└── tests/
+    ├── __init__.py
+    └── test_core.py
+```
+
+In `my_agent_plugin/pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["my_agent_plugin/tests"]
+```
+
+This scopes pytest collection to your plugin's tests when running locally.
+
+### Pattern B — consumer ignores your plugin in their pytest config
+
+Consumer owns this:
+
+```toml
+# In the consumer project's pytest.ini or pyproject.toml:
+[tool.pytest.ini_options]
+addopts = ["--ignore=tools/my_agent_plugin"]
+```
+
+Both work. Pattern A is preferable for plugin authors (no consumer
+configuration needed); Pattern B is for cases where the consumer integrates
+a plugin they don't own.

cli_agent_runner-0.1.8/tests/_test_helpers.py

@@ -0,0 +1,44 @@
+"""Shared test helpers.
+
+Centralises the snapshot+clear+restore fixture pattern used by every test
+file that interacts with a plugin-extension registry (hooks, detectors,
+event kinds, owned paths). Before: 8 near-identical autouse fixtures across
+the test suite. After: one factory.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+
+def isolating(*registries: list[Any] | dict[Any, Any]) -> Any:
+    """Return an autouse fixture that snapshots, clears, and restores registries.
+
+    Usage in a test module:
+
+        from tests._test_helpers import isolating
+        from agent_runner import monitor
+
+        _reset = isolating(monitor._PLUGIN_DETECTORS)
+
+    Multiple registries can be passed; all are isolated around each test.
+    Supports list and dict registries.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _reset():
+        saved: list[Any] = []
+        for reg in registries:
+            saved.append(reg.copy() if isinstance(reg, dict) else list(reg))
+            reg.clear()
+        yield
+        for reg, snap in zip(registries, saved, strict=True):
+            reg.clear()
+            if isinstance(reg, dict):
+                reg.update(snap)
+            else:
+                reg.extend(snap)
+
+    return _reset

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/tests/contract/test_public_api_surface.py

@@ -80,6 +80,11 @@ EXPECTED_DETECTOR_HELPERS_API = {
     "phase_filter",
 }
 
+EXPECTED_VCS_STATE_API = {
+    "register_plugin_owned_paths",
+    "plugin_owned_paths",
+}
+
 # Doomed symbols (removed in 0.1.7) — verify ABSENCE so a future revert can't
 # silently restore them and re-couple core to Claude.
 FORBIDDEN_AGENT_RUNTIME = {
@@ -128,3 +133,15 @@ def test_given_agent_runtime_when_imported_then_claude_specific_symbols_absent()
         f"agent_runner.agent_runtime: forbidden Claude-specific symbols present: {present}. "
         f"These were intentionally removed in 0.1.7 — env injection lives in AgentConfig.env."
     )
+
+
+def test_given_vcs_state_module_when_imported_then_plugin_owned_paths_api_present() -> None:
+    """0.1.8: register_plugin_owned_paths + plugin_owned_paths are the new
+    plugin-author public surface. Lock them in so a future refactor can't
+    silently rename or remove them."""
+    actual = _public_names("agent_runner.vcs_state")
+    missing = EXPECTED_VCS_STATE_API - actual
+    assert not missing, (
+        f"agent_runner.vcs_state: missing public names {missing}. "
+        f"Plugin authors registered against the 0.1.8 names — do not remove without major bump."
+    )

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/tests/integration/test_context_enricher_namespacing.py

@@ -4,19 +4,11 @@ from __future__ import annotations
 
 from pathlib import Path
 
-import pytest
-
 from agent_runner import hooks
 from agent_runner.runner import _stitch_enricher_slices
+from tests._test_helpers import isolating
 
-
-@pytest.fixture(autouse=True)
-def _reset_enrichers():
-    saved = list(hooks._CONTEXT_ENRICHERS)
-    hooks._CONTEXT_ENRICHERS.clear()
-    yield
-    hooks._CONTEXT_ENRICHERS.clear()
-    hooks._CONTEXT_ENRICHERS.extend(saved)
+_reset = isolating(hooks._CONTEXT_ENRICHERS)
 
 
 class _Branch:

{cli_agent_runner-0.1.7 → cli_agent_runner-0.1.8}/tests/integration/test_plugin_detector_loaded.py

@@ -4,19 +4,11 @@ from __future__ import annotations
 
 from pathlib import Path
 
-import pytest
-
 from agent_runner import monitor
 from agent_runner.api_types import Alert
+from tests._test_helpers import isolating
 
-
-@pytest.fixture(autouse=True)
-def _reset_plugin_detectors():
-    saved = list(monitor._PLUGIN_DETECTORS)
-    monitor._PLUGIN_DETECTORS.clear()
-    yield
-    monitor._PLUGIN_DETECTORS.clear()
-    monitor._PLUGIN_DETECTORS.extend(saved)
+_reset = isolating(monitor._PLUGIN_DETECTORS)
 
 
 class _AlwaysFiresDetector:

cli_agent_runner-0.1.8/tests/integration/test_plugin_owned_paths.py

@@ -0,0 +1,88 @@
+"""End-to-end: plugin-owned paths are filtered out of detect_dirty_files."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from agent_runner.vcs_state import _PLUGIN_OWNED_PATHS
+from tests._test_helpers import isolating
+
+_reset = isolating(_PLUGIN_OWNED_PATHS)
+
+
+def _commit(repo: Path, msg: str) -> None:
+    subprocess.run(
+        [
+            "git",
+            "-c",
+            "commit.gpgsign=false",
+            "commit",
+            "-q",
+            "-m",
+            msg,
+        ],
+        cwd=repo,
+        check=True,
+    )
+
+
+def _intent_to_add(repo: Path) -> None:
+    """Mark all untracked files with ``git add -N`` so ``status --porcelain``
+    lists them individually (rather than collapsing into the parent dir).
+
+    Real-world plugins write files into already-tracked directories, so
+    per-file porcelain entries are the production reality. This helper
+    reproduces that shape from a fresh tmp_git_repo.
+    """
+    subprocess.run(["git", "add", "-N", "."], cwd=repo, check=True)
+
+
+def test_given_no_registration_when_dirty_files_then_all_returned(
+    tmp_git_repo: Path,
+) -> None:
+    """Baseline: with no registration, today's behavior is preserved."""
+    from agent_runner.vcs_state import detect_dirty_files
+
+    (tmp_git_repo / "proposals").mkdir()
+    (tmp_git_repo / "proposals" / "report.md").write_text("hello\n")
+    (tmp_git_repo / "other.txt").write_text("x\n")
+    _intent_to_add(tmp_git_repo)
+
+    dirty = detect_dirty_files(tmp_git_repo)
+    assert "other.txt" in dirty
+    assert "proposals/report.md" in dirty
+
+
+def test_given_proposals_registered_when_dirty_files_then_proposals_filtered(
+    tmp_git_repo: Path,
+) -> None:
+    """Plugin-owned 'proposals/' files are excluded from dirty list."""
+    from agent_runner.vcs_state import detect_dirty_files, register_plugin_owned_paths
+
+    register_plugin_owned_paths(["proposals/"])
+    (tmp_git_repo / "proposals").mkdir()
+    (tmp_git_repo / "proposals" / "report.md").write_text("hello\n")
+    (tmp_git_repo / "other.txt").write_text("x\n")
+    _intent_to_add(tmp_git_repo)
+
+    dirty = detect_dirty_files(tmp_git_repo)
+    assert "other.txt" in dirty
+    assert "proposals/report.md" not in dirty
+
+
+def test_given_recursive_glob_registered_when_dirty_files_then_deep_paths_filtered(
+    tmp_git_repo: Path,
+) -> None:
+    """Recursive ``**`` glob excludes nested paths too."""
+    from agent_runner.vcs_state import detect_dirty_files, register_plugin_owned_paths
+
+    register_plugin_owned_paths(["logs/plugins/**/*"])
+    (tmp_git_repo / "logs" / "plugins" / "argus").mkdir(parents=True)
+    (tmp_git_repo / "logs" / "plugins" / "argus" / "state.json").write_text("{}\n")
+    (tmp_git_repo / "logs" / "other.log").write_text("x\n")
+    _intent_to_add(tmp_git_repo)
+
+    dirty = detect_dirty_files(tmp_git_repo)
+    assert "logs/plugins/argus/state.json" not in dirty
+    assert "logs/other.log" in dirty

cli_agent_runner-0.1.8/tests/invariants/test_module_sizes.py

@@ -0,0 +1,22 @@
+"""Single ceiling on production module sizes.
+
+Catches the actual signal worth catching — "this file got long enough that
+a split is overdue" — without the per-release ratchet-bumping bookkeeping
+the old parameterised version generated.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent.parent.parent / "agent_runner"
+LIMIT = 1000
+
+
+def test_given_production_module_when_counted_then_under_thousand_lines() -> None:
+    offenders: list[tuple[str, int]] = []
+    for path in PKG.rglob("*.py"):
+        n = sum(1 for _ in path.read_text(encoding="utf-8").splitlines())
+        if n > LIMIT:
+            offenders.append((str(path.relative_to(PKG)), n))
+    assert offenders == [], f"modules exceed {LIMIT} LOC; split overdue: {offenders}"