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

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.8}/.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
@@ -225,6 +232,16 @@ stash_idempotency_s
 # agent_runner.lifecycle.PIDFile
 path
 
+# agent_runner.migrations.Migration
+detect
+apply
+describe
+
+# agent_runner.migrations.MigrationResult
+new_text
+applied
+manual
+
 # agent_runner.monitor.LocalSource
 log_dir
 
@@ -233,6 +250,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.8}/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.8] - 2026-08-25
+
+### Added
+- `agent-runner migrate [--dry-run]` rewrites removed/renamed fields in `agent-runner.toml` to their current form, keeping a `.bak`; reports fields needing a manual change.
+- `upgrade` auto-migrates the config before the package/service step and emits a `config_migrated` event; a config needing a manual change aborts the run before it stops the service. `--no-migrate` skips it.
+
+### Changed
+- Removed-field `ConfigError` messages now point to `agent-runner migrate`.
+
+See `docs/migrations/0.2.8.md`.
+
+## [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.8}/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.8
 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
@@ -51,7 +51,7 @@ full disks, runaway memory.
 ┌──────────────────────────────────────────┐
 │ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
-│ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
+│ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
 │ Layer 1: The Round (round)               │  one agent invocation
 └──────────────────────────────────────────┘
@@ -80,14 +80,15 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 15 verbs
+## 16 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
-| `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
+| `round` / `serve` | `events` — query / stream events.jsonl |
+| `upgrade` / `migrate` | |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
@@ -106,6 +107,10 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
+Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
+`serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
+of [`docs/configuration.md`](docs/configuration.md).
+
 ## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.8}/README.md

@@ -15,7 +15,7 @@ full disks, runaway memory.
 ┌──────────────────────────────────────────┐
 │ Layer 3: The Witness (monitor)           │  11 detectors + auto-stop
 ├──────────────────────────────────────────┤
-│ Layer 2: The Loop (serve, ~120 LOC)      │  signal-trapping restart loop
+│ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
 │ Layer 1: The Round (round)               │  one agent invocation
 └──────────────────────────────────────────┘
@@ -44,14 +44,15 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 15 verbs
+## 16 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
-| `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
+| `round` / `serve` | `events` — query / stream events.jsonl |
+| `upgrade` / `migrate` | |
 
 Verb reference: [`docs/commands.md`](docs/commands.md).
 
@@ -70,6 +71,10 @@ guards it. Highlights:
 
 Full list and rationale: [`docs/architecture.md`](docs/architecture.md).
 
+Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
+`serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
+of [`docs/configuration.md`](docs/configuration.md).
+
 ## Monitor: 11 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.8}/agent_runner/_docgen.py

@@ -7,12 +7,16 @@ renderer registry so the substitution rule is testable in isolation.
 
 from __future__ import annotations
 
+import argparse
 import dataclasses
+import functools
+import importlib.resources
 import re
 import typing
 from collections.abc import Callable
 from pathlib import Path
 
+from agent_runner.cli.init_cmd import _preset_names
 from agent_runner.config import (
     AgentConfig,
     Config,
@@ -22,6 +26,7 @@ from agent_runner.config import (
     PluginsConfig,
     PromptConfig,
     RuntimeConfig,
+    ScheduleConfig,
     VcsConfig,
 )
 from agent_runner.defenses import catalog
@@ -45,6 +50,7 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
     ("monitor", MonitorConfig, [("monitor.host_health", MonitorHostHealthConfig)]),
     ("phases", PhasesConfig, []),
     ("plugins", PluginsConfig, []),
+    ("schedule", ScheduleConfig, []),
 ]
 
 
@@ -150,18 +156,53 @@ def render_event_kinds_list() -> str:
     return "\n".join(f"- `{k}`" for k in sorted(KNOWN_EVENT_KINDS))
 
 
-def render_verb_table() -> str:
-    """Walk the argparse subparsers and render a verb table."""
+def _subparser_action() -> argparse.Action:
+    """The single ``_SubParsersAction`` on the top-level parser."""
     from agent_runner.cli import _build_parser
 
     parser = _build_parser()
-    # Find the sub-parsers action — there's exactly one.
-    sub_action = next(a for a in parser._actions if a.__class__.__name__ == "_SubParsersAction")
+    return next(a for a in parser._actions if a.__class__.__name__ == "_SubParsersAction")
+
+
+def _subparser_choices() -> dict[str, argparse.ArgumentParser]:
+    """Map ``verb -> subparser`` for the CLI, the SSOT both verb renderers use."""
+    return _subparser_action().choices
+
+
+def _render_verb_flags(verb: str) -> str:
+    """Bullet list of a verb's own option flags, from its argparse subparser.
+
+    Parent-inherited ``--config`` / ``--json`` carry ``help=SUPPRESS`` on the
+    shared parent and are filtered here, so only verb-specific flags render.
+    """
+    choices = _subparser_choices()
+    lines: list[str] = []
+    for act in choices[verb]._actions:
+        if not act.option_strings:  # positionals
+            continue
+        if isinstance(act, argparse._HelpAction):  # -h/--help
+            continue
+        if act.help is argparse.SUPPRESS:  # parent --config/--json
+            continue
+        name = max(act.option_strings, key=len)
+        if act.choices:
+            val = " {" + ",".join(map(str, act.choices)) + "}"
+        elif act.metavar:
+            val = f" {act.metavar}"
+        else:
+            val = ""
+        lines.append(f"- `{name}{val}` — {act.help}")
+    return "\n".join(lines)
+
+
+def render_verb_table() -> str:
+    """Walk the argparse subparsers and render a verb table."""
+    sub_action = _subparser_action()
     rows = [
         "| Verb | Description |",
         "|---|---|",
     ]
-    for verb, _sp in sub_action.choices.items():
+    for verb in sub_action.choices:
         # Argparse stores help text via `sub_action._choices_actions` indexed by add order.
         help_text = (
             next(
@@ -174,6 +215,18 @@ def render_verb_table() -> str:
     return "\n".join(rows)
 
 
+def _render_preset(name: str) -> str:
+    """Fenced TOML block quoting a shipped ``agent_runner/presets/<name>.toml``.
+
+    The preset file is the SSOT; the recipe doc block is a verbatim mirror so a
+    flag or auth-hint edit in the preset can never drift from its recipe.
+    """
+    body = (importlib.resources.files("agent_runner.presets") / f"{name}.toml").read_text(
+        encoding="utf-8"
+    )
+    return "```toml\n" + body.rstrip() + "\n```"
+
+
 RENDERERS: dict[str, Callable[[], str]] = {
     "defenses-table": render_defenses_table,
     "detector-list": render_detector_list,
@@ -181,6 +234,13 @@ RENDERERS: dict[str, Callable[[], str]] = {
     "config-schema": render_config_schema_table,
     "verb-table": render_verb_table,
 }
+RENDERERS.update(
+    {
+        f"flags-{v}": functools.partial(_render_verb_flags, v)
+        for v in ("init", "monitor", "serve", "migrate")
+    }
+)
+RENDERERS.update({f"preset-{n}": functools.partial(_render_preset, n) for n in _preset_names()})
 
 _GEN_OPEN = re.compile(r"<!-- gen:([a-z0-9-]+) -->")
 
@@ -194,7 +254,9 @@ def render(docs_dir: Path, *, write: bool = True) -> dict[Path, str]:
     Raises ``ValueError`` when a marker references an unknown renderer name.
     """
     out: dict[Path, str] = {}
-    for md in sorted(docs_dir.glob("*.md")):
+    # Top-level docs plus recipes/. NOT rglob: migrations/ is frozen history and
+    # internal/ is gitignored — neither should be regenerated.
+    for md in sorted(docs_dir.glob("*.md")) + sorted((docs_dir / "recipes").glob("*.md")):
         text = md.read_text(encoding="utf-8")
         for match in _GEN_OPEN.finditer(text):
             name = match.group(1)

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

@@ -17,6 +17,7 @@ __all__ = [
     "emit_agent_auth_error_detected",
     "emit_agent_usage_recorded",
     "emit_anomaly_repetitive_tool",
+    "emit_config_migrated",
     "emit_fresh_eyes_round_triggered",
     "emit_max_rounds_reached",
     "emit_rate_limit_stop",
@@ -26,6 +27,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",
@@ -70,6 +73,15 @@ def emit_crash_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path
     emit(log_dir, CRASH_LOOP, consecutive=consecutive, exit_code=exit_code, reason=reason)
 
 
+def emit_config_migrated(
+    log_dir: Path, *, applied: list[str], manual: list[str], path: str
+) -> None:
+    """Emit config_migrated when `migrate`/`upgrade` rewrites the config."""
+    from agent_runner.events import CONFIG_MIGRATED, emit
+
+    emit(log_dir, CONFIG_MIGRATED, applied=applied, manual=manual, path=path)
+
+
 def emit_stop_file_detected(
     log_dir: Path, *, stop_file: Path, content: str, rounds_completed: int
 ) -> None:
@@ -85,6 +97,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.8}/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.8'
+__version_tuple__ = version_tuple = (0, 2, 8)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.8}/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)
 
@@ -736,6 +737,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_agent_usage_recorded,
     emit_anomaly_repetitive_tool,
     emit_config_broken,
+    emit_config_migrated,
     emit_crash_loop,
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
@@ -746,6 +748,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.8}/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.8}/agent_runner/cli/__init__.py

@@ -20,6 +20,7 @@ from agent_runner.cli import (
     events_cmd,
     init_cmd,
     install_cmd,
+    migrate_cmd,
     monitor_cmd,
     peek_cmd,
     round_cmd,
@@ -69,6 +70,7 @@ def _build_parser() -> argparse.ArgumentParser:
     serve_cmd.add_parser(sub, parent)
     round_cmd.add_parser(sub, parent)
     upgrade_cmd.add_parser(sub, parent)
+    migrate_cmd.add_parser(sub, parent)
 
     return parser
 

cli_agent_runner-0.2.8/agent_runner/cli/migrate_cmd.py

@@ -0,0 +1,51 @@
+"""agent-runner migrate — rewrite removed/renamed config fields to current form."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from agent_runner import migrations
+from agent_runner.cli.common import fail  # `fail(msg, *, code=1)` prints to stderr, returns code
+
+
+def add_parser(sub, parent) -> None:
+    p = sub.add_parser(
+        "migrate",
+        parents=[parent],
+        help="Rewrite removed/renamed fields in agent-runner.toml to current form",
+    )
+    p.add_argument("--dry-run", action="store_true", help="Show changes without writing the file")
+    p.set_defaults(func=cmd)
+
+
+def cmd(args) -> int:
+    cfg_path = Path(getattr(args, "config", None) or "agent-runner.toml")
+    try:
+        text = cfg_path.read_text(encoding="utf-8")
+    except OSError as e:
+        return fail(f"cannot read {cfg_path}: {e}", code=2)
+    try:
+        parsed = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        return fail(f"{cfg_path} is not valid TOML: {e}", code=2)
+
+    result = migrations.run_migrations(text, parsed)
+    if not result.applied and not result.manual:
+        print(f"{cfg_path}: nothing to migrate")
+        return 0
+
+    for line in result.applied:
+        print(f"  rewrite: {line}")
+    for line in result.manual:
+        print(f"  MANUAL:  {line}")
+
+    if args.dry_run:
+        print("(dry-run — no changes written)")
+        return 1 if result.manual else 0
+
+    if result.applied:
+        cfg_path.with_suffix(cfg_path.suffix + ".bak").write_text(text, encoding="utf-8")
+        cfg_path.write_text(result.new_text, encoding="utf-8")
+        print(f"wrote {cfg_path} (backup: {cfg_path.name}.bak)")
+    return 1 if result.manual else 0

{cli_agent_runner-0.2.6 → cli_agent_runner-0.2.8}/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(