cli-agent-runner 0.2.19__tar.gz → 0.2.21__tar.gz

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/.vulture-whitelist.py

@@ -133,6 +133,7 @@ prompt_arg_template
 name
 env
 prompt_delivery
+exec_prefix
 
 # agent_runner.config.models.Config
 agent

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/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.21] - 2026-09-11
+
+### Added
+- `[agent] exec_prefix`: an optional token list prepended to the agent command at spawn (with `{work_dir}` substituted), so the agent can run inside a container you supply (`docker`/`podman run …`) while agent-runner supervises the resulting process from outside. The agent's identity — throttle, crash-loop, usage plugins — still keys on `command`, unchanged.
+- Startup check: a stdin-delivery agent whose container `exec_prefix` omits `-i`/`--interactive` now fails loudly at boot instead of silently hanging until the round-timeout kill.
+- Docs: container recipes (`docs/recipes/container-pi.md`, with Kimi/Claude/rootless-podman deltas), an all-in-one deploy recipe (`deploy/` + `docs/recipes/deploy-all-in-one.md`), and a `SECURITY.md` containment section.
+
+### Fixed
+- The best-effort container stop no longer reports a false "stop failed" when a `--rm` container has already exited on its own; an already-removed container now counts as a successful stop.
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change.
+
+## [0.2.20] - 2026-09-09
+
+### Fixed
+- A supervised CLI's `setsid()`-detached descendant — outside the round leader's process group — is now killed at the hard-kill fallthrough instead of being left running, orphaned, after the round is torn down.
+- A configured `docker run`/`podman run` command (including `sudo`/`env`-wrapped and global-flag forms) escapes killpg-based termination and could previously outlive the round silently. It's now detected, agent-runner warns loudly and emits a `round_container_orphan_risk` event that the hard-wall can't guarantee stopping it, and best-effort-stops the container via an injected `--cidfile` for the plain (unwrapped, unflagged) form. Full container lifecycle management remains a later-release item.
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change.
+- `peek --json` gains the new `round_container_orphan_risk` event kind; existing kinds unchanged.
+
 ## [0.2.19] - 2026-09-09
 
 ### Changed

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.19
+Version: 0.2.21
 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.2.19 → cli_agent_runner-0.2.21}/SECURITY.md

@@ -37,6 +37,26 @@ 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.
 
+## Containment
+
+If you need to bound what the agent can reach, run it inside a container (or
+VM) you supply, via `[agent] exec_prefix` — see
+[docs/recipes/container-pi.md](docs/recipes/container-pi.md). The container
+(or VM) enforces the isolation; agent-runner still just watches the
+resulting process from outside, the same way it watches a bare agent
+process.
+
+One limit worth knowing: agent-runner's own process-tree defenses (reaping a
+hung round's descendants) only see processes in its own subtree, and a
+container-runtime-managed process usually isn't one of them. On a stuck
+round, the one remaining lever is stopping the container by the id
+agent-runner captured at spawn, which only works for a plain `docker
+run …`/`podman run …` invocation — not one wrapped in `sudo` or other global
+flags (see container-pi.md's footguns). Using a container this way gives you
+a narrower safety net than the host-level reaping a bare agent process gets,
+not a wider one — keep running it as a dedicated unprivileged user with no
+passwordless sudo and tight egress limits regardless.
+
 ## Scope
 
 In scope: the `agent_runner` Python package, its CLI, its bundled systemd

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/agent_runner/_emit/__init__.py

@@ -40,6 +40,7 @@ from agent_runner._emit.memory import (  # noqa: F401 — public re-export
 )
 from agent_runner._emit.rounds import (  # noqa: F401 — public re-export
     emit_fresh_eyes_round_triggered,
+    emit_round_container_orphan_risk,
     emit_round_grace_extended,
     emit_round_grace_kill,
     emit_round_logs_prune_deferred,
@@ -79,6 +80,7 @@ __all__ = [
     "emit_mem_pressure_deferred_to_cgroup",
     "emit_rate_limit_stop",
     "emit_round_cgroup_memory",
+    "emit_round_container_orphan_risk",
     "emit_round_deferred",
     "emit_round_grace_extended",
     "emit_round_grace_kill",

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/agent_runner/_emit/rounds.py

@@ -47,6 +47,42 @@ def emit_round_substrate_after(
     )
 
 
+def emit_round_container_orphan_risk(
+    log_dir: Path,
+    *,
+    round_num: int,
+    runtime: str,
+    container_id: str | None,
+    stop_ok: bool | None,
+) -> None:
+    """Emit when a round's configured command launches a container (`docker run`
+    / `podman run`) and the round had to be terminated: killpg-based
+    termination reaches the launcher process, not conmon/containerd's
+    double-fork-detached container itself, so the R1128 hard-wall cannot
+    guarantee the container stops. This event is the actual floor -- it must
+    never fire silently, regardless of whether the best-effort stop below
+    lands.
+
+    `container_id`/`stop_ok` describe the best-effort `<runtime> stop`
+    attempt made when an id was recoverable (an injected or pre-existing
+    `--cidfile`): `container_id` is None when no id could be recovered (no
+    stop was attempted, so `stop_ok` is also None); otherwise `stop_ok` is
+    whether that `stop` call exited zero. Full container lifecycle
+    management (cgroup delegation, a containment ladder) is out of scope
+    here -- left for a future release.
+    """
+    from agent_runner.events import ROUND_CONTAINER_ORPHAN_RISK, emit
+
+    emit(
+        log_dir,
+        ROUND_CONTAINER_ORPHAN_RISK,
+        round_num=round_num,
+        runtime=runtime,
+        container_id=container_id,
+        stop_ok=stop_ok,
+    )
+
+
 def emit_round_supervisor_wedged(
     log_dir: Path, *, pid: int, timeout_s: int, log_path: Path
 ) -> None:

{cli_agent_runner-0.2.19 → cli_agent_runner-0.2.21}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.19'
-__version_tuple__ = version_tuple = (0, 2, 19)
+__version__ = version = '0.2.21'
+__version_tuple__ = version_tuple = (0, 2, 21)
 
 __commit_id__ = commit_id = None