cli-agent-runner 0.2.6__tar.gz → 0.2.7__tar.gz

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/.vulture-whitelist.py

@@ -50,6 +50,7 @@ service
 recent_events
 recent_hook_failures
 recent_blips
+schedule
 
 # agent_runner.api_types.RateLimitState
 throttled_until_epoch
@@ -121,6 +122,7 @@ vcs
 monitor
 phases
 plugins
+schedule
 
 # agent_runner.config.MonitorConfig
 auth_fail_patterns
@@ -176,6 +178,11 @@ dry_run
 max_grace_after_result_s
 grace_kill_ignore_patterns
 
+# agent_runner.config.ScheduleConfig
+timezone
+run_windows
+pause_windows
+
 # agent_runner.config.VcsConfig
 stash_idempotency_s
 dirty_action
@@ -233,6 +240,17 @@ deleted
 deferred
 existing
 
+# agent_runner.schedule.PauseDecision
+paused
+resume_at
+active_window
+
+# agent_runner.schedule.Window
+start_min
+end_min
+label
+days
+
 # agent_runner.startup_check.CheckResult
 name
 ok

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.2.7] - 2026-08-25
+
+### Added
+- `[schedule]` config gates the serve loop between rounds: `pause_windows` / `run_windows` decide whether the next round launches now or the supervisor idle-sleeps until a window opens, then auto-resumes. Windows are `[WEEKDAYS ]HH:MM-HH:MM` (24h, end-exclusive, midnight-wrap; optional `Mon-Fri` / `Sat,Sun` weekday prefix, bare = every day). Timezone-aware (`timezone`, IANA; omit → host local). Evaluation is `run AND NOT pause`. Absent section → unchanged 7×24 behavior. An in-flight round is never interrupted; `agent-runner round` is never gated.
+- `schedule_paused` / `schedule_resumed` events; `peek` surfaces the current pause state (`schedule` field).
+- `serve --ignore-schedule` runs rounds regardless of the windows (catch-up / testing).
+
+### Fixed
+- Monitor no longer raises `supervisor_stale` during an intentional schedule pause (suppressed until `resume_at` plus one staleness window).
+
+See `docs/migrations/0.2.7.md`.
+
 ## [0.2.6] - 2026-07-28
 
 ### Changed

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.6
+Version: 0.2.7
 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.2.6 → cli_agent_runner-0.2.7}/agent_runner/_docgen.py

@@ -22,6 +22,7 @@ from agent_runner.config import (
     PluginsConfig,
     PromptConfig,
     RuntimeConfig,
+    ScheduleConfig,
     VcsConfig,
 )
 from agent_runner.defenses import catalog
@@ -45,6 +46,7 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
     ("monitor", MonitorConfig, [("monitor.host_health", MonitorHostHealthConfig)]),
     ("phases", PhasesConfig, []),
     ("plugins", PluginsConfig, []),
+    ("schedule", ScheduleConfig, []),
 ]
 
 

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/_emit.py

@@ -26,6 +26,8 @@ __all__ = [
     "emit_round_progress",
     "emit_round_substrate_after",
     "emit_round_substrate_before",
+    "emit_schedule_paused",
+    "emit_schedule_resumed",
     "emit_stop_file_detected",
     "emit_transient_error_backoff_capped",
     "emit_transient_error_detected",
@@ -85,6 +87,28 @@ def emit_stop_file_detected(
     )
 
 
+def emit_schedule_paused(
+    log_dir: Path, *, active_window: str, resume_at: str, timezone: str
+) -> None:
+    """Emit schedule_paused when the serve loop enters a configured pause window."""
+    from agent_runner.events import SCHEDULE_PAUSED, emit
+
+    emit(
+        log_dir,
+        SCHEDULE_PAUSED,
+        active_window=active_window,
+        resume_at=resume_at,
+        timezone=timezone,
+    )
+
+
+def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
+    """Emit schedule_resumed when the serve loop exits a pause window."""
+    from agent_runner.events import SCHEDULE_RESUMED, emit
+
+    emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
+
+
 def emit_round_substrate_before(
     log_dir: Path, *, round_num: int, git_head: str | None, paths_hash: str | None
 ) -> None:

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.6'
-__version_tuple__ = version_tuple = (0, 2, 6)
+__version__ = version = '0.2.7'
+__version_tuple__ = version_tuple = (0, 2, 7)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/api.py

@@ -473,6 +473,7 @@ def peek(
         recent_events=recent,
         recent_hook_failures=recent_hook_failures,
         recent_blips=recent_blips,
+        schedule=monitor.latest_schedule_state(parsed_events),
     )
     return state if select is None else select_path(state, select)
 
@@ -746,6 +747,8 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_round_progress,
     emit_round_substrate_after,
     emit_round_substrate_before,
+    emit_schedule_paused,
+    emit_schedule_resumed,
     emit_stop_file_detected,
     emit_transient_error_backoff_capped,
     emit_transient_error_detected,

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/api_types.py

@@ -98,6 +98,7 @@ class ProjectState:
     recent_events: list[dict[str, Any]] = field(default_factory=list)
     recent_hook_failures: list[dict[str, Any]] = field(default_factory=list)
     recent_blips: list[dict[str, Any]] = field(default_factory=list)
+    schedule: dict | None = None
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/cli/serve_cmd.py

@@ -17,6 +17,7 @@ import sys
 import time
 from pathlib import Path
 
+from agent_runner import schedule
 from agent_runner._substrate import compute_git_head, compute_paths_hash
 from agent_runner._throttle import _check_throttle_state
 from agent_runner._throttle import reset_counters as _reset_counters
@@ -30,6 +31,8 @@ from agent_runner.api import (
     emit_round_logs_prune_deferred,
     emit_round_substrate_after,
     emit_round_substrate_before,
+    emit_schedule_paused,
+    emit_schedule_resumed,
     emit_stop_file_detected,
     post_round_decision,
 )
@@ -58,6 +61,68 @@ def _resolve_max_rounds(*, cli_value: int | None, config_value: int | None) -> i
     return effective
 
 
+def _maybe_pause_for_schedule(
+    cfg,
+    log_dir,
+    stop,
+    *,
+    now_fn=schedule.now_in_zone,
+    sleep_fn=time.sleep,
+    chunk_s: int = 30,
+) -> bool:
+    """If the current time is outside the run schedule, pause until it opens.
+
+    Returns True if a pause was entered (caller should ``continue`` so the
+    top-of-loop guards re-run), False if runnable now. During a pause, sleeps
+    in <= chunk_s slices so SIGTERM / SIGINT (which set stop["requested"]) lands
+    within one slice.
+
+    We do NOT check the self-terminate sentinel here: no round runs during a
+    pause, so no new sentinel can appear, and any pre-existing one already broke
+    the loop at its top before this gate. schedule_resumed is emitted ONLY when
+    the window actually opens — an interrupted pause (stop) is a termination, not
+    a resume, and correctly leaves schedule_paused as the newest event."""
+    sched = cfg.schedule
+    if not sched.enabled:
+        return False
+    decision = schedule.evaluate(
+        run_windows=sched.run_windows,
+        pause_windows=sched.pause_windows,
+        now_local=now_fn(sched.timezone),
+    )
+    if not decision.paused:
+        return False
+
+    started = time.monotonic()
+    emit_schedule_paused(
+        log_dir,
+        active_window=decision.active_window or "",
+        resume_at=decision.resume_at.isoformat() if decision.resume_at else "",
+        timezone=sched.timezone or "local",
+    )
+    stop_file = cfg.runtime.stop_file
+    window_opened = False
+    while not stop["requested"]:
+        if stop_file is not None and stop_file.exists():
+            # Operator stop_file dropped mid-pause: break without emitting
+            # schedule_resumed (the window did not open). The serve loop's
+            # top-of-loop stop_file check then emits stop_file_detected and exits.
+            break
+        # #3: should_run (not evaluate) avoids the 8-day next_resume_at scan on
+        # every poll; should_run is the negation of the pre-loop paused decision.
+        if schedule.should_run(
+            now_fn(sched.timezone),
+            run_windows=sched.run_windows,
+            pause_windows=sched.pause_windows,
+        ):
+            window_opened = True
+            break
+        sleep_fn(chunk_s)
+    if window_opened:
+        emit_schedule_resumed(log_dir, paused_for_s=int(time.monotonic() - started))
+    return True
+
+
 def _prune_serve_round_logs(log_dir: Path, retention: int) -> None:
     """Prune the serve-level ``round-<N>.log`` family; report a deferred prune.
 
@@ -101,6 +166,11 @@ def add_parser(sub, parent) -> None:
     p = sub.add_parser("serve", parents=[parent], help="Long-running supervisor loop")
     p.add_argument("--once", action="store_true", help="Run a single round then exit (debug)")
     _add_max_rounds_arg(p)
+    p.add_argument(
+        "--ignore-schedule",
+        action="store_true",
+        help="Run rounds regardless of [schedule] pause/run windows (testing / catch-up)",
+    )
     p.set_defaults(func=cmd)
 
 
@@ -177,6 +247,8 @@ def cmd(args) -> int:
                     max_rounds=effective_max_rounds,
                 )
                 break
+            if not args.ignore_schedule and _maybe_pause_for_schedule(cfg, log_dir, stop):
+                continue
             round_num = next_round_num(log_dir)
             git_head_before = compute_git_head(work_dir)
             paths_hash_before = compute_paths_hash(

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/config.py

@@ -8,6 +8,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
+from agent_runner import schedule
+
 _VALID_INJECTION_MODES: frozenset[str] = frozenset({"prepend", "file", "none"})
 _VALID_DIRTY_ACTIONS: frozenset[str] = frozenset({"stash", "ignore", "auto_commit"})
 _VALID_TRANSIENT_ERROR_ACTIONS: frozenset[str] = frozenset({"back_off", "skip", "stop"})
@@ -168,6 +170,17 @@ class MonitorConfig:
     """
 
 
+@dataclass(frozen=True)
+class ScheduleConfig:
+    timezone: str | None = None  # IANA name; None = host local time
+    run_windows: tuple[schedule.Window, ...] = ()
+    pause_windows: tuple[schedule.Window, ...] = ()
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.run_windows or self.pause_windows)
+
+
 @dataclass(frozen=True)
 class Config:
     agent: AgentConfig
@@ -177,6 +190,7 @@ class Config:
     monitor: MonitorConfig = field(default_factory=MonitorConfig)
     phases: PhasesConfig = field(default_factory=PhasesConfig)
     plugins: PluginsConfig = field(default_factory=PluginsConfig)
+    schedule: ScheduleConfig = field(default_factory=ScheduleConfig)
 
 
 def _require(d: dict, *path: str) -> object:
@@ -357,6 +371,32 @@ def _parse_fresh_eyes_every_n(runtime_d: dict) -> int | None:
     return _require_positive_int(raw, field="runtime.fresh_eyes_every_n")
 
 
+def _parse_schedule(schedule_d: dict) -> ScheduleConfig:
+    tz = schedule_d.get("timezone")
+    if tz is not None:
+        tz = str(tz)
+        if not schedule.valid_timezone(tz):
+            raise ConfigError(f"schedule.timezone: unknown IANA zone {tz!r}")
+
+    def _parse_list(key: str) -> tuple[schedule.Window, ...]:
+        raw = schedule_d.get(key, [])
+        if not isinstance(raw, list):
+            raise ConfigError(f"schedule.{key} must be a list of window strings")
+        out = []
+        for w in raw:
+            try:
+                out.append(schedule.parse_window(str(w)))
+            except ValueError as e:
+                raise ConfigError(f"schedule.{key}: {e}") from e
+        return tuple(out)
+
+    return ScheduleConfig(
+        timezone=tz,
+        run_windows=_parse_list("run_windows"),
+        pause_windows=_parse_list("pause_windows"),
+    )
+
+
 def load_config(toml_path: Path) -> Config:
     if not toml_path.exists():
         raise FileNotFoundError(f"config not found: {toml_path}")
@@ -571,6 +611,8 @@ def load_config(toml_path: Path) -> Config:
     disable = list(plugins_raw.pop("disable", []))
     plugins = PluginsConfig(disable=disable, raw=plugins_raw)
 
+    schedule_cfg = _parse_schedule(raw.get("schedule", {}))
+
     cfg = Config(
         agent=agent,
         runtime=runtime,
@@ -579,6 +621,7 @@ def load_config(toml_path: Path) -> Config:
         monitor=monitor,
         phases=phases_cfg,
         plugins=plugins,
+        schedule=schedule_cfg,
     )
 
     # Honor [plugins] disable — must happen after registries are populated by

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/events.py

@@ -61,6 +61,8 @@ ROUND_START = "round_start"
 ROUND_SUBSTRATE_AFTER = "round_substrate_after"
 ROUND_SUBSTRATE_BEFORE = "round_substrate_before"
 ROUND_TIMEOUT_KILL = "round_timeout_kill"
+SCHEDULE_PAUSED = "schedule_paused"
+SCHEDULE_RESUMED = "schedule_resumed"
 SELF_TERMINATED = "agent_self_terminated"
 SERVE_STARTUP_HOOK_FAILED = "serve_startup_hook_failed"
 SERVICE_UPGRADE_ROLLBACK_FAILED = "service_upgrade_rollback_failed"

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/agent_runner/monitor.py

@@ -22,7 +22,7 @@ import time
 from collections import deque
 from collections.abc import Iterable
 from dataclasses import dataclass
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from typing import Any, Protocol
 
@@ -48,6 +48,8 @@ from agent_runner.events import (
     ORPHAN_STASHED,
     ROUND_END,
     ROUND_START,
+    SCHEDULE_PAUSED,
+    SCHEDULE_RESUMED,
     TRANSIENT_ERROR_DETECTED,
     TRANSIENT_ERROR_RECOVERED,
     now_iso_ms,
@@ -447,6 +449,16 @@ def detect_anomaly_repetitive_active(
     )
 
 
+def _latest_schedule_event(events: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Newest schedule_paused/schedule_resumed event by stream order, or None.
+
+    Reverse-walk with early break — events grows unboundedly over a project's life."""
+    for e in reversed(events):
+        if e.get("event") in (SCHEDULE_PAUSED, SCHEDULE_RESUMED):
+            return e
+    return None
+
+
 def detect_supervisor_stale(
     events: list[dict[str, Any]],
     *,
@@ -471,6 +483,30 @@ def detect_supervisor_stale(
     age_s = (now - parse_iso_ms(last_ts_str)).total_seconds()
     if age_s <= stale_threshold_s:
         return None
+
+    newest = _latest_schedule_event(events)
+    if newest is not None and newest.get("event") == SCHEDULE_PAUSED:
+        # Suppress only while the pause is plausibly still live: until its
+        # announced resume_at plus one staleness window. A supervisor that died
+        # mid-pause therefore still alarms once that bound passes.
+        paused = newest
+        bound = None
+        try:
+            resume_dt = parse_iso_ms(paused.get("resume_at") or "")
+            if resume_dt.tzinfo is not None:
+                bound = resume_dt
+        except (ValueError, TypeError):
+            bound = None
+        if bound is None:
+            # No usable resume_at (empty/unparseable/naive) → bound by the pause's
+            # own timestamp + the 8-day resume horizon, so an always-paused config
+            # is not a permanent silent-death blind spot.
+            try:
+                bound = parse_iso_ms(paused["ts"]) + timedelta(days=8)
+            except (KeyError, ValueError, TypeError):
+                return None  # truly no anchor → suppress conservatively
+        if now <= bound + timedelta(seconds=stale_threshold_s):
+            return None
     return _alert(
         "supervisor_stale",
         "warning",
@@ -480,6 +516,21 @@ def detect_supervisor_stale(
     )
 
 
+def latest_schedule_state(events: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """Current schedule-pause state derived from the event stream.
+
+    Returns None when there is no pause in effect (no schedule events, or the
+    newest one is a resume). When paused, returns the paused indicator dict."""
+    newest = _latest_schedule_event(events)
+    if newest is None or newest.get("event") != SCHEDULE_PAUSED:
+        return None
+    return {
+        "paused": True,
+        "resume_at": newest.get("resume_at", ""),
+        "active_window": newest.get("active_window", ""),
+    }
+
+
 # ---------------------------------------------------------------------------
 # State-tree assembly (Task 3.2)
 # ---------------------------------------------------------------------------

cli_agent_runner-0.2.7/agent_runner/schedule.py

@@ -0,0 +1,178 @@
+"""Time-window scheduling core (pure). The serve loop uses this to decide,
+between rounds, whether to run the next round now or idle-sleep until a
+configured window opens. All functions are clock-injectable for testing."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+_WINDOW_RE = re.compile(r"^(\d{2}):(\d{2})-(\d{2}):(\d{2})$")
+_MINUTES_PER_DAY = 24 * 60
+_WEEKDAYS = {"mon": 0, "tue": 1, "wed": 2, "thu": 3, "fri": 4, "sat": 5, "sun": 6}
+_SEARCH_HORIZON_MIN = 8 * _MINUTES_PER_DAY  # weekday-scoped run_windows can pause a full weekend
+
+
+def _parse_weekday_spec(spec: str) -> frozenset[int]:
+    days: set[int] = set()
+    for token in spec.split(","):
+        token = token.strip().lower()
+        if not token:
+            raise ValueError(f"empty weekday token in {spec!r}")
+        if "-" in token:
+            a, _, b = token.partition("-")
+            if a not in _WEEKDAYS or b not in _WEEKDAYS:
+                raise ValueError(f"invalid weekday range {token!r}")
+            start, end = _WEEKDAYS[a], _WEEKDAYS[b]
+            if start > end:
+                raise ValueError(f"weekday range must be ascending Mon..Sun: {token!r}")
+            days.update(range(start, end + 1))
+        elif token not in _WEEKDAYS:
+            raise ValueError(f"invalid weekday {token!r}")
+        else:
+            days.add(_WEEKDAYS[token])
+    return frozenset(days)
+
+
+@dataclass(frozen=True)
+class Window:
+    start_min: int  # minutes from midnight, [0, 1440)
+    end_min: int  # minutes from midnight, (0, 1440]
+    label: str  # original "[WEEKDAYS ]HH:MM-HH:MM" for event payloads
+    days: frozenset[int] = frozenset()  # empty = every day
+
+    def contains(self, weekday: int, minute: int) -> bool:
+        wraps = self.start_min >= self.end_min
+        if wraps:  # spans past midnight
+            in_time = minute >= self.start_min or minute < self.end_min
+        else:
+            in_time = self.start_min <= minute < self.end_min
+        if not in_time:
+            return False
+        if not self.days:
+            return True
+        start_day = weekday
+        if wraps and minute < self.end_min:
+            start_day = (weekday - 1) % 7  # wrapped tail belongs to the start day
+        return start_day in self.days
+
+
+def _to_minutes(h: int, m: int, *, allow_24: bool, where: str) -> int:
+    if h == 24:
+        if not allow_24 or m != 0:
+            raise ValueError(f"{where}: 24:00 is only valid as an end bound")
+        return _MINUTES_PER_DAY
+    if not 0 <= h <= 23:
+        raise ValueError(f"{where}: hour {h} out of range")
+    if not 0 <= m <= 59:
+        raise ValueError(f"{where}: minute {m} out of range")
+    return h * 60 + m
+
+
+def parse_window(s: str) -> Window:
+    spec = s.strip()
+    days: frozenset[int] = frozenset()
+    parts = spec.split(None, 1)
+    if len(parts) == 2 and _WINDOW_RE.match(parts[1]):
+        days = _parse_weekday_spec(parts[0])
+        time_part = parts[1]
+    else:
+        time_part = spec
+    match = _WINDOW_RE.match(time_part)
+    if not match:
+        raise ValueError(f"invalid window {s!r}: expected [WEEKDAYS ]HH:MM-HH:MM")
+    sh, sm, eh, em = (int(g) for g in match.groups())
+    start = _to_minutes(sh, sm, allow_24=False, where=f"window {s!r} start")
+    end = _to_minutes(eh, em, allow_24=True, where=f"window {s!r} end")
+    if start == end:
+        raise ValueError(f"invalid window {s!r}: start equals end (zero-length)")
+    return Window(start_min=start, end_min=end, label=s, days=days)
+
+
+def _minute_of_day(now_local: datetime) -> int:
+    return now_local.hour * 60 + now_local.minute
+
+
+def should_run(
+    now_local: datetime,
+    *,
+    run_windows: Sequence[Window],
+    pause_windows: Sequence[Window],
+) -> bool:
+    minute = _minute_of_day(now_local)
+    weekday = now_local.weekday()
+    in_run = (not run_windows) or any(w.contains(weekday, minute) for w in run_windows)
+    in_pause = any(w.contains(weekday, minute) for w in pause_windows)
+    return in_run and not in_pause
+
+
+def next_resume_at(
+    now_local: datetime,
+    *,
+    run_windows: Sequence[Window],
+    pause_windows: Sequence[Window],
+) -> datetime | None:
+    """First minute-boundary within the next 8 days where should_run flips True.
+    Called only while currently paused; returns None if no window opens in 8 days."""
+    base = now_local.replace(second=0, microsecond=0)
+    for k in range(1, _SEARCH_HORIZON_MIN + 1):
+        cand = base + timedelta(minutes=k)
+        if should_run(cand, run_windows=run_windows, pause_windows=pause_windows):
+            return cand
+    return None
+
+
+def _active_window_label(
+    now_local: datetime,
+    *,
+    run_windows: Sequence[Window],
+    pause_windows: Sequence[Window],
+) -> str:
+    minute = _minute_of_day(now_local)
+    weekday = now_local.weekday()
+    for w in pause_windows:
+        if w.contains(weekday, minute):
+            return w.label
+    return "outside run_windows"
+
+
+@dataclass(frozen=True)
+class PauseDecision:
+    paused: bool
+    resume_at: datetime | None
+    active_window: str | None
+
+
+def evaluate(
+    *,
+    run_windows: Sequence[Window],
+    pause_windows: Sequence[Window],
+    now_local: datetime,
+) -> PauseDecision:
+    if should_run(now_local, run_windows=run_windows, pause_windows=pause_windows):
+        return PauseDecision(paused=False, resume_at=None, active_window=None)
+    return PauseDecision(
+        paused=True,
+        resume_at=next_resume_at(now_local, run_windows=run_windows, pause_windows=pause_windows),
+        active_window=_active_window_label(
+            now_local, run_windows=run_windows, pause_windows=pause_windows
+        ),
+    )
+
+
+def now_in_zone(tz_name: str | None) -> datetime:
+    """Timezone-aware now. tz_name None → host local time."""
+    if tz_name is None:
+        return datetime.now().astimezone()
+    return datetime.now(ZoneInfo(tz_name))
+
+
+def valid_timezone(tz_name: str) -> bool:
+    try:
+        ZoneInfo(tz_name)
+    except (ZoneInfoNotFoundError, ValueError):
+        return False
+    return True

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.7}/docs/architecture.md

@@ -226,6 +226,8 @@ See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
 - `round_substrate_after`
 - `round_substrate_before`
 - `round_timeout_kill`
+- `schedule_paused`
+- `schedule_resumed`
 - `serve_startup_hook_failed`
 - `service_upgrade_rollback_failed`
 - `service_upgrade_rolled_back`