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

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

@@ -228,6 +228,11 @@ path
 # agent_runner.monitor.LocalSource
 log_dir
 
+# agent_runner.round_log.PruneOutcome
+deleted
+deferred
+existing
+
 # agent_runner.startup_check.CheckResult
 name
 ok

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

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.6] - 2026-07-28
+
+### Changed
+- **Round-log pruning is now opt-in.** `runtime.round_log_retention` defaults to `0` (never prune) and `0` is now a legal value — previously both `0` and `-1` were rejected, so there was no off switch. Retaining too much is defended (`disk_warning` at 90%, `disk_critical` at 95% auto-stops the service); deleting too much was not defended at all. Both round-log families are affected, including the serve-level `round-<N>.log` family that had been capped at 100 for many releases. Set `round_log_retention = 100` for the previous behavior.
+
+### Fixed
+- A prune that would delete more files than it keeps is now refused wholesale — nothing is deleted — so opting in on an existing backlog, or lowering the value later, can no longer wipe history in one pass. 0.2.4 and 0.2.5 did exactly that on their first post-upgrade round (one deployment: 12,193 of 12,293 transcripts, ~6.4 GB).
+
+### Added
+- `round_logs_prune_deferred` event — emitted on every prune attempt the bulk guard defers, carrying `directory`, `existing`, `keep`, `would_delete` and a hint naming `runtime.round_log_retention`. Resolve by raising retention above the backlog or deleting the files yourself; the guard never blocks a round. Retention `0` emits nothing.
+
+See `docs/migrations/0.2.6.md`.
+
 ## [0.2.5] - 2026-07-27
 
 ### Added
@@ -950,7 +963,8 @@ 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.5...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.6...HEAD
+[0.2.6]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.2...v0.2.3

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.5
+Version: 0.2.6
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme
@@ -93,7 +93,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-12 named defenses, structured as data — see `agent-runner peek --select defenses`.
+13 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/README.md

@@ -57,7 +57,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 
 ## Defenses (built in)
 
-12 named defenses, structured as data — see `agent-runner peek --select defenses`.
+13 named defenses, structured as data — see `agent-runner peek --select defenses`.
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 

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

@@ -22,6 +22,7 @@ __all__ = [
     "emit_rate_limit_stop",
     "emit_round_grace_extended",
     "emit_round_grace_kill",
+    "emit_round_logs_prune_deferred",
     "emit_round_progress",
     "emit_round_substrate_after",
     "emit_round_substrate_before",
@@ -346,6 +347,42 @@ def emit_round_grace_extended(
     )
 
 
+def emit_round_logs_prune_deferred(
+    log_dir: Path,
+    *,
+    directory: str,
+    existing: int,
+    keep: int,
+    would_delete: int,
+) -> None:
+    """Emit when a round-log prune was deferred because it would be *bulk*
+    (it would delete more files than it keeps), so nothing was deleted.
+
+    ``directory`` is the directory holding the family — ``{log_dir}/rounds``
+    for agent transcripts, ``{log_dir}`` for the serve-level ``round-<N>.log``
+    files. Re-emitted on every prune attempt while the condition holds: the
+    deferral is permanent until an operator acts, and a one-shot event would
+    be missed by anyone who started watching later.
+
+    The hint is composed here rather than at the call sites so both families
+    name the same knob with the same wording.
+    """
+    from agent_runner.events import ROUND_LOGS_PRUNE_DEFERRED, emit
+
+    emit(
+        log_dir,
+        ROUND_LOGS_PRUNE_DEFERRED,
+        directory=directory,
+        existing=existing,
+        keep=keep,
+        would_delete=would_delete,
+        hint=(
+            f"nothing deleted; raise runtime.round_log_retention to >= {existing} "
+            f"to keep this backlog, or delete files in {directory} yourself"
+        ),
+    )
+
+
 def emit_anomaly_repetitive_tool(
     log_dir: Path,
     *,

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.2.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
 
 __commit_id__ = commit_id = None

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

@@ -742,6 +742,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_rate_limit_stop,
     emit_round_grace_extended,
     emit_round_grace_kill,
+    emit_round_logs_prune_deferred,
     emit_round_progress,
     emit_round_substrate_after,
     emit_round_substrate_before,

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/cli/serve_cmd.py

@@ -15,6 +15,7 @@ import signal
 import subprocess  # noqa: TID251
 import sys
 import time
+from pathlib import Path
 
 from agent_runner._substrate import compute_git_head, compute_paths_hash
 from agent_runner._throttle import _check_throttle_state
@@ -26,6 +27,7 @@ from agent_runner.api import (
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
+    emit_round_logs_prune_deferred,
     emit_round_substrate_after,
     emit_round_substrate_before,
     emit_stop_file_detected,
@@ -56,6 +58,24 @@ def _resolve_max_rounds(*, cli_value: int | None, config_value: int | None) -> i
     return effective
 
 
+def _prune_serve_round_logs(log_dir: Path, retention: int) -> None:
+    """Prune the serve-level ``round-<N>.log`` family; report a deferred prune.
+
+    A prune that would delete more files than it keeps is deferred wholesale
+    (nothing is deleted) and surfaced as ``round_logs_prune_deferred`` — the
+    same contract ``rounds/`` gets at round start, since one knob governs both.
+    """
+    outcome = prune_old_round_logs(log_dir, retention)
+    if outcome.deferred:
+        emit_round_logs_prune_deferred(
+            log_dir,
+            directory=str(log_dir),
+            existing=outcome.existing,
+            keep=retention,
+            would_delete=outcome.deferred,
+        )
+
+
 def _is_fresh_eyes_round(*, round_num: int, every_n: int | None) -> bool:
     """True if this round should signal fresh-eyes mode to the agent subprocess.
 
@@ -106,7 +126,7 @@ def cmd(args) -> int:
 
     # Pre-loop cleanup: remove stale sentinel, prune old round logs.
     (log_dir / ".agent-done").unlink(missing_ok=True)
-    prune_old_round_logs(log_dir, cfg.runtime.round_log_retention)
+    _prune_serve_round_logs(log_dir, cfg.runtime.round_log_retention)
 
     round_env = {**os.environ, "AGENT_RUNNER_LOG_DIR": str(log_dir)}
 

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/config.py

@@ -39,7 +39,7 @@ class RuntimeConfig:
     round_timeout_s: int = 1800
     restart_delay_s: int = 3
     disable_pre_round_hooks: bool = False
-    round_log_retention: int = 100
+    round_log_retention: int = 0  # 0 = never prune (pruning is opt-in)
     narrative_file: Path | None = None
     transient_error_action: Literal["back_off", "skip", "stop"] = "back_off"
     max_rounds: int | None = None  # None = unbounded
@@ -439,8 +439,8 @@ def load_config(toml_path: Path) -> Config:
             runtime_d.get("disable_pre_round_hooks", False),
             field="runtime.disable_pre_round_hooks",
         ),
-        round_log_retention=_require_positive_int(
-            runtime_d.get("round_log_retention", 100), field="runtime.round_log_retention"
+        round_log_retention=_require_non_negative_int(
+            runtime_d.get("round_log_retention", 0), field="runtime.round_log_retention"
         ),
         narrative_file=_expand_and_resolve(str(runtime_d["narrative_file"]), project_name, work_dir)
         if "narrative_file" in runtime_d

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/defenses.py

@@ -102,6 +102,17 @@ def catalog(cfg: Config) -> list[Defense]:
             guarded_by=Path("tests/unit/test_serve_crash_loop.py"),
             current_state="active",
         ),
+        Defense(
+            name="bulk_round_log_prune_guard",
+            value="a prune deleting more files than it keeps deletes nothing",
+            codifies=(
+                "0.2.4 — rounds/ pruning shipped against backlogs it never built; "
+                "one deployment's first post-upgrade round would have deleted "
+                "12,193 of 12,293 transcripts silently"
+            ),
+            guarded_by=Path("tests/unit/test_round_log_helpers.py"),
+            current_state="active",
+        ),
         Defense(
             name="flock_concurrency",
             value="agent-runner.lock",

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/events.py

@@ -55,6 +55,7 @@ PROMPT_OVERWRITTEN = "prompt_overwritten"
 ROUND_END = "round_end"
 ROUND_GRACE_EXTENDED = "round_grace_extended"
 ROUND_GRACE_KILL = "round_grace_kill"
+ROUND_LOGS_PRUNE_DEFERRED = "round_logs_prune_deferred"
 ROUND_PROGRESS = "round_progress"
 ROUND_START = "round_start"
 ROUND_SUBSTRATE_AFTER = "round_substrate_after"

cli_agent_runner-0.2.6/agent_runner/round_log.py

@@ -0,0 +1,160 @@
+"""Round-log file operations for serve_cmd.
+
+Extracted from serve_cmd to keep that module a thin dispatcher.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_runner.api import read_round_num
+
+ROUND_CURRENT_LINK = "round-current.log"
+_AGENT_ROUND_LOG_RE = re.compile(r"^R(\d+)-")
+
+
+@dataclass(frozen=True)
+class PruneOutcome:
+    """What one prune pass did to a round-log family.
+
+    ``deleted`` and ``deferred`` are never both nonzero: a pass either prunes
+    normally, defers wholesale (see the bulk guard below), or does not run at
+    all (pruning disabled). ``existing`` is the total number of files the pass
+    considered — carried so a caller reporting a deferral does not have to
+    re-derive it from the slice rule.
+    """
+
+    deleted: int
+    deferred: int
+    existing: int
+
+
+def _pruning_disabled(keep: int) -> bool:
+    """``keep == 0`` disables pruning entirely — the default.
+
+    Distinct from a deferral, and deliberately reported as neither deleted nor
+    deferred: 0 is the operator's expressed intent, not a backlog awaiting a
+    decision, so callers emit nothing. Unbounded growth is the accepted trade
+    and it is not undefended — ``disk_warning`` (90%) alerts and
+    ``disk_critical`` (95%) auto-stops the service.
+    """
+    return keep == 0
+
+
+def _is_bulk(stale: int, keep: int) -> bool:
+    """A prune that would remove more files than it keeps is a *bulk* prune.
+
+    Bulk prunes delete nothing. In steady state a pass removes ~1 file, so
+    this can only trip on the first encounter with a pre-existing backlog or
+    after an operator drastically lowers ``runtime.round_log_retention`` —
+    both cases where wiping history is far likelier to be an accident than an
+    intent. The supervisor never performs a bulk deletion on its own; the
+    operator raises retention (the backlog then falls inside the kept window
+    and normal pruning resumes) or clears the files themselves.
+    """
+    return stale > keep
+
+
+def atomic_relink(link: Path, target: Path) -> None:
+    """Atomically replace ``link`` to point at ``target``.
+
+    Uses ``os.symlink`` + ``os.replace``: create the symlink at a temp path,
+    then atomically rename it to the final link name.
+    """
+    tmp = link.with_suffix(link.suffix + ".tmp")
+    tmp.unlink(missing_ok=True)
+    os.symlink(target.name, tmp)
+    os.replace(tmp, link)
+
+
+def prune_old_round_logs(log_dir: Path, retention: int) -> PruneOutcome:
+    """Keep most-recent ``retention`` round-*.log files by mtime; unlink the rest.
+
+    Excludes the ``round-current.log`` symlink — that's not a regular log file.
+    Called once at serve startup (no mid-session pruning, avoid race with
+    active writes).
+
+    ``retention == 0`` (the default) never prunes. Otherwise subject to the
+    bulk guard (:func:`_is_bulk`): a startup that would delete more than it
+    keeps deletes nothing and reports the deferral instead. ``round_log_retention``
+    governs both round-log families, so both opting in and lowering the value
+    mean the same thing in both.
+    """
+    if _pruning_disabled(retention):
+        return PruneOutcome(deleted=0, deferred=0, existing=0)
+    logs = sorted(
+        log_dir.glob("round-*.log"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    logs = [p for p in logs if p.name != ROUND_CURRENT_LINK]
+    stale = logs[retention:]
+    if _is_bulk(len(stale), retention):
+        return PruneOutcome(deleted=0, deferred=len(stale), existing=len(logs))
+    for old in stale:
+        old.unlink(missing_ok=True)
+    return PruneOutcome(deleted=len(stale), deferred=0, existing=len(logs))
+
+
+def prune_rounds_dir(rounds_dir: Path, keep: int) -> PruneOutcome:
+    """Keep the ``keep`` highest-numbered ``R<n>-*.log`` agent logs; unlink the rest.
+
+    Ordered by the round number parsed out of the filename — not by string sort
+    (``R9`` must not outrank ``R10``) and not by mtime (a restore or copy can
+    rewrite that; the round number is the semantic order). Names that don't
+    match are left alone. Called at round start, before the current round's log
+    is minted, so the active log is never a deletion candidate.
+
+    ``keep == 0`` (the default) never prunes: these transcripts are forensic
+    material — the record used to reconstruct a round lost to a dropped
+    connection, or to verify that a fix actually worked — so retaining them is
+    the default and discarding them is opt-in. When pruning IS enabled, the
+    bulk guard (:func:`_is_bulk`) still applies: a pass that would delete more
+    than it keeps deletes nothing, so opting in (or later lowering the value)
+    does not consume a backlog in one shot.
+    """
+    if _pruning_disabled(keep):
+        return PruneOutcome(deleted=0, deferred=0, existing=0)
+    if not rounds_dir.is_dir():
+        return PruneOutcome(deleted=0, deferred=0, existing=0)
+    numbered = []
+    for path in rounds_dir.glob("R*.log"):
+        match = _AGENT_ROUND_LOG_RE.match(path.name)
+        if match:
+            numbered.append((int(match.group(1)), path))
+    # Sort on the number alone: the same round can be present twice with
+    # different timestamps after a crash-rerun, and tuple comparison would then
+    # fall through to comparing Paths.
+    numbered.sort(key=lambda item: item[0], reverse=True)
+    stale = numbered[keep:]
+    if _is_bulk(len(stale), keep):
+        return PruneOutcome(deleted=0, deferred=len(stale), existing=len(numbered))
+    for _num, old in stale:
+        old.unlink(missing_ok=True)
+    return PruneOutcome(deleted=len(stale), deferred=0, existing=len(numbered))
+
+
+def next_round_num(log_dir: Path) -> int:
+    """Return the next round number, avoiding reuse of any existing log file numbers.
+
+    Takes ``max(read_round_num, max_log_file_num) + 1``. Under normal operation
+    these agree. The file-system fallback handles the case where ``status.json``
+    has been deleted but old ``round-*.log`` files remain — the counter skips
+    forward instead of silently overwriting a numbered log.
+    """
+    status_num = read_round_num(log_dir)
+    file_nums = []
+    for p in log_dir.glob("round-*.log"):
+        if p.name == ROUND_CURRENT_LINK:
+            continue
+        stem_parts = p.stem.split("-", 1)
+        if len(stem_parts) == 2:
+            try:
+                file_nums.append(int(stem_parts[1]))
+            except ValueError:
+                pass
+    max_file_num = max(file_nums, default=0)
+    return max(status_num, max_file_num) + 1

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/agent_runner/runner.py

@@ -428,8 +428,17 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
     rounds_dir = log_dir / "rounds"
     rounds_dir.mkdir(exist_ok=True)
     # Prune BEFORE minting this round's log: only historical files exist now,
-    # so the active round's log can never be a deletion candidate.
-    prune_rounds_dir(rounds_dir, cfg.runtime.round_log_retention)
+    # so the active round's log can never be a deletion candidate. A bulk
+    # prune deletes nothing and is reported instead — never blocks the round.
+    pruned = prune_rounds_dir(rounds_dir, cfg.runtime.round_log_retention)
+    if pruned.deferred:
+        api.emit_round_logs_prune_deferred(
+            log_dir,
+            directory=str(rounds_dir),
+            existing=pruned.existing,
+            keep=cfg.runtime.round_log_retention,
+            would_delete=pruned.deferred,
+        )
     log_path = rounds_dir / f"R{round_num}-{datetime.now(UTC).strftime('%Y%m%dT%H%M%S')}.log"
 
     hook_ctx = hooks.HookContext(

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/docs/architecture.md

@@ -38,7 +38,7 @@ common to all three. Operator learns one mental model, three lenses.
 
 ## Defenses-as-data
 
-`agent_runner.defenses.catalog(cfg)` returns 12 structured `Defense` entries.
+`agent_runner.defenses.catalog(cfg)` returns 13 structured `Defense` entries.
 Each entry carries:
 
 - `name` — stable identifier
@@ -65,6 +65,7 @@ surfacing everywhere.
 | `critical_envs_injection` | Env injection via [agent.env] block — preset-supplied per CLI (e.g. DISABLE_AUTOUPDATER for claude prevents mid-loop self-updates) | `tests/unit/test_agent_runtime.py` |
 | `startup_smoke_check` | R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn; now halts serve (config_broken) instead of respawning a broken config | `tests/unit/test_serve_config_broken.py` |
 | `crash_loop_breaker` | Run 6 — crashing agent respawned ~100 empty rounds at a fixed 2x delay | `tests/unit/test_serve_crash_loop.py` |
+| `bulk_round_log_prune_guard` | 0.2.4 — rounds/ pruning shipped against backlogs it never built; one deployment's first post-upgrade round would have deleted 12,193 of 12,293 transcripts silently | `tests/unit/test_round_log_helpers.py` |
 | `flock_concurrency` | Architectural — prevent concurrent supervisors corrupting state | `tests/unit/test_runner.py` |
 | `atomic_state_writes` | Data integrity — crashes never leave half-written state files | `tests/invariants/test_atomic_write_enforced.py` |
 | `event_kind_registry` | Prevent events.emit() typos / unregistered kinds slipping past CI | `tests/invariants/test_event_kind_registry.py` |
@@ -219,6 +220,7 @@ See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
 - `round_end`
 - `round_grace_extended`
 - `round_grace_kill`
+- `round_logs_prune_deferred`
 - `round_progress`
 - `round_start`
 - `round_substrate_after`
@@ -240,4 +242,4 @@ See `docs/plugins.md` for the `DirtyHandler` protocol and override recipe.
 
 三层架构：Round（一轮 agent）/ Loop（serve 薄壳）/ Witness（monitor）。
 三视角对称：peek（快照）/ watch（快照循环）/ monitor（异常检测），共用下钻参数。
-防御以结构化目录形式存在（12 条），每条防御自描述「防的是哪条历史教训、被哪个 invariant test 守、当前状态」。
+防御以结构化目录形式存在（13 条），每条防御自描述「防的是哪条历史教训、被哪个 invariant test 守、当前状态」。

{cli_agent_runner-0.2.5 → cli_agent_runner-0.2.6}/docs/configuration.md

@@ -39,7 +39,7 @@ running with newly-set `dirty_action = "auto_commit"` is undefined).
 | `round_timeout_s` | `int` | 1800 |
 | `restart_delay_s` | `int` | 3 |
 | `disable_pre_round_hooks` | `bool` | False |
-| `round_log_retention` | `int` | 100 |
+| `round_log_retention` | `int` | 0 |
 | `narrative_file` | `Path \| None` | None |
 | `transient_error_action` | `Literal['back_off', 'skip', 'stop']` | 'back_off' |
 | `max_rounds` | `int \| None` | None |
@@ -119,6 +119,64 @@ commands happen to match a token drawn from its prompt. The `claude` preset
 defaults to `"stdin"`; existing configs are unchanged. See
 `docs/migrations/0.2.1.md` to adopt on an existing config.
 
+### `runtime.round_log_retention`
+
+Type: int (>= 0)
+Default: `0`
+
+**Pruning is opt-in. `0` — the default — never prunes anything.** Round logs
+accumulate for as long as the deployment runs, and agent-runner deletes none of
+them unless you ask it to.
+
+The knob governs both round-log families:
+
+- the serve-level `{log_dir}/round-<N>.log` files, pruned by mtime once at
+  serve startup;
+- the agent transcripts in `{log_dir}/rounds/R<N>-<timestamp>.log`, pruned by
+  round number at the start of every round.
+
+**We are not ignoring disk.** Unbounded growth is watched, and loudly: the
+`disk_warning` detector alerts at 90% used and `disk_critical` — in the default
+`[monitor] auto_stop_on` — stops the service at 95%. Deleting history has no
+equivalent defense; it is discovered on the day you need the file and it is not
+there. Given a risk that already auto-stops the service versus a risk with no
+detector at all, the default belongs on the side that keeps the files.
+
+### Enabling pruning
+
+Set a positive count — the number of files to keep per family:
+
+```toml
+[runtime]
+round_log_retention = 100   # pre-0.2.6 behavior
+```
+
+Sizing it: agent transcripts are one file per round, from a few KB to several
+MB each depending on how verbose the agent CLI is. Multiply by your rounds/day
+and check it against free space rather than picking a round number.
+
+### Bulk-prune guard (0.2.6+)
+
+If you do enable pruning, a prune that would delete *more* files than it keeps
+is a bulk prune, and a bulk prune deletes nothing. It emits
+`round_logs_prune_deferred` (fields: `directory`, `existing`, `keep`,
+`would_delete`, `hint`) and leaves every file in place. In steady state a round
+retires about one file, so the guard only trips when you first opt in on an
+existing backlog, or when you lower the value far below the current file
+count — exactly the moments a mass deletion would otherwise happen silently.
+
+The deferral is permanent until you act, and you have two options:
+
+- **Raise `round_log_retention`** to at least the reported `existing` count.
+  The backlog then fits inside the kept window, nothing is deleted, and normal
+  per-round pruning resumes once the count grows past the new value.
+- **Delete files yourself** from the reported `directory`. The next prune sees
+  a count the guard no longer calls bulk and resumes.
+
+The supervisor never performs a bulk deletion on its own. Note that `0` is not
+a deferral: it emits nothing, because never-prune is a stated intent rather
+than a backlog awaiting a decision.
+
 ### `vcs.dirty_action`
 
 Type: string, one of `"stash"`, `"ignore"`, `"auto_commit"`

cli_agent_runner-0.2.6/docs/migrations/0.2.6.md

@@ -0,0 +1,127 @@
+# Migration guide: 0.2.6
+
+## TL;DR
+
+**Round-log pruning is now opt-in.** `runtime.round_log_retention` defaults to
+`0`, which means never prune; both round-log families now grow until you
+configure a cap or clear them yourself. If you want the pre-0.2.6 behavior, set
+`round_log_retention = 100` explicitly. A second change backs it up: when
+pruning *is* enabled, a prune that would delete more files than it keeps is
+refused and reported rather than performed. No public symbols removed, one new
+event kind (`round_logs_prune_deferred`).
+
+---
+
+## Why: a release that deleted the evidence for its own fix
+
+0.2.4 shipped a `KillMode=mixed` fix for systemd units. A downstream integrator
+was able to confirm that fix actually worked in production — but only because
+they still had the full transcript of round R11498 on disk. Under 0.2.4's own
+default, that file would have been deleted.
+
+Their numbers, on an unremarkable long-running deployment: 12,293 transcripts,
+6.5 GB, oldest `R1-20260520T023025.log`, `round_log_retention` never
+configured. The first round after upgrading would have deleted 12,193 files —
+about 6.4 GB, the complete history since R1 — on a host with 856 GB free. That
+history is what they used to reconstruct a round lost to a dropped connection,
+and to find a flaky test's trigger condition.
+
+A release that fixes X while silently deleting the evidence needed to verify X
+is the argument for this change.
+
+## The default was on the wrong side of an asymmetric risk
+
+The two failure modes are not symmetric, and only one of them was defended:
+
+| If we | Result | How you find out |
+|---|---|---|
+| retain too much | disk fills | **Loud** — `disk_warning` at 90%, `disk_critical` at 95%, which is in the default `[monitor] auto_stop_on` and stops the service |
+| delete too much | history gone | **Silent** — no detector; discovered on the day you need the file |
+
+So the old default protected against a risk that already had a louder,
+auto-stopping defense, while creating a risk with no defense at all.
+
+Disk was also the *only* remaining justification. The other original reason for
+pruning — the monitor's per-poll cost scaling with file count — was removed
+independently: `load_round_log_tails` now reads only the newest 20 files
+regardless of how many exist.
+
+## Changed: `round_log_retention` defaults to `0` = never prune
+
+`0` is now a legal, meaningful value (previously the validator rejected both
+`0` and `-1`, so there was no off switch — "set it very large" was a
+workaround, not an answer). Negative values are still rejected at load.
+
+Both families are affected:
+
+- `{log_dir}/rounds/R<N>-<timestamp>.log` — the agent transcripts. Pruned since
+  0.2.4; no longer pruned by default.
+- `{log_dir}/round-<N>.log` — the serve-level wrapper logs. **This one is a
+  real behavior change in the safe direction**: that family has been capped at
+  100 files at serve startup for many releases, and now it is not capped unless
+  you say so. Expect it to start growing; size it deliberately if that matters
+  to you.
+
+To keep the old behavior, say so explicitly:
+
+```toml
+[runtime]
+round_log_retention = 100
+```
+
+Nothing else in the supervisor reads these files, so retaining them is inert
+apart from disk. To reclaim space without enabling pruning, delete or archive
+old files yourself.
+
+## Added: bulk prunes are refused, not performed
+
+For anyone who opts in, the second half of this release. A prune that would
+delete **more files than it keeps** is a *bulk* prune, and a bulk prune deletes
+nothing: it emits `round_logs_prune_deferred` and leaves every file in place.
+
+In steady state a round retires about one file, so the guard cannot trip during
+normal operation. It trips exactly when a mass deletion would otherwise have
+happened silently — the first prune after you opt in on an existing backlog, or
+after you lower an existing value.
+
+| Field | Meaning |
+|---|---|
+| `directory` | the directory whose prune was deferred |
+| `existing` | matching files present |
+| `keep` | `runtime.round_log_retention` as configured |
+| `would_delete` | files a normal prune would have removed |
+| `hint` | one line naming the knob to turn |
+
+Re-emitted on every prune attempt while the condition holds — the deferral is
+permanent until an operator acts, and a one-shot event would be invisible to
+anyone who started watching later. `round_log_retention = 0` emits nothing:
+never-prune is a stated intent, not a backlog awaiting a decision.
+
+The guard never blocks or fails a round: it defers a deletion, nothing else.
+
+When you see it, you have two options — raise `round_log_retention` to at least
+the reported `existing` (the backlog then fits inside the kept window and
+normal pruning resumes as the count grows past it), or delete the files
+yourself from the reported `directory`. There is deliberately no config knob to
+re-enable bulk deletion.
+
+## Where you stand, by current version
+
+- **On ≤0.2.3** — `rounds/` has never been pruned on your deployment, and after
+  upgrading straight to 0.2.6 it still will not be. Your backlog is safe by
+  default; you do not need to pre-emptively raise anything before upgrading.
+  (Upgrading via 0.2.4 or 0.2.5, even briefly, runs the deletion once.) Your
+  `round-<N>.log` family stops being capped at 100 — set `round_log_retention`
+  if you want that cap back.
+- **On 0.2.4 or 0.2.5** — the `rounds/` deletion has already happened; those
+  files are gone and 0.2.6 cannot bring them back. What it does is guarantee
+  there is no second one: pruning stops entirely unless you opt in, and if you
+  do, the bulk guard stands between a lowered value and your history.
+- **Anyone who wants the old behavior** — set `round_log_retention = 100`. You
+  get pruning back, now with the bulk guard in front of it.
+
+## Internal API note
+
+`agent_runner.round_log.prune_rounds_dir` and `prune_old_round_logs` return a
+`PruneOutcome` (`deleted`, `deferred`, `existing`) instead of `int` / `None`.
+Both are internal helpers, not part of the pinned public API surface.