cli-agent-runner 0.2.20__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.20 → 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.20 → 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.20 → 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
@@ -133,6 +134,7 @@ prompt_arg_template
 name
 env
 prompt_delivery
+exec_prefix
 
 # agent_runner.config.models.Config
 agent

{cli_agent_runner-0.2.20 → 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.20 → cli_agent_runner-0.2.22}/CHANGELOG.md

@@ -5,6 +5,32 @@ 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
+- `[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.20
+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.22/SECURITY.md

@@ -0,0 +1,84 @@
+# Security policy
+
+## Supported versions
+
+The latest tagged release. We do not back-port security fixes to older versions.
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories:
+<https://github.com/wan9yu/cli-agent-runner/security/advisories/new>
+
+If GitHub Security Advisories is not workable for you, email
+`wangyu@go2imagination.com` with the subject line `agent-runner security`.
+
+Please **do not** open a public issue for security problems.
+
+## Response timeline
+
+- Acknowledgement within 3 business days.
+- An initial assessment within 7 business days.
+- A fix and coordinated disclosure timeline once the scope is understood.
+
+## Threat model
+
+agent-runner is a **supervisor**, not a sandbox. It provides observability
+(structured events, peek/watch/monitor) and lifecycle safety (round timeouts,
+process-group reaping, orphan stashing, auto-stop on critical alerts). It does
+**not** confine the agent process: the agent runs with the invoking user's full
+privileges and can read, write, and execute anything that user can.
+
+Prompt injection from untrusted repository content is unsolved and out of the
+supervisor's reach — a malicious file in the work tree can steer the agent, and
+no defense in this project prevents that.
+
+Operators supervising untrusted input should run the agent as a dedicated
+unprivileged user, inside a container or VM, without passwordless sudo, and
+with egress limits. The supervisor's defenses bound the blast radius of a
+*misbehaving* agent, not a *hostile* one.
+
+## 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.
+
+**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
+unit templates, and the CI / release workflows.
+
+Out of scope: vulnerabilities in dependencies (psutil, etc.) — please
+report those upstream. Misconfiguration of a downstream deployment is also
+out of scope unless agent-runner's defaults caused it.

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

{cli_agent_runner-0.2.20 → 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
@@ -26,6 +27,11 @@ from agent_runner.clock import SYSTEM_CLOCK, Clock
 
 REAP_GRACE_S = 5
 
+# Wall-clock bound on the best-effort `<runtime> stop` subprocess. Pinned by an
+# invariant test to stay <= _serve_policy._ROUND_TERM_GRACE_S so serve's
+# round-terminate escalation never SIGKILLs round_cmd mid-stop.
+_CONTAINER_STOP_TIMEOUT_S = REAP_GRACE_S + 5
+
 # Backstop cap on the stored child "name" (see _live_children). The primary
 # source (kernel comm) is already bounded (15 bytes on Linux); this only
 # guards the argv[0]-basename fallback used when comm is unavailable.
@@ -285,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
@@ -362,6 +376,20 @@ def _detect_container_run(command: list[str]) -> tuple[str, int] | None:
     return None
 
 
+# Matches the docker/podman flags that attach the container's stdin: `-i`, any
+# short cluster containing `i` (`-it`, `-ti`, `-di`), and `--interactive[=…]`;
+# NOT `--init` (double-dash, so the single-dash alternative can't consume it).
+_INTERACTIVE_FLAG = re.compile(r"^(-[a-z]*i[a-z]*|--interactive(=.*)?)$")
+
+
+def _exec_prefix_is_interactive(exec_prefix: list[str]) -> bool:
+    """True when the operator's ``exec_prefix`` carries a stdin-attaching flag.
+    Only the prefix's own docker flags matter -- the wrapped ``command`` runs
+    INSIDE the container, so an ``-i`` there is irrelevant to whether the
+    runtime forwards stdin."""
+    return any(_INTERACTIVE_FLAG.match(tok) for tok in exec_prefix)
+
+
 # `docker run`/`podman run` OPTIONS known to take a separate value token --
 # used only to walk PAST them without mistaking their value for IMAGE (e.g.
 # `--name foo`: without this, a naive scan would stop at "foo" thinking it's
@@ -479,26 +507,36 @@ def _best_effort_container_stop(
     ``(container_id, stop_ok)``: `container_id` is None when no id could be
     recovered (the container never actually started, or the cidfile is still
     empty) -- `stop_ok` is then also None, meaning no stop was attempted.
-    Otherwise `stop_ok` is whether the `stop` subprocess exited zero. Every
-    failure here is swallowed -- this is advisory best-effort, never a
-    guarantee; the caller's loud warning + event is the actual floor when
-    this doesn't land."""
+    Otherwise `stop_ok` is True when the `stop` subprocess exited zero, or
+    when it failed because the container was already gone (a `--rm`
+    container can self-remove before our stop lands -- that's not a failure
+    to report). Every other failure here is swallowed -- this is advisory
+    best-effort, never a guarantee; the caller's loud warning + event is the
+    actual floor when this doesn't land."""
     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", cid],
+            [runtime, "stop", "-t", str(REAP_GRACE_S), "--", cid],
             stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            timeout=10,
+            stderr=subprocess.PIPE,
+            timeout=_CONTAINER_STOP_TIMEOUT_S,
         )
-        return cid, result.returncode == 0
+        if result.returncode == 0:
+            return cid, True
+        # A `--rm` container that already exited is GONE, not orphaned — not a failure.
+        stderr = (result.stderr or b"").decode("utf-8", "replace").lower()
+        return cid, "no such container" in stderr
     except (OSError, subprocess.TimeoutExpired):
         return cid, False
 
@@ -581,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:
@@ -613,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)
 
@@ -644,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:
@@ -780,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.20 → 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.20 → 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.20 → cli_agent_runner-0.2.22}/agent_runner/cli/serve_cmd.py

@@ -29,6 +29,7 @@ from agent_runner._throttle import (
     round_outcome,
     round_was_mem_terminated,
 )
+from agent_runner.agent_runtime import _detect_container_run
 from agent_runner.api import (
     check_self_terminated_sentinel,
     emit_config_broken,
@@ -611,7 +612,9 @@ def cmd(args) -> int:
         return fail_code
     stop_file = cfg.runtime.stop_file  # cache: same pattern as effective_max_rounds
     work_dir = cfg.runtime.work_dir
-    defer_to_cgroup = _probe_and_emit_cgroup_defer(log_dir)
+    # Emitted exactly once per serve lifetime -- the per-round defer decision below
+    # reuses this bool rather than re-probing/re-emitting every round.
+    cgroup_probe_defer = _probe_and_emit_cgroup_defer(log_dir)
     rounds_completed = 0
     # Three independent consecutive-failure counters, one per breaker: b12
     # crash-loop (unknown short crashes), mem-loop (mem-terminated
@@ -685,6 +688,15 @@ def cmd(args) -> int:
             ]
             if phase_arg is not None:
                 round_argv += ["--phase", phase_arg]
+            # Phase-aware, per-round: a phase can override [phases.<name>.agent]
+            # command to a bare container run even when the base agent isn't one
+            # (exec_prefix is base-only, but command isn't) -- computing this once
+            # from the base agent would wrongly keep deferring a containerized
+            # phase's mid-round kill to dockerd's own cgroup-OOM.
+            defer_to_cgroup = cgroup_probe_defer and (
+                _detect_container_run(cfg.profile_for(phase_arg).agent.spawn_command(work_dir))
+                is None
+            )
             r_returncode = _spawn_round(
                 round_argv,
                 round_log_path,

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.22}/agent_runner/config/models.py

@@ -30,6 +30,7 @@ class AgentConfig:
     name: str | None = None
     env: dict[str, str] = field(default_factory=dict)
     prompt_delivery: Literal["argv", "stdin"] = "argv"
+    exec_prefix: list[str] = field(default_factory=list)
 
     @property
     def binary(self) -> str | None:
@@ -40,6 +41,16 @@ class AgentConfig:
         serve and runner don't each re-spell ``Path(command[0]).name``."""
         return Path(self.command[0]).name if self.command else None
 
+    def spawn_command(self, work_dir: Path) -> list[str]:
+        """The effective argv to spawn: an opaque operator-supplied ``exec_prefix``
+        (e.g. ``docker run … img``) spliced BEFORE ``command``, with the one
+        ``{work_dir}`` token substituted IN THE PREFIX ONLY. ``command`` (and thus
+        ``binary``) is appended verbatim and never rewritten, so the
+        throttle/crash-loop/hook identity join stays keyed on the real agent. Empty
+        ``exec_prefix`` ⇒ ``command`` unchanged. The SSOT both the spawn (runner) and
+        the startup battery resolve, so they can't drift."""
+        return [t.replace("{work_dir}", str(work_dir)) for t in self.exec_prefix] + self.command
+
 
 @dataclass(frozen=True)
 class RuntimeConfig:

{cli_agent_runner-0.2.20 → cli_agent_runner-0.2.22}/agent_runner/config/parsers.py

@@ -106,12 +106,16 @@ def _parse_agent(
             f"{field_prefix} command: must be a non-empty list; run `agent-runner migrate`"
         )
     env_d = _require_table(agent_d, "env", label=f"{field_prefix.strip('[]')}.env")
+    exec_prefix = _require_str_list(
+        agent_d.get("exec_prefix", []), field=f"{field_prefix} exec_prefix"
+    )
     return AgentConfig(
         command=command,
         prompt_arg_template=prompt_arg_template,
         name=agent_d.get("name"),
         env={str(k): str(v) for k, v in env_d.items()},
         prompt_delivery=prompt_delivery,  # type: ignore[arg-type]  # narrowed above
+        exec_prefix=exec_prefix,
     )
 
 
@@ -214,6 +218,11 @@ def _parse_phase_overrides(
             agent_sub = value["agent"]
             if not isinstance(agent_sub, dict):
                 raise ConfigError(f"[phases.{phase_name}.agent] must be a table")
+            if "exec_prefix" in agent_sub:
+                raise ConfigError(
+                    f"[phases.{phase_name}.agent] exec_prefix: not allowed per-phase — set "
+                    "exec_prefix once on the base [agent] table (it applies to every phase)"
+                )
             merged = {**agent_d, **agent_sub}
             phase_agent = _parse_agent(
                 merged,