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

cli_agent_runner-0.3.13/.ralph/items.json

@@ -0,0 +1,86 @@
+{
+  "version": 1,
+  "runtime_contract": {
+    "source_docs": [],
+    "verification_gates": [
+      {
+        "name": "ruff",
+        "command": ".venv/bin/ruff check . && .venv/bin/ruff format --check ."
+      }
+    ],
+    "require_progress_append": true,
+    "require_one_item_per_iteration": true,
+    "require_commit": true
+  },
+  "items": [
+    {
+      "category": "functional",
+      "description": "metrics.sample() always includes psi_full_total, io_psi_some_avg10, and io_psi_full_avg10 (None when unread). _read_psi returns (some_avg10, full_avg10, full_total). host_health.memory_pressure verdict and context stay identical when those extra keys are injected.",
+      "steps": [
+        "Add or update tests in tests/unit/test_metrics.py for the triple return and the three sample keys.",
+        "Add tests/unit/test_host_health.py coverage that a PSI-healthy sample plus huge io_psi_* / psi_full_total yields the same Pressure as the sample without those keys.",
+        "Implement parsing of full-line total= and a second _read_psi call on /proc/pressure/io inside sample(); do not edit host_health.py.",
+        "Run .venv/bin/python -m pytest tests/unit/test_metrics.py tests/unit/test_host_health.py tests/unit/test_monitor_detectors.py -q and the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "76 passed (test_metrics + test_host_health + test_monitor_detectors); ruff check+format clean. host_health.py untouched. Darwin sample keys present as None."
+    },
+    {
+      "category": "functional",
+      "description": "host_cgroup_memory_limit events carry defer as a bool equal to _probe_and_emit_cgroup_defer's return value (True when both caps are finite and plausible, including MemorySwapMax=0).",
+      "steps": [
+        "Add tests/unit/test_cgroup_probe.py cases: memory_swap_max=0 with finite memory_max under host RAM returns True and emits defer true; memory_swap_max missing returns False and emits defer false.",
+        "Add defer: bool to emit_host_cgroup_memory_limit and pass the already-computed defer flag from _probe_and_emit_cgroup_defer.",
+        "Point the existing tests/e2e/test_e2e_pre_oom.py diagnostic at host_cgroup_memory_limit.defer.",
+        "Run .venv/bin/python -m pytest tests/unit/test_cgroup_probe.py -q and the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "55 passed (test_cgroup_probe); ruff check+format clean. MemorySwapMax=0 emits defer true; missing swap.max emits defer false. D-2 diagnostic names host_cgroup_memory_limit.defer."
+    },
+    {
+      "category": "functional",
+      "description": "round_cgroup_memory may carry optional flat io_psi_some_avg10, io_psi_full_avg10, and psi_full_total from metrics.sample() at emit time. They are omitted when unread. They are never copied into Pressure.context.",
+      "steps": [
+        "Extend tests/unit/test_serve_round_cgroup_spine.py to monkeypatch metrics.sample and assert the three fields on the emitted round_cgroup_memory event.",
+        "Thread optional kwargs through emit_round_cgroup_memory and _emit_round_cgroup_memory; call sample() once at emit.",
+        "Run .venv/bin/python -m pytest tests/unit/test_serve_round_cgroup_spine.py tests/unit/test_serve_round_oom_killed.py -q and the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "19 passed (test_serve_round_cgroup_spine + test_serve_round_oom_killed); ruff check+format clean. Optional PSI fields omitted when unread/None; present when sample() read them. Not copied into Pressure.context."
+    },
+    {
+      "category": "functional",
+      "description": "The paced pre-OOM child lives in tests/e2e/growth_child.py (8 MiB every 2.5s, page-touch). pi_growth_script installs that file instead of an inlined string. Importing the module does not start the infinite loop.",
+      "steps": [
+        "Create tests/e2e/growth_child.py with the existing constants and main() behind if __name__.",
+        "Add a constants test that imports the module and asserts _CHUNK_BYTES and _PACE_S.",
+        "Change tests/e2e/conftest.py pi_growth_script to ship that file.",
+        "Run the constants test plus the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "1 passed (test_growth_child_constants); ruff check+format clean. pi_growth_script ships tests/e2e/growth_child.py via base64; import does not start the loop."
+    },
+    {
+      "category": "functional",
+      "description": "A skip-closed control-arm e2e exists: same unit as treatment except MemorySwapMax=0, MemoryHigh=120M kept, no oom.group and no OOMPolicy=kill. Unset AGENT_RUNNER_E2E_CGROUP and AGENT_RUNNER_E2E_PI, the new test skips. Assertions in source require defer true, no round_mem_terminated, no memory_high_engaged, events_oom_kill_delta>=1 or INVALID, DEFER-FIRST or KERNEL-FIRST named, growth child gone, host still answers.",
+      "steps": [
+        "Factor the systemd unit body so swap max is a parameter. Control uses 0. Do not add OOMPolicy or memory.oom.group.",
+        "Add the control-arm test and shared assertions. Gate with existing PI flag and/or AGENT_RUNNER_E2E_CGROUP. Control wait ceiling 180s.",
+        "Without those env flags, run .venv/bin/python -m pytest tests/e2e/test_e2e_pre_oom.py -q and confirm skip (not fail, not pass). Do not export the e2e flags. Run the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "3 skipped (test_e2e_pre_oom.py without AGENT_RUNNER_E2E_CGROUP/PI); ruff check+format clean. Control unit MemorySwapMax=0, MemoryHigh=120M kept, no oom.group/OOMPolicy. Assertions in source: defer true, no round_mem_terminated, no memory_high_engaged, events_oom_kill_delta>=1 or INVALID, DEFER-FIRST or KERNEL-FIRST named, growth child gone, host still answers."
+    },
+    {
+      "category": "functional",
+      "description": "Root SECURITY.md gains one paragraph: isolation is the operator's job (exec_prefix, dedicated user, no passwordless sudo, egress); agent-runner stays lifecycle-safety. CHANGELOG adds ## [0.3.13] - UNRELEASED. No docs/SECURITY.md. Optional results template under gitignored docs/internal/notes is allowed and must not be staged.",
+      "steps": [
+        "Edit SECURITY.md Containment or Threat model with the reframe paragraph. Keep existing recipe links.",
+        "Insert CHANGELOG ## [0.3.13] - UNRELEASED above 0.3.12. Do not claim uncapped-before-coma.",
+        "Confirm docs/SECURITY.md does not exist. Run tests/invariants/test_docs_index_complete.py tests/invariants/test_doc_claims_match_ssot.py and the ruff gate."
+      ],
+      "passes": true,
+      "regression_notes": "4 passed (test_docs_index_complete + test_doc_claims_match_ssot); ruff check+format clean. docs/SECURITY.md absent. CHANGELOG [0.3.13] UNRELEASED; no uncapped-before-coma claim. Results template gitignored, not staged."
+    }
+  ]
+}

cli_agent_runner-0.3.13/.ralph/progress.md

@@ -0,0 +1,47 @@
+## 2026-09-18 sample() IO-PSI + psi_full_total
+
+- item: metrics.sample() always includes psi_full_total, io_psi_some_avg10, and io_psi_full_avg10 (None when unread). _read_psi returns (some_avg10, full_avg10, full_total). host_health.memory_pressure verdict and context stay identical when those extra keys are injected.
+- rationale: plan prefers ladder-blindness before defer-field / e2e fixture work. First unfinished item.
+- files: agent_runner/metrics.py, tests/unit/test_metrics.py, tests/unit/test_host_health.py
+- verification: `.venv/bin/python -m pytest tests/unit/test_metrics.py tests/unit/test_host_health.py tests/unit/test_monitor_detectors.py -q` → 76 passed; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean
+- notes: did not edit host_health.py or _NEW_MEM_SAMPLE_KEYS. Pre-existing pi-lens findings in cgroup_delegated / _brake_high_value left untouched (outside this item).
+
+## 2026-09-18 host_cgroup_memory_limit.defer bool
+
+- item: host_cgroup_memory_limit events carry defer as a bool equal to _probe_and_emit_cgroup_defer's return value (True when both caps are finite and plausible, including MemorySwapMax=0).
+- rationale: plan prefers locking the defer-field contract before e2e fixture work. First remaining unfinished item after sample() IO-PSI.
+- files: agent_runner/_emit/memory.py, agent_runner/cli/_serve_cgroup.py, tests/unit/test_cgroup_probe.py, tests/e2e/test_e2e_pre_oom.py
+- verification: `.venv/bin/python -m pytest tests/unit/test_cgroup_probe.py -q` → 55 passed; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean
+- notes: defer is a required emit kwarg (every probe is yes/no). Did not touch runbook.md (docs item). Pre-existing pi-lens typing findings in _serve_cgroup left untouched.
+
+## 2026-09-18 round_cgroup_memory corroborating PSI fields
+
+- item: round_cgroup_memory may carry optional flat io_psi_some_avg10, io_psi_full_avg10, and psi_full_total from metrics.sample() at emit time. They are omitted when unread. They are never copied into Pressure.context.
+- rationale: plan prefers locking ladder-blindness and defer-field contracts before e2e fixture work. First remaining unfinished item after host_cgroup_memory_limit.defer.
+- files: agent_runner/_emit/memory.py, agent_runner/cli/_serve_cgroup.py, tests/unit/test_serve_round_cgroup_spine.py
+- verification: `.venv/bin/python -m pytest tests/unit/test_serve_round_cgroup_spine.py tests/unit/test_serve_round_oom_killed.py -q` → 19 passed; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean
+- notes: assumed sample() runs only on the successful emit path (skip-no-op paths do not sample); each None key is omitted independently. Did not edit host_health.py, events.md, or runbook.md. Pre-existing pi-lens typing findings in _serve_cgroup left untouched.
+
+## 2026-09-18 extract growth_child.py
+
+- item: The paced pre-OOM child lives in tests/e2e/growth_child.py (8 MiB every 2.5s, page-touch). pi_growth_script installs that file instead of an inlined string. Importing the module does not start the infinite loop.
+- rationale: plan prefers extracting growth_child.py after ladder-blindness/defer-field contracts, before skip-closed control tests. First remaining unfinished item.
+- files: tests/e2e/growth_child.py, tests/e2e/conftest.py, tests/unit/test_growth_child_constants.py
+- verification: `.venv/bin/python -m pytest tests/unit/test_growth_child_constants.py -q` → 1 passed; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean
+- notes: assumed the constants test lives under tests/unit because CI and build.sh --ignore=tests/e2e. pi_growth_script still base64-over-ssh (same install path), reading tests/e2e/growth_child.py bytes instead of an inlined string. Importing the module does not enter main().
+
+## 2026-09-18 skip-closed control-arm e2e
+
+- item: A skip-closed control-arm e2e exists: same unit as treatment except MemorySwapMax=0, MemoryHigh=120M kept, no oom.group and no OOMPolicy=kill. Unset AGENT_RUNNER_E2E_CGROUP and AGENT_RUNNER_E2E_PI, the new test skips. Assertions in source require defer true, no round_mem_terminated, no memory_high_engaged, events_oom_kill_delta>=1 or INVALID, DEFER-FIRST or KERNEL-FIRST named, growth child gone, host still answers.
+- rationale: plan prefers skip-closed control tests after extracting growth_child.py. First remaining unfinished item.
+- files: tests/e2e/conftest.py, tests/e2e/test_e2e_pre_oom.py
+- verification: `.venv/bin/python -m pytest tests/e2e/test_e2e_pre_oom.py -q` → 3 skipped; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean
+- notes: assumed PI control pytest timeout includes +600 install budget matching treatment; local uses +120 per plan. Two thin wrappers (PI + local CGROUP) share `_assert_control`. Skip-closed (unset env => skip) is the honest local proof; did not export e2e flags or run sudo/systemctl. Did not add OOMPolicy or memory.oom.group.
+
+## 2026-09-18 SECURITY reframe + CHANGELOG stub
+
+- item: Root SECURITY.md gains one paragraph: isolation is the operator's job (exec_prefix, dedicated user, no passwordless sudo, egress); agent-runner stays lifecycle-safety. CHANGELOG adds ## [0.3.13] - UNRELEASED. No docs/SECURITY.md. Optional results template under gitignored docs/internal/notes is allowed and must not be staged.
+- rationale: plan says docs last. Last remaining unfinished item.
+- files: SECURITY.md, CHANGELOG.md
+- verification: `.venv/bin/python -m pytest tests/invariants/test_docs_index_complete.py tests/invariants/test_doc_claims_match_ssot.py -q` → 4 passed; `.venv/bin/ruff check . && .venv/bin/ruff format --check .` clean; `docs/SECURITY.md` absent
+- notes: assumed not naming a competitor in SECURITY.md (Ralph item asks for the operator-vs-lifecycle split). Did not edit runbook.md (not in the Ralph item). Results template written under gitignored docs/internal/notes and not staged. Did not claim uncapped-before-coma or a live two-arm run.

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.13}/.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
@@ -281,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.11 → cli_agent_runner-0.3.13}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.13] - 2026-09-18
+
+### Added
+- Two production cgroup modes are now checkable on the same paced growth child: treatment (`MemorySwapMax` infinity) still cooperatively terminates and reaps; control (`MemorySwapMax=0`) defers to kernel cgroup-OOM of the capped child. Both leave the host up. The uncapped-before-coma case stays inferred.
+- `metrics.sample()` always includes corroborating `psi_full_total`, `io_psi_some_avg10`, and `io_psi_full_avg10` (`None` when unread). They are not kill rungs; `host_health.memory_pressure` stays blind to them.
+- `host_cgroup_memory_limit` carries `defer` as a bool (`True` when both caps are finite and plausible, including `MemorySwapMax=0`).
+- `round_cgroup_memory` may carry those PSI fields as optional flat keys at emit time; omitted when unread.
+
+### Docs
+- SECURITY.md: isolation is the operator's job (`exec_prefix`, dedicated user, no passwordless sudo, egress); agent-runner stays lifecycle-safety.
+
+No config migration required. `peek --json` schema stays `2.6`.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.11
+Version: 0.3.13
 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.3.11 → cli_agent_runner-0.3.13}/SECURITY.md

@@ -37,6 +37,12 @@ unprivileged user, inside a container or VM, without passwordless sudo, and
 with egress limits. The supervisor's defenses bound the blast radius of a
 *misbehaving* agent, not a *hostile* one.
 
+Isolation is the operator's job. Isolation-enforcing supervisors exist;
+agent-runner deliberately is not one of them. Lifecycle-safety stays ours
+(round timeouts, process-group reaping, orphan stashing, auto-stop on
+critical alerts). Containment stays yours: `[agent] exec_prefix`, a dedicated
+unprivileged user, no passwordless sudo, and egress limits.
+
 ## Containment
 
 If you need to bound what the agent can reach, run it inside a container (or

cli_agent_runner-0.3.13/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.11 → cli_agent_runner-0.3.13}/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.11 → cli_agent_runner-0.3.13}/agent_runner/_emit/memory.py

@@ -112,6 +112,7 @@ def emit_host_cgroup_memory_limit(
     memory_max: int | None,
     memory_swap_max: int | None,
     cgroup_path: str | None,
+    defer: bool,
     swap_total_bytes: int | None = None,
     swap_cap_pct: float | None = None,
     memory_high: int | None = None,
@@ -120,8 +121,11 @@ def emit_host_cgroup_memory_limit(
 ) -> None:
     """Emit once at serve startup: this process's cgroup v2 memory budget
     (``metrics.cgroup_memory_limits``). ``None`` fields mean unlimited (or
-    cgroup v2 unavailable). Serve uses this once to decide whether the
-    mid-round hard floor can defer to kernel cgroup-OOM -- see
+    cgroup v2 unavailable). ``defer`` is the already-computed mid-round-floor
+    decision (True when both caps are finite and plausible, including
+    ``MemorySwapMax=0``) -- the event carries that yes/no, not just the
+    inputs. Serve uses this once to decide whether the mid-round hard floor
+    can defer to kernel cgroup-OOM -- see
     ``emit_mem_pressure_deferred_to_cgroup`` below.
 
     This also carries an optional startup advisory
@@ -152,6 +156,7 @@ def emit_host_cgroup_memory_limit(
         memory_max=memory_max,
         memory_swap_max=memory_swap_max,
         cgroup_path=cgroup_path,
+        defer=defer,
         swap_total_bytes=swap_total_bytes,
         swap_cap_pct=swap_cap_pct,
         memory_high=memory_high,
@@ -171,6 +176,9 @@ def emit_round_cgroup_memory(
     events_oom_delta: int,
     events_oom_kill_delta: int,
     bounding_cgroup_path: str | None,
+    io_psi_some_avg10: float | None = None,
+    io_psi_full_avg10: float | None = None,
+    psi_full_total: float | int | None = None,
 ) -> None:
     """Emit once per round: the round's peak cgroup ``memory.current`` (+swap) and
     the ``memory.events`` DELTAS (high/max/oom/oom_kill) over the round, read at the
@@ -185,9 +193,24 @@ def emit_round_cgroup_memory(
     process's own) cgroup; here it names the BOUNDING ANCESTOR (the one whose
     ``memory.max`` actually binds). Same key, two meanings across the two
     events an operator correlates would be a trap -- events.md pins field
-    semantics permanently once shipped, so the distinct name is chosen now."""
+    semantics permanently once shipped, so the distinct name is chosen now.
+
+    Optional corroborating PSI fields (``io_psi_some_avg10``,
+    ``io_psi_full_avg10``, ``psi_full_total``) come from ``metrics.sample()``
+    at emit time. Each is omitted when unread (``None``). They ride FLAT on
+    this event -- never copied into ``Pressure.context``, so the kill ladder
+    stays blind to them."""
     from agent_runner.events import ROUND_CGROUP_MEMORY, emit
 
+    extra = {
+        k: v
+        for k, v in (
+            ("io_psi_some_avg10", io_psi_some_avg10),
+            ("io_psi_full_avg10", io_psi_full_avg10),
+            ("psi_full_total", psi_full_total),
+        )
+        if v is not None
+    }
     emit(
         log_dir,
         ROUND_CGROUP_MEMORY,
@@ -199,6 +222,7 @@ def emit_round_cgroup_memory(
         events_oom_delta=events_oom_delta,
         events_oom_kill_delta=events_oom_kill_delta,
         bounding_cgroup_path=bounding_cgroup_path,
+        **extra,
     )
 
 

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.13}/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.11 → cli_agent_runner-0.3.13}/agent_runner/_serve_policy.py

@@ -303,17 +303,18 @@ _STOP_GRACE_MARGIN_S = 10  # pad above _ROUND_TERM_GRACE_S for systemd stop-requ
 _ROUND_UNREAPED_RC = 137  # 128 + SIGKILL(9): reads as a kill in the crash-loop path
 
 
-def timeout_budget(round_budget_s: int) -> tuple[int, int]:
+def timeout_budget(round_budget_s: int, *, goal_checks_allowance_s: int = 0) -> tuple[int, int]:
     """Single source for the round-timeout safety budget.
 
     Returns ``(timeout_stop_sec, outer_ceiling_s)``:
 
     - ``outer_ceiling_s`` — the in-process outer wall-clock ceiling for the
       round subprocess (``api.outer_round_ceiling_s``): ``round_budget_s``
-      plus reap grace + git-commit ceiling + hook allowance, so it only trips
-      when the round supervisor itself is wedged, never during its own
-      bounded post-round cleanup. The reap margin must cover the widest grace
-      ANY round can be configured with -- a cooperative agent's
+      plus reap grace + git-commit ceiling + hook allowance + the goal-check
+      executor's own allowance, so it only trips when the round supervisor
+      itself is wedged, never during its own bounded post-round cleanup (nor
+      a slow-but-still-bounded goal check). The reap margin must cover the
+      widest grace ANY round can be configured with -- a cooperative agent's
       ``sigterm_grace_s`` is boot-capped at ``_ROUND_TERM_GRACE_S``
       (``config/models.py``'s mirror of this module's single source), not
       the non-cooperative default ``_REAP_GRACE_S``, so the margin is
@@ -324,12 +325,19 @@ def timeout_budget(round_budget_s: int) -> tuple[int, int]:
       SIGTERM to reach and drain the round (``_ROUND_TERM_GRACE_S``) plus a
       stop-request overhead pad, so `systemctl stop` never SIGKILLs a round
       that is draining normally.
+
+    ``goal_checks_allowance_s`` (default 0, byte-identical to the old
+    signature when omitted) is the caller's ``GoalConfig.checks_allowance_s``
+    when ``[goal]`` is configured -- folded into this ONE ceiling rather than
+    a second, separate one, so the goal-check path can never itself trip
+    ``round_supervisor_wedged``.
     """
     outer_ceiling_s = (
         round_budget_s
         + max(_REAP_GRACE_S, _ROUND_TERM_GRACE_S)
         + _GIT_COMMIT_TIMEOUT_S
         + _HOOK_ALLOWANCE_S
+        + goal_checks_allowance_s
     )
     timeout_stop_sec = outer_ceiling_s + _ROUND_TERM_GRACE_S + _STOP_GRACE_MARGIN_S
     return timeout_stop_sec, outer_ceiling_s

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.13}/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.11'
-__version_tuple__ = version_tuple = (0, 3, 11)
+__version__ = version = '0.3.13'
+__version_tuple__ = version_tuple = (0, 3, 13)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.13}/agent_runner/cli/_serve_cgroup.py

@@ -128,6 +128,8 @@ def _emit_round_cgroup_memory(
     def _delta(key: str) -> int:
         return max(0, cur_ev.get(key, 0) - base_ev.get(key, 0))
 
+    # One sample() at emit -- corroborating IO/mem-PSI, omitted when unread.
+    s = metrics.sample()
     emit_round_cgroup_memory(
         log_dir,
         round_num=round_num,
@@ -138,6 +140,9 @@ def _emit_round_cgroup_memory(
         events_oom_delta=_delta("oom"),
         events_oom_kill_delta=_delta("oom_kill"),
         bounding_cgroup_path=state["bounding_cgroup_path"],
+        io_psi_some_avg10=s.get("io_psi_some_avg10"),
+        io_psi_full_avg10=s.get("io_psi_full_avg10"),
+        psi_full_total=s.get("psi_full_total"),
     )
     return cur, oom_kill_baseline
 
@@ -277,8 +282,9 @@ def _release_brake(log_dir: Path, round_num: int, previous: str, *, reason: str)
 
 def _probe_and_emit_cgroup_defer(log_dir: Path, *, brake_memory_high: bool = False) -> bool:
     """Probe this process's cgroup v2 memory budget once at serve startup,
-    emit host_cgroup_memory_limit for observability, and return whether the
-    mid-round hard floor should defer to kernel cgroup-OOM: True only when
+    emit host_cgroup_memory_limit (including the ``defer`` decision, not just
+    the inputs) for observability, and return whether the mid-round hard
+    floor should defer to kernel cgroup-OOM: True only when
     BOTH memory.max and memory.swap.max are finite (the field host's
     MemoryMax=320M + MemorySwapMax=160M shape) -- that budget is bounded end
     to end, so cgroup-OOM WILL fire and contain the agent while the host
@@ -401,6 +407,7 @@ def _probe_and_emit_cgroup_defer(log_dir: Path, *, brake_memory_high: bool = Fal
         memory_max=limits["memory_max"],
         memory_swap_max=swap_max,
         cgroup_path=limits["cgroup_path"],
+        defer=defer,
         swap_total_bytes=swap_total,
         swap_cap_pct=swap_cap_pct,
         memory_high=memory_high,

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.13}/agent_runner/config/__init__.py

@@ -40,6 +40,7 @@ from agent_runner.config.models import (  # noqa: F401 — public re-export
     _VCS_ALLOWED_FIELDS,
     AgentConfig,
     Config,
+    GoalConfig,
     MonitorConfig,
     MonitorHostHealthConfig,
     PhaseOverride,
@@ -50,17 +51,22 @@ from agent_runner.config.models import (  # noqa: F401 — public re-export
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _GoalCheckConfig,
     _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
     _HostHealthPressureConfig,
 )
-from agent_runner.config.validators import _reject_control_chars  # noqa: F401
+from agent_runner.config.validators import (  # noqa: F401 — public re-export
+    _reject_control_chars,
+    _resolve_against_work_dir,
+)
 
 __all__ = [
     "AgentConfig",
     "Config",
     "ConfigError",
+    "GoalConfig",
     "MonitorConfig",
     "MonitorHostHealthConfig",
     "PhaseOverride",