cli-agent-runner 0.1.39__tar.gz → 0.1.41__tar.gz

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/.gitignore

@@ -27,3 +27,6 @@ agent_runner/_version.py
 .coverage
 coverage.xml
 htmlcov/
+
+# Personal /team-onboarding artifact — not project content
+ONBOARDING.md

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/CHANGELOG.md

@@ -5,7 +5,23 @@ 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).
 
-## [Unreleased]
+## [0.1.41] - 2026-06-07
+
+### Added
+- New `codewhale` preset — supervise Hmbown/CodeWhale (DeepSeek terminal agent) via `codewhale exec --auto --output-format stream-json`. `agent-runner init --preset codewhale`.
+- New built-in `codewhale_error_detector` plugin — emits `agent_usage_recorded` (model + token counts) from codewhale's stream-json output. Transient-error classification is best-effort (mappable buckets only); auth failures surface via the existing monitor `oauth_fail` detector.
+
+## [0.1.40] - 2026-05-31
+
+### Security
+- Grace-kill child-process fields (`live_children` / `ignored_children` in `round_grace_extended` / `round_grace_kill`) no longer store raw command lines — only the executable basename + pid (and, for ignored children, which ignore-pattern matched). This structurally prevents secrets passed in a child's arguments from reaching `events-*.jsonl`. The field shape changed from a list of strings to a list of objects.
+- Free-text event excerpts that can carry agent output — `transient_error_detected.raw`, `hook_failed.error_message`/`traceback`, `serve_startup_hook_failed.exc_msg` — are now best-effort redacted (auth headers, tokens, credential URLs, `KEY=value` secrets, known key-prefixes, JWT, PEM).
+- Pre-0.1.40 `events-*.jsonl` may contain unredacted argv/excerpts — see `docs/migrations/0.1.40.md`.
+
+### Changed
+- Docs: `configuration.md` `[monitor.host_health]` example points to the generated schema table instead of restating default values.
+
+## [0.1.39] - 2026-05-29
 
 ### Fixed
 - Grace-kill (`max_grace_after_result_s`) is no longer defeated by long-lived helper subprocesses (e.g. claude's persistent Bash-tool shell-snapshot). `[runtime] grace_kill_ignore_patterns` lists regexes for cmdlines to exclude from the liveness count; the claude preset ships a matching default.

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.39
+Version: 0.1.41
 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.1.39 → cli_agent_runner-0.1.41}/agent_runner/_emit.py

@@ -112,8 +112,10 @@ def emit_transient_error_detected(
     raw: str,
 ) -> None:
     """Emit detection of a transient agent error (rate limit / 5xx / timeout)."""
+    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,
@@ -234,12 +236,15 @@ def emit_round_grace_kill(
     *,
     round_num: int,
     grace_s: int,
-    live_children: list[str] | None = None,
+    live_children: list[dict] | None = None,
 ) -> None:
     """Emit when the subprocess was killed because the grace-after-result timer
     expired AND the agent's process group had no live worker processes left
     (a genuine hang). Distinct from round_grace_extended (grace elapsed but a
     worker was still running) and round_timeout_kill (wall-clock exceeded).
+
+    live_children: list of ``{"name": <exe basename>, "pid": <int>}`` dicts
+        (0.1.40+; previously list of cmdline strings).
     """
     from agent_runner.events import ROUND_GRACE_KILL, emit
 
@@ -257,17 +262,18 @@ def emit_round_grace_extended(
     *,
     round_num: int,
     grace_s: int,
-    live_children: list[str],
-    ignored_children: list[str] | None = None,
+    live_children: list[dict],
+    ignored_children: list[dict] | None = None,
 ) -> None:
     """Emit when the grace-after-result timer expired but the agent still had
     live worker processes (e.g. a backgrounded build), so the round was NOT
     killed; it continues until it finishes or hits round_timeout_s.
 
-    ignored_children: cmdlines that matched a grace_kill_ignore_patterns entry
-        and were excluded from the liveness count — useful for verifying
-        patterns are firing and for noticing when an upstream CLI changes
-        its helper path.
+    live_children: list of ``{"name": <exe basename>, "pid": <int>}`` dicts
+        (0.1.40+; previously list of cmdline strings).
+    ignored_children: list of ``{"name": ..., "pid": ..., "matched": <pattern>}``
+        dicts for children that matched a grace_kill_ignore_patterns entry
+        and were excluded from the liveness count (0.1.40+; previously cmdline strings).
     """
     from agent_runner.events import ROUND_GRACE_EXTENDED, emit
 

cli_agent_runner-0.1.41/agent_runner/_redact.py

@@ -0,0 +1,102 @@
+"""Mask secret-bearing tokens in semi-trusted free text before it is persisted
+to durable, default-readable event logs (events-*.jsonl).
+
+Single source of truth for secret-shaping. Pure, dependency-free, idempotent.
+BEST-EFFORT: applied only to free-text excerpts (transient error output, hook
+exception messages/tracebacks), never as the sole control. The grace-kill child
+fields avoid this entirely by storing basename+pid, not argv.
+
+Patterns are length/charset-anchored so benign argv (sk-report.md, psql -h db,
+'Basic auth disabled') passes through unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+
+_MASK = "<redacted>"
+
+_LONG_FLAGS = [
+    "--token",
+    "--password",
+    "--passwd",
+    "--api-key",
+    "--apikey",
+    "--secret",
+    "--secret-access-key",
+    "--access-key",
+    "--auth",
+    "--authorization",
+    "--client-secret",
+    "--aws-session-token",
+    "--bearer",
+    "--auth-token",
+    "--private-key",
+]
+# (prefix, min-tail-len) — anchored so short filenames don't match.
+_PREFIX_RES = [
+    r"sk-ant-[A-Za-z0-9\-_]{16,}",
+    r"sk-[A-Za-z0-9]{16,}",
+    r"ghp_[A-Za-z0-9]{20,}",
+    r"gho_[A-Za-z0-9]{20,}",
+    r"ghs_[A-Za-z0-9]{20,}",
+    r"ghu_[A-Za-z0-9]{20,}",
+    r"github_pat_[A-Za-z0-9_]{20,}",
+    r"xox[bpars]-[A-Za-z0-9-]{10,}",
+    r"xapp-[A-Za-z0-9-]{10,}",
+    r"AKIA[0-9A-Z]{16}",
+    r"ASIA[0-9A-Z]{16}",
+    r"AIza[0-9A-Za-z_\-]{35}",
+    r"glpat-[A-Za-z0-9_\-]{20}",
+    r"ya29\.[A-Za-z0-9._\-]{20,}",
+    r"(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{16,}",
+    r"npm_[A-Za-z0-9]{20,}",
+    r"hf_[A-Za-z0-9]{20,}",
+]
+
+_FLAG_RE = re.compile(r"(?i)(" + "|".join(re.escape(f) for f in _LONG_FLAGS) + r")(\s+|=)(\S+)")
+# Short HTTP-basic flag `-u user:pass` (curl/wget). Case-SENSITIVE so `-U`
+# (psql/pg username) is left alone; a colon is required so `sort -u file` and
+# bare `-u username` (no password) are not masked; and the value must NOT be a
+# URL (`://`) — a `-u <url>` is left for _URL_USERINFO_RE, which masks only the
+# userinfo and preserves the host (e.g. redis://<redacted>@cache:6379/0).
+_SHORT_USER_RE = re.compile(r"(?<![\w-])-u(\s+|=)(?!\S*://)(\S+:\S+)")
+_HEADER_NAME_RE = re.compile(
+    r"(?im)\b(Authorization|Proxy-Authorization|Cookie|Set-Cookie|"
+    r"X-Api-Key|X-Auth-Token|X-Amz-Security-Token)(\s*:\s*)([^\r\n]+)"
+)
+_SCHEME_RE = re.compile(
+    r"\b(Bearer|Basic|Token|ApiKey|Digest|Negotiate|NTLM)(\s+)([A-Za-z0-9+/=._\-]{12,})"
+)
+_URL_USERINFO_RE = re.compile(r"(?i)([a-z][a-z0-9+.\-]*://)([^/\s@]+)@")
+_URL_QUERY_RE = re.compile(
+    r"(?i)([?&#](?:access_token|api_?key|token|auth|secret|sig|signature|"
+    r"password|client_secret|x-amz-security-token|x-amz-signature)=)([^&#\s]+)"
+)
+_ENV_RE = re.compile(
+    r"(?i)((?:(?<=\s)|^)[A-Za-z_][A-Za-z0-9_]*"
+    r"(?:PASSWORD|PASSWD|PWD|TOKEN|SECRET|API[_-]?KEY|ACCESS[_-]?KEY|CREDENTIAL|PRIVATE[_-]?KEY)"
+    r"[A-Za-z0-9_]*)=(\S+)"
+)
+_PREFIX_RE = re.compile(r"(?<![A-Za-z0-9])(?:" + "|".join(_PREFIX_RES) + r")")
+_JWT_RE = re.compile(r"\beyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+")
+_PEM_RE = re.compile(
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", re.DOTALL
+)
+
+
+def redact_secrets(text: str) -> str:
+    """Return *text* with secret-bearing tokens replaced by ``<redacted>``."""
+    if not text:
+        return text
+    out = _PEM_RE.sub(_MASK, text)
+    out = _ENV_RE.sub(rf"\1={_MASK}", out)
+    out = _FLAG_RE.sub(rf"\1\2{_MASK}", out)
+    out = _SHORT_USER_RE.sub(rf"-u\1{_MASK}", out)
+    out = _HEADER_NAME_RE.sub(rf"\1\2{_MASK}", out)
+    out = _SCHEME_RE.sub(rf"\1\2{_MASK}", out)
+    out = _URL_USERINFO_RE.sub(rf"\1{_MASK}@", out)
+    out = _URL_QUERY_RE.sub(rf"\1{_MASK}", out)
+    out = _JWT_RE.sub(_MASK, out)
+    out = _PREFIX_RE.sub(_MASK, out)
+    return out

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.39'
-__version_tuple__ = version_tuple = (0, 1, 39)
+__version__ = version = '0.1.41'
+__version_tuple__ = version_tuple = (0, 1, 41)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/agent_runner/agent_runtime.py

@@ -31,7 +31,7 @@ class RunResult:
     timed_out: bool
     pid: int
     killed_for_grace: bool = False
-    grace_kill_children: list[str] = field(default_factory=list)
+    grace_kill_children: list[dict] = field(default_factory=list)
 
 
 def _build_argv(command: list[str], prompt_arg_template: list[str], prompt: str) -> list[str]:
@@ -63,35 +63,43 @@ def _live_children(
     *,
     ignore_patterns: list[re.Pattern[str]] | None = None,
     max_n: int = 5,
-    max_len: int = 120,
-) -> tuple[list[str], list[str]]:
-    """Cmdlines of live (non-zombie) descendants of ``proc``, split into
-    ``(live, ignored)``: ``live`` is what counts toward the grace-kill
-    liveness check; ``ignored`` matched an ``ignore_patterns`` entry and is
-    excluded (e.g. claude's persistent shell-snapshot helper). Both lists
-    are bounded by ``max_n``/``max_len`` to keep events small. ``ignore_patterns
-    is None`` → no filtering, ``ignored`` is empty, ``live`` matches 0.1.38.
+) -> tuple[list[dict], list[dict]]:
+    """Live (non-zombie) descendants of ``proc``, split into ``(live, ignored)``.
+
+    Each entry is ``{"name": <executable basename>, "pid": <int>}``; an ignored
+    entry also carries ``"matched": <pattern str>``. We store only basename+pid,
+    NOT argv — process arguments are where secrets leak (PGPASSWORD=…, --api-key
+    …, redis://:pass@…) and these lists are persisted to events-*.jsonl.
+    Ignore-pattern MATCHING runs against the full cmdline (detection unchanged);
+    only what we STORE is minimized.
     """
     try:
         parent = psutil.Process(proc.pid)
     except (psutil.NoSuchProcess, psutil.AccessDenied):
         return [], []
-    live: list[str] = []
-    ignored: list[str] = []
+    live: list[dict] = []
+    ignored: list[dict] = []
     for child in parent.children(recursive=True):
         try:
             if child.status() == psutil.STATUS_ZOMBIE:
                 continue
-            line = " ".join(child.cmdline()) or child.name()
+            argv = child.cmdline()
+            full = " ".join(argv) or child.name()  # MATCHING only
+            name = (Path(argv[0]).name if argv else "") or child.name()
+            pid = child.pid
         except (psutil.NoSuchProcess, psutil.AccessDenied):
             continue
-        short = line[:max_len]
-        if ignore_patterns and any(p.search(line) for p in ignore_patterns):
+        matched = None
+        if ignore_patterns:
+            for p in ignore_patterns:
+                if p.search(full):
+                    matched = p.pattern
+                    break
+        if matched is not None:
             if len(ignored) < max_n:
-                ignored.append(short)
-        else:
-            if len(live) < max_n:
-                live.append(short)
+                ignored.append({"name": name, "pid": pid, "matched": matched})
+        elif len(live) < max_n:
+            live.append({"name": name, "pid": pid})
         if len(live) >= max_n and len(ignored) >= max_n:
             break
     return live, ignored
@@ -114,7 +122,7 @@ def run(
     max_grace_after_result_s: int = 0,
     progress_callback: Callable[[dict], None] | None = None,
     progress_interval_s: int = 0,
-    on_grace_extended: Callable[[list[str], list[str]], None] | None = None,
+    on_grace_extended: Callable[[list[dict], list[dict]], None] | None = None,
     grace_kill_ignore_patterns: list[re.Pattern[str]] | None = None,
 ) -> RunResult:
     """Spawn the agent subprocess and wait for exit or timeout.

cli_agent_runner-0.1.41/agent_runner/builtin_plugins/codewhale.py

@@ -0,0 +1,133 @@
+"""Built-in post_round_hook for codewhale CLI: usage events + transient classifier.
+
+Third built-in plugin (after claude, gemini). Parses codewhale's `exec
+--output-format stream-json` NDJSON stdout tail; emits agent_usage_recorded
+from the terminal metadata record. Transient-error classification is
+best-effort and emits ONLY when an error maps to an existing bucket (like
+gemini): codewhale's exec stdout surfaces a {"type":"error"} record, but the
+only observed case so far is auth failure (oauth_fail territory, not a
+transient bucket), so nothing maps yet -- usage-only today. 429/5xx mapping
+is added when a real rate-limit sample is captured.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from agent_runner.api import (
+    emit_agent_usage_recorded,
+    emit_transient_error_detected,
+)
+from agent_runner.builtin_plugins._constants import (
+    _5XX_STATUSES,
+    _BACK_OFF_DEFAULTS,
+    _RAW_CAP,
+    _TAIL_LINES,
+)
+from agent_runner.hooks import HookContext, register_post_round_hook
+
+
+class CodewhaleErrorDetector:
+    """Parse codewhale round log tail; emit usage + transient_error_detected events."""
+
+    name = "codewhale_error_detector"
+
+    def after_round(self, ctx: HookContext, result: Any) -> None:
+        if ctx.agent_binary != "codewhale":
+            return
+        log_path = ctx.agent_log_path
+        if log_path is None or not log_path.exists():
+            return
+        parsed = _parse_codewhale_log(log_path)
+        if parsed.get("transient_error"):
+            emit_transient_error_detected(
+                ctx.log_dir, round_num=ctx.round_num, **parsed["transient_error"]
+            )
+        if parsed.get("usage"):
+            emit_agent_usage_recorded(
+                ctx.log_dir,
+                round_num=ctx.round_num,
+                phase=ctx.phase or "",
+                success=(result.exit_code == 0 and not result.timed_out),
+                **parsed["usage"],
+            )
+
+
+def _parse_codewhale_log(log_path: Path) -> dict[str, Any]:
+    """Scan last _TAIL_LINES of codewhale NDJSON; extract usage from the metadata
+    record; classify any {"type":"error"} that maps to a transient bucket.
+
+    Tolerates non-JSON lines (codewhale prefixes some stdout with terminal
+    escapes) via per-line try/except.
+    """
+    with log_path.open("r", encoding="utf-8", errors="replace") as f:
+        tail = deque(f, maxlen=_TAIL_LINES)
+    metadata: dict | None = None
+    error_event: dict | None = None
+    for line in tail:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        etype = event.get("type")
+        if etype == "metadata":
+            metadata = event.get("meta") or {}
+        elif etype == "error":
+            error_event = event
+
+    out: dict[str, Any] = {}
+
+    if metadata:
+        out["usage"] = {
+            "agent": "codewhale",
+            "model": str(metadata.get("model", "unknown")),
+            "input_tokens": int(metadata.get("input_tokens", 0)),
+            "output_tokens": int(metadata.get("output_tokens", 0)),
+            "cached_tokens": 0,  # codewhale exec stdout exposes no cache counts
+            "cost_usd": None,  # codewhale exec stdout exposes no USD
+            "duration_ms": 0,  # not in exec metadata
+        }
+
+    if error_event is not None:
+        classification = _classify_codewhale_error(error_event)
+        if classification:
+            duration = _BACK_OFF_DEFAULTS[classification]
+            out["transient_error"] = {
+                "classification": classification,
+                "agent": "codewhale",
+                "reset_at_epoch": int(time.time() + duration),
+                "raw": str(error_event.get("error", "error"))[:_RAW_CAP],
+            }
+    return out
+
+
+def _classify_codewhale_error(error_event: dict[str, Any]) -> str | None:
+    """Map a codewhale {"type":"error"} record to a transient bucket, or None.
+
+    None means 'not a transient error' (e.g. auth failure -> handled by the
+    monitor's oauth_fail log-scan, not the transient classifier). codewhale's
+    error record currently carries only a free-text 'error' string with no
+    status code; until a real rate-limit/5xx sample is captured we cannot map
+    to rate_limit_model / api_transient_5xx / api_timeout, so we return None.
+    A future revision keys on a numeric status field once observed.
+    """
+    code = error_event.get("code") or error_event.get("status_code")
+    if code == 429:
+        return "rate_limit_model"
+    if code in _5XX_STATUSES:
+        return "api_transient_5xx"
+    if code == 408:
+        return "api_timeout"
+    return None
+
+
+register_post_round_hook(CodewhaleErrorDetector())

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/agent_runner/cli/init_cmd.py

@@ -2,15 +2,27 @@
 
 from __future__ import annotations
 
+import importlib.resources
+
 from agent_runner import api
 from agent_runner.cli.common import emit, fail, work_dir_from_args
 
 
+def _preset_names() -> list[str]:
+    """Discover scaffold presets from the shipped ``agent_runner/presets/*.toml``.
+
+    Derived (not hardcoded) so adding a preset is a single new .toml file — the
+    ``--preset`` choices and validation track the filesystem automatically.
+    """
+    presets = importlib.resources.files("agent_runner.presets")
+    return sorted(p.name[:-5] for p in presets.iterdir() if p.name.endswith(".toml"))
+
+
 def add_parser(sub, parent) -> None:
     p = sub.add_parser("init", parents=[parent], help="Scaffold agent-runner project files")
     p.add_argument(
         "--preset",
-        choices=["claude", "aider", "gemini"],
+        choices=_preset_names(),
         default="claude",
         help="Which agent CLI preset to scaffold (default: claude)",
     )

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/agent_runner/hooks.py

@@ -35,6 +35,7 @@ from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
 
 from agent_runner import events
+from agent_runner._redact import redact_secrets
 from agent_runner._registry import ensure_unique
 
 _HEAD_BYTES = 1024
@@ -201,7 +202,7 @@ def run_serve_startup_hooks(cfg: Any, log_dir: Path) -> bool:
             hook(cfg)
         except Exception as e:  # noqa: BLE001 — hook is plugin contract; any failure aborts serve
             exc_type = type(e).__name__
-            exc_msg = str(e)[:200]
+            exc_msg = redact_secrets(str(e))[:200]
             print(
                 f"agent-runner: serve_startup_hook {hook.name} failed: {exc_type}: {exc_msg}",
                 file=sys.stderr,
@@ -232,6 +233,6 @@ def _summarize_error(exc: BaseException, tb: str) -> dict[str, str]:
         trimmed = tb[:_HEAD_BYTES] + _TRUNC_MARKER + tb[-_TAIL_BYTES:]
     return {
         "error_type": type(exc).__name__,
-        "error_message": str(exc),
-        "traceback": trimmed,
+        "error_message": redact_secrets(str(exc)),
+        "traceback": redact_secrets(trimmed),
     }

cli_agent_runner-0.1.41/agent_runner/presets/codewhale.toml

@@ -0,0 +1,30 @@
+# agent-runner.toml — generated by `agent-runner init --preset codewhale`.
+#
+# Prereqs:
+#   - codewhale installed (ships `codewhale` + `codewhale-tui`; both on PATH):
+#       npm i -g codewhale     (or cargo/brew per CodeWhale docs)
+#   - DEEPSEEK_API_KEY set on the supervisor host (or a key saved via
+#     `codewhale auth set`; resolution order is config > keyring > env)
+#   - work_dir is a git repo
+
+[agent]
+command = ["codewhale", "exec", "--auto", "--output-format", "stream-json"]
+prompt_arg_template = ["{prompt}"]
+name = "codewhale"
+
+[runtime]
+work_dir = "."
+log_dir = "~/.agent-runner/{project}/logs"
+round_timeout_s = 1800
+restart_delay_s = 3
+
+[prompt]
+file = "./prompts/main.md"
+inject_context = true
+
+[vcs]
+dirty_action = "stash"
+stash_idempotency_s = 5
+
+[monitor]
+auth_fail_hint = "Run `codewhale auth status` to inspect provider/credentials, or set DEEPSEEK_API_KEY on the supervisor host."

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/agent_runner/scaffold.py

@@ -5,8 +5,8 @@ Writes three files into a git repo:
   prompts/main.md        — neutral 8-line placeholder
   .gitignore             — append "logs/" if missing
 
-Available presets ship as package data in `agent_runner/presets/*.toml`.
-Currently: `claude`, `aider`, `gemini`.
+Available presets ship as package data in `agent_runner/presets/*.toml`;
+`agent-runner init --preset <name>` discovers them from that directory.
 
 Optionally commits in one step (default true via the CLI).
 """

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/docs/commands.md

@@ -36,7 +36,7 @@ appends `logs/` to `.gitignore`. By default also creates a git commit.
 
 Flags:
 
-- `--preset {claude,aider,gemini}` — agent CLI preset to scaffold (default: `claude`)
+- `--preset {claude,aider,gemini,codewhale}` — agent CLI preset to scaffold (default: `claude`)
 - `--force` — overwrite an existing `agent-runner.toml`
 - `--no-commit` — skip the initial git commit
 
@@ -101,6 +101,9 @@ back to package-only mode automatically.
 `--no-restart` forces package-only even on a systemd --user host (upgrade the
 package now, restart your service yourself).
 
+Operator walkthrough (per-deployment decision table, rollback, failure modes,
+postmortem trail): see `docs/runbook.md` § "Upgrading agent-runner".
+
 ## Observation
 
 ### `agent-runner peek [flags]`

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/docs/configuration.md

@@ -103,10 +103,11 @@ working tree:
 `[agent.env]` is a flat `dict[str, str]` of environment variables injected into
 the agent subprocess **per round**. This is preset-supplied per CLI: e.g. the
 claude preset sets `DISABLE_AUTOUPDATER=1` to prevent mid-loop self-updates;
-the aider preset omits `[agent.env]` entirely. Override these values in your
-project's `agent-runner.toml` only when you need to deviate from the preset
-default. The runtime merges `[agent.env]` on top of the supervisor's own env;
-unset (empty string) does not unset an inherited variable.
+the aider and codewhale presets omit `[agent.env]` entirely (both resolve their
+API keys from the ambient environment or their own keyrings). Override these
+values in your project's `agent-runner.toml` only when you need to deviate from
+the preset default. The runtime merges `[agent.env]` on top of the supervisor's
+own env; unset (empty string) does not unset an inherited variable.
 
 ## `[monitor].auth_fail_hint` (preset-supplied)
 
@@ -117,6 +118,8 @@ guidance without authoring it themselves:
 - `--preset claude` → recommend `claude /login` / refresh `ANTHROPIC_API_KEY`.
 - `--preset aider` → verify provider env var (`OPENAI_API_KEY` /
   `ANTHROPIC_API_KEY` / `DEEPSEEK_API_KEY` / etc.); run `aider --models`.
+- `--preset codewhale` → run `codewhale auth status` to inspect provider
+  credentials, or set `DEEPSEEK_API_KEY` on the supervisor host.
 
 Override in your `agent-runner.toml` if you ship a custom CLI.
 
@@ -212,9 +215,10 @@ round_progress_interval_s = 0  # 0 = disabled; set >0 to emit round_progress hea
 # supervisor_stale_threshold_s = 2700  # unset = round_timeout_s * 1.5; 0 = disable
 
 [monitor.host_health]
-mem_avail_min_mb = 200        # mem_pressure fires when mem_available_mb < this
-disk_warning_pct = 90.0       # disk_warning fires when disk_used_pct >= this
-disk_critical_pct = 95.0      # disk_critical fires when disk_used_pct >= this
+# Thresholds for mem_pressure / disk_warning / disk_critical. Defaults are
+# authoritative in the config-schema table above — set a field here only to
+# override. (mem_avail_min_mb: mem_pressure when mem_available_mb below it;
+# disk_warning_pct / disk_critical_pct: fire when disk_used_pct at/above.)
 ```
 
 Comment out individual entries to disable; e.g. `# auto_stop_on = []` disables

cli_agent_runner-0.1.41/docs/migrations/0.1.40.md

@@ -0,0 +1,42 @@
+# Migrating to 0.1.40
+
+## TL;DR
+
+```bash
+pip install --upgrade cli-agent-runner==0.1.40
+```
+
+A security release. No config or behavior change for the supervisor. One
+consumer-visible field-shape change (below).
+
+## Breaking: grace-kill child fields are now objects, not strings
+
+`round_grace_extended` / `round_grace_kill` previously carried
+`live_children` / `ignored_children` as lists of command-line **strings**.
+They are now lists of **objects**:
+
+- `live_children`:   `[{"name": "<exe basename>", "pid": <int>}, ...]`
+- `ignored_children`: `[{"name": ..., "pid": ..., "matched": "<pattern>"}, ...]`
+
+If you parse these fields, update your consumer. The change exists because the
+old strings were full process command lines, which could contain a secret
+passed in a child's arguments (a DB password, an API key, a credential URL).
+Storing only basename + pid removes that leak by construction. Ignore-pattern
+matching is unchanged — it still runs against the full command line; only what
+is **stored** is minimized.
+
+## Best-effort redaction of free-text excerpts
+
+`transient_error_detected.raw`, `hook_failed.error_message`/`traceback`, and
+`serve_startup_hook_failed.exc_msg` are now passed through a redactor that masks
+auth headers, tokens, credential URLs, `KEY=value` secrets, known key-prefixes,
+JWTs, and PEM blocks. This is **best-effort defense-in-depth**, not a guarantee:
+do not pass secrets as command-line arguments to supervised agents, and treat
+`events-*.jsonl` as sensitive.
+
+## One-time action (if applicable)
+
+If pre-0.1.40 `events-*.jsonl` were shipped to a log aggregator, shared, or
+fetched cross-host (`monitor --host`), review them for secret-bearing child
+argv / error excerpts and rotate any exposed credential. Post-upgrade events
+are protected.

{cli_agent_runner-0.1.39 → cli_agent_runner-0.1.41}/docs/quickstart.md

@@ -37,7 +37,7 @@ Edit `prompts/main.md` to describe what the agent should do per round.
 Edit `agent-runner.toml` if you need to change `round_timeout_s` or `[phases]`.
 
 The default preset (`--preset claude`) invokes `claude`. Other built-in
-presets: `--preset aider` and `--preset gemini`. To use any other CLI,
+presets: `--preset aider`, `--preset gemini`, and `--preset codewhale`. To use any other CLI,
 edit `agent.command` to your CLI's invocation and `agent.prompt_arg_template`
 to its prompt-argument syntax — for example: