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

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.3}/.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.3}/.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.3/.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.3/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.3}/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.3] - 2026-07-26
+
+Details: [docs/migrations/0.2.3.md](docs/migrations/0.2.3.md)
+
+### Added
+- `--preset kimi` — a preset for [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) (`kimi -p --output-format stream-json`). `docs/recipes/kimi.md` also documents running Kimi K3 through the existing `claude` preset via Moonshot's Anthropic-compatible endpoint.
+- `--preset pi` — a preset for [Pi Coding Agent](https://github.com/earendil-works/pi) (`pi -p -na --mode json --model …`; `-na` pins project trust off for unattended runs). `docs/recipes/pi.md` documents driving Kimi K3 through pi via a Moonshot OpenAI-compatible provider.
+
+### Fixed
+- 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.
+
+## [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
@@ -363,7 +398,7 @@ See `docs/migrations/0.1.17.md`.
 
 ### Acknowledgements
 
-Argus Gateway's post-Q1-audit feedback (2026-05-14) surfaced the per-phase sub-table need (S3) and the multi-file prompt pattern (S1). Their R721 frontmatter-strip lesson informed making the (already-shipping) strip behavior an explicit opt-out config flag rather than hardcoded.
+A downstream integrator's post-Q1-audit feedback (2026-05-14) surfaced the per-phase sub-table need (S3) and the multi-file prompt pattern (S1). Their R721 frontmatter-strip lesson informed making the (already-shipping) strip behavior an explicit opt-out config flag rather than hardcoded.
 
 ## [0.1.15] - 2026-05-14
 
@@ -395,10 +430,10 @@ independent components bundled into one release because both serve the same
 
 ### Acknowledgements
 
-Two of six nice-to-have items surfaced in Argus Gateway's v0.1.12
+Two of six nice-to-have items surfaced in a downstream integrator's v0.1.12
 production-evaluation report (2026-05-14). An earlier scope also included
 per-phase runtime override; spec review caught that `runtime.round_timeout_per_phase`
-already covers Argus's stated need, so that component was deferred to a future
+already covers the integrator's stated need, so that component was deferred to a future
 release where a second per-phase field surfaces. Other items in the report
 (detector helper, hot-reload, replay) remain intentionally out of scope.
 
@@ -417,7 +452,7 @@ release where a second per-phase field surfaces. Other items in the report
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team — this release answers their imminent
+Thanks to our downstream integrators — this release answers their imminent
 production-deployment requirement for upgrade-without-disruption. After
 confirming round duration (10-40 min) fits within graceful-stop tolerance,
 this release scopes to round-boundary upgrade UX (Level 1). Mid-round
@@ -442,7 +477,7 @@ real production need.
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team for the deep v0.1.10 audit-session feedback
+Thanks to our downstream integrators for the deep v0.1.10 audit-session feedback
 (6 items, 3-round real-run testing on ARMv8 Pi). This release reframes those
 items into a coherent "Plugin & Operator Transparency" theme across three
 layers: transparency (see what plugins do), operator override (escape hatches
@@ -464,16 +499,16 @@ for audit/debug), and diagnostic quality (errors point at the next debug step).
 
 ### Migration notes
 
-- `Config.plugins` type change is breaking for any caller reading the field as a dict (`cfg.plugins.get("foo")`). Plugin authors using `[plugins.argus_*]`-style keys: read them from `cfg.plugins.raw.get("argus_*")` instead.
+- `Config.plugins` type change is breaking for any caller reading the field as a dict (`cfg.plugins.get("foo")`). Plugin authors using `[plugins.acme_*]`-style keys: read them from `cfg.plugins.raw.get("acme_*")` instead.
 - `LockHeldError` message format changed (now includes holder info: `"another agent-runner is holding /path (held by PID N, age Ns, cmd: ...)"` or stale/missing variants). Operators grepping the exact format string need to update.
-- For Argus's P5 confusion: see new `docs/architecture.md` section "Plugin injection: two paths" — `inject_context` and `disable_pre_round_hooks` are INDEPENDENT flags. Setting one does not affect the other.
+- For the integrator's P5 confusion: see new `docs/architecture.md` section "Plugin injection: two paths" — `inject_context` and `disable_pre_round_hooks` are INDEPENDENT flags. Setting one does not affect the other.
 - **Known limitation**: `[plugins] disable` removes named plugins from the hook / context-enricher / detector / event-kind registries, but does NOT remove a disabled plugin's owned VCS paths (the `register_plugin_owned_paths` registry has no name attribution today). Mostly inert. If this becomes a real issue, file a GitHub issue.
 
 ## [0.1.11] - 2026-05-13
 
 ### Acknowledgements
 
-Thanks again to the Argus Gateway team — this release closes the
+Thanks again to our downstream integrators — this release closes the
 network-resilience gap that 0.1.10's `MonitorRemoteError` propagation
 exposed, plus adds per-occurrence agent network blip observability requested
 during 0.1.10 handover review.
@@ -502,7 +537,7 @@ For network-related failures, the events index points at the diagnostic body:
 
 ### Acknowledgements
 
-Thanks to the Argus Gateway team for the Phase 4 second-pass production feedback that drove every change in this release. Six audit memos across 50 minutes of validated runtime surfaced four specific gaps; this release closes them.
+Thanks to our downstream integrators for the Phase 4 second-pass production feedback that drove every change in this release. Six audit memos across 50 minutes of validated runtime surfaced four specific gaps; this release closes them.
 
 ### Added
 
@@ -530,7 +565,7 @@ Thanks to the Argus Gateway team for the Phase 4 second-pass production feedback
 
 ### Acknowledgements
 
-Thanks to the argus-gateway team for the dev/qa/product wall-time data
+Thanks to our downstream integrators for the dev/qa/product wall-time data
 (Phase 4 feedback §3.1) that drove this API shape. Their three-role
 distribution made the case for per-phase overrides concrete.
 
@@ -556,7 +591,7 @@ documented plugin-author public surface.
 
 ### Acknowledgements
 
-Thanks to the argus-gateway team for Phase 4 dogfooding feedback that drove
+Thanks to our downstream integrators for Phase 4 dogfooding feedback that drove
 every item in this release. 3 audit memos (~90KB) silently swept into an
 orphan stash is a real-world failure mode; this release closes that loop.
 
@@ -585,7 +620,7 @@ orphan stash is a real-world failure mode; this release closes that loop.
 
 - Plugin outputs in plugin-declared paths (e.g. `proposals/`,
   `logs/plugins/my_plugin/`) no longer silently swept into orphan stashes
-  by `process_orphan_wip`. Previously: 90KB Argus audit memos invisible
+  by `process_orphan_wip`. Previously: 90KB audit memos invisible
   after Phase 4 round; required stash archaeology to recover.
 
 ### Migration
@@ -628,7 +663,7 @@ Or regenerate cleanly:
 agent-runner init --preset claude --force
 ```
 
-Plugin authors (Argus Gateway, etc.): no public API was renamed or removed
+Plugin authors (downstream integrators, etc.): no public API was renamed or removed
 from your import surface. The deleted symbols (`agent_runner.agent_runtime.CRITICAL_ENV_DEFAULTS`,
 `agent_runner.agent_runtime.merge_critical_envs`) were internal — not part of
 the documented plugin API. A new public-API contract test
@@ -859,7 +894,7 @@ Initial public release on PyPI as `cli-agent-runner`.
 
 ### Added
 - Three-layer model: Round / Loop / Witness.
-- 13 CLI verbs: `init`, `install`, `uninstall`, `start`, `stop`, `kill`,
+- 14 CLI verbs: `init`, `install`, `uninstall`, `start`, `stop`, `kill`,
   `cancel`, `restart`, `status`, `round`, `serve`, `peek`, `watch`, `monitor`.
 - 11 named defenses (round timeout, process group isolation, orphan stash
   with SHA lock, set-diff classification, smoke check, flock concurrency,
@@ -886,7 +921,10 @@ Initial public release on PyPI as `cli-agent-runner`.
 - Tag-triggered release publishing to PyPI via Trusted Publishing OIDC,
   gated by a manual approval on the `pypi` GitHub environment.
 
-[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/wan9yu/cli-agent-runner/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.42...v0.2.0
 [0.1.26]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.25...v0.1.26
 [0.1.25]: https://github.com/wan9yu/cli-agent-runner/compare/v0.1.24...v0.1.25

{cli_agent_runner-0.2.1 → cli_agent_runner-0.2.3}/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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.2.1
+Version: 0.2.3
 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, codewhale, kimi and pi; 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.3}/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, codewhale, kimi and pi; 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.3/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).