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

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

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-agent-runner
-Version: 0.1.36
+Version: 0.1.37
 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.37}/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.37'
+__version_tuple__ = version_tuple = (0, 1, 37)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.37}/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.37}/agent_runner/events.py

@@ -46,6 +46,7 @@ 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_KILL = "round_grace_kill"

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

@@ -165,6 +165,7 @@ 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_kill`

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.37}/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.37/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).

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.37}/docs/runbook.md

@@ -149,28 +149,35 @@ RestartSec=5
 
 ## Upgrading agent-runner
 
-### Recommended: single command
+`upgrade` detects the deployment topology and takes the safe path for it:
 
-```
-agent-runner upgrade [--target X.Y.Z] --config /path/to/agent-runner.toml
-```
+### Path 1 — systemd --user service (installed via `agent-runner install`)
+
+    agent-runner upgrade --target 0.1.37
+
+Does stop → pip → smoke → start, with auto-rollback on smoke failure.
 
 `--target` defaults to the latest version on PyPI. To pin a specific
 version (or roll back), pass `--target X.Y.Z`.
 
-### What it does
+### Path 2 — self-managed service (systemd system unit, foreground, etc.)
+
+`agent-runner upgrade` detects it does not manage your service and does a
+package-only upgrade (pip + smoke + rollback), then prints the restart command.
+It never runs `sudo` and never starts a service it didn't install. Restart your
+supervisor yourself:
+
+    python3 -m pip install --user --break-system-packages --upgrade cli-agent-runner==0.1.37
+    agent-runner --version
+    sudo systemctl restart <your-unit>
+
+> Do NOT run `agent-runner start` on a system-unit host — it spawns a second
+> supervisor next to the one systemd manages.
+
+Use `--no-restart` to force package-only mode even on a systemd --user host
+(upgrade the package now, restart later):
 
-1. Capture the currently-installed version via `agent_runner.__version__`
-2. Graceful stop (waits for the current round to finish)
-3. `pip install --upgrade cli-agent-runner[==<target>]`
-4. Smoke check the new binary in a fresh subprocess: `agent-runner --version`
-   + `agent-runner peek --json --config <path>`
-5. If smoke passes: start service. Emit `service_upgraded` event.
-6. If smoke fails: roll back to the previous version via
-   `pip install --force-reinstall cli-agent-runner==<previous>`, sanity-smoke,
-   start service, emit `service_upgrade_rolled_back` event. Exit code 1.
-7. If rollback itself fails (rare): emit `service_upgrade_rollback_failed`
-   event. Service stopped. Exit code 2. Manual intervention required.
+    agent-runner upgrade --target 0.1.37 --no-restart
 
 ### Manual rollback
 
@@ -188,19 +195,20 @@ fetch from there. To verify your index before upgrading: `pip config list`.
 
 | Symptom | Recovery |
 |---|---|
-| Stop is stuck | `agent-runner kill` → manual `pip install --upgrade ...` → `agent-runner start` |
-| pip install fails (network / no PyPI) | Service is left stopped. Run `agent-runner start` to resume the previous version. Retry upgrade later. |
-| Smoke fails, rollback succeeds | Service running on previous version. Investigate via `journalctl --user -u agent-runner@<project>` and the `service_upgrade_rolled_back` event's `failure_reason` field. File a bug report. |
-| Smoke fails, rollback ALSO fails (rare) | Service stopped. `service_upgrade_rollback_failed` event written (best-effort). Manually: `pip install --force-reinstall cli-agent-runner==<known-good>` then `systemctl restart agent-runner@<project>`. |
+| Stop is stuck (user mode) | `agent-runner kill` → manual `pip install --upgrade ...` → `agent-runner start` |
+| pip install fails (network / no PyPI) | Orchestrated: service left stopped, run `agent-runner start`. Package-only: service untouched, retry upgrade later. |
+| Smoke fails, rollback succeeds | Orchestrated: service running on previous version. Package-only: on-disk package restored. |
+| Smoke fails, rollback ALSO fails (rare) | Orchestrated: `service_upgrade_rollback_failed` event (service stopped). Manually: `pip install --force-reinstall cli-agent-runner==<known-good>` then `systemctl restart agent-runner@<project>`. |
 
 ### Postmortem trail
 
 Grep events.jsonl for upgrade history:
 ```
-grep -E "service_upgrad" {log_dir}/events-*.jsonl | jq .
+grep -E "service_upgrad|package_upgraded" {log_dir}/events-*.jsonl | jq .
 ```
-Three event kinds are interesting:
-- `service_upgraded` — clean upgrade
+Event kinds:
+- `service_upgraded` — clean orchestrated upgrade (live service on new version)
+- `package_upgraded` — package updated, restart deferred to operator
 - `service_upgrade_rolled_back` — attempted upgrade reverted (safety net fired)
 - `service_upgrade_rollback_failed` — critical: needs manual intervention
 

{cli_agent_runner-0.1.36 → cli_agent_runner-0.1.37}/tests/invariants/test_catalogs.py

@@ -213,3 +213,10 @@ def test_given_agent_usage_recorded_constant_when_exported_then_matches_kind():
 
     assert AGENT_USAGE_RECORDED == "agent_usage_recorded"
     assert AGENT_USAGE_RECORDED in _BUILTIN_KINDS
+
+
+def test_given_package_upgraded_kind_when_registered_then_in_known_event_kinds() -> None:
+    from agent_runner.events import _BUILTIN_KINDS, PACKAGE_UPGRADED
+
+    assert PACKAGE_UPGRADED == "package_upgraded"
+    assert PACKAGE_UPGRADED in _BUILTIN_KINDS