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

{cli_agent_runner-0.2.5 → 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
@@ -228,6 +235,22 @@ path
 # agent_runner.monitor.LocalSource
 log_dir
 
+# agent_runner.round_log.PruneOutcome
+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.5 → cli_agent_runner-0.2.7}/CHANGELOG.md

@@ -5,6 +5,31 @@ 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
+- **Round-log pruning is now opt-in.** `runtime.round_log_retention` defaults to `0` (never prune) and `0` is now a legal value — previously both `0` and `-1` were rejected, so there was no off switch. Retaining too much is defended (`disk_warning` at 90%, `disk_critical` at 95% auto-stops the service); deleting too much was not defended at all. Both round-log families are affected, including the serve-level `round-<N>.log` family that had been capped at 100 for many releases. Set `round_log_retention = 100` for the previous behavior.
+
+### Fixed
+- A prune that would delete more files than it keeps is now refused wholesale — nothing is deleted — so opting in on an existing backlog, or lowering the value later, can no longer wipe history in one pass. 0.2.4 and 0.2.5 did exactly that on their first post-upgrade round (one deployment: 12,193 of 12,293 transcripts, ~6.4 GB).
+
+### Added
+- `round_logs_prune_deferred` event — emitted on every prune attempt the bulk guard defers, carrying `directory`, `existing`, `keep`, `would_delete` and a hint naming `runtime.round_log_retention`. Resolve by raising retention above the backlog or deleting the files yourself; the guard never blocks a round. Retention `0` emits nothing.
+
+See `docs/migrations/0.2.6.md`.
+
 ## [0.2.5] - 2026-07-27
 
 ### Added
@@ -950,7 +975,8 @@ Initial public release on PyPI as `cli-agent-runner`.
 - Tag-triggered release publishing to PyPI via Trusted Publishing OIDC,
   gated by a manual approval on the `pypi` GitHub environment.
 
-[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.6...HEAD
+[0.2.6]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.2...v0.2.3

{cli_agent_runner-0.2.5 → 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.5
+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
@@ -93,7 +93,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-12 named defenses, structured as data — see `agent-runner peek --select defenses`.
+13 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.7}/README.md

@@ -57,7 +57,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-12 named defenses, structured as data — see `agent-runner peek --select defenses`.
+13 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

{cli_agent_runner-0.2.5 → 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.5 → cli_agent_runner-0.2.7}/agent_runner/_emit.py

@@ -22,9 +22,12 @@ __all__ = [
     "emit_rate_limit_stop",
     "emit_round_grace_extended",
     "emit_round_grace_kill",
+    "emit_round_logs_prune_deferred",
     "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",
@@ -84,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:
@@ -346,6 +371,42 @@ def emit_round_grace_extended(
     )
 
 
+def emit_round_logs_prune_deferred(
+    log_dir: Path,
+    *,
+    directory: str,
+    existing: int,
+    keep: int,
+    would_delete: int,
+) -> None:
+    """Emit when a round-log prune was deferred because it would be *bulk*
+    (it would delete more files than it keeps), so nothing was deleted.
+
+    ``directory`` is the directory holding the family — ``{log_dir}/rounds``
+    for agent transcripts, ``{log_dir}`` for the serve-level ``round-<N>.log``
+    files. Re-emitted on every prune attempt while the condition holds: the
+    deferral is permanent until an operator acts, and a one-shot event would
+    be missed by anyone who started watching later.
+
+    The hint is composed here rather than at the call sites so both families
+    name the same knob with the same wording.
+    """
+    from agent_runner.events import ROUND_LOGS_PRUNE_DEFERRED, emit
+
+    emit(
+        log_dir,
+        ROUND_LOGS_PRUNE_DEFERRED,
+        directory=directory,
+        existing=existing,
+        keep=keep,
+        would_delete=would_delete,
+        hint=(
+            f"nothing deleted; raise runtime.round_log_retention to >= {existing} "
+            f"to keep this backlog, or delete files in {directory} yourself"
+        ),
+    )
+
+
 def emit_anomaly_repetitive_tool(
     log_dir: Path,
     *,

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

{cli_agent_runner-0.2.5 → 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)
 
@@ -742,9 +743,12 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_rate_limit_stop,
     emit_round_grace_extended,
     emit_round_grace_kill,
+    emit_round_logs_prune_deferred,
     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.5 → 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.5 → cli_agent_runner-0.2.7}/agent_runner/cli/serve_cmd.py

@@ -15,7 +15,9 @@ import signal
 import subprocess  # noqa: TID251
 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
@@ -26,8 +28,11 @@ from agent_runner.api import (
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
+    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,
 )
@@ -56,6 +61,86 @@ 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.
+
+    A prune that would delete more files than it keeps is deferred wholesale
+    (nothing is deleted) and surfaced as ``round_logs_prune_deferred`` — the
+    same contract ``rounds/`` gets at round start, since one knob governs both.
+    """
+    outcome = prune_old_round_logs(log_dir, retention)
+    if outcome.deferred:
+        emit_round_logs_prune_deferred(
+            log_dir,
+            directory=str(log_dir),
+            existing=outcome.existing,
+            keep=retention,
+            would_delete=outcome.deferred,
+        )
+
+
 def _is_fresh_eyes_round(*, round_num: int, every_n: int | None) -> bool:
     """True if this round should signal fresh-eyes mode to the agent subprocess.
 
@@ -81,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)
 
 
@@ -106,7 +196,7 @@ def cmd(args) -> int:
 
     # Pre-loop cleanup: remove stale sentinel, prune old round logs.
     (log_dir / ".agent-done").unlink(missing_ok=True)
-    prune_old_round_logs(log_dir, cfg.runtime.round_log_retention)
+    _prune_serve_round_logs(log_dir, cfg.runtime.round_log_retention)
 
     round_env = {**os.environ, "AGENT_RUNNER_LOG_DIR": str(log_dir)}
 
@@ -157,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.5 → 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"})
@@ -39,7 +41,7 @@ class RuntimeConfig:
     round_timeout_s: int = 1800
     restart_delay_s: int = 3
     disable_pre_round_hooks: bool = False
-    round_log_retention: int = 100
+    round_log_retention: int = 0  # 0 = never prune (pruning is opt-in)
     narrative_file: Path | None = None
     transient_error_action: Literal["back_off", "skip", "stop"] = "back_off"
     max_rounds: int | None = None  # None = unbounded
@@ -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}")
@@ -439,8 +479,8 @@ def load_config(toml_path: Path) -> Config:
             runtime_d.get("disable_pre_round_hooks", False),
             field="runtime.disable_pre_round_hooks",
         ),
-        round_log_retention=_require_positive_int(
-            runtime_d.get("round_log_retention", 100), field="runtime.round_log_retention"
+        round_log_retention=_require_non_negative_int(
+            runtime_d.get("round_log_retention", 0), field="runtime.round_log_retention"
         ),
         narrative_file=_expand_and_resolve(str(runtime_d["narrative_file"]), project_name, work_dir)
         if "narrative_file" in runtime_d
@@ -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.5 → cli_agent_runner-0.2.7}/agent_runner/defenses.py

@@ -102,6 +102,17 @@ def catalog(cfg: Config) -> list[Defense]:
             guarded_by=Path("tests/unit/test_serve_crash_loop.py"),
             current_state="active",
         ),
+        Defense(
+            name="bulk_round_log_prune_guard",
+            value="a prune deleting more files than it keeps deletes nothing",
+            codifies=(
+                "0.2.4 — rounds/ pruning shipped against backlogs it never built; "
+                "one deployment's first post-upgrade round would have deleted "
+                "12,193 of 12,293 transcripts silently"
+            ),
+            guarded_by=Path("tests/unit/test_round_log_helpers.py"),
+            current_state="active",
+        ),
         Defense(
             name="flock_concurrency",
             value="agent-runner.lock",

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

@@ -55,11 +55,14 @@ PROMPT_OVERWRITTEN = "prompt_overwritten"
 ROUND_END = "round_end"
 ROUND_GRACE_EXTENDED = "round_grace_extended"
 ROUND_GRACE_KILL = "round_grace_kill"
+ROUND_LOGS_PRUNE_DEFERRED = "round_logs_prune_deferred"
 ROUND_PROGRESS = "round_progress"
 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.5 → 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)
 # ---------------------------------------------------------------------------