cli-agent-runner 0.2.11__tar.gz → 0.2.13__tar.gz

{cli_agent_runner-0.2.11 → cli_agent_runner-0.2.13}/.vulture-whitelist.py

@@ -12,7 +12,6 @@ duration_s
 timed_out
 pid
 killed_for_grace
-grace_kill_children
 
 # agent_runner.api_types.Alert
 severity
@@ -248,15 +247,21 @@ path
 detect
 apply
 describe
+advisory
 
 # agent_runner.migrations.MigrationResult
 new_text
 applied
 manual
+advisory
 
 # agent_runner.monitor.LocalSource
 log_dir
 
+# agent_runner.monitor._EventTail
+offsets
+buffer
+
 # agent_runner.phase_select.Selection
 phase
 paused
@@ -287,6 +292,7 @@ name
 ok
 reason
 how_to_fix
+permanent
 
 # agent_runner.vcs_state.StashRef
 sha

{cli_agent_runner-0.2.11 → cli_agent_runner-0.2.13}/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.13] - 2026-09-02
+
+### Breaking
+- Config validation now rejects unknown keys in base `[agent]`/`[runtime]`/`[vcs]`/`[monitor]`, a table given as a scalar, unknown per-phase `[phases.<name>.prompt]` keys, and an argv `prompt_arg_template` missing `{prompt}`. **Run `agent-runner migrate` before `upgrade`**, as in 0.2.12.
+- systemd `serve` units grow `TimeoutStopSec` (now `round_timeout_s + 210`, up from `+60`) — re-render after upgrading.
+
+### Fixed
+- Round-child exit codes are classified by permanence, not a type whitelist: a config break stays 78, a self-healing environmental failure (lock contention, a git-status timeout, an unwritable log dir) now reliably reaches retryable 76, and everything else still falls to 1 so the crash-loop breaker bounds a genuine bug; serve itself still never exits 76.
+- `kill` reaps the whole round-and-agent process group; `stop`/`restart`/`uninstall` are drain-aware so a mid-round stop no longer leaves a systemd serve stopped or raises; service-mode detection checks systemd `is-active` instead of guessing; and `monitor_auto_stop_triggered` fires only after a confirmed stop.
+- `install --system` rejects control characters in `work_dir`/`log_dir`/config path, closing a root-injection path through the rendered unit.
+- `read_json`/orphan-state reads survive a non-UTF-8 byte or a directory instead of crashing serve; a git-status timeout mid-round no longer drops the round's own bookkeeping (`dirty_check_failed`).
+- Throttle readers (serve's loop-top gate, the skip path, `peek`, monitor) converge on one reset source; the back-off sleep now wakes early on an NTP clock jump.
+
+### Notes
+- New event kind: `dirty_check_failed`. `peek --json` schema is unchanged this release.
+
+See `docs/migrations/0.2.md`.
+
+## [0.2.12] - 2026-08-31
+
+### Breaking
+- Config validation now hard-rejects footguns that used to load silently: a scalar where a list is required (`phases.list`, `[agent] command`, `prompt_arg_template`, `[prompt] files`), an empty `[agent] command` / empty top-level `[prompt] files`, unknown keys in `[schedule]`/`[prompt]`, and `threshold > window`. **Run `agent-runner migrate` BEFORE `upgrade`** — the orchestrated upgrade runs the old binary's migrate, which cannot self-cross this break. Every new error names `agent-runner migrate`.
+- systemd `serve` unit adds `StartLimitIntervalSec`/`StartLimitBurst`; re-render or hand-edit existing units.
+
+### Fixed
+- The monitor no longer dies on a non-UTF-8 byte or an odd plugin severity; each builtin detector is isolated (`detector_error` event) and a hung round is TERM→grace→killpg'd (`round_supervisor_wedged`) instead of orphaning the agent or latching `hung`.
+- Environmental startup failures (ENOSPC, mount hiccup, unclassified) exit 76 and keep serve retrying at a fixed back-off until they heal, instead of tripping the crash-loop breaker; deterministic config failures give up by name (exit 78).
+- A git-commit timeout leaves no surviving `.git/index.lock` (self-caused only; `stale_index_lock_cleared`); a stop-file lands within one back-off chunk.
+- `status`/`kill`/`restart` report and act on real service state: liveness falls back to `serve.pid` when `systemctl` is absent, and `restart` refuses on non-service modes before stopping.
+- `upgrade` runs the new binary's `migrate` before the smoke check, restores the config on rollback, and emits `upgrade_start_failed` with a remedy when the new version installs but won't start.
+- `json_tail` no longer lets a blank-line flood evict the terminal round-log record; `init` commits only its scaffold files.
+
+### Notes
+- New event kinds: `detector_error`, `round_supervisor_wedged`, `stale_index_lock_cleared`, `upgrade_start_failed`. `RestartPreventExitStatus` stays `78 75` — environmental failures (round exit 76) are retried inside serve rather than stopping it.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.11] - 2026-08-29
 
 ### Changed

{cli_agent_runner-0.2.11 → cli_agent_runner-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.11
+Version: 0.2.13
 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

{cli_agent_runner-0.2.11 → cli_agent_runner-0.2.13}/agent_runner/_docgen.py

@@ -157,10 +157,15 @@ def render_event_kinds_list() -> str:
 
 
 def _render_migrate_transforms() -> str:
-    """Bullet list of the transforms `agent-runner migrate` applies, from the registry."""
-    from agent_runner.migrations import MIGRATIONS
-
-    return "\n".join(f"- {m.describe}" for m in MIGRATIONS)
+    """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
+    exact offending key found in a real config); rendered here with `{}`, which degrades
+    to the same generic instruction since there's no config in hand."""
+    from agent_runner.migrations import MIGRATIONS, _describe
+
+    # No config in hand here, so pass an empty parsed dict: a `parsed -> str`
+    # describe degrades to its generic instruction, same rule as the manual report.
+    return "\n".join(f"- {_describe(m, {})}" for m in MIGRATIONS)
 
 
 def _subparser_action() -> argparse.Action:

{cli_agent_runner-0.2.11 → cli_agent_runner-0.2.13}/agent_runner/_emit.py

@@ -27,9 +27,11 @@ __all__ = [
     "emit_round_progress",
     "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_stop_file_detected",
     "emit_transient_error_backoff_capped",
     "emit_transient_error_detected",
@@ -52,7 +54,8 @@ def emit_max_rounds_reached(log_dir: Path, *, rounds_completed: int, max_rounds:
 
 
 def emit_config_broken(log_dir: Path, *, reason: str) -> None:
-    """Emit config_broken (serve stopped on a permanent startup-battery failure)."""
+    """Emit config_broken (serve gave up on a permanent, non-self-healing failure —
+    a startup-battery check, or any other ConfigError-classified round exit)."""
     from agent_runner.events import CONFIG_BROKEN, emit
 
     emit(log_dir, CONFIG_BROKEN, reason=reason)
@@ -68,7 +71,7 @@ def emit_crash_loop(log_dir: Path, *, consecutive: int, exit_code: int, log_path
     from agent_runner.events import CRASH_LOOP, emit
 
     try:
-        reason = redact_secrets(log_path.read_text(errors="replace")[-2000:])
+        reason = redact_secrets(log_path.read_text(encoding="utf-8", errors="replace")[-2000:])
     except OSError:
         reason = ""
     emit(log_dir, CRASH_LOOP, consecutive=consecutive, exit_code=exit_code, reason=reason)
@@ -98,6 +101,15 @@ def emit_stop_file_detected(
     )
 
 
+def emit_stale_index_lock_cleared(log_dir: Path, *, lock_path: str, round_num: int) -> None:
+    """Emit when serve removed a .git/index.lock that its own timed-out+killed git
+    call orphaned. Single-writer: serve holds the round lock, so any lock surviving
+    our kill is ours to clear."""
+    from agent_runner.events import STALE_INDEX_LOCK_CLEARED, emit
+
+    emit(log_dir, STALE_INDEX_LOCK_CLEARED, lock_path=lock_path, round_num=round_num)
+
+
 def emit_schedule_paused(
     log_dir: Path, *, active_window: str, resume_at: str, timezone: str, phase: str = ""
 ) -> None:
@@ -168,6 +180,18 @@ def emit_round_substrate_after(
     )
 
 
+def emit_round_supervisor_wedged(
+    log_dir: Path, *, pid: int, timeout_s: int, log_path: Path
+) -> None:
+    """Emit when the round subprocess blew past the outer ceiling and serve had to
+    TERM/kill it (the round supervisor was wedged — not doing its own bounded
+    post-round cleanup). Distinct from round_timeout_kill (the AGENT hit the inner
+    wall inside a healthy round)."""
+    from agent_runner.events import ROUND_SUPERVISOR_WEDGED, emit
+
+    emit(log_dir, ROUND_SUPERVISOR_WEDGED, pid=pid, timeout_s=timeout_s, log_path=str(log_path))
+
+
 def emit_fresh_eyes_round_triggered(log_dir: Path, *, round_num: int, every_n: int) -> None:
     """Emit fresh-eyes signal trigger event (only on triggered rounds)."""
     from agent_runner.events import FRESH_EYES_ROUND_TRIGGERED, emit
@@ -292,8 +316,11 @@ def emit_agent_usage_recorded(
     - ``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). Billed at ~25% premium
-      over fresh input per Anthropic pricing. Gemini has no equivalent → 0.
+      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``.

cli_agent_runner-0.2.13/agent_runner/_resolve.py

@@ -0,0 +1,120 @@
+"""Internal identity/location resolver (Group C, 0.2.13 "close the seams").
+
+Project name, config path, unit filename and log_dir were each derived
+independently at several call sites and could disagree when ``work_dir`` and
+the TOML's own directory differ. This module is the single source for all
+four; the divergent call sites route through it instead of re-deriving. It
+also carries ``guard_against_clobber``, ``api.install``'s same-basename
+sibling-unit guard — a natural fit since it works entirely off unit-file
+identity (``WorkingDirectory=``) rather than any install-specific state.
+
+INTERNAL ONLY -- not a public/documented contract. Exposing a resolver as a
+public contract is deferred to 0.3.
+
+Leaf module: imports only ``agent_runner.config`` and
+``agent_runner.service_unit`` (both leaves themselves), so anything in the
+package can import this without risking a cycle.
+
+Lenient/strict split (spec-review correction): validating the project
+name on the serve/round/init path would newly reject any ``work_dir`` whose
+basename has a space or CJK characters -- common on macOS dev boxes -- an
+unflagged BREAK, since only lifecycle/observe verbs validate today. So
+``strict=True`` applies ONLY where the name is interpolated into a unit
+filename / ssh / systemd identity (api.py's lifecycle verbs, install,
+lifecycle.py, install_cmd.py); ``strict=False`` for descriptive uses
+(``hook_ctx.project`` in runner.py, the scaffolded toml's ``{project}`` in
+scaffold.py) that must keep accepting any basename.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from agent_runner.config import load_config
+from agent_runner.service_unit import serve_unit_filename
+
+_PROJECT_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def project_name(work_dir: Path, *, strict: bool) -> str:
+    """Derive the project name from ``work_dir``'s basename.
+
+    strict=True rejects anything but ``[A-Za-z0-9._-]+`` -- required wherever
+    the name is interpolated into a unit filename / ssh / systemd identity.
+    strict=False accepts any non-empty basename (spaces, CJK, etc.) -- for
+    descriptive uses where the name is never shelled out or used as a
+    filesystem/systemd token by itself.
+    """
+    name = work_dir.resolve().name or "default"
+    if strict and not _PROJECT_NAME_RE.match(name):
+        raise ValueError(
+            f"invalid project name {name!r}: must match [A-Za-z0-9._-]+. "
+            "The project name is the basename of work_dir and is interpolated into "
+            "ssh remote commands and systemd unit filenames; shell metacharacters "
+            "and path separators are rejected."
+        )
+    return name
+
+
+def config_path(args) -> Path:
+    """Resolve the config TOML path CLI ``args`` refer to (``--config``,
+    default ``./agent-runner.toml``).
+
+    Single source for "given argparse args, which agent-runner.toml" so every
+    CLI bootstrap step (which runs before a ``Config`` exists to read
+    ``runtime.work_dir`` back from) agrees on the same file, instead of each
+    reconstructing its own getattr/default dance.
+    """
+    cfg = getattr(args, "config", None)
+    return Path(cfg).resolve() if cfg is not None else Path("agent-runner.toml").resolve()
+
+
+def unit_filename(project: str) -> str:
+    """Thin wrap of the existing ``service_unit.serve_unit_filename`` -- the
+    single name every unit-filename call site should go through."""
+    return serve_unit_filename(project)
+
+
+def log_dir(work_dir: Path) -> Path:
+    """Return the configured log_dir from ``<work_dir>/agent-runner.toml``.
+
+    Falls back to the conventional ``~/.agent-runner/<project>/logs`` only
+    when the toml is missing there, keeping lifecycle/observe verbs aligned
+    with where ``serve_cmd.py`` actually writes ``serve.pid``.
+    """
+    cfg_path = work_dir / "agent-runner.toml"
+    if cfg_path.exists():
+        return load_config(cfg_path).runtime.log_dir
+    return Path.home() / ".agent-runner" / project_name(work_dir, strict=True) / "logs"
+
+
+def _unit_owner(serve_path: Path) -> Path | None:
+    """Parse an existing unit's ``WorkingDirectory=`` line, or None if the file
+    doesn't exist / can't be read / has no such line."""
+    try:
+        text = serve_path.read_text()
+    except OSError:
+        return None
+    for line in text.splitlines():
+        if line.startswith("WorkingDirectory="):
+            return Path(line.removeprefix("WorkingDirectory="))
+    return None
+
+
+def guard_against_clobber(serve_path: Path, work_dir: Path, *, force: bool) -> None:
+    """Refuse to overwrite a same-basename sibling project's unit.
+
+    The unit filename is derived from the project name (work_dir's basename)
+    alone, so two unrelated projects sharing a basename — or the same project
+    moved to a new path — would silently clobber each other's install.
+    force=True is the explicit override for the moved-repo case (``api.install``).
+    """
+    owner = _unit_owner(serve_path)
+    if owner is None or owner == work_dir or force:
+        return
+    raise FileExistsError(
+        f"{serve_path} already manages a different project at {owner} "
+        f"(this is {work_dir}); pass force=True to overwrite "
+        "(e.g. after moving/renaming that project's directory)."
+    )

cli_agent_runner-0.2.13/agent_runner/_serve_policy.py

@@ -0,0 +1,189 @@
+"""Pure serve restart policy — no I/O, no clock, no events read.
+
+Extracted from api.py (0.2.12 Group G): serve_cmd imports the decision + exit
+codes from here directly (see the architecture allowlist); api.py re-exports
+them for external back-compat. Kept dependency-free so the serve loop stays a
+thin dispatcher and the policy is unit-testable in isolation.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from agent_runner.config import ConfigError
+
+# Exit code for a permanent (no-retry) startup-battery failure. A broken config
+# does not self-heal between rounds, so serve STOPS rather than respawning it
+# forever. 78 = EX_CONFIG (sysexits) — avoids argparse's 2 and the generic 1.
+PERMANENT_CONFIG_EXIT = 78
+
+# Exit code serve returns when the crash-loop breaker trips (a give-up stop, like
+# config_broken). Distinct from 78 so `systemctl status` / SuccessExitStatus can
+# tell the two "needs intervention" stops apart. 75 = EX_TEMPFAIL (sysexits).
+# The systemd unit lists both in RestartPreventExitStatus so a deliberate stop
+# stays stopped (and visibly failed) while an unexpected supervisor crash restarts.
+CRASH_LOOP_EXIT = 75
+
+# Exit code for an ENVIRONMENTAL startup-battery failure (ENOSPC, mount hiccup,
+# an unclassified check): recoverable, unlike a permanent config break. NOT in
+# the unit's RestartPreventExitStatus (stays "78 75") so 76 restarts; treated
+# exactly like an active throttle (post_round_decision), so serve keeps
+# retrying at a fixed doubled delay with the crash-loop breaker disarmed,
+# staying alive until the environment heals. StartLimit bounds only repeated
+# serve-PROCESS death, not this round-level path. 76 = EX_PROTOCOL (sysexits).
+ENV_BATTERY_EXIT = 76
+
+# Crash-loop circuit breaker (b12). The serve loop escalates the restart delay
+# on consecutive UNKNOWN short crashes (non-zero exit, short duration, no
+# classified transient) and STOPS after CRASH_LOOP_THRESHOLD of them — the Run 6
+# ~100-empty-rounds scar. Recoverable-slow failures (rate limit / 5h quota / 5xx
+# / timeout) are already handled by the transient-error throttle and never reach
+# this path. A clean (exit 0), long, or classified-transient round resets the run.
+CRASH_LOOP_THRESHOLD = 5
+CRASH_LOOP_SHORT_EXIT_S = 60  # mirrors monitor.SHORT_EXIT_THRESHOLD_S
+CRASH_LOOP_MAX_DELAY_S = 1800  # cap the escalating restart delay (30 min)
+
+
+class EnvironmentalError(Exception):
+    """Marks a round-child failure as ENVIRONMENTAL (recoverable) rather than a
+    permanent config break — classify_round_exit maps it to ENV_BATTERY_EXIT
+    (76), same treatment as an active throttle: serve retries at a flat back-off
+    with the crash-loop breaker disarmed.
+
+    A raise site elsewhere in the package (runner.LockHeldError,
+    vcs_state.GitTimeout) mixes this in alongside its own base class instead of
+    _serve_policy importing every module that raises one — this leaf module
+    sits BELOW runner.py/vcs_state.py in the import graph (both reach here via
+    api.py already), so importing upward would cycle. classify_round_exit
+    matches this marker, not the concrete class or its OTHER base.
+    """
+
+
+# The action strings below are the restart-action enum, not events.py kinds:
+# "continue" has no constant, and a constant cannot sit inside Literal[...].
+def post_round_decision(
+    *,
+    returncode: int,
+    duration_s: float,
+    throttle_active: bool,
+    consecutive: int,
+    restart_delay_s: int,
+) -> tuple[Literal["config_broken", "crash_loop", "continue"], int, int]:
+    """Restart policy after one round — keeps the serve loop a thin dispatcher.
+
+    Returns ``(action, delay_s, consecutive)`` where action is:
+    - ``"config_broken"`` — permanent startup failure (b18): stop.
+    - ``"crash_loop"`` — CRASH_LOOP_THRESHOLD consecutive unknown short crashes
+      (b12): stop. An unknown short crash is a non-zero, fast exit with no
+      classified transient (rate-limit/5xx/timeout are handled by the throttle).
+    - ``"continue"`` — sleep ``delay_s`` then run the next round.
+
+    A clean (exit 0), long, or transient round resets ``consecutive`` to 0; an
+    unknown short crash escalates the delay (restart × 2ⁿ, capped) until the stop.
+    An ``ENV_BATTERY_EXIT`` (76, environmental startup-battery failure) is treated
+    exactly like an active throttle: it takes the flat ``restart_delay_s * 2``
+    delay below (never escalating) and resets ``consecutive`` to 0, so it never
+    counts toward the crash-loop breaker — a short environmental outage (ENOSPC,
+    mount hiccup) never trips ``crash_loop``. This always returns ``"continue"``,
+    so serve itself never exits 76 and systemd's StartLimit window never engages
+    for this path; a *persistent* environmental failure keeps serve alive
+    retrying at the doubled delay until the environment heals. StartLimit bounds
+    only repeated serve-PROCESS death, independent of this round-level path.
+    """
+    if returncode == PERMANENT_CONFIG_EXIT:
+        return ("config_broken", 0, consecutive)
+    throttle_active = throttle_active or returncode == ENV_BATTERY_EXIT
+    unknown_short_crash = (
+        returncode != 0 and duration_s < CRASH_LOOP_SHORT_EXIT_S and not throttle_active
+    )
+    if unknown_short_crash:
+        consecutive += 1
+        if consecutive >= CRASH_LOOP_THRESHOLD:
+            return ("crash_loop", 0, consecutive)
+        delay = min(restart_delay_s * 2**consecutive, CRASH_LOOP_MAX_DELAY_S)
+        return ("continue", delay, consecutive)
+    delay = restart_delay_s if returncode == 0 else restart_delay_s * 2
+    return ("continue", delay, 0)
+
+
+def classify_round_exit(exc: BaseException) -> int:
+    """The round-child exit-code CLASSIFIER (Group A) — permanence, not exception
+    identity, decides serve's response. Replaces the old exception *whitelist*
+    (``cli/__init__.py`` mapped only ``ConfigError``->78, ``round_cmd.py`` only
+    ``KeyboardInterrupt``->130; ~10 other classes fell through to Python's own
+    uncaught-exception exit 1 — neither retry-76 nor stay-stopped-78/75).
+
+    - ``ConfigError`` (won't self-heal) -> ``PERMANENT_CONFIG_EXIT`` (78).
+    - ``EnvironmentalError``-marked (self-heals) -> ``ENV_BATTERY_EXIT`` (76).
+    - ``KeyboardInterrupt`` (SIGTERM/SIGINT) -> 130, the shell's convention.
+    - ``SystemExit`` passes its own code through unchanged (an int code; a
+      non-int/absent code — argparse-style ``sys.exit("msg")`` or a bare
+      ``sys.exit()`` — falls to 1, same as unclassified).
+    - Anything else, INCLUDING a totally unclassified traceback, falls to 1 so
+      the crash-loop breaker still bounds a genuine supervisor bug. Do NOT
+      default unclassified -> 76: ``post_round_decision`` resets its counter on
+      76, so an arbitrary bug would loop forever at the doubled delay with no
+      breaker and no detector. The battery's own "unclassified -> environmental"
+      rule (``startup_check.py``) governs *authored probes*, not arbitrary round
+      tracebacks — a different trust boundary.
+
+    Never returns ``CRASH_LOOP_EXIT`` (75) — that verdict belongs exclusively to
+    serve's own ``post_round_decision``, counting consecutive unknown short
+    crashes; a round child never claims it directly.
+    """
+    if isinstance(exc, SystemExit):
+        return exc.code if isinstance(exc.code, int) else 1
+    if isinstance(exc, KeyboardInterrupt):
+        return 130
+    if isinstance(exc, ConfigError):
+        return PERMANENT_CONFIG_EXIT
+    if isinstance(exc, EnvironmentalError):
+        return ENV_BATTERY_EXIT
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# Round-timeout budget (Group C, seam 3 — 0.2.13). TimeoutStopSec
+# (service_unit.py, systemd's SIGKILL deadline after `systemctl stop`) and the
+# outer round-wall ceiling (api.outer_round_ceiling_s, the in-process watchdog
+# around the round subprocess) were derived independently and could drift —
+# TimeoutStopSec only added a flat 60s to the inner round timeout, with no
+# margin for the outer ceiling's own reap/git-commit/hook slack, let alone the
+# SIGTERM-to-round-child grace on top of that. One function computes both so
+# they cannot disagree.
+#
+# service_unit.py must not import api.py (cycle: api.py already imports
+# service_unit.render_serve_unit), so this lives here — a dependency-free leaf
+# both service_unit.py and api.py can import. Its margin constants are
+# LITERAL mirrors of the real sources of truth (agent_runtime.REAP_GRACE_S,
+# vcs_state.GIT_COMMIT_TIMEOUT_S, api._ROUND_TERM_GRACE_S) rather than
+# imports, same as service_unit.py's literal "78 75" RestartPreventExitStatus
+# mirroring PERMANENT_CONFIG_EXIT/CRASH_LOOP_EXIT — pinned by
+# test_timeout_budget_invariant.py so a change to any of the three can't
+# silently drift this budget out of sync.
+_REAP_GRACE_S = 5
+_GIT_COMMIT_TIMEOUT_S = 120
+_HOOK_ALLOWANCE_S = 60  # slack for post-round hooks between the inner wall and the ceiling
+_ROUND_TERM_GRACE_S = 15  # mirrors api._ROUND_TERM_GRACE_S / serve_cmd._ROUND_TERM_GRACE_S
+_STOP_GRACE_MARGIN_S = 10  # pad above _ROUND_TERM_GRACE_S for systemd stop-request overhead
+
+
+def timeout_budget(round_timeout_s: int) -> tuple[int, int]:
+    """Single source for the round-timeout safety budget.
+
+    Returns ``(timeout_stop_sec, outer_ceiling_s)``:
+
+    - ``outer_ceiling_s`` — the in-process outer wall-clock ceiling for the
+      round subprocess (``api.outer_round_ceiling_s``): ``round_timeout_s``
+      plus reap grace + git-commit ceiling + hook allowance, so it only trips
+      when the round supervisor itself is wedged, never during its own
+      bounded post-round cleanup.
+    - ``timeout_stop_sec`` — systemd's ``TimeoutStopSec``
+      (``service_unit.py``): must clear ``outer_ceiling_s`` by enough for a
+      SIGTERM to reach and drain the round (``_ROUND_TERM_GRACE_S``) plus a
+      stop-request overhead pad, so `systemctl stop` never SIGKILLs a round
+      that is draining normally.
+    """
+    outer_ceiling_s = round_timeout_s + _REAP_GRACE_S + _GIT_COMMIT_TIMEOUT_S + _HOOK_ALLOWANCE_S
+    timeout_stop_sec = outer_ceiling_s + _ROUND_TERM_GRACE_S + _STOP_GRACE_MARGIN_S
+    return timeout_stop_sec, outer_ceiling_s