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

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

@@ -5,6 +5,12 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.5
+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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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.5'
-__version_tuple__ = version_tuple = (0, 3, 5)
+__version__ = version = '0.3.6'
+__version_tuple__ = version_tuple = (0, 3, 6)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.5 → 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
 
@@ -206,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)``.
 
@@ -217,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
@@ -251,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
 

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

@@ -28,7 +28,7 @@ from typing import Literal
 
 from agent_runner import _resolve, events, hooks, host_health, metrics
 from agent_runner._notify import NULL_LISTENER, Listener, NullListener
-from agent_runner._plugin_sandbox import run_hook_sandboxed
+from agent_runner._plugin_sandbox import SpawnHookInterrupted, run_hook_sandboxed
 from agent_runner._procwait import wait_exit
 from agent_runner._serve_policy import (
     _MEM_LOOP_PERSIST_THRESHOLD,
@@ -251,7 +251,9 @@ def _spawn_view(work_dir, profile) -> hooks.SpawnView:
     )
 
 
-def _run_one_spawn_hook(h, ctx, log_dir, view, *, sandbox, engaged) -> SpawnDecision | None:
+def _run_one_spawn_hook(
+    h, ctx, log_dir, view, *, sandbox, engaged, listener=NULL_LISTENER, stop
+) -> SpawnDecision | None:
     """Run one spawn hook, isolating any failure exactly as ``dispatch_dirty``
     isolates a raising dirty handler: emit ``hook_failed`` and return None (the
     caller omits None from the collapse — treated as proceed).
@@ -265,7 +267,9 @@ def _run_one_spawn_hook(h, ctx, log_dir, view, *, sandbox, engaged) -> SpawnDeci
     in-process (unconfined — announced once at serve boot) and ``require`` refuses
     it (belt-and-braces; ``gate_serve_boot`` already aborts serve under
     require+can't-engage). The same ``view`` is passed on every path, so ``env``
-    stays names-only (no secret value)."""
+    stays names-only (no secret value). A sandboxed hook interrupted by a stop
+    (``should_stop`` fires on the serve doorbell) returns None WITHOUT emitting
+    ``hook_failed`` -- a stop is not a plugin failure."""
     third_party = not hooks._SPAWN_HOOK_BUILTIN.get(id(h), False)
     try:
         from agent_runner._sandbox_probe import hook_route
@@ -279,9 +283,19 @@ def _run_one_spawn_hook(h, ctx, log_dir, view, *, sandbox, engaged) -> SpawnDeci
         if route == "trampoline":
             module_path, attr_path = hooks._SPAWN_HOOK_MODULE.get(id(h), ("", ""))
             return run_hook_sandboxed(
-                "spawn_hook", module_path, attr_path, h.name, ctx, log_dir=log_dir, view=view
+                "spawn_hook",
+                module_path,
+                attr_path,
+                h.name,
+                ctx,
+                log_dir=log_dir,
+                view=view,
+                wake_fd=listener.fd,
+                should_stop=lambda: stop["requested"],
             )
         return h.before_spawn(ctx, view)
+    except SpawnHookInterrupted:
+        return None
     except Exception as exc:  # noqa: BLE001 — isolate; omit from collapse (== proceed)
         events.emit(
             log_dir,
@@ -294,7 +308,15 @@ def _run_one_spawn_hook(h, ctx, log_dir, view, *, sandbox, engaged) -> SpawnDeci
 
 
 def _maybe_defer_for_spawn_hooks(
-    cfg, log_dir, stop, *, phase, work_dir, engaged: bool, clock: Clock = SYSTEM_CLOCK
+    cfg,
+    log_dir,
+    stop,
+    *,
+    phase,
+    work_dir,
+    engaged: bool,
+    clock: Clock = SYSTEM_CLOCK,
+    listener: Listener | NullListener = NULL_LISTENER,
 ) -> bool:
     """The LAST serve-admission gate: run every registered SpawnHook over a
     read-only view of the resolved spawn and collapse their verdicts
@@ -321,8 +343,17 @@ def _maybe_defer_for_spawn_hooks(
     named: list[tuple[str, SpawnDecision]] = []
     for h in registered:
         decision = _run_one_spawn_hook(
-            h, ctx, log_dir, view, sandbox=cfg.plugins.sandbox, engaged=engaged
+            h,
+            ctx,
+            log_dir,
+            view,
+            sandbox=cfg.plugins.sandbox,
+            engaged=engaged,
+            listener=listener,
+            stop=stop,
         )
+        if stop["requested"]:
+            return False  # a stop landed during a hook -- serve_cmd's stop-check refuses the spawn
         if decision is None:
             continue  # hook_failed already emitted; omit from collapse (== proceed)
         if decision.action != "proceed" and h.name not in allow:
@@ -351,13 +382,13 @@ def _maybe_defer_for_spawn_hooks(
             defer_s=collapsed.defer_s,
             reason=collapsed.reason,
         )
-        if not _interruptible_sleep(collapsed.defer_s, stop, clock=clock):
+        if not _interruptible_sleep(collapsed.defer_s, stop, clock=clock, listener=listener):
             emit_round_resumed(log_dir, deferred_for_s=int(clock.monotonic() - started))
         return True
     emit_plugin_spawn_decision(
         log_dir, hook=winner, action="skip", defer_s=0, reason=collapsed.reason
     )
-    _interruptible_sleep(_SPAWN_SKIP_REPOLL_S, stop, clock=clock)
+    _interruptible_sleep(_SPAWN_SKIP_REPOLL_S, stop, clock=clock, listener=listener)
     return True
 
 

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

@@ -456,7 +456,7 @@ def _round_throttle_gate(cfg, args, log_dir, stop) -> tuple[frozenset[str], int
     return frozenset(), None
 
 
-def _spawn_gate(cfg, log_dir, stop, phase, *, sandbox_engaged: bool):
+def _spawn_gate(cfg, log_dir, stop, phase, *, sandbox_engaged: bool, listener=NULL_LISTENER):
     """The final admission gate: run the pre-spawn hooks for the resolved
     ``phase`` and translate a defer/skip into the ``_PAUSED_CONTINUE`` sentinel
     (caller re-admits next iteration); a proceed returns ``phase`` unchanged.
@@ -465,9 +465,17 @@ def _spawn_gate(cfg, log_dir, stop, phase, *, sandbox_engaged: bool):
     already paused, and it is the LAST gate (after memory / schedule / throttle
     have all resolved a concrete phase to spawn). ``sandbox_engaged`` is the
     boot probe verdict threaded from ``cmd()`` so the seam routes without
-    re-probing per round."""
+    re-probing per round. ``listener`` forwards into the sandboxed spawn-hook
+    wait and any defer/skip sleep, so a stop lands immediately instead of
+    riding out the trampoline's 30s wall-timeout."""
     if _maybe_defer_for_spawn_hooks(
-        cfg, log_dir, stop, phase=phase, work_dir=cfg.runtime.work_dir, engaged=sandbox_engaged
+        cfg,
+        log_dir,
+        stop,
+        phase=phase,
+        work_dir=cfg.runtime.work_dir,
+        engaged=sandbox_engaged,
+        listener=listener,
     ):
         return _PAUSED_CONTINUE
     return phase
@@ -505,11 +513,15 @@ def _select_and_gate(
     if args.ignore_schedule:
         # rotation self-resolves in the round; no --phase, but the pre-spawn gate
         # still runs on the concrete (None) outcome.
-        return _spawn_gate(cfg, log_dir, stop, None, sandbox_engaged=sandbox_engaged)
+        return _spawn_gate(
+            cfg, log_dir, stop, None, sandbox_engaged=sandbox_engaged, listener=listener
+        )
     if not _phase_aware(cfg):
         if _maybe_pause_for_schedule(cfg, log_dir, stop, listener=listener):
             return _PAUSED_CONTINUE
-        return _spawn_gate(cfg, log_dir, stop, None, sandbox_engaged=sandbox_engaged)
+        return _spawn_gate(
+            cfg, log_dir, stop, None, sandbox_engaged=sandbox_engaged, listener=listener
+        )
     # Pass the clock explicitly (call-time lookup) so tests can monkeypatch
     # schedule.now_in_zone; a default arg would capture the original at import.
     sel = phase_select.select_phase(
@@ -548,7 +560,9 @@ def _select_and_gate(
             chosen=sel.phase,
             active_window=sel.active_window or "",
         )
-    return _spawn_gate(cfg, log_dir, stop, sel.phase, sandbox_engaged=sandbox_engaged)
+    return _spawn_gate(
+        cfg, log_dir, stop, sel.phase, sandbox_engaged=sandbox_engaged, listener=listener
+    )
 
 
 def _prune_serve_round_logs(log_dir: Path, retention: int) -> None:

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

@@ -34,13 +34,14 @@ 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
+# NOT equal to it. The margin buys the round LEADER's own cooperative
+# _kill_pgroup (SIGTERM -> grace -> killpg of its agent) room to finish before
+# any outside SIGKILL lands: on the out-of-process `agent-runner kill` path
+# (_lifecycle._terminate_round_pid) the leader is SIGTERM'd first and only
+# SIGKILLed after this same grace, so a flushing agent isn't cut off an instant
+# before the leader's own escalation. 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.

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

@@ -89,6 +89,10 @@ there:
 - `start` is idempotent.
 - `stop` waits up to `round_budget_s` for the current round.
 - `kill` (and `restart --force`) is for a stuck round only — 5s grace then SIGKILL.
+- `agent-runner kill` does NOT honor `[agent] sigterm_grace_s`: under a systemd
+  `--user` unit it `systemctl kill`s the whole cgroup after a fixed 5 s, so a
+  cooperative agent (e.g. `gemini`) that needs its full grace to flush should be
+  stopped with `agent-runner serve stop` (drain-aware) rather than `kill`.
 - `restart` against a `--system`-installed unit refuses, printing the
   `sudo systemctl restart ...` command to run instead (it manages user-scope
   units only). `status` still reports it correctly — a `--system` install

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

@@ -496,6 +496,34 @@ No new internal wait — the grace window rides the v0.3.4 `wait_exit` deadline
 
 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.
 
+## 0.3.5 → 0.3.6 (2026-09-15)
+
+Two closed lifecycle gaps, not a new subsystem: `kill` now reaps a stuck round's detached descendants the way `serve stop` already did, and the sandboxed spawn-hook trampoline wait now joins the same `wait_exit` fd primitive as the rest of `serve`, so a stop during a confined third-party hook (or a plugin `defer`) reacts immediately instead of riding out the old poll. Same macOS harness (§ methodology above).
+
+### 1. Import/startup RSS
+
+| | 0.3.5 | 0.3.6 | Δ |
+|---|---|---|---|
+| RSS (avg of 5 cold runs) | 24.12 MB | 24.18 MB | +0.06 MB (flat, within noise) |
+| RSS range | 24.03–24.19 MB* | 24.00–24.34 MB | |
+
+\* one v0.3.5 run came in at 27.17 MB — the same first-invocation cold-page-cache outlier this page excludes elsewhere (see Caveats); dropped from the average/range as noise.
+
+Flat, and no new import edge. `_plugin_sandbox`/`_procwait`/`_notify` are NOT on the bare `import agent_runner` graph, but they ARE on the `import agent_runner.cli` (serve/round) startup graph — frozen in `test_import_footprint.py`'s `EXPECTED_STARTUP_PKG_MODULES` allowlist since the v0.3.2 SpawnHook seam (`_serve_round` imports `run_hook_sandboxed` at module level) and the v0.3.4 doorbell. v0.3.6 adds no new module to that graph — only new NAMES within those already-imported modules (`wake_fd`/`should_stop`/`SpawnHookInterrupted`/`_DRAIN_JOIN_S`/`_join_drain_threads`) — so the allowlist is unchanged and `test_import_footprint.py` + `test_round_alloc_growth.py` are green. Base dependency stays `psutil>=5.9`. (The raw `sys.modules` count shows +1, `agent_runner._version` — a generated file a fresh throwaway worktree lacks, a measurement artifact, not a code change.)
+
+### 2. Efficiency
+
+No headline RSS number here — the win is in wakeups and reaction latency, and it's conditional on workload. For the first-party plugin fleet, which runs no third-party spawn hooks, this release is flat, same as 0.3.5. The number that moves is scoped to whoever *does* run one:
+
+- **Per engaged third-party spawn hook, the trampoline wait drops from ~20 wakeups/s to exactly 1.** The old confinement trampoline joined a stdlib `subprocess.Popen.wait()`, which sleep-polls internally (~20 Hz); the rewrite blocks the trampoline on the same `wait_exit` fd primitive the rest of `serve` already uses, so it wakes exactly once, on the hook's actual exit — asserted by `test_plugin_sandbox_wire.py`'s `calls["n"] == 1` property test.
+- **A stop during a confined hook or a plugin `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 — closing the two lifecycle gaps this release targets. Behavioral, not an RSS change.
+
+The trampoline bounds its post-reap pipe drain to `_DRAIN_JOIN_S` (`agent_runner/_plugin_sandbox.py`): if a process the hook itself `fork()`'d keeps the reaped child's output pipe open, the drain thread stays blocked in `read()` and is abandoned (a daemon thread) rather than stalling the stop. That leaks at most one drain-thread pair per such invocation, bounded by the plugin's own process leak and negligible in RSS (an untouched thread stack); the thread dies when the fork()'d holder exits or when `serve` itself does. Reaping the hook's own `fork()`'d descendants is a recorded internal follow-up.
+
+### 3. Constrained-host (honesty)
+
+Dev-host-relative (macOS). Neither closed gap is constrained-host-specific — both are plain process-lifecycle correctness fixes exercised on CI (Linux, where the sandbox trampoline actually engages) and dev. No new constrained-host claim; the 462 MB `memory.high` write stays 0.3.7, Pi-gated.
+
 ## Enforcement
 
 Four invariant tests keep these numbers from drifting silently: