cli-agent-runner 0.1.36__tar.gz → 0.1.38__tar.gz

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.38] - 2026-05-24
+
+### Fixed
+- Grace-kill (`max_grace_after_result_s`) no longer reaps a round that emitted `type=result` while a backgrounded child process (e.g. a long build) is still running. It now reaps only when the agent's process group has no live worker processes left (a genuine hang); otherwise it waits for the round to finish or for the `round_timeout_s` ceiling.
+- Corrected `round_grace_kill`'s description: the kill is gated on the process group being idle (no live workers), not on log silence.
+
+### Added
+- New event `round_grace_extended` — emitted once when grace elapsed after `type=result` but a live worker process kept the round busy; carries the worker cmdlines.
+- `round_grace_kill` now carries `live_children` (cmdlines observed at kill time; empty for a genuine idle hang).
+
+## [0.1.37] - 2026-05-22
+
+### Fixed
+- `upgrade` no longer crashes when run from a directory without `agent-runner.toml` — it upgrades the package and falls back to package-only mode.
+- `upgrade` handles PEP 668 externally-managed environments (Debian 12 etc.): retries pip with `--break-system-packages` (and `--user` for user-site installs) when not in a venv.
+
+### Changed
+- `upgrade` only stop/start-orchestrates the `systemd --user` service it installed. For a self-managed service (e.g. a systemd system unit) it does package-only upgrade + smoke and prints the restart command to run yourself — no more silent no-op, and no more `agent-runner start` suggestion (which could spawn a conflicting second supervisor).
+- New `--no-restart` flag forces package-only upgrade.
+
+### Added
+- New event `package_upgraded` (on-disk package changed; restart deferred to the operator), distinct from `service_upgraded` (the live service is now on the new version).
+
 ## [0.1.36] - 2026-05-21
 
 ### Added

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.36
+Version: 0.1.38
 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.1.36 → cli_agent_runner-0.1.38}/agent_runner/_emit.py

@@ -19,6 +19,7 @@ __all__ = [
     "emit_fresh_eyes_round_triggered",
     "emit_max_rounds_reached",
     "emit_rate_limit_stop",
+    "emit_round_grace_extended",
     "emit_round_grace_kill",
     "emit_round_progress",
     "emit_round_substrate_after",
@@ -233,16 +234,44 @@ def emit_round_grace_kill(
     *,
     round_num: int,
     grace_s: int,
+    live_children: list[str] | None = None,
 ) -> None:
-    """Emit when subprocess killed because grace-after-result timer expired.
-
-    Subprocess emitted type=result in JSONL log then sat silent for longer
-    than max_grace_after_result_s seconds. Distinguishes from round_timeout_kill
-    (wall-clock exceeded without result event).
+    """Emit when the subprocess was killed because the grace-after-result timer
+    expired AND the agent's process group had no live worker processes left
+    (a genuine hang). Distinct from round_grace_extended (grace elapsed but a
+    worker was still running) and round_timeout_kill (wall-clock exceeded).
     """
     from agent_runner.events import ROUND_GRACE_KILL, emit
 
-    emit(log_dir, ROUND_GRACE_KILL, round_num=round_num, grace_s=grace_s)
+    emit(
+        log_dir,
+        ROUND_GRACE_KILL,
+        round_num=round_num,
+        grace_s=grace_s,
+        live_children=live_children or [],
+    )
+
+
+def emit_round_grace_extended(
+    log_dir: Path,
+    *,
+    round_num: int,
+    grace_s: int,
+    live_children: list[str],
+) -> 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.
+    """
+    from agent_runner.events import ROUND_GRACE_EXTENDED, emit
+
+    emit(
+        log_dir,
+        ROUND_GRACE_EXTENDED,
+        round_num=round_num,
+        grace_s=grace_s,
+        live_children=live_children,
+    )
 
 
 def emit_anomaly_repetitive_tool(

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.36'
-__version_tuple__ = version_tuple = (0, 1, 36)
+__version__ = version = '0.1.38'
+__version_tuple__ = version_tuple = (0, 1, 38)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/agent_runtime.py

@@ -15,9 +15,11 @@ import signal
 import subprocess  # noqa: TID251 — sanctioned subprocess caller
 import time
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 
+import psutil
+
 REAP_GRACE_S = 5
 
 
@@ -28,6 +30,7 @@ class RunResult:
     timed_out: bool
     pid: int
     killed_for_grace: bool = False
+    grace_kill_children: list[str] = field(default_factory=list)
 
 
 def _build_argv(command: list[str], prompt_arg_template: list[str], prompt: str) -> list[str]:
@@ -54,6 +57,31 @@ def _kill_pgroup(proc: subprocess.Popen) -> None:
         pass
 
 
+def _live_children(proc: subprocess.Popen, *, max_n: int = 5, max_len: int = 120) -> list[str]:
+    """Cmdlines of live (non-zombie) descendant processes of ``proc``.
+
+    Empty when ``proc`` has no live workers (a stuck agent that emitted
+    type=result then hung). Non-empty when the round backgrounded work (e.g. a
+    build) still running. Bounded so the resulting event stays small.
+    """
+    try:
+        parent = psutil.Process(proc.pid)
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        return []
+    out: list[str] = []
+    for child in parent.children(recursive=True):
+        try:
+            if child.status() == psutil.STATUS_ZOMBIE:
+                continue
+            line = " ".join(child.cmdline()) or child.name()
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+        out.append(line[:max_len])
+        if len(out) >= max_n:
+            break
+    return out
+
+
 # Exact compact bytes — matches claude CLI's no-whitespace JSONL output.
 # A future CLI variant emitting `{"type": "result", ...}` (with space) would
 # bypass this scan; revisit if that happens.
@@ -71,14 +99,18 @@ def run(
     max_grace_after_result_s: int = 0,
     progress_callback: Callable[[dict], None] | None = None,
     progress_interval_s: int = 0,
+    on_grace_extended: Callable[[list[str]], None] | None = None,
 ) -> RunResult:
     """Spawn the agent subprocess and wait for exit or timeout.
 
     Wall-clock timeout (R1128). On timeout: SIGTERM pgroup → REAP_GRACE_S → SIGKILL.
 
     max_grace_after_result_s: when > 0, start a countdown after the first
-    type=result event is detected in the log; kill if subprocess is still
-    running after this many seconds (HUNG defense). 0 = disabled.
+    type=result event is detected in the log. After it elapses, reap the
+    process group only if the agent has no live worker processes left (a
+    genuine hang). If a worker is still running (e.g. a backgrounded build),
+    do not reap — invoke ``on_grace_extended`` once and keep waiting until the
+    round finishes or hits the wall-clock ``timeout_s`` ceiling. 0 = disabled.
 
     progress_callback: when not None and progress_interval_s > 0, called every
     progress_interval_s seconds with a dict of log stats (log_size_kb,
@@ -100,6 +132,7 @@ def run(
         start_new_session=True,
     )
     result_seen_at: float | None = None
+    grace_extended_emitted = False
     try:
         while True:
             ret = proc.poll()
@@ -114,10 +147,9 @@ def run(
                 return RunResult(
                     exit_code=exit_code, duration_s=duration, timed_out=True, pid=proc.pid
                 )
-            # Grace kill: result emitted but subprocess still running
+            # Grace kill: result emitted but subprocess still running.
             if max_grace_after_result_s > 0:
                 if result_seen_at is None:
-                    # Cheap check: byte-scan log for marker substring
                     try:
                         with log_path.open("rb") as f:
                             if _RESULT_MARKER in f.read():
@@ -125,16 +157,26 @@ def run(
                     except OSError:
                         pass  # log not flushed yet; check next tick
                 if result_seen_at is not None and now - result_seen_at > max_grace_after_result_s:
-                    _kill_pgroup(proc)
-                    duration = time.time() - start
-                    exit_code = proc.returncode if proc.returncode is not None else -1
-                    return RunResult(
-                        exit_code=exit_code,
-                        duration_s=duration,
-                        timed_out=True,
-                        pid=proc.pid,
-                        killed_for_grace=True,
-                    )
+                    children = _live_children(proc)
+                    if children:
+                        # Busy: a backgrounded worker is still running. Don't
+                        # reap — defer to the wall-clock ceiling. Signal once.
+                        if not grace_extended_emitted:
+                            if on_grace_extended is not None:
+                                on_grace_extended(children)
+                            grace_extended_emitted = True
+                    else:
+                        _kill_pgroup(proc)
+                        duration = time.time() - start
+                        exit_code = proc.returncode if proc.returncode is not None else -1
+                        return RunResult(
+                            exit_code=exit_code,
+                            duration_s=duration,
+                            timed_out=True,
+                            pid=proc.pid,
+                            killed_for_grace=True,
+                            grace_kill_children=[],
+                        )
             # Progress heartbeat: call back if interval elapsed
             if progress_callback is not None and progress_interval_s > 0:
                 if now - last_progress_at >= progress_interval_s:

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/api.py

@@ -733,6 +733,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_fresh_eyes_round_triggered,
     emit_max_rounds_reached,
     emit_rate_limit_stop,
+    emit_round_grace_extended,
     emit_round_grace_kill,
     emit_round_progress,
     emit_round_substrate_after,

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/cli/upgrade_cmd.py

@@ -18,7 +18,9 @@ import sys
 import time
 from pathlib import Path
 
+import agent_runner
 from agent_runner import __version__, api, events
+from agent_runner.api_types import ServiceMode
 from agent_runner.cli.common import cfg_from_args, fail, info
 from agent_runner.config import Config
 
@@ -28,8 +30,8 @@ def add_parser(sub, parent) -> None:
         "upgrade",
         parents=[parent],
         help=(
-            "Round-boundary upgrade: stop → pip install → smoke → start"
-            " (auto-rollback on smoke fail)"
+            "Package upgrade with service-mode gate: orchestrated stop/start"
+            " for systemd --user; package-only otherwise"
         ),
     )
     p.add_argument(
@@ -40,24 +42,69 @@ def add_parser(sub, parent) -> None:
         help="Pin a specific version (e.g. 0.1.13). Default: latest from PyPI. "
         "Use to roll back: `--target <previous-version>`.",
     )
+    p.add_argument(
+        "--no-restart",
+        action="store_true",
+        help="Upgrade the package + smoke only; do not stop/start the service "
+        "(you restart it yourself).",
+    )
     p.set_defaults(func=cmd)
 
 
 def cmd(args) -> int:
-    cfg = cfg_from_args(args)
-    return _run_upgrade(cfg, target=args.target, cfg_path=args.config)
+    cfg = _try_load_cfg(args)
+    return _run_upgrade(
+        cfg,
+        target=args.target,
+        cfg_path=args.config,
+        no_restart=getattr(args, "no_restart", False),
+    )
 
 
-def _pip_install(spec: str, *, force_reinstall: bool = False) -> subprocess.CompletedProcess:
-    """Invoke pip install with the given spec. Returns CompletedProcess (rc check by caller).
+def _try_load_cfg(args) -> Config | None:
+    """Load the project config if present; None when absent (package-only)."""
+    try:
+        return cfg_from_args(args)
+    except FileNotFoundError:
+        return None
+
+
+def _pip_env_flags() -> list[str]:
+    """Extra pip flags for the current install under PEP 668.
 
-    Uses ``sys.executable -m pip`` to match the smoke functions and guarantee
-    we install into the same interpreter we will smoke-test against.
+    Inside a venv: none (pip is unrestricted). Otherwise (system/user
+    interpreter on an externally-managed distro) the caller retries with these.
+    ``--user`` is added only when agent_runner lives in user-site, matching
+    where the existing install actually is.
+    """
+    import sys
+
+    if sys.prefix != sys.base_prefix:  # inside a venv → no PEP 668
+        return []
+    import site
+
+    flags = ["--break-system-packages"]
+    user_site = site.getusersitepackages()
+    if str(Path(agent_runner.__file__)).startswith(str(Path(user_site))):
+        flags.insert(0, "--user")
+    return flags
+
+
+def _pip_install(spec: str, *, force_reinstall: bool = False) -> subprocess.CompletedProcess:
+    """pip install --upgrade <spec>, retrying once with PEP668 flags on an
+    externally-managed environment. Returns CompletedProcess (rc check by caller).
     """
-    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", spec]
+    base = [sys.executable, "-m", "pip", "install", "--upgrade", spec]
     if force_reinstall:
-        cmd.insert(4, "--force-reinstall")
-    return subprocess.run(cmd, capture_output=True, text=True, check=False)
+        base.insert(4, "--force-reinstall")
+    r = subprocess.run(base, capture_output=True, text=True, check=False)
+    if r.returncode == 0 or "externally-managed-environment" not in (r.stderr or ""):
+        return r
+    extra = _pip_env_flags()
+    if not extra:
+        return r
+    info(f"externally-managed env detected; retrying pip with {' '.join(extra)}")
+    return subprocess.run(base + extra, capture_output=True, text=True, check=False)
 
 
 def _smoke_version() -> tuple[int, str]:
@@ -93,18 +140,40 @@ def _smoke_peek(cfg_path: Path) -> tuple[int, str]:
     return 0, ""
 
 
-def _run_upgrade(cfg: Config, *, target: str | None, cfg_path: Path) -> int:
-    """Orchestrate the full upgrade flow.
-
-    Returns exit code (0 success, 1 user-recoverable, 2 critical).
-    """
+def _run_upgrade(
+    cfg: Config | None,
+    *,
+    target: str | None,
+    cfg_path: Path,
+    no_restart: bool = False,
+) -> int:
+    """Dispatch: full orchestration for the systemd --user service we installed;
+    package-only everywhere else."""
     if target is not None and not target.strip():
         return fail("--target must be a non-empty version string (e.g. 0.1.13)")
+    from_version = __version__
+    if _orchestrate_capable(cfg, no_restart):
+        return _orchestrated_upgrade(
+            cfg, target=target, cfg_path=cfg_path, from_version=from_version
+        )
+    return _package_only_upgrade(cfg, target=target, from_version=from_version)
+
+
+def _orchestrate_capable(cfg: Config | None, no_restart: bool) -> bool:
+    if cfg is None or no_restart:
+        return False
+    pname = api._resolve_project(cfg.runtime.work_dir)
+    return api.detect_service_mode(pname, log_dir=cfg.runtime.log_dir) == ServiceMode.SYSTEMD_USER
 
+
+def _orchestrated_upgrade(
+    cfg: Config, *, target: str | None, cfg_path: Path, from_version: str
+) -> int:
+    """Full stop → pip → smoke(--version + peek) → start → emit service_upgraded,
+    with auto-rollback on smoke failure. Only reached for the systemd --user
+    service agent-runner installed (api.start works there)."""
     log_dir = cfg.runtime.log_dir
     log_dir.mkdir(parents=True, exist_ok=True)
-
-    from_version = __version__
     t0 = time.monotonic()
 
     info("stopping service...")
@@ -155,14 +224,13 @@ def _run_upgrade(cfg: Config, *, target: str | None, cfg_path: Path) -> int:
             started_at=t0,
             cfg_path=cfg_path,
         )
-
     info(f"smoke OK (now at {to_version})")
 
     info("starting service...")
     t_start = time.monotonic()
     try:
         api.start(cfg.runtime.work_dir)
-    except Exception as e:  # noqa: BLE001 — new version installed but service stopped; no safe auto-rollback
+    except Exception as e:  # noqa: BLE001 — new version installed but service stopped
         return _rollback_failed(
             log_dir,
             to_version,
@@ -183,6 +251,65 @@ def _run_upgrade(cfg: Config, *, target: str | None, cfg_path: Path) -> int:
     return 0
 
 
+def _package_only_upgrade(cfg: Config | None, *, target: str | None, from_version: str) -> int:
+    """Upgrade the on-disk package + smoke (--version), with pip-level rollback.
+    Never touches the service — the operator restarts it. Used for any deployment
+    not managed as a systemd --user service (system unit, foreground, none, no
+    config, or --no-restart)."""
+    spec = "cli-agent-runner" if target is None else f"cli-agent-runner=={target}"
+    info(f"package-only upgrade (service not managed by agent-runner); installing {spec}...")
+    pip_result = _pip_install(spec)
+    if pip_result.returncode != 0:
+        return fail(
+            f"pip install failed (rc={pip_result.returncode}): "
+            f"{pip_result.stderr.strip()[:200]}; "
+            f"package unchanged, your service keeps running the current version"
+        )
+
+    rc_v, version_or_err = _smoke_version()
+    if rc_v != 0:
+        attempted = target or "latest"
+        info(f"smoke failed at {attempted} ({version_or_err}); reinstalling {from_version}...")
+        rb = _pip_install(f"cli-agent-runner=={from_version}", force_reinstall=True)
+        if rb.returncode != 0:
+            return fail(
+                f"package smoke failed AND rollback reinstall failed (rc={rb.returncode}): "
+                f"{rb.stderr.strip()[:200]}; run: "
+                f"pip install --force-reinstall cli-agent-runner=={from_version}"
+            )
+        return fail(
+            f"package smoke failed at {attempted}; reinstalled {from_version}; service untouched"
+        )
+    to_version = version_or_err
+
+    if cfg is not None:
+        log_dir = cfg.runtime.log_dir
+        log_dir.mkdir(parents=True, exist_ok=True)
+        events.emit(
+            log_dir,
+            events.PACKAGE_UPGRADED,
+            from_version=from_version,
+            to_version=to_version,
+            restart_deferred=True,
+        )
+    info(f"package upgraded {from_version} → {to_version}. Restart your supervisor to load it:")
+    info(_restart_hint(cfg))
+    return 0
+
+
+def _restart_hint(cfg: Config | None) -> str:
+    """Mode-correct restart command. Never suggests `agent-runner start`
+    (which would spawn a conflicting supervisor on a system-unit host)."""
+    if cfg is not None:
+        pname = api._resolve_project(cfg.runtime.work_dir)
+        if api.detect_service_mode(pname, log_dir=cfg.runtime.log_dir) == ServiceMode.SYSTEMD_USER:
+            return f"  systemctl --user restart {api.serve_unit_filename(pname)}"
+    return (
+        "  sudo systemctl restart <your-unit>   # if run by a systemd system unit\n"
+        "  (agent-runner can't know a service it didn't install; substitute your unit name)"
+    )
+
+
 def _rollback(
     cfg: Config,
     log_dir: Path,

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/events.py

@@ -46,8 +46,10 @@ MONITOR_STARTED = "monitor_started"
 ORPHAN_IDEMPOTENT_SKIP = "orphan_idempotent_skip"
 ORPHAN_STASH_FAILED = "orphan_stash_failed"
 ORPHAN_STASHED = "orphan_stashed"
+PACKAGE_UPGRADED = "package_upgraded"
 PROMPT_OVERWRITTEN = "prompt_overwritten"
 ROUND_END = "round_end"
+ROUND_GRACE_EXTENDED = "round_grace_extended"
 ROUND_GRACE_KILL = "round_grace_kill"
 ROUND_PROGRESS = "round_progress"
 ROUND_START = "round_start"

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/agent_runner/runner.py

@@ -466,6 +466,14 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
             **stats,
         )
 
+    def _grace_extended_emit(children: list[str]) -> None:
+        api.emit_round_grace_extended(
+            log_dir,
+            round_num=round_num,
+            grace_s=cfg.runtime.max_grace_after_result_s,
+            live_children=children,
+        )
+
     result = agent_runtime.run(
         command=cfg.agent.command,
         prompt_arg_template=cfg.agent.prompt_arg_template,
@@ -476,6 +484,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
         max_grace_after_result_s=cfg.runtime.max_grace_after_result_s,
         progress_callback=_progress_emit,
         progress_interval_s=cfg.monitor.round_progress_interval_s,
+        on_grace_extended=_grace_extended_emit,
     )
     events.emit(
         log_dir,
@@ -549,6 +558,7 @@ def _run_one_round_inner(cfg: Config, *, phase_override: str | None = None) -> R
             log_dir,
             round_num=round_num,
             grace_s=cfg.runtime.max_grace_after_result_s,
+            live_children=result.grace_kill_children,
         )
     elif result.timed_out:
         events.emit(

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/docs/architecture.md

@@ -165,8 +165,10 @@ hook (vs ALL pre-round hooks), use `[plugins] disable = ["that_entry_point_name"
 - `orphan_idempotent_skip`
 - `orphan_stash_failed`
 - `orphan_stashed`
+- `package_upgraded`
 - `prompt_overwritten`
 - `round_end`
+- `round_grace_extended`
 - `round_grace_kill`
 - `round_progress`
 - `round_start`

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.38}/docs/commands.md

@@ -24,7 +24,7 @@ are shared between `peek`, `watch`, and `monitor`.
 | `monitor` | Anomaly detection, narrate/events stream, or HTTP progress page |
 | `serve` | Long-running supervisor loop |
 | `round` | Run one round and exit |
-| `upgrade` | Round-boundary upgrade: stop → pip install → smoke → start (auto-rollback on smoke fail) |
+| `upgrade` | Package upgrade with service-mode gate: orchestrated stop/start for systemd --user; package-only otherwise |
 <!-- /gen:verb-table -->
 
 ## Lifecycle
@@ -76,6 +76,24 @@ Long-running supervisor loop. Traps SIGTERM (graceful stop), SIGINT (graceful),
 SIGUSR1 (cancel — forwards SIGINT to current round). Writes `serve.pid` and
 `round.pid`. `--once` runs a single round then exits (debug).
 
+### `agent-runner upgrade [--target VERSION] [--no-restart] [--config PATH]`
+
+Upgrade the agent-runner package. Behavior depends on the detected service mode:
+
+- **systemd --user service** (installed via `agent-runner install`): full
+  orchestrated flow — stop → pip install → smoke (`--version` + `peek`) →
+  start → emit `service_upgraded`. Auto-rollback on smoke failure.
+- **Anything else** (system unit, foreground, no config): package-only —
+  PEP 668-aware pip + `--version` smoke + pip-level rollback, emits
+  `package_upgraded`, prints the restart command. Never touches your running
+  service, never runs `sudo`.
+
+`--config` is optional: when omitted (or the file is absent), `upgrade` falls
+back to package-only mode automatically.
+
+`--no-restart` forces package-only even on a systemd --user host (upgrade the
+package now, restart your service yourself).
+
 ## Observation
 
 ### `agent-runner peek [flags]`

cli_agent_runner-0.1.38/docs/migrations/0.1.37.md

@@ -0,0 +1,65 @@
+# Migrating to 0.1.37
+
+## TL;DR
+
+```bash
+pip install --upgrade cli-agent-runner==0.1.37
+```
+
+If you run agent-runner as a `systemd --user` service (the kind `agent-runner
+install` creates), `agent-runner upgrade` works end-to-end as before. If you run
+it any other way (a systemd **system** unit, a foreground process, etc.), see
+"Upgrading a self-managed service" below.
+
+## What was fixed
+
+- `upgrade` no longer crashes when run from a directory without
+  `agent-runner.toml`.
+- `upgrade` handles Debian 12 / PEP 668 `externally-managed-environment`:
+  outside a venv it retries pip with `--break-system-packages` (plus `--user`
+  when the install lives in user-site).
+- `upgrade` no longer silently no-ops on a non-user-managed service, and never
+  suggests `agent-runner start` (which would start a second, conflicting
+  supervisor next to your real one).
+
+## How `upgrade` behaves now
+
+- **systemd --user service** → full flow: stop → pip → smoke → start →
+  `service_upgraded`, with auto-rollback on smoke failure. Unchanged.
+- **Anything else** (system unit / foreground / no config / `--no-restart`) →
+  **package-only**: PEP668-aware pip + `--version` smoke + pip-level rollback,
+  then it emits `package_upgraded` and prints the restart command for you to run.
+  It does not touch your running service.
+
+## Upgrading a self-managed service (e.g. systemd system unit)
+
+agent-runner never runs `sudo` and does not manage a unit it did not create.
+The canonical recipe:
+
+```bash
+# 1. Upgrade the package (PEP 668: --break-system-packages only touches ~/.local)
+python3 -m pip install --user --break-system-packages --upgrade cli-agent-runner==0.1.37
+# (or: agent-runner upgrade --target 0.1.37 --no-restart  — does the pip + smoke for you)
+
+# 2. Verify
+agent-runner --version          # → 0.1.37
+python3 -c "import your_plugin"  # if you use a plugin
+
+# 3. Restart your supervisor so the long-running process loads the new code
+sudo systemctl restart <your-unit>
+```
+
+Do **not** run `agent-runner start` on a system-unit host — it would spawn a
+second supervisor alongside the one systemd manages.
+
+## `package_upgraded` vs `service_upgraded`
+
+- `service_upgraded` — the live service is now running the new version (emitted
+  only in the orchestrated systemd --user flow).
+- `package_upgraded` — the on-disk package changed but the running supervisor
+  still runs the old code until you restart it (`restart_deferred: true`).
+
+## What did NOT change
+
+- The systemd --user happy path (the 0.1.13 flow) and its auto-rollback events.
+- Smoke design (fresh-subprocess `--version`, plus `peek` in the orchestrated flow).