fix(sdk): openrunner update works on PEP 668 hosts (2.38.3)

CHANGELOG.md

@@ -10,6 +10,16 @@
   with `DEBUG=true` is unaffected. See [`SECURITY.md`](SECURITY.md) for the
   disclosed defect and remediation steps. (GLA-22)
 
+## 2.38.3
+
+### Fixed
+
+- **`openrunner update` on PEP 668 systems** — the self-upgrade ran a plain
+  `pip install --upgrade` which Debian/Ubuntu system Python rejects with
+  `externally-managed-environment`. It now retries with
+  `--break-system-packages` (plus `--user` outside a venv), so `openrunner
+  update` works out of the box on managed hosts.
+
 ## 2.38.2
 
 ### Added

sdk/openrunner/__init__.py

@@ -181,7 +181,7 @@
 # openrunner.trace.patch_openai() syntax
 trace.patch_openai = _patch_openai  # type: ignore[attr-defined]
 
-__version__ = "2.38.2"
+__version__ = "2.38.3"
 
 logger = logging.getLogger("openrunner")
 

sdk/openrunner/cli.py

@@ -3079,7 +3079,9 @@ def update_cmd(pre: bool, no_reinstall: bool) -> None:
 
     Runs ``pip install --upgrade --no-cache-dir openrunner-sdk`` (the no-cache
     avoids a stale index serving an older wheel), then reinstalls the /openrunner
-    slash commands for all detected AI coding tools.
+    slash commands for all detected AI coding tools. On a PEP 668
+    externally-managed environment (Debian/Ubuntu system Python) the plain upgrade
+    is retried with ``--break-system-packages`` (+ ``--user`` outside a venv).
     """
     import subprocess
     import sys
@@ -3093,12 +3095,27 @@ def update_cmd(pre: bool, no_reinstall: bool) -> None:
         click.echo("Already up to date.")
         if no_reinstall:
             return
-    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "--no-cache-dir"]
-    if pre:
-        cmd.append("--pre")
-    cmd.append("openrunner-sdk")
-    click.echo("Upgrading: " + " ".join(cmd[2:]))
-    rc = subprocess.call(cmd)
+    def _pip(extra: list[str]) -> int:
+        cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "--no-cache-dir"]
+        if pre:
+            cmd.append("--pre")
+        cmd += extra
+        cmd.append("openrunner-sdk")
+        click.echo("Upgrading: " + " ".join(cmd[2:]))
+        return subprocess.call(cmd)
+
+    rc = _pip([])
+    if rc != 0:
+        # PEP 668 "externally-managed-environment" (Debian/Ubuntu system Python)
+        # rejects a plain pip upgrade. Retry with the flags that work for a
+        # user-site install; skip --user inside a venv (pip forbids it there).
+        in_venv = sys.prefix != sys.base_prefix
+        fallback = ["--break-system-packages"] + ([] if in_venv else ["--user"])
+        click.echo(
+            "Retrying with " + " ".join(fallback)
+            + " (externally-managed environment)..."
+        )
+        rc = _pip(fallback)
     if rc != 0:
         click.echo("pip upgrade failed.", err=True)
         raise SystemExit(rc)

sdk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openrunner-sdk"
-version = "2.38.2"
+version = "2.38.3"
 description = "OpenRunner SDK - W&B-compatible ML experiment tracking client"
 readme = "README.md"
 license = {text = "MIT"}