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

cli_agent_runner-0.2.22/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 2
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
           # PR: scan only new commits the PR introduces (base..head).
           # Push to main: scan the just-pushed commits (before..after).
@@ -74,10 +74,10 @@ jobs:
     # granularity AND because coverage requires extra pytest flags not in
     # the local `test` task. CONTRIBUTING.md states the parity intentionally.
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: ${{ matrix.python }}
           cache: pip
@@ -108,7 +108,7 @@ jobs:
         run: pytest tests/literate/ -q
       - name: upload coverage
         if: matrix.python == '3.12' && matrix.os == 'ubuntu-latest'
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v6
         with:
           files: ./coverage.xml
           fail_ci_if_error: false

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/.github/workflows/release.yml

@@ -26,10 +26,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
         with:
           python-version: "3.12"
       - name: install build
@@ -38,7 +38,7 @@ jobs:
         run: python -m build
       - name: list dist artifacts
         run: ls -la dist/
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           name: dist
           path: dist/
@@ -53,11 +53,15 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v8
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      # SHA-pinned to release/v1's composite. NOTE: this pins the composite source;
+      # the image it pulls is still referenced by a moving ghcr tag, so a full pin
+      # would require the ghcr digest — deferred (needs read:packages + release-time
+      # validation). dependabot (github-actions) bumps this SHA.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
         with:
           attestations: true
 
@@ -68,8 +72,8 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/download-artifact@v8
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: dist
           path: dist/

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

@@ -110,6 +110,7 @@ pid
 uptime_s
 unit_file
 rate_limit
+system_managed
 
 # agent_runner.api_types.SystemMetrics
 mem_total_mb

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/BACKLOG.md

@@ -53,18 +53,6 @@ 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
@@ -89,21 +77,6 @@ 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.
 
-## `_monitor_loop_iter`'s three fail-open guards are hand-duplicated
-
-`api._monitor_loop_iter` wraps the startup `monitor_started` emit, the
-per-tick poll, and `on_alert`'s per-alert dispatch each in its own
-`try/except Exception: warnings.warn(...)` block so a crash in any one of the
-three never ends monitor supervision. The three guards are structurally
-identical (catch, format a `type(e).__name__: {e}` warning, keep the loop
-alive) but hand-copied rather than sharing one implementation; `on_alert`'s
-own `emit()` closure already shows the pattern for factoring a shared guard.
-
-Collapsing them to one shared guard is behavior-preserving — it must not
-change which failures warn vs which propagate, nor the specific fallback
-each site takes on failure (sleep-and-retry after a poll failure,
-`verdict = "failed"` after an `on_alert` failure). Slated for 0.2.19.
-
 ## `oom_kill_delta` is named differently on its two events — NEEDS_DESIGN, DEFERRED to 0.3
 
 The same cgroup `memory.events.oom_kill` delta is emitted under two

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.22] - 2026-09-11
+
+### Fixed
+- Container safety: agent-runner now refuses to boot when `runtime.log_dir` resolves inside a containerized `work_dir` — a contained agent could otherwise rewrite the pid/lock/cidfile control files the supervisor trusts. The best-effort container stop also validates the recovered container id (hex, length-bounded) and passes an end-of-options separator, and the injected `--cidfile` moves to a host-private directory, so a poisoned cidfile can no longer stop an unrelated container.
+- `kill` / `restart --force` verify the lock-holder's start time before signaling, so a recycled pid is never sent a signal.
+- System mode (`install --system`): `restart` / `uninstall` recognize a system unit and refuse with the exact `sudo systemctl …` command instead of a misleading one, and `uninstall` no longer aborts with an uncaught error on a host without a systemd user bus.
+
+### Security
+- Release and CI GitHub Actions are pinned to commit SHAs, with Dependabot tracking updates.
+
+### Notes
+- Not breaking: no `agent-runner migrate` step, no systemd unit change. `status --json` gains a `system_managed` field; existing fields unchanged. The one newly-rejected configuration is a containerized agent whose `runtime.log_dir` sits inside `work_dir` — move `log_dir` outside `work_dir` (the default already is).
+
 ## [0.2.21] - 2026-09-11
 
 ### Added

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

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

@@ -57,6 +57,23 @@ 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.
 
+**Residual: `agent-runner.toml` lives inside the mount.** The startup check
+above stops the agent's pid and lock files from sitting inside a mounted
+`work_dir` (the injected cidfile is separately placed in a host-private temp
+dir outside any mount, so it's protected independently of `log_dir`) — but
+`agent-runner.toml` itself is scaffolded at the `work_dir` root, and the
+container recipes in
+[docs/recipes/container-pi.md](docs/recipes/container-pi.md) bind-mount all
+of `work_dir` read-write. Each round re-reads the config, so a containerized
+agent that can write its own mount can rewrite `[agent] command` /
+`exec_prefix` — or `runtime.stop_file`, if it's pointed inside the mount —
+and have it run on the host next round. This is consistent with the threat
+model above: agent-runner bounds a *misbehaving* agent, not a *hostile* one,
+and containment is the container/VM's job, not agent-runner's. An operator
+who needs to contain a not-fully-trusted agent should keep the config (and
+`runtime.stop_file`) outside any bind-mount, or otherwise treat the
+container boundary as their own responsibility to shape.
+
 ## Scope
 
 In scope: the `agent_runner` Python package, its CLI, its bundled systemd

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/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.21'
-__version_tuple__ = version_tuple = (0, 2, 21)
+__version__ = version = '0.2.22'
+__version_tuple__ = version_tuple = (0, 2, 22)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/agent_runtime.py

@@ -14,6 +14,7 @@ import re
 import shutil
 import signal
 import subprocess  # noqa: TID251 — sanctioned subprocess caller
+import tempfile
 import threading
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -290,6 +291,14 @@ def resolve_exec_target(command0: str, work_dir: Path, env_path: str | None = No
 # ladder) is out of scope here -- left for a future release.
 _CONTAINER_RUNTIMES = frozenset({"docker", "podman"})
 
+# A real docker/podman container id is hex, 12-64 chars (short or full form).
+# The cidfile is a trust-bearing control input -- validated before it's ever
+# handed to a `stop` subprocess argv.
+_CONTAINER_ID_RE = re.compile(r"^[0-9a-fA-F]{12,64}$")
+# A real container id is <=64 hex chars; cap the read so a poisoned giant
+# file can't OOM a constrained host.
+_CIDFILE_READ_CAP = 128
+
 # docker/podman GLOBAL flags (before the subcommand) that take a separate
 # value token -- skipped in pairs so `docker -H unix:///var/run/docker.sock
 # run ...` / `docker --context foo run ...` still resolve to `run`. Not
@@ -507,14 +516,18 @@ def _best_effort_container_stop(
     if cidfile is None:
         return None, None
     try:
-        cid = cidfile.read_text(encoding="utf-8").strip()
+        with cidfile.open("rb") as fh:
+            raw = fh.read(_CIDFILE_READ_CAP + 1)
     except OSError:
         return None, None
-    if not cid:
-        return None, None
+    if len(raw) > _CIDFILE_READ_CAP:
+        return None, None  # oversize — not a real container id
+    cid = raw.decode("utf-8", "replace").strip()
+    if not _CONTAINER_ID_RE.match(cid):
+        return None, None  # not a hex id — detection already fired the loud warn + event
     try:
         result = subprocess.run(
-            [runtime, "stop", "-t", str(REAP_GRACE_S), cid],
+            [runtime, "stop", "-t", str(REAP_GRACE_S), "--", cid],
             stdout=subprocess.DEVNULL,
             stderr=subprocess.PIPE,
             timeout=_CONTAINER_STOP_TIMEOUT_S,
@@ -606,6 +619,11 @@ def run(
     attempt where covered; it just isn't reported).
     """
     stdin_mode = prompt_delivery == "stdin"
+    # Raising work (mkdir can fail on disk-full/perms/removed log_dir) must
+    # happen BEFORE the container-detection block below creates the
+    # host-private cidfile tempdir -- otherwise a raise here would skip the
+    # try/finally that cleans that tempdir up, leaking it once per round.
+    log_path.parent.mkdir(parents=True, exist_ok=True)
     # Container-orphan defense: detect BEFORE building argv (spawn_command may
     # gain an injected --cidfile) -- see _detect_container_run's module-level
     # note. A non-container command's argv is byte-identical to before:
@@ -638,8 +656,13 @@ def run(
                 # no-silent-orphan floor.
                 pass
             else:
-                container_cidfile = log_path.with_name(log_path.name + ".cid")
-                container_cidfile.unlink(missing_ok=True)  # docker/podman refuse an existing one
+                # A supervisor control file must not live where the container can
+                # write it; put our injected cidfile in a host-private 0700 dir
+                # outside any mount. Docker writes the file host-side; the
+                # container never needs it.
+                container_cid_dir = Path(tempfile.mkdtemp(prefix="agent-runner-cid-"))
+                # Not created here — docker/podman refuse an existing cidfile.
+                container_cidfile = container_cid_dir / "round.cid"
                 container_cidfile_is_ours = True
                 spawn_command = _inject_cidfile(command, run_idx, container_cidfile)
 
@@ -669,7 +692,6 @@ def run(
     # PWD pinned last — it mirrors cwd= (a correctness pin, not a knob), so
     # an [agent.env] PWD cannot silently diverge from where the child runs.
     env = {**os.environ, **env_extra, "PWD": str(work_dir)}
-    log_path.parent.mkdir(parents=True, exist_ok=True)
     proc: subprocess.Popen | None = None
     log_file = None
     try:
@@ -805,10 +827,10 @@ def run(
     finally:
         if log_file is not None:
             log_file.close()
-        # Cleanup, not correctness: our own injected cidfile is a tiny,
-        # round-scoped tmp file -- delete it once the round is fully done
-        # (read-back for the best-effort stop, if any, already happened
-        # above). Only ours: an operator-supplied --cidfile is never ours to
-        # delete.
+        # Cleanup, not correctness: our own injected cidfile lives in a tiny,
+        # round-scoped private tempdir -- remove that whole dir once the round
+        # is fully done (read-back for the best-effort stop, if any, already
+        # happened above). Only ours: an operator-supplied --cidfile is never
+        # ours to delete.
         if container_cidfile_is_ours and container_cidfile is not None:
-            container_cidfile.unlink(missing_ok=True)
+            shutil.rmtree(container_cidfile.parent, ignore_errors=True)

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/api.py

@@ -193,6 +193,11 @@ def init(
 _SYSTEM_UNITS_DIR = Path("/etc/systemd/system")
 
 
+def _system_unit_exists(project: str) -> bool:
+    """A --system install's root-owned unit; detect_service_mode can't see it (user-scope only)."""
+    return (_SYSTEM_UNITS_DIR / serve_unit_filename(project)).exists()
+
+
 def _install_system(
     cfg: Config, project: str, *, config_path: Path, with_monitor: bool
 ) -> InstallResult:
@@ -283,6 +288,15 @@ def uninstall(work_dir: Path | None = None) -> bool:
     if work_dir is None:
         work_dir = Path.cwd()
     project = _project_name(work_dir)
+    if _system_unit_exists(project):  # root-owned -- don't silently no-op the user-scope dir
+        units = [serve_unit_filename(project)]
+        if (_SYSTEM_UNITS_DIR / monitor_unit_filename(project)).exists():
+            units.append(monitor_unit_filename(project))
+        remedy = " && ".join(
+            f"sudo systemctl disable --now {u} && sudo rm {_SYSTEM_UNITS_DIR / u}" for u in units
+        )
+        print(f"{project} is managed by a system unit; run: {remedy}")
+        return False
     units_dir = lifecycle._user_systemd_dir()
     serve = units_dir / serve_unit_filename(project)
     monitor = units_dir / monitor_unit_filename(project)
@@ -295,7 +309,10 @@ def uninstall(work_dir: Path | None = None) -> bool:
             lifecycle.stop_unit_draining(p.name, clock=SYSTEM_CLOCK, confirm_s=_PID_SIGNAL_GRACE_S)
             _systemctl_user("disable", p.name)
             p.unlink(missing_ok=True)
-    _systemctl_user("daemon-reload")
+    try:
+        _systemctl_user("daemon-reload")
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass  # no user bus on this host -- units above (if any) already gone
     return True
 
 
@@ -340,6 +357,8 @@ def _round_holder_pid(log_dir: Path) -> int | None:
     alive. This is the ONLY way ``kill()`` can reach an in-flight round: the
     round is ``start_new_session=True`` (its own session, its own pgid), so it
     sits outside whatever process group serve itself belongs to."""
+    import psutil
+
     from agent_runner.context_store import read_json
 
     data = read_json(log_dir / "agent-runner.lock.holder")
@@ -348,7 +367,17 @@ def _round_holder_pid(log_dir: Path) -> int | None:
     pid = data.get("pid")
     if not lifecycle._valid_pid(pid):
         return None
-    return pid if pid_alive(pid) else None
+    if not pid_alive(pid):
+        return None
+    recorded = data.get("create_time")
+    if recorded is None:
+        return pid  # legacy sidecar without a token: best-effort, mirrors serve.pid's read
+    try:
+        if abs(psutil.Process(pid).create_time() - recorded) < 1.0:
+            return pid
+    except psutil.Error:
+        return None
+    return None  # recorded create_time != live process: a recycled pid, do not signal it
 
 
 def _terminate_round_pid(pid: int) -> None:
@@ -435,6 +464,11 @@ def restart(project: str | Path, *, force: bool = False) -> ServiceStatus:
     # SYSTEMD_USER unit, so restarting a PID_FILE/NONE service would stop it and
     # never bring it back — the half-execution this fix eliminates.
     pname = _resolve_project(project)
+    if _system_unit_exists(pname):  # root-owned -- below's message would mislead
+        raise RuntimeError(
+            f"{pname} is managed by a system unit; run: "
+            f"sudo systemctl restart {serve_unit_filename(pname)}"
+        )
     log_dir = _log_dir_for_project(project)
     mode = detect_service_mode(pname, log_dir=log_dir)
     if mode != ServiceMode.SYSTEMD_USER:
@@ -463,14 +497,18 @@ def status(project: str | Path) -> ServiceStatus:
     pname = _resolve_project(project)
     log_dir = _log_dir_for_project(project)
     mode = detect_service_mode(pname, log_dir=log_dir)
-    if mode == ServiceMode.PID_FILE:
-        pid = PIDFile(log_dir / "serve.pid").read()
-        return ServiceStatus(mode=mode, active=pid is not None and pid_alive(pid), pid=pid)
     if mode == ServiceMode.SYSTEMD_USER:
         unit = lifecycle._user_systemd_dir() / serve_unit_filename(pname)
         active = _systemd_active(serve_unit_filename(pname), log_dir)
         return ServiceStatus(mode=mode, active=active, unit_file=unit)
-    return ServiceStatus(mode=ServiceMode.NONE, active=False)
+    # detect_service_mode only sees the user-scope unit dir; label a --system
+    # install found here (PID_FILE/NONE) via system_managed, not unit_file.
+    system_managed = _system_unit_exists(pname)
+    if mode == ServiceMode.PID_FILE:
+        pid = PIDFile(log_dir / "serve.pid").read()
+        active = pid is not None and pid_alive(pid)
+        return ServiceStatus(mode=mode, active=active, pid=pid, system_managed=system_managed)
+    return ServiceStatus(mode=ServiceMode.NONE, active=False, system_managed=system_managed)
 
 
 def _resolve_target(project: str | Path | None) -> tuple[str, Path]:

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/api_types.py

@@ -62,6 +62,11 @@ class ServiceStatus:
     uptime_s: float | None = None
     unit_file: Path | None = None
     rate_limit: RateLimitState | None = None
+    # True when a `--system` install's root-owned unit owns this project but
+    # detect_service_mode fell through to PID_FILE/NONE (it only sees the
+    # user-scope unit dir) -- distinct from `unit_file`, which stays the
+    # live, user-owned, CLI-restartable systemd_user unit's path.
+    system_managed: bool = False
 
 
 @dataclass(frozen=True)

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/defenses.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from agent_runner import events
+from agent_runner import events, startup_check
 from agent_runner.config import Config
 
 
@@ -29,6 +29,7 @@ class Defense:
 
 def catalog(cfg: Config) -> list[Defense]:
     """Return the defense catalog parameterised by current config."""
+    check_kinds = startup_check.all_check_kinds()
     return [
         Defense(
             name="round_timeout_s",
@@ -89,7 +90,10 @@ def catalog(cfg: Config) -> list[Defense]:
         ),
         Defense(
             name="startup_smoke_check",
-            value="6 checks (config / log_dir / agent_cli / git / prompt_file / prompt_smoke)",
+            # Computed from startup_check.all_check_kinds() -- the battery's
+            # own SSOT -- so this count/list can't drift from the real boot
+            # battery the way the hand-written "6 checks" string once did.
+            value=f"{len(check_kinds)} checks ({' / '.join(check_kinds)})",
             codifies=(
                 "R721 + #446 — _common.md frontmatter caused 4h/123-round silent burn; "
                 "now halts serve (config_broken) instead of respawning a broken config"

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/runner.py

@@ -78,6 +78,12 @@ def _write_holder_sidecar(lock_path: Path) -> None:
         "started_at": now_iso_ms(),
         "cmdline": _read_cmdline(os.getpid()),
     }
+    import psutil
+
+    try:
+        payload["create_time"] = psutil.Process(os.getpid()).create_time()
+    except psutil.Error:
+        pass
     _holder_sidecar(lock_path).write_text(json.dumps(payload), encoding="utf-8")
 
 

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/agent_runner/startup_check.py

@@ -106,6 +106,33 @@ def _check_stdin_container_interactive(
     )
 
 
+def _check_control_plane_outside_container(
+    agent: AgentConfig, work_dir: Path, log_dir: Path, name: str
+) -> CheckResult:
+    """The supervisor's per-round pid and lock-holder files live under
+    log_dir. When the agent runs in a container and log_dir resolves inside
+    work_dir -- which the container mounts -- the agent could forge them;
+    refuse at boot. (The injected cidfile is kept safe separately, in a
+    host-private temp dir outside any mount.) Enforced on work_dir (the mount
+    we can reason about); exec_prefix's other mounts are opaque, so the
+    general rule is documented, not code-enforced."""
+    if agent_runtime._detect_container_run(agent.spawn_command(work_dir)) is None:
+        return CheckResult(name, True)
+    if log_dir.is_relative_to(work_dir):
+        return CheckResult(
+            name,
+            False,
+            reason="runtime.log_dir is inside work_dir, which the container mounts — "
+            "the agent could forge the pid/lock control files agent-runner trusts",
+            how_to_fix="set runtime.log_dir OUTSIDE work_dir (the default "
+            "~/.agent-runner/<project>/logs already is); agent-runner's "
+            "per-round pid and lock files live under log_dir, so keeping "
+            "log_dir outside the mount keeps them out of the agent's reach",
+            permanent=True,
+        )
+    return CheckResult(name, True)
+
+
 def _check_work_dir_is_git(cfg: Config) -> CheckResult:
     from agent_runner.vcs_state import GitTimeout, is_git_repo
 
@@ -205,6 +232,11 @@ CHECKS: list[Callable[[Config], CheckResult]] = [
 ]
 
 
+def _phase_qualified(base: str, phase: str | None) -> str:
+    """A check's name, suffixed `:<phase>` for an overriding phase profile."""
+    return base if phase is None else f"{base}:{phase}"
+
+
 def _agent_cli_checks(cfg: Config) -> list[CheckResult]:
     """Validate ``command[0]`` for EVERY profile the runner might launch — the
     base agent plus each phase's own agent — so a bad phase agent fails at boot
@@ -223,15 +255,24 @@ def _agent_cli_checks(cfg: Config) -> list[CheckResult]:
     results: list[CheckResult] = []
     for phase in [None, *overriding]:
         profile = cfg.profile_for(phase)
-        name = "agent_cli_in_path" if phase is None else f"agent_cli_in_path:{phase}"
-        results.append(_check_agent_target(profile.agent, cfg.runtime.work_dir, name))
-        stdin_name = (
-            "stdin_container_interactive"
-            if phase is None
-            else f"stdin_container_interactive:{phase}"
+        work_dir = cfg.runtime.work_dir
+        results.append(
+            _check_agent_target(
+                profile.agent, work_dir, _phase_qualified("agent_cli_in_path", phase)
+            )
+        )
+        results.append(
+            _check_stdin_container_interactive(
+                profile.agent, work_dir, _phase_qualified("stdin_container_interactive", phase)
+            )
         )
         results.append(
-            _check_stdin_container_interactive(profile.agent, cfg.runtime.work_dir, stdin_name)
+            _check_control_plane_outside_container(
+                profile.agent,
+                work_dir,
+                cfg.runtime.log_dir,
+                _phase_qualified("control_plane_outside_container", phase),
+            )
         )
     return results
 
@@ -254,6 +295,33 @@ def _phase_prompt_checks(cfg: Config) -> list[CheckResult]:
     return results
 
 
+def all_check_kinds() -> tuple[str, ...]:
+    """Static kind-names ``run_battery`` can emit, ``:<phase>`` suffix
+    stripped: the 5 base ``CHECKS`` names plus the 3 per-profile kinds
+    ``_agent_cli_checks`` adds (``agent_cli_in_path``,
+    ``stdin_container_interactive``, ``control_plane_outside_container``).
+    Per-phase prompt checks (``_phase_prompt_checks``) reuse
+    ``prompt_smoke_passes`` under a ``:<phase>`` suffix -- the same kind,
+    not a new one, so it is not listed twice.
+
+    Single source of truth for the defenses catalog's ``startup_smoke_check``
+    entry (see ``defenses.py``), so the human-readable count there is
+    computed from this instead of hand-copied and drifting; pinned against
+    the real battery by
+    ``test_all_check_kinds_should_match_battery_kinds_when_config_is_valid``.
+    """
+    return (
+        "config_loaded",
+        "log_dir_writable",
+        "work_dir_is_git_repo",
+        "prompt_file_exists",
+        "prompt_smoke_passes",
+        "agent_cli_in_path",
+        "stdin_container_interactive",
+        "control_plane_outside_container",
+    )
+
+
 def run_battery(cfg: Config) -> list[CheckResult]:
     """Run all checks. Returns empty list if escape hatch env is set."""
     if os.environ.get(ESCAPE_HATCH_ENV, "").lower() in ("1", "true", "yes", "on"):

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/docs/commands.md

@@ -65,11 +65,20 @@ Generate and install systemd user unit(s):
 - `--force`: overwrite a same-basename sibling project's unit (the clobber guard
   otherwise refuses, e.g. after moving/renaming a project directory).
 
-After writing, runs `systemctl --user daemon-reload`, `enable`, `start`.
+For the default (non-`--system`) path, after writing the unit(s) it runs
+`systemctl --user daemon-reload`, `enable`, `start`. The `--system` path runs
+the system-level `daemon-reload` and `enable` only, as noted above — it does
+not start the unit.
 
 ### `agent-runner uninstall`
 
-Stops and disables both units, then deletes the unit files and reloads systemd.
+Stops and disables both user units, then deletes the unit files and reloads
+systemd. A `--system`-installed unit is root-owned and out of reach here: this
+refuses instead, printing the `sudo systemctl disable --now ...` command for
+the serve unit (and the monitor unit too, if `--system --monitor` installed
+one) to run in its place. Never raises for a missing user bus either (the
+dietpi/RPi hosts `--system` is recommended for) — a failed `daemon-reload`
+there is harmless once the units are already gone.
 
 ### `agent-runner start | stop | kill | restart | status`
 
@@ -79,6 +88,11 @@ there:
 - `start` is idempotent.
 - `stop` waits up to `round_timeout_s` for the current round.
 - `kill` (and `restart --force`) is for a stuck round only — 5s grace then SIGKILL.
+- `restart` against a `--system`-installed unit refuses, printing the
+  `sudo systemctl restart ...` command to run instead (it manages user-scope
+  units only). `status` still reports it correctly — a `--system` install
+  sets `system_managed: true` on the result rather than misreporting it as a
+  `systemd_user`-mode service.
 
 ### `agent-runner round`
 

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/docs/recipes/container-pi.md

@@ -87,6 +87,22 @@ dirty-tree detector every round:
 -v /home/you/.pi-container-auth:/home/agent/.pi/agent:ro
 ```
 
+## Residual: the config file is inside the mount
+
+`-v {work_dir}:/work:Z` above mounts all of `work_dir` read-write, and
+`agent-runner.toml` is scaffolded at the `work_dir` root — so it's inside
+that mount too. agent-runner's own startup check keeps its pid and lock
+files out of a mounted `work_dir` (they live under `runtime.log_dir`,
+required to sit outside it — the injected cidfile is separately placed in a
+host-private temp dir outside any mount, protected independently of
+`log_dir`), but it does not and cannot protect the config file the same way:
+a containerized agent that can write
+its own mount can rewrite `[agent] command` / `exec_prefix` and have it run
+on the host next round. This is a residual of the supervisor-not-sandbox
+model (see [SECURITY.md](../../SECURITY.md#containment)), not something this
+recipe or agent-runner defends against — if you don't fully trust the agent,
+keep the config (and `runtime.stop_file`, if set) outside any bind-mount.
+
 ## Footguns
 
 These aren't enforced by agent-runner (`exec_prefix` is opaque) — get them

{cli_agent_runner-0.2.21 → cli_agent_runner-0.2.22}/docs/runbook.md

@@ -729,11 +729,13 @@ ssh -L 8765:127.0.0.1:8765 <pi-host>
 ### Going truly 24×7 (systemd)
 
 ```bash
-agent-runner install --config <toml>
-systemctl --user start agent-runner@<project>
-systemctl --user enable agent-runner@<project>  # restart on Pi reboot
+agent-runner install --monitor --config <toml>
 ```
 
+`install` already enables, starts, and (with `--monitor`) installs the
+auto-stop sidekick in one step — no separate `systemctl --user start/enable`
+needed.
+
 ## Supervision coverage on a 24/7 host
 
 Check this table before wrapping `[agent] command` in a shell script — most