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

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

@@ -5,6 +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.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.
+- `--preset pi` — a preset for [Pi Coding Agent](https://github.com/earendil-works/pi) (`pi -p -na --mode json --model …`; `-na` pins project trust off for unattended runs). `docs/recipes/pi.md` documents driving Kimi K3 through pi via a Moonshot OpenAI-compatible provider.
+
+### Fixed
+- 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
@@ -386,7 +415,7 @@ See `docs/migrations/0.1.17.md`.
 
 ### Acknowledgements
 
-Argus Gateway's post-Q1-audit feedback (2026-05-14) surfaced the per-phase sub-table need (S3) and the multi-file prompt pattern (S1). Their R721 frontmatter-strip lesson informed making the (already-shipping) strip behavior an explicit opt-out config flag rather than hardcoded.
+A downstream integrator's post-Q1-audit feedback (2026-05-14) surfaced the per-phase sub-table need (S3) and the multi-file prompt pattern (S1). Their R721 frontmatter-strip lesson informed making the (already-shipping) strip behavior an explicit opt-out config flag rather than hardcoded.
 
 ## [0.1.15] - 2026-05-14
 
@@ -418,10 +447,10 @@ independent components bundled into one release because both serve the same
 
 ### Acknowledgements
 
-Two of six nice-to-have items surfaced in Argus Gateway's v0.1.12
+Two of six nice-to-have items surfaced in a downstream integrator's v0.1.12
 production-evaluation report (2026-05-14). An earlier scope also included
 per-phase runtime override; spec review caught that `runtime.round_timeout_per_phase`
-already covers Argus's stated need, so that component was deferred to a future
+already covers the integrator's stated need, so that component was deferred to a future
 release where a second per-phase field surfaces. Other items in the report
 (detector helper, hot-reload, replay) remain intentionally out of scope.
 
@@ -440,7 +469,7 @@ release where a second per-phase field surfaces. Other items in the report
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team — this release answers their imminent
+Thanks to our downstream integrators — this release answers their imminent
 production-deployment requirement for upgrade-without-disruption. After
 confirming round duration (10-40 min) fits within graceful-stop tolerance,
 this release scopes to round-boundary upgrade UX (Level 1). Mid-round
@@ -465,7 +494,7 @@ real production need.
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team for the deep v0.1.10 audit-session feedback
+Thanks to our downstream integrators for the deep v0.1.10 audit-session feedback
 (6 items, 3-round real-run testing on ARMv8 Pi). This release reframes those
 items into a coherent "Plugin & Operator Transparency" theme across three
 layers: transparency (see what plugins do), operator override (escape hatches
@@ -487,16 +516,16 @@ for audit/debug), and diagnostic quality (errors point at the next debug step).
 
 ### Migration notes
 
-- `Config.plugins` type change is breaking for any caller reading the field as a dict (`cfg.plugins.get("foo")`). Plugin authors using `[plugins.argus_*]`-style keys: read them from `cfg.plugins.raw.get("argus_*")` instead.
+- `Config.plugins` type change is breaking for any caller reading the field as a dict (`cfg.plugins.get("foo")`). Plugin authors using `[plugins.acme_*]`-style keys: read them from `cfg.plugins.raw.get("acme_*")` instead.
 - `LockHeldError` message format changed (now includes holder info: `"another agent-runner is holding /path (held by PID N, age Ns, cmd: ...)"` or stale/missing variants). Operators grepping the exact format string need to update.
-- For Argus's P5 confusion: see new `docs/architecture.md` section "Plugin injection: two paths" — `inject_context` and `disable_pre_round_hooks` are INDEPENDENT flags. Setting one does not affect the other.
+- For the integrator's P5 confusion: see new `docs/architecture.md` section "Plugin injection: two paths" — `inject_context` and `disable_pre_round_hooks` are INDEPENDENT flags. Setting one does not affect the other.
 - **Known limitation**: `[plugins] disable` removes named plugins from the hook / context-enricher / detector / event-kind registries, but does NOT remove a disabled plugin's owned VCS paths (the `register_plugin_owned_paths` registry has no name attribution today). Mostly inert. If this becomes a real issue, file a GitHub issue.
 
 ## [0.1.11] - 2026-05-13
 
 ### Acknowledgements
 
-Thanks again to the Argus Gateway team — this release closes the
+Thanks again to our downstream integrators — this release closes the
 network-resilience gap that 0.1.10's `MonitorRemoteError` propagation
 exposed, plus adds per-occurrence agent network blip observability requested
 during 0.1.10 handover review.
@@ -525,7 +554,7 @@ For network-related failures, the events index points at the diagnostic body:
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team for the Phase 4 second-pass production feedback that drove every change in this release. Six audit memos across 50 minutes of validated runtime surfaced four specific gaps; this release closes them.
+Thanks to our downstream integrators for the Phase 4 second-pass production feedback that drove every change in this release. Six audit memos across 50 minutes of validated runtime surfaced four specific gaps; this release closes them.
 
 ### Added
 
@@ -553,7 +582,7 @@ Thanks to the Argus Gateway team for the Phase 4 second-pass production feedback
 
 ### Acknowledgements
 
-Thanks to the argus-gateway team for the dev/qa/product wall-time data
+Thanks to our downstream integrators for the dev/qa/product wall-time data
 (Phase 4 feedback §3.1) that drove this API shape. Their three-role
 distribution made the case for per-phase overrides concrete.
 
@@ -579,7 +608,7 @@ documented plugin-author public surface.
 
 ### Acknowledgements
 
-Thanks to the argus-gateway team for Phase 4 dogfooding feedback that drove
+Thanks to our downstream integrators for Phase 4 dogfooding feedback that drove
 every item in this release. 3 audit memos (~90KB) silently swept into an
 orphan stash is a real-world failure mode; this release closes that loop.
 
@@ -608,7 +637,7 @@ orphan stash is a real-world failure mode; this release closes that loop.
 
 - Plugin outputs in plugin-declared paths (e.g. `proposals/`,
   `logs/plugins/my_plugin/`) no longer silently swept into orphan stashes
-  by `process_orphan_wip`. Previously: 90KB Argus audit memos invisible
+  by `process_orphan_wip`. Previously: 90KB audit memos invisible
   after Phase 4 round; required stash archaeology to recover.
 
 ### Migration
@@ -651,7 +680,7 @@ Or regenerate cleanly:
 agent-runner init --preset claude --force
 ```
 
-Plugin authors (Argus Gateway, etc.): no public API was renamed or removed
+Plugin authors (downstream integrators, etc.): no public API was renamed or removed
 from your import surface. The deleted symbols (`agent_runner.agent_runtime.CRITICAL_ENV_DEFAULTS`,
 `agent_runner.agent_runtime.merge_critical_envs`) were internal — not part of
 the documented plugin API. A new public-API contract test
@@ -882,7 +911,7 @@ Initial public release on PyPI as `cli-agent-runner`.
 
 ### Added
 - Three-layer model: Round / Loop / Witness.
-- 13 CLI verbs: `init`, `install`, `uninstall`, `start`, `stop`, `kill`,
+- 14 CLI verbs: `init`, `install`, `uninstall`, `start`, `stop`, `kill`,
   `cancel`, `restart`, `status`, `round`, `serve`, `peek`, `watch`, `monitor`.
 - 11 named defenses (round timeout, process group isolation, orphan stash
   with SHA lock, set-diff classification, smoke check, flock concurrency,
@@ -909,7 +938,11 @@ 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.0...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.4...HEAD
+[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
 [0.2.0]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.42...v0.2.0
 [0.1.26]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.25...v0.1.26
 [0.1.25]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.24...v0.1.25

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 # agent-runner
 
 A restart-on-exit supervisor for autonomous coding CLIs. Ships presets for
-Claude Code, aider, gemini and codewhale; any prompt-arg CLI via custom
+Claude Code, aider, gemini, codewhale, kimi and pi; any prompt-arg CLI via custom
 config. Spawn the agent round-after-round under defenses that prevent the
 failure modes
 that bite in production: stuck rounds, orphan commits, OAuth burn loops,
@@ -116,20 +116,20 @@ 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.
+> **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.
 
 ## Documentation
 

{cli_agent_runner-0.2.2 → cli_agent_runner-0.2.4}/README.md

@@ -5,7 +5,7 @@
 # agent-runner
 
 A restart-on-exit supervisor for autonomous coding CLIs. Ships presets for
-Claude Code, aider, gemini and codewhale; any prompt-arg CLI via custom
+Claude Code, aider, gemini, codewhale, kimi and pi; any prompt-arg CLI via custom
 config. Spawn the agent round-after-round under defenses that prevent the
 failure modes
 that bite in production: stuck rounds, orphan commits, OAuth burn loops,
@@ -80,20 +80,20 @@ 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.
+> **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.
 
 ## Documentation
 

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

{cli_agent_runner-0.2.2 → cli_agent_runner-0.2.4}/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],
@@ -137,6 +165,7 @@ def run(
     prompt: str,
     prompt_delivery: str = "argv",
     timeout_s: int,
+    work_dir: Path,
     log_path: Path,
     env_extra: dict[str, str],
     max_grace_after_result_s: int = 0,
@@ -149,6 +178,10 @@ def run(
 
     Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
 
+    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
     process group only if the agent has no live worker processes left (a
@@ -175,16 +208,21 @@ def run(
         if stdin_mode
         else _build_argv(command, prompt_arg_template, prompt)
     )
-    env = {**os.environ, **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()
     last_progress_at = start
     proc = subprocess.Popen(
         argv,
+        cwd=work_dir,
         env=env,
         stdin=subprocess.PIPE if stdin_mode else subprocess.DEVNULL,
         stdout=log_file,
+        # Merged on purpose: oauth_fail / network_fail / network-blip detection
+        # regex-scan stderr text out of this log (see hooks.agent_log_path).
         stderr=subprocess.STDOUT,
         start_new_session=True,
     )

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

@@ -486,6 +486,8 @@ def _poll_once(project: str | Path, *, host: str | None) -> list[monitor.Alert]:
     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))
     events = monitor.parse_events_from_jsonl_files(src.events_files())
     metrics = monitor.parse_events_from_jsonl_files(src.metrics_files())
@@ -525,12 +527,29 @@ 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()``.
+    """
+    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``.
+
     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.
+    the 0.1.10 immediate-propagate behavior with no blip events emitted. That
+    path is dormant while remote mode is rejected at startup.
     """
     import json as _json
 
@@ -771,6 +790,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,

{cli_agent_runner-0.2.2 → cli_agent_runner-0.2.4}/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:

cli_agent_runner-0.2.4/agent_runner/builtin_plugins/_constants.py

@@ -0,0 +1,125 @@
+"""Shared constants and tail-scan helpers for built-in CLI plugins.
+
+Extracted to single source of truth so every round-log tail-scanner
+(plugin JSONL parsers and monitor text detectors) uses the same window
+size, raw-text caps, transient-error back-off defaults, and the same
+HTTP-status → classification ladder.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import deque
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, TextIO
+
+_TAIL_LINES: int = 200
+"""Number of log lines to scan from the end of a round log.
+
+The round log is merged stdout+stderr. JSONL consumers window via
+``json_tail`` (chatter filtered before windowing); plain-text consumers
+(monitor oauth/network detectors) window the raw tail — keep this generous
+so a stderr burst cannot evict what they scan for."""
+
+
+def json_tail(f: TextIO, maxlen: int = _TAIL_LINES) -> deque[str]:
+    """Last ``maxlen`` JSON-looking lines of a merged round log.
+
+    Non-JSON chatter (stderr text) is filtered BEFORE windowing, so a burst
+    of any size cannot evict the terminal JSONL event from the window.
+    """
+    return deque((ln for ln in f if ln.lstrip()[:1] in "{["), maxlen=maxlen)
+
+
+def json_events(log_path: Path) -> Iterator[dict]:
+    """JSON objects in a round log's tail window, in file order.
+
+    One reader for every plugin's parse loop: window via ``json_tail``, then
+    per line strip / skip blank / ``json.loads`` / drop anything that is not an
+    object. Non-JSON lines are expected — the round log merges stdout+stderr,
+    and every CLI writes some plain text there.
+    """
+    with log_path.open("r", encoding="utf-8", errors="replace") as f:
+        tail = json_tail(f)
+    for line in tail:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(event, dict):
+            yield event
+
+
+_RAW_CAP: int = 200
+"""Maximum length for ``raw`` field in transient_error_detected payload."""
+
+# Default back-off durations (seconds) for non-precise transient classifications.
+# rate_limit_account uses exact resetsAt epoch from claude; not in this table.
+_BACK_OFF_DEFAULTS: dict[str, int] = {
+    "rate_limit_model": 60,
+    "api_transient_5xx": 60,
+    "api_timeout": 30,
+}
+
+# 5xx codes treated as transient (retry-worthy server errors per RFC 9110):
+# 500=unexpected, 502=bad gateway, 503=unavailable, 504=gateway timeout,
+# 529=overloaded (Anthropic's non-RFC code emitted during sustained capacity
+# issues; treated as transient per Anthropic SDK behavior).
+# Excluded: 501 (not implemented = permanent), 505 (HTTP version mismatch).
+_5XX_STATUSES: frozenset[int] = frozenset({500, 502, 503, 504, 529})
+
+
+def classify_transient_status(status: Any) -> str | None:
+    """Map an HTTP status from a CLI's error record to a transient bucket.
+
+    The one ladder every plugin classifier delegates to, so a status is
+    bucketed identically no matter which CLI reported it.
+
+    ``None`` means 'not transient — do not back off'. Notably 401 (auth) and
+    404 (unknown model) land here: both are permanent until an operator fixes
+    configuration, which is oauth/config territory rather than something a
+    back-off would clear. Non-integer or missing statuses are ``None`` too;
+    a CLI that reports no status gets no classification.
+    """
+    if not isinstance(status, int) or isinstance(status, bool):
+        return None
+    if status == 429:
+        return "rate_limit_model"
+    if status in _5XX_STATUSES:
+        return "api_transient_5xx"
+    if status == 408:
+        return "api_timeout"
+    return None
+
+
+_CLASSIFICATIONS: frozenset[str] = frozenset(
+    {
+        "rate_limit_account",
+        "rate_limit_model",
+        "api_transient_5xx",
+        "api_timeout",
+    }
+)
+"""Canonical set of transient-error classifications.
+
+rate_limit_account uses server-provided resetsAt (excluded from
+_BACK_OFF_DEFAULTS table); others use defaults from that table.
+"""
+
+_EXP_CAP: int = 5
+"""Maximum exponent for transient-error consecutive backoff: 2^5 = 32×.
+
+Beyond this, the multiplier plateaus. Combined with _ABSOLUTE_CAP_S, this
+prevents runaway wait times during sustained outages (max wait = 30min).
+"""
+
+_ABSOLUTE_CAP_S: int = 1800
+"""Absolute upper bound on supervisor-applied transient back-off (30 min).
+
+Applies after exp multiplier — even if base × 2^5 exceeds this, the wait
+is clipped here. Defends against an indefinitely-stuck supervisor.
+"""