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

{cli_agent_runner-0.2.4 → cli_agent_runner-0.2.6}/.github/workflows/release.yml

@@ -9,9 +9,13 @@ permissions:
 
 # Trusted Publishing: the `environment` name below MUST match the
 # `Environment name` field in the PyPI pending publisher config.
-# A mismatch fails publish with an opaque OIDC error.
-# Note: TestPyPI stage intentionally omitted — first release verification
-# happens via the manual approval gate on the `pypi` environment.
+# A mismatch fails publish with an opaque OIDC error. Keep the environment
+# declared even when it carries no protection rules — it is the OIDC claim,
+# not just an approval gate; deleting it breaks publishing outright. Whether
+# a tag publishes straight through or waits for a reviewer is configured in
+# the repo's environment settings, not here.
+# Note: TestPyPI stage intentionally omitted — the tag is the release signal;
+# pre-tag verification is `./build.sh check` plus the CI matrix on main.
 
 concurrency:
   group: release-${{ github.ref }}

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

@@ -228,9 +228,10 @@ path
 # agent_runner.monitor.LocalSource
 log_dir
 
-# agent_runner.monitor.RemoteSource
-host
-project
+# agent_runner.round_log.PruneOutcome
+deleted
+deferred
+existing
 
 # agent_runner.startup_check.CheckResult
 name

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

@@ -5,6 +5,30 @@ 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.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
+- `events --since <ISO ts>` — replays every matching event with `ts >= since`, across month files, one-shot or as the backlog phase of `--tail`. At-least-once: a client whose stream dropped reconnects with the last ts it saw and loses nothing (that one event may repeat).
+- `monitor --host <alias> --mode events` — a managed ssh event relay, replacing a hand-rolled `ssh … --tail; sleep` loop. Passes the remote's JSONL through unmodified, reconnects with `--since <last ts>` so a dropped link replays its gap, emits `monitor_remote_blip` per drop and `monitor_remote_giveup` + exit 1 once the outage passes `[monitor] remote_failure_tolerance_s`, and kills the ssh process GROUP on exit so no orphan tree survives. New flags `--kind` and `--remote-config`.
+
+### Removed
+- The polling remote monitor (`RemoteSource`, `run_remote_command`, `MonitorRemoteError`, auto-stop over ssh) — it read remote paths on the local filesystem and was already failing loud since 0.2.4. Detection is on-host by design; remote observation is the relay above. `monitor.on_alert` lost its `host` parameter and `monitor_auto_stop_triggered` its `host` field; `monitor_auto_stop_failed` now reports a failed *local* stop (previously a failed ssh stop) instead of crashing the monitor loop.
+
+See `docs/migrations/0.2.5.md`.
+
 ## [0.2.4] - 2026-07-27
 
 ### Added
@@ -648,6 +672,7 @@ No breaking changes. Plugin authors:
   between rounds, opt them out:
   ```python
   from agent_runner.vcs_state import register_plugin_owned_paths
+
   register_plugin_owned_paths(["your-output-dir/", "logs/your-plugin/**/*"])
   ```
 - If you followed the old `_register()` pattern from docs and noticed
@@ -938,7 +963,9 @@ 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.4...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
 [0.2.2]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.1...v0.2.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.4
+Version: 0.2.6
 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
@@ -28,7 +28,7 @@ Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Requires-Dist: vulture>=2.13; extra == 'dev'
 Provides-Extra: e2e
 Requires-Dist: pytest>=8; extra == 'e2e'
@@ -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:
 
@@ -123,13 +123,24 @@ agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-> **Remote monitoring is unsupported in this version**: `monitor --host <alias>`
-> cannot read a remote host's round logs or events, so it exits with an error at
-> startup instead of watching an empty world and reporting healthy. Run the
-> monitor on the supervised host itself (`ssh <alias>`, then `agent-runner
-> monitor`). See [`docs/runbook.md`](docs/runbook.md) § "Remote monitor & SSH
-> trust" — the SSH trust boundary applies to any agent-runner command you drive
-> over ssh.
+Watch a remote host's event stream from your laptop — one command instead of a
+hand-rolled `ssh … ; sleep` loop:
+
+```bash
+agent-runner monitor --host pi --mode events   # managed ssh relay, JSONL stdout
+```
+
+The relay reconnects with `--since <last ts>` so a dropped link replays its gap,
+gives up (exit 1) once the outage passes `remote_failure_tolerance_s`, and kills
+the ssh process group on exit so no orphan tree is left behind.
+
+> **Detection stays on the host.** `--host` with `--mode anomaly | narrate |
+> http` exits with an error: the detectors read the supervised host's logs and
+> auto-stop its service, which must keep working with your laptop closed. Run
+> the monitor there (`ssh <alias>`, then `agent-runner monitor`) and relay its
+> events here. See [`docs/runbook.md`](docs/runbook.md) § "Remote event relay &
+> SSH trust" — the SSH trust boundary applies to any agent-runner command you
+> drive over ssh.
 
 ## Documentation
 

{cli_agent_runner-0.2.4 → cli_agent_runner-0.2.6}/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:
 
@@ -87,13 +87,24 @@ agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-> **Remote monitoring is unsupported in this version**: `monitor --host <alias>`
-> cannot read a remote host's round logs or events, so it exits with an error at
-> startup instead of watching an empty world and reporting healthy. Run the
-> monitor on the supervised host itself (`ssh <alias>`, then `agent-runner
-> monitor`). See [`docs/runbook.md`](docs/runbook.md) § "Remote monitor & SSH
-> trust" — the SSH trust boundary applies to any agent-runner command you drive
-> over ssh.
+Watch a remote host's event stream from your laptop — one command instead of a
+hand-rolled `ssh … ; sleep` loop:
+
+```bash
+agent-runner monitor --host pi --mode events   # managed ssh relay, JSONL stdout
+```
+
+The relay reconnects with `--since <last ts>` so a dropped link replays its gap,
+gives up (exit 1) once the outage passes `remote_failure_tolerance_s`, and kills
+the ssh process group on exit so no orphan tree is left behind.
+
+> **Detection stays on the host.** `--host` with `--mode anomaly | narrate |
+> http` exits with an error: the detectors read the supervised host's logs and
+> auto-stop its service, which must keep working with your laptop closed. Run
+> the monitor there (`ssh <alias>`, then `agent-runner monitor`) and relay its
+> events here. See [`docs/runbook.md`](docs/runbook.md) § "Remote event relay &
+> SSH trust" — the SSH trust boundary applies to any agent-runner command you
+> drive over ssh.
 
 ## Documentation
 

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

@@ -22,6 +22,7 @@ __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",
@@ -346,6 +347,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.4 → cli_agent_runner-0.2.6}/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.4'
-__version_tuple__ = version_tuple = (0, 2, 4)
+__version__ = version = '0.2.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
 
 __commit_id__ = commit_id = None

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

@@ -16,9 +16,9 @@ import signal
 import subprocess  # noqa: TID251 — api uses systemctl + ssh, both subprocess
 import sysconfig
 import time
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any, Literal, TextIO
 
 from agent_runner import events, lifecycle
 from agent_runner.api_types import (
@@ -383,8 +383,6 @@ from agent_runner import defenses, monitor  # noqa: E402
 from agent_runner.events import (  # noqa: E402
     AGENT_NETWORK_BLIP,
     HOOK_FAILED,
-    MONITOR_REMOTE_BLIP,
-    MONITOR_REMOTE_GIVEUP,
     MONITOR_STARTED,
 )
 
@@ -479,16 +477,13 @@ def peek(
     return state if select is None else select_path(state, select)
 
 
-def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
+def _poll_once(project: str | Path) -> list[monitor.Alert]:
     work_dir = project if isinstance(project, Path) else Path.cwd()
     cfg = load_config(work_dir / "agent-runner.toml")
-    src: monitor.StateSource
-    if host is None:
-        src = monitor.LocalSource(log_dir=cfg.runtime.log_dir)
-    else:
-        # Dormant: monitor_loop rejects --host before any poll, so this branch
-        # is unreachable today. See monitor.MonitorRemoteUnsupportedError.
-        src = monitor.RemoteSource(host=host, project=_project_name(work_dir))
+    # Always local: detection runs on the supervised host by design. Remote
+    # observation is an event RELAY (``monitor --host X --mode events``), not a
+    # remote poll — see agent_runner/remote_relay.py.
+    src: monitor.StateSource = monitor.LocalSource(log_dir=cfg.runtime.log_dir)
     events = monitor.parse_events_from_jsonl_files(src.events_files())
     metrics = monitor.parse_events_from_jsonl_files(src.metrics_files())
     log_tails = monitor.load_round_log_tails(src.rounds_dir())
@@ -512,11 +507,6 @@ def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
     return builtin + plugin
 
 
-# Backoff schedule for remote-failure retries: each element is the sleep duration
-# in seconds for that attempt index (capped at 30s per step).
-_REMOTE_FAILURE_BACKOFF = (1, 2, 4, 8, 16, 30)
-
-
 def monitor_loop(
     project: str | Path | None = None, *, host: str | None = None, interval_s: int = 30
 ) -> Iterator[monitor.Alert]:
@@ -527,11 +517,11 @@ def monitor_loop(
     to that kind as the canonical "supervision is up" signal (monitor is otherwise
     silent during healthy operation by design).
 
-    ``host`` (remote mode) raises ``MonitorRemoteUnsupportedError`` immediately:
-    remote reads are unimplemented, so a remote loop would poll an empty world
-    and report healthy forever. The check is eager — this wrapper validates
-    before handing back the generator, so the failure lands at startup rather
-    than at the first ``next()``.
+    ``host`` raises ``MonitorRemoteUnsupportedError`` immediately: detection runs
+    on the supervised host by design, so there is no remote polling mode. The
+    check is eager — this wrapper validates before handing back the generator,
+    so the failure lands at startup rather than at the first ``next()``. For a
+    remote event stream, see ``relay_remote_events``.
     """
     if host is not None:
         raise monitor.MonitorRemoteUnsupportedError(host)
@@ -543,13 +533,9 @@ def _monitor_loop_iter(
 ) -> Iterator[monitor.Alert]:
     """Polling generator behind ``monitor_loop``.
 
-    Tolerates transient ``MonitorRemoteError`` failures (from ``--host`` ssh)
-    for up to ``cfg.monitor.remote_failure_tolerance_s`` seconds with exponential
-    backoff (1s → 2s → 4s → ... → 30s cap). Each retry emits ``monitor_remote_blip``;
-    crossing the cap emits one ``monitor_remote_giveup`` and propagates the error
-    (CLI exits 1; systemd restarts the process). Setting tolerance to 0 preserves
-    the 0.1.10 immediate-propagate behavior with no blip events emitted. That
-    path is dormant while remote mode is rejected at startup.
+    ``host`` is None by construction (``monitor_loop`` rejects anything else);
+    it is carried into the ``monitor_started`` payload as an explicit record
+    that this monitor watches its own host.
     """
     import json as _json
 
@@ -566,51 +552,8 @@ def _monitor_loop_iter(
         mode="anomaly-only",
     )
 
-    tolerance_s = cfg.monitor.remote_failure_tolerance_s
-    blip_start: float | None = None
-    attempt = 0
-
     while True:
-        try:
-            alerts = _poll_once(work_dir, host=host)
-            # Success: reset retry state.
-            blip_start = None
-            attempt = 0
-        except monitor.MonitorRemoteError as e:
-            if tolerance_s == 0:
-                raise  # 0.1.10 behavior preserved
-            now = time.monotonic()
-            if blip_start is None:
-                blip_start = now
-            attempt += 1
-            elapsed = now - blip_start
-            if elapsed >= tolerance_s:
-                events.emit(
-                    cfg.runtime.log_dir,
-                    MONITOR_REMOTE_GIVEUP,
-                    host=host,
-                    total_attempts=attempt,
-                    total_elapsed_s=elapsed,
-                    cap_s=tolerance_s,
-                    final_error=e.stderr,
-                )
-                raise
-            backoff_idx = min(attempt - 1, len(_REMOTE_FAILURE_BACKOFF) - 1)
-            next_sleep_s = min(_REMOTE_FAILURE_BACKOFF[backoff_idx], tolerance_s - elapsed)
-            events.emit(
-                cfg.runtime.log_dir,
-                MONITOR_REMOTE_BLIP,
-                host=host,
-                error=e.stderr,
-                attempt=attempt,
-                elapsed_s=elapsed,
-                cap_s=tolerance_s,
-                interval_s=interval_s,
-                next_sleep_s=next_sleep_s,
-            )
-            time.sleep(next_sleep_s)
-            continue
-
+        alerts = _poll_once(work_dir)
         for alert in alerts:
             key = f"{alert.detector}:{_json.dumps(alert.context, sort_keys=True)}"
             if key in seen:
@@ -620,7 +563,6 @@ def _monitor_loop_iter(
             monitor.on_alert(
                 alert,
                 project=_project_name(work_dir),
-                host=host,
                 log_dir=cfg.runtime.log_dir,
                 allowed_stop_names=cfg.monitor.auto_stop_on,
             )
@@ -800,6 +742,7 @@ 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,
@@ -849,6 +792,41 @@ def stream_events_jsonl(log_dir: Path, *, poll_interval_s: float = 0.1) -> Itera
     yield from _tail_events_jsonl(log_dir, start_at_now=True, poll_interval_s=poll_interval_s)
 
 
+def relay_remote_events(
+    host: str,
+    *,
+    log_dir: Path,
+    kinds: Sequence[str] | None = None,
+    remote_config: str | None = None,
+    failure_tolerance_s: float = 90.0,
+    out: TextIO | None = None,
+) -> int:
+    """Remote sibling of ``stream_events_jsonl``: relay ``host``'s event stream.
+
+    Spawns a managed ``ssh <host> -- agent-runner events --tail`` and passes its
+    JSONL through, reconnecting with ``--since`` so a dropped link replays its
+    gap. Returns a CLI exit code (0 on interrupt, 1 once the link stays down
+    past ``failure_tolerance_s``). Blocks until then.
+
+    ``log_dir`` is this CLIENT's log dir: the ``monitor_remote_blip`` /
+    ``monitor_remote_giveup`` events it writes describe the local machine's link
+    to ``host``, not the supervised project. Detection is deliberately NOT
+    relayed — the detectors run on ``host`` (see ``monitor_loop``).
+    """
+    # Late import: pulls agent_runtime (psutil, threading) only for the callers
+    # that actually stream from a remote host.
+    from agent_runner.remote_relay import relay_remote_events as _relay
+
+    return _relay(
+        host,
+        log_dir=log_dir,
+        kinds=kinds,
+        remote_config=remote_config,
+        failure_tolerance_s=failure_tolerance_s,
+        out=out,
+    )
+
+
 def _format_narrate_line(evt: dict[str, Any]) -> str:
     """Format an event dict as a one-line human-readable string.
 

{cli_agent_runner-0.2.4 → cli_agent_runner-0.2.6}/agent_runner/cli/events_cmd.py

@@ -3,7 +3,13 @@
 One-shot (--window N) or streaming (--tail) query against events.jsonl.
 JSON Lines output (one JSON object per line, no pretty-print).
 
-Current-month scope only. Tail mode follows month rollover via per-poll glob.
+Current-month scope only, except under ``--since <ISO ts>``, which replays every
+matching event with ``ts >= since`` across month files (and then follows, under
+``--tail``). That replay is at-least-once by contract: a client resumes by
+passing the last ts it saw, so the boundary event may arrive twice — no event is
+ever silently lost across a dropped connection.
+
+Tail mode follows month rollover via per-poll glob.
 """
 
 from __future__ import annotations
@@ -16,6 +22,8 @@ import time
 from datetime import UTC, datetime
 from pathlib import Path
 
+from agent_runner.events import parse_iso_ms
+
 # Sentinel for "user did not explicitly set --window" so we can detect
 # --window + --tail combinations. argparse mutually-exclusive group would
 # be cleaner but argparse doesn't support "exclusive only when X has value Y".
@@ -64,6 +72,18 @@ def add_parser(sub, parent) -> None:
         action="store_true",
         help=("Streaming mode: emit each new matching event as it fires (blocks until SIGINT)."),
     )
+    p.add_argument(
+        "--since",
+        type=str,
+        default=None,
+        metavar="ISO-TS",
+        help=(
+            "Replay every matching event with ts >= this ISO-8601 timestamp "
+            "(e.g. 2026-07-27T10:00:00.000Z), across month files, then keep "
+            "streaming if --tail. At-least-once: resume by passing the last ts "
+            "you saw — that event may repeat, none is lost. Excludes --window."
+        ),
+    )
     p.set_defaults(func=cmd_events)
 
 
@@ -97,6 +117,27 @@ def cmd_events(args) -> int:
         )
         return 2
 
+    since_raw = getattr(args, "since", None)
+    since: datetime | None = None
+    if since_raw is not None:
+        if window_explicit:
+            print(
+                "Error: --window and --since are mutually exclusive",
+                file=sys.stderr,
+            )
+            return 2
+        try:
+            since = parse_iso_ms(since_raw)
+        except ValueError:
+            print(
+                f"Error: --since expects an ISO-8601 timestamp "
+                f"(e.g. 2026-07-27T10:00:00.000Z), got {since_raw!r}",
+                file=sys.stderr,
+            )
+            return 2
+        if since.tzinfo is None:
+            since = since.replace(tzinfo=UTC)
+
     try:
         log_dir = _resolve_log_dir(args)
     except FileNotFoundError as e:
@@ -104,7 +145,15 @@ def cmd_events(args) -> int:
         return 1
 
     if args.tail:
-        return _tail_events(log_dir, kind_set)
+        return _tail_events(log_dir, kind_set, since=since)
+
+    if since is not None:
+        try:
+            _replay_since(log_dir, kind_set, since)  # offset only matters to --tail
+        except OSError as e:
+            print(f"Error: events file unreadable: {e}", file=sys.stderr)
+            return 1
+        return 0
 
     window = args.window if args.window != _WINDOW_DEFAULT_SENTINEL else 10
     return _query_events(log_dir, kind_set, window)
@@ -115,6 +164,68 @@ def _current_month_events_file(log_dir: Path) -> Path:
     return log_dir / f"events-{month}.jsonl"
 
 
+def _month_of(events_file: Path) -> str:
+    """The YYYY-MM embedded in an ``events-YYYY-MM.jsonl`` filename."""
+    return events_file.name[len("events-") : -len(".jsonl")]
+
+
+def _matches_since(line: str, kind_set: set[str], since: datetime) -> bool:
+    """True if ``line`` is a matching kind whose ts is at or after ``since``.
+
+    Malformed lines and lines carrying no parseable ``ts`` are skipped silently,
+    matching the tolerance of the other parse loops in this module.
+    """
+    try:
+        evt = json.loads(line)
+    except json.JSONDecodeError:
+        return False
+    if evt.get("event") not in kind_set:
+        return False
+    ts = evt.get("ts")
+    if not isinstance(ts, str):
+        return False
+    try:
+        parsed = parse_iso_ms(ts)
+    except ValueError:
+        return False
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed >= since
+
+
+def _replay_since(log_dir: Path, kind_set: set[str], since: datetime) -> tuple[Path, int]:
+    """Emit every matching event with ``ts >= since``, oldest month file first.
+
+    Not windowed: replay is the resume path, so it emits the whole backlog.
+
+    Returns ``(current-month file, bytes consumed of it)``. That offset is the
+    handoff point for ``--tail``: it is the true end-of-read position, so a line
+    appended while the replay was running is picked up by the poll loop instead
+    of being skipped, and no line is emitted in both phases.
+    """
+    since_month = since.astimezone(UTC).strftime("%Y-%m")
+    current = _current_month_events_file(log_dir)
+    offset = 0
+    for path in sorted(log_dir.glob("events-*.jsonl")):
+        if _month_of(path) < since_month:
+            # Nothing to replay from a month that ended before `since`. The live
+            # file lands here only when `since` names a future month — seed the
+            # tail at its end rather than rewinding it to 0.
+            if path == current:
+                offset = path.stat().st_size
+            continue
+        with path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                if _matches_since(line, kind_set, since):
+                    print(line, flush=True)
+            if path == current:
+                offset = f.tell()
+    return current, offset
+
+
 def _query_events(log_dir: Path, kind_set: set[str], window: int) -> int:
     """One-shot: read current-month events.jsonl, filter, print last N."""
     events_file = _current_month_events_file(log_dir)
@@ -143,10 +254,15 @@ def _query_events(log_dir: Path, kind_set: set[str], window: int) -> int:
     return 0
 
 
-def _tail_events(log_dir: Path, kind_set: set[str]) -> int:
+def _tail_events(log_dir: Path, kind_set: set[str], since: datetime | None = None) -> int:
     """Streaming: poll current-month events.jsonl at 1s interval; emit each
     new matching line as it fires. Blocks until SIGINT (KeyboardInterrupt).
     Follows month rollover via per-poll glob.
+
+    With ``since``, the backlog (``ts >= since``, across month files) is replayed
+    first and the poll resumes at the exact byte the replay stopped on — no gap
+    and no duplicate across the handoff. At-least-once overall: the caller
+    resumes from the last ts it saw, so that one event may repeat.
     """
     last_size = 0
     current_file: Path | None = None
@@ -156,6 +272,13 @@ def _tail_events(log_dir: Path, kind_set: set[str]) -> int:
 
     signal.signal(signal.SIGINT, _handle_sigint)
 
+    if since is not None:
+        try:
+            current_file, last_size = _replay_since(log_dir, kind_set, since)
+        except OSError as e:
+            print(f"Error: events file unreadable: {e}", file=sys.stderr)
+            return 1
+
     try:
         while True:
             events_file = _current_month_events_file(log_dir)