cli-agent-runner 0.2.1__tar.gz → 0.2.2__tar.gz

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/.github/workflows/ci.yml

@@ -87,6 +87,10 @@ jobs:
         run: |
           ruff check .
           ruff format --check .
+      - name: vulture (dead-code scan)
+        # Config in [tool.vulture]; exits nonzero on any finding. No pipe — a
+        # `| tail` would swallow the exit code and let dead code through.
+        run: vulture
       - name: tests with coverage
         run: pytest -q --ignore=tests/e2e --ignore=tests/literate --cov --cov-report=xml --cov-report=term
       - name: docs CI gate

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/.gitignore

@@ -30,3 +30,8 @@ htmlcov/
 
 # Personal /team-onboarding artifact — not project content
 ONBOARDING.md
+
+# Local tooling scratch directories — never project content, never published.
+# Defense in depth only: releases build from a fresh CI checkout, and every
+# sdist 0.1.1–0.2.1 was checked clean. This only guards a local `python -m build`.
+.superpowers/

cli_agent_runner-0.2.2/.vulture-whitelist.py

@@ -0,0 +1,244 @@
+# GENERATED by tests/generate_vulture_whitelist.py — DO NOT EDIT BY HAND.
+# Regenerate: ./build.sh vulture-whitelist
+#
+# vulture (min_confidence=60) reports @dataclass fields as "unused variable":
+# they cross a JSON / CLI / plugin boundary static analysis cannot see. Each
+# bare name below marks one field "used". SSOT = the @dataclass definitions in
+# agent_runner/; a new field is covered by regenerating, never by editing here.
+
+# agent_runner.agent_runtime.RunResult
+exit_code
+duration_s
+timed_out
+pid
+killed_for_grace
+grace_kill_children
+
+# agent_runner.api_types.Alert
+severity
+detector
+message
+context
+ts
+auto_action
+
+# agent_runner.api_types.DirtyOutcome
+kind
+ref
+
+# agent_runner.api_types.InitResult
+work_dir
+files_created
+committed
+preset
+
+# agent_runner.api_types.InstallResult
+unit_path
+monitor_unit_path
+enabled
+started
+
+# agent_runner.api_types.ProjectState
+project
+status
+defenses
+current_round
+recent_rounds
+orphan
+system
+service
+recent_events
+recent_hook_failures
+recent_blips
+
+# agent_runner.api_types.RateLimitState
+throttled_until_epoch
+limit_type
+agent
+since_round
+
+# agent_runner.api_types.RoundResult
+round_num
+phase
+started_at
+ended_at
+exit_code
+duration_s
+timed_out
+log_path
+dirty_files
+stashed
+dirty_outcome
+killed_for_grace
+
+# agent_runner.api_types.RoundView
+round_num
+phase
+started_at
+duration_so_far_s
+pid
+exit_code
+timed_out
+log_path
+log_tail
+recent_events
+
+# agent_runner.api_types.ServiceStatus
+mode
+active
+pid
+uptime_s
+unit_file
+rate_limit
+
+# agent_runner.api_types.SystemMetrics
+mem_total_mb
+mem_available_mb
+disk_used_pct
+disk_free_gb
+load_1m
+cpu_pct
+agent_process_count
+
+# agent_runner.api_types.TransientErrorState
+reset_at_epoch
+classification
+agent
+since_round
+
+# agent_runner.config.AgentConfig
+command
+prompt_arg_template
+name
+env
+prompt_delivery
+
+# agent_runner.config.Config
+agent
+runtime
+prompt
+vcs
+monitor
+phases
+plugins
+
+# agent_runner.config.MonitorConfig
+auth_fail_patterns
+auth_fail_hint
+auto_stop_on
+remote_failure_tolerance_s
+anomaly_repetitive_window
+anomaly_repetitive_threshold
+host_health
+round_progress_interval_s
+supervisor_stale_threshold_s
+
+# agent_runner.config.MonitorHostHealthConfig
+mem_avail_min_mb
+disk_warning_pct
+disk_critical_pct
+
+# agent_runner.config.PhaseOverride
+round_timeout_s
+disable_pre_round_hooks
+prompt_files
+
+# agent_runner.config.PhasesConfig
+list
+overrides
+
+# agent_runner.config.PluginsConfig
+disable
+raw
+
+# agent_runner.config.PromptConfig
+file
+files
+inject_context
+context_injection_mode
+concat_separator
+strip_yaml_frontmatter
+
+# agent_runner.config.RuntimeConfig
+work_dir
+log_dir
+round_timeout_s
+restart_delay_s
+disable_pre_round_hooks
+round_log_retention
+narrative_file
+transient_error_action
+max_rounds
+stop_file
+substrate_fingerprint_paths
+fresh_eyes_every_n
+dry_run
+max_grace_after_result_s
+grace_kill_ignore_patterns
+
+# agent_runner.config.VcsConfig
+stash_idempotency_s
+dirty_action
+
+# agent_runner.context_store.OrphanState
+round_num
+files
+stashed_ref
+stash_message
+timestamp
+phase
+
+# agent_runner.context_store.Status
+round_num
+running
+last_completed_at
+last_exit_code
+last_duration_s
+current_phase
+phase_index
+
+# agent_runner.defenses.Defense
+name
+value
+codifies
+guarded_by
+current_state
+
+# agent_runner.hooks.HookContext
+work_dir
+log_dir
+project
+round_num
+phase
+agent_name
+agent_binary
+agent_log_path
+dry_run
+anomaly_repetitive_window
+anomaly_repetitive_threshold
+vcs
+
+# agent_runner.hooks.VcsHookView
+dirty_action
+stash_idempotency_s
+
+# agent_runner.lifecycle.PIDFile
+path
+
+# agent_runner.monitor.LocalSource
+log_dir
+
+# agent_runner.monitor.RemoteSource
+host
+project
+
+# agent_runner.startup_check.CheckResult
+name
+ok
+reason
+how_to_fix
+
+# agent_runner.vcs_state.StashRef
+sha
+message
+reused

cli_agent_runner-0.2.2/BACKLOG.md

@@ -0,0 +1,90 @@
+# Backlog
+
+Known follow-ups that are real design or behavior decisions, not defects. Each
+entry carries enough context to act on without re-deriving it.
+
+Items marked **NEEDS_DESIGN** change user-visible behavior and are held for an
+explicit decision — they are not shipped silently in a maintenance release.
+
+## `try_auto_commit` sweeps plugin-owned paths
+
+`vcs_state.try_auto_commit` runs `git add -A` with an exclude pathspec built only
+from the log directory (`_log_dir_exclude_pathspec`), so under
+`vcs.dirty_action = "auto_commit"` paths registered via
+`register_plugin_owned_paths` are committed along with the agent's work.
+
+0.2.2 made the registry authoritative at the git boundary for `stash_orphan`
+only. That fix discharged the specific promise in `docs/plugins.md` that owned
+paths are not silently swept into an orphan stash. `auto_commit` is a different
+promise with a different harm (a commit, not a hidden stash) and no equivalent
+published guarantee, so it needs its own call: should `auto_commit` honor the
+registry, or is committing a plugin deliverable alongside agent work the
+intended behavior?
+
+## `_tail_events` / `_tail_events_jsonl` duplication
+
+`cli/events_cmd.py:_tail_events` and `api.py:_tail_events_jsonl` both tail the
+event stream, deliberately at different scopes: `api` globs every
+`events-*.jsonl`; `events_cmd` is current-month-scoped and resets its offset to
+0 on truncation. They are not accidental copies. Collapsing them means first
+deciding which scope is correct for each caller.
+
+Related, from the same area: the kind-read loops in `_throttle.py` and
+`monitor.py` (`kind = ev.get("event")` over `reversed(events)`) are
+character-identical after the 0.2.2 constant normalization. Extracting a shared
+helper is a structural change, not a literal swap.
+
+## Detector fixtures pin raw event-kind literals
+
+Detector test fixtures construct events from hardcoded strings (`{"event":
+"round_start"}`) rather than emitting through `events.emit()`. Fixture and
+reader therefore agree with each other while both can diverge from what the
+supervisor actually writes.
+
+Proven by mutation: point the emitter at a different kind value and the 28
+`test_claude_error_detector.py` tests stay green while every detector is blind.
+The 0.2.2 constant normalization does not close this — it moves the pin from the
+reader to the fixture. Closing it means fixtures emitting through
+`events.emit()`, or an end-to-end test asserting a real round produces events
+the detectors actually match.
+
+Bounded by `docs/events.md`, which forbids renaming a kind value outright (the
+kind name is the version discriminator; a breaking change ships as
+`round_start_v2`). Reaching this failure requires a contract violation — but the
+suite would not report it.
+
+## `remote_failure_tolerance_s` does not cover `subprocess.TimeoutExpired` — NEEDS_DESIGN
+
+The tolerance window covers ssh exit code 255 only. `monitor.run_remote_command`
+raises `MonitorRemoteError` on rc=255, and `api.monitor_loop`'s retry loop
+catches exactly that. A hung (not failed) ssh connection instead trips the
+`subprocess.run(timeout=...)` guard and raises `subprocess.TimeoutExpired`,
+which bypasses the window and kills the monitor.
+
+The rc=255-only scope is intentional and pinned by the monitor-signals design,
+and the documentation matches the code exactly — there is no drift here. Widening
+it changes a documented recovery path, so it is a design decision, not debt.
+
+## `anomaly_repetitive_*` default — NEEDS_DESIGN
+
+`monitor.anomaly_repetitive_window` and `anomaly_repetitive_threshold` both
+default to `0`, which disables the detector. This is a deliberate opt-in kill
+switch, documented since the field's first commit, and the detector fires
+correctly the moment an operator opts in.
+
+The open question is whether opt-in is the right default, or whether this belongs
+in a preset. Flipping the default would arm a new alert for every existing
+deployment.
+
+## `stash_orphan` loses the ref when the post-push listing fails
+
+`vcs_state.stash_orphan` returns `None` in three cases; two are true no-ops. The
+third — `git stash push` succeeded but the follow-up `git stash list` failed —
+means the WIP *is* stashed yet callers read "nothing stashed" and report the
+tree as ignored. It is already documented in-code as a KNOWN GAP and judged
+effectively unreachable (a listing that fails microseconds after a push that
+just succeeded in the same repo).
+
+Deferred because closing it is a naming decision, not cleanup: no event kind
+carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
+— the stash exists). Left as-is until that kind is designed.

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.2] - 2026-07-18
+
+### Removed
+- `agent_runner.detector_helpers` and its three helpers (`cumulative_window_check`, `dual_source_silence`, `phase_filter`) — **breaking** for any out-of-tree detector that imported them; vendor the ~115 LOC.
+- `agent-runner cancel` and `api.cancel()` — **breaking**; they never delivered the documented SIGINT-to-round semantics (nothing ever wrote the `round.pid` they read), so `cancel` was only a slower alias for `stop`. Use `stop`; `serve` no longer traps `SIGUSR1`.
+- `events.SIGTERM_RECEIVED` (the `sigterm_received` kind) — declared but never emitted, so nothing could ever observe it.
+
+### Changed
+- Paths registered with `register_plugin_owned_paths` are no longer swept into the orphan stash: all three documented pattern forms (trailing-slash prefix, glob, `**/*`) are now honored at the git boundary, not only the report boundary, so a deliverable is no longer silently stashed — and possibly lost — when the agent also touches a non-owned file. `**/*` patterns now also match files directly in the registered directory, changing which paths `detect_dirty_files` filters. **Check `git stash list` if you register owned paths.**
+- Config-load rejections now raise `ConfigError` (a subclass of `ValueError`) consistently; fully backward compatible — any `except ValueError` still catches them.
+- `[monitor.host_health]` percent thresholds, `[prompt] inject_context`, and `[monitor] auth_fail_patterns` are validated at load, so configs that were previously accepted-but-silently-broken now fail loudly at startup.
+
+### Fixed
+- `agent-runner events --tail` no longer re-emits events appended while a poll's read loop was in flight.
+- The orphan-stash defense now signals push failure (`orphan_stash_failed`) and idempotent reuse (`orphan_idempotent_skip`) — both kinds were declared but never emitted — instead of degrading silently; `stash_orphan` raises `StashError` (re-exported from `agent_runner.api`) on push failure.
+- Plugin-supplied transient-error classifications no longer crash the supervisor with `KeyError`.
+- Defense-catalog honesty (every advertised defense now names a real guarding test) and ~31 false claims across README, docs, and docstrings.
+
+### Added
+- Housekeeping: the build gate runs `vulture` (dead-code scan, whitelist auto-generated from `@dataclass` fields); `AGENT_RUNNER_FRESH_EYES` is now a documented, tested round-subprocess env-var contract; `SECURITY.md` gains a threat model (agent-runner is a supervisor, not a sandbox).
+
+See `docs/migrations/0.2.2.md`.
+
 ## [0.2.1] - 2026-07-16
 
 ### Added

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/CONTRIBUTING.md

@@ -29,6 +29,26 @@ what GitHub Actions runs on every push and PR.
    reject auto-generated trailers and robot signatures — keep messages
    human-authored.
 
+## Migration docs
+
+A `docs/migrations/<version>.md` guide is written **only** when a release:
+
+- makes a **breaking change** — a removed or renamed public symbol, or a
+  config that used to load and now does not; or
+- **requires operator action** — a TOML edit, a manual recovery step, or a
+  data/format migration.
+
+Otherwise `CHANGELOG.md` carries the whole story; a guide that only restates
+the changelog is upkeep with no reader. When a guide does exist, keep the
+CHANGELOG entry terse and link it (`See docs/migrations/<version>.md.`).
+
+0.2.2 is the first release written under this policy: it removes two public
+symbols — the `detector_helpers` module and the `cancel` verb — so it ships a
+guide. Existing `docs/migrations/` files are history: append-only, never
+rewritten or deleted, including ones this policy would not have produced.
+Correct a shipped guide with a dated `**Correction (<version>)**:` note, not
+an edit in place.
+
 ## Architecture / docs
 
 - [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data.
@@ -40,6 +60,12 @@ table in `docs/*.md` are auto-generated by `./build.sh docs`. The CI gate
 fails if those regions drift from the code's source of truth. Don't edit
 them manually — edit the generator or the data source.
 
+`.vulture-whitelist.py` is likewise generated — from every `@dataclass` field
+in `agent_runner/`. If you add or rename a dataclass field, run
+`./build.sh vulture-whitelist` and commit the regenerated file;
+`tests/invariants/test_vulture_whitelist_generated.py` fails the gate if it
+drifts.
+
 ## Tests
 
 - Unit + integration: `pytest -q --ignore=tests/e2e --ignore=tests/literate`

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -31,7 +31,6 @@ Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Requires-Dist: vulture>=2.13; extra == 'dev'
 Provides-Extra: e2e
-Requires-Dist: fabric>=3; extra == 'e2e'
 Requires-Dist: pytest>=8; extra == 'e2e'
 Description-Content-Type: text/markdown
 
@@ -41,9 +40,10 @@ Description-Content-Type: text/markdown
 
 # agent-runner
 
-A restart-on-exit supervisor for autonomous coding CLIs. Tested with Claude
-Code and aider out of the box; any prompt-arg CLI via custom config. Spawn
-the agent round-after-round under defenses that prevent the failure modes
+A restart-on-exit supervisor for autonomous coding CLIs. Ships presets for
+Claude Code, aider, gemini and codewhale; any prompt-arg CLI via custom
+config. Spawn the agent round-after-round under defenses that prevent the
+failure modes
 that bite in production: stuck rounds, orphan commits, OAuth burn loops,
 full disks, runaway memory.
 
@@ -80,12 +80,12 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 16 verbs
+## 15 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
-| `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
+| `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/README.md

@@ -4,9 +4,10 @@
 
 # agent-runner
 
-A restart-on-exit supervisor for autonomous coding CLIs. Tested with Claude
-Code and aider out of the box; any prompt-arg CLI via custom config. Spawn
-the agent round-after-round under defenses that prevent the failure modes
+A restart-on-exit supervisor for autonomous coding CLIs. Ships presets for
+Claude Code, aider, gemini and codewhale; any prompt-arg CLI via custom
+config. Spawn the agent round-after-round under defenses that prevent the
+failure modes
 that bite in production: stuck rounds, orphan commits, OAuth burn loops,
 full disks, runaway memory.
 
@@ -43,12 +44,12 @@ agent-runner monitor              # live anomaly detection
 
 Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 
-## 16 verbs
+## 15 verbs
 
 | Lifecycle | Observation |
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
-| `start` / `stop` / `kill` / `cancel` | `watch` — peek in a refresh loop |
+| `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
 | `restart` / `status` | `monitor` — 11 detectors, alerts, auto-stop |
 | `round` / `serve` / `upgrade` | `events` — query / stream events.jsonl |
 

cli_agent_runner-0.2.2/README.zh.md

@@ -0,0 +1,37 @@
+> 中文 · **[English](README.md)**
+
+# agent-runner
+
+把任意 CLI agent（Claude Code、aider、任何接受 prompt 参数的命令）包装成能被
+systemd / launchd 拉起、能被远程观测的服务。**每轮跑完进程退出**，外层
+supervisor 重启 —— 这是核心模式。中间穿插一组防御，避开 production 上最容易
+翻车的几条路：轮卡死、脏文件没 commit、OAuth 失效烧 quota、磁盘写满、
+两个 supervisor 抢同一个仓库。
+
+三层，每层都能独立运行，上层都是可选的：`round` 跑一次 agent 跑完即退；
+`serve` 捕获信号循环拉起 round；`monitor` 检测器 + 告警，critical 时自动停服
+（本机或 ssh 远程）。
+
+## 安装
+
+```bash
+pip install cli-agent-runner
+```
+
+CLI 命令是 `agent-runner`（PyPI 包名加 `cli-` 前缀只是为了规避命名冲突，
+导入名 `agent_runner` 和命令名都不变）。
+
+## 完整文档
+
+文档以英文为准。下面 `docs/` 各页末尾都附有中文摘要，完整细节见英文正文：
+
+- [`docs/quickstart.md`](docs/quickstart.md) —— 5 步装好并跑通第一轮
+- [`README.md`](README.md) —— 定位、动词表、内置防御、Monitor 检测器
+- [`docs/architecture.md`](docs/architecture.md) —— 三层模型 + defenses-as-data
+- [`docs/commands.md`](docs/commands.md) —— 动词参考
+- [`docs/configuration.md`](docs/configuration.md) —— `agent-runner.toml` schema
+- [`docs/runbook.md`](docs/runbook.md) —— 操作手册 + 故障排查
+
+## License
+
+[Apache License 2.0](LICENSE).

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/SECURITY.md

@@ -20,6 +20,23 @@ Please **do not** open a public issue for security problems.
 - An initial assessment within 7 business days.
 - A fix and coordinated disclosure timeline once the scope is understood.
 
+## Threat model
+
+agent-runner is a **supervisor**, not a sandbox. It provides observability
+(structured events, peek/watch/monitor) and lifecycle safety (round timeouts,
+process-group reaping, orphan stashing, auto-stop on critical alerts). It does
+**not** confine the agent process: the agent runs with the invoking user's full
+privileges and can read, write, and execute anything that user can.
+
+Prompt injection from untrusted repository content is unsolved and out of the
+supervisor's reach — a malicious file in the work tree can steer the agent, and
+no defense in this project prevents that.
+
+Operators supervising untrusted input should run the agent as a dedicated
+unprivileged user, inside a container or VM, without passwordless sudo, and
+with egress limits. The supervisor's defenses bound the blast radius of a
+*misbehaving* agent, not a *hostile* one.
+
 ## Scope
 
 In scope: the `agent_runner` Python package, its CLI, its bundled systemd

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.2}/agent_runner/_docgen.py

@@ -17,6 +17,9 @@ from agent_runner.config import (
     AgentConfig,
     Config,
     MonitorConfig,
+    MonitorHostHealthConfig,
+    PhasesConfig,
+    PluginsConfig,
     PromptConfig,
     RuntimeConfig,
     VcsConfig,
@@ -25,41 +28,60 @@ from agent_runner.defenses import catalog
 from agent_runner.events import KNOWN_EVENT_KINDS
 from agent_runner.monitor import AUTO_STOP_ALERTS, KNOWN_ALERT_KINDS
 
-_SECTIONS = [
-    ("agent", AgentConfig),
-    ("runtime", RuntimeConfig),
-    ("prompt", PromptConfig),
-    ("vcs", VcsConfig),
-    ("monitor", MonitorConfig),
+# (toml_section_name, dataclass, nested_sub_sections). Nesting is an EXPLICIT
+# registry, not reflection, on two counts:
+#   - field name != TOML key: PhaseOverride.prompt_files is written as
+#     [phases.<name>.prompt] files=[...], and PluginsConfig.raw is a catch-all
+#     for unknown keys. Recursing generically would document TOML keys that do
+#     not exist.
+#   - typing.get_type_hints() raises TypeError on PhasesConfig — its `list`
+#     field shadows the builtin, so `list[str] | None` resolves against
+#     None. Do not reach for it here.
+_SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
+    ("agent", AgentConfig, []),
+    ("runtime", RuntimeConfig, []),
+    ("prompt", PromptConfig, []),
+    ("vcs", VcsConfig, []),
+    ("monitor", MonitorConfig, [("monitor.host_health", MonitorHostHealthConfig)]),
+    ("phases", PhasesConfig, []),
+    ("plugins", PluginsConfig, []),
 ]
 
 
+def _cell(s: str) -> str:
+    # A bare `|` ends the markdown cell. Live sources: `X | None` annotations
+    # and the auth_fail_patterns regex default.
+    return s.replace("|", "\\|")
+
+
 def _type_label(t: typing.Any) -> str:
     # dataclasses.fields exposes `.type` as a string (PEP 563), so we render
     # the raw annotation. Strip ``Path`` / ``Path | None`` wrappers cosmetically.
-    s = str(t).replace("pathlib.", "")
-    return s
+    return _cell(str(t).replace("pathlib.", ""))
 
 
 def _default_label(field: dataclasses.Field) -> str:
     if field.default is not dataclasses.MISSING:
-        return repr(field.default)
+        return _cell(repr(field.default))
     if field.default_factory is not dataclasses.MISSING:  # type: ignore[misc]
-        return repr(field.default_factory())
+        return _cell(repr(field.default_factory()))
     return "—"
 
 
+def _field_table(dc: type) -> list[str]:
+    rows = ["| Field | Type | Default |", "|---|---|---|"]
+    for f in dataclasses.fields(dc):
+        rows.append(f"| `{f.name}` | `{_type_label(f.type)}` | {_default_label(f)} |")
+    return rows
+
+
 def render_config_schema_table() -> str:
     """Markdown sub-sections per Config dataclass with field/type/default."""
     parts: list[str] = []
-    for name, dc in _SECTIONS:
-        parts.append(f"### `[{name}]`")
-        parts.append("")
-        parts.append("| Field | Type | Default |")
-        parts.append("|---|---|---|")
-        for f in dataclasses.fields(dc):
-            parts.append(f"| `{f.name}` | `{_type_label(f.type)}` | {_default_label(f)} |")
-        parts.append("")
+    for name, dc, nested in _SECTIONS:
+        parts += [f"### `[{name}]`", "", *_field_table(dc), ""]
+        for sub_name, sub_dc in nested:
+            parts += [f"#### `[{sub_name}]`", "", *_field_table(sub_dc), ""]
     return "\n".join(parts).rstrip()
 
 
@@ -80,7 +102,11 @@ def replace_block(text: str, name: str, new_content: str) -> str:
         re.escape(open_tag) + r".*?" + re.escape(close_tag),
         re.DOTALL,
     )
-    return pattern.sub(f"{open_tag}\n{new_content}\n{close_tag}", text)
+    replacement = f"{open_tag}\n{new_content}\n{close_tag}"
+    # A string repl is a TEMPLATE (expands \n, \t, \1, \g<...>); a callable repl
+    # is inserted literally. new_content carries rendered config defaults, which
+    # may contain backslashes.
+    return pattern.sub(lambda _m: replacement, text)
 
 
 def _default_cfg() -> Config: