cli-agent-runner 0.2.22__tar.gz → 0.2.24__tar.gz

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/.vulture-whitelist.py

@@ -128,6 +128,11 @@ agent
 since_round
 phase
 
+# agent_runner.cli.doctor_cmd.DoctorReport
+checks
+overlaps
+plan
+
 # agent_runner.config.models.AgentConfig
 command
 prompt_arg_template
@@ -135,6 +140,7 @@ name
 env
 prompt_delivery
 exec_prefix
+terminal_marker
 
 # agent_runner.config.models.Config
 agent
@@ -296,6 +302,12 @@ resume_timezone
 skipped
 active_window
 
+# agent_runner.phase_select.WindowOverlap
+phase_a
+phase_b
+window_a
+window_b
+
 # agent_runner.round_log.PruneOutcome
 deleted
 deferred
@@ -319,6 +331,11 @@ reason
 how_to_fix
 permanent
 
+# agent_runner.startup_check.CheckSpec
+kind
+scope
+run
+
 # agent_runner.vcs_state.StashRef
 sha
 message

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.24] - 2026-09-12
+
+### Added
+- `host_cgroup_memory_limit` now advises adding `MemoryHigh` when a cgroup has `memory.max` set without `memory.high` (graceful pre-OOM throttling) — only for a bound on the supervisor's own cgroup, with the PSI-floor caveat when the mid-round floor isn't already deferring.
+
+### Changed
+- `doctor`'s phase-plan preview now shows a paused phase's resume time.
+- Trimmed the grace-kill test wall-time (~80s faster suite; behavior-identical).
+
+## [0.2.23] - 2026-09-12
+
+### Added
+- `[agent] terminal_marker` — per-preset grace-kill result marker (default = Claude's token; pi/codewhale set their own; kimi/aider have no marker and run to the wall-clock ceiling).
+- `doctor` — read-only pre-flight (never launches the agent): startup checks, phase-window overlap warnings, and an N-round phase-plan preview.
+- `phase_window_overlap` event — emitted at serve boot when two agent-overriding phases' windows collide in the same timezone.
+
+### Changed
+- Startup-check dispatch and the catalog's kind list now derive from a single descriptor table (no behavior change).
+- The lock-holder pid create_time verify now shares one `lifecycle` helper with `serve.pid` (no behavior change).
+- Default `claude` preset model updated `claude-opus-4-7` → `claude-opus-5`.
+
+### Fixed
+- `peek` no longer prints spurious "cannot coerce None" warnings on a freshly-initialized project; absent metric samples fall back to defaults silently (a genuinely malformed value still warns).
+
 ## [0.2.22] - 2026-09-11
 
 ### Fixed

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.22
+Version: 0.2.24
 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
@@ -82,7 +82,7 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 16 verbs
+## 17 verbs
 
 | Lifecycle | Observation |
 |---|---|

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/README.md

@@ -44,7 +44,7 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 16 verbs
+## 17 verbs
 
 | Lifecycle | Observation |
 |---|---|

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/_emit/__init__.py

@@ -57,6 +57,7 @@ from agent_runner._emit.serve import (  # noqa: F401 — public re-export
     emit_max_rounds_reached,
     emit_mem_loop,
     emit_mem_loop_persistent,
+    emit_phase_window_overlap,
     emit_rate_limit_stop,
     emit_schedule_paused,
     emit_schedule_phase_skipped,
@@ -78,6 +79,7 @@ __all__ = [
     "emit_mem_loop",
     "emit_mem_loop_persistent",
     "emit_mem_pressure_deferred_to_cgroup",
+    "emit_phase_window_overlap",
     "emit_rate_limit_stop",
     "emit_round_cgroup_memory",
     "emit_round_container_orphan_risk",

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/_emit/memory.py

@@ -113,7 +113,7 @@ def emit_host_cgroup_memory_limit(
     mid-round hard floor can defer to kernel cgroup-OOM -- see
     ``emit_mem_pressure_deferred_to_cgroup`` below.
 
-    This also carries an optional startup swap-cap advisory
+    This also carries an optional startup advisory
     (``swap_total_bytes`` / ``swap_cap_pct`` / ``memory_high`` / ``advisory``)
     as FIELDS on this SAME event -- never a separate event kind, and never an
     auto-change to the operator's cgroup or unit. ``swap_total_bytes`` is the
@@ -123,8 +123,12 @@ def emit_host_cgroup_memory_limit(
     bytes (``metrics.cgroup_memory_high``) -- ``None`` means unset (the
     cgroup read the literal ``"max"``, or no finite value at all), never the
     raw ``"max"`` token, so a caller can't mistake "unset" for a real
-    ceiling; ``advisory`` is the human-readable warning text when the swap
-    cap looks implausibly tight, else ``None``."""
+    ceiling; ``advisory`` is the human-readable warning text, else ``None`` --
+    it covers two independent conditions, joined with ``"; "`` when both
+    fire: a ``memory.swap.max`` that looks implausibly tight against host
+    swap, and a ``memory.max`` set on this process's OWN cgroup without a
+    ``memory.high``, which recommends adding one (below ``memory.max``) for
+    graceful pre-OOM throttling instead of a hard kill."""
     from agent_runner.events import HOST_CGROUP_MEMORY_LIMIT, emit
 
     emit(

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/_emit/serve.py

@@ -191,3 +191,23 @@ def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
     from agent_runner.events import SCHEDULE_RESUMED, emit
 
     emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
+
+
+def emit_phase_window_overlap(
+    log_dir: Path, *, phase_a: str, phase_b: str, window_a: str, window_b: str
+) -> None:
+    """Emit phase_window_overlap: two agent-overriding phases' own run_windows
+    collide (a rotation footgun; a later release promotes this exact detection
+    to a hard error). Called once at serve boot -- the collision is a property of the
+    static config, not of any one round, so (like emit_max_rounds_reached's
+    cgroup-probe sibling) this must not be called from the per-round path."""
+    from agent_runner.events import PHASE_WINDOW_OVERLAP, emit
+
+    emit(
+        log_dir,
+        PHASE_WINDOW_OVERLAP,
+        phase_a=phase_a,
+        phase_b=phase_b,
+        window_a=window_a,
+        window_b=window_b,
+    )

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/_monitor_state.py

@@ -154,21 +154,41 @@ def _latest_metric_dict(metrics: list[dict[str, Any]]) -> dict[str, Any]:
     return metrics[-1] if metrics else {}
 
 
+def _metric_int(latest: dict[str, Any], key: str, default: int) -> int:
+    """``_coerce_int`` for a metric field, silent on absence.
+
+    A fresh project has no metric events yet, so ``latest`` is ``{}`` and
+    every field reads as None -- "no sample yet", not malformed data. Only a
+    present-but-non-numeric value should still warn (delegated to
+    ``_coerce_int``, which owns that contract)."""
+    from agent_runner._throttle import _coerce_int
+
+    value = latest.get(key)
+    return default if value is None else _coerce_int(value, default)
+
+
+def _metric_float(latest: dict[str, Any], key: str, default: float) -> float:
+    """Float sibling of ``_metric_int`` -- see its docstring."""
+    from agent_runner._throttle import _coerce_float
+
+    value = latest.get(key)
+    return default if value is None else _coerce_float(value, default)
+
+
 def assemble_project_state(source: LocalSource, *, project: str) -> ProjectState:
     metrics = parse_events_from_jsonl_files(source.metrics_files())
     status = read_json(source.status_path()) or {}
     orphan = read_json(source.orphan_path())
     latest = _latest_metric_dict(metrics)
-    from agent_runner._throttle import _coerce_float, _coerce_int
 
     system = SystemMetrics(
-        mem_total_mb=_coerce_int(latest.get("mem_total_mb"), 0),
-        mem_available_mb=_coerce_int(latest.get("mem_available_mb"), 0),
-        disk_used_pct=_coerce_float(latest.get("disk_used_pct"), 0.0),
-        disk_free_gb=_coerce_float(latest.get("disk_free_gb"), 0.0),
+        mem_total_mb=_metric_int(latest, "mem_total_mb", 0),
+        mem_available_mb=_metric_int(latest, "mem_available_mb", 0),
+        disk_used_pct=_metric_float(latest, "disk_used_pct", 0.0),
+        disk_free_gb=_metric_float(latest, "disk_free_gb", 0.0),
         load_1m=latest.get("load_1m"),
         cpu_pct=latest.get("cpu_pct"),
-        agent_process_count=_coerce_int(latest.get("agent_process_count"), 0),
+        agent_process_count=_metric_int(latest, "agent_process_count", 0),
     )
     return ProjectState(
         project=project,

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.22'
-__version_tuple__ = version_tuple = (0, 2, 22)
+__version__ = version = '0.2.24'
+__version_tuple__ = version_tuple = (0, 2, 24)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/agent_runtime.py

@@ -247,11 +247,6 @@ def _live_children(
     return live, ignored
 
 
-# Exact compact bytes — matches claude CLI's no-whitespace JSONL output.
-# A future CLI variant emitting `{"type": "result", ...}` (with space) would
-# bypass this scan; revisit if that happens.
-_RESULT_MARKER = b'"type":"result"'
-
 # Decoupled from the 0.2s poll tick: the marker scan only needs to notice the
 # result within max_grace_after_result_s (seconds, integer), so scanning more
 # often than this buys nothing but re-read cost on a growing round log.
@@ -573,6 +568,7 @@ def run(
     log_path: Path,
     env_extra: dict[str, str],
     max_grace_after_result_s: int = 0,
+    terminal_marker: str = '"type":"result"',  # mirrors config.DEFAULT_TERMINAL_MARKER
     progress_callback: Callable[[dict], None] | None = None,
     progress_interval_s: int = 0,
     on_grace_extended: Callable[[list[dict], list[dict]], None] | None = None,
@@ -588,13 +584,19 @@ def run(
     already-absolute cfg.runtime.work_dir. CLIs with no --cwd flag of their
     own (e.g. pi) depend on this.
 
-    max_grace_after_result_s: when > 0, start a countdown after the first
-    type=result event is detected in the log. After it elapses, reap the
+    max_grace_after_result_s: when > 0, start a countdown after
+    ``terminal_marker`` is first detected in the log. After it elapses, reap the
     process group only if the agent has no live worker processes left (a
     genuine hang). If a worker is still running (e.g. a backgrounded build),
     do not reap — invoke ``on_grace_extended`` once and keep waiting until the
     round finishes or hits the wall-clock ``timeout_s`` ceiling. 0 = disabled.
 
+    terminal_marker: exact compact byte substring the grace-kill scan looks
+    for (default matches claude CLI's no-whitespace JSONL ``{"type":"result",
+    ...}`` output). An empty string disables the marker scan outright, even
+    with max_grace_after_result_s > 0 (honest opt-out, not an
+    empty-substring-matches-everything trap).
+
     progress_callback: when not None and progress_interval_s > 0, called every
     progress_interval_s seconds with a dict of log stats (log_size_kb,
     last_write_age_s, wall_age_s). Keeps agent_runtime event-free; callers
@@ -619,6 +621,7 @@ def run(
     attempt where covered; it just isn't reported).
     """
     stdin_mode = prompt_delivery == "stdin"
+    marker_bytes = terminal_marker.encode("utf-8")
     # Raising work (mkdir can fail on disk-full/perms/removed log_dir) must
     # happen BEFORE the container-detection block below creates the
     # host-private cidfile tempdir -- otherwise a raise here would skip the
@@ -749,7 +752,7 @@ def run(
                     exit_code=exit_code, duration_s=duration, timed_out=True, pid=proc.pid
                 )
             # Grace kill: result emitted but subprocess still running.
-            if max_grace_after_result_s > 0:
+            if max_grace_after_result_s > 0 and marker_bytes:
                 if result_seen_at is None and now - last_result_scan >= _RESULT_SCAN_INTERVAL_S:
                     last_result_scan = now
                     try:
@@ -758,12 +761,16 @@ def run(
                             chunk = f.read()
                         result_scan_offset += len(chunk)
                         haystack = result_scan_carry + chunk
-                        if _RESULT_MARKER in haystack:
+                        if marker_bytes in haystack:
                             result_seen_at = now
                         else:
                             # Keep the tail so a marker split across two read
                             # chunks (this scan vs. the next) still re-forms.
-                            result_scan_carry = haystack[-(len(_RESULT_MARKER) - 1) :]
+                            # A 1-byte marker can't be split, so carry nothing
+                            # -- haystack[-0:] is the WHOLE buffer, not empty,
+                            # so the zero case needs its own branch.
+                            _carry = len(marker_bytes) - 1
+                            result_scan_carry = haystack[-_carry:] if _carry else b""
                     except OSError:
                         pass  # log not flushed yet; retry next interval
                 if result_seen_at is not None and now - result_seen_at > max_grace_after_result_s:

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/api.py

@@ -357,8 +357,6 @@ def _round_holder_pid(log_dir: Path) -> int | None:
     alive. This is the ONLY way ``kill()`` can reach an in-flight round: the
     round is ``start_new_session=True`` (its own session, its own pgid), so it
     sits outside whatever process group serve itself belongs to."""
-    import psutil
-
     from agent_runner.context_store import read_json
 
     data = read_json(log_dir / "agent-runner.lock.holder")
@@ -370,14 +368,7 @@ def _round_holder_pid(log_dir: Path) -> int | None:
     if not pid_alive(pid):
         return None
     recorded = data.get("create_time")
-    if recorded is None:
-        return pid  # legacy sidecar without a token: best-effort, mirrors serve.pid's read
-    try:
-        if abs(psutil.Process(pid).create_time() - recorded) < 1.0:
-            return pid
-    except psutil.Error:
-        return None
-    return None  # recorded create_time != live process: a recycled pid, do not signal it
+    return pid if lifecycle.create_time_matches(pid, recorded) else None
 
 
 def _terminate_round_pid(pid: int) -> None:
@@ -854,6 +845,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_mem_loop,
     emit_mem_loop_persistent,
     emit_mem_pressure_deferred_to_cgroup,
+    emit_phase_window_overlap,
     emit_rate_limit_stop,
     emit_round_cgroup_memory,
     emit_round_container_orphan_risk,

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/cli/__init__.py

@@ -17,6 +17,7 @@ from pathlib import Path
 
 from agent_runner import __version__
 from agent_runner.cli import (
+    doctor_cmd,
     events_cmd,
     init_cmd,
     install_cmd,
@@ -71,6 +72,7 @@ def _build_parser() -> argparse.ArgumentParser:
     round_cmd.add_parser(sub, parent)
     upgrade_cmd.add_parser(sub, parent)
     migrate_cmd.add_parser(sub, parent)
+    doctor_cmd.add_parser(sub, parent)
 
     return parser
 

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/cli/_serve_cgroup.py

@@ -225,9 +225,18 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     memory.swap.max is bounded but far below the host's own available swap
     (``_SWAP_CAP_ADVISORY_PCT``): the operator capped the cgroup's swap well
     under what the host has, so the mid-round floor may terminate a round
-    the kernel would have contained on a wider cap. One line is also printed
-    to stderr in that case. The event also carries ``memory_high`` -- the
-    bounding ancestor's ``memory.high`` soft-throttle threshold
+    the kernel would have contained on a wider cap. A second, independent
+    advisory recommends ``memory.high`` when ``memory.max`` is set but
+    ``memory.high`` isn't -- ONLY when the bounding ancestor is the
+    operator's OWN leaf (``bounding_cgroup_path == cgroup_path``): since
+    ``memory.max`` is the MIN across every ancestor, "set" can also mean an
+    inherited parent slice or a container root, where "add MemoryHigh" is
+    noise the operator can't act on from their own unit. That hint also
+    appends a PSI-floor caveat, but only when the floor ISN'T already
+    deferring to kernel cgroup-OOM (a deferring host has no floor for the
+    throttle's PSI-full rise to trip). Both advisories join with ``"; "``
+    and print as one stderr line. The event also carries ``memory_high`` --
+    the bounding ancestor's ``memory.high`` soft-throttle threshold
     (``metrics.cgroup_memory_high``), ``None`` when unset -- for the same
     reason: an operator asking "is MemoryHigh even set" is exactly this
     release's field ask. Advisory only -- this never changes the operator's
@@ -247,13 +256,39 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
     swap_cap_pct = (
         round(100.0 * swap_max / swap_total, 1) if swap_max is not None and swap_total > 0 else None
     )
-    advisory: str | None = None
+    advisories: list[str] = []
     if swap_cap_pct is not None and swap_cap_pct < _SWAP_CAP_ADVISORY_PCT:
-        advisory = (
+        advisories.append(
             "cgroup memory.swap.max is far below host swap; the mid-round floor may "
             "terminate rounds the kernel would have contained -- consider bounding "
             "both memory.max and memory.swap.max, or set in_round_mem_terminate=false"
         )
+    defer = (
+        limits["memory_max"] is not None
+        and swap_max is not None
+        and limits["memory_max"] < metrics.mem_total_bytes()
+        and swap_max <= swap_total  # 4th guard: a >> host-swap cap can't bind -> stay armed
+    )
+    own_scope = (
+        limits["memory_max"] is not None
+        and memory_high is None
+        and limits["bounding_cgroup_path"] == limits["cgroup_path"]
+    )
+    if own_scope:
+        hint = (
+            "memory.max is set on this cgroup without memory.high -- add "
+            "memory.high (below memory.max) for graceful throttling before an "
+            "OOM kill"
+        )
+        if not defer:
+            hint += (
+                "; bound memory.swap.max (at or below host swap) too, or set "
+                "in_round_mem_terminate=false, so the throttle's PSI-full rise "
+                "doesn't trip the mid-round floor"
+            )
+        advisories.append(hint)
+    advisory = "; ".join(advisories) or None
+    if advisory is not None:
         print(f"agent-runner: {advisory}", file=sys.stderr)
     emit_host_cgroup_memory_limit(
         log_dir,
@@ -265,9 +300,4 @@ def _probe_and_emit_cgroup_defer(log_dir: Path) -> bool:
         memory_high=memory_high,
         advisory=advisory,
     )
-    return (
-        limits["memory_max"] is not None
-        and swap_max is not None
-        and limits["memory_max"] < metrics.mem_total_bytes()
-        and swap_max <= swap_total  # 4th guard: a >> host-swap cap can't bind -> stay armed
-    )
+    return defer

cli_agent_runner-0.2.24/agent_runner/cli/doctor_cmd.py

@@ -0,0 +1,84 @@
+"""doctor subcommand — never launches the configured agent; runs the same
+read-only-ish boot checks serve does (it may create/probe the log dir to
+verify it's writable), then reports window overlaps + phase plan."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_runner import phase_select, startup_check
+from agent_runner.cli.common import cfg_from_args, emit
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    checks: list[startup_check.CheckResult]
+    overlaps: list[phase_select.WindowOverlap]
+    plan: list[dict]
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser("doctor", parents=[parent], help="Read-only pre-flight: checks + phase plan")
+    p.add_argument("--rounds", type=int, default=3, help="Phase-plan preview depth (default 3)")
+    p.set_defaults(func=cmd_doctor)
+
+
+def _plan(cfg, rounds: int) -> list[dict]:
+    out = []
+    for r in range(1, rounds + 1):
+        sel = phase_select.select_phase(cfg, r)
+        out.append(
+            {
+                "round": r,
+                "phase": sel.phase,
+                "paused": sel.paused,
+                "resume_phase": sel.resume_phase,
+                "resume_at": sel.resume_at.isoformat() if sel.resume_at else None,
+                "resume_timezone": sel.resume_timezone,
+                "skipped": sel.skipped,
+                "active_window": sel.active_window,
+            }
+        )
+    return out
+
+
+def cmd_doctor(args) -> int:
+    cfg = cfg_from_args(args)
+    report = DoctorReport(
+        checks=startup_check.run_battery(cfg),
+        overlaps=phase_select.find_phase_window_overlaps(cfg),
+        plan=_plan(cfg, args.rounds),
+    )
+    json_mode = getattr(args, "json", False)
+    if json_mode:
+        emit(report, json_mode=True)
+    else:
+        print(_format(report))
+    return 0
+
+
+def _format(report: DoctorReport) -> str:
+    # Hand-formatted rather than common._pretty: that helper repr()s nested
+    # lists/dicts, which would dump report.plan's per-round dicts as Python
+    # reprs instead of the readable "round N: phase" lines below.
+    lines = ["checks:"]
+    for c in report.checks:
+        mark = "ok" if c.ok else "FAIL"
+        detail = ""
+        if not c.ok:
+            detail = f" — {c.reason}" + (f" (fix: {c.how_to_fix})" if c.how_to_fix else "")
+        lines.append(f"  [{mark}] {c.name}{detail}")
+    if report.overlaps:
+        lines.append("window overlaps:")
+        for o in report.overlaps:
+            lines.append(f"  {o.phase_a} ({o.window_a}) vs {o.phase_b} ({o.window_b})")
+    lines.append("phase plan:")
+    for step in report.plan:
+        if step["paused"]:
+            where = "paused"
+            if step["resume_at"] is not None:
+                where += f" -> resumes {step['resume_phase']} at {step['resume_at']}"
+        else:
+            where = step["phase"] or "base"
+        lines.append(f"  round {step['round']}: {where}")
+    return "\n".join(lines)

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/cli/serve_cmd.py

@@ -35,6 +35,7 @@ from agent_runner.api import (
     emit_config_broken,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
+    emit_phase_window_overlap,
     emit_rate_limit_stop,
     emit_round_logs_prune_deferred,
     emit_round_substrate_after,
@@ -615,6 +616,16 @@ def cmd(args) -> int:
     # Emitted exactly once per serve lifetime -- the per-round defer decision below
     # reuses this bool rather than re-probing/re-emitting every round.
     cgroup_probe_defer = _probe_and_emit_cgroup_defer(log_dir)
+    # Static config check -- phase-window collisions can't change mid-lifetime, so
+    # (like the cgroup probe above) this runs once at boot, not once per round.
+    for ov in phase_select.find_phase_window_overlaps(cfg):
+        emit_phase_window_overlap(
+            log_dir,
+            phase_a=ov.phase_a,
+            phase_b=ov.phase_b,
+            window_a=ov.window_a,
+            window_b=ov.window_b,
+        )
     rounds_completed = 0
     # Three independent consecutive-failure counters, one per breaker: b12
     # crash-loop (unknown short crashes), mem-loop (mem-terminated

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/config/models.py

@@ -22,6 +22,12 @@ _VALID_DIRTY_ACTIONS: frozenset[str] = frozenset({"stash", "ignore", "auto_commi
 _VALID_TRANSIENT_ERROR_ACTIONS: frozenset[str] = frozenset({"back_off", "skip", "stop"})
 _VALID_PROMPT_DELIVERY: frozenset[str] = frozenset({"argv", "stdin"})
 
+# claude's own compact JSONL terminal token — the default `[agent] terminal_marker`
+# so existing configs are unaffected. Single source for the field default and the
+# TOML-parse fallback (parsers.py); `agent_runtime.run`'s own kwarg default mirrors
+# this literal but is decoupled to avoid an agent_runtime -> config import.
+DEFAULT_TERMINAL_MARKER = '"type":"result"'
+
 
 @dataclass(frozen=True)
 class AgentConfig:
@@ -31,6 +37,11 @@ class AgentConfig:
     env: dict[str, str] = field(default_factory=dict)
     prompt_delivery: Literal["argv", "stdin"] = "argv"
     exec_prefix: list[str] = field(default_factory=list)
+    terminal_marker: str = DEFAULT_TERMINAL_MARKER
+    """Byte substring the grace-kill scan looks for in the round log to detect
+    the agent's terminal record (see ``agent_runtime.run``'s marker scan).
+    Defaults to claude's own JSONL token so existing configs are unaffected;
+    an empty string opts out of the marker scan entirely (wall-clock-ceiling-only)."""
 
     @property
     def binary(self) -> str | None:

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/config/parsers.py

@@ -32,6 +32,7 @@ from agent_runner.config.models import (
     _VALID_PROMPT_DELIVERY,
     _VALID_TRANSIENT_ERROR_ACTIONS,
     _VCS_ALLOWED_FIELDS,
+    DEFAULT_TERMINAL_MARKER,
     AgentConfig,
     MonitorConfig,
     MonitorHostHealthConfig,
@@ -109,6 +110,7 @@ def _parse_agent(
     exec_prefix = _require_str_list(
         agent_d.get("exec_prefix", []), field=f"{field_prefix} exec_prefix"
     )
+    terminal_marker = str(agent_d.get("terminal_marker", DEFAULT_TERMINAL_MARKER))
     return AgentConfig(
         command=command,
         prompt_arg_template=prompt_arg_template,
@@ -116,6 +118,7 @@ def _parse_agent(
         env={str(k): str(v) for k, v in env_d.items()},
         prompt_delivery=prompt_delivery,  # type: ignore[arg-type]  # narrowed above
         exec_prefix=exec_prefix,
+        terminal_marker=terminal_marker,
     )
 
 

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/events.py

@@ -60,6 +60,7 @@ ORPHAN_IDEMPOTENT_SKIP = "orphan_idempotent_skip"
 ORPHAN_STASH_FAILED = "orphan_stash_failed"
 ORPHAN_STASHED = "orphan_stashed"
 PACKAGE_UPGRADED = "package_upgraded"
+PHASE_WINDOW_OVERLAP = "phase_window_overlap"
 PROMPT_OVERWRITTEN = "prompt_overwritten"
 ROUND_CGROUP_MEMORY = "round_cgroup_memory"
 ROUND_CONTAINER_ORPHAN_RISK = "round_container_orphan_risk"

{cli_agent_runner-0.2.22 → cli_agent_runner-0.2.24}/agent_runner/lifecycle.py

@@ -89,6 +89,29 @@ def _valid_pid(value: object) -> bool:
     return isinstance(value, int) and not isinstance(value, bool) and value > 1
 
 
+def create_time_of(pid: int) -> float | None:
+    """The process start-time identity token for ``pid``, or None if it can't be
+    read (no such process / no permission). Recorded when writing a pid so a
+    later read can tell the same process from a recycled PID."""
+    try:
+        return psutil.Process(pid).create_time()
+    except psutil.Error:
+        return None
+
+
+def create_time_matches(pid: int, recorded: float | None) -> bool:
+    """True iff ``pid`` still names the process whose start-time was ``recorded``.
+    ``recorded is None`` (a legacy sidecar without a token) -> True, best-effort
+    unverified, matching the historical behaviour. A live start-time differing by
+    >= 1s, or an unreadable process, -> False (a recycled PID: do not signal it)."""
+    if recorded is None:
+        return True
+    try:
+        return abs(psutil.Process(pid).create_time() - recorded) < 1.0
+    except psutil.Error:
+        return False
+
+
 @dataclass(frozen=True)
 class PIDFile:
     path: Path
@@ -99,10 +122,9 @@ class PIDFile:
         atomically (tmp + rename) so a concurrent ``stop``/``kill`` read never sees a
         torn file."""
         payload: dict[str, object] = {"pid": pid}
-        try:
-            payload["create_time"] = psutil.Process(pid).create_time()
-        except psutil.Error:
-            pass  # token is best-effort; a read without it falls back to unverified
+        ct = create_time_of(pid)
+        if ct is not None:
+            payload["create_time"] = ct
         atomic_write_json(self.path, payload)
 
     def read(self) -> int | None:
@@ -124,14 +146,7 @@ class PIDFile:
             return None
         pid = data["pid"]
         recorded = data.get("create_time")
-        if recorded is None:
-            return pid  # write couldn't capture a token; best-effort unverified
-        try:
-            if abs(psutil.Process(pid).create_time() - recorded) < 1.0:
-                return pid
-        except psutil.Error:
-            pass
-        return None  # process gone, or a different (recycled) process now holds the PID
+        return pid if create_time_matches(pid, recorded) else None
 
     def unlink(self) -> None:
         self.path.unlink(missing_ok=True)