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

{cli_agent_runner-0.3.3 → 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.3 → cli_agent_runner-0.3.5}/CHANGELOG.md

@@ -5,6 +5,20 @@ 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
+- While a round runs, the supervisor now blocks on the round process's exit instead of polling about once a second — it uses no CPU while waiting and notices a round's exit immediately.
+- A stop (`SIGTERM` / `agent-runner serve stop`) during a schedule, memory, or phase pause, or during the inter-round restart delay, now takes effect near-instantly instead of after the current pause chunk (up to 30 s).
+- `agent-runner events --tail` shows a new matching event within a drain cycle of its being written, instead of on a ~1 s poll.
+
+No change to the rules for when a round is deferred, terminated, or reaped. The mid-round memory check and the round budget now take effect on schedule instead of up to ~1 s late, so within that window the sustained-pressure floor or the budget cutoff can act on a round the old ~1 s poll would have seen finish first.
+
 ## [0.3.3] - 2026-09-14
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.3
+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.5/agent_runner/_notify.py

@@ -0,0 +1,245 @@
+"""A broker-less FIFO doorbell -- wake a waiting consumer within milliseconds
+of a durable event write, instead of a busy-poll loop checking every second.
+
+Per-listener FIFO under ``log_dir/.notify/``: one named pipe per live
+``Listener``, path-addressed so the producer (``events.emit``) needs no
+registry, no socket, and no persistent connection -- it just fans a single
+byte out to every ``*.fifo`` file it finds. Zero cost when nobody is
+listening (the directory is empty, ``ring`` is a fast no-op scan).
+Self-healing on a stale entry left behind by a crashed listener: opening a
+FIFO with no reader raises ``ENXIO``, which ``ring`` treats as "nobody's
+there" and cleans up.
+
+Stdlib only (``os``, ``select``, ``pathlib``) -- no watchfiles/inotify,
+no socketpair/AF_UNIX. A FIFO is opened ``O_RDWR`` (the self-pipe trick):
+holding the write side open ourselves means the read side never sees the
+"all writers closed" EOF a plain read-only open would eventually hit.
+
+Fail-open throughout: any ``OSError`` from ``mkfifo``/``open`` degrades a
+would-be ``Listener`` to a ``NullListener`` that just sleeps out its
+timeout, so a filesystem without FIFO support (or without write
+permission under ``log_dir``) never breaks the caller -- it only falls
+back to the busy-poll cadence this module was built to avoid.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import select
+from pathlib import Path
+
+from agent_runner.clock import SYSTEM_CLOCK, Clock
+
+_NOTIFY_DIRNAME = ".notify"
+
+
+def ring(log_dir: Path) -> None:
+    """Best-effort wake for every live ``Listener`` under ``log_dir/.notify/``.
+
+    For each ``*.fifo``: open ``O_WRONLY | O_NONBLOCK``, write one byte,
+    close. Every ``OSError`` is swallowed -- ``EAGAIN`` (the listener's
+    kernel pipe buffer is full) is harmless, the wake already landed;
+    ``ENXIO`` (no reader -- a stale FIFO left by a listener that crashed
+    without unlinking) means the entry is dead, so it is unlinked. Never
+    raises into the caller's durable-write path.
+    """
+    notify_dir = log_dir / _NOTIFY_DIRNAME
+    try:
+        with os.scandir(notify_dir) as it:
+            paths = [e.path for e in it if e.name.endswith(".fifo")]
+    except OSError:
+        return
+
+    for path in paths:
+        try:
+            fd = os.open(path, os.O_WRONLY | os.O_NONBLOCK)
+        except OSError as e:
+            if e.errno == errno.ENXIO:
+                try:
+                    os.unlink(path)
+                except OSError:
+                    pass  # a permission-denied .notify/ can't be cleaned up -- never mind
+            continue
+        try:
+            os.write(fd, b"\x00")
+        except OSError:
+            pass  # EAGAIN: listener's kernel buffer is full -- the wake already landed
+        finally:
+            try:
+                os.close(fd)
+            except OSError:
+                pass  # EINTR or similar -- fail-open, never let a close raise into emit()
+
+
+def drain(fd: int) -> None:
+    """Read a level-triggered wakeup fd until ``EAGAIN`` so a delivered byte
+    (a ``ring()`` or a ``signal.set_wakeup_fd`` signal) doesn't leave the next
+    ``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.
+    """
+    while True:
+        try:
+            if not os.read(fd, 4096):
+                break
+        except OSError:
+            break
+
+
+class Listener:
+    """Context manager owning one FIFO under ``log_dir/.notify/``.
+
+    ``__enter__`` creates ``log_dir/.notify/<pid>-<id(self)>.fifo`` and
+    opens it ``O_RDWR | O_NONBLOCK`` -- holding the write side ourselves
+    is what keeps the read side from ever seeing a persistent EOF. It
+    retries up to 3 times if a concurrent ``ring()`` wins the race between
+    ``mkfifo`` and ``open`` and unlinks the readerless FIFO out from under
+    us (see ``__enter__``'s own comment).
+    ``__exit__`` unlinks the FIFO unconditionally (including when an
+    exception, e.g. ``KeyboardInterrupt``, propagates through the
+    ``with`` block).
+    """
+
+    def __init__(self, log_dir: Path) -> None:
+        self._notify_dir = log_dir / _NOTIFY_DIRNAME
+        self._path = self._notify_dir / f"{os.getpid()}-{id(self)}.fifo"
+        self._fd: int | None = None
+
+    def __enter__(self) -> Listener:
+        # Idempotent: open_listener() pre-enters a Listener to detect OSError
+        # and degrade to a NullListener, then hands the already-entered
+        # instance to the caller's own `with` statement, which enters it a
+        # second time -- that second entry must be a no-op, not a re-mkfifo.
+        if self._fd is not None:
+            return self
+        self._notify_dir.mkdir(parents=True, exist_ok=True)
+        # Bounded retry: mkfifo and open are two separate syscalls, so there is a
+        # window between them where the FIFO exists but has no reader yet. A
+        # concurrent ring() from another process sharing this log_dir can open
+        # our fresh, readerless FIFO O_WRONLY|O_NONBLOCK, get ENXIO, and (by
+        # design -- see ring()'s docstring) unlink it as "stale". Our own
+        # os.open then loses the file underneath us with FileNotFoundError.
+        # Retrying re-creates the FIFO from scratch; three tries makes losing
+        # the race every single time astronomically unlikely.
+        last_exc: OSError | None = None
+        for _ in range(3):
+            try:
+                os.mkfifo(self._path)
+            except FileExistsError:
+                pass  # a prior retry (or the same path) already made it -- try to open it
+            try:
+                self._fd = os.open(self._path, os.O_RDWR | os.O_NONBLOCK)
+                return self
+            except FileNotFoundError as e:
+                last_exc = e  # a concurrent ring() unlinked our readerless FIFO -- retry
+        raise last_exc if last_exc is not None else OSError("Listener.__enter__ exhausted retries")
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: object
+    ) -> None:
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            except OSError:
+                pass
+            self._fd = None
+        try:
+            self._path.unlink(missing_ok=True)
+        except OSError:
+            pass  # e.g. a permission-denied .notify/ -- fail-open, never crash teardown
+
+    @property
+    def fd(self) -> int:
+        """The FIFO's read/write fd -- selectable, and the value handed to
+        ``signal.set_wakeup_fd``."""
+        assert self._fd is not None, "Listener.fd read outside its `with` block"
+        return self._fd
+
+    def wait(self, timeout_s: float, *, clock: Clock = SYSTEM_CLOCK) -> bool:
+        """Block until a ring wakes this listener or ``timeout_s`` elapses.
+
+        ``select.select`` against a ``clock.monotonic()`` deadline so a
+        real timeout still elapses under real time even though the wake
+        itself is an fd event no fake clock can simulate. On wake, drains
+        the fd (reads until ``EAGAIN``) so a burst of rings before the
+        next ``wait`` call coalesces into a single wake instead of one
+        per byte.
+
+        Returns ``True`` iff woken before the timeout -- a ring, a signal
+        delivered via ``signal.set_wakeup_fd`` on this same fd, or a
+        spurious wake all look identical here; callers never distinguish
+        them because the wake is purely advisory -- either way the caller
+        re-reads its own state after ``wait`` returns.
+        """
+        deadline = clock.monotonic() + timeout_s
+        remaining = max(0.0, deadline - clock.monotonic())
+        ready, _, _ = select.select([self.fd], [], [], remaining)
+        if not ready:
+            return False
+
+        drain(self.fd)
+        return True
+
+
+class NullListener:
+    """Fallback when ``mkfifo``/``open`` fails (no filesystem permission,
+    FIFOs unsupported). ``fd`` is ``None`` -- there is nothing to select
+    on. A no-op context manager so ``with open_listener(...) as listener``
+    works identically whether or not the FIFO could be created.
+    """
+
+    @property
+    def fd(self) -> None:
+        return None
+
+    def __enter__(self) -> NullListener:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: object
+    ) -> None:
+        return None
+
+    def wait(self, timeout_s: float, *, clock: Clock = SYSTEM_CLOCK) -> bool:
+        """Degrades to a plain timed sleep -- preserves every ``FakeClock``
+        test's semantics unchanged: waiting still advances virtual time by
+        exactly ``timeout_s``, same as a bare ``clock.sleep(timeout_s)``."""
+        clock.sleep(timeout_s)
+        return False
+
+
+# Stateless (fd=None, wait==clock.sleep, no-op ctx mgr), so one module-level
+# instance is a safe default arg -- the stable-singleton default (mirrors
+# SYSTEM_CLOCK) every non-serve caller of a listener-aware function keeps by
+# not passing one, staying byte-identical to its pre-doorbell behavior.
+NULL_LISTENER = NullListener()
+
+
+def open_listener(log_dir: Path) -> Listener | NullListener:
+    """Try to construct a live ``Listener``; degrade to a ``NullListener``
+    on any ``OSError`` from ``mkfifo``/``open`` (e.g. a read-only
+    filesystem or a platform without FIFO support) so the consumer never
+    has to branch on which one it got.
+
+    Pre-enters the ``Listener`` here (rather than leaving that to the
+    caller's own ``with``) so the failure can be caught and swapped for a
+    ``NullListener``; ``Listener.__enter__`` is idempotent, so the
+    caller's subsequent ``with open_listener(log_dir) as listener:`` is
+    safe to call it a second time.
+    """
+    listener = Listener(log_dir)
+    try:
+        listener.__enter__()
+    except OSError:
+        try:
+            listener._path.unlink(missing_ok=True)
+        except OSError:
+            pass  # cleanup best-effort -- must not crash the caller's degrade-to-Null path
+        return NullListener()
+    return listener

{cli_agent_runner-0.3.3 → 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.5/agent_runner/_procwait.py

@@ -0,0 +1,165 @@
+"""Process-exit waiting on a readable fd, not a busy-poll loop.
+
+``exit_fd`` opens a throwaway fd that becomes readable once a subprocess has
+exited (``os.pidfd_open`` on Linux, a kqueue ``NOTE_EXIT`` registration on
+macOS/BSD, ``None`` on any other platform or any setup failure). ``wait_exit``
+blocks in one ``select.select`` on that fd until the process exits or a real
+deadline passes.
+
+Neither function ever reaps the process on this fast path -- a pidfd or a
+kqueue registration only observes the kernel's process table, it never
+consumes the zombie slot. There is exactly one path from "notices exit" to
+"reaps": the caller, in the same thread, right after ``wait_exit`` returns
+``"exited"``. No background watcher thread ever touches the process table,
+which is what keeps this immune to CPython's pidfd/child-watcher race
+(https://github.com/python/cpython/issues/127049): a background reaper can
+consume a zombie's pid slot between the moment some other code decides to
+signal that pid and the moment it actually does, letting a freshly spawned,
+unrelated process reuse the pid and get signalled by mistake. With no
+background reaper at all, that window doesn't exist.
+
+The one exception is the poll fallback used when ``exit_fd`` returns
+``None`` (no pidfd/kqueue support, or a kernel/pid-race failure on setup):
+it calls ``proc.poll()`` on a short cadence, exactly like the busy-poll loop
+this module replaces. That does reap on exit, but synchronously, inside the
+one call, in the caller's own thread -- there is still no separate
+notice-then-reap window and no background thread, so the safety argument
+above still holds; only the fast path is structurally two separate steps
+(notice, then a later caller-owned reap).
+"""
+
+from __future__ import annotations
+
+import os
+import select
+import subprocess  # noqa: TID251 -- exit_fd/wait_exit observe Popen.pid; see pyproject.toml
+import sys
+from typing import Literal
+
+from agent_runner.clock import SYSTEM_CLOCK, Clock
+
+# Fallback poll cadence when exit_fd() is unsupported -- matches the
+# real-second value of the busy-poll tick this module's callers used to run
+# themselves before switching to wait_exit (e.g. _spawn_round's old
+# proc.wait(timeout=1)). Kept as its own constant, not imported by/from a
+# caller, so this module has no dependency on any of them.
+_POLL_TICK_S = 1.0
+
+
+def exit_fd(proc: subprocess.Popen) -> int | None:
+    """A fd that becomes readable once ``proc``'s pid has exited (zombie, not
+    yet reaped) -- this never itself waits on or reaps it.
+
+    Linux: ``os.pidfd_open(proc.pid, 0)``. macOS/BSD: a kqueue registered
+    with ``EVFILT_PROC``/``NOTE_EXIT`` on ``proc.pid``, whose underlying
+    kernel object is kept alive by handing back a ``os.dup``'d descriptor
+    rather than the kqueue object's own fileno -- the ``select.kqueue``
+    Python object is closed before this function returns (its ``__del__``
+    would otherwise race a caller's pending ``select`` and close the fd out
+    from under it), while the duplicated fd keeps the same underlying kqueue
+    alive until the caller closes it. Any other platform, or any ``OSError``
+    from either path (kernel too old, permission denied, or the pid already
+    reaped out from under us): ``None`` -- always fail-open, never fatal.
+
+    The caller owns the returned fd for exactly the lifetime of the one
+    ``wait_exit`` call that opened it; see that function's docstring for the
+    close-after-use discipline this enables.
+    """
+    if sys.platform.startswith("linux") and hasattr(os, "pidfd_open"):
+        try:
+            return os.pidfd_open(proc.pid, 0)
+        except OSError:
+            return None
+
+    if hasattr(select, "kqueue"):
+        try:
+            kq = select.kqueue()
+            try:
+                event = select.kevent(
+                    proc.pid,
+                    filter=select.KQ_FILTER_PROC,
+                    flags=select.KQ_EV_ADD,
+                    fflags=select.KQ_NOTE_EXIT,
+                )
+                kq.control([event], 0, 0)
+                return os.dup(kq.fileno())
+            finally:
+                kq.close()
+        except OSError:
+            return None
+
+    return None
+
+
+def wait_exit(
+    proc: subprocess.Popen,
+    *,
+    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).
+
+    Opens and closes its own ``exit_fd(proc)`` registration internally, once
+    per call, in a single ``select.select`` -- callers invoke this at most
+    every few seconds (a round's mem-check interval) or once per grace
+    window, so the per-call setup cost is negligible and no fd is held open
+    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"``.
+
+    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.
+
+    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).
+    Re-opening ``exit_fd(proc.pid)`` on a freed pid could bind pidfd/kqueue to
+    an UNRELATED process and ride out the whole deadline as a false
+    ``"timeout"``. The most common way this happens is ``Popen.terminate()``,
+    whose ``send_signal`` calls ``proc.poll()`` first and reaps a leader that
+    exited in the microseconds before the signal.
+    """
+    if proc.returncode is not None:
+        return "exited"  # already reaped by this owner -- never re-open a pid we no longer hold
+
+    fd = exit_fd(proc)
+
+    if fd is None:
+        return _wait_exit_by_polling(proc, deadline=deadline, clock=clock)
+
+    try:
+        remaining = max(0.0, deadline - clock.monotonic())
+        ready, _, _ = select.select([fd], [], [], remaining)
+        return "exited" if ready else "timeout"
+    finally:
+        os.close(fd)
+
+
+def _wait_exit_by_polling(
+    proc: subprocess.Popen,
+    *,
+    deadline: float,
+    clock: Clock,
+) -> Literal["exited", "timeout"]:
+    # Not clock.wait_until: keep this poll loop in _procwait so
+    # test_procwait_shield.py's _procwait-only scan guards its KeyboardInterrupt
+    # propagation (the grace-kill shield depends on it).
+    while True:
+        if proc.poll() is not None:
+            return "exited"
+
+        remaining = deadline - clock.monotonic()
+        if remaining <= 0:
+            return "timeout"
+
+        clock.sleep(min(_POLL_TICK_S, remaining))

{cli_agent_runner-0.3.3 → 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.3 → cli_agent_runner-0.3.5}/agent_runner/_throttle.py

@@ -18,6 +18,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
+from agent_runner._notify import NULL_LISTENER, Listener, NullListener
 from agent_runner.api_types import TransientErrorState
 from agent_runner.clock import SYSTEM_CLOCK, Clock
 from agent_runner.events import (
@@ -594,6 +595,7 @@ def _interruptible_sleep(
     chunk_s: int = 30,
     should_stop: Callable[[], bool] | None = None,
     deadline_epoch: float | None = None,
+    listener: Listener | NullListener = NULL_LISTENER,
 ) -> bool:
     """Sleep ``total_s`` in ``<= chunk_s`` slices, re-checking ``stop`` (and, if given,
     ``should_stop()``) at each boundary; return True iff ``stop["requested"]`` OR
@@ -601,14 +603,45 @@ def _interruptible_sleep(
     :func:`_apply_back_off` so a SIGTERM or a stop_file lands within one chunk instead
     of after the full sleep (e.g. the 8h back-off cap).
 
+    ``listener`` (default :data:`agent_runner._notify.NULL_LISTENER`) is the single
+    wakeup mechanism for the per-chunk nap below: a real ``Listener`` wakes early on a
+    SIGTERM/SIGINT (via ``signal.set_wakeup_fd``) or a cross-process ``ring()``,
+    dropping the wait to milliseconds instead of riding out the full ``chunk_s``; the
+    default ``NullListener`` degrades ``listener.wait(nap, clock=clock)`` to a plain
+    ``clock.sleep(nap)`` on the SAME clock, so every existing caller (none of which
+    pass ``listener``) stays byte-identical.
+
     ``should_stop`` matches :func:`_pause_poll`'s contract (cli/_serve_round.py): a
     zero-arg predicate the caller closes over its own stop_file check with, so this
     module never needs to know what "should stop" means beyond calling it.
 
-    Counts down the *intended* nap per slice rather than measuring a wall/monotonic
-    deadline: NTP-step immune (no clock read for the deadline) AND does not busy-spin
-    when ``clock.sleep`` is a no-op (a test patching ``time.sleep`` runs it instantly
-    instead of looping until real time advances).
+    A live ``Listener`` can return from ``wait`` early on an advisory event byte that
+    is not a stop (e.g. a doorbell already rung by a concurrent ``events.emit``
+    before this call even started, or another emit landing mid-sleep) — crediting
+    the full nap for a wait that actually returned in microseconds would collapse
+    the whole sleep to ~0 on the first stray byte, defeating callers like the serve
+    restart/crash back-off delay that depend on this function to ride out its full
+    duration. So a live listener is credited its *actual* ``clock.monotonic()``
+    elapsed per slice, not the intended nap.
+
+    ``NullListener.wait``, by contrast, can never return early — there is no fd to
+    wake on, it always just calls ``clock.sleep(nap)`` and returns — so for it the
+    intended nap IS the correct credit, and this function keeps using it directly
+    (``remaining -= nap``) rather than measuring elapsed around it. This is
+    deliberate, not an optimization: a monotonic-elapsed measurement would only be
+    byte-identical to the old intended-nap count if the injected clock's
+    ``monotonic()`` genuinely tracked its own ``sleep()`` — true for ``FakeClock``,
+    but NOT for a test that monkeypatches the stdlib ``time.sleep`` (what
+    ``RealClock.sleep`` calls) to skip real waiting without touching
+    ``time.monotonic()`` (a real, used-elsewhere-in-this-suite pattern, e.g.
+    ``test_serve_crash_loop.py``): that combination would leave elapsed pinned
+    near 0 forever and busy-spin the loop for the full ``chunk_s``/``total_s``
+    instead of terminating. Branching on the listener type sidesteps that clock
+    fragility entirely and keeps every existing NULL_LISTENER caller provably
+    byte-identical to the pre-fix accounting. Still NTP-step immune either way:
+    ``clock.monotonic()`` is never stepped by an NTP correction (only
+    ``clock.epoch()`` is, which the ``deadline_epoch`` branch below handles
+    separately).
 
     ``deadline_epoch``, when given, additionally re-checks ``clock.epoch() >=
     deadline_epoch`` at each chunk boundary and returns False (completed, NOT
@@ -627,8 +660,18 @@ def _interruptible_sleep(
         if deadline_epoch is not None and clock.epoch() >= deadline_epoch:
             return False
         nap = min(float(chunk_s), remaining)
-        clock.sleep(nap)
-        remaining -= nap
+        if isinstance(listener, NullListener):
+            # Never returns early (no fd to wake on) -- the intended nap is exactly
+            # what it consumed, so crediting it directly is provably byte-identical
+            # to the pre-fix accounting for every existing (non-serve) caller.
+            listener.wait(nap, clock=clock)
+            remaining -= nap
+        else:
+            # May return early on a spurious/stale ring -- credit only what the
+            # wait actually consumed, or a stray event byte collapses the sleep.
+            started = clock.monotonic()
+            listener.wait(nap, clock=clock)
+            remaining -= max(0.0, clock.monotonic() - started)
     return False
 
 

{cli_agent_runner-0.3.3 → 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.3'
-__version_tuple__ = version_tuple = (0, 3, 3)
+__version__ = version = '0.3.5'
+__version_tuple__ = version_tuple = (0, 3, 5)
 
 __commit_id__ = commit_id = None