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

{cli_agent_runner-0.2.3 → cli_agent_runner-0.2.5}/.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.3 → cli_agent_runner-0.2.5}/.vulture-whitelist.py

@@ -228,10 +228,6 @@ path
 # agent_runner.monitor.LocalSource
 log_dir
 
-# agent_runner.monitor.RemoteSource
-host
-project
-
 # agent_runner.startup_check.CheckResult
 name
 ok

{cli_agent_runner-0.2.3 → cli_agent_runner-0.2.5}/CHANGELOG.md

@@ -5,9 +5,35 @@ 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.3] - 2026-07-26
+## [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`.
 
-Details: [docs/migrations/0.2.3.md](docs/migrations/0.2.3.md)
+## [0.2.4] - 2026-07-27
+
+### Added
+- `kimi_error_detector` plugin — classifies transient errors from Kimi Code CLI rounds (`turn.step.retrying` records) so a rate-limited round backs off instead of hot-restarting. No usage events: the CLI's stream-json output carries no token counters.
+- `agent_auth_error_detected` event — a plugin reports an auth failure named by the agent CLI's own structured output, and the `oauth_fail` detector counts those rounds directly. Makes pi's 401 loop visible (pi exits 0); the text-heuristic path keeps its nonzero-exit gate unchanged.
+- `pi_error_detector` plugin — emits per-round token usage (summed across the round's assistant messages, since pi reports usage per message) and classifies transient errors from Pi Coding Agent rounds. pi exits 0 on provider failure, so the classifier reads the final message's `stopReason`/`errorMessage` rather than the exit code.
+
+### Fixed
+- Round-log tail scanning hardened: plugin JSONL parsers filter non-JSON chatter *before* windowing (a stderr burst of any size can no longer evict the terminal event), monitor detectors share the same 200-line window (was 50 — the oauth/network text scans had the identical eviction risk), and each monitor poll reads only the newest 20 round logs instead of every log ever written.
+- A relative `runtime.work_dir` (and every path derived from it) now resolves against the config file's directory instead of the caller's cwd, so `--config /abs/proj/agent-runner.toml` drives `/abs/proj` no matter where the supervisor was launched from.
+- Remote monitor (`monitor --host <alias>`) was silently observing an empty world and reporting healthy — it listed remote filenames over ssh but read every path locally. It now fails loudly at startup (exit 1, with guidance to run the monitor on the host) until remote reads are implemented.
+- Agent round logs (`{log_dir}/rounds/R*-*.log`) are now pruned under `runtime.round_log_retention` at the start of every round — previously that family grew unboundedly, since only the serve-level `round-<N>.log` family was pruned, and only at serve startup.
+- Startup validation resolves the agent command exactly as the spawn does (child's PATH — `[agent.env]` may override it — and `work_dir` base); `PWD` now stays pinned to `work_dir` even if `[agent.env]` sets it. The stdout+stderr merge is now pinned by a behavioral test, not just prose.
+- Generated serve systemd units now set `KillMode=mixed`: with systemd's default `control-group`, `systemctl stop` SIGTERMed the whole cgroup — agent child included — making the graceful round drain structurally ineffective. Existing installs: re-run `agent-runner install` (or add a drop-in) to pick this up.
+
+See `docs/migrations/0.2.4.md`.
+
+## [0.2.3] - 2026-07-26
 
 ### Added
 - `--preset kimi` — a preset for [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) (`kimi -p --output-format stream-json`). `docs/recipes/kimi.md` also documents running Kimi K3 through the existing `claude` preset via Moonshot's Anthropic-compatible endpoint.
@@ -17,6 +43,8 @@ Details: [docs/migrations/0.2.3.md](docs/migrations/0.2.3.md)
 - The agent subprocess now runs in `runtime.work_dir` (`cwd=` on spawn). Previously it inherited the supervisor's cwd and only launch conventions (systemd `WorkingDirectory=`, relative `--config`) kept the two aligned — fatal for agent CLIs with no working-directory flag of their own (e.g. `pi`). The startup check now also validates a relative `agent.command[0]` against `work_dir`, matching where it executes.
 - Plugin round-log tail window widened 50 → 200 lines: a stderr burst after the agent's terminal JSONL event could evict it from the scan window, silently dropping usage/transient classification. The round log's merged stdout+stderr contract is now documented (`HookContext.agent_log_path`, `docs/long-running-agents.md`) — the merge is deliberate; auth/network detection reads stderr text from it.
 
+See `docs/migrations/0.2.3.md`.
+
 ## [0.2.2] - 2026-07-18
 
 ### Removed
@@ -631,6 +659,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
@@ -921,7 +950,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.3...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.5...HEAD
+[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
 [0.2.1]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.0...v0.2.1

{cli_agent_runner-0.2.3 → cli_agent_runner-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.3
+Version: 0.2.5
 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'
@@ -116,20 +116,31 @@ Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
 - `oauth_fail` — burning API quota on auth-rejected rounds
 - `disk_critical` — writing to a near-full disk risks corruption
 
-Runs locally or against a remote host via ssh:
+Runs against the supervised project's local logs:
 
 ```bash
-agent-runner monitor                  # local, 30s poll
-agent-runner monitor --host pi        # remote, 60s poll
+agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-> **SSH trust boundary**: `monitor --host <alias>` shells out via plain SSH
-> using your local `~/.ssh/config` (aliases, `StrictHostKeyChecking` behavior).
-> A monitor with `auto_stop` enabled can issue `agent-runner stop` on the
-> remote — verify your SSH config before pointing monitor at a remote service.
-> See [`docs/runbook.md`](docs/runbook.md) § "Remote monitor & SSH trust" for
-> recommended hygiene.
+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.3 → cli_agent_runner-0.2.5}/README.md

@@ -80,20 +80,31 @@ Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
 - `oauth_fail` — burning API quota on auth-rejected rounds
 - `disk_critical` — writing to a near-full disk risks corruption
 
-Runs locally or against a remote host via ssh:
+Runs against the supervised project's local logs:
 
 ```bash
-agent-runner monitor                  # local, 30s poll
-agent-runner monitor --host pi        # remote, 60s poll
+agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-> **SSH trust boundary**: `monitor --host <alias>` shells out via plain SSH
-> using your local `~/.ssh/config` (aliases, `StrictHostKeyChecking` behavior).
-> A monitor with `auto_stop` enabled can issue `agent-runner stop` on the
-> remote — verify your SSH config before pointing monitor at a remote service.
-> See [`docs/runbook.md`](docs/runbook.md) § "Remote monitor & SSH trust" for
-> recommended hygiene.
+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.3 → cli_agent_runner-0.2.5}/agent_runner/_emit.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 from pathlib import Path
 
 __all__ = [
+    "emit_agent_auth_error_detected",
     "emit_agent_usage_recorded",
     "emit_anomaly_repetitive_tool",
     "emit_fresh_eyes_round_triggered",
@@ -150,6 +151,38 @@ def emit_transient_error_detected(
     )
 
 
+def emit_agent_auth_error_detected(
+    log_dir: Path,
+    *,
+    round_num: int,
+    agent: str,
+    raw: str,
+) -> None:
+    """Emit an authentication/authorization failure the agent itself reported.
+
+    Contract: emitted by a per-CLI plugin only when the agent's OWN structured
+    output names the failure (e.g. an HTTP 401 in its JSON event stream). That
+    is certain evidence, unlike the monitor's ``oauth_fail`` text heuristic,
+    which scans free-text log tails and therefore needs a nonzero-exit shield
+    against prose that merely mentions "401". The monitor counts a round
+    carrying this event without that shield — which is what makes an auth loop
+    visible for a CLI that exits 0 on provider failure.
+
+    No back-off partner event: an auth failure is permanent until an operator
+    fixes the credential, so it is deliberately not a transient classification.
+    """
+    from agent_runner._redact import redact_secrets
+    from agent_runner.events import AGENT_AUTH_ERROR_DETECTED, emit
+
+    emit(
+        log_dir,
+        AGENT_AUTH_ERROR_DETECTED,
+        round_num=round_num,
+        agent=agent,
+        raw=redact_secrets(raw),
+    )
+
+
 def emit_transient_error_recovered(
     log_dir: Path,
     *,
@@ -205,7 +238,10 @@ def emit_agent_usage_recorded(
       Claude: count of ``tool_use`` content blocks across all assistant events.
       Gemini: ``stats.tool_calls``.
     - ``phase``: phase label from HookContext (e.g. "planning"); empty string when None.
-    - ``success``: True when exit_code == 0 and not timed_out.
+    - ``success``: the supervisor's clean-exit predicate (``RoundResult.ok``).
+      A plugin MAY additionally fold in the agent's own terminal verdict when
+      its CLI's exit code is unreliable — pi does, because pi exits 0 on
+      provider failure.
     """
     from agent_runner.events import AGENT_USAGE_RECORDED, emit
 

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

{cli_agent_runner-0.2.3 → cli_agent_runner-0.2.5}/agent_runner/agent_runtime.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import os
 import re
+import shutil
 import signal
 import subprocess  # noqa: TID251 — sanctioned subprocess caller
 import threading
@@ -52,6 +53,15 @@ class RunResult:
     killed_for_grace: bool = False
     grace_kill_children: list[dict] = field(default_factory=list)
 
+    @property
+    def ok(self) -> bool:
+        """The supervisor's round-success predicate: clean exit, no timeout.
+
+        Single definition of "did this round fail" at the supervisor level. A
+        plugin MAY narrow it further when its CLI's exit code is unreliable.
+        """
+        return self.exit_code == 0 and not self.timed_out
+
 
 def _build_argv(command: list[str], prompt_arg_template: list[str], prompt: str) -> list[str]:
     """Build full argv: command + prompt args (with {prompt} substituted)."""
@@ -130,6 +140,24 @@ def _live_children(
 _RESULT_MARKER = b'"type":"result"'
 
 
+def resolve_exec_target(command0: str, work_dir: Path, env_path: str | None = None) -> str | None:
+    """Model of Popen's POSIX exec resolution for argv[0].
+
+    Kept beside the ``Popen`` in :func:`run` so validation and exec cannot
+    drift: a slash-containing argv[0] resolves against the child's cwd
+    (``work_dir``); a bare name is looked up on the CHILD's PATH
+    (``env_path`` — pass ``[agent.env]``'s PATH override if set; ``None``
+    falls back to the supervisor's, matching env inheritance). Returns the
+    resolved executable path, or ``None`` if it would not exec.
+    """
+    if "/" in command0:
+        candidate = Path(command0)
+        if not candidate.is_absolute():
+            candidate = work_dir / candidate
+        return shutil.which(str(candidate))
+    return shutil.which(command0, path=env_path)
+
+
 def run(
     *,
     command: list[str],
@@ -150,11 +178,9 @@ def run(
 
     Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
 
-    work_dir: the agent child's working directory (required). Before 0.2.3 the
-    child inherited the supervisor's cwd and only launch conventions (systemd
-    WorkingDirectory=, relative --config) kept the two aligned — fatal for CLIs
-    with no --cwd flag of their own (e.g. pi). Callers pass the already-absolute
-    cfg.runtime.work_dir.
+    work_dir: the agent child's working directory; callers pass the
+    already-absolute cfg.runtime.work_dir. CLIs with no --cwd flag of their
+    own (e.g. pi) depend on this.
 
     max_grace_after_result_s: when > 0, start a countdown after the first
     type=result event is detected in the log. After it elapses, reap the
@@ -182,8 +208,9 @@ def run(
         if stdin_mode
         else _build_argv(command, prompt_arg_template, prompt)
     )
-    # PWD pinned alongside cwd= so shell-reported paths agree; env_extra wins.
-    env = {**os.environ, "PWD": str(work_dir), **env_extra}
+    # PWD pinned last — it mirrors cwd= (a correctness pin, not a knob), so
+    # an [agent.env] PWD cannot silently diverge from where the child runs.
+    env = {**os.environ, **env_extra, "PWD": str(work_dir)}
     log_path.parent.mkdir(parents=True, exist_ok=True)
     log_file = log_path.open("w", encoding="utf-8")
     start = time.time()

{cli_agent_runner-0.2.3 → cli_agent_runner-0.2.5}/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,14 +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:
-        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())
@@ -510,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]:
@@ -525,12 +517,25 @@ def monitor_loop(
     to that kind as the canonical "supervision is up" signal (monitor is otherwise
     silent during healthy operation by design).
 
-    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.
+    ``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)
+    return _monitor_loop_iter(project, host=host, interval_s=interval_s)
+
+
+def _monitor_loop_iter(
+    project: str | Path | None = None, *, host: str | None = None, interval_s: int = 30
+) -> Iterator[monitor.Alert]:
+    """Polling generator behind ``monitor_loop``.
+
+    ``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
 
@@ -547,51 +552,8 @@ def monitor_loop(
         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:
@@ -601,7 +563,6 @@ def monitor_loop(
             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,
             )
@@ -771,6 +732,7 @@ def check_self_terminated_sentinel(log_dir: Path) -> bool:
 # Re-export emit_* wrappers from _emit module (extracted for size hygiene).
 # Preserves the public import surface: `from agent_runner.api import emit_*` continues to work.
 from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-export
+    emit_agent_auth_error_detected,
     emit_agent_usage_recorded,
     emit_anomaly_repetitive_tool,
     emit_config_broken,
@@ -829,6 +791,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.3 → cli_agent_runner-0.2.5}/agent_runner/api_types.py

@@ -173,6 +173,15 @@ class RoundResult:
     dirty_outcome: DirtyOutcome | None = None
     killed_for_grace: bool = False
 
+    @property
+    def ok(self) -> bool:
+        """The supervisor's round-success predicate: clean exit, no timeout.
+
+        Single definition of "did this round fail" at the supervisor level. A
+        plugin MAY narrow it further when its CLI's exit code is unreliable.
+        """
+        return self.exit_code == 0 and not self.timed_out
+
 
 @dataclass(frozen=True)
 class InitResult: