Skip to content

The agent that grows with you

refactor(deadline): one poll_until for check-until-deadline loops

kshitijk4poorde5f56c92a8f
diff --git a/agent/deadline.py b/agent/deadline.py
index 82025d98198..44c91cf50bd 100644
--- a/agent/deadline.py
+++ b/agent/deadline.py
@@ -6,6 +6,8 @@
* :func:`run_bounded_async` / :func:`run_bounded_sync` — wall-clock deadlines driven by
a daemon ``threading.Timer`` / worker thread, so a blocked event loop cannot disable them.
* :func:`kill_process_tree` — portable whole-tree termination.
+* :func:`poll_until` — the one "check until it holds or the deadline passes" loop; use it
+ instead of hand-writing ``deadline = time.monotonic() + t; while ...: time.sleep(...)``.
Invariants: operation exceptions propagate unchanged (only the *timeout* outcome is reified
as :class:`BoundedResult`); a timeout here is OUR deadline, not the provider's (classify
@@ -25,7 +27,7 @@ import sys
import threading
import time
from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Optional, Protocol
+from typing import Any, Awaitable, Callable, Optional, Protocol, TypeVar
logger = logging.getLogger(__name__)
@@ -35,11 +37,14 @@ __all__ = [
"DeadlineExpired",
"clamp_timeout",
"kill_process_tree",
+ "poll_until",
"resolve_timeout",
"run_bounded_async",
"run_bounded_sync",
]
+_T = TypeVar("_T")
+
# Upper bound for any timeout handed to platform wait primitives.
#
# CPython converts ``threading.Lock.acquire(timeout=...)`` /
@@ -132,6 +137,24 @@ def clamp_timeout(timeout: Optional[float]) -> Optional[float]:
return None if value <= 0 else min(value, MAX_SAFE_TIMEOUT_S)
+def poll_until(predicate: Callable[[], _T], timeout: float, interval: float) -> _T:
+ """Call ``predicate`` every ``interval`` s until it returns something truthy or ``timeout`` s
+ pass; return its last result (falsy on timeout).
+
+ The first check runs at once and the last sleep is cut to the time left, so a condition that
+ holds when the deadline arrives still counts. ``timeout <= 0`` means exactly one check.
+ """
+ deadline = time.monotonic() + timeout
+ while True:
+ result = predicate()
+ if result:
+ return result
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ return result
+ time.sleep(min(interval, remaining))
+
+
# --- Timeout resolution: config ``timeouts:`` > legacy env var > default ------
diff --git a/agent/outbound_webhooks.py b/agent/outbound_webhooks.py
index 29c0822538c..ec8732827e9 100644
--- a/agent/outbound_webhooks.py
+++ b/agent/outbound_webhooks.py
@@ -24,6 +24,7 @@ from typing import Any, Dict, List, Optional, Set, Tuple
from urllib import error as urlerror
from urllib import request as urlrequest
+from agent.deadline import poll_until
from agent.shell_hooks import (
_TOOL_EVENTS as _TOOL_SCOPED_EVENTS,
_ToolMatcherMixin,
@@ -123,14 +124,11 @@ def iter_configured_targets(cfg: Optional[dict[str, Any]]) -> list[WebhookTarget
def flush(timeout: float = 5.0) -> bool:
"""Block until all queued deliveries are done (or *timeout* elapses); True if drained."""
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
+ def _drained() -> bool:
with _delivery_queue.all_tasks_done:
- if _delivery_queue.unfinished_tasks == 0:
- return True
- time.sleep(0.02)
- with _delivery_queue.all_tasks_done:
- return _delivery_queue.unfinished_tasks == 0
+ return _delivery_queue.unfinished_tasks == 0
+
+ return poll_until(_drained, timeout, 0.02)
def re_register_config_hooks() -> None:
diff --git a/cron/delivery_queue.py b/cron/delivery_queue.py
index 5d3ecd9c29e..fbabf1f0afe 100644
--- a/cron/delivery_queue.py
+++ b/cron/delivery_queue.py
@@ -14,12 +14,12 @@ import logging
import os
import sqlite3
import threading
-import time
import uuid
from contextlib import contextmanager
from pathlib import Path
from typing import Any, Callable, Iterator, Optional
+from agent.deadline import poll_until
from agent.redact import redact_sensitive_text
from cron.executions import _owner_is_live, _process_start_time
from hermes_constants import get_hermes_home
@@ -417,12 +417,13 @@ def enqueue_and_wait(
wait_timeout = (
DEFAULT_DELIVERY_WAIT_TIMEOUT_SECONDS if timeout is None else max(0.0, timeout)
)
- deadline = time.monotonic() + wait_timeout
- while time.monotonic() < deadline:
+ def _terminal_row() -> Optional[dict]:
row = get_status(execution_id)
- if row and row["status"] in _TERMINAL:
- return None if row["status"] in {"delivered", "suppressed"} else str(
- row.get("error") or f"delivery {row['status']}"
- )
- time.sleep(1.0)
- return _terminalize_wait_timeout(execution_id) or None
+ return row if row and row["status"] in _TERMINAL else None
+
+ row = poll_until(_terminal_row, wait_timeout, 1.0)
+ if row is None:
+ return _terminalize_wait_timeout(execution_id) or None
+ return None if row["status"] in {"delivered", "suppressed"} else str(
+ row.get("error") or f"delivery {row['status']}"
+ )
diff --git a/cron/jobs.py b/cron/jobs.py
index 5558dae3ad0..c07480451b7 100644
--- a/cron/jobs.py
+++ b/cron/jobs.py
@@ -28,6 +28,7 @@ except ImportError: # pragma: no cover - non-Windows
msvcrt = None
from datetime import datetime, timedelta, timezone, UTC
from pathlib import Path
+from agent.deadline import poll_until
from hermes_constants import get_hermes_home
from cron.constants import CLAIM_TTL_INACTIVITY_HEADROOM, FIRE_CLAIM_SKEW_SECONDS, FIRE_CLAIM_TTL_SECONDS
from cron.env_settings import cron_env_setting
@@ -258,15 +259,14 @@ def _acquire_flock(lock_fd, timeout: float) -> Optional[bool]:
EVERY cron function forever, so poll LOCK_NB against a deadline; the caller picks the
degraded mode."""
if fcntl is not None:
- deadline = time.monotonic() + timeout
- while True:
+ def _try_flock() -> bool:
try:
fcntl.flock(lock_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
return True
except OSError:
- if time.monotonic() >= deadline:
- return False
- time.sleep(0.1)
+ return False
+
+ return poll_until(_try_flock, timeout, 0.1)
if msvcrt is not None:
msvcrt.locking(lock_fd.fileno(), msvcrt.LK_LOCK, 1)
return True
diff --git a/gateway/host_attach.py b/gateway/host_attach.py
index 4d6d41f8980..c7023c4d688 100644
--- a/gateway/host_attach.py
+++ b/gateway/host_attach.py
@@ -45,6 +45,8 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Optional
+from agent.deadline import poll_until
+
logger = logging.getLogger(__name__)
#: How long a caller waits for the owner's control socket after seeing its record (see module doc).
@@ -205,14 +207,13 @@ def _probe_host_gateway(wait_for_channel: float) -> Optional[HostGateway]:
if not hr.record_names_live_owner(record):
return None
home = record_home(record)
- deadline = time.monotonic() + max(0.0, wait_for_channel)
- while True:
+ def _matching_identity():
identity = _identify(home)
- if _identity_matches(identity, record, home):
- return HostGateway(record.pid, home, _served_from_identity(identity))
- if time.monotonic() >= deadline:
- break
- time.sleep(_CHANNEL_POLL_S)
+ return identity if _identity_matches(identity, record, home) else None
+
+ identity = poll_until(_matching_identity, max(0.0, wait_for_channel), _CHANNEL_POLL_S)
+ if identity is not None:
+ return HostGateway(record.pid, home, _served_from_identity(identity))
# An owner exists and has not answered: the served set is UNKNOWN, never the record's word.
return HostGateway(record.pid, home, (), served_known=False)
diff --git a/hermes_cli/browser_connect.py b/hermes_cli/browser_connect.py
index 2088f4dcad7..3cc15924698 100644
--- a/hermes_cli/browser_connect.py
+++ b/hermes_cli/browser_connect.py
@@ -26,6 +26,7 @@ import urllib.request
from dataclasses import dataclass, field
from pathlib import Path
+from agent.deadline import poll_until
from agent.proxy_bypass import is_loopback_host
from hermes_constants import get_hermes_home
@@ -631,11 +632,8 @@ def close_browser_holding_profile(src: str, timeout: float = 15.0) -> tuple[bool
psutil.wait_procs(alive, timeout=3.0)
# The lock releases slightly after the process exits on Windows; poll.
source_profile = _resolve_source_profile(src)[0] or _last_used_profile(src)
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
- if not _profile_is_locked(src, source_profile):
- return True, "closed the browser and the profile lock released."
- time.sleep(0.5)
+ if poll_until(lambda: not _profile_is_locked(src, source_profile), timeout, 0.5):
+ return True, "closed the browser and the profile lock released."
return False, (
"closed the browser processes but the profile is still locked — "
"another instance may have relaunched (background/tray mode).")
diff --git a/hermes_cli/data_cleanup_holders.py b/hermes_cli/data_cleanup_holders.py
index c722c73933c..e0b1b969ed0 100644
--- a/hermes_cli/data_cleanup_holders.py
+++ b/hermes_cli/data_cleanup_holders.py
@@ -3,7 +3,8 @@ from __future__ import annotations
from contextlib import ExitStack, contextmanager
from pathlib import Path
-import time
+
+from agent.deadline import poll_until
_OWNER_STOP_HINTS = {
@@ -59,14 +60,13 @@ def _drain_manual_gateway(home: Path) -> None:
response = pause_gateway_for_update(home)
if not pause_acked(response, identity):
raise RuntimeError(f"gateway refused to drain for {home}")
- deadline = time.monotonic() + min(120.0, max(5.0, float(response.get("drain_timeout", 30.0)) + 5.0))
- while time.monotonic() < deadline:
+ def _gone() -> bool:
current = get_process_start_time(pid)
original_gone = not _pid_exists(pid) or (current is not None and current != start)
- if original_gone and identify_gateway(home) is None and get_running_pid_identity_strict(home / "gateway.pid") is None:
- return
- time.sleep(0.05)
- raise RuntimeError(f"gateway did not exit for {home}; no data removed")
+ return original_gone and identify_gateway(home) is None and get_running_pid_identity_strict(home / "gateway.pid") is None
+
+ if not poll_until(_gone, min(120.0, max(5.0, float(response.get("drain_timeout", 30.0)) + 5.0)), 0.05):
+ raise RuntimeError(f"gateway did not exit for {home}; no data removed")
def _refuse_backend_writers(home: Path) -> None:
diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index e845b118506..8d863fc7e6c 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -34,6 +34,7 @@ PROJECT_ROOT = Path(__file__).parent.parent.resolve()
from gateway.config import coerce_systemd_watchdog_seconds, load_gateway_config
from gateway.status import terminate_pid
+from agent.deadline import poll_until
from gateway.restart import (
DEFAULT_GATEWAY_RESTART_DRAIN_TIMEOUT,
EXTERNAL_GATEWAY_SUPERVISOR_ENV,
@@ -2420,13 +2421,10 @@ def _ensure_user_systemd_env() -> None:
def _wait_for_user_dbus_socket(timeout: float = 3.0) -> bool:
"""Poll up to ``timeout`` s for a user systemd control socket ([email protected] takes a moment after enable-linger)."""
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
- if _user_systemd_socket_ready():
- _ensure_user_systemd_env()
- return True
- time.sleep(0.2)
- return _user_systemd_socket_ready()
+ if not poll_until(_user_systemd_socket_ready, timeout, 0.2):
+ return False
+ _ensure_user_systemd_env()
+ return True
def _wait_for_target_user_bus(uid: int, timeout: float = 5.0) -> bool:
@@ -2434,12 +2432,7 @@ def _wait_for_target_user_bus(uid: int, timeout: float = 5.0) -> bool:
Only the D-Bus socket counts — ``systemd/private`` alone is enough for ``systemctl --user`` but not for
the ``systemd-run --user`` that restart-safe workers need. Never adopts anything into our env."""
bus = Path(f"/run/user/{uid}/bus")
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
- if _path_exists_safe(bus):
- return True
- time.sleep(0.2)
- return _path_exists_safe(bus)
+ return poll_until(lambda: _path_exists_safe(bus), timeout, 0.2)
def _loginctl_enable_linger(username: str) -> subprocess.CompletedProcess:
diff --git a/hermes_cli/gateway_launchd.py b/hermes_cli/gateway_launchd.py
index 170a38e594e..c6289e0e1b1 100644
--- a/hermes_cli/gateway_launchd.py
+++ b/hermes_cli/gateway_launchd.py
@@ -19,6 +19,8 @@ from datetime import UTC
from hermes_cli import gateway_service_owner
+from agent.deadline import poll_until
+
def _gw():
from hermes_cli import gateway # late: the facade imports this module
@@ -804,14 +806,11 @@ def _wait_for_launchd_service_pid(
) -> bool:
"""Poll ``domain/label`` (0.5s) until it runs on a fresh PID or ``timeout`` passes — KeepAlive respawn
isn't instantaneous. launchctl ``TimeoutExpired`` propagates; callers own failure accounting."""
- deadline = time.monotonic() + max(timeout, 0.5)
- while True:
- _loaded, pid = _gw()._launchd_print_service_pid(domain, label)
- if pid is not None and pid > 0 and pid != old_pid:
- return True
- if time.monotonic() >= deadline:
- return False
- time.sleep(0.5)
+ def _fresh_pid() -> bool:
+ pid = _gw()._launchd_print_service_pid(domain, label)[1]
+ return pid is not None and pid > 0 and pid != old_pid
+
+ return poll_until(_fresh_pid, max(timeout, 0.5), 0.5)
def launchd_restart():
@@ -927,14 +926,11 @@ def wait_for_launchd_gateway_supervision(
return True
label = label or _gw().get_launchd_label()
- deadline = time.monotonic() + max(timeout, 0.0)
- while True:
+ def _supervised() -> bool:
pid = _gw()._launchctl_supervised_pid(label)
- if pid is not None and pid != old_pid:
- return True
- if time.monotonic() >= deadline:
- return False
- time.sleep(max(poll_interval, 0.01))
+ return pid is not None and pid != old_pid
+
+ return poll_until(_supervised, max(timeout, 0.0), max(poll_interval, 0.01))
def launchd_status(deep: bool = False):
diff --git a/hermes_cli/gateway_migrate.py b/hermes_cli/gateway_migrate.py
index cb0ec0334f7..bc412998c0a 100644
--- a/hermes_cli/gateway_migrate.py
+++ b/hermes_cli/gateway_migrate.py
@@ -32,6 +32,8 @@ from pathlib import Path
from types import SimpleNamespace
from typing import Callable, Iterator, Optional
+from agent.deadline import poll_until
+
logger = logging.getLogger(__name__)
MANIFEST_NAME = "gateway_migration.json"
@@ -1105,14 +1107,7 @@ def _wait_for_live_gateway(home: Path, timeout: float) -> Optional[int]:
timeout on a unit that keeps failing, and taking that for success is how the compensator
printed "✓ Restored" over a unit respawning every 5 s at ``ExecMainStatus=75``.
"""
- deadline = time.monotonic() + timeout
- while True:
- pid = _live_gateway_pid(home)
- if pid is not None:
- return pid
- if time.monotonic() >= deadline:
- return None
- time.sleep(0.5)
+ return poll_until(lambda: _live_gateway_pid(home), timeout, 0.5)
def rollback_migration(default_home: Optional[Path] = None) -> bool:
diff --git a/hermes_cli/gateway_supervised_restart.py b/hermes_cli/gateway_supervised_restart.py
index 1f92986208a..a2a3ce2d77d 100644
--- a/hermes_cli/gateway_supervised_restart.py
+++ b/hermes_cli/gateway_supervised_restart.py
@@ -11,9 +11,10 @@ supervisor (SIGUSR1 drain), and success is a fresh supervised PID — never the
from __future__ import annotations
import sys
-import time
from pathlib import Path
+from agent.deadline import poll_until
+
# A custom KeepAlive supervisor keeps its own respawn interval (launchd's is ~once per 10s,
# per LAUNCHD_SUPERVISION_VERIFY_TIMEOUT); 15s matches _wait_for_launchd_service_pid's budget.
SUPERVISED_REPLACEMENT_VERIFY_TIMEOUT = 15.0
@@ -63,14 +64,11 @@ def _wait_for_supervised_gateway_replacement(
if timeout is None:
timeout = SUPERVISED_REPLACEMENT_VERIFY_TIMEOUT
- deadline = time.monotonic() + max(timeout, 0.5)
- while True:
+ def _fresh_pid() -> int | None:
pid = get_running_pid()
- if pid is not None and pid > 0 and pid != old_pid:
- return pid
- if time.monotonic() >= deadline:
- return None
- time.sleep(poll_interval)
+ return pid if pid is not None and pid > 0 and pid != old_pid else None
+
+ return poll_until(_fresh_pid, max(timeout, 0.5), poll_interval)
def restart_externally_supervised_gateway(supervised_pid: int) -> None:
diff --git a/hermes_cli/gateway_windows.py b/hermes_cli/gateway_windows.py
index 6146bf9e7a1..5292ebd384a 100644
--- a/hermes_cli/gateway_windows.py
+++ b/hermes_cli/gateway_windows.py
@@ -25,6 +25,7 @@ from pathlib import Path
from xml.etree import ElementTree
from xml.sax.saxutils import escape
+from agent.deadline import poll_until
from hermes_cli._subprocess_compat import (
_WINDOWS_GATEWAY_BREAKAWAY_ENV,
windows_detach_flags,
@@ -1747,12 +1748,7 @@ def _drain_gateway_pid(pid: int, drain_timeout: float) -> bool:
except Exception:
pass # best-effort; caller escalates to a hard kill
- deadline = time.monotonic() + max(drain_timeout, 1.0)
- while time.monotonic() < deadline:
- if not _pid_exists(pid):
- return True
- time.sleep(0.5)
- return False
+ return poll_until(lambda: not _pid_exists(pid), max(drain_timeout, 1.0), 0.5)
def _windows_stop_drain_timeout() -> float:
@@ -1865,12 +1861,7 @@ def _wait_for_gateway_absent(timeout_s: float = 30.0, interval_s: float = 0.5) -
def _absent() -> bool:
return get_running_pid() is None and not _gateway_pids()
- deadline = time.monotonic() + max(timeout_s, interval_s)
- while time.monotonic() < deadline:
- if _absent():
- return True
- time.sleep(interval_s)
- return _absent()
+ return poll_until(_absent, max(timeout_s, interval_s), interval_s)
def _mark_planned_restart() -> None:
diff --git a/hermes_cli/kanban_db_connect.py b/hermes_cli/kanban_db_connect.py
index 27fcf568db9..19be46e40da 100644
--- a/hermes_cli/kanban_db_connect.py
+++ b/hermes_cli/kanban_db_connect.py
@@ -18,6 +18,7 @@ import threading
import time
from dataclasses import dataclass
from dataclasses import field
+from agent.deadline import poll_until
from hermes_cli.sqlite_util import add_column_if_missing as _add_column_if_missing
from pathlib import Path
from typing import Any
@@ -131,15 +132,13 @@ def _cross_process_init_lock(path: Path):
handle = lock_path.open("a+b")
acquired = False
try:
- deadline = time.monotonic() + _INIT_LOCK_TIMEOUT_SECONDS
- while True:
+ def _try_lock() -> bool:
try:
- acquired = _try_lock_nb(handle)
+ return _try_lock_nb(handle)
except OSError:
- acquired = False
- if acquired or time.monotonic() >= deadline:
- break
- time.sleep(_INIT_LOCK_POLL_SECONDS)
+ return False
+
+ acquired = poll_until(_try_lock, _INIT_LOCK_TIMEOUT_SECONDS, _INIT_LOCK_POLL_SECONDS)
if not acquired:
_kb._log.warning(
"kanban init lock for %s not acquired within %.0fs — proceeding "
diff --git a/hermes_cli/local_runtime/endpoint.py b/hermes_cli/local_runtime/endpoint.py
index 2abb34cfc7b..4943a046565 100644
--- a/hermes_cli/local_runtime/endpoint.py
+++ b/hermes_cli/local_runtime/endpoint.py
@@ -11,9 +11,10 @@ from contextlib import suppress
import json
import logging
import threading
-import time
import urllib.request
+from agent.deadline import poll_until
+
LLAMACPP_ALIASES = frozenset({"llamacpp", "llama.cpp", "llama-cpp"})
@@ -107,12 +108,7 @@ def resolve_llamacpp_endpoint(config: dict | None = None,
if wait_for_boot_s > 0 and _boot_in_flight(config):
_kick_managed_boot(config)
- deadline = time.monotonic() + wait_for_boot_s
- while time.monotonic() < deadline:
- time.sleep(0.25)
- managed = _state_endpoint()
- if managed:
- return managed
+ return poll_until(_state_endpoint, wait_for_boot_s, 0.25) or None
return None
diff --git a/hermes_cli/update_cmd_windows.py b/hermes_cli/update_cmd_windows.py
index f1142b9574b..d4b701a7369 100644
--- a/hermes_cli/update_cmd_windows.py
+++ b/hermes_cli/update_cmd_windows.py
@@ -15,6 +15,7 @@ import time as _time
from datetime import datetime, timezone, UTC
from pathlib import Path
+from agent.deadline import poll_until
from hermes_cli.update_cmd_common import _best_effort
logger = logging.getLogger("hermes_cli.update_cmd") # log-record parity with the origin module
@@ -89,7 +90,7 @@ def _wait_for_windows_update_gateway_exit(pids: list[int], *, timeout: float) ->
remaining = {pid for pid in remaining if _alive(pid)}
return not remaining
- _poll_until(_all_gone, max(timeout, 0.0), 0.25)
+ poll_until(_all_gone, max(timeout, 0.0), 0.25)
return {pid for pid in remaining if _alive(pid)}
@@ -693,16 +694,6 @@ def _original_process_is_alive(psutil, pid: int, create_time: float) -> bool:
return abs(current - create_time) <= 0.001
-def _poll_until(condition, timeout: float, interval: float = 0.2) -> bool:
- """Poll *condition* every *interval* seconds until true (True) or *timeout* elapses (False)."""
- deadline = _time.monotonic() + timeout
- while _time.monotonic() < deadline:
- if condition():
- return True
- _time.sleep(interval)
- return False
-
-
def _process_create_time(psutil, pid: int, label: str) -> float:
"""``create_time`` of *pid*; unreadable identity aborts the stop (RuntimeError)."""
try:
@@ -748,7 +739,7 @@ def _stop_windows_gateway_service(
def _alive() -> list[int]:
return [pid for pid, create_time in expected_processes if _original_process_is_alive(psutil, pid, create_time)]
- if _poll_until(lambda: service.status() == "stopped" and not _alive(), timeout):
+ if poll_until(lambda: service.status() == "stopped" and not _alive(), timeout, 0.2):
return
if service.status() != "stopped":
raise RuntimeError(f"Windows service {name} did not stop within {timeout:.0f}s; venv mutation unsafe.")
@@ -760,7 +751,7 @@ def _start_windows_gateway_service(name: str, *, timeout: float = 30.0) -> None:
"""Start one previously paused Windows service and verify it is running."""
service = _win_service(name)[1]
_sc_exe("start", name, service, "running")
- if not _poll_until(lambda: service.status() == "running", timeout):
+ if not poll_until(lambda: service.status() == "running", timeout, 0.2):
raise RuntimeError(f"Windows service {name} did not start within {timeout:.0f}s")
@@ -775,7 +766,7 @@ def _restore_windows_gateway_service(name: str, *, timeout: float = 60.0) -> Non
_start_windows_gateway_service(name)
return status in ("running", "stopped")
- if not _poll_until(_settled, timeout):
+ if not poll_until(_settled, timeout, 0.2):
raise RuntimeError(f"Windows service {name} did not reach a restorable state within {timeout:.0f}s")
diff --git a/tests/agent/test_deadline.py b/tests/agent/test_deadline.py
index 70b479e631b..86394e7106e 100644
--- a/tests/agent/test_deadline.py
+++ b/tests/agent/test_deadline.py
@@ -27,6 +27,7 @@ from agent.deadline import (
MAX_SAFE_TIMEOUT_S,
clamp_timeout,
kill_process_tree,
+ poll_until,
resolve_timeout,
run_bounded_async,
run_bounded_sync,
@@ -70,6 +71,54 @@ class TestClampTimeout:
assert clamp_timeout("not-a-number") is None # type: ignore[arg-type]
+# ---------------------------------------------------------------------------
+# poll_until
+# ---------------------------------------------------------------------------
+
+
+class _FakeClock:
+ def __init__(self):
+ self.now = 0.0
+ self.slept: list[float] = []
+
+ def monotonic(self) -> float:
+ return self.now
+
+ def sleep(self, seconds: float) -> None:
+ self.slept.append(seconds)
+ self.now += seconds
+
+
+def fake_clock(monkeypatch):
+ clock = _FakeClock()
+ monkeypatch.setattr("agent.deadline.time.monotonic", clock.monotonic)
+ monkeypatch.setattr("agent.deadline.time.sleep", clock.sleep)
+ return clock
+
+
+class TestPollUntil:
+ def test_returns_the_truthy_result_without_sleeping(self, fake_clock):
+ assert poll_until(lambda: 4242, 10.0, 0.5) == 4242
+ assert fake_clock.slept == []
+
+ def test_gives_up_at_the_deadline_with_the_last_falsy_result(self, fake_clock):
+ assert poll_until(lambda: False, 2.0, 0.5) is False
+ assert sum(fake_clock.slept) == 2.0
+
+ def test_condition_that_holds_when_the_deadline_arrives_counts(self, fake_clock):
+ # Interval 3 against a 5 s budget: the second sleep is cut to 2 s, and the check made at
+ # the deadline itself still sees the condition.
+ assert poll_until(lambda: fake_clock.now >= 5.0, 5.0, 3.0) is True
+ assert fake_clock.slept == [3.0, 2.0]
+
+ def test_zero_timeout_is_one_check(self, fake_clock):
+ calls = []
+ assert poll_until(lambda: calls.append(1), 0.0, 1.0) is None
+ assert calls == [1]
+ assert fake_clock.slept == []
+
+
# ---------------------------------------------------------------------------
# resolve_timeout
# ---------------------------------------------------------------------------
diff --git a/tests/scripts/test_fresh_source_install.py b/tests/scripts/test_fresh_source_install.py
index 7b522c260c2..fec58c84ab3 100644
--- a/tests/scripts/test_fresh_source_install.py
+++ b/tests/scripts/test_fresh_source_install.py
@@ -71,11 +71,12 @@ def test_current_installer_publishes_real_dependencies_and_warm_path(tmp_path, s
"setup-hermes.sh"):
shutil.copy2(ROOT / name, source / name)
# The CLI's user-facing text resolves through the i18n kernel (agent.i18n + the English catalog),
- # and its config/env layer consults the stdlib-only safe-worker policy; the rest of agent/ stays
- # out so the tail cannot grow a dependency on the agent runtime.
+ # its config/env layer consults the stdlib-only safe-worker policy, and the update path's wait
+ # loops use the stdlib-only agent.deadline; the rest of agent/ stays out so the tail cannot grow
+ # a dependency on the agent runtime.
(source / "agent").mkdir()
for name in ("__init__.py", "jiter_preload.py", "i18n.py", "i18n_layers.py", "i18n_languages.py",
- "safe_worker_policy.py"):
+ "safe_worker_policy.py", "deadline.py"):
shutil.copy2(ROOT / "agent" / name, source / "agent" / name)
(source / "locales").mkdir()
shutil.copy2(ROOT / "locales/en.yaml", source / "locales/en.yaml")
diff --git a/tools/bot_desktop/runtime.py b/tools/bot_desktop/runtime.py
index 954807af50b..3fac333c2bd 100644
--- a/tools/bot_desktop/runtime.py
+++ b/tools/bot_desktop/runtime.py
@@ -26,6 +26,7 @@ from dataclasses import dataclass
from pathlib import Path
from typing import Dict, Optional
+from agent.deadline import poll_until
from hermes_constants import get_hermes_home
from tools.bot_desktop import placement
@@ -294,13 +295,13 @@ def _kill_group_then_wait(pgid: Optional[int], pid: int, grace: float = 2.0) ->
with contextlib.suppress(ChildProcessError, OSError):
os.waitpid(pid, os.WNOHANG) # windows-footgun: ok — Linux-only runtime (is_supported_host gates start/stop)
- _signal(signal.SIGTERM)
- deadline = time.monotonic() + grace
- while time.monotonic() < deadline:
+ def _gone() -> bool:
_reap_if_ours()
- if not _anything_left():
- return
- time.sleep(0.05)
+ return not _anything_left()
+
+ _signal(signal.SIGTERM)
+ if poll_until(_gone, grace, 0.05):
+ return
_signal(signal.SIGKILL) # windows-footgun: ok — Linux-only runtime (is_supported_host gates start/stop)
time.sleep(0.1)
_reap_if_ours()
diff --git a/tools/bot_desktop/sandbox_host.py b/tools/bot_desktop/sandbox_host.py
index a827bc2be0a..9fea7374694 100644
--- a/tools/bot_desktop/sandbox_host.py
+++ b/tools/bot_desktop/sandbox_host.py
@@ -23,6 +23,7 @@ import time
from pathlib import Path
from typing import Any, Dict, Optional
+from agent.deadline import poll_until
from hermes_constants import get_hermes_home
from tools.environments import streams
@@ -269,13 +270,14 @@ def start(env: Any, profile: str, *, geometry: str, wait_seconds: float = 20.0,
proc = streams.run_in(env, ["bash", "-c", spawn], child_env=child_env, user=user, timeout=30)
if proc.returncode != 0:
raise RuntimeError(f"sandbox desktop launcher did not start: {proc.stderr.decode('utf-8', 'replace')[-500:]}")
- deadline = time.monotonic() + wait_seconds
- while time.monotonic() < deadline:
+ def _live_display() -> dict[str, str] | None:
live = _published(env, rdir)
- if live.get("DISPLAY"):
- logger.info("Bot Desktop for profile %s up inside %s on %s", profile, type(env).__name__, live["DISPLAY"])
- return _record(env, rdir, profile, live)
- time.sleep(0.25)
+ return live if live.get("DISPLAY") else None
+
+ live = poll_until(_live_display, wait_seconds, 0.25)
+ if live:
+ logger.info("Bot Desktop for profile %s up inside %s on %s", profile, type(env).__name__, live["DISPLAY"])
+ return _record(env, rdir, profile, live)
tail = streams.run_in(env, ["tail", "-c", "2000", f"{rdir}/launcher.log"], user=user, timeout=10).stdout
stop(env, profile)
raise RuntimeError(f"sandbox desktop did not publish its display within {wait_seconds:.0f}s:\n"
diff --git a/tui_gateway/methods_browser.py b/tui_gateway/methods_browser.py
index 97bf48d9553..33e5da9335f 100644
--- a/tui_gateway/methods_browser.py
+++ b/tui_gateway/methods_browser.py
@@ -43,6 +43,7 @@ def _cdp_http_reachable(parsed, timeout: float = 2.0) -> bool:
def _connect_local_default(port: int, system: str, announce) -> str | None:
"""Discover (or launch) the default local debug browser → CDP URL, or None after announcing."""
+ from agent.deadline import poll_until
from hermes_cli.browser_connect import (
discover_local_cdp_url, find_free_debug_port, launch_chrome_debug, local_port_in_use,
manual_chrome_debug_command)
@@ -65,11 +66,7 @@ def _connect_local_default(port: int, system: str, announce) -> str | None:
launch = launch_chrome_debug(launch_port, system)
if launch.launched:
# Bounded wait: the whole connect must finish inside the client RPC timeout.
- deadline = time.monotonic() + 10.0
- while time.monotonic() < deadline:
- if discovered := discover_local_cdp_url(launch_port, timeout=1.0):
- break
- time.sleep(0.5)
+ discovered = poll_until(lambda: discover_local_cdp_url(launch_port, timeout=1.0), 10.0, 0.5)
if discovered:
announce(f"Chromium-family browser launched and listening on port {launch_port}")
return discovered