cli-agent-runner 0.1.38__tar.gz → 0.1.40__tar.gz

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/.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.38 → cli_agent_runner-0.1.40}/CHANGELOG.md

@@ -5,7 +5,31 @@ 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.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.
+
+### Added
+- `[runtime] grace_kill_ignore_patterns: list[str]` — regex patterns; matching child cmdlines are excluded from the grace-kill liveness check.
+- `round_grace_extended` event payload gains `ignored_children` — cmdlines filtered by `grace_kill_ignore_patterns`.
+
+### Changed
+- Docs: `commands.md` documents `monitor --mode/--port` and `init --preset`; the Chinese verb list and `[monitor]` default values now point to the generated tables instead of restating them; runbook upgrade examples use a version placeholder.
+
+### Internal
+- New invariant `test_doc_claims_match_ssot` gates documented counts (detectors / defenses / verbs) and config value-sets (`dirty_action` / `context_injection_mode` / transient classification) against their code SSOT — count/enum doc drift now fails CI at the introducing commit.
+- Removed the unused `alert-kinds` docgen renderer; de-duplicated redundant defense-count and alert-kind guards to one canonical tripwire each.
 
 ## [0.1.38] - 2026-05-24
 

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.38
+Version: 0.1.40
 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.38 → cli_agent_runner-0.1.40}/agent_runner/_docgen.py

@@ -110,11 +110,6 @@ def render_defenses_table() -> str:
     return "\n".join(lines)
 
 
-def render_alert_kinds_list() -> str:
-    """Flat bullet list of all known alert kinds, alphabetised."""
-    return "\n".join(f"- `{k}`" for k in sorted(KNOWN_ALERT_KINDS))
-
-
 def render_detector_list() -> str:
     """Bullet list of detectors; auto-stop kinds flagged inline."""
     lines: list[str] = []
@@ -155,7 +150,6 @@ def render_verb_table() -> str:
 
 RENDERERS: dict[str, Callable[[], str]] = {
     "defenses-table": render_defenses_table,
-    "alert-kinds": render_alert_kinds_list,
     "detector-list": render_detector_list,
     "event-kinds": render_event_kinds_list,
     "config-schema": render_config_schema_table,

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/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,11 +262,18 @@ def emit_round_grace_extended(
     *,
     round_num: int,
     grace_s: int,
-    live_children: list[str],
+    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.
+
+    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
 
@@ -271,6 +283,7 @@ def emit_round_grace_extended(
         round_num=round_num,
         grace_s=grace_s,
         live_children=live_children,
+        ignored_children=ignored_children or [],
     )
 
 

cli_agent_runner-0.1.40/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.38 → cli_agent_runner-0.1.40}/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.38'
-__version_tuple__ = version_tuple = (0, 1, 38)
+__version__ = version = '0.1.40'
+__version_tuple__ = version_tuple = (0, 1, 40)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/agent_runner/agent_runtime.py

@@ -11,6 +11,7 @@ Defenses encoded here:
 from __future__ import annotations
 
 import os
+import re
 import signal
 import subprocess  # noqa: TID251 — sanctioned subprocess caller
 import time
@@ -30,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]:
@@ -57,29 +58,51 @@ def _kill_pgroup(proc: subprocess.Popen) -> None:
         pass
 
 
-def _live_children(proc: subprocess.Popen, *, max_n: int = 5, max_len: int = 120) -> list[str]:
-    """Cmdlines of live (non-zombie) descendant processes of ``proc``.
-
-    Empty when ``proc`` has no live workers (a stuck agent that emitted
-    type=result then hung). Non-empty when the round backgrounded work (e.g. a
-    build) still running. Bounded so the resulting event stays small.
+def _live_children(
+    proc: subprocess.Popen,
+    *,
+    ignore_patterns: list[re.Pattern[str]] | None = None,
+    max_n: int = 5,
+) -> 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 []
-    out: list[str] = []
+        return [], []
+    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
-        out.append(line[:max_len])
-        if len(out) >= max_n:
+        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({"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 out
+    return live, ignored
 
 
 # Exact compact bytes — matches claude CLI's no-whitespace JSONL output.
@@ -99,7 +122,8 @@ 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]], 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.
 
@@ -116,6 +140,10 @@ def run(
     progress_interval_s seconds with a dict of log stats (log_size_kb,
     last_write_age_s, wall_age_s). Keeps agent_runtime event-free; callers
     build the callback to emit events.
+
+    grace_kill_ignore_patterns: pre-compiled regex patterns; child cmdlines
+    matching any pattern (re.search) are excluded from the liveness count
+    (persistent helpers that aren't real workers). None = no filtering.
     """
     argv = _build_argv(command, prompt_arg_template, prompt)
     env = {**os.environ, **env_extra}
@@ -157,13 +185,13 @@ def run(
                     except OSError:
                         pass  # log not flushed yet; check next tick
                 if result_seen_at is not None and now - result_seen_at > max_grace_after_result_s:
-                    children = _live_children(proc)
-                    if children:
+                    live, ignored = _live_children(proc, ignore_patterns=grace_kill_ignore_patterns)
+                    if live:
                         # Busy: a backgrounded worker is still running. Don't
                         # reap — defer to the wall-clock ceiling. Signal once.
                         if not grace_extended_emitted:
                             if on_grace_extended is not None:
-                                on_grace_extended(children)
+                                on_grace_extended(live, ignored)
                             grace_extended_emitted = True
                     else:
                         _kill_pgroup(proc)

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/agent_runner/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import tomllib
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -40,6 +41,12 @@ class RuntimeConfig:
     fresh_eyes_every_n: int | None = None  # None = disabled
     dry_run: bool = False
     max_grace_after_result_s: int = 0  # 0 = disabled
+    grace_kill_ignore_patterns: list[str] = field(default_factory=list)
+    """Regex patterns (re.search) tested against each child process's joined
+    cmdline. Matching children are excluded from the grace-kill liveness
+    check — for persistent helper subprocesses (e.g. claude's shell-snapshot
+    bash) that would otherwise defeat max_grace_after_result_s. Empty list
+    = no filtering (0.1.38 behavior preserved)."""
 
 
 @dataclass(frozen=True)
@@ -221,6 +228,25 @@ def _validate_remote_failure_tolerance(value: Any) -> int:
     return v
 
 
+def _validate_regex_list(value: Any, *, field: str) -> list[str]:
+    """Validate a list of regex pattern strings (each must compile). Returns the
+    raw strings unchanged; callers compile when they need ``re.Pattern`` objects."""
+    if not isinstance(value, list):
+        raise ValueError(f"{field}: expected a list of regex strings, got {type(value).__name__}")
+    out: list[str] = []
+    for p in value:
+        if not isinstance(p, str):
+            raise ValueError(
+                f"{field}: each pattern must be a string, got {type(p).__name__}: {p!r}"
+            )
+        try:
+            re.compile(p)
+        except re.error as e:
+            raise ValueError(f"{field}: invalid regex {p!r}: {e}") from e
+        out.append(p)
+    return out
+
+
 _PHASE_OVERRIDE_ALLOWED_FIELDS = frozenset(
     {
         "round_timeout_s",
@@ -392,6 +418,10 @@ def load_config(toml_path: Path) -> Config:
             runtime_d.get("max_grace_after_result_s", 0),
             field="runtime.max_grace_after_result_s",
         ),
+        grace_kill_ignore_patterns=_validate_regex_list(
+            runtime_d.get("grace_kill_ignore_patterns", []),
+            field="runtime.grace_kill_ignore_patterns",
+        ),
     )
     prompt_d = raw.get("prompt", {})
     mode = prompt_d.get("context_injection_mode", "prepend")

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/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.38 → cli_agent_runner-0.1.40}/agent_runner/presets/claude.toml

@@ -16,6 +16,7 @@ work_dir = "."
 log_dir = "~/.agent-runner/{project}/logs"
 round_timeout_s = 1800
 restart_delay_s = 3
+grace_kill_ignore_patterns = ['\.claude/shell-snapshots/snapshot-bash-']
 
 [prompt]
 file = "./prompts/main.md"

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/agent_runner/runner.py

@@ -10,6 +10,7 @@ import hashlib
 import json
 import os
 import random
+import re
 import sys
 import time
 import traceback as tb_mod
@@ -466,12 +467,15 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
             **stats,
         )
 
-    def _grace_extended_emit(children: list[str]) -> None:
+    grace_kill_ignore_patterns = [re.compile(p) for p in cfg.runtime.grace_kill_ignore_patterns]
+
+    def _grace_extended_emit(live: list[str], ignored: list[str]) -> None:
         api.emit_round_grace_extended(
             log_dir,
             round_num=round_num,
             grace_s=cfg.runtime.max_grace_after_result_s,
-            live_children=children,
+            live_children=live,
+            ignored_children=ignored,
         )
 
     result = agent_runtime.run(
@@ -485,6 +489,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         progress_callback=_progress_emit,
         progress_interval_s=cfg.monitor.round_progress_interval_s,
         on_grace_extended=_grace_extended_emit,
+        grace_kill_ignore_patterns=grace_kill_ignore_patterns,
     )
     events.emit(
         log_dir,

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/docs/commands.md

@@ -34,8 +34,15 @@ are shared between `peek`, `watch`, and `monitor`.
 Scaffold a new project: writes `agent-runner.toml`, `prompts/main.md`, and
 appends `logs/` to `.gitignore`. By default also creates a git commit.
 
+Flags:
+
+- `--preset {claude,aider,gemini}` — agent CLI preset to scaffold (default: `claude`)
+- `--force` — overwrite an existing `agent-runner.toml`
+- `--no-commit` — skip the initial git commit
+
 ```bash
-agent-runner init                      # default: commit
+agent-runner init                      # default: claude preset, commit
+agent-runner init --preset aider       # aider preset
 agent-runner init --no-commit          # skip the commit
 agent-runner init --force              # overwrite an existing toml
 ```
@@ -94,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]`
@@ -133,7 +143,7 @@ agent-runner events --kind transient_error_backoff_capped --tail
 
 `peek` in a clear-and-refresh loop. Default 2s interval. Stop with Ctrl-C.
 
-### `agent-runner monitor [--host SSH-ALIAS] [--interval N] [--json]`
+### `agent-runner monitor [--host SSH-ALIAS] [--interval N] [--mode MODE] [--port PORT] [--json]`
 
 Anomaly-detection daemon. Runs the 12 detectors against the live state on every
 poll. Without `--host`, watches local logs at default 30s interval. With
@@ -143,15 +153,25 @@ When OAuth-fail or disk-critical detectors fire, monitor automatically issues a
 graceful stop (locally via `api.stop`; remotely via `ssh <host> 'agent-runner stop'`).
 Override with `[monitor]` config block (see configuration.md).
 
+Flags:
+
+- `--mode {anomaly,narrate,events,http}` — output mode (default: `anomaly`). `narrate`
+  streams a human-readable narrative; `events` streams raw event JSON; `http` serves
+  a local progress page.
+- `--port PORT` — HTTP port for `--mode http` (default: `8765`, local-only).
+- `--host SSH-ALIAS` — watch a remote agent-runner via ssh (anomaly mode only).
+
 ```bash
-agent-runner monitor                       # local
+agent-runner monitor                       # local anomaly mode
 agent-runner monitor --host pi             # remote
+agent-runner monitor --mode narrate        # streaming narrative
+agent-runner monitor --mode http --port 9000  # HTTP progress page on port 9000
 agent-runner monitor --json | jq -c        # pipe alerts to a downstream consumer
 ```
 
 ## 中文摘要
 
-16 个动词：`init / install / uninstall / start / stop / kill / cancel / restart / status / round / serve / upgrade / peek / watch / events / monitor`。
+16 个动词，完整列表见上方动词表（自动生成）。
 
 观察类（peek/watch/monitor）三视角对称，全部共用 `--round / --log / --events / --select / --json` 下钻参数。
 

{cli_agent_runner-0.1.38 → cli_agent_runner-0.1.40}/docs/configuration.md

@@ -47,6 +47,7 @@ running with newly-set `dirty_action = "auto_commit"` is undefined).
 | `fresh_eyes_every_n` | `int | None` | None |
 | `dry_run` | `bool` | False |
 | `max_grace_after_result_s` | `int` | 0 |
+| `grace_kill_ignore_patterns` | `list[str]` | [] |
 
 ### `[prompt]`
 
@@ -200,6 +201,10 @@ Unconfigured phases (and configs without `[phases]`) keep using the global
 
 ## `[monitor]` (optional, defaults shown)
 
+> Authoritative field-level defaults are in the generated schema table above
+> (`[monitor]` section). The snippet below shows only the fields most commonly
+> customised, with operational notes.
+
 ```toml
 [monitor]
 auto_stop_on = ["oauth_fail", "disk_critical"]
@@ -207,9 +212,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.38 → cli_agent_runner-0.1.40}/docs/long-running-agents.md

@@ -140,7 +140,7 @@ token breakdown + cost (where the underlying CLI exposes it).
 ```
 
 Use as input to a cost-tracking detector or external billing reconciler.
-See `docs/migrations/0.1.28.md` for the current 12-field payload schema
+See `docs/migrations/0.1.28.md` for the current payload schema
 (includes `cache_creation_tokens`, `tool_call_count`, `phase`, `success`)
 plus a consumer dispatcher sketch. Aggregation (rollups, budget warnings)
 is the consumer's responsibility — agent-runner emits raw per-round

cli_agent_runner-0.1.40/docs/migrations/0.1.39.md

@@ -0,0 +1,74 @@
+# Migrating to 0.1.39
+
+## TL;DR
+
+```bash
+pip install --upgrade cli-agent-runner==0.1.39
+```
+
+**Claude users running 0.1.38**: add one line to `[runtime]` to unblock
+grace-kill against claude's persistent shell-snapshot helper (see below).
+New `agent-runner init --preset=claude` scaffolds get this automatically.
+
+**Everyone else**: no action.
+
+## Persistent-helper exclusion (the live fix)
+
+0.1.38's grace-kill liveness check was correctly conservative — it refused to
+reap a round with live worker children — but claude's `-p` mode keeps a
+persistent Bash-tool shell-snapshot subprocess alive for the whole session.
+That subprocess is not doing work; it's idle infrastructure. 0.1.38 saw it as
+a live worker and deferred every post-result hang to `round_timeout_s` instead
+of reaping at `max_grace_after_result_s`. This is the "persistent-helper
+caveat" 0.1.38's migration doc flagged.
+
+0.1.39 adds `[runtime] grace_kill_ignore_patterns` — a list of regex patterns;
+child cmdlines matching any pattern (via `re.search`) are excluded from the
+liveness count. `presets/claude.toml` ships a default pattern matching
+claude's shell-snapshot.
+
+### Existing claude operators — one line
+
+Add to your `[runtime]` block:
+
+```toml
+[runtime]
+grace_kill_ignore_patterns = ['\.claude/shell-snapshots/snapshot-bash-']
+```
+
+Or run `agent-runner init --preset=claude` in a scratch directory and diff
+the generated `agent-runner.toml` against yours.
+
+After the change, post-result hangs are reaped at `max_grace_after_result_s`.
+Without it, they continue to defer to `round_timeout_s` (the 0.1.38 behavior).
+
+### Verifying the pattern is firing
+
+The `round_grace_extended` event payload gains `ignored_children` listing
+cmdlines that matched a pattern. Use it to:
+
+- confirm the shell-snapshot is being filtered (`ignored_children` non-empty)
+- catch the day claude renames its helper (`live_children` shows a new
+  unfiltered persistent process)
+
+### Other presets
+
+`aider.toml` and `gemini.toml` ship no default patterns. Add operator-specific
+patterns to your own `agent-runner.toml` if needed.
+
+## SSOT consistency hardening (also in 0.1.39)
+
+A new invariant `test_doc_claims_match_ssot` gates documented counts
+(detectors / defenses / verbs) and config value-sets against code SSOT.
+`commands.md` documents `monitor --mode/--port` and `init --preset`.
+Redundant count guards collapsed to one canonical tripwire each. The unused
+`alert-kinds` docgen renderer was removed. No action required.
+
+## What did NOT change
+
+- The 0.1.38 grace-kill liveness semantics (still process-group-based;
+  patterns are an exclusion filter on top).
+- `round_grace_kill` (still fires only when the post-filter live set is empty).
+- `round_timeout_s` (still the hard ceiling).
+- `max_grace_after_result_s` (knob unchanged).
+- For non-claude deployments: zero behavior change.