cli-agent-runner 0.2.18__tar.gz → 0.2.19__tar.gz

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/BACKLOG.md

@@ -88,3 +88,38 @@ just succeeded in the same repo).
 Deferred because closing it is a naming decision, not cleanup: no event kind
 carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
 — the stash exists). Left as-is until that kind is designed.
+
+## `_monitor_loop_iter`'s three fail-open guards are hand-duplicated
+
+`api._monitor_loop_iter` wraps the startup `monitor_started` emit, the
+per-tick poll, and `on_alert`'s per-alert dispatch each in its own
+`try/except Exception: warnings.warn(...)` block so a crash in any one of the
+three never ends monitor supervision. The three guards are structurally
+identical (catch, format a `type(e).__name__: {e}` warning, keep the loop
+alive) but hand-copied rather than sharing one implementation; `on_alert`'s
+own `emit()` closure already shows the pattern for factoring a shared guard.
+
+Collapsing them to one shared guard is behavior-preserving — it must not
+change which failures warn vs which propagate, nor the specific fallback
+each site takes on failure (sleep-and-retry after a poll failure,
+`verdict = "failed"` after an `on_alert` failure). Slated for 0.2.19.
+
+## `oom_kill_delta` is named differently on its two events — NEEDS_DESIGN, DEFERRED to 0.3
+
+The same cgroup `memory.events.oom_kill` delta is emitted under two
+different field names depending on which event carries it: `round_cgroup_memory`
+reports it as `events_oom_kill_delta` (matching its sibling counters
+`events_high_delta`/`events_max_delta`/`events_oom_delta`), while
+`round_oom_killed` — folded from the same scan, no second sysfs read —
+reports the identical value as bare `oom_kill_delta`. A reader correlating
+the two events for the same round has to know the same quantity carries two
+names.
+
+Renaming either side is a change to a published event field name — part of
+the peek/event JSON contract — so which name becomes canonical (and whether
+it lands as a rename or an additive alias) needs a decision, not a silent
+swap. Tagged NEEDS_DESIGN. Deferred to 0.3's event-model canonicalization
+(see [[project-03-direction]]) rather than reconciled standalone in 0.2.19 —
+0.3 is already renaming/unifying event fields wholesale, and settling this
+name now risks a double-rename (once here, again when 0.3's canonical model
+lands). No field name changes in code until that decision is made.

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.19] - 2026-09-09
+
+### Changed
+- `monitor --host` relay now drains cleanly on SIGTERM — tears down its ssh child group and exits 0 — instead of dying immediately, matching `serve`'s stop-signal behavior.
+- Internal structure, behavior-identical: `_emit.py` split into an `_emit/` package (domain submodules behind a facade); the cgroup-pressure spine carved out of `cli/_serve_round.py` into `cli/_serve_cgroup.py`.
+- The give-up exit-code table in the runbook is now generated from code instead of hand-copied; detector/defense counts and the `peek` schema version are now invariant-pinned against the same source.
+- Internal hardening: the monitor's fail-open guards are unified into one implementation; `kill`'s systemd-user SIGKILL escalation shares the same bounded poll `serve` uses; the cgroup pressure spine resolves its bounding ancestor once per round instead of on every tick; a single-implementation `Protocol` was collapsed to its concrete type; a process's stored child-name no longer passes an attacker-rewritable `argv[0]` through unbounded; plugin discovery now scans legacy egg-info installs and handles entry points with an extras suffix.
+
+### Fixed
+- Docs: the `agent_usage_recorded` plugin list corrected to claude/gemini/codewhale/pi (kimi's built-in plugin emits no token counters).
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change. The relay's SIGTERM-drain above is the one behavior change in this release — anyone relying on the relay's old immediate-exit-on-SIGTERM will now see it drain instead.
+- `oom_kill_delta`'s two-different-field-names inconsistency is deferred to 0.3's event-model work rather than reconciled here, to avoid a double-rename.
+
 ## [0.2.18] - 2026-09-08
 
 ### Added

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.18
+Version: 0.2.19
 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
@@ -152,6 +152,7 @@ your laptop closed. Full relay + SSH-trust mechanics:
 - [`docs/configuration.md`](docs/configuration.md) — `agent-runner.toml` schema
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
+- [`docs/memory-efficiency.md`](docs/memory-efficiency.md) — supervisor memory footprint, measured release over release
 
 ## Development
 

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/README.md

@@ -114,6 +114,7 @@ your laptop closed. Full relay + SSH-trust mechanics:
 - [`docs/configuration.md`](docs/configuration.md) — `agent-runner.toml` schema
 - [`docs/runbook.md`](docs/runbook.md) — operator troubleshooting (OAuth, disk, orphan)
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data
+- [`docs/memory-efficiency.md`](docs/memory-efficiency.md) — supervisor memory footprint, measured release over release
 
 ## Development
 

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/agent_runner/__init__.py

@@ -44,7 +44,12 @@ def _load_plugins_from_group(group: str) -> None:
 
     for name, value in scan_entry_points(sys.path, group):
         try:
-            module_path, _, attr_path = value.partition(":")
+            # An entry-point value may carry a trailing extras marker
+            # (``module:attr [extra1,extra2]``); importlib.metadata.EntryPoint's
+            # own module/attr grammar excludes "[", so anything from the first
+            # "[" onward is always extras, never part of the path — strip it
+            # before resolving, or it glues onto attr_path and breaks getattr().
+            module_path, _, attr_path = value.partition("[")[0].rstrip().partition(":")
             mod = importlib.import_module(module_path)
             target = mod
             for attr in filter(None, attr_path.split(".")):

{cli_agent_runner-0.2.18 → cli_agent_runner-0.2.19}/agent_runner/_docgen.py

@@ -16,6 +16,7 @@ import typing
 from collections.abc import Callable
 from pathlib import Path
 
+from agent_runner import _serve_policy
 from agent_runner.cli.init_cmd import _preset_names
 from agent_runner.config import (
     AgentConfig,
@@ -30,7 +31,14 @@ from agent_runner.config import (
     VcsConfig,
 )
 from agent_runner.defenses import catalog
-from agent_runner.events import KNOWN_EVENT_KINDS
+from agent_runner.events import (
+    CONFIG_BROKEN,
+    CRASH_LOOP,
+    KNOWN_EVENT_KINDS,
+    MEM_LOOP,
+    MEM_LOOP_PERSISTENT,
+    STALLED_NO_PROGRESS,
+)
 from agent_runner.monitor import AUTO_STOP_ALERTS, KNOWN_ALERT_KINDS
 
 # (toml_section_name, dataclass, nested_sub_sections). Nesting is an EXPLICIT
@@ -156,6 +164,84 @@ def render_event_kinds_list() -> str:
     return "\n".join(f"- `{k}`" for k in sorted(KNOWN_EVENT_KINDS))
 
 
+def _giveup_verdict_rows() -> list[tuple[str, int, bool]]:
+    """``(verdict, exit_code, in_restart_prevent)`` rows for serve's five
+    give-up verdicts, in the order the runbook's Symptom section lists them.
+
+    The verdict->code mapping itself is CONTROL FLOW in
+    ``cli/_serve_round.post_round_verdicts`` (a chain of ``if``/``return``,
+    not a dict), so it is mirrored here by hand rather than imported — the
+    four exit-code integers are imported from ``_serve_policy``, the actual
+    code SSOT, so a constant change here is caught by ``./build.sh docs``
+    producing a diff. The third column is DERIVED from
+    ``_serve_policy.RESTART_PREVENT_EXIT_CODES`` (the same single source
+    ``service_unit.py`` renders from) rather than hand-typed per row.
+    """
+    verdict_codes = [
+        (CONFIG_BROKEN, _serve_policy.PERMANENT_CONFIG_EXIT),
+        (CRASH_LOOP, _serve_policy.CRASH_LOOP_EXIT),
+        (STALLED_NO_PROGRESS, _serve_policy.CRASH_LOOP_EXIT),
+        (MEM_LOOP_PERSISTENT, _serve_policy.MEM_LOOP_PERSISTENT_EXIT),
+        (MEM_LOOP, _serve_policy.MEM_LOOP_EXIT),
+    ]
+    return [
+        (verdict, code, code in _serve_policy.RESTART_PREVENT_EXIT_CODES)
+        for verdict, code in verdict_codes
+    ]
+
+
+def render_giveup_exit_codes_table() -> str:
+    """Verdict -> exit-code -> ``RestartPreventExitStatus`` membership table
+    for serve's give-up breakers. 5 verdicts map to only 4 distinct codes:
+    ``stalled_no_progress`` reuses ``crash_loop``'s 75 rather than minting its
+    own (same give-up verdict — "an unknown failure kept recurring, stop for
+    real" — reached via a different signal)."""
+    lines = ["| Verdict | Exit code | `RestartPreventExitStatus`? |", "|---|---|---|"]
+    seen_codes: dict[int, str] = {}
+    for verdict, code, stays_stopped in _giveup_verdict_rows():
+        shares = f" (shares `{seen_codes[code]}`'s exit code)" if code in seen_codes else ""
+        seen_codes.setdefault(code, verdict)
+        behavior = "yes — stays stopped" if stays_stopped else "no — restarts (break-then-restart)"
+        lines.append(f"| `{verdict}` | `{code}`{shares} | {behavior} |")
+    return "\n".join(lines)
+
+
+def render_giveup_systemd_example() -> str:
+    """The ``systemd unit pattern recommendations`` fenced example.
+
+    ``RestartPreventExitStatus`` lists the three DELIBERATE give-up codes
+    (config_broken/crash_loop/mem_loop_persistent), derived from
+    ``_serve_policy.RESTART_PREVENT_EXIT_CODES`` — the same single source
+    ``service_unit.py`` renders from; ``mem_loop``'s 71 is deliberately
+    excluded so systemd respawns to retry. The second comment line's
+    leading padding is derived from the first line's own length (not
+    hand-counted) so the two ``#`` columns always line up even if a future
+    exit code changes ``prevent``'s width."""
+    prevent = " ".join(str(c) for c in _serve_policy.RESTART_PREVENT_EXIT_CODES)
+    header = f"RestartPreventExitStatus={prevent}   "
+    return (
+        "```ini\n"
+        "# Prod (infinite supervisor) — current default\n"
+        "[Service]\n"
+        "ExecStart=... serve --config /etc/agent-runner.toml\n"
+        "Restart=on-failure\n"
+        f"{header}"
+        f"# config_broken ({_serve_policy.PERMANENT_CONFIG_EXIT}) / "
+        f"crash_loop ({_serve_policy.CRASH_LOOP_EXIT}) / "
+        f"mem_loop_persistent ({_serve_policy.MEM_LOOP_PERSISTENT_EXIT}) stay stopped\n"
+        f"{' ' * len(header)}"
+        f"# mem_loop ({_serve_policy.MEM_LOOP_EXIT}) is NOT listed here — it restarts\n"
+        "RestartSec=3\n"
+        "\n"
+        "# Bounded job\n"
+        "[Service]\n"
+        "ExecStart=... serve --config /etc/test.toml --max-rounds 10\n"
+        "Restart=on-failure\n"
+        "RestartSec=5\n"
+        "```"
+    )
+
+
 def _render_migrate_transforms() -> str:
     """Bullet list of the transforms `agent-runner migrate` applies, from the registry.
     A few entries carry a `parsed -> str` describe (so the manual report can name the
@@ -265,6 +351,16 @@ RENDERERS: dict[str, Renderer] = {
     "migrate-transforms": Renderer(
         _render_migrate_transforms, "agent_runner/migrations.py MIGRATIONS"
     ),
+    "giveup-exit-codes": Renderer(
+        render_giveup_exit_codes_table,
+        "agent_runner/_serve_policy.py exit-code constants + "
+        "cli/_serve_round.py post_round_verdicts's verdict->code map",
+    ),
+    "giveup-systemd-example": Renderer(
+        render_giveup_systemd_example,
+        "agent_runner/_serve_policy.py exit-code constants "
+        "(service_unit.py's RestartPreventExitStatus mirrors these same three)",
+    ),
 }
 RENDERERS.update(
     {

cli_agent_runner-0.2.19/agent_runner/_emit/__init__.py

@@ -0,0 +1,103 @@
+"""Event emission wrappers — extracted from api.py for module-size hygiene.
+
+Public facade over the ``_emit`` package: every sibling module in
+``agent_runner`` (and every test) imports from ``agent_runner._emit``
+directly, never from ``agent_runner._emit.<submodule>`` — this file is the
+one place a name crosses that boundary. All wrappers are re-exported from
+agent_runner.api for backward compatibility; plugins and supervisor should
+continue importing from agent_runner.api (e.g.
+``from agent_runner.api import emit_transient_error_detected``).
+
+Each wrapper exists to keep cli/serve_cmd.py from importing agent_runner.events
+directly — preserves the module-boundary architecture invariant. Local-import pattern
+inside each wrapper body keeps agent_runner.api import-cheap.
+
+Submodules are organised by domain: ``serve`` (supervisor control plane +
+config/schedule lifecycle), ``rounds`` (one round's own lifecycle),
+``memory`` (host/cgroup memory pressure), ``agent`` (the agent axis — plugin
+reports + throttle response).
+"""
+
+from __future__ import annotations
+
+from agent_runner._emit.agent import (  # noqa: F401 — public re-export
+    emit_agent_auth_error_detected,
+    emit_agent_usage_recorded,
+    emit_anomaly_repetitive_tool,
+    emit_transient_error_backoff_capped,
+    emit_transient_error_detected,
+    emit_transient_error_recovered,
+)
+from agent_runner._emit.memory import (  # noqa: F401 — public re-export
+    emit_host_cgroup_memory_limit,
+    emit_mem_pressure_deferred_to_cgroup,
+    emit_round_cgroup_memory,
+    emit_round_deferred,
+    emit_round_mem_critical_sample,
+    emit_round_mem_terminated,
+    emit_round_oom_killed,
+    emit_round_resumed,
+)
+from agent_runner._emit.rounds import (  # noqa: F401 — public re-export
+    emit_fresh_eyes_round_triggered,
+    emit_round_grace_extended,
+    emit_round_grace_kill,
+    emit_round_logs_prune_deferred,
+    emit_round_progress,
+    emit_round_substrate_after,
+    emit_round_substrate_before,
+    emit_round_supervisor_wedged,
+    emit_stale_index_lock_cleared,
+)
+from agent_runner._emit.serve import (  # noqa: F401 — public re-export
+    emit_config_broken,
+    emit_config_migrated,
+    emit_crash_loop,
+    emit_max_rounds_reached,
+    emit_mem_loop,
+    emit_mem_loop_persistent,
+    emit_rate_limit_stop,
+    emit_schedule_paused,
+    emit_schedule_phase_skipped,
+    emit_schedule_resumed,
+    emit_stalled_no_progress,
+    emit_stop_file_detected,
+)
+
+__all__ = [
+    "emit_agent_auth_error_detected",
+    "emit_agent_usage_recorded",
+    "emit_anomaly_repetitive_tool",
+    "emit_config_broken",
+    "emit_config_migrated",
+    "emit_crash_loop",
+    "emit_fresh_eyes_round_triggered",
+    "emit_host_cgroup_memory_limit",
+    "emit_max_rounds_reached",
+    "emit_mem_loop",
+    "emit_mem_loop_persistent",
+    "emit_mem_pressure_deferred_to_cgroup",
+    "emit_rate_limit_stop",
+    "emit_round_cgroup_memory",
+    "emit_round_deferred",
+    "emit_round_grace_extended",
+    "emit_round_grace_kill",
+    "emit_round_logs_prune_deferred",
+    "emit_round_mem_critical_sample",
+    "emit_round_mem_terminated",
+    "emit_round_oom_killed",
+    "emit_round_progress",
+    "emit_round_resumed",
+    "emit_round_substrate_after",
+    "emit_round_substrate_before",
+    "emit_round_supervisor_wedged",
+    "emit_schedule_paused",
+    "emit_schedule_phase_skipped",
+    "emit_schedule_resumed",
+    "emit_stale_index_lock_cleared",
+    "emit_stalled_no_progress",
+    "emit_stop_file_detected",
+    "emit_transient_error_backoff_capped",
+    "emit_transient_error_detected",
+    "emit_transient_error_recovered",
+]

cli_agent_runner-0.2.19/agent_runner/_emit/agent.py

@@ -0,0 +1,231 @@
+"""Event emission wrappers — the agent axis: what a per-CLI plugin reports
+(transient errors, auth failures, usage, anomalies) and the throttle
+response. Re-exported from ``agent_runner._emit`` (the package facade) —
+see its docstring.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def emit_transient_error_detected(
+    log_dir: Path,
+    *,
+    classification: str,
+    agent: str,
+    reset_at_epoch: int,
+    round_num: int,
+    raw: str,
+    phase: str = "",
+) -> None:
+    """Emit detection of a transient agent error (rate limit / 5xx / timeout).
+
+    ``phase`` is the rotation phase the failing round ran under ("" when the
+    config has no ``[phases]``). It lets a ``phase_policy = "skip"`` serve loop
+    step over *this* phase while a healthy sibling keeps running."""
+    from agent_runner._redact import redact_secrets
+    from agent_runner.events import TRANSIENT_ERROR_DETECTED, emit
+
+    raw = redact_secrets(raw)
+    emit(
+        log_dir,
+        TRANSIENT_ERROR_DETECTED,
+        classification=classification,
+        agent=agent,
+        reset_at_epoch=reset_at_epoch,
+        round_num=round_num,
+        raw=raw,
+        phase=phase,
+    )
+
+
+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,
+    *,
+    classification: str,
+    agent: str,
+    throttled_for_s: int,
+) -> None:
+    """Emit recovery from a transient error back-off (right before resuming)."""
+    from agent_runner.events import TRANSIENT_ERROR_RECOVERED, emit
+
+    emit(
+        log_dir,
+        TRANSIENT_ERROR_RECOVERED,
+        classification=classification,
+        agent=agent,
+        throttled_for_s=throttled_for_s,
+    )
+
+
+def emit_agent_usage_recorded(
+    log_dir: Path,
+    *,
+    agent: str,
+    model: str,
+    round_num: int,
+    input_tokens: int,
+    output_tokens: int,
+    cached_tokens: int,
+    cost_usd: float | None,
+    duration_ms: int,
+    models_breakdown: dict[str, dict[str, int]] | None = None,
+    cache_creation_tokens: int = 0,
+    tool_call_count: int = 0,
+    phase: str = "",
+    success: bool = True,
+) -> None:
+    """Emit per-round usage record from a CLI plugin.
+
+    Raw data only — aggregation (totals, projections, budget warnings) is
+    deferred to consumers and the capability layer.
+
+    Field semantics:
+    - ``input_tokens``: net non-cached input (both claude and gemini emit net;
+      total throughput = input_tokens + cached_tokens).
+    - ``cost_usd``: USD cost for the round, or None when CLI doesn't expose it
+      (gemini has no cost field; claude exposes total_cost_usd).
+    - ``models_breakdown``: only populated when a round used multiple models
+      (gemini multi-model rounds). None for claude (always single-model).
+    - ``cache_creation_tokens``: claude only — ``usage.cache_creation_input_tokens``,
+      independent count from ``cached_tokens`` (cache_read). Priced differently
+      from fresh input by the provider; the framework records the count only and
+      never interprets cost (no price tables here — see ``cost_usd`` above for the
+      one cost figure the framework passes through verbatim). Gemini has no
+      equivalent → 0.
+    - ``tool_call_count``: number of tool invocations the agent made in the round.
+      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``: 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
+
+    emit(
+        log_dir,
+        AGENT_USAGE_RECORDED,
+        agent=agent,
+        model=model,
+        round_num=round_num,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+        cost_usd=cost_usd,
+        duration_ms=duration_ms,
+        models_breakdown=models_breakdown,
+        cache_creation_tokens=cache_creation_tokens,
+        tool_call_count=tool_call_count,
+        phase=phase,
+        success=success,
+    )
+
+
+def emit_anomaly_repetitive_tool(
+    log_dir: Path,
+    *,
+    round_num: int,
+    tool_name: str,
+    target: str | None,
+    count: int,
+    window: int,
+) -> None:
+    """Emit when claude plugin detects the same (tool, target) tuple repeated
+    >= threshold times in a sliding window of tool-call events.
+
+    Claude-only (gemini JSONL stats summary does not expose per-tool events).
+    Default OFF: both anomaly_repetitive_window and anomaly_repetitive_threshold
+    must be > 0 in [monitor] config to activate.
+    """
+    from agent_runner.events import ANOMALY_REPETITIVE_TOOL, emit
+
+    emit(
+        log_dir,
+        ANOMALY_REPETITIVE_TOOL,
+        round_num=round_num,
+        tool_name=tool_name,
+        target=target,
+        count=count,
+        window=window,
+    )
+
+
+def emit_transient_error_backoff_capped(
+    log_dir: Path,
+    *,
+    classification: str,
+    agent: str,
+    requested_sleep_s: int,
+    applied_sleep_s: int,
+    original_reset_at_epoch: int | None = None,
+    applied_reset_at_epoch: int | None = None,
+    consecutive_count: int | None = None,
+    capped_by_absolute_max: bool | None = None,
+) -> None:
+    """Emit when supervisor adjusts the plugin-emitted transient back-off.
+
+    Fires in two cases:
+    1. **Exp backoff applied**: estimated-class transient errors
+       (`rate_limit_model` / `api_transient_5xx` / `api_timeout`) doubled
+       on consecutive failures. ``consecutive_count`` > 1, multiplier > 1×.
+    2. **Defensive cap hit**: malformed `reset_at_epoch` or the
+       30-min absolute cap clipped the wait. ``capped_by_absolute_max`` True.
+
+    Fields ``original_reset_at_epoch`` / ``applied_reset_at_epoch`` /
+    ``consecutive_count`` / ``capped_by_absolute_max`` are newer fields. Older
+    callers that pass only the first 4 kwargs continue to work; the new
+    fields are omitted from the payload when None.
+    """
+    from agent_runner.events import TRANSIENT_ERROR_BACKOFF_CAPPED, emit
+
+    kwargs: dict = {
+        "classification": classification,
+        "agent": agent,
+        "requested_sleep_s": requested_sleep_s,
+        "applied_sleep_s": applied_sleep_s,
+    }
+    if original_reset_at_epoch is not None:
+        kwargs["original_reset_at_epoch"] = original_reset_at_epoch
+    if applied_reset_at_epoch is not None:
+        kwargs["applied_reset_at_epoch"] = applied_reset_at_epoch
+    if consecutive_count is not None:
+        kwargs["consecutive_count"] = consecutive_count
+    if capped_by_absolute_max is not None:
+        kwargs["capped_by_absolute_max"] = capped_by_absolute_max
+
+    emit(log_dir, TRANSIENT_ERROR_BACKOFF_CAPPED, **kwargs)