cli-agent-runner 0.3.4__tar.gz → 0.3.5__tar.gz

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/.vulture-whitelist.py

@@ -158,6 +158,7 @@ overlaps
 plan
 sandbox
 cgroup
+sigterm_grace
 
 # agent_runner.config.models.AgentConfig
 command
@@ -167,6 +168,7 @@ env
 prompt_delivery
 exec_prefix
 terminal_marker
+sigterm_grace_s
 
 # agent_runner.config.models.Config
 agent

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.5] - 2026-09-15
+
+### Added
+- `[agent] sigterm_grace_s` (default 10): the SIGTERM→SIGKILL grace a round gives its agent when the agent's preset declares itself cooperative (the built-in `gemini` preset does), so an agent that catches SIGTERM to flush or commit its work gets time to finish. A non-cooperative agent (e.g. `claude`) keeps the previous 5 s. Capped at 12 s, inside the supervisor's 15 s wait for the round; `peek --json` (schema `2.4`) and `doctor` report the resolved grace per agent.
+
 ## [0.3.4] - 2026-09-15
 
 ### Changed

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.4
+Version: 0.3.5
 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.4 → cli_agent_runner-0.3.5}/agent_runner/_plugin_manifest.py

@@ -62,6 +62,26 @@ def cooperative_manifest_names() -> list[str]:
     return [m.name for m in _LOADED_MANIFESTS if m.sigterm_cooperative]
 
 
+def is_cooperative_agent(agent_binary: str | None) -> bool:
+    """Whether the agent's preset declares itself SIGTERM-cooperative.
+    `None in [...]` is safely False, so no None-guard is needed."""
+    return agent_binary in cooperative_manifest_names()
+
+
+def resolve_sigterm_grace_s(agent_binary: str | None, sigterm_grace_s: int) -> int:
+    """The SIGTERM->SIGKILL grace this round's agent actually gets:
+    `sigterm_grace_s` (config's [agent] sigterm_grace_s, boot-capped at
+    _ROUND_TERM_GRACE_S) when `agent_binary` names a manifest declaring
+    sigterm_cooperative=True, else agent_runtime.REAP_GRACE_S (5s)
+    unchanged. One function, two callers: cli.serve_cmd._apply_reap_grace_env
+    (what the agent actually gets) and doctor/peek (what an operator sees)."""
+    from agent_runner.agent_runtime import REAP_GRACE_S
+
+    if is_cooperative_agent(agent_binary):
+        return sigterm_grace_s
+    return REAP_GRACE_S
+
+
 def register_manifest(
     manifest: PluginManifest,
     *,

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/_serve_policy.py

@@ -312,13 +312,24 @@ def timeout_budget(round_budget_s: int) -> tuple[int, int]:
       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.
+      bounded post-round cleanup. 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
+      ``max(_REAP_GRACE_S, _ROUND_TERM_GRACE_S)`` -- else a long cooperative
+      grace could trip the outer wall-clock ceiling mid-grace.
     - ``timeout_stop_sec`` — systemd's ``TimeoutStopSec``
       (``service_unit.py``): must clear ``outer_ceiling_s`` by enough for a
       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.
     """
-    outer_ceiling_s = round_budget_s + _REAP_GRACE_S + _GIT_COMMIT_TIMEOUT_S + _HOOK_ALLOWANCE_S
+    outer_ceiling_s = (
+        round_budget_s
+        + max(_REAP_GRACE_S, _ROUND_TERM_GRACE_S)
+        + _GIT_COMMIT_TIMEOUT_S
+        + _HOOK_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.4 → cli_agent_runner-0.3.5}/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.4'
-__version_tuple__ = version_tuple = (0, 3, 4)
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/agent_runtime.py

@@ -161,7 +161,9 @@ def _wait_exit_shielded(
             continue
 
 
-def _kill_pgroup(proc: subprocess.Popen, clock: Clock = SYSTEM_CLOCK) -> None:
+def _kill_pgroup(
+    proc: subprocess.Popen, clock: Clock = SYSTEM_CLOCK, reap_grace_s: int = REAP_GRACE_S
+) -> None:
     """SIGTERM the pgroup, grace, then SIGKILL — the reap primitive shared by
     the round-timeout path and ``run``'s BaseException handler (which fires on
     a SIGTERM landing while the round is unwinding from a first one).
@@ -185,7 +187,7 @@ def _kill_pgroup(proc: subprocess.Popen, clock: Clock = SYSTEM_CLOCK) -> None:
     except OSError:
         pass
     deadline = (
-        clock.monotonic() + REAP_GRACE_S
+        clock.monotonic() + reap_grace_s
     )  # monotonic: an NTP step must not stretch/skip the reap
     _wait_exit_shielded(proc, deadline=deadline, clock=clock)
     # "exited" or "timeout": either way, fall through to the SIGKILL last-resort
@@ -574,6 +576,7 @@ def _terminate_agent(
     container_runtime: str | None,
     container_cidfile: Path | None,
     on_container_orphan_risk: Callable[[str, str | None, bool | None], None] | None,
+    reap_grace_s: int = REAP_GRACE_S,
 ) -> None:
     """Reap the agent pgroup (``_kill_pgroup``), then -- for a
     container-launching command only -- make a best-effort container `stop`
@@ -581,7 +584,7 @@ def _terminate_agent(
     hard-kill entry point ``run()`` uses for all three of its termination
     paths (R1128 wall-clock, grace-kill, and the BaseException reap), so the
     container handling isn't duplicated three times."""
-    _kill_pgroup(proc, clock)
+    _kill_pgroup(proc, clock, reap_grace_s=reap_grace_s)
     if container_runtime is not None:
         cid, stop_ok = _best_effort_container_stop(container_runtime, container_cidfile)
         if on_container_orphan_risk is not None:
@@ -606,10 +609,16 @@ def run(
     grace_kill_ignore_patterns: list[re.Pattern[str]] | None = None,
     on_container_orphan_risk: Callable[[str, str | None, bool | None], None] | None = None,
     clock: Clock = SYSTEM_CLOCK,
+    reap_grace_s: int = REAP_GRACE_S,
 ) -> RunResult:
     """Spawn the agent subprocess and wait for exit or timeout.
 
-    Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
+    Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → reap_grace_s → SIGKILL.
+
+    reap_grace_s: the SIGTERM->SIGKILL grace passed straight through to every
+    ``_terminate_agent`` call site below (R1128 wall-clock, grace-kill, and
+    the BaseException reap) -- one deadline value, threaded end to end.
+    Defaults to REAP_GRACE_S so every existing caller is unchanged.
 
     work_dir: the agent child's working directory; callers pass the
     already-absolute cfg.runtime.work_dir. CLIs with no --cwd flag of their
@@ -776,6 +785,7 @@ def run(
                     container_runtime=container_runtime,
                     container_cidfile=container_cidfile,
                     on_container_orphan_risk=_report_orphan_once,
+                    reap_grace_s=reap_grace_s,
                 )
                 duration = clock.monotonic() - start
                 exit_code = proc.returncode if proc.returncode is not None else -1
@@ -820,6 +830,7 @@ def run(
                             container_runtime=container_runtime,
                             container_cidfile=container_cidfile,
                             on_container_orphan_risk=_report_orphan_once,
+                            reap_grace_s=reap_grace_s,
                         )
                         duration = clock.monotonic() - start
                         exit_code = proc.returncode if proc.returncode is not None else -1
@@ -860,6 +871,7 @@ def run(
                 container_runtime=container_runtime,
                 container_cidfile=container_cidfile,
                 on_container_orphan_risk=_report_orphan_once,
+                reap_grace_s=reap_grace_s,
             )
         raise
     finally:

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/cli/_serve_round.py

@@ -362,10 +362,12 @@ def _maybe_defer_for_spawn_hooks(
 
 
 # Grace after TERMing a wedged round before killpg: the round's own SIGTERM handler
-# reaps its agent pgroup (agent_runtime.REAP_GRACE_S) then exits, so allow that plus
-# margin. test_spawn_round_wedged asserts it stays >= REAP_GRACE_S so the two never
-# drift. Single-sourced in _serve_policy (imported above) -- api.py imports the same
-# constant, so this and the out-of-process kill path can no longer drift apart.
+# reaps its agent pgroup -- up to agent_runtime.REAP_GRACE_S for a non-cooperative
+# agent, or up to the configured (boot-capped) config.models._MAX_SIGTERM_GRACE_S
+# for a cooperative one -- then exits, so allow that plus margin. test_spawn_round_wedged
+# asserts it stays > _MAX_SIGTERM_GRACE_S so the two never drift. Single-sourced in
+# _serve_policy (imported above) -- api.py imports the same constant, so this and the
+# out-of-process kill path can no longer drift apart.
 #
 # _ROUND_UNREAPED_RC (the D-state-leader sentinel returned below) is likewise
 # single-sourced in _serve_policy (imported above), not defined here.

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/cli/common.py

@@ -19,7 +19,7 @@ from agent_runner.hooks import plugin_context_enrichers, post_round_hooks, pre_r
 from agent_runner.monitor import plugin_detectors
 from agent_runner.vcs_state import plugin_owned_paths
 
-PEEK_SCHEMA_VERSION = "2.3"
+PEEK_SCHEMA_VERSION = "2.4"
 
 
 def cfg_from_args(args) -> Config:
@@ -98,7 +98,10 @@ def emit(value: Any, *, json_mode: bool, cfg: Config | None = None) -> None:
     if json_mode:
         if isinstance(value, ProjectState):
             from agent_runner import _sandbox_probe, disabled_plugin_names
-            from agent_runner._plugin_manifest import cooperative_manifest_names
+            from agent_runner._plugin_manifest import (
+                cooperative_manifest_names,
+                resolve_sigterm_grace_s,
+            )
 
             plugins_block = {
                 "event_kinds": plugin_event_kinds(),
@@ -112,6 +115,9 @@ def emit(value: Any, *, json_mode: bool, cfg: Config | None = None) -> None:
             }
             if cfg is not None:
                 plugins_block.update(_sandbox_probe.peek_snapshot(cfg))
+                plugins_block["resolved_sigterm_grace_s"] = resolve_sigterm_grace_s(
+                    cfg.agent.binary, cfg.agent.sigterm_grace_s
+                )
             wrapped = {
                 "schema_version": PEEK_SCHEMA_VERSION,
                 "plugins": plugins_block,

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/cli/doctor_cmd.py

@@ -17,6 +17,7 @@ class DoctorReport:
     plan: list[dict]
     sandbox: dict
     cgroup: dict
+    sigterm_grace: dict
 
 
 def add_parser(sub, parent) -> None:
@@ -65,12 +66,21 @@ def cmd_doctor(args) -> int:
     from agent_runner._sandbox_probe import doctor_snapshot
 
     cfg = cfg_from_args(args)
+    is_cooperative = _plugin_manifest.is_cooperative_agent(cfg.agent.binary)
+    sigterm_grace = {
+        "agent": cfg.agent.binary,
+        "cooperative": is_cooperative,
+        "resolved_s": _plugin_manifest.resolve_sigterm_grace_s(
+            cfg.agent.binary, cfg.agent.sigterm_grace_s
+        ),
+    }
     report = DoctorReport(
         checks=startup_check.run_battery(cfg),
         overlaps=phase_select.find_phase_window_overlaps(cfg),
         plan=_plan(cfg, args.rounds),
         sandbox=doctor_snapshot(cfg),
         cgroup=_cgroup_report(),
+        sigterm_grace=sigterm_grace,
     )
     json_mode = getattr(args, "json", False)
     if json_mode:
@@ -122,6 +132,11 @@ def _format(report: DoctorReport) -> str:
             lines.append(f'    {name} = "{digest}"')
     cooperative = _plugin_manifest.cooperative_manifest_names()
     lines.append(f"cooperative presets: {', '.join(sorted(cooperative)) or '(none)'}")
+    sg = report.sigterm_grace
+    lines.append(
+        f"sigterm grace: {sg['resolved_s']}s "
+        f"({'cooperative' if sg['cooperative'] else 'non-cooperative'}, agent={sg['agent']})"
+    )
     cgroup = report.cgroup
     lines.append("cgroup:")
     lines.append(f"  cgroup_path: {cgroup['cgroup_path']}")

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/cli/serve_cmd.py

@@ -598,6 +598,51 @@ def _apply_round_num_env(round_env: dict, round_num: int) -> None:
     round_env["AGENT_RUNNER_ROUND_NUM"] = str(round_num)
 
 
+def _resolve_reap_grace_by_phase(cfg) -> dict[str | None, int]:
+    """Precompute this serve lifetime's per-phase SIGTERM grace ONCE --
+    boot-invariant like cgroup_probe_defer/overlaps below (for a fixed
+    phase_arg, resolve_sigterm_grace_s depends only on the per-phase-static
+    agent binary + sigterm_grace_s + the once-populated plugin-manifest
+    registry), so _apply_reap_grace_env does a single dict lookup per round
+    instead of re-resolving from scratch. Keyed by the finite known
+    phase_arg set: None (base) plus every configured [phases.<name>]
+    override."""
+    from agent_runner._plugin_manifest import resolve_sigterm_grace_s
+
+    phase_args: list[str | None] = [None, *cfg.phases.overrides.keys()]
+    return {
+        phase_arg: resolve_sigterm_grace_s(
+            cfg.profile_for(phase_arg).agent.binary,
+            cfg.profile_for(phase_arg).agent.sigterm_grace_s,
+        )
+        for phase_arg in phase_args
+    }
+
+
+def _apply_reap_grace_env(
+    cfg, round_env: dict, phase_arg: str | None, grace_by_phase: dict[str | None, int]
+) -> None:
+    """Publish this round's agent's SIGTERM grace via
+    AGENT_RUNNER_REAP_GRACE_S -- the same single-source-from-serve pattern
+    AGENT_RUNNER_ROUND_NUM uses, so the round child's grace can't skew from
+    the phase serve actually selected this round (see
+    _plugin_manifest.resolve_sigterm_grace_s for the decision itself). The
+    grace is looked up in `grace_by_phase` (precomputed once per serve
+    lifetime by _resolve_reap_grace_by_phase) rather than re-resolved here --
+    but the env write itself stays UNCONDITIONAL every round, so a
+    cooperative<->non-cooperative phase transition still overwrites the
+    previous round's value."""
+    from agent_runner._plugin_manifest import resolve_sigterm_grace_s
+
+    grace = grace_by_phase.get(phase_arg)
+    if grace is None:
+        # Defensive only -- every phase_arg serve can select is one of the
+        # keys _resolve_reap_grace_by_phase precomputed from this same cfg.
+        agent = cfg.profile_for(phase_arg).agent
+        grace = resolve_sigterm_grace_s(agent.binary, agent.sigterm_grace_s)
+    round_env["AGENT_RUNNER_REAP_GRACE_S"] = str(grace)
+
+
 def _capture_substrate(work_dir, cfg, log_dir, round_num, *, when):
     """Snapshot git-head + paths-hash and emit the round-substrate event for `when`."""
     git_head = compute_git_head(work_dir)
@@ -689,6 +734,9 @@ def cmd(args) -> int:
     # 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.
     overlaps = phase_select.find_phase_window_overlaps(cfg)
+    # Boot-invariant per-phase SIGTERM grace -- resolved once here, looked up
+    # (not re-resolved) every round by _apply_reap_grace_env below.
+    grace_by_phase = _resolve_reap_grace_by_phase(cfg)
     if overlaps:
         detail = phase_select.describe_overlaps(overlaps)
         _release_serve_lock(serve_lock_fd)
@@ -756,6 +804,7 @@ def cmd(args) -> int:
             _capture_substrate(work_dir, cfg, log_dir, round_num, when="before")
             _apply_fresh_eyes(cfg, log_dir, round_num, round_env)
             _apply_round_num_env(round_env, round_num)
+            _apply_reap_grace_env(cfg, round_env, phase_arg, grace_by_phase)
             round_log_path = log_dir / f"round-{round_num}.log"
             round_started = SYSTEM_CLOCK.monotonic()
             round_argv = [

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/config/models.py

@@ -28,6 +28,24 @@ _VALID_PROMPT_DELIVERY: frozenset[str] = frozenset({"argv", "stdin"})
 # this literal but is decoupled to avoid an agent_runtime -> config import.
 DEFAULT_TERMINAL_MARKER = '"type":"result"'
 
+# Default [agent] sigterm_grace_s: the SIGTERM->SIGKILL grace a cooperative
+# agent's preset gets from the round leader (see AgentConfig.sigterm_grace_s).
+DEFAULT_SIGTERM_GRACE_S = 10
+
+# Ceiling for [agent] sigterm_grace_s: sits a STRICT ~3s BELOW _serve_policy's
+# _ROUND_TERM_GRACE_S (15, the supervisor's own wait for the round leader) --
+# NOT equal to it. The margin matters on the out-of-process `agent-runner kill`
+# path (_lifecycle._terminate_round_pid), which SIGKILLs only the leader pid
+# with no stray-reap: without it, a leader whose own killpg(SIGKILL) of its
+# agent fires at the same instant the supervisor SIGKILLs the leader could lose
+# the race, leaving the agent permanently orphaned. config/ cannot import
+# _serve_policy (a cycle: _serve_policy already imports agent_runner.config for
+# ConfigError), so this is a LITERAL mirror-with-margin, pinned by
+# tests/invariants/test_timeout_budget_invariant.py against drift, the same
+# pattern _serve_policy uses for its own agent_runtime.REAP_GRACE_S /
+# vcs_state.GIT_COMMIT_TIMEOUT_S mirrors.
+_MAX_SIGTERM_GRACE_S = 12
+
 
 @dataclass(frozen=True)
 class AgentConfig:
@@ -42,6 +60,14 @@ class AgentConfig:
     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)."""
+    sigterm_grace_s: int = DEFAULT_SIGTERM_GRACE_S
+    """The SIGTERM->SIGKILL grace this round's leader gives its agent, applied
+    only when the agent's preset declares itself cooperative (sigterm_cooperative
+    on its PluginManifest) -- a non-cooperative agent always gets the fixed
+    agent_runtime.REAP_GRACE_S instead. Capped at _MAX_SIGTERM_GRACE_S, which sits
+    strictly inside (not equal to) _serve_policy._ROUND_TERM_GRACE_S, the
+    supervisor's own wait for the round leader -- a value above the cap is
+    rejected at boot, not clamped."""
 
     @property
     def binary(self) -> str | None:

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/config/parsers.py

@@ -22,6 +22,7 @@ from agent_runner.config.models import (
     _HOST_HEALTH_DISK_ALLOWED_FIELDS,
     _HOST_HEALTH_MEMORY_ALLOWED_FIELDS,
     _HOST_HEALTH_PRESSURE_ALLOWED_FIELDS,
+    _MAX_SIGTERM_GRACE_S,
     _MONITOR_ALLOWED_FIELDS,
     _MONITOR_HOST_HEALTH_ALLOWED_FIELDS,
     _PHASE_OVERRIDE_ALLOWED_FIELDS,
@@ -36,6 +37,7 @@ from agent_runner.config.models import (
     _VALID_SANDBOX_MODES,
     _VALID_TRANSIENT_ERROR_ACTIONS,
     _VCS_ALLOWED_FIELDS,
+    DEFAULT_SIGTERM_GRACE_S,
     DEFAULT_TERMINAL_MARKER,
     AgentConfig,
     MonitorConfig,
@@ -67,6 +69,23 @@ from agent_runner.config.validators import (
 )
 
 
+def _validate_sigterm_grace_s(value: Any, *, field: str) -> int:
+    """Validate [agent] sigterm_grace_s (or a per-phase override): positive
+    int, capped at _MAX_SIGTERM_GRACE_S -- a value strictly inside (not equal
+    to) the supervisor's own wait for the round leader, preserving leader-exit
+    margin. Mirrors _validate_remote_failure_tolerance's require-then-cap
+    shape; `field` is threaded through (unlike that single-call-site
+    validator) since this one validates both the base [agent] table and each
+    [phases.<name>.agent] override, under different prefixes."""
+    v = _require_positive_int(value, field=field)
+    if v > _MAX_SIGTERM_GRACE_S:
+        raise ConfigError(
+            f"{field}: must be <= {_MAX_SIGTERM_GRACE_S} "
+            f"(strictly inside the supervisor's own wait for the round leader), got {v}"
+        )
+    return v
+
+
 def _parse_agent(
     agent_d: dict, *, field_prefix: str, require_prompt_placeholder: bool = True
 ) -> AgentConfig:
@@ -119,6 +138,10 @@ def _parse_agent(
         agent_d.get("exec_prefix", []), field=f"{field_prefix} exec_prefix"
     )
     terminal_marker = str(agent_d.get("terminal_marker", DEFAULT_TERMINAL_MARKER))
+    sigterm_grace_s = _validate_sigterm_grace_s(
+        agent_d.get("sigterm_grace_s", DEFAULT_SIGTERM_GRACE_S),
+        field=f"{field_prefix} sigterm_grace_s",
+    )
     return AgentConfig(
         command=command,
         prompt_arg_template=prompt_arg_template,
@@ -127,6 +150,7 @@ def _parse_agent(
         prompt_delivery=prompt_delivery,  # type: ignore[arg-type]  # narrowed above
         exec_prefix=exec_prefix,
         terminal_marker=terminal_marker,
+        sigterm_grace_s=sigterm_grace_s,
     )
 
 

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/agent_runner/runner.py

@@ -190,6 +190,29 @@ def _resolve_round_num(log_dir: Path) -> int:
     return next_round_num(log_dir)
 
 
+def _resolve_reap_grace_s() -> int:
+    """The SIGTERM->SIGKILL grace this round's agent gets, published by serve
+    via AGENT_RUNNER_REAP_GRACE_S (cli/serve_cmd.py's _apply_reap_grace_env)
+    so the child never re-derives (and skews) serve's own cooperative-manifest
+    resolution; a standalone `agent-runner round` (no env) falls back to
+    agent_runtime.REAP_GRACE_S -- the same non-cooperative default -- when the
+    env var is absent, unparseable, or non-positive (a leaked <=0 value would
+    make a past deadline and kill with zero grace; serve only ever publishes a
+    boot-validated positive value or REAP_GRACE_S, so this only guards a
+    hand-set/leaked standalone env)."""
+    from agent_runner.agent_runtime import REAP_GRACE_S
+
+    raw = os.environ.get("AGENT_RUNNER_REAP_GRACE_S")
+    if raw is not None:
+        try:
+            parsed = int(raw)
+        except ValueError:
+            parsed = None
+        if parsed is not None and parsed > 0:
+            return parsed
+    return REAP_GRACE_S
+
+
 def _previous_block(prev: context_store.Status | None, dirty_last: bool) -> dict[str, Any] | None:
     if prev is None:
         return None
@@ -573,6 +596,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         on_grace_extended=_grace_extended_emit,
         grace_kill_ignore_patterns=grace_kill_ignore_patterns,
         on_container_orphan_risk=_container_orphan_risk_emit,
+        reap_grace_s=_resolve_reap_grace_s(),
     )
     events.emit(
         log_dir,

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/docs/commands.md

@@ -294,7 +294,7 @@ The transforms `migrate` applies (generated from the registry):
 - unknown [schedule] key(s) rejected in 0.2.12; delete them (allowed: ['pause_windows', 'run_windows', 'timezone'])
 - monitor.anomaly_repetitive_threshold > anomaly_repetitive_window: lower the threshold or raise the window so the detector can fire
 - [<table>] given as a scalar, not a table; give it real [table] content (no auto-fix possible)
-- unknown [agent] key(s) rejected in 0.2.13; delete them (allowed: ['command', 'env', 'exec_prefix', 'name', 'prompt_arg_template', 'prompt_delivery', 'terminal_marker'])
+- unknown [agent] key(s) rejected in 0.2.13; delete them (allowed: ['command', 'env', 'exec_prefix', 'name', 'prompt_arg_template', 'prompt_delivery', 'sigterm_grace_s', 'terminal_marker'])
 - unknown [runtime] key(s) rejected in 0.2.13; delete them (allowed: ['disable_pre_round_hooks', 'dry_run', 'fresh_eyes_every_n', 'grace_kill_ignore_patterns', 'log_dir', 'max_grace_after_result_s', 'max_rounds', 'narrative_file', 'restart_delay_s', 'round_budget_s', 'round_log_retention', 'stop_file', 'substrate_fingerprint_paths', 'transient_error_action', 'work_dir'])
 - unknown [vcs] key(s) rejected in 0.2.13; delete them (allowed: ['dirty_action', 'stash_idempotency_s'])
 - unknown [monitor] key(s) rejected in 0.2.13; delete them (allowed: ['anomaly_repetitive_threshold', 'anomaly_repetitive_window', 'auth_fail_hint', 'auth_fail_patterns', 'auto_stop_on', 'host_health', 'remote_failure_tolerance_s', 'round_progress_interval_s', 'supervisor_stale_threshold_s'])

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/docs/configuration.md

@@ -32,6 +32,7 @@ running with newly-set `dirty_action = "auto_commit"` is undefined).
 | `prompt_delivery` | `Literal['argv', 'stdin']` | 'argv' |
 | `exec_prefix` | `list[str]` | [] |
 | `terminal_marker` | `str` | '"type":"result"' |
+| `sigterm_grace_s` | `int` | 10 |
 
 ### `[runtime]`
 
@@ -184,6 +185,20 @@ grace-kill never engages and a round runs to the wall-clock
 `round_budget_s` ceiling instead. An empty string disables the marker scan
 outright — an honest opt-out, not an empty-string-matches-everything trap.
 
+### `agent.sigterm_grace_s` (0.3.5+)
+
+Type: int, default `10`, max `12`
+
+The SIGTERM→SIGKILL grace the round leader gives ITS AGENT — but only when
+the configured agent's preset declares `sigterm_cooperative = true` (the
+built-in `gemini` preset does; see `peek --json`'s `plugins.sigterm_cooperative`
+or `doctor`'s "cooperative presets" line). A non-cooperative agent (e.g.
+`claude`) always gets the fixed 5s grace regardless of this setting. Capped
+at 12 — 3 s inside the supervisor's own 15 s wait for the round
+(`_ROUND_TERM_GRACE_S`) — a config above that is rejected at boot, not
+silently clamped: a grace longer than the supervisor waits for the leader
+would let the supervisor SIGKILL the leader mid-wrap-up, defeating the point.
+
 ### `runtime.round_log_retention`
 
 **Pruning is opt-in. `0` — the default — never prunes anything.** Round logs

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/docs/memory-efficiency.md

@@ -473,6 +473,29 @@ The decision RULES are byte-identical: none of this changes the inputs→verdict
 
 Numbers are dev-host-relative (the macOS `kqueue` harness). The Linux `pidfd` fast path is exercised only on CI (ubuntu runners); the real 462 MB / 256 MB constrained-host wake-latency and `pidfd`/`kqueue`-under-swap-pressure confirmation stays deferred to 0.3.5 while that host is offline — measured on dev/CI, documented as deferred for the constrained host, never reported as zero-cost.
 
+## 0.3.4 → 0.3.5 (2026-09-15)
+
+"Cooperative wrap-up grace": a configurable, manifest-gated SIGTERM→SIGKILL grace threaded to the round leader's actual reap deadline (a cooperative agent like `gemini` gets `[agent] sigterm_grace_s`, default 10 s; `claude` keeps 5 s). Same macOS harness. <!-- authored: default sigterm_grace_s / REAP_GRACE_S; SSOT agent_runner/config/models.py, agent_runner/agent_runtime.py -->
+
+### 1. Import/startup RSS
+
+| | 0.3.4 | 0.3.5 | Δ |
+|---|---|---|---|
+| RSS (avg of 5 cold runs) | 24.0 MB | 24.1 MB | ~0 MB (flat, within noise) |
+| RSS range | 23.95–24.12 MB | 23.91–24.25 MB | |
+
+Flat: the change is a config field, a pure grace-resolution function, an env round-trip, and two observability fields — no new module on the cold-startup graph, no new dependency (base stays `psutil>=5.9`). `test_import_footprint.py` + `test_round_alloc_growth.py` green.
+
+### 2. Efficiency
+
+No new internal wait — the grace window rides the v0.3.4 `wait_exit` deadline (zero polling during the grace), so a 12 s cooperative grace costs zero wakeups, same as the old 5 s. Two structural wins rather than a headline number:
+- **One grace code path, not two.** The reap deadline is now a single threaded value (defaulting to `REAP_GRACE_S`) instead of a hardcoded constant plus a would-be cooperative branch — the branch was never created, closing the v0.3.3 dark-code shape at the source.
+- **No wasted force-kills.** A cooperative agent that finishes flushing within its grace is reaped normally instead of SIGKILLed mid-write — work that the old fixed 5 s could truncate now completes. The behavioral efficiency win, measured by the wall-clock PROPERTY test (`test_cooperative_grace_property.py`), not RSS.
+
+### 3. Constrained-host (honesty)
+
+Dev-host-relative (macOS). The grace's real value shows on the constrained fleet (a `gemini` round flushing under memory pressure before an early-SIGTERM nudge) — that nudge is the 462 MB-constrained-host-gated v0.3.7 work; this release ships only the correct, configurable grace it will use. No new constrained-host claim.
+
 ## Enforcement
 
 Four invariant tests keep these numbers from drifting silently:

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/docs/plugins.md

@@ -188,7 +188,7 @@ The round itself continues — a broken plugin must not crash the supervisor.
 
 ```json
 {
-  "schema_version": "2.3",
+  "schema_version": "2.4",
   "plugins": {
     "event_kinds": [...],
     "context_enrichers": ["current_branch"],
@@ -550,7 +550,7 @@ detector. Other plugin detectors and all builtins still run normally.
 
 ```json
 {
-  "schema_version": "2.3",
+  "schema_version": "2.4",
   "plugins": {
     "event_kinds": [...],
     "context_enrichers": [...],

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.5}/tests/integration/test_auto_stop_e2e.py

@@ -221,7 +221,15 @@ def test_kill_should_reap_round_and_agent_pgroup_when_using_holder_sidecar(
 
         assert result.active is False
         round_proc.wait(timeout=20)  # own child: an OS condition, not an event
-        assert not pid_alive(agent_pid[0]), "the round's agent was orphaned by kill()"
+        # Poll, don't assert-immediately: the agent (a grandchild reparented to
+        # init once the leader is reaped) is SIGKILLed by the holder-sidecar reap,
+        # but init reaps its zombie asynchronously -- a sub-30ms window where
+        # pid_alive() still reads the reaping pid as alive (surfaced as a flake
+        # only under CI load). A genuinely orphaned agent rides out its lifetime,
+        # so this poll fails after the timeout for the real bug.
+        assert poll_until(lambda: not pid_alive(agent_pid[0]), timeout_s=10), (
+            "the round's agent was orphaned by kill()"
+        )
         assert serve_stub.poll() is not None  # the serve stand-in was reaped too
     finally:
         for p in (round_proc, serve_stub):