cli-agent-runner 0.3.10__tar.gz → 0.3.11__tar.gz

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/.vulture-whitelist.py

@@ -240,6 +240,9 @@ warning_consecutive_samples
 # agent_runner.config.models._HostHealthDiskConfig
 warning_pct
 critical_pct
+growth_window_s
+disk_growth_pct_per_hr_warning
+inode_growth_pct_per_hr_warning
 
 # agent_runner.config.models._HostHealthMemoryConfig
 avail_min_mb

cli_agent_runner-0.3.11/BACKLOG.md

@@ -0,0 +1,195 @@
+# Backlog
+
+Known follow-ups and candidate work — real design or behavior decisions, not
+defects. Each entry carries enough context to act on without re-deriving it.
+
+Items marked **NEEDS_DESIGN** change user-visible behavior and are held for an
+explicit decision — they are not shipped silently in a maintenance release.
+
+**Ordered by priority** (highest first). The number is a rank, not a stable id.
+Priority follows the sharpest differentiator: prove and deepen host-health /
+cooperative pre-OOM supervision on constrained hosts first (items 1–2); the
+cognitive / goal-adherence layer (item 3) builds on that same control loop;
+cross-CLI resume breadth and reach are lower.
+
+## 1. Prove cooperative pre-OOM drain end-to-end on a constrained cgroup — NEEDS_DESIGN
+
+The host-health mechanisms built across the 0.3.x line — the cgroup
+memory-growth-rate detector (0.3.1), the `memory.high` soft-brake (0.3.7), and
+the typed `cooperative_stop` signal (0.3.9) — have never been demonstrated
+*together*, end-to-end, under real memory pressure on a small (~462 MB) cgroup.
+The load-bearing property is: the agent is cooperatively drained **before** the
+kernel OOM killer fires. It is provable with a synthetic memory-growing child
+under a constrained cgroup — no live model needed. Build that harness, verify
+the full detect → brake → drain loop, and pin the small-host calibration
+(swap-floor + PSI thresholds) and reap-safety (PID-reuse, orphan reap) as a
+durable, tested execution guarantee. Making this claim demonstrable is the
+highest-value work on the list; everything below is secondary to it.
+
+## 2. Runaway session-footprint host-health signal — NEEDS_DESIGN
+
+A resumed CLI session file (e.g. pi's session `.jsonl`) grows unbounded across
+rounds — a disk / inode pressure surface only the supervisor can see, and one
+that cross-round resume (0.3.10) amplifies. Add a host disk/inode pressure
+detector as a leading indicator so the pre-OOM brake can fire earlier and more
+specifically. Frame it as a *host* signal (any growing per-agent footprint),
+not a single-CLI feature.
+
+## 3. Cognitive / goal-adherence supervision loop (observe → assess → steer → persist) — NEEDS_DESIGN
+
+Today the supervisor watches *resource* health (memory / host) and *mechanical*
+progress (no-usage, substrate fingerprint, repetitive-tool). It cannot tell when
+an agent is "on a treadmill" — busy (produces output, edits files, exits 0) but
+not actually advancing toward its goal. Add a second, **advisory** layer to the
+same round-loop: a plugin observes each round, assesses progress toward a
+declared goal, and — only when warranted — injects a short, grounded advisory
+into the *next* round's context (through the existing `inject_context` path) that
+the agent may heed or dismiss.
+
+Design spine (composes as a fold over the durable event bus + `inject_context`,
+**not** a new live callback — the round is a fresh subprocess, so cross-round
+state is file/event-based; this re-adds a feedback seam an earlier release
+removed for lack of a producer, but strictly narrower: a data-return / fold, not
+arbitrary context mutation):
+
+- A first-class `[goal]` config (the "goal command"). PRIMARY verification is
+  **objective**: operator-declared `goal.checks` (a command the supervisor runs
+  each round — exit 0 = satisfied, an optional numeric target) and milestones,
+  run through the reap-safe / timeout / killpg machinery so a check can never
+  orphan or blow the cgroup. An optional, objective-gated LLM assessor is a last
+  resort, never in the base install.
+- A zero-cost default assessor: an objective **"treadmill signature"**
+  (activity-high + net-convergence-low, from signals already emitted; requires
+  persistence over K rounds + affirmative evidence, so false positives stay near
+  zero).
+- **Hard invariant — the advisory / kill firewall:** the advisory path is
+  strictly separate from the give-up / kill decision. A possibly-wrong assessor
+  can steer but can NEVER influence a kill (a distinct event kind the kill path
+  never reads, plus an import firewall; the assessment type structurally has no
+  kill field). Killing stays on the conservative mechanical path.
+- Steering is advisory only: a fixed schema that cannot express a command
+  (grounded observation + a question + confidence + a respected one-line
+  dismissal), edge-triggered, one concern at a time, dismiss-and-respect so it
+  never nags.
+- CLI-agnostic: reads the agent's merged log + the goal; works around any CLI.
+- Persistence rides a supervisor-owned, bounded, append-only lessons ledger
+  re-injected each round (subordinate to the disk host-health signal in item 2).
+  The supervisor never edits the agent's own memory files — it may *suggest* the
+  agent record a lesson.
+
+Sequence this after items 1–2: it is a second consumer of the same
+observe → assess → act control loop (mechanical actuator kills, advisory
+actuator steers), and it earns its slot only once the resource edge is proven.
+
+## 4. SECURITY containment guidance
+
+agent-runner is lifecycle-safety + observability, not containment — a
+deliberate boundary that is currently undocumented, so it reads as a gap. Add a
+SECURITY section that states the division plainly and gives the operator
+concrete containment guidance: a dedicated unprivileged user, a container/VM via
+`exec_prefix`, egress limits, no passwordless sudo, read-only mounts. Docs-only.
+
+## 5. claude cross-round resume — NEEDS_DESIGN
+
+0.3.10 shipped resume for pi only (its `--session-id` is idempotent —
+create-or-resume). claude's `--session-id` is create-only and `--resume` is a
+separate flag, so it needs a create-vs-resume state machine gated on the prior
+round's outcome (a crashed round re-creates rather than `--resume`-errors), plus
+an empirical check that `claude -p --resume <id>` with the prompt on stdin
+actually resumes **and** runs the new turn (rather than silently no-opping).
+Keep it a thin per-CLI declaration; if it forces heavy session-state ownership,
+that is the signal it belongs at the CLI layer, not here.
+
+## 6. Surface resume in the preflight (doctor / peek) — NEEDS_DESIGN
+
+resume is the one manifest-declared capability not shown by `doctor` / `peek`
+(unlike `cooperative_stop` and the SIGTERM grace). An operator on a
+resume-capable preset has no preflight way to confirm resume will engage for
+their phase config — in particular the deliberate cold-start on an ambiguous
+phase is silent until they notice no `session_resumed` events. Add a preflight
+line (with a "resume will not engage — ambiguous phase" note). Requires a `peek`
+schema bump.
+
+## 7. Resume for gemini / codex / kimi — NEEDS_DESIGN
+
+Each has a different resume shape (gemini resumes by index/latest, not a chosen
+id; codex uses a subcommand plus a captured id). Extending resume means widening
+the manifest `resume_flag` into a small sum type with a per-variant injection at
+the argv-build site — never optional fields bolted onto one struct. Ship only
+the variants whose resume is verified to work end-to-end.
+
+## 8. Fleet fan-in view — NEEDS_DESIGN
+
+Aggregate several supervised hosts into one place to watch, built on the
+existing remote-relay primitives — the density story (many cheap / constrained
+boxes under one supervisor). A larger effort; sequence it after the pre-OOM edge
+(item 1) is proven, so it fans in verified hosts rather than claimed ones.
+
+## 9. Runtime & distribution: single-binary edge install (language) — longer-horizon, gated
+
+Python is the right foundation for the *plugin* surface — dynamic per-CLI
+plugins and the declared-capability manifest are a Python strength, and "cover
+every CLI via a plugin" is a core stance; a wholesale Rust/Go rewrite would
+regress exactly that. The one place another language would genuinely help is
+**distribution**: a static single binary ("copy one file, run it", no
+interpreter or install step) suits constrained / edge hosts better than a Python
+runtime plus a dependency. Footprint and speed are *not* reasons — the
+supervisor's ~24 MB RSS is negligible against a GB-scale agent, and all internal
+scheduling is already event-based (run time is model-latency-bound, not
+CPU-bound in our code).
+
+Held for an explicit decision, gated on two triggers: (a) the host-health /
+pre-OOM edge (item 1) is proven and stable — you do not rewrite a moving,
+unproven core; and (b) a distribution benchmark shows single-binary install is
+the binding constraint. Even then, try Python-native single-binary packaging
+first (a self-contained bundle) before any rewrite. If a rewrite is ever
+warranted, the realistic shape is a small, stable core of the host-health / reap
+logic in Rust or Go with the plugin layer staying Python or a declarative
+format — a hybrid whose language boundary is the hard part, not a full port.
+
+## 10. Per-CLI session-directory resolution
+
+Resolve each CLI's session directory via its own environment precedence rather
+than a hardcoded default (never assume `~/.pi` / `~/.claude` / etc.). Ties to
+the existing work_dir-resolution work.
+
+## 11. Test the resume boot-guard's per-phase branch
+
+The boot guard that rejects a static resume flag already present in a command is
+tested for the base agent but not the per-phase `[phases.<name>.agent]` override
+branch. The override loop is correct by construction but untested — one small
+test.
+
+## 12. `_tail_events` / `_tail_events_jsonl` duplication
+
+Three event-stream tailers now exist at deliberately different scopes, and they
+are not accidental copies:
+
+- `cli/events_cmd.py:_tail_events` — current-month-scoped
+  (`_current_month_events_file`), resets its offset to `0` on truncation.
+- `_monitor_state.py:_tail_events_jsonl` — globs every `events-*.jsonl`;
+  re-exported through the `monitor.py` facade. It moved out of `api.py` in the
+  0.3.0 api split (`_install`/`_lifecycle`/`_observe`).
+- `_throttle.py:_tail_events` — the newest two monthly files
+  (`glob("events-*.jsonl")[-2:]`).
+
+Collapsing them means first deciding which scope is correct for each caller — a
+structural decision, not a literal swap. (The older "character-identical
+kind-read loop in `_throttle.py` and `monitor.py`" sub-concern has evaporated:
+`monitor.py` no longer carries that loop — it moved to `_monitor_detectors.py`
+and grew its own reset-ladder logic — and `_throttle.py` iterates forward over
+the tailer generator, so the only shared text left is the single line
+`kind = ev.get("event")`.)
+
+## 13. `stash_orphan` loses the ref when the post-push listing fails
+
+`vcs_state.stash_orphan` returns `None` in three cases; two are true no-ops. The
+third — `git stash push` succeeded but the follow-up `git stash list` failed —
+means the WIP *is* stashed yet callers read "nothing stashed" and report the
+tree as ignored. It is already documented in-code as a KNOWN GAP and judged
+effectively unreachable (a listing that fails microseconds after a push that
+just succeeded in the same repo).
+
+Deferred because closing it is a naming decision, not cleanup: no event kind
+carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
+— the stash exists). Left as-is until that kind is designed.

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.3.11] - 2026-09-17
+
+### Added
+- Host disk/inode-growth WARNING detector: `[monitor.host_health.disk]` gains `disk_growth_pct_per_hr_warning`/`inode_growth_pct_per_hr_warning` (default 5.0%/hr each); a new `disk_growth` monitor alert kind (observability-only, no action taken).
+- `agent_runner.events.register_plugin_kind(name)` restores a namespaced custom-event-kind affordance for out-of-tree plugins, validated against the builtin-kind namespace.
+
+### Verified
+- Pre-OOM host-pressure terminate: small-host PSI/swap calibration pinned as always-on tests-of-record, plus a gated real-cgroup property test (`AGENT_RUNNER_E2E_PI`) run live on a ~0.5 GB host — sustained host PSI-full ≥ 60 (measured 69–77 over 3 samples) terminated and reaped the agent with the host still responsive and no cgroup OOM kill; reproduced across two clean runs.
+
+### Docs
+- `docs/migrations/0.3.md` clarifies the 0.3.9 seam-subtraction adaptation contract (fold-in via `post_round_hooks`, `event_kinds` replacement) and documents `register_plugin_kind`.
+
+No config migration required. `peek --json` schema stays `2.6`.
+
 ## [0.3.10] - 2026-09-17
 
 ### Added

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.10
+Version: 0.3.11
 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
@@ -51,7 +51,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  14 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -88,7 +88,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` — 13 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 14 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
@@ -113,10 +113,10 @@ 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: 13 detectors
+## Monitor: 14 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`disk_growth`, `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 —

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/README.md

@@ -13,7 +13,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  14 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` — 13 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 14 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
@@ -75,10 +75,10 @@ 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: 13 detectors
+## Monitor: 14 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`disk_growth`, `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 —

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/_monitor_detectors.py

@@ -1,6 +1,6 @@
 """Pure anomaly detectors over events + metrics + log tails.
 
-13 built-in detectors. Two trigger ``auto_action="stop_service"``:
+14 built-in detectors. Two trigger ``auto_action="stop_service"``:
   * oauth_fail  — agent-reported auth failures, or an auth pattern in
     short-exit logs (retrying burns API quota)
   * disk_critical — disk_used_pct > 95% (writing more risks corruption)
@@ -218,6 +218,93 @@ def detect_disk_critical(
     )
 
 
+def detect_disk_growth(
+    metrics: list[dict[str, Any]],
+    *,
+    growth_window_s: int = 1800,
+    disk_growth_pct_per_hr_warning: float = 5.0,
+    inode_growth_pct_per_hr_warning: float = 5.0,
+) -> Alert | None:
+    """WARNING when disk_used_pct and/or inode_used_pct is climbing faster than
+    its configured %/hr floor -- a generalized host-disk/inode-pressure signal
+    (pi's cross-round resume amplifies session-log growth; not pi-specific).
+
+    Rate is Δpct over the OLDEST metrics sample landing within
+    ``growth_window_s`` of the LATEST sample's ``ts`` (``agent_runner``'s
+    ``parse_iso_ms``), divided by the elapsed hours between them -- real
+    metrics land at variable wall-clock gaps, so a fixed-interval
+    ``(cur - prev)`` delta would misjudge the rate whenever polls drift.
+    Fewer than two samples inside the window (a cold start, or every prior
+    sample already aged out) returns ``None`` -- no baseline, no rate.
+
+    Observability only BY DESIGN, mirroring
+    :func:`host_health.cgroup_growth_rate_pressure`: unlike
+    :func:`detect_disk_critical`, this NEVER sets ``auto_action`` -- a
+    growth-rate signal is for an operator/plugin to act on, not a kill
+    trigger. Carries BOTH the disk and inode rate dims on one alert (not two
+    separate alert kinds) even when only one crosses its floor, so a reader
+    always sees the other dimension's current rate for context.
+    """
+    latest_ts_raw = _latest(metrics, "ts")
+    latest_disk = _latest(metrics, "disk_used_pct")
+    if latest_ts_raw is None or latest_disk is None:
+        return None
+    latest_ts = parse_iso_ms(latest_ts_raw)
+    latest_inode = _latest(metrics, "inode_used_pct")
+
+    baseline: dict[str, Any] | None = None
+    baseline_ts: datetime | None = None
+    for m in metrics:
+        ts_raw = m.get("ts")
+        if ts_raw is None or "disk_used_pct" not in m:
+            continue
+        ts = parse_iso_ms(ts_raw)
+        age_s = (latest_ts - ts).total_seconds()
+        if age_s < 0 or age_s > growth_window_s:
+            continue  # future-dated, or aged out of the growth window
+        # metrics is chronologically ascending, so the first in-window sample
+        # is the oldest -- the widest baseline; no later sample can be older.
+        baseline, baseline_ts = m, ts
+        break
+
+    if baseline is None or baseline_ts is None or baseline_ts >= latest_ts:
+        return None  # no earlier in-window sample to diff against
+    elapsed_hr = (latest_ts - baseline_ts).total_seconds() / 3600.0
+    if elapsed_hr <= 0:
+        return None
+
+    disk_rate = (latest_disk - baseline["disk_used_pct"]) / elapsed_hr
+    baseline_inode = baseline.get("inode_used_pct")
+    inode_rate = (
+        (latest_inode - baseline_inode) / elapsed_hr
+        if latest_inode is not None and baseline_inode is not None
+        else None
+    )
+
+    disk_trip = disk_rate >= disk_growth_pct_per_hr_warning
+    inode_trip = inode_rate is not None and inode_rate >= inode_growth_pct_per_hr_warning
+    if not disk_trip and not inode_trip:
+        return None
+
+    bits = []
+    if disk_trip:
+        bits.append(f"disk +{disk_rate:.1f}%/hr (>= {disk_growth_pct_per_hr_warning})")
+    if inode_trip:
+        bits.append(f"inode +{inode_rate:.1f}%/hr (>= {inode_growth_pct_per_hr_warning})")
+    return _alert(
+        "disk_growth",
+        "warning",
+        f"{' and '.join(bits)} over the last {growth_window_s}s",
+        {
+            "disk_pct_per_hr": round(disk_rate, 2),
+            "disk_threshold_pct_per_hr": disk_growth_pct_per_hr_warning,
+            "inode_pct_per_hr": round(inode_rate, 2) if inode_rate is not None else None,
+            "inode_threshold_pct_per_hr": inode_growth_pct_per_hr_warning,
+            "window_s": growth_window_s,
+        },
+    )
+
+
 def _latest_two(metrics: list[dict[str, Any]]) -> tuple[dict[str, Any], dict[str, Any]]:
     """Return (current, previous) full metric dicts -- the last two history
     entries (or ``{}`` when shorter). The mem-pressure ladder needs a delta

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/_monitor_registry.py

@@ -26,6 +26,7 @@ KNOWN_ALERT_KINDS: frozenset[str] = frozenset(
         "orphan_chain",
         "disk_warning",
         "disk_critical",
+        "disk_growth",
         "mem_pressure",
         "mem_signal_unavailable",
         "mem_pressure_gate_inert",

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.10'
-__version_tuple__ = version_tuple = (0, 3, 10)
+__version__ = version = '0.3.11'
+__version_tuple__ = version_tuple = (0, 3, 11)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/config/models.py

@@ -204,6 +204,13 @@ class PluginsConfig:
 class _HostHealthDiskConfig:
     warning_pct: float = 90.0  # disk_warning fires when disk_used_pct >= this
     critical_pct: float = 95.0  # disk_critical fires when disk_used_pct >= this
+    # disk_growth: observability-only WARNING when disk_used_pct/inode_used_pct
+    # climbs faster than a %/hr floor, measured over the oldest metrics sample
+    # landing within this many seconds of the latest one -- never a kill (see
+    # detect_disk_growth).
+    growth_window_s: int = 1800
+    disk_growth_pct_per_hr_warning: float = 5.0
+    inode_growth_pct_per_hr_warning: float = 5.0
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/config/parsers.py

@@ -517,6 +517,18 @@ def _parse_monitor(monitor_d: dict) -> MonitorConfig:
             critical_pct=_require_pct(
                 disk_d.get("critical_pct", 95.0), field="monitor.host_health.disk.critical_pct"
             ),
+            growth_window_s=_require_positive_int(
+                disk_d.get("growth_window_s", 1800),
+                field="monitor.host_health.disk.growth_window_s",
+            ),
+            disk_growth_pct_per_hr_warning=_require_positive_float(
+                disk_d.get("disk_growth_pct_per_hr_warning", 5.0),
+                field="monitor.host_health.disk.disk_growth_pct_per_hr_warning",
+            ),
+            inode_growth_pct_per_hr_warning=_require_positive_float(
+                disk_d.get("inode_growth_pct_per_hr_warning", 5.0),
+                field="monitor.host_health.disk.inode_growth_pct_per_hr_warning",
+            ),
         ),
         memory=_HostHealthMemoryConfig(
             avail_min_mb=_require_non_negative_int(

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/events.py

@@ -4,8 +4,11 @@
 supervisor code, collected by reflection (see ``_collect_builtin_kinds``).
 
 Public API:
-- ``KNOWN_EVENT_KINDS`` — the set of known kinds; supports ``in`` and iteration.
-  Preserved so ``from agent_runner.events import KNOWN_EVENT_KINDS`` still works.
+- ``KNOWN_EVENT_KINDS`` — the set of known kinds (builtin + plugin-registered);
+  supports ``in`` and iteration. Preserved so
+  ``from agent_runner.events import KNOWN_EVENT_KINDS`` still works.
+- ``register_plugin_kind(name)`` — an out-of-tree plugin registers a
+  namespaced custom event kind so ``emit()`` accepts it.
 - ``emit(log_dir, kind, /, **fields)`` — append a structured event line.
   ``log_dir`` and ``kind`` are positional-only so callers can pass
   ``log_dir=...`` as a payload field name without parameter shadowing.
@@ -96,6 +99,16 @@ TRANSIENT_ERROR_RECOVERED = "transient_error_recovered"
 UPGRADE_START_FAILED = "upgrade_start_failed"
 
 
+def _is_snake_case_kind(s: str) -> bool:
+    """The legal event-kind name rule: lowercase snake_case, no leading '_'.
+
+    Single source shared by _collect_builtin_kinds (filtering this module's
+    constants) and register_plugin_kind (validating plugin-supplied names) so
+    the two cannot drift if the naming rule ever changes.
+    """
+    return s.islower() and not s.startswith("_") and s.replace("_", "").isalnum()
+
+
 def _collect_builtin_kinds() -> frozenset[str]:
     """Single-source: every module-level UPPER_CASE str constant whose value
     is a snake_case kind name is a builtin event kind. Drift between the
@@ -107,39 +120,78 @@ def _collect_builtin_kinds() -> frozenset[str]:
     return frozenset(
         v
         for k, v in vars(mod).items()
-        if k.isupper()
-        and isinstance(v, str)
-        and v.islower()
-        and not v.startswith("_")
-        and v.replace("_", "").isalnum()
+        if k.isupper() and isinstance(v, str) and _is_snake_case_kind(v)
     )
 
 
 _BUILTIN_KINDS: frozenset[str] = _collect_builtin_kinds()
 
+# Runtime-registered plugin event kinds (out-of-tree producers). Unlike
+# _BUILTIN_KINDS this is mutable and populated at import/registration time by
+# plugin code via register_plugin_kind(), not by reflection over this module.
+_PLUGIN_KINDS: set[str] = set()
+
 
 def _is_known(name: str) -> bool:
-    return name in _BUILTIN_KINDS
+    return name in _BUILTIN_KINDS or name in _PLUGIN_KINDS
+
+
+def register_plugin_kind(name: str) -> None:
+    """Register a namespaced custom event kind for an out-of-tree plugin.
+
+    Restores a minimal affordance a prior release's subtraction of the
+    ``event_kinds`` manifest field removed: a plugin installed on a target
+    host still needs a validated way to emit its own event kinds through the
+    same ``emit()``/events-*.jsonl stream core uses, rather than
+    hand-appending JSON lines (unvalidated, and liable to collide with a
+    builtin kind).
+
+    ``name`` must be lowercase snake_case, contain at least one ``_`` (so it
+    is namespaced — e.g. ``myplugin_ok``), and its first underscore-segment
+    must not be a prefix any builtin kind uses (derived programmatically from
+    _BUILTIN_KINDS, not hand-maintained — e.g. ``round_myplugin`` collides
+    with the ``round_*`` builtin namespace even though ``round_myplugin``
+    itself isn't a builtin kind). Raises ValueError on any violation.
+    """
+    if not isinstance(name, str) or not name or not _is_snake_case_kind(name):
+        raise ValueError(f"invalid plugin event kind: {name!r}")
+    if "_" not in name:
+        raise ValueError(f"plugin event kind must be namespaced (contain '_'): {name!r}")
+    # An exact builtin collision is also caught by the prefix check below (a
+    # builtin's own first-segment is always a builtin prefix), but flag it here
+    # for a clearer, more specific error message.
+    if name in _BUILTIN_KINDS:
+        raise ValueError(f"plugin event kind collides with a builtin kind: {name!r}")
+    prefix = name.split("_", 1)[0]
+    builtin_prefixes = {k.split("_", 1)[0] for k in _BUILTIN_KINDS}
+    if prefix in builtin_prefixes:
+        raise ValueError(f"plugin event kind {name!r} uses builtin-owned prefix {prefix!r}")
+    _PLUGIN_KINDS.add(name)
 
 
 class _KnownEventKindsView:
-    """Read-only view of built-in event kinds.
+    """Read-only view of known event kinds — builtin plus plugin-registered.
 
     Backward compat for ``from agent_runner.events import KNOWN_EVENT_KINDS``.
-    Supports ``in`` and ``iter``; intentionally does NOT support mutation.
+    Supports ``in`` and ``iter``; intentionally does NOT support mutation
+    (use ``register_plugin_kind()`` to add a plugin kind).
     """
 
     def __contains__(self, item: object) -> bool:
         return isinstance(item, str) and _is_known(item)
 
     def __iter__(self) -> Iterator[str]:
-        yield from sorted(_BUILTIN_KINDS)
+        yield from sorted(_BUILTIN_KINDS | _PLUGIN_KINDS)
 
     def __len__(self) -> int:
-        return len(_BUILTIN_KINDS)
+        return len(_BUILTIN_KINDS | _PLUGIN_KINDS)
 
     def __repr__(self) -> str:
-        return f"<KNOWN_EVENT_KINDS: {len(_BUILTIN_KINDS)} built-in>"
+        total = len(_BUILTIN_KINDS | _PLUGIN_KINDS)
+        return (
+            f"<KNOWN_EVENT_KINDS: {total} known "
+            f"({len(_BUILTIN_KINDS)} built-in, {len(_PLUGIN_KINDS)} plugin)>"
+        )
 
 
 KNOWN_EVENT_KINDS = _KnownEventKindsView()

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/metrics.py

@@ -80,6 +80,10 @@ def sample() -> dict[str, Any]:
 def collect(disk_path: Path, *, agent_binary: str | None = None) -> dict[str, Any]:
     vm = psutil.virtual_memory()
     du = psutil.disk_usage(str(disk_path))
+    st = os.statvfs(str(disk_path))
+    # f_files==0 means the filesystem does not track inode counts at all (some
+    # network/overlay filesystems) -- None signals "no signal", not "0% used".
+    inode_used_pct = round(100 * (1 - st.f_ffree / st.f_files), 1) if st.f_files else None
     out: dict[str, Any] = {
         "mem_total_mb": vm.total // (1024 * 1024),
         "mem_used_pct": round(vm.percent, 1),
@@ -87,6 +91,7 @@ def collect(disk_path: Path, *, agent_binary: str | None = None) -> dict[str, An
         "disk_total_gb": round(du.total / (1024**3), 1),
         "disk_free_gb": round(du.free / (1024**3), 1),
         "disk_used_pct": round(du.percent, 1),
+        "inode_used_pct": inode_used_pct,
     }
     try:
         load = os.getloadavg()

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.11}/agent_runner/monitor.py

@@ -1,6 +1,6 @@
 """Monitor — the cycle-edge: running detectors and dispatching on their alerts.
 
-13 built-in detectors run every poll (see ``_monitor_detectors``); two trigger
+14 built-in detectors run every poll (see ``_monitor_detectors``); two trigger
 ``auto_action="stop_service"``:
   * oauth_fail  — agent-reported auth failures, or an auth pattern in
     short-exit logs (retrying burns API quota)
@@ -36,6 +36,7 @@ from typing import Any, Literal
 from agent_runner._monitor_detectors import (
     detect_anomaly_repetitive_active,
     detect_disk_critical,
+    detect_disk_growth,
     detect_disk_warning,
     detect_hung,
     detect_mem_pressure,
@@ -102,7 +103,7 @@ def run_all_detectors(
     host_health_cfg: MonitorHostHealthConfig = _DEFAULT_HOST_HEALTH_CFG,
     log_dir: Path | None = None,
 ) -> list[Alert]:
-    """Run all 13 detectors; returns alerts (empty = healthy).
+    """Run all 14 detectors; returns alerts (empty = healthy).
 
     Each detector is isolated via ``_run_detector``: a crash in one emits
     ``detector_error`` (when ``log_dir`` is given) and does not stop the rest.
@@ -138,6 +139,15 @@ def run_all_detectors(
             "disk_critical",
             lambda: detect_disk_critical(metrics, threshold_pct=host_health_cfg.disk.critical_pct),
         ),
+        (
+            "disk_growth",
+            lambda: detect_disk_growth(
+                metrics,
+                growth_window_s=host_health_cfg.disk.growth_window_s,
+                disk_growth_pct_per_hr_warning=host_health_cfg.disk.disk_growth_pct_per_hr_warning,
+                inode_growth_pct_per_hr_warning=host_health_cfg.disk.inode_growth_pct_per_hr_warning,
+            ),
+        ),
         ("mem_pressure", lambda: detect_mem_pressure(metrics, cfg=host_health_cfg)),
         (
             "mem_pressure_gate_inert",