cli-agent-runner 0.2.24__tar.gz → 0.3.1__tar.gz

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 2
     steps:
-      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         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@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: ${{ matrix.python }}
           cache: pip

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/.github/workflows/release.yml

@@ -26,10 +26,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.12"
       - name: install build
@@ -72,7 +72,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09  # v5
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: dist

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/.vulture-whitelist.py

@@ -13,6 +13,16 @@ log_dir
 offsets
 buffer
 
+# agent_runner._plugin_manifest.PluginManifest
+name
+pre_round_hooks
+context_enrichers
+post_round_hooks
+serve_startup_hooks
+dirty_handlers
+detectors
+event_kinds
+
 # agent_runner._round_outcome.RoundOutcome
 mem_terminated
 usage_capable
@@ -67,6 +77,7 @@ service
 recent_events
 recent_hook_failures
 recent_blips
+recent_cgroup_growth_warnings
 schedule
 
 # agent_runner.api_types.RateLimitState
@@ -164,18 +175,12 @@ round_progress_interval_s
 supervisor_stale_threshold_s
 
 # agent_runner.config.models.MonitorHostHealthConfig
-mem_avail_min_mb
-disk_warning_pct
-disk_critical_pct
-swap_sout_noise_floor_mb
-mem_free_low_mb
-psi_full_avg10_critical
-psi_some_avg10_warning
-mem_critical_consecutive_samples
-in_round_mem_terminate
+disk
+memory
+pressure
 
 # agent_runner.config.models.PhaseOverride
-round_timeout_s
+round_budget_s
 disable_pre_round_hooks
 prompt_files
 agent
@@ -207,7 +212,7 @@ strip_yaml_frontmatter
 # agent_runner.config.models.RuntimeConfig
 work_dir
 log_dir
-round_timeout_s
+round_budget_s
 restart_delay_s
 disable_pre_round_hooks
 round_log_retention
@@ -230,6 +235,22 @@ pause_windows
 stash_idempotency_s
 dirty_action
 
+# agent_runner.config.models._HostHealthDiskConfig
+warning_pct
+critical_pct
+
+# agent_runner.config.models._HostHealthMemoryConfig
+avail_min_mb
+free_low_mb
+swap_out_noise_floor_mb
+
+# agent_runner.config.models._HostHealthPressureConfig
+full_avg10_critical
+some_avg10_warning
+critical_consecutive_samples
+in_round_terminate
+cgroup_growth_rate_warning_mb_per_min
+
 # agent_runner.context_store.OrphanState
 round_num
 files

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-09-14
+
+### Added
+- `monitor.host_health.pressure.cgroup_growth_rate_warning_mb_per_min` (default 512.0): a mid-round memory-growth-rate detector gives an earlier growth signal than the existing PSI/MemFree floors catch, ahead of a runaway climb reaching them. Observability only — no round action.
+- `cgroup_growth_rate_warning` event, surfaced in `peek --json` as `recent_cgroup_growth_warnings` (schema `2.1`).
+
+## [0.3.0] - 2026-09-13
+
+**The one breaking release of the 0.3 line.** Run `agent-runner migrate` before upgrading — it rewrites everything below in one pass.
+
+### Changed
+- `[monitor.host_health]`'s 9 flat keys regroup into `.disk`/`.memory`/`.pressure` sub-tables (defaults unchanged).
+- `round_timeout_s` renamed to `round_budget_s` in `[runtime]` and `[phases.*]` (flat and nested forms).
+- The plugin ABI collapses from 7 entry-point groups to one (`agent_runner.plugins`), each resolving a typed `PluginManifest` instead of an import-time side effect. External plugins need a manual port — see `docs/migrations/0.3.md`.
+- A phase-window overlap now refuses `serve` boot (was a warning); `doctor` reports it as a failing check.
+- `peek --json` schema bumps to `2.0`.
+- Config now carries a top-level `schema_version`; a pre-0.3 or unversioned config is rejected with a pointed `agent-runner migrate` instruction.
+- `api.py` split into `_install`/`_lifecycle`/`_observe` behind an unchanged public facade — no external-surface change.
+
+### Renamed
+- Tenet-3 terminology: "price-blind" → "price-agnostic" (no logic change).
+
 ## [0.2.24] - 2026-09-12
 
 ### Added

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.2.24
+Version: 0.3.1
 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
@@ -100,7 +100,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 
-- **round_timeout_s** — hard wall, never the agent's word on when to stop
+- **round_budget_s** — hard wall, never the agent's word on when to stop
 - **process_group_isolation** — kill the round, not just the parent
 - **orphan_stash_idempotency_s** — no 3-stashes-per-second pile-ups
 - **sha_locked_stash** — `stash@{N}` indices drift; SHAs don't

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/README.md

@@ -62,7 +62,7 @@ Verb reference: [`docs/commands.md`](docs/commands.md).
 Each carries the historical incident it codifies and the invariant test that
 guards it. Highlights:
 
-- **round_timeout_s** — hard wall, never the agent's word on when to stop
+- **round_budget_s** — hard wall, never the agent's word on when to stop
 - **process_group_isolation** — kill the round, not just the parent
 - **orphan_stash_idempotency_s** — no 3-stashes-per-second pile-ups
 - **sha_locked_stash** — `stash@{N}` indices drift; SHAs don't

cli_agent_runner-0.3.1/agent_runner/__init__.py

@@ -0,0 +1,102 @@
+"""Agent Runner — restart-on-exit supervisor for autonomous CLI agents."""
+
+from __future__ import annotations
+
+try:
+    from agent_runner._version import __version__
+except ImportError:  # editable install before hatch-vcs has generated _version.py
+    __version__ = "0.0.0+unknown"
+
+_PLUGIN_GROUP = "agent_runner.plugins"
+
+# Tracks the names passed to the most recent ``apply_plugin_disable`` call.
+# Surfaced via peek --json `plugins.disabled` for operator visibility.
+_DISABLED_PLUGIN_NAMES: list[str] = []
+
+
+def _load_plugin_manifests() -> None:
+    """Discover agent_runner.plugins entry points, resolve each to a
+    module-level PluginManifest, and register its declared capabilities.
+
+    Called at package import. A broken plugin (bad import, missing PLUGIN
+    attribute, malformed manifest) must never crash the supervisor — isolated
+    as a UserWarning.
+
+    Discovery goes through the ``entry_points.txt`` scanner (cheaper than a
+    fresh ``importlib.metadata.entry_points()`` scan per process; see
+    ``_plugin_scan``), with a hard fallback to ``importlib.metadata`` on any
+    parse failure.
+    """
+    import importlib
+    import sys
+    import warnings
+
+    from agent_runner._plugin_manifest import register_manifest
+    from agent_runner._plugin_scan import scan_entry_points
+
+    for name, value in scan_entry_points(sys.path, _PLUGIN_GROUP):
+        try:
+            # An entry-point value may carry a trailing extras marker
+            # (``module:attr [extra1,extra2]``); importlib.metadata.EntryPoint's
+            # own module/attr grammar excludes "[", so anything from the first
+            # "[" onward is always extras, never part of the path — strip it
+            # before resolving, or it glues onto attr_path and breaks getattr().
+            module_path, _, attr_path = value.partition("[")[0].rstrip().partition(":")
+            mod = importlib.import_module(module_path)
+            target = mod
+            for attr in filter(None, attr_path.split(".")):
+                target = getattr(target, attr)
+            register_manifest(target)
+        except Exception as e:
+            warnings.warn(
+                f"failed to load {_PLUGIN_GROUP} plugin {name!r}: {e}",
+                stacklevel=3,
+            )
+
+
+_load_plugin_manifests()
+
+
+def apply_plugin_disable(names: list[str]) -> None:
+    """Remove plugins matching ``names`` (manifest names) from all in-memory
+    registries.
+
+    Called after config-load to honor ``[plugins] disable``. Idempotent for
+    already-removed names. Emits a UserWarning for names that match no
+    loaded manifest (typo catcher; tolerates cross-env config drift).
+
+    Plugin packages still load at import time — this removes from the registries
+    that the runner and peek consult. Side effects from loading (module-level
+    imports, etc.) have already happened by the time this runs.
+
+    Known limitation: vcs_state._PLUGIN_OWNED_PATHS lacks per-plugin name
+    attribution today, so owned-paths are NOT filtered here. Disabled plugin's
+    paths remain registered (mostly inert).
+    """
+    import warnings
+
+    from agent_runner._plugin_manifest import unregister_by_name
+
+    if not names:
+        return
+
+    global _DISABLED_PLUGIN_NAMES
+    _DISABLED_PLUGIN_NAMES = list(names)
+
+    found = unregister_by_name(set(names))
+    unknown = set(names) - found
+    if unknown:
+        warnings.warn(
+            f"[plugins] disable references unknown plugin name(s): {sorted(unknown)}. "
+            f"(Names matched no loaded PluginManifest; check spelling or installed packages.)",
+            stacklevel=2,
+        )
+
+
+def disabled_plugin_names() -> list[str]:
+    """Names passed to the most recent ``apply_plugin_disable`` call.
+
+    Used by peek --json to surface ``plugins.disabled`` for operator visibility.
+    Returns the LIST (not set) preserving configured order.
+    """
+    return list(_DISABLED_PLUGIN_NAMES)

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/agent_runner/_docgen.py

@@ -29,6 +29,9 @@ from agent_runner.config import (
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _HostHealthDiskConfig,
+    _HostHealthMemoryConfig,
+    _HostHealthPressureConfig,
 )
 from agent_runner.defenses import catalog
 from agent_runner.events import (
@@ -55,7 +58,16 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
     ("runtime", RuntimeConfig, []),
     ("prompt", PromptConfig, []),
     ("vcs", VcsConfig, []),
-    ("monitor", MonitorConfig, [("monitor.host_health", MonitorHostHealthConfig)]),
+    (
+        "monitor",
+        MonitorConfig,
+        [
+            ("monitor.host_health", MonitorHostHealthConfig),
+            ("monitor.host_health.disk", _HostHealthDiskConfig),
+            ("monitor.host_health.memory", _HostHealthMemoryConfig),
+            ("monitor.host_health.pressure", _HostHealthPressureConfig),
+        ],
+    ),
     ("phases", PhasesConfig, []),
     ("plugins", PluginsConfig, []),
     ("schedule", ScheduleConfig, []),

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/agent_runner/_emit/__init__.py

@@ -29,6 +29,7 @@ from agent_runner._emit.agent import (  # noqa: F401 — public re-export
     emit_transient_error_recovered,
 )
 from agent_runner._emit.memory import (  # noqa: F401 — public re-export
+    emit_cgroup_growth_rate_warning,
     emit_host_cgroup_memory_limit,
     emit_mem_pressure_deferred_to_cgroup,
     emit_round_cgroup_memory,
@@ -57,7 +58,6 @@ from agent_runner._emit.serve import (  # noqa: F401 — public re-export
     emit_max_rounds_reached,
     emit_mem_loop,
     emit_mem_loop_persistent,
-    emit_phase_window_overlap,
     emit_rate_limit_stop,
     emit_schedule_paused,
     emit_schedule_phase_skipped,
@@ -70,6 +70,7 @@ __all__ = [
     "emit_agent_auth_error_detected",
     "emit_agent_usage_recorded",
     "emit_anomaly_repetitive_tool",
+    "emit_cgroup_growth_rate_warning",
     "emit_config_broken",
     "emit_config_migrated",
     "emit_crash_loop",
@@ -79,7 +80,6 @@ __all__ = [
     "emit_mem_loop",
     "emit_mem_loop_persistent",
     "emit_mem_pressure_deferred_to_cgroup",
-    "emit_phase_window_overlap",
     "emit_rate_limit_stop",
     "emit_round_cgroup_memory",
     "emit_round_container_orphan_risk",

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/agent_runner/_emit/memory.py

@@ -78,10 +78,10 @@ def emit_round_mem_critical_sample(
     sample-level signal, distinct from mem_pressure_deferred_to_cgroup's
     once-per-episode terminate-vs-defer notice).
 
-    The caller caps this at ``2 * mem_critical_consecutive_samples``
+    The caller caps this at ``2 * pressure.critical_consecutive_samples``
     consecutive ticks (1..6 at the default 3) -- a sustained-critical
     don't-terminate run (cgroup-defer, or the off switch) would otherwise
-    write one event per ~10s tick for up to a whole ``round_timeout_s`` on a
+    write one event per ~10s tick for up to a whole ``round_budget_s`` on a
     permanently-deferred/off host. The cap is per streak-episode, not a
     lifetime limit: any non-critical tick still resets the streak to 0, and
     sampling resumes from 1 the next time critical pressure recurs."""
@@ -233,8 +233,38 @@ def emit_mem_pressure_deferred_to_cgroup(
     (both memory.max and memory.swap.max finite) -- kernel cgroup-OOM will
     contain the agent and keep the host responsive on its own, so the
     cruder host-wide round-kill steps back instead of firing
-    round_mem_terminated. This OVERRIDES in_round_mem_terminate=True: a
+    round_mem_terminated. This OVERRIDES in_round_terminate=True: a
     bounded cgroup makes the host floor strictly worse, not just redundant."""
     from agent_runner.events import MEM_PRESSURE_DEFERRED_TO_CGROUP, emit
 
     emit(log_dir, MEM_PRESSURE_DEFERRED_TO_CGROUP, pid=pid, signal=signal, message=message)
+
+
+def emit_cgroup_growth_rate_warning(
+    log_dir: Path,
+    *,
+    round_num: int,
+    rate_mb_per_min: float,
+    threshold_mb_per_min: float,
+    source: str,
+    context: dict,
+) -> None:
+    """Emit on a False->True crossing of _spawn_round's mid-round growth-rate
+    derivative (host_health.cgroup_growth_rate_pressure) -- observability
+    only, no action path. ``source`` names which per-tick reading the
+    derivative used: "cgroup" (a finite cgroup memory.max bound exists,
+    memory.current is read) or "rss_sum" (no finite bound -- the psutil
+    children_rss_sum_bytes tree sum is used instead). Edge-triggered: fires
+    once per crossing episode, not once per tick, so a sustained climb does
+    not spam the event stream."""
+    from agent_runner.events import CGROUP_GROWTH_RATE_WARNING, emit
+
+    emit(
+        log_dir,
+        CGROUP_GROWTH_RATE_WARNING,
+        round_num=round_num,
+        rate_mb_per_min=rate_mb_per_min,
+        threshold_mb_per_min=threshold_mb_per_min,
+        source=source,
+        context=context,
+    )

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/agent_runner/_emit/rounds.py

@@ -169,7 +169,7 @@ def emit_round_grace_extended(
 ) -> None:
     """Emit when the grace-after-result timer expired but the agent still had
     live worker processes (e.g. a backgrounded build), so the round was NOT
-    killed; it continues until it finishes or hits round_timeout_s.
+    killed; it continues until it finishes or hits round_budget_s.
 
     live_children: list of ``{"name": <exe basename>, "pid": <int>}`` dicts
         (previously a list of cmdline strings).

{cli_agent_runner-0.2.24 → cli_agent_runner-0.3.1}/agent_runner/_emit/serve.py

@@ -191,23 +191,3 @@ def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
     from agent_runner.events import SCHEDULE_RESUMED, emit
 
     emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
-
-
-def emit_phase_window_overlap(
-    log_dir: Path, *, phase_a: str, phase_b: str, window_a: str, window_b: str
-) -> None:
-    """Emit phase_window_overlap: two agent-overriding phases' own run_windows
-    collide (a rotation footgun; a later release promotes this exact detection
-    to a hard error). Called once at serve boot -- the collision is a property of the
-    static config, not of any one round, so (like emit_max_rounds_reached's
-    cgroup-probe sibling) this must not be called from the per-round path."""
-    from agent_runner.events import PHASE_WINDOW_OVERLAP, emit
-
-    emit(
-        log_dir,
-        PHASE_WINDOW_OVERLAP,
-        phase_a=phase_a,
-        phase_b=phase_b,
-        window_a=window_a,
-        window_b=window_b,
-    )

cli_agent_runner-0.3.1/agent_runner/_install.py

@@ -0,0 +1,187 @@
+"""Systemd install / uninstall: ``init``, ``install``, ``uninstall``.
+
+Depends one-directionally on ``_lifecycle.py`` for the shared
+``_project_name`` / ``_check_user_systemd_available`` / ``_SYSTEM_UNITS_DIR`` /
+``_system_unit_exists`` / ``_PID_SIGNAL_GRACE_S`` helpers — never the reverse.
+
+Re-exported from ``agent_runner.api`` (the thin facade) so external callers
+and existing internal callers keep working unchanged.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess  # noqa: TID251 — install uses systemctl, subprocess
+import sysconfig
+from pathlib import Path
+
+from agent_runner import _resolve, lifecycle
+from agent_runner._lifecycle import (
+    _PID_SIGNAL_GRACE_S,
+    _SYSTEM_UNITS_DIR,
+    _check_user_systemd_available,
+    _project_name,
+    _system_unit_exists,
+)
+from agent_runner.api_types import InitResult, InstallResult
+from agent_runner.clock import SYSTEM_CLOCK
+from agent_runner.config import Config, load_config
+from agent_runner.lifecycle import _systemctl_user
+from agent_runner.scaffold import scaffold_project
+from agent_runner.service_unit import (
+    monitor_unit_filename,
+    render_monitor_unit,
+    render_serve_unit,
+    serve_unit_filename,
+)
+
+
+def _agent_runner_script_path() -> Path:
+    """Locate the agent-runner CLI script for systemd ExecStart.
+
+    Tries shutil.which first (honors PATH). Falls back to sysconfig's
+    scripts dir (handles cases where PATH excludes the install dir).
+    Raises FileNotFoundError if neither resolves to an existing file.
+    """
+    which = shutil.which("agent-runner")
+    if which:
+        return Path(which)
+    scripts_dir = Path(sysconfig.get_path("scripts"))
+    candidate = scripts_dir / "agent-runner"
+    if candidate.exists():
+        return candidate
+    raise FileNotFoundError(
+        "agent-runner script not found in PATH or "
+        f"{scripts_dir}; reinstall via pip or activate the right venv"
+    )
+
+
+def init(
+    work_dir: Path | None = None,
+    *,
+    preset: str = "claude",
+    force: bool = False,
+    commit: bool = True,
+) -> InitResult:
+    if work_dir is None:
+        work_dir = Path.cwd()
+    return scaffold_project(work_dir, preset=preset, force=force, commit=commit)
+
+
+def _install_system(
+    cfg: Config, project: str, *, config_path: Path, with_monitor: bool
+) -> InstallResult:
+    if os.geteuid() != 0:
+        raise RuntimeError(
+            "--system requires sudo; run via `sudo -E agent-runner install --system`"
+        )
+    sudo_user = os.environ.get("SUDO_USER")
+    if not sudo_user:
+        raise RuntimeError(
+            "--system needs SUDO_USER env var; run via "
+            "`sudo -E agent-runner install --system` to preserve env"
+        )
+    script_path = _agent_runner_script_path()
+    serve_path = _SYSTEM_UNITS_DIR / serve_unit_filename(project)
+    serve_path.write_text(
+        render_serve_unit(cfg, script_path=script_path, config_path=config_path, user=sudo_user)
+    )
+    monitor_path: Path | None = None
+    if with_monitor:
+        monitor_path = _SYSTEM_UNITS_DIR / monitor_unit_filename(project)
+        monitor_path.write_text(
+            render_monitor_unit(
+                cfg, script_path=script_path, config_path=config_path, user=sudo_user
+            )
+        )
+    subprocess.run(["systemctl", "daemon-reload"], check=True)
+    subprocess.run(["systemctl", "enable", serve_unit_filename(project)], check=True)
+    if with_monitor:
+        subprocess.run(["systemctl", "enable", monitor_unit_filename(project)], check=True)
+    return InstallResult(
+        unit_path=serve_path,
+        monitor_unit_path=monitor_path,
+        enabled=True,
+        started=False,
+    )
+
+
+def install(
+    work_dir: Path | None = None,
+    *,
+    system: bool = False,
+    with_monitor: bool = False,
+    force: bool = False,
+) -> InstallResult:
+    if work_dir is None:
+        work_dir = Path.cwd()
+    cfg_path = work_dir / "agent-runner.toml"
+    cfg = load_config(cfg_path)
+    project = _project_name(work_dir)
+
+    units_dir = _SYSTEM_UNITS_DIR if system else lifecycle._user_systemd_dir()
+    _resolve.guard_against_clobber(
+        units_dir / serve_unit_filename(project), cfg.runtime.work_dir, force=force
+    )
+
+    if system:
+        return _install_system(cfg, project, config_path=cfg_path, with_monitor=with_monitor)
+
+    _check_user_systemd_available()
+    script_path = _agent_runner_script_path()
+
+    units_dir.mkdir(parents=True, exist_ok=True)
+
+    serve_path = units_dir / serve_unit_filename(project)
+    serve_path.write_text(render_serve_unit(cfg, script_path=script_path, config_path=cfg_path))
+
+    monitor_path: Path | None = None
+    if with_monitor:
+        monitor_path = units_dir / monitor_unit_filename(project)
+        monitor_path.write_text(
+            render_monitor_unit(cfg, script_path=script_path, config_path=cfg_path)
+        )
+
+    _systemctl_user("daemon-reload")
+    _systemctl_user("enable", serve_unit_filename(project))
+    _systemctl_user("start", serve_unit_filename(project))
+    if with_monitor:
+        _systemctl_user("enable", monitor_unit_filename(project))
+        _systemctl_user("start", monitor_unit_filename(project))
+
+    return InstallResult(
+        unit_path=serve_path, monitor_unit_path=monitor_path, enabled=True, started=True
+    )
+
+
+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)
+    for p in (serve, monitor):
+        if p.exists():
+            # Drain-aware (see stop_unit_draining, the same primitive api.stop/
+            # api.restart use): a blocking `systemctl stop` would TimeoutExpired
+            # while serve drains its round -- queue it and confirm within a
+            # bounded window instead, same as stop(), before disabling/unlinking.
+            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)
+    try:
+        _systemctl_user("daemon-reload")
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass  # no user bus on this host -- units above (if any) already gone
+    return True