cli-agent-runner 0.2.8__tar.gz → 0.2.10__tar.gz

{cli_agent_runner-0.2.8 → cli_agent_runner-0.2.10}/.vulture-whitelist.py

@@ -57,6 +57,7 @@ throttled_until_epoch
 limit_type
 agent
 since_round
+phase
 
 # agent_runner.api_types.RoundResult
 round_num
@@ -106,6 +107,7 @@ reset_at_epoch
 classification
 agent
 since_round
+phase
 
 # agent_runner.config.AgentConfig
 command
@@ -144,15 +146,24 @@ disk_critical_pct
 round_timeout_s
 disable_pre_round_hooks
 prompt_files
+agent
+schedule
 
 # agent_runner.config.PhasesConfig
 list
 overrides
+phase_policy
 
 # agent_runner.config.PluginsConfig
 disable
 raw
 
+# agent_runner.config.Profile
+agent
+runtime
+schedule
+prompt_files
+
 # agent_runner.config.PromptConfig
 file
 files
@@ -245,6 +256,15 @@ manual
 # agent_runner.monitor.LocalSource
 log_dir
 
+# agent_runner.phase_select.Selection
+phase
+paused
+resume_at
+resume_phase
+resume_timezone
+skipped
+active_window
+
 # agent_runner.round_log.PruneOutcome
 deleted
 deferred

{cli_agent_runner-0.2.8 → cli_agent_runner-0.2.10}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.10] - 2026-08-29
+
+### Added
+- Throttle-aware skip: under `[phases] phase_policy = "skip"`, a phase whose provider is currently rate-limited/erroring is stepped over in the rotation — a healthy sibling runs instead of the whole loop sleeping on the throttle. No new config; the trigger is the existing `skip` policy.
+- `transient_error_detected` now carries the failing `phase`; `peek --json` `rate_limit` and the HTTP progress state surface which phase is throttled.
+- `transient_error_recovered` is emitted when a skip-around throttle clears (events-derived, restart-safe, no double-emit with the back-off path).
+
+### Notes
+- Only `skip` routes around a throttle; `wait`, `--ignore-schedule`, and non-`[phases]` configs keep the 0.2.9 global back-off. When every phase is throttled or window-closed, the loop waits until the earlier of a window opening or the throttle resetting.
+
+See `docs/migrations/0.2.md`.
+
+## [0.2.9] - 2026-08-28
+
+### Added
+- Per-phase profiles: `[phases.<name>.agent]` and `[phases.<name>.schedule]` join the existing runtime/prompt overrides, so each phase resolves its own `(agent, runtime, schedule, prompt files)`. A phase's `[...agent]` field-merges onto the base `[agent]` (swap just `command`, inherit the rest); its `[...schedule]` replaces the global windows wholesale. Runs each phase under its own model — see the mixed-model rotation recipe.
+- `[phases.<name>.runtime]` nested sub-table for `round_timeout_s` / `disable_pre_round_hooks`; the flat `[phases.<name>]` form stays as a permanent alias. Setting both twins is a config error.
+- `[phases] phase_policy` (`wait` | `skip`): on a per-phase schedule, `wait` idle-sleeps until this round's phase opens; `skip` steps the rotation forward to the first open phase and runs it. `schedule_phase_skipped` event (`round_num`, `skipped`, `chosen`, `active_window`) records the stepped-over phases.
+- `agent-runner migrate` reports (does not rewrite) flat per-phase runtime overrides that can move under `[phases.<name>.runtime]`.
+
+See `docs/migrations/0.2.md`.
+
 ## [0.2.8] - 2026-08-25
 
 ### Added
@@ -14,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Removed-field `ConfigError` messages now point to `agent-runner migrate`.
 
-See `docs/migrations/0.2.8.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.7] - 2026-08-25
 
@@ -26,7 +48,7 @@ See `docs/migrations/0.2.8.md`.
 ### Fixed
 - Monitor no longer raises `supervisor_stale` during an intentional schedule pause (suppressed until `resume_at` plus one staleness window).
 
-See `docs/migrations/0.2.7.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.6] - 2026-07-28
 
@@ -39,7 +61,7 @@ See `docs/migrations/0.2.7.md`.
 ### 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`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.5] - 2026-07-27
 
@@ -50,7 +72,7 @@ See `docs/migrations/0.2.6.md`.
 ### Removed
 - The polling remote monitor (`RemoteSource`, `run_remote_command`, `MonitorRemoteError`, auto-stop over ssh) — it read remote paths on the local filesystem and was already failing loud since 0.2.4. Detection is on-host by design; remote observation is the relay above. `monitor.on_alert` lost its `host` parameter and `monitor_auto_stop_triggered` its `host` field; `monitor_auto_stop_failed` now reports a failed *local* stop (previously a failed ssh stop) instead of crashing the monitor loop.
 
-See `docs/migrations/0.2.5.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.4] - 2026-07-27
 
@@ -67,7 +89,7 @@ See `docs/migrations/0.2.5.md`.
 - Startup validation resolves the agent command exactly as the spawn does (child's PATH — `[agent.env]` may override it — and `work_dir` base); `PWD` now stays pinned to `work_dir` even if `[agent.env]` sets it. The stdout+stderr merge is now pinned by a behavioral test, not just prose.
 - Generated serve systemd units now set `KillMode=mixed`: with systemd's default `control-group`, `systemctl stop` SIGTERMed the whole cgroup — agent child included — making the graceful round drain structurally ineffective. Existing installs: re-run `agent-runner install` (or add a drop-in) to pick this up.
 
-See `docs/migrations/0.2.4.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.3] - 2026-07-26
 
@@ -79,7 +101,7 @@ See `docs/migrations/0.2.4.md`.
 - The agent subprocess now runs in `runtime.work_dir` (`cwd=` on spawn). Previously it inherited the supervisor's cwd and only launch conventions (systemd `WorkingDirectory=`, relative `--config`) kept the two aligned — fatal for agent CLIs with no working-directory flag of their own (e.g. `pi`). The startup check now also validates a relative `agent.command[0]` against `work_dir`, matching where it executes.
 - Plugin round-log tail window widened 50 → 200 lines: a stderr burst after the agent's terminal JSONL event could evict it from the scan window, silently dropping usage/transient classification. The round log's merged stdout+stderr contract is now documented (`HookContext.agent_log_path`, `docs/long-running-agents.md`) — the merge is deliberate; auth/network detection reads stderr text from it.
 
-See `docs/migrations/0.2.3.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.2] - 2026-07-18
 
@@ -102,7 +124,7 @@ See `docs/migrations/0.2.3.md`.
 ### 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`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.1] - 2026-07-16
 
@@ -113,7 +135,7 @@ See `docs/migrations/0.2.2.md`.
 ### Fixed
 - A signal-killed round is no longer misclassified as `agent_network_blip` when its log happens to contain a network-error string; signal deaths are terminations, not network blips.
 
-See `docs/migrations/0.2.1.md`.
+See `docs/migrations/0.2.md`.
 
 ## [0.2.0] - 2026-07-02
 
@@ -121,7 +143,7 @@ See `docs/migrations/0.2.1.md`.
 - Dirty-tree handling is now pluggable. The clean-exit-dirty policy moved out of core into a `dirty_handler` hook; `stash` / `ignore` / `auto_commit` now ship as the bundled, default-on `default_dirty_handler` plugin. **No behavior or config change for existing users** — `[vcs] dirty_action` works exactly as before.
 
 ### Added
-- `dirty_handler` plugin seam (4th lifecycle hook) + `DirtyOutcome` on `RoundResult`; `stash_orphan` / `try_auto_commit` are now public `api` primitives. Consumers can fully own dirty-tree policy — see `docs/migrations/0.2.0.md`.
+- `dirty_handler` plugin seam (4th lifecycle hook) + `DirtyOutcome` on `RoundResult`; `stash_orphan` / `try_auto_commit` are now public `api` primitives. Consumers can fully own dirty-tree policy — see `docs/migrations/0.2.md`.
 - `dirty_auto_committed` event (emitted when a handler auto-commits).
 
 ## [0.1.42] - 2026-06-25
@@ -150,7 +172,7 @@ See `docs/migrations/0.2.1.md`.
 ### 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`.
+- Pre-0.1.40 `events-*.jsonl` may contain unredacted argv/excerpts.
 
 ### Changed
 - Docs: `configuration.md` `[monitor.host_health]` example points to the generated schema table instead of restating default values.
@@ -206,7 +228,7 @@ See `docs/migrations/0.2.1.md`.
 ## [0.1.35] - 2026-05-20
 
 ### Removed
-- `claude_rate_limit_detector` plugin alias (0.1.20-era back-compat layer after the 0.1.23 rename to `claude_error_detector`). Hard-cut at both entry-point and config-mapping layers. See `docs/migrations/0.1.35.md` for the 1-line TOML migration.
+- `claude_rate_limit_detector` plugin alias (0.1.20-era back-compat layer after the 0.1.23 rename to `claude_error_detector`). Hard-cut at both entry-point and config-mapping layers.
 
 ## [0.1.34] - 2026-05-20
 
@@ -218,8 +240,6 @@ See `docs/migrations/0.2.1.md`.
 ### Removed
 - `peek --select events.<kind>` selector (mis-placed in state-snapshot verb). Use `events --kind <kind>` instead. 1-line `s///` migration.
 
-See `docs/migrations/0.1.34.md`.
-
 ## [0.1.33] - 2026-05-19
 
 ### Added
@@ -228,8 +248,6 @@ See `docs/migrations/0.1.34.md`.
 - `transient_error_backoff_capped` event gains `original_reset_at_epoch`, `applied_reset_at_epoch`, `consecutive_count`, `capped_by_absolute_max` fields for backoff-curve observability.
 - `docs/thesis.md` names the server-authoritative vs estimated reset principle.
 
-See `docs/migrations/0.1.33.md`.
-
 ## [0.1.32] - 2026-05-18
 
 ### Added
@@ -238,8 +256,6 @@ See `docs/migrations/0.1.33.md`.
 - `[monitor.host_health]` config section — `mem_avail_min_mb` / `disk_warning_pct` / `disk_critical_pct` thresholds for `mem_pressure` / `disk_warning` / `disk_critical` detectors. Defaults preserve prior behavior.
 - New monitor detector `anomaly_repetitive_active` (notify) — alerts when `anomaly_repetitive_tool` events fire in recent rounds. Detector count 10 → 11.
 
-See `docs/migrations/0.1.32.md`.
-
 ## [0.1.31] - 2026-05-18
 
 ### Added
@@ -248,8 +264,6 @@ See `docs/migrations/0.1.32.md`.
 - `[runtime] dry_run` boolean exposed via `HookContext.dry_run` for plugin authors to skip side-effect actions when set.
 - Documentation: TOML changes require daemon restart (no hot-reload); phase rotation indexing clarification.
 
-See `docs/migrations/0.1.31.md`.
-
 ## [0.1.30] - 2026-05-18
 
 ### Fixed
@@ -262,8 +276,6 @@ See `docs/migrations/0.1.31.md`.
 - `docs/thesis.md` — project non-goals SSOT for feature-request evaluation.
 - README + runbook callouts for SSH trust boundary of `monitor --host`.
 
-See `docs/migrations/0.1.30.md`.
-
 ## [0.1.29] - 2026-05-17
 
 ### Added
@@ -278,8 +290,6 @@ See `docs/migrations/0.1.30.md`.
 - Legacy API exports: `emit_rate_limit_rejected`, `emit_rate_limit_recovered`, `emit_rate_limit_backoff_capped`.
 - Config alias `runtime.rate_limit_action` — use `runtime.transient_error_action`. Removed configs now error with migration hint.
 
-See `docs/migrations/0.1.29.md`.
-
 ## [0.1.28] - 2026-05-17
 
 ### Added
@@ -295,7 +305,7 @@ See `docs/migrations/0.1.29.md`.
 - `agent_runner.api_types.ThrottleState` dead alias (0.1.23 back-compat; deprecation window
   passed; switch to `TransientErrorState`).
 
-See `docs/migrations/0.1.28.md`.
+See `docs/plugins.md` under `claude_error_detector` for the `agent_usage_recorded` payload schema.
 
 ## [0.1.27] - 2026-05-17
 
@@ -305,11 +315,9 @@ See `docs/migrations/0.1.28.md`.
   Affects supervisors consuming transient_error_detected.
 
 ### Added
-- docs/migrations/0.1.27.md: supervisor usage guide for transient_error_detected event
+- Supervisor usage guide for transient_error_detected event
   (4-bucket dispatch table + back-off recipe).
 
-See `docs/migrations/0.1.27.md`.
-
 ## [0.1.26] - 2026-05-17
 
 - Fix claude `agent_usage_recorded` `model` field (was always
@@ -322,8 +330,6 @@ See `docs/migrations/0.1.27.md`.
   `gemini_error_detector` plugin can parse output. Existing scaffolds
   need manual TOML edit; round log format changes (text → JSONL).
 
-See `docs/migrations/0.1.26.md`.
-
 ## [0.1.25] - 2026-05-17
 
 - **Hotfix**: built-in `claude_error_detector` and `gemini_error_detector`
@@ -334,8 +340,6 @@ See `docs/migrations/0.1.26.md`.
 - `HookContext.agent_log_path: Path | None = None` (additive). 3rd-party
   plugin authors reading `ctx.log_dir / "round-{N}.log"` should migrate.
 
-See `docs/migrations/0.1.25.md`.
-
 ## [0.1.24] - 2026-05-17
 
 - New `agent_usage_recorded` event: per-round token + cost data, emitted
@@ -348,8 +352,6 @@ See `docs/migrations/0.1.25.md`.
   unattended operation (gemini CLI refuses headless runs in untrusted
   dirs). Existing scaffolds need manual edit.
 
-See `docs/migrations/0.1.24.md`.
-
 ## [0.1.23] - 2026-05-17
 
 - Generalized claude error handling: new `transient_error_*` event family
@@ -362,8 +364,6 @@ See `docs/migrations/0.1.24.md`.
 - Plugin `claude_rate_limit_detector` renamed to `claude_error_detector`
   (entry-point alias preserved).
 
-See `docs/migrations/0.1.23.md`.
-
 ## [0.1.22] - 2026-05-16
 
 - `[runtime] substrate_fingerprint_paths` + `round_substrate_before` /
@@ -376,8 +376,6 @@ See `docs/migrations/0.1.23.md`.
 - New `docs/long-running-agents.md`: hazards + 4 primitives + framework
   abstraction boundary.
 
-See `docs/migrations/0.1.22.md`.
-
 ## [0.1.21] - 2026-05-16
 
 - `[runtime] max_rounds = N` + `--max-rounds N` CLI flag: supervisor
@@ -388,8 +386,6 @@ See `docs/migrations/0.1.22.md`.
   `systemctl start` to resume.
 - 2 new events: `max_rounds_reached`, `stop_file_detected`.
 
-See `docs/migrations/0.1.21.md`.
-
 ## [0.1.20] - 2026-05-16
 
 - Built-in detection of claude rate-limit rejections (5h OAuth quota).
@@ -402,8 +398,6 @@ See `docs/migrations/0.1.21.md`.
 - `peek --json` schema bumped 1.8 → 1.9 (additive `rate_limit` field).
 - New monitor detector `rate_limit_active` (warning, no auto-stop).
 
-See `docs/migrations/0.1.20.md`.
-
 ## [0.1.19] - 2026-05-15
 
 - `agent-runner install` derives `ExecStart` via `shutil.which`; fixes
@@ -415,15 +409,12 @@ See `docs/migrations/0.1.20.md`.
 - New `gemini` preset: `agent-runner init --preset gemini` scaffolds
   for Gemini CLI (uses `--yolo` for unattended operation).
 
-See `docs/migrations/0.1.19.md`.
-
 ## [0.1.18] - 2026-05-15
 
 ### ⚠️ Breaking
 
 - `vcs.orphan_action` removed (deprecated in 0.1.17). TOML using the
   old key raises `ValueError` with migration hint. Use `vcs.dirty_action`.
-  See `docs/migrations/0.1.17.md`.
 
 ## [0.1.17] - 2026-05-15
 
@@ -436,13 +427,11 @@ See `docs/migrations/0.1.19.md`.
 - New round subprocess env vars `AGENT_RUNNER_ROUND_NUM` and
   `AGENT_RUNNER_PHASE`.
 
-See `docs/migrations/0.1.17.md`.
-
 ## [0.1.16] - 2026-05-14
 
 ### ⚠️ Breaking changes
 
-- **`runtime.round_timeout_per_phase` dict syntax removed**. Use `[phases.<name>] round_timeout_s = X` sub-table instead. Migration recipe in `docs/migrations/0.1.16.md`. Rationale: the dict syntax scaled poorly (N² as more per-phase fields would land); the sub-table is a one-time generalization that accommodates any per-phase field including the new `prompt.files`.
+- **`runtime.round_timeout_per_phase` dict syntax removed**. Use `[phases.<name>] round_timeout_s = X` sub-table instead. Rationale: the dict syntax scaled poorly (N² as more per-phase fields would land); the sub-table is a one-time generalization that accommodates any per-phase field including the new `prompt.files`.
 - **`Config.phases` type changed** from `list[str] | None` to `PhasesConfig` dataclass with `.list: list[str] | None` and `.overrides: dict[str, PhaseOverride]`. Code reading `cfg.phases` as a list directly must update to `cfg.phases.list`. Internal callers and plugins are advised to check this access pattern.
 
 ### Added
@@ -456,7 +445,7 @@ See `docs/migrations/0.1.17.md`.
 
 ### Migration notes
 
-- Replace `runtime.round_timeout_per_phase = { dev = 3600, qa = 900 }` with `[phases.dev] round_timeout_s = 3600` + `[phases.qa] round_timeout_s = 900` sub-tables. See `docs/migrations/0.1.16.md` for full recipe.
+- Replace `runtime.round_timeout_per_phase = { dev = 3600, qa = 900 }` with `[phases.dev] round_timeout_s = 3600` + `[phases.qa] round_timeout_s = 900` sub-tables.
 - Code reading `cfg.phases` (e.g. iterating phase names) must update to `cfg.phases.list`.
 - `prompt.file = "x.md"` continues to work unchanged; no migration required unless adopting multi-file concat.
 

cli_agent_runner-0.2.10/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing to agent-runner
+
+Thanks for your interest in contributing!
+
+## Development setup
+
+```bash
+git clone https://github.com/wan9yu/cli-agent-runner.git
+cd cli-agent-runner
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+./build.sh check
+```
+
+`./build.sh check` runs the full local-CI sweep: ruff (lint + format), unit
++ integration tests, the literate quickstart, and the docs CI gate. It's
+what GitHub Actions runs on every push and PR.
+
+## Workflow
+
+1. Open an issue first for non-trivial changes — saves wasted work on both sides.
+2. Branch off `main`. Keep PRs focused; one logical change per PR.
+3. **TDD encouraged**: write the failing test first, then the implementation.
+4. Every public API change needs a home for each new fact — see
+   [Where does this fact go?](#where-does-this-fact-go) below.
+5. Run `./build.sh check` locally before pushing.
+6. Conventional Commits: `feat:` / `fix:` / `docs:` / `refactor:` / `test:` /
+   `chore:` / `ci:` / `build:` / `perf:`. Subjects in English, imperative mood.
+   CI (`lint-commits` job) and `tests/invariants/test_no_ai_signatures.py`
+   reject auto-generated trailers and robot signatures — keep messages
+   human-authored.
+
+## Where does this fact go?
+
+Before you write a sentence into a doc, run it through these four questions in
+order. The first one that matches is the fact's home — put it there and nowhere
+else. This is mechanical: a contributor (or an AI) should reach the same answer
+without judgment.
+
+1. **Is it enumerable/mechanical?** A default, enum, flag, count, schema,
+   transform, or preset. → It lives in **code as data**. The doc gets a
+   `gen:` block that renders it (see the generated regions in `docs/*.md`,
+   filled by `./build.sh docs`) or it gets nothing. Never hand-copy the value
+   into prose.
+
+2. **Is it a behavioral claim?** "X happens when Y." → It lives in a **test**.
+   The doc may name that test — the path is data, and a named test that goes
+   red is a self-correcting reference. Prose that asserts behavior no test
+   pins is a claim waiting to rot.
+
+3. **Is it judgment, rationale, or narrative?** Why a design is the way it is,
+   a trade-off, a walkthrough. → It's **authored prose**; write it. If that
+   prose must name an owned fact (e.g. a config default) to make its point,
+   declare it inline with `<!-- authored: reason; SSOT <source> -->` so the
+   mention is a reviewed choice, not silent drift.
+
+4. **None of the above?** → **Delete it.** A fact with no home is upkeep with
+   no reader.
+
+The corollary: **a fact stated twice is a bug with a delay timer.** The two
+copies will diverge; the only question is when. Derive one from the other, or
+delete one.
+
+This isn't only convention. `tests/invariants/test_authored_facts_declared.py`
+enforces (1) and (3) for config defaults today: a known config field named
+alongside a default literal in prose fails the gate unless it carries an
+`<!-- authored: reason -->` declaration. The linter's scope grows over time —
+more owned facts, more of this procedure, mechanically enforced.
+
+## Migration docs
+
+Migration guidance is primarily the executable `agent-runner migrate` command
+(which rewrites removed/renamed config fields — its transform list is generated
+into `docs/commands.md` from the registry) plus `CHANGELOG.md`. Between them
+they carry a config rewrite and per-version notes; a doc that only restates the
+changelog is upkeep with no reader.
+
+`docs/migrations/0.2.md` is the one surviving guide: it collects the few manual
+steps a config rewrite can't do (recovery procedures, a systemd regen, a mode
+switch). Keep the relevant CHANGELOG entries terse and link it
+(`See docs/migrations/0.2.md.`).
+
+Migration guides are **not** append-only. A per-version guide is pruned once its
+content becomes executable (`migrate`), generated (the transform list),
+consolidated (into `0.2.md`), or purely archival — its live referrers retargeted
+in the same change so no dead pointer remains. When you consolidate, correct a
+carried-over step in place rather than preserving the original wording.
+
+## Architecture / docs
+
+- [`docs/architecture.md`](docs/architecture.md) — 3-layer model, defenses-as-data.
+- [`docs/commands.md`](docs/commands.md) — verb reference.
+- [`docs/configuration.md`](docs/configuration.md) — TOML schema.
+
+The defenses table, detector list, event kinds, config schema, and verb
+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`
+- Literate quickstart: `./build.sh literate`
+- Pi e2e (opt-in): `AGENT_RUNNER_E2E_PI=1 pytest tests/e2e/` (needs a `pi`
+  ssh alias; not run in CI).
+
+## Code of conduct
+
+Project follows the [Contributor Covenant v2.1](CODE_OF_CONDUCT.md). Be kind.
+
+## Reporting security issues
+
+Please **don't** open public issues for security problems — see
+[SECURITY.md](SECURITY.md).

{cli_agent_runner-0.2.8 → cli_agent_runner-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.8
+Version: 0.2.10
 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
@@ -128,24 +128,17 @@ agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-Watch a remote host's event stream from your laptop — one command instead of a
-hand-rolled `ssh … ; sleep` loop:
+Watch a remote host's event stream from your laptop with a managed ssh relay —
+one command instead of a hand-rolled `ssh … ; sleep` loop:
 
 ```bash
 agent-runner monitor --host pi --mode events   # managed ssh relay, JSONL stdout
 ```
 
-The relay reconnects with `--since <last ts>` so a dropped link replays its gap,
-gives up (exit 1) once the outage passes `remote_failure_tolerance_s`, and kills
-the ssh process group on exit so no orphan tree is left behind.
-
-> **Detection stays on the host.** `--host` with `--mode anomaly | narrate |
-> http` exits with an error: the detectors read the supervised host's logs and
-> auto-stop its service, which must keep working with your laptop closed. Run
-> the monitor there (`ssh <alias>`, then `agent-runner monitor`) and relay its
-> events here. See [`docs/runbook.md`](docs/runbook.md) § "Remote event relay &
-> SSH trust" — the SSH trust boundary applies to any agent-runner command you
-> drive over ssh.
+Detection stays on the host: `--host` with `--mode anomaly | narrate | http`
+exits with an error, since the detectors and auto-stop must keep working with
+your laptop closed. Full relay + SSH-trust mechanics:
+[`docs/runbook.md`](docs/runbook.md) § "Remote event relay & SSH trust".
 
 ## Documentation
 

{cli_agent_runner-0.2.8 → cli_agent_runner-0.2.10}/README.md

@@ -92,24 +92,17 @@ agent-runner monitor                  # 30s poll
 agent-runner monitor --json | jq -c   # pipe to downstream consumers
 ```
 
-Watch a remote host's event stream from your laptop — one command instead of a
-hand-rolled `ssh … ; sleep` loop:
+Watch a remote host's event stream from your laptop with a managed ssh relay —
+one command instead of a hand-rolled `ssh … ; sleep` loop:
 
 ```bash
 agent-runner monitor --host pi --mode events   # managed ssh relay, JSONL stdout
 ```
 
-The relay reconnects with `--since <last ts>` so a dropped link replays its gap,
-gives up (exit 1) once the outage passes `remote_failure_tolerance_s`, and kills
-the ssh process group on exit so no orphan tree is left behind.
-
-> **Detection stays on the host.** `--host` with `--mode anomaly | narrate |
-> http` exits with an error: the detectors read the supervised host's logs and
-> auto-stop its service, which must keep working with your laptop closed. Run
-> the monitor there (`ssh <alias>`, then `agent-runner monitor`) and relay its
-> events here. See [`docs/runbook.md`](docs/runbook.md) § "Remote event relay &
-> SSH trust" — the SSH trust boundary applies to any agent-runner command you
-> drive over ssh.
+Detection stays on the host: `--host` with `--mode anomaly | narrate | http`
+exits with an error, since the detectors and auto-stop must keep working with
+your laptop closed. Full relay + SSH-trust mechanics:
+[`docs/runbook.md`](docs/runbook.md) § "Remote event relay & SSH trust".
 
 ## Documentation
 

{cli_agent_runner-0.2.8 → cli_agent_runner-0.2.10}/agent_runner/_docgen.py

@@ -156,6 +156,13 @@ def render_event_kinds_list() -> str:
     return "\n".join(f"- `{k}`" for k in sorted(KNOWN_EVENT_KINDS))
 
 
+def _render_migrate_transforms() -> str:
+    """Bullet list of the transforms `agent-runner migrate` applies, from the registry."""
+    from agent_runner.migrations import MIGRATIONS
+
+    return "\n".join(f"- {m.describe}" for m in MIGRATIONS)
+
+
 def _subparser_action() -> argparse.Action:
     """The single ``_SubParsersAction`` on the top-level parser."""
     from agent_runner.cli import _build_parser
@@ -227,20 +234,50 @@ def _render_preset(name: str) -> str:
     return "```toml\n" + body.rstrip() + "\n```"
 
 
-RENDERERS: dict[str, Callable[[], str]] = {
-    "defenses-table": render_defenses_table,
-    "detector-list": render_detector_list,
-    "event-kinds": render_event_kinds_list,
-    "config-schema": render_config_schema_table,
-    "verb-table": render_verb_table,
+class Renderer(typing.NamedTuple):
+    """A gen block's renderer paired with the code SSOT it renders from.
+
+    Source lives beside the callable at the registration site — the same paired
+    shape as ``_SECTIONS`` — so a block can never exist without declaring its
+    provenance; the gap is unrepresentable, not caught at render time.
+    """
+
+    fn: Callable[[], str]
+    source: str
+
+
+RENDERERS: dict[str, Renderer] = {
+    "defenses-table": Renderer(render_defenses_table, "agent_runner/defenses.py catalog()"),
+    "detector-list": Renderer(
+        render_detector_list,
+        "agent_runner/monitor.py KNOWN_ALERT_KINDS / AUTO_STOP_ALERTS",
+    ),
+    "event-kinds": Renderer(render_event_kinds_list, "agent_runner/events.py KNOWN_EVENT_KINDS"),
+    "config-schema": Renderer(render_config_schema_table, "agent_runner/config.py dataclasses"),
+    "verb-table": Renderer(render_verb_table, "agent_runner/cli argparse subparsers"),
+    "migrate-transforms": Renderer(
+        _render_migrate_transforms, "agent_runner/migrations.py MIGRATIONS"
+    ),
 }
 RENDERERS.update(
     {
-        f"flags-{v}": functools.partial(_render_verb_flags, v)
+        f"flags-{v}": Renderer(
+            functools.partial(_render_verb_flags, v),
+            f"agent_runner/cli {v} argparse flags",
+        )
         for v in ("init", "monitor", "serve", "migrate")
     }
 )
-RENDERERS.update({f"preset-{n}": functools.partial(_render_preset, n) for n in _preset_names()})
+RENDERERS.update(
+    {
+        f"preset-{n}": Renderer(
+            functools.partial(_render_preset, n),
+            f"agent_runner/presets/{n}.toml",
+        )
+        for n in _preset_names()
+    }
+)
+
 
 _GEN_OPEN = re.compile(r"<!-- gen:([a-z0-9-]+) -->")
 
@@ -264,8 +301,10 @@ def render(docs_dir: Path, *, write: bool = True) -> dict[Path, str]:
                 raise ValueError(
                     f"{md.name}: unknown gen marker {name!r} — valid names: {sorted(RENDERERS)}"
                 )
+            r = RENDERERS[name]
             try:
-                text = replace_block(text, name, RENDERERS[name]())
+                body = f"<!-- source: {r.source} -->\n{r.fn()}"
+                text = replace_block(text, name, body)
             except ValueError as e:
                 raise ValueError(f"{md.name}: {e}") from e
         out[md] = text