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

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.6}/.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.6}/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.6] - 2026-09-15
+
+### Changed
+- `agent-runner kill` now reaps a stuck round's detached descendants (a child that `setsid()`'d off its process group) the same way `serve stop` already does, so a forced stop never leaves an orphan behind.
+- A stop (`SIGTERM` / `serve stop`) during a sandboxed third-party spawn hook, or during a plugin-requested `defer`, now takes effect immediately instead of after up to 30 s — and the confined hook's child process is always reaped, never left running. A background process the hook itself forks is not reaped; its abandoned output pipe is dropped after a bounded 2 s drain wait (on a normal hook exit, surfaced as `hook_failed`) rather than stalling the stop.
+
+## [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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.4
+Version: 0.3.6
 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.6}/agent_runner/_lifecycle.py

@@ -181,17 +181,26 @@ def _terminate_round_pid(pid: int) -> None:
     """TERM-first -> grace -> SIGKILL a bare round-child pid.
 
     Mirrors ``serve_cmd._terminate_round``'s shape, but this runs from a
-    SEPARATE CLI process (``kill()``) that only has the pid — not serve's own
+    SEPARATE CLI process (``kill()``) that only has the pid -- not serve's own
     ``Popen`` handle. Never ``killpg``: the round is ``start_new_session=True``,
-    so its own pgid holds only itself, and even a killpg on it cannot reach the
-    agent (itself a separate session again, ``agent_runtime.py``) — only the
-    round's own SIGTERM -> KeyboardInterrupt handler (``round_cmd.py``) walks
-    that link and reaps the agent pgroup via ``_kill_pgroup``. A plain SIGTERM
-    here fires exactly that handler; SIGKILL is only the last-resort escalation
-    for a round that doesn't even get to run its handler."""
+    so a plain SIGTERM here fires the round's own SIGTERM -> KeyboardInterrupt
+    handler (``round_cmd.py``), which walks the link to the agent pgroup and
+    reaps it via ``_kill_pgroup`` (itself snapshotting and reaping any stray).
+    SIGKILL is only the last-resort escalation for a round that never even runs
+    its handler -- and on THAT path the leader's own cooperative reap never
+    happened, so we snapshot the leader's descendants up front (while the leader
+    subtree is still resolvable) via a bare-pid shim and reap the strays here:
+    a descendant that ``setsid()``'d off the leader's pgroup would otherwise
+    survive the leader's death, orphaned. Symmetric with ``serve stop``."""
+    import types
+
+    from agent_runner import agent_runtime
+
+    stray = agent_runtime._snapshot_stray_descendants(types.SimpleNamespace(pid=pid))
     send_signal_to_pid(pid, signal.SIGTERM)
     if _await_pid_exit(pid, _ROUND_TERM_GRACE_S):
         send_signal_to_pid(pid, signal.SIGKILL)
+        agent_runtime._kill_stray_descendants(stray)
 
 
 def stop(project: str | Path) -> ServiceStatus:

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.6}/agent_runner/_notify.py

@@ -78,11 +78,14 @@ def drain(fd: int) -> None:
     ``select()`` on it instantly ready -- an undrained fd busy-spins its
     caller at 100% CPU forever after the first wake, since a level-triggered
     fd stays readable until read. Advisory: the bytes carry no payload and are
-    discarded. Used only by :meth:`Listener.wait` (its own timeout branch) --
-    the pause/sleep waits (``_interruptible_sleep``/``_pause_poll``) are the
-    sole consumers of a live ``Listener``. Nothing watches this fd mid-round
-    (``_spawn_round`` only ever waits on the round leader's own exit fd), so
-    there is no other caller that must drain it itself.
+    discarded. Two callers: :meth:`Listener.wait` self-drains its own fd on the
+    wake branch (the pause/sleep waits ``_interruptible_sleep``/``_pause_poll``
+    are the consumers of a live ``Listener``); and the sandboxed-hook trampoline
+    (``_plugin_sandbox._run_child_process``, P3) drains the CALLER-OWNED wake fd
+    it was handed on the ``"woken"`` branch of its exit wait, before re-checking
+    ``should_stop()`` -- that fd is the serve listener's, watched by
+    ``wait_exit`` for the duration of the hook, so the trampoline must drain it
+    itself rather than leave the next wait instantly ready.
     """
     while True:
         try:
@@ -179,7 +182,13 @@ class Listener:
         """
         deadline = clock.monotonic() + timeout_s
         remaining = max(0.0, deadline - clock.monotonic())
-        ready, _, _ = select.select([self.fd], [], [], remaining)
+        try:
+            ready, _, _ = select.select([self.fd], [], [], remaining)
+        except ValueError:
+            # fd >= FD_SETSIZE (1024) makes select.select raise ValueError --
+            # degrade to a plain timed sleep instead of crashing.
+            clock.sleep(remaining)
+            return False
         if not ready:
             return False
 

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.6}/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.6}/agent_runner/_plugin_sandbox.py

@@ -17,12 +17,15 @@ from __future__ import annotations
 import json
 import subprocess
 import sys
+from collections.abc import Callable
 from pathlib import Path
 from typing import Literal
 
-from agent_runner import hooks
+from agent_runner import _notify, hooks
+from agent_runner._procwait import wait_exit
 from agent_runner._registry import resolve_entry_target
 from agent_runner.api_types import DirtyOutcome, SpawnDecision
+from agent_runner.clock import SYSTEM_CLOCK
 
 _TRAMPOLINE_TIMEOUT_S = 30.0  # wall-clock; not config-tunable this release
 _MAX_WIRE_BYTES = 64 * 1024
@@ -30,6 +33,17 @@ _MAX_STDERR_BYTES = 8 * 1024  # hard read cap; a runaway child can't OOM the sup
 _REF_CAP = 256
 _STDERR_CAP = 512
 
+# Total wall budget for draining a confined child's pipes AFTER it is reaped. A
+# process the hook itself fork()'d inherits the child's stdout/stderr and can hold
+# them open past the child's own death, so the drain join is BOUNDED, not
+# unbounded -- otherwise a single such pipe-holder stalls the stop forever. The
+# pair of joins shares ONE absolute deadline (not _DRAIN_JOIN_S each), and
+# _DRAIN_JOIN_S + 3 <= _lifecycle._PID_SIGNAL_GRACE_S leaves >=3 s of the
+# stop-confirm window for the rest of the unwind (pinned by
+# tests/invariants/test_timeout_budget_invariant.py; a literal mirror -- this
+# module must never import _lifecycle in production).
+_DRAIN_JOIN_S = 2
+
 # The child's environment is built default-DENY from this allowlist -- NOT copied
 # from the parent's, which holds the real agent secrets (ANTHROPIC_*, and every
 # *_API_KEY/*_TOKEN/*_SECRET agent_runtime injects). A confined plugin is Python
@@ -126,6 +140,13 @@ def _ctx_from_wire(data: dict) -> hooks.HookContext:
 # ---------------------------------------------------------------------------
 
 
+class SpawnHookInterrupted(Exception):  # noqa: N818 -- a control-flow signal, not an error
+    """Raised by ``_run_child_process`` when ``should_stop()`` fires on a wake
+    during a sandboxed spawn hook -- distinct from a plugin failure so the seam
+    returns ``None`` WITHOUT emitting ``hook_failed`` (a stop is not the plugin's
+    fault). Never raised on the dirty round path, which passes no ``wake_fd``."""
+
+
 def run_hook_sandboxed(
     hook_kind: Literal["spawn_hook", "dirty_handler"],
     module_path: str,
@@ -137,6 +158,8 @@ def run_hook_sandboxed(
     dirty_files: list[str] | None = None,
     view: hooks.SpawnView | None = None,
     timeout_s: float = _TRAMPOLINE_TIMEOUT_S,
+    wake_fd: int | None = None,
+    should_stop: Callable[[], bool] | None = None,
 ) -> SpawnDecision | DirtyOutcome | None:
     """Launch the confinement child for one third-party hook call and return its
     validated outcome. ``module_path``/``attr_path`` locate the plugin the child
@@ -172,6 +195,8 @@ def run_hook_sandboxed(
         ],
         json.dumps(payload).encode("utf-8"),
         timeout_s,
+        wake_fd=wake_fd,
+        should_stop=should_stop,
     )
     if returncode < 0:
         from agent_runner.api import emit_plugin_sandbox_kill
@@ -224,14 +249,50 @@ def _drain_capped(stream, cap: int, out: list[bytes]) -> None:
         out.append(bytes(data))
 
 
+def _join_drain_threads(threads: tuple, budget_s: float) -> bool:
+    """Join the drain threads under ONE absolute deadline -- the whole set is
+    bounded by ``budget_s``, NOT ``budget_s`` each -- so a process the hook
+    ``fork()``'d that still holds the reaped child's output pipe open cannot stall
+    the join past ``budget_s``. Returns True iff every thread finished draining
+    within the budget (the normal-exit path raises on False; the ``BaseException``
+    cleanup path ignores it, since it is already unwinding)."""
+    join_deadline = SYSTEM_CLOCK.monotonic() + budget_s
+    for t in threads:
+        t.join(max(0.0, join_deadline - SYSTEM_CLOCK.monotonic()))
+    return not any(t.is_alive() for t in threads)
+
+
 def _run_child_process(
-    argv: list[str], stdin_bytes: bytes, timeout_s: float
+    argv: list[str],
+    stdin_bytes: bytes,
+    timeout_s: float,
+    *,
+    wake_fd: int | None = None,
+    should_stop: Callable[[], bool] | None = None,
 ) -> tuple[int, bytes, bytes]:
     """Spawn the confined child with the minimal env and read BOUNDED stdout/stderr
     concurrently (a thread per stream), so a plugin printing without limit within
     the wall-timeout cannot exhaust supervisor memory. Concurrent draining also
-    avoids a full-pipe deadlock. On timeout the child is killed and
-    ``TimeoutExpired`` propagates (the caller isolates it as ``hook_failed``)."""
+    avoids a full-pipe deadlock.
+
+    The exit wait is the fd-driven ``_procwait.wait_exit`` (not a sleep-poll):
+    ``"exited"`` reaps and returns; ``"timeout"`` kills and raises
+    ``TimeoutExpired`` (the caller isolates it as ``hook_failed``); ``"woken"``
+    (only when ``wake_fd`` is set) drains the advisory byte and, if
+    ``should_stop()`` is now true, kills the child and raises
+    ``SpawnHookInterrupted`` -- otherwise a stray ring re-enters the wait on the
+    SAME ABSOLUTE deadline so it never shortens the hook's budget. The whole wait
+    is wrapped so the confined child NEVER outlives its parent: any BaseException
+    (a round ``KeyboardInterrupt``, a timeout, an interrupt) kills and reaps the
+    child before propagating.
+
+    A process the hook itself ``fork()``s is NOT reaped (that child has no process
+    group of its own -- see the Option-B follow-up), and it can inherit and hold
+    the child's stdout/stderr open past the child's own death; so the drain joins
+    are BOUNDED (``_DRAIN_JOIN_S``, one absolute deadline across the pair) at BOTH
+    the normal-exit tail and the ``BaseException`` cleanup -- such a pipe-holder can
+    never stall the parent. On the normal path a timed-out drain surfaces as a
+    ``RuntimeError`` the seam isolates as ``hook_failed``."""
     import threading
 
     proc = subprocess.Popen(
@@ -243,9 +304,17 @@ def _run_child_process(
     )
     out_box: list[bytes] = []
     err_box: list[bytes] = []
-    # +1 so an over-cap stdout stays over the limit and _parse_dirty_stdout rejects it.
-    t_out = threading.Thread(target=_drain_capped, args=(proc.stdout, _MAX_WIRE_BYTES + 1, out_box))
-    t_err = threading.Thread(target=_drain_capped, args=(proc.stderr, _MAX_STDERR_BYTES, err_box))
+    # daemon=True is load-bearing, not cosmetic: nothing in agent_runner/ calls
+    # os._exit, so a non-daemon drain thread still blocked on a fork()'d
+    # pipe-holder's read() would be joined by threading._shutdown() at interpreter
+    # exit and re-hang the stop the bounded join below just rescued. Matches the
+    # repo's other pump threads (remote_relay._pump, agent_runtime._write_stdin).
+    t_out = threading.Thread(
+        target=_drain_capped, args=(proc.stdout, _MAX_WIRE_BYTES + 1, out_box), daemon=True
+    )
+    t_err = threading.Thread(
+        target=_drain_capped, args=(proc.stderr, _MAX_STDERR_BYTES, err_box), daemon=True
+    )
     t_out.start()
     t_err.start()
     try:
@@ -255,15 +324,26 @@ def _run_child_process(
             pass
         finally:
             proc.stdin.close()
-        proc.wait(timeout=timeout_s)
-    except subprocess.TimeoutExpired:
+        deadline = SYSTEM_CLOCK.monotonic() + timeout_s
+        while True:
+            outcome = wait_exit(proc, deadline=deadline, wake_fd=wake_fd)
+            if outcome == "exited":
+                proc.wait()
+                break
+            if outcome == "timeout":
+                raise subprocess.TimeoutExpired(proc.args, timeout_s)
+            _notify.drain(wake_fd)
+            if should_stop is not None and should_stop():
+                raise SpawnHookInterrupted(f"spawn hook interrupted for {argv[0]!r}")
+    except BaseException:
         proc.kill()
         proc.wait()
-        t_out.join()
-        t_err.join()
+        _join_drain_threads((t_out, t_err), _DRAIN_JOIN_S)
         raise
-    t_out.join()
-    t_err.join()
+    if not _join_drain_threads((t_out, t_err), _DRAIN_JOIN_S):
+        raise RuntimeError(
+            "drain timed out: a process the hook forked still holds its output pipe (not reaped)"
+        )
     return proc.returncode, out_box[0], err_box[0]
 
 

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.6}/agent_runner/_procwait.py

@@ -96,12 +96,13 @@ def wait_exit(
     *,
     deadline: float,
     clock: Clock = SYSTEM_CLOCK,
-) -> Literal["exited", "timeout"]:
-    """Block until ``proc`` exits or ``deadline`` (a ``clock.monotonic()``
-    timestamp) is reached, whichever is soonest. Never calls
-    ``os.waitpid``/``proc.wait``/``proc.poll`` on the fast path -- a caller
-    that gets back ``"exited"`` must reap ``proc`` itself right after this
-    returns (see the module docstring).
+    wake_fd: int | None = None,
+) -> Literal["exited", "timeout", "woken"]:
+    """Block until ``proc`` exits, ``deadline`` (a ``clock.monotonic()``
+    timestamp) is reached, or ``wake_fd`` becomes readable -- whichever is
+    soonest. Never calls ``os.waitpid``/``proc.wait``/``proc.poll`` on the
+    fast path -- a caller that gets back ``"exited"`` must reap ``proc``
+    itself right after this returns (see the module docstring).
 
     Opens and closes its own ``exit_fd(proc)`` registration internally, once
     per call, in a single ``select.select`` -- callers invoke this at most
@@ -110,16 +111,27 @@ def wait_exit(
     across calls.
 
     Returns ``"exited"`` (the caller should immediately reap, e.g.
-    ``proc.wait()``) or ``"timeout"`` (deadline reached, proc still running,
-    caller re-evaluates its own logic). When ``proc`` has already exited by
-    the time ``deadline`` is reached, the exit fd is ready in the SAME
-    ``select`` call that also times out -- the exit always wins that tie, so
-    an already-dead proc is never mistakenly reported as ``"timeout"``.
+    ``proc.wait()``), ``"timeout"`` (deadline reached, proc still running,
+    caller re-evaluates its own logic), or ``"woken"`` (only possible when
+    ``wake_fd`` is given: it became readable before either of the other two).
+    When ``proc`` has already exited by the time ``deadline`` is reached, the
+    exit fd is ready in the SAME ``select`` call that also times out -- the
+    exit always wins that tie, so an already-dead proc is never mistakenly
+    reported as ``"timeout"``. Likewise, when both the exit fd and
+    ``wake_fd`` are ready in the same ``select`` call, the exit fd wins --
+    an already-dead proc is never mistakenly reported as ``"woken"``.
+    ``wake_fd`` is caller-owned: this function neither opens, closes, nor
+    drains it (the caller drains it after a ``"woken"`` return); ``_procwait``
+    never imports ``_notify``.
 
     Fallback (``exit_fd(proc)`` is ``None``): polls ``proc.poll()`` at a
     short, fixed cadence via ``clock.sleep``, with the same two return
-    meanings, so a test driving this path with a fake clock still makes
-    progress without blocking on real wall time.
+    meanings (``wake_fd`` is IGNORED on this path -- a documented latency
+    degrade, not a "woken" report), so a test driving this path with a fake
+    clock still makes progress without blocking on real wall time. The same
+    poll fallback is also used when the fast path's ``select.select`` raises
+    ``ValueError`` (a fd >= ``FD_SETSIZE``, 1024, is unselectable) instead of
+    crashing.
 
     Short-circuits to ``"exited"`` when ``proc.returncode`` is already set:
     this owner has already reaped it, so its pid is freed (and may be reused).
@@ -139,8 +151,19 @@ def wait_exit(
 
     try:
         remaining = max(0.0, deadline - clock.monotonic())
-        ready, _, _ = select.select([fd], [], [], remaining)
-        return "exited" if ready else "timeout"
+        rlist = [fd, wake_fd] if wake_fd is not None else [fd]
+        try:
+            ready, _, _ = select.select(rlist, [], [], remaining)
+        except ValueError:
+            # fd >= FD_SETSIZE (1024) makes select.select raise ValueError --
+            # degrade to the poll fallback (its documented latency) instead
+            # of crashing.
+            return _wait_exit_by_polling(proc, deadline=deadline, clock=clock)
+        if fd in ready:
+            return "exited"
+        if ready:
+            return "woken"
+        return "timeout"
     finally:
         os.close(fd)
 

{cli_agent_runner-0.3.4 → cli_agent_runner-0.3.6}/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.6}/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.6'
+__version_tuple__ = version_tuple = (0, 3, 6)
 
 __commit_id__ = commit_id = None

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

@@ -141,7 +141,7 @@ def _snapshot_stray_descendants(proc: subprocess.Popen) -> list[dict]:
     while the leader (and hence its subtree) is still alive -- both reap sites
     (``_kill_pgroup`` and ``cli/_serve_round._terminate_round``) open with it, so
     the capture-before-signal ordering lives in ONE place, not copy-pasted."""
-    stray, _ignored = _live_children(proc)
+    stray, _ignored = _live_children(proc, max_n=None)
     _capture_descendant_pgids(stray)
     return stray
 
@@ -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
@@ -204,7 +206,7 @@ def _live_children(
     proc: subprocess.Popen,
     *,
     ignore_patterns: list[re.Pattern[str]] | None = None,
-    max_n: int = 5,
+    max_n: int | None = 5,
 ) -> tuple[list[dict], list[dict]]:
     """Live (non-zombie) descendants of ``proc``, split into ``(live, ignored)``.
 
@@ -215,6 +217,12 @@ def _live_children(
     events-*.jsonl. Ignore-pattern MATCHING runs against the full cmdline
     (detection unchanged); only what we STORE is minimized.
 
+    ``max_n`` (default 5) bounds only the event-persisted lists this returns
+    to a caller that writes them to events-*.jsonl. The reap snapshot
+    (``_snapshot_stray_descendants``) passes ``max_n=None`` — a real subtree
+    can exceed 5 live descendants, and undercounting it here would leave the
+    excess unreaped, not merely under-logged.
+
     The stored name is read from the kernel-reported process name (comm —
     e.g. /proc/<pid>/comm on Linux), not from ``Path(argv[0]).name``: comm is
     derived from the exec()'d binary, not from argv[0], and is itself
@@ -249,11 +257,11 @@ def _live_children(
                     matched = p.pattern
                     break
         if matched is not None:
-            if len(ignored) < max_n:
+            if max_n is None or len(ignored) < max_n:
                 ignored.append({"name": name, "pid": pid, "matched": matched})
-        elif len(live) < max_n:
+        elif max_n is None or len(live) < max_n:
             live.append({"name": name, "pid": pid})
-        if len(live) >= max_n and len(ignored) >= max_n:
+        if max_n is not None and len(live) >= max_n and len(ignored) >= max_n:
             break
     return live, ignored
 
@@ -574,6 +582,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 +590,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 +615,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 +791,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 +836,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 +877,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: