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

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

@@ -6,6 +6,12 @@
 # bare name below marks one field "used". SSOT = the @dataclass definitions in
 # agent_runner/; a new field is covered by regenerating, never by editing here.
 
+# agent_runner._bounded.BoundedResult
+rc
+stdout
+stderr
+timed_out
+
 # agent_runner._monitor_state.LocalSource
 log_dir
 
@@ -161,6 +167,11 @@ monitor
 phases
 plugins
 schedule
+goal
+
+# agent_runner.config.models.GoalConfig
+ledger
+checks
 
 # agent_runner.config.models.MonitorConfig
 auth_fail_patterns
@@ -232,6 +243,12 @@ pause_windows
 stash_idempotency_s
 dirty_action
 
+# agent_runner.config.models._GoalCheckConfig
+name
+cmd
+cwd
+timeout_s
+
 # agent_runner.config.models._HostHealthBrakeConfig
 memory_high
 memory_high_step_pct
@@ -240,6 +257,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
@@ -278,6 +298,11 @@ codifies
 guarded_by
 current_state
 
+# agent_runner.goal.Advisory
+observation
+question
+confidence
+
 # agent_runner.hooks.HookContext
 work_dir
 log_dir

cli_agent_runner-0.3.12/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.12}/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.12] - 2026-09-18
+
+### Added
+- `[goal]` config table: a markdown lessons `ledger` (listed in `[prompt] files` at index >= 1, and — since it must survive the round's own `git stash` — required to sit under `log_dir` or outside `work_dir`) plus `[[goal.checks]]` (`name`, `cmd` argv, optional `timeout_s`) — objective, CLI-agnostic checks the round child runs after each round's agent exits, each emitting a `goal_check` event (`satisfied` bool, optional `value`).
+- Treadmill assessor (advisory-only): across the last 3 completed rounds, if every round showed activity but at least one goal check stayed unsatisfied with an unchanged signature, serve writes one edge-triggered advisory to the ledger and emits a `goal_assessment` event (never on convergence). The ledger's `[prompt] files` membership carries it into the next round's prompt.
+- Advisory/kill firewall: the goal loop never CAUSES a kill or give-up — the kill/give-up path reads events by kind and stays blind to `goal_check`/`goal_assessment`. A goal check's own wall time does count toward the round's duration, so a long check can DELAY (never trigger) the fast-spin `stalled_no_progress`/`crash_loop` breakers; config load warns if the total check budget reaches that window.
+
+Check timeouts fold into the round's own timeout budget. No config migration required (v0.3.11 silently ignores an unrecognized `[goal]` table). `peek --json` schema stays `2.6`.
+
+## [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.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.10
+Version: 0.3.12
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme
@@ -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.12}/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.12/agent_runner/_bounded.py

@@ -0,0 +1,135 @@
+"""Sanctioned timeout-bounded subprocess primitive.
+
+Runs a command in its OWN session under a wall-clock timeout, escalating
+TERM -> grace -> killpg(SIGKILL) on breach so a hung process leaves no
+descendants (a backgrounded grandchild included, since killpg targets the
+whole process group). Returns a ``BoundedResult`` with ``timed_out=True`` on
+breach instead of raising -- the caller decides how to react. No ``clock``
+parameter: ``subprocess.communicate(timeout=)`` self-times, there is no raw
+wall-clock read here to abstract.
+
+Two hardening properties beyond the plain TERM/KILL escalation:
+
+- **Bounded even against a session-detached pipe holder.** A descendant that
+  ``setsid``-detaches out of the killed process group can still hold the
+  inherited stdout/stderr pipe open, so the final drain after ``killpg`` would
+  block forever waiting on EOF. Every drain is capped at ``_KILL_GRACE_S``; on
+  breach the read ends are closed and whatever was captured so far is returned.
+  The whole primitive therefore returns within ``timeout_s + 2*_KILL_GRACE_S``
+  (one grace for TERM->KILL, one for the post-kill drain) no matter what the
+  command spawns. A truly detached grandchild in its OWN session is NOT reaped
+  -- killpg cannot reach it; keep checks in a single process group.
+- **Reap-on-interrupt.** A SIGTERM to the supervisor (see
+  ``cli.common.install_term_handler``, which raises ``KeyboardInterrupt``)
+  propagates out of ``communicate()`` while the command runs in its own
+  session and would otherwise never be signalled. Any ``BaseException`` out of
+  a wait therefore SIGKILLs the whole group, closes the pipes, and reaps under
+  one bounded ``_KILL_GRACE_S`` wait before re-raising, mirroring
+  ``agent_runtime._kill_pgroup``'s bounded-wait-after-SIGKILL.
+
+Kept out of the startup import graph on purpose (see
+tests/invariants/test_import_footprint.py): callers import it function-scope.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess  # noqa: TID251 — agent_runner._bounded is the sanctioned timeout-bounded subprocess primitive
+from dataclasses import dataclass
+from pathlib import Path
+
+_KILL_GRACE_S = 3  # grace between TERM and killpg(SIGKILL), and for the post-kill drain
+
+
+@dataclass(frozen=True)
+class BoundedResult:
+    rc: int
+    stdout: str
+    stderr: str
+    timed_out: bool
+
+
+def _kill_group(proc: subprocess.Popen) -> None:
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+def _close_pipes(proc: subprocess.Popen) -> None:
+    for pipe in (proc.stdout, proc.stderr):
+        if pipe is not None:
+            try:
+                pipe.close()
+            except OSError:
+                pass
+
+
+def _drain_after_kill(proc: subprocess.Popen, exc: subprocess.TimeoutExpired) -> tuple[str, str]:
+    """Best-effort drain after ``killpg(SIGKILL)`` that never blocks unbounded.
+
+    A ``setsid``-detached descendant can still hold the stdout/stderr pipe open,
+    so stop waiting on it: close the read ends and reap the (already-SIGKILLed)
+    immediate child under one more ``_KILL_GRACE_S`` cap. ``TimeoutExpired.output``
+    is ``bytes`` even on this text-mode Popen (the partial read captured at
+    timeout bypasses the text-decoding wrapper), so decode it here with the
+    same ``errors="replace"`` policy; fall back to empty strings if the
+    attribute isn't bytes at all."""
+    _close_pipes(proc)
+    try:
+        proc.wait(timeout=_KILL_GRACE_S)
+    except subprocess.TimeoutExpired:
+        pass
+    out = (
+        exc.output.decode("utf-8", errors="replace")
+        if isinstance(exc.output, (bytes, bytearray))
+        else ""
+    )
+    err = (
+        exc.stderr.decode("utf-8", errors="replace")
+        if isinstance(exc.stderr, (bytes, bytearray))
+        else ""
+    )
+    return out, err
+
+
+def run_bounded(argv: list[str], *, cwd: Path, timeout_s: int) -> BoundedResult:
+    """Run argv in its own session under a wall-clock timeout, escalating
+    TERM -> grace -> killpg on breach so a hung command leaves no reachable
+    descendants. Returns timed_out=True on breach -- never raises on breach.
+    A ``BaseException`` out of a wait (e.g. a SIGTERM-driven KeyboardInterrupt)
+    SIGKILLs the group, closes the pipes, and reaps under one bounded
+    ``_KILL_GRACE_S`` wait, then re-raises, so an interrupted check is torn
+    down (not left a zombie) rather than orphaned. ``errors="replace"`` keeps a
+    non-UTF-8 byte in the command's output from raising a UnicodeDecodeError
+    past the caller's fail-open guard."""
+    proc = subprocess.Popen(
+        argv,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+        start_new_session=True,
+    )
+    try:
+        try:
+            out, err = proc.communicate(timeout=timeout_s)
+            return BoundedResult(rc=proc.returncode, stdout=out, stderr=err, timed_out=False)
+        except subprocess.TimeoutExpired:
+            proc.terminate()
+            try:
+                out, err = proc.communicate(timeout=_KILL_GRACE_S)
+            except subprocess.TimeoutExpired as exc:
+                _kill_group(proc)
+                out, err = _drain_after_kill(proc, exc)
+            return BoundedResult(rc=proc.returncode, stdout=out, stderr=err, timed_out=True)
+    except BaseException:
+        _kill_group(proc)
+        _close_pipes(proc)
+        try:
+            proc.wait(timeout=_KILL_GRACE_S)
+        except subprocess.TimeoutExpired:
+            pass
+        raise

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.12}/agent_runner/_docgen.py

@@ -21,6 +21,7 @@ from agent_runner.cli.init_cmd import _preset_names
 from agent_runner.config import (
     AgentConfig,
     Config,
+    GoalConfig,
     MonitorConfig,
     MonitorHostHealthConfig,
     PhasesConfig,
@@ -29,6 +30,7 @@ from agent_runner.config import (
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _GoalCheckConfig,
     _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
@@ -72,6 +74,7 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
     ("phases", PhasesConfig, []),
     ("plugins", PluginsConfig, []),
     ("schedule", ScheduleConfig, []),
+    ("goal", GoalConfig, [("goal.checks", _GoalCheckConfig)]),
 ]
 
 
@@ -102,13 +105,23 @@ def _field_table(dc: type) -> list[str]:
     return rows
 
 
+# Nested sub-sections that are TOML arrays-of-tables (`[[name]]`), not single
+# sub-tables (`[name]`): the parent field is a list/tuple of the sub-dataclass,
+# so the header must double-bracket or a copy-pasted single `[goal.checks]` is
+# rejected by the parser (_parse_goal expects a list).
+_ARRAY_OF_TABLES_SECTIONS = frozenset({"goal.checks"})
+
+
 def render_config_schema_table() -> str:
     """Markdown sub-sections per Config dataclass with field/type/default."""
     parts: list[str] = []
     for name, dc, nested in _SECTIONS:
         parts += [f"### `[{name}]`", "", *_field_table(dc), ""]
         for sub_name, sub_dc in nested:
-            parts += [f"#### `[{sub_name}]`", "", *_field_table(sub_dc), ""]
+            brackets = (
+                f"[[{sub_name}]]" if sub_name in _ARRAY_OF_TABLES_SECTIONS else f"[{sub_name}]"
+            )
+            parts += [f"#### `{brackets}`", "", *_field_table(sub_dc), ""]
     return "\n".join(parts).rstrip()
 
 

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.12}/agent_runner/_lifecycle.py

@@ -56,7 +56,7 @@ def outer_round_ceiling_s(cfg: Config, phase_arg: str | None) -> int:
             (cfg.profile_for(p).runtime.round_budget_s for p in (cfg.phases.list or [])),
             default=cfg.runtime.round_budget_s,
         )
-    _, outer_ceiling = timeout_budget(inner)
+    _, outer_ceiling = timeout_budget(inner, goal_checks_allowance_s=cfg.goal_checks_allowance_s)
     return outer_ceiling
 
 

{cli_agent_runner-0.3.10 → cli_agent_runner-0.3.12}/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.12}/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",