@agentsdock/server 1.0.10-beta.4 → 1.0.10-beta.6

package/README.md

@@ -20,6 +20,12 @@ the same prerequisites as the source installer: a trusted `uv`, Linux with a
 working user systemd session or Apple silicon macOS with a GUI launchd session,
 and the desired provider CLIs. It runs as the current user without `sudo`.
 
+Installation and recovery exclude temporary npm lifecycle `.bin` paths, npm
+`_npx` cache paths and npm node-gyp shims from the inherited PATH. Stable absolute
+user/provider/Node locations remain ordered; empty and relative entries are
+excluded. This lexical filter is not executable or symlink authorization and
+does not repair the persisted PATH of an existing installation.
+
 The npm entrypoint only permits a fresh default installation. It refuses an
 existing managed installation, legacy service, or custom installation roots;
 changing directories does not create a second service. Use AgentsDock's managed

package/npm/cli.cjs

@@ -23,6 +23,27 @@ No installation hooks run when this npm package is installed.
 `
 const ROOT_SELECTORS = ['AGENTS_SERVER_INSTALL_DIR', 'AGENTS_SERVER_CONFIG_DIR', 'AGENTS_SERVER_STATE_DIR', 'AGENTSDOCK_STATE_DIR', 'ZENITHBOT_AGENT_DIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME']
 
+function persistentPath(value) {
+  if (value === undefined) return undefined
+  // npm adds package/ancestor .bin directories and node-gyp shims to lifecycle
+  // PATH; npx additionally exposes its disposable cache. These must not become
+  // dependencies of a long-lived native service. Keep stable absolute user,
+  // provider and Node paths in order; do not trust npm env as an "original PATH".
+  // This is a lexical persistence filter, not executable/symlink authorization.
+  const entries = new Set()
+  for (const entry of String(value).split(path.delimiter)) {
+    if (!path.isAbsolute(entry) || /[\x00-\x1f\x7f]/.test(entry)) continue
+    const normalized = path.normalize(entry).replace(/\/$/, '') || '/'
+    if (/\/node_modules\/\.bin$/.test(normalized) ||
+        /\/_npx\/[^/]+(?:\/|$)/.test(normalized) ||
+        /\/node_modules\/(?:npm\/bin|@npmcli\/run-script\/lib)\/node-gyp-bin$/.test(normalized)) continue
+    // Do not rewrite retained paths across symlink/.. boundaries: lexical
+    // normalization is only for recognizing npm entries, not resolving paths.
+    entries.add(entry)
+  }
+  return entries.size ? [...entries].join(path.delimiter) : '/usr/bin:/bin:/usr/sbin:/sbin'
+}
+
 function parse(argv) {
   const [command = 'help', ...args] = argv
   if (['help', '--help', '-h', '--version'].includes(command)) {
@@ -236,6 +257,7 @@ async function run(argv, overrides = {}) {
   const payload = path.join(context.packageRoot, 'server')
   const payloadVersion = readRegular(path.join(payload, 'VERSION'), 200).toString('utf8').trim()
   if (payloadVersion !== metadata.version) throw new Error('Package and server payload versions do not match.')
+  if (Object.hasOwn(context.env, 'PATH')) context.env = { ...context.env, PATH: persistentPath(context.env.PATH) }
   if (command === 'recover') {
     const recovery = recoveryContext(context)
     if (!recovery) { context.print('No unfinished default server migration was found. No changes were made.'); return 0 }
@@ -290,4 +312,4 @@ async function run(argv, overrides = {}) {
 }
 
 if (require.main === module) run(process.argv.slice(2)).then(code => { process.exitCode = code }).catch(error => { process.stderr.write(`agentsdock-server: ${error.message}\n`); process.exitCode = 1 })
-module.exports = { parse, readRegular, ensureFreshInstall, recoveryContext, validateOrigin, run }
+module.exports = { parse, readRegular, ensureFreshInstall, recoveryContext, validateOrigin, persistentPath, run }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsdock/server",
-  "version": "1.0.10-beta.4",
+  "version": "1.0.10-beta.6",
   "description": "AgentsDock's self-hosted Python server and explicit installation CLI",
   "license": "Apache-2.0",
   "repository": {

package/server/VERSION

@@ -1 +1 @@
-1.0.10-beta.4
+1.0.10-beta.6

package/server/agent_server.py

@@ -67519,8 +67519,8 @@ async def run_opencode_process(
       - The workspace is explicitly passed as ``--dir`` as well as cwd.
       - There is no init event. Every event already carries the sessionID, so
         the session is considered started at the first event of any kind.
-      - The turn ends at a ``step_finish`` whose reason is not ``tool-calls``;
-        there is no separate terminal result event.
+      - An explicit completion ``step_finish`` ends the turn; ``tool-calls``
+        continues it and invalid/unknown finishes fail closed.
       - Usage is reported per step and must be accumulated, not overwritten.
     """
     from opencode_agent_client import (
@@ -68429,10 +68429,24 @@ async def run_opencode_process(
                     opencode_usage,
                     normalized.get("usage") or {},
                 )
-                # A turn is a sequence of steps. "tool-calls" means another
-                # step follows; anything else ends the turn, and there is no
-                # separate terminal result event to wait for.
-                if str(normalized.get("reason") or "") != "tool-calls":
+                # Only explicit completion reasons end a turn. In particular,
+                # HTML-200/empty streams can yield "unknown" while the CLI
+                # immediately requests another step; waiting for exit lets it
+                # loop and hides the invalid response behind a cleanup error.
+                finish_reason = str(normalized.get("reason") or "")
+                if finish_reason not in {"tool-calls", "stop", "length", "content-filter"}:
+                    stream_error = (
+                        "OpenCode did not receive a valid completion from the "
+                        "model API. Check the endpoint URL, selected protocol "
+                        "and streaming support. The run was stopped to prevent "
+                        "repeated requests."
+                    )
+                    await terminate_process_tree(
+                        proc,
+                        grace=OPENCODE_GUARD_TEARDOWN_GRACE_SECONDS,
+                    )
+                    break
+                if finish_reason != "tool-calls":
                     await flush_opencode_reasoning()
                     terminal_event_seen = True
                     try:

package/server/codex_provider.py

@@ -814,6 +814,17 @@ def safe_model_label(label, model):
     return label.strip() if isinstance(label, str) and label.strip() and len(label) <= 160 and all(ord(c) >= 32 and ord(c) != 127 for c in label) else model
 
 
+def endpoint_api_base_url(base: str, protocol: str) -> str:
+    """Resolve the API prefix, retaining the gateway's path and saved identity.
+
+    Anthropic settings accept either a root or its /v1 API prefix. AI SDK
+    adapters append /messages, unlike Claude Code which appends /v1/messages.
+    OpenAI-compatible settings already specify their complete API prefix.
+    """
+    base = base.rstrip("/")
+    return base + "/v1" if protocol == "anthropic" and not base.endswith("/v1") else base
+
+
 def endpoint_model_catalog(selected: dict, *, protocol="responses") -> dict:
     """Read only this endpoint's inventory. Never use CLI models or infer a default.
 
@@ -823,8 +834,7 @@ def endpoint_model_catalog(selected: dict, *, protocol="responses") -> dict:
     base = selected["base_url"].rstrip("/")
     parsed = urlsplit(base)
     router = parsed.scheme == "https" and parsed.netloc in {"openrouter.ai", "eu.openrouter.ai"} and parsed.path in {"/api", "/api/v1"}
-    target = (base.removesuffix("/v1") + "/v1/models/user") if router else base + (
-        "/v1/models" if protocol == "anthropic" and not base.endswith("/v1") else "/models")
+    target = (base.removesuffix("/v1") + "/v1/models/user") if router else endpoint_api_base_url(base, protocol) + "/models"
     headers = {"Accept": "application/json", "anthropic-version": "2023-06-01"}
     header = selected.get("auth_header", "bearer")
     headers["x-api-key" if header == "x-api-key" else "Authorization"] = selected["api_key"] if header == "x-api-key" else "Bearer " + selected["api_key"]

package/server/execution_activation.py

@@ -249,7 +249,7 @@ def require_retired_legacy_intent(layout: files.ExecutionLayout, previous: Any,
 
     root = layout.install_root
     def no_journal():
-        for name in (".activation-transaction", ".execution-transaction", ".execution-uninstall.json"):
+        for name in (".activation-transaction", ".execution-transaction", ".execution-uninstall.json", ".execution-lifecycle.json"):
             if (root / name).exists() or (root / name).is_symlink():
                 raise RuntimeError("a lifecycle journal still owns the previous recovery intent")
     no_journal()

package/server/execution_control.py

@@ -186,6 +186,10 @@ class ExecutionControl:
                 if length not in {None, 0}:
                     raise ExecutionControlError(400, "Status requests do not accept a body")
                 result = await self.status_callback()
+                # This running worker understands execution-lifecycle startup
+                # holds. New CLIs must not stop an older retained worker and
+                # discover only after restart that its queue was not held.
+                result = {**result, "native_lifecycle_protocol": 1}
             else:
                 content_types = _header_values(headers, b"content-type")
                 if (len(content_types) != 1 or content_types[0].lower()

package/server/execution_install.py

@@ -329,6 +329,36 @@ def layout_manifest(layout: ExecutionLayout) -> dict[str, Any]:
             "retained_releases": sorted({str(layout.worker_release), str(layout.gateway_release)})}
 
 
+def installed_layout(root: Path) -> ExecutionLayout:
+    """Validate authoritative bindings without discarding retained rollback history."""
+    root = _path(root)
+    data, _mode = _read_file(root / LAYOUT_NAME, private=True)
+    value = json.loads(data)
+    if not isinstance(value, dict):
+        raise ValueError("installed execution layout is invalid")
+    layout = ExecutionLayout.from_dict(value.get("layout"))
+    expected = layout_manifest(layout)
+    retained = value.get("retained_releases")
+    if (layout.install_root != root or set(value) != set(expected)
+            or {key: item for key, item in value.items() if key != "retained_releases"}
+            != {key: item for key, item in expected.items() if key != "retained_releases"}
+            or not isinstance(retained, list) or not all(isinstance(item, str) for item in retained)
+            or len(retained) != len(set(retained))
+            or not set(expected["retained_releases"]).issubset(retained)):
+        raise ValueError("installed execution layout does not match its runtime")
+    # Old monolith releases may have no execution_service.py. Retention is not
+    # activation authority, but every advisory entry must be an owned, real
+    # version directory inside this installation (never an arbitrary path).
+    for item in retained:
+        path = _path(item)
+        if path.parent != root / "releases" or path.name.startswith("."):
+            raise ValueError("retained release is outside the installation")
+        _owned_directory(path)
+        version, _mode = _read_file(path / "VERSION")
+        _text(version.decode().strip())
+    return layout
+
+
 def prepare_runtime(layout: ExecutionLayout) -> None:
     """Create private IPC state; never rotate an existing control token."""
     from execution_transport import ensure_execution_secret
@@ -399,6 +429,10 @@ def stage(layout: ExecutionLayout, *, scope: str, prior_services: dict[str, Any]
     legacy = layout.install_root / ".activation-transaction"
     if legacy.exists() or legacy.is_symlink():
         raise RuntimeError("legacy activation recovery must finish before execution activation")
+    for name in (".execution-lifecycle.json", ".execution-uninstall.json"):
+        marker = layout.install_root / name
+        if marker.exists() or marker.is_symlink():
+            raise RuntimeError("native lifecycle ownership must finish before execution activation")
     if layout.transaction_dir.exists() or layout.transaction_dir.is_symlink():
         raise FileExistsError("an execution activation is already pending")
     prior_layout = _snapshot(layout.manifest_path)
@@ -674,6 +708,19 @@ def pending_worker_operation(root: Path, runtime_root: Path) -> str | None:
     journal = root / TRANSACTION_NAME
     outer = root / ".activation-transaction"
     uninstall = root / ".execution-uninstall.json"
+    lifecycle = root / ".execution-lifecycle.json"
+    if lifecycle.exists() or lifecycle.is_symlink():
+        if any(path.exists() or path.is_symlink() for path in (outer, journal)):
+            raise RuntimeError("activation and lifecycle both claim execution ownership")
+        from execution_manage import pending_lifecycle_operation
+        operation = pending_lifecycle_operation(root, runtime_root)
+        if uninstall.exists() or uninstall.is_symlink():
+            # An interrupted owned-stop -> uninstall adoption may retain both
+            # journals, but they must describe the very same sealed operation.
+            from execution_uninstall import pending_uninstall_operation
+            if pending_uninstall_operation(root, runtime_root) != operation:
+                raise RuntimeError("uninstall and lifecycle ownership conflict")
+        return operation
     if uninstall.exists() or uninstall.is_symlink():
         if outer.exists() or outer.is_symlink() or journal.exists() or journal.is_symlink():
             raise RuntimeError("activation and uninstall both claim execution ownership")
@@ -714,13 +761,7 @@ def active_worker_release(root: Path) -> Path | None:
         data, _mode = _read_file(root / LAYOUT_NAME, private=True)
     except FileNotFoundError:
         return None
-    value = json.loads(data)
-    if not isinstance(value, dict) or value.get("format") != FORMAT:
-        raise ValueError("installed execution layout is invalid")
-    layout = ExecutionLayout.from_dict(value.get("layout"))
-    if layout.install_root != root or value != layout_manifest(layout):
-        raise ValueError("installed execution layout no longer matches its runtime")
-    return layout.worker_release
+    return installed_layout(root).worker_release
 
 
 def main(argv: list[str] | None = None) -> None:

package/server/execution_manage.py

@@ -12,7 +12,9 @@ from __future__ import annotations
 
 import argparse
 import base64
+from contextlib import ExitStack
 import errno
+import hashlib
 import json
 import os
 from pathlib import Path
@@ -25,6 +27,7 @@ import sys
 import time
 from typing import Any, Callable
 import urllib.parse
+import uuid
 
 import execution_install as files
 from execution_transport import _read_secret
@@ -216,6 +219,35 @@ class NativeServices:
             raise RuntimeError("native service is transitioning; retry after it settles")
         return states
 
+    def validate_registered_bindings(self) -> None:
+        """Reject foreign or stale manager-loaded jobs without exposing output."""
+        for role in ("worker", "gateway"):
+            path = str(self.layout.service_path(role))
+            if self.layout.platform == "Linux":
+                result = self._command(["systemctl", "--user", "show", self._unit(role), "--no-pager",
+                    "--property=FragmentPath,DropInPaths,NeedDaemonReload"])
+                values = {}
+                for line in result.stdout.splitlines():
+                    key, separator, value = line.partition("=")
+                    if not separator or key in values:
+                        raise RuntimeError("systemd returned ambiguous registered bindings")
+                    values[key] = value
+                if values != {"FragmentPath": path, "DropInPaths": "", "NeedDaemonReload": "no"}:
+                    raise RuntimeError("native unit registration is foreign, overridden, or stale")
+            else:
+                result = self._command(["/bin/launchctl", "print", self._target(role)], allow_failure=True)
+                if result.returncode:
+                    if "Could not find service" in result.stderr:
+                        continue  # bootout removed the job; exact plist is checked separately.
+                    raise RuntimeError("launchd registration ownership is unknown")
+                paths = re.findall(r"(?m)^\s*path = (.+)$", result.stdout)
+                programs = re.findall(r"(?m)^\s*program = (.+)$", result.stdout)
+                arguments = re.findall(r"(?ms)^\s*arguments = \{\n(.*?)^\s*\}", result.stdout)
+                expected = files.service_arguments(self.layout, role)
+                if (paths != [path] or programs != [expected[0]] or len(arguments) != 1
+                        or [line.strip() for line in arguments[0].splitlines() if line.strip()] != expected):
+                    raise RuntimeError("native launchd registration does not match the installed service")
+
     def stop(self, role: str) -> None:
         state = self._observe(role)
         if state["state"] in {"absent", "stopped"}:
@@ -426,6 +458,278 @@ class WorkerControl:
                 "maintenance_held": worker.get("maintenance_held")}
 
 
+LIFECYCLE_NAME = ".execution-lifecycle.json"
+
+
+def read_lifecycle_intent(layout: files.ExecutionLayout) -> dict | None:
+    """Read owned stop/restart evidence; never repair or normalize user state."""
+    from execution_preparation import _check_binding
+    try:
+        data, _mode = files._read_file(layout.install_root / LIFECYCLE_NAME, private=True)
+    except FileNotFoundError:
+        return None
+    value = json.loads(data)
+    expected = {"format", "operation_id", "layout_sha256", "identities", "server_identity",
+                "worker_pid", "gateway_pid", "worker_instance_id", "lease_id", "phase", "started"}
+    if (not isinstance(value, dict) or set(value) != expected or type(value["format"]) is not int
+            or value["format"] != 1 or value["phase"] not in {"prepared", "sealed", "stopped", "starting", "releasing"}
+            or not isinstance(value["operation_id"], str)
+            or str(uuid.UUID(value["operation_id"])) != value["operation_id"]
+            or any(type(value[key]) is not int or value[key] <= 0 for key in ("worker_pid", "gateway_pid"))
+            or any(not isinstance(value[key], str) or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", value[key]) is None
+                   for key in ("server_identity", "worker_instance_id"))
+            or (value["lease_id"] is not None and (not isinstance(value["lease_id"], str)
+                or str(uuid.UUID(value["lease_id"])) != value["lease_id"]))):
+        raise ValueError("native lifecycle intent is invalid")
+    started = value["started"]
+    if started is not None and (not isinstance(started, dict) or set(started) != {"pid", "instance_id"}
+            or type(started["pid"]) is not int or started["pid"] <= 0
+            or not isinstance(started["instance_id"], str)
+            or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", started["instance_id"]) is None):
+        raise ValueError("native lifecycle startup identity is invalid")
+    if (value["phase"] == "releasing" and started is None
+            or value["phase"] not in {"starting", "releasing"} and started is not None
+            or value["phase"] != "prepared" and value["lease_id"] is None):
+        raise ValueError("native lifecycle phase lacks its admission evidence")
+    paths = {"root": layout.install_root, "worker": layout.worker_release,
+             "gateway": layout.gateway_release, "config": layout.config_root, "state": layout.state_root}
+    if not isinstance(value["identities"], dict) or set(value["identities"]) != set(paths):
+        raise ValueError("native lifecycle directory identities are invalid")
+    for name, path in paths.items():
+        _check_binding(path, value["identities"][name])
+    manifest, _mode = files._read_file(layout.manifest_path, private=True)
+    if hashlib.sha256(manifest).hexdigest() != value["layout_sha256"]:
+        raise RuntimeError("installed layout changed after lifecycle admission")
+    return value
+
+
+def pending_lifecycle_operation(root: Path, runtime_root: Path) -> str:
+    layout = files.installed_layout(root)
+    intent = read_lifecycle_intent(layout)
+    if intent is None or files._path(runtime_root) != layout.worker_release:
+        raise RuntimeError("worker is outside the retained lifecycle operation")
+    marker = root / ".execution-uninstall.json"
+    if marker.exists() or marker.is_symlink():
+        from execution_uninstall import _read_intent
+        removal = _read_intent(root, layout)
+        if (intent["phase"] != "stopped" or removal is None
+                or removal["operation_id"] != intent["operation_id"]
+                or removal["server_identity"] != intent["server_identity"]):
+            raise RuntimeError("uninstall and lifecycle ownership conflict")
+    return intent["operation_id"]
+
+
+def retire_lifecycle_intent(layout: files.ExecutionLayout, intent: dict) -> None:
+    if read_lifecycle_intent(layout) != intent:
+        raise RuntimeError("native lifecycle intent changed before retirement")
+    (layout.install_root / LIFECYCLE_NAME).unlink()
+    files._fsync_directory(layout.install_root)
+
+
+class LifecycleController:
+    """Idle-only control of an installed pair, not an installer or force repair.
+
+    Failures retain an exact operation journal and any sealed admission hold.
+    Retry may finish that operation; an unjournaled broken/stopped installation
+    or a changed worker epoch is never guessed safe. Explicit start releases
+    startup admission only after both components have authenticated health.
+    """
+
+    def __init__(self, layout: files.ExecutionLayout, *, services: NativeServices | None = None,
+                 control: WorkerControl | None = None, health_timeout: float = 30.0):
+        self.layout = layout
+        self.services = services or NativeServices(layout)
+        self.control = control or WorkerControl(services=self.services)
+        self.health_timeout = health_timeout
+
+    def _save(self, intent: dict, **changes) -> dict:
+        if read_lifecycle_intent(self.layout) != intent:
+            raise RuntimeError("native lifecycle intent changed")
+        updated = {**intent, **changes}
+        files._atomic_write(self.layout.install_root / LIFECYCLE_NAME, files._json_bytes(updated))
+        return updated
+
+    def _unchanged(self, originals: dict) -> None:
+        from execution_uninstall import _service_files, _no_pending_update
+        from update_handoff import _no_activation
+        _no_activation(self.layout.install_root)
+        marker = self.layout.install_root / ".execution-uninstall.json"
+        if marker.exists() or marker.is_symlink():
+            raise RuntimeError("uninstall owns this native lifecycle")
+        _no_pending_update(self.layout)
+        if _service_files(self.layout) != originals:
+            raise RuntimeError("native service bindings changed during lifecycle operation")
+        self.services.validate_registered_bindings()
+
+    def _new_intent(self, prior: dict) -> dict:
+        from execution_preparation import _binding
+        receipt = self.control.receipt(self.layout, self.services)
+        record, status = self.control.status(self.layout)
+        if type(status.get("native_lifecycle_protocol")) is not int or status["native_lifecycle_protocol"] != 1:
+            raise RuntimeError("installed worker does not support safe paired lifecycle commands; update the installed server through its signed managed update first")
+        if (receipt.get("worker_pid") != prior["worker"].get("pid")
+                or receipt.get("gateway_pid") != prior["gateway"].get("pid")
+                or receipt.get("worker_release") != str(self.layout.worker_release)
+                or record.get("pid") != receipt.get("worker_pid")
+                or record.get("instance_id") != receipt.get("worker_instance_id")
+                or status.get("idle") is not True or status.get("lease") is not None):
+            raise RuntimeError("execution is busy, changed, or another operation owns admission; no services stopped")
+        manifest, _mode = files._read_file(self.layout.manifest_path, private=True)
+        intent = {"format": 1, "operation_id": str(uuid.uuid4()), "phase": "prepared", "lease_id": None,
+                  "started": None, "server_identity": receipt.get("server_identity"),
+                  "worker_pid": receipt["worker_pid"], "gateway_pid": receipt["gateway_pid"],
+                  "worker_instance_id": receipt["worker_instance_id"],
+                  "layout_sha256": hashlib.sha256(manifest).hexdigest(),
+                  "identities": {name: _binding(path) for name, path in {
+                      "root": self.layout.install_root, "worker": self.layout.worker_release,
+                      "gateway": self.layout.gateway_release, "config": self.layout.config_root,
+                      "state": self.layout.state_root}.items()}}
+        if not isinstance(intent["server_identity"], str) or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", intent["server_identity"]) is None:
+            raise RuntimeError("authenticated server identity is unavailable")
+        if self.services.snapshot() != prior or read_lifecycle_intent(self.layout) is not None:
+            raise RuntimeError("native ownership changed before lifecycle admission")
+        files._atomic_write(self.layout.install_root / LIFECYCLE_NAME, files._json_bytes(intent))
+        return intent
+
+    def _stop(self, intent: dict, originals: dict) -> dict:
+        from execution_uninstall import _owned_lease, _no_provider_children
+        if intent["phase"] in {"starting", "releasing"}:
+            raise RuntimeError("an owned start must finish before another stop")
+        self._unchanged(originals)
+        prior = self.services.snapshot()
+        if any(prior[role].get("state") not in {"running", "stopped", "absent"} for role in ("worker", "gateway")):
+            raise RuntimeError("native lifecycle state is uncertain")
+        if prior["worker"].get("state") == "running":
+            record, status = self.control.status(self.layout)
+            if (record.get("pid") != intent["worker_pid"] or prior["worker"].get("pid") != intent["worker_pid"]
+                    or record.get("instance_id") != intent["worker_instance_id"]
+                    or record.get("release_root") != str(self.layout.worker_release)):
+                raise RuntimeError("worker epoch changed after lifecycle admission")
+            if intent["lease_id"] is not None and (status.get("lease") or {}).get("lease_id") != intent["lease_id"]:
+                raise RuntimeError("owned lifecycle admission changed")
+            try:
+                sealed = self.control.seal_for_stop(self.layout, intent["operation_id"], intent["worker_pid"])
+            except (OSError, ValueError, RuntimeError) as error:
+                raise RuntimeError("lifecycle admission was not confirmed; its owned retry evidence was retained and no service was stopped by this attempt; retry the same command when work is idle (a changed worker requires ownership recovery)") from error
+            if sealed["record"] != record:
+                raise RuntimeError("worker changed while lifecycle admission was sealed")
+            intent = self._save(intent, phase="sealed", lease_id=sealed["lease"]["lease_id"])
+            self._unchanged(originals)
+            if self.services.snapshot() != prior:
+                raise RuntimeError("native jobs changed after lifecycle admission")
+            for role in ("gateway", "worker"):
+                current = self.services.snapshot()[role]
+                if current.get("state") in {"stopped", "absent"}:
+                    self.services.set_enabled(role, False)
+                    continue
+                if current.get("state") != "running" or current.get("pid") != intent[role + "_pid"]:
+                    raise RuntimeError("native process changed before its authorized stop")
+                if role == "worker":
+                    now_record, now_status = self.control.status(self.layout)
+                    if (now_record != sealed["record"] or now_status.get("lease") != sealed["lease"]
+                            or now_status.get("idle") is not True):
+                        raise RuntimeError("worker admission changed before its authorized stop")
+                self._unchanged(originals)
+                self.services.set_enabled(role, False)
+                self.services.stop(role)
+        elif intent["lease_id"] is None or prior["gateway"].get("state") == "running":
+            raise RuntimeError("stopped worker lacks an owned completed shutdown")
+        else:
+            for role in ("gateway", "worker"):
+                self.services.set_enabled(role, False)
+        if any(self.services.snapshot()[role].get("state") not in {"stopped", "absent"} for role in ("worker", "gateway")):
+            raise RuntimeError("both native services must stop before lifecycle completion")
+        with _owned_lease(self.layout.state_root / "admin/state-owner.lock"):
+            _no_provider_children(self.layout.state_root)
+            self._unchanged(originals)
+            return self._save(intent, phase="stopped")
+
+    def _wait_worker(self, intent: dict) -> dict:
+        deadline = time.monotonic() + self.health_timeout
+        while True:
+            try:
+                record, status = self.control.status(self.layout)
+                native = self.services.snapshot()["worker"]
+                if (native.get("state") != "running" or native.get("pid") != record.get("pid")
+                        or record.get("release_root") != str(self.layout.worker_release)):
+                    raise RuntimeError("native worker does not own startup admission")
+                started = {"pid": record["pid"], "instance_id": record["instance_id"]}
+                if intent["started"] is not None and started != intent["started"]:
+                    raise RuntimeError("worker epoch changed during lifecycle startup")
+                if intent["phase"] != "releasing" or status.get("lease") is not None:
+                    self.control.require_startup_hold(self.layout, intent["operation_id"])
+                return started
+            except (OSError, ValueError, RuntimeError) as error:
+                if time.monotonic() >= deadline:
+                    raise RuntimeError("owned native worker did not reach held startup; retry start after recovery") from error
+                time.sleep(0.1)
+
+    def _start(self, intent: dict, originals: dict) -> dict:
+        from execution_uninstall import _owned_lease, _no_provider_children
+        if intent["phase"] == "stopped":
+            with _owned_lease(self.layout.state_root / "admin/state-owner.lock"):
+                _no_provider_children(self.layout.state_root)
+                self._unchanged(originals)
+                if any(self.services.snapshot()[role].get("state") not in {"stopped", "absent"} for role in ("worker", "gateway")):
+                    raise RuntimeError("stopped native jobs changed before authorized start")
+                intent = self._save(intent, phase="starting")
+        if intent["phase"] not in {"starting", "releasing"}:
+            raise RuntimeError("native shutdown must complete before starting")
+        self._unchanged(originals)
+        native = self.services.snapshot()
+        if native["worker"].get("state") in {"stopped", "absent"}:
+            if intent["started"] is not None or native["gateway"].get("state") == "running":
+                raise RuntimeError("owned startup process disappeared; automatic replacement is refused")
+            self.services.start("worker")
+        started = self._wait_worker(intent)
+        if intent["started"] is None:
+            intent = self._save(intent, started=started)
+        self._unchanged(originals)
+        gateway = self.services.snapshot()["gateway"]
+        if gateway.get("state") in {"stopped", "absent"}:
+            self.services.start("gateway")
+        receipt = ActivationController(self.layout, services=self.services, control=self.control,
+                                       health_timeout=self.health_timeout)._wait_receipt(self.layout)
+        if (receipt.get("server_identity") != intent["server_identity"]
+                or receipt.get("worker_pid") != intent["started"]["pid"]
+                or receipt.get("worker_instance_id") != intent["started"]["instance_id"]):
+            raise RuntimeError("authenticated lifecycle identity changed")
+        self._wait_worker(intent)
+        self._unchanged(originals)
+        intent = self._save(intent, phase="releasing")
+        self.control.release(self.layout, intent["operation_id"])
+        retire_lifecycle_intent(self.layout, intent)
+        return {"ok": True, "status": "running", "receipt": receipt}
+
+    def run(self, action: str) -> dict:
+        if action not in {"start", "stop", "restart"}:
+            raise ValueError("unknown native lifecycle action")
+        from execution_uninstall import _service_files, _hold_preparation_leases
+        from execution_recovery import require_retired_owners
+        with InstallationLock(self.layout.install_root), ExitStack() as leases:
+            if files.installed_layout(self.layout.install_root) != self.layout:
+                raise RuntimeError("native lifecycle layout changed")
+            originals = _service_files(self.layout)
+            self._unchanged(originals)
+            require_retired_owners(self.layout.install_root)
+            _hold_preparation_leases(self.layout.install_root, leases)
+            intent = read_lifecycle_intent(self.layout)
+            if intent is None:
+                prior = self.services.snapshot()
+                if any(prior[role].get("state") != "running" for role in ("worker", "gateway")):
+                    raise RuntimeError("unjournaled stopped or broken services require ownership recovery")
+                if action == "start":
+                    return {"ok": True, "status": "running", "receipt": self.control.receipt(self.layout, self.services)}
+                intent = self._new_intent(prior)
+            if intent["phase"] not in {"starting", "releasing"}:
+                intent = self._stop(intent, originals)
+            if action == "stop":
+                if intent["phase"] != "stopped":
+                    raise RuntimeError("retry start to finish the pending owned startup")
+                return {"ok": True, "status": "stopped"}
+            return self._start(intent, originals)
+
+
 class ActivationController:
     def __init__(self, layout: files.ExecutionLayout, *, services: NativeServices | None = None,
                  control: WorkerControl | None = None, health_timeout: float = 30.0) -> None:

package/server/execution_recovery.py

@@ -107,7 +107,7 @@ def _source_inventory(source: Path) -> dict[str, str]:
 
 
 def _conflicts(root: Path) -> None:
-    for name in (".execution-transaction", ".execution-uninstall.json"):
+    for name in (".execution-transaction", ".execution-uninstall.json", ".execution-lifecycle.json"):
         if (root / name).exists() or (root / name).is_symlink():
             raise RuntimeError("another lifecycle operation owns this installation")
 

package/server/execution_uninstall.py

@@ -205,6 +205,7 @@ def uninstall(root: Path, *, config_root: Path, state_root: Path, home: Path,
         native = services or NativeServices(layout)
         control = control or WorkerControl()
         originals = _service_files(layout)
+        native.validate_registered_bindings()
         _no_pending_update(layout)
         _hold_preparation_leases(root, leases)
         _removable_tree(root)
@@ -216,6 +217,24 @@ def uninstall(root: Path, *, config_root: Path, state_root: Path, home: Path,
         if intent is not None and intent["purge_state"] != purge_state:
             raise RuntimeError("retry must preserve the existing uninstall data-removal choice")
         prior = native.snapshot()
+        from execution_manage import read_lifecycle_intent, retire_lifecycle_intent
+        lifecycle = read_lifecycle_intent(layout)
+        if lifecycle is not None:
+            # Adopt only a proven completed owned stop. Never start a worker
+            # merely to remove it: that could run saved scheduled/queued work.
+            if (lifecycle["phase"] != "stopped"
+                    or any(prior[role].get("state") not in {"stopped", "absent"} for role in ("worker", "gateway"))):
+                raise RuntimeError("finish the owned lifecycle stop before uninstalling")
+            native.validate_registered_bindings()
+            with _owned_lease(state_root / "admin/state-owner.lock"):
+                _no_provider_children(state_root)
+                if intent is None:
+                    intent = _write_intent(root, layout, lifecycle["operation_id"], purge_state,
+                                           lifecycle["server_identity"])
+                elif (intent["operation_id"] != lifecycle["operation_id"]
+                        or intent["server_identity"] != lifecycle["server_identity"]):
+                    raise RuntimeError("uninstall and lifecycle journal ownership conflict")
+                retire_lifecycle_intent(layout, lifecycle)
         # An interrupted graceful stop can precede the stopped-phase write.
         # The exact intent, empty child registry and exclusive state lease
         # below supply the missing proof; an unjournaled stopped install fails.

package/server/execution_update_status.py

@@ -6,7 +6,6 @@ activation remains incomplete even after it has published the new files.
 """
 from __future__ import annotations
 
-import json
 from pathlib import Path
 from typing import Any
 
@@ -22,17 +21,11 @@ def current_components(
     """Read-only proof, invoked off the server event loop for an equal-version ensure."""
     root = files._path(root)
     files._owned_directory(root)
-    for name in (".activation-transaction", ".execution-transaction"):
+    for name in (".activation-transaction", ".execution-transaction", ".execution-lifecycle.json", ".execution-uninstall.json"):
         journal = root / name
         if journal.exists() or journal.is_symlink():
             return False
-    data, _mode = files._read_file(root / files.LAYOUT_NAME, private=True)
-    document = json.loads(data)
-    if not isinstance(document, dict) or document.get("format") != files.FORMAT:
-        raise ValueError("installed execution layout is invalid")
-    layout = files.ExecutionLayout.from_dict(document.get("layout"))
-    if layout.install_root != root or document != files.layout_manifest(layout):
-        raise ValueError("installed execution layout does not match its runtime")
+    layout = files.installed_layout(root)
     receipt: dict[str, Any] = WorkerControl().receipt(layout, NativeServices(layout))
     if (receipt.get("server_identity") != expected_server_identity
             or receipt.get("worker_instance_id") != expected_worker_instance):
@@ -45,5 +38,5 @@ def current_components(
     # Do not claim completion over the operation that just acquired ownership.
     return complete and not any(
         (root / name).exists() or (root / name).is_symlink()
-        for name in (".activation-transaction", ".execution-transaction")
+        for name in (".activation-transaction", ".execution-transaction", ".execution-lifecycle.json", ".execution-uninstall.json")
     )

package/server/opencode_agent_client.py

@@ -156,6 +156,11 @@ def opencode_error_message(error: Any) -> str:
     if not message:
         message = str(error.get("message") or "")
     name = str(error.get("name") or "")
+    status = data.get("statusCode") if isinstance(data, dict) else None
+    if type(status) is int and 100 <= status <= 599:
+        # Preserve useful HTTP diagnostics without exposing request headers,
+        # gateway response bodies or URLs that may contain credentials.
+        name = f"{name} (HTTP {status})" if name else f"HTTP {status}"
     if message and name:
         return f"{name}: {message}"
     return message or name

package/server/provider_connections.py

@@ -22,9 +22,12 @@ import httpx
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse
 
-from codex_provider import validate_selection, validate_model, endpoint_model_catalog
+from codex_provider import validate_selection, validate_model, endpoint_model_catalog, endpoint_api_base_url
 
 MAX_BODY_BYTES = 16 * 1024
+# Reasoning can consume output tokens before the short visible check answer.
+# Keep this explicit probe bounded and single-shot, including for such models.
+MODEL_CHECK_MAX_OUTPUT_TOKENS = 256
 PROTOCOLS = {"claude": {"anthropic"}, "opencode": {"anthropic", "chat_completions", "responses"}, "cursor": {"cursor"}}
 RESULTS = {"verified", "authentication_failed", "rate_limited", "unsupported", "connection_failed", "invalid_response", "model_required", "cli_update_required"}
 
@@ -277,7 +280,7 @@ class ConnectionStore:
         model = require_model(value)
         config = json.loads(env.get("OPENCODE_CONFIG_CONTENT") or "{}")
         adapter = {"anthropic": "@ai-sdk/anthropic", "chat_completions": "@ai-sdk/openai-compatible", "responses": "@ai-sdk/openai"}[value["protocol"]]
-        options = {"baseURL": value["base_url"], "apiKey": "{env:AGENTSDOCK_CUSTOM_API_KEY}"}
+        options = {"baseURL": endpoint_api_base_url(value["base_url"], value["protocol"]), "apiKey": "{env:AGENTSDOCK_CUSTOM_API_KEY}"}
         if value["protocol"] == "anthropic" and value["auth_header"] == "bearer":
             options["headers"] = {"Authorization": "Bearer {env:AGENTSDOCK_CUSTOM_API_KEY}", "x-api-key": ""}
         config.setdefault("provider", {})["agentsdock_custom"] = {"npm": adapter, "name": "Custom endpoint", "options": options, "models": {model: {"name": model}}}
@@ -361,8 +364,7 @@ async def probe_credentials(selected: dict) -> str:
         headers["Authorization"] = "Bearer " + selected["api_key"]
     url = urlsplit(base)
     router = url.scheme == "https" and url.netloc == "openrouter.ai" and url.path in {"/api", "/api/v1"}
-    target = "https://openrouter.ai/api/v1/key" if router else base + (
-        "/v1/models" if protocol == "anthropic" and not base.endswith("/v1") else "/models")
+    target = "https://openrouter.ai/api/v1/key" if router else endpoint_api_base_url(base, protocol) + "/models"
     async def send():
         async with httpx.AsyncClient(timeout=10, follow_redirects=False, trust_env=False) as client:
             async with client.stream("GET", target, headers=headers) as response:
@@ -403,18 +405,18 @@ async def probe(selected: dict) -> str:
         headers["x-api-key"] = selected["api_key"]
     else:
         headers["Authorization"] = "Bearer " + selected["api_key"]
-    base = selected["base_url"]
+    base = endpoint_api_base_url(selected["base_url"], protocol)
     prompt = "Connection check. Reply with OK only."
     if protocol == "anthropic":
-        suffix = "/messages" if base.endswith("/v1") else "/v1/messages"
+        suffix = "/messages"
         headers["anthropic-version"] = "2023-06-01"
-        body = {"model": selected["model"], "max_tokens": 32, "messages": [{"role": "user", "content": prompt}]}
+        body = {"model": selected["model"], "max_tokens": MODEL_CHECK_MAX_OUTPUT_TOKENS, "messages": [{"role": "user", "content": prompt}]}
     elif protocol == "responses":
         suffix = "/responses"
-        body = {"model": selected["model"], "max_output_tokens": 64, "input": prompt, "store": False}
+        body = {"model": selected["model"], "max_output_tokens": MODEL_CHECK_MAX_OUTPUT_TOKENS, "input": prompt, "store": False}
     else:
         suffix = "/chat/completions"
-        body = {"model": selected["model"], "max_tokens": 32, "messages": [{"role": "user", "content": prompt}]}
+        body = {"model": selected["model"], "max_tokens": MODEL_CHECK_MAX_OUTPUT_TOKENS, "messages": [{"role": "user", "content": prompt}]}
     async def send():
         async with httpx.AsyncClient(timeout=15, follow_redirects=False, trust_env=False) as client:
             async with client.stream("POST", base + suffix, headers=headers, json=body) as response:
@@ -600,7 +602,11 @@ def create_router(*, authorize, store: ConnectionStore, check=probe, account=nat
                     current = store.read(backend)
                     if current["revision"] != revision(payload["expected_revision"]):
                         raise HTTPException(409, "Endpoint settings changed. Refresh and try again.")
-                    if current.get("last_result") != "verified": raise HTTPException(409, "Check this API connection first.")
+                    if not current.get("configured"):
+                        raise HTTPException(409, "Connect a custom API first.")
+                    # A saved, unverified connection can choose its first model.
+                    # This write does not verify it or make it usable by chats;
+                    # the explicit /check operation must still succeed.
                     value = {key: current[key] for key in ("base_url", "api_key", "protocol", "auth_header")}
                     saved = store.write(backend, current["revision"], {**value, "model": model, "expected_revision": current["revision"]}, current["last_result"], checked_at=current["checked_at"])
                     cached = store.catalog_cache.get((backend, current["revision"]))
@@ -651,7 +657,11 @@ def create_router(*, authorize, store: ConnectionStore, check=probe, account=nat
                     result = "cli_update_required" if discovered.get("cli_update_required") else "verified" if discovered["discovery_status"] == "ready" and discovered["models"] else "connection_failed"
                 else:
                     result = await check(selected)
-                if request.method == "PUT" and result != "verified":
+                # Public catalogs cannot authenticate a key. Keep a private,
+                # explicitly unverified setup so the client can list models
+                # before choosing one for a subsequent explicit check.
+                pending_model = result == "model_required" and not selected.get("model") and backend != "cursor"
+                if request.method == "PUT" and result != "verified" and not pending_model:
                     return reply({"ok": False, "status": result})
                 configuration = await asyncio.to_thread(store.write, backend, expected, selected, result)
                 if backend == "cursor" and result == "verified":

package/server/server_instances.py

@@ -138,6 +138,26 @@ def read_config(instance: Instance) -> dict[str, str]:
     return result
 
 
+def split_layout(instance: Instance, platform: str = sys.platform):
+    """Default-only split detection; invalid evidence never falls back to legacy."""
+    if instance.name != "default":
+        return None
+    marker = instance.runtime / "execution-layout.json"
+    if not marker.exists() and not marker.is_symlink():
+        return None
+    import execution_install as files
+    from execution_uninstall import _service_files
+    layout = files.installed_layout(instance.runtime)
+    expected_platform = "Darwin" if platform == "darwin" else "Linux" if platform.startswith("linux") else None
+    if ((layout.install_root, layout.config_root, layout.state_root, layout.home, layout.platform)
+            != (instance.runtime, instance.config, instance.state, instance.home, expected_platform)):
+        raise ValueError("Default execution roots/platform do not match this instance.")
+    for role in ("worker", "gateway"):
+        check_path(layout.service_path(role), instance.home)
+    _service_files(layout)
+    return layout
+
+
 def validate_binding(instance: Instance, platform: str = sys.platform) -> None:
     for path in (instance.runtime, instance.config, instance.state, instance.logs, instance.service_file(platform)):
         check_path(path, instance.home)
@@ -145,6 +165,8 @@ def validate_binding(instance: Instance, platform: str = sys.platform) -> None:
     for key, value in instance.environment().items():
         if key in env and env[key] != value:
             raise ValueError(f"{instance.name}: {key} does not match this instance; refusing service changes.")
+    if split_layout(instance, platform) is not None:
+        return
     service = instance.service_file(platform)
     if service.exists():
         data = read_regular(service)
@@ -370,6 +392,22 @@ def run(command: list[str], **kwargs):
 
 
 def service_status(instance: Instance, platform: str = sys.platform) -> str:
+    try:
+        layout = split_layout(instance, platform)
+        if layout is not None:
+            from execution_manage import NativeServices, read_lifecycle_intent
+            native = NativeServices(layout)
+            native.validate_registered_bindings()
+            snapshot = native.snapshot()
+            states = {item["state"] for item in snapshot.values()}
+            intent = read_lifecycle_intent(layout)
+            if states <= {"absent", "stopped"}:
+                return "stopped"
+            if states == {"running"}:
+                return "pending" if intent is not None else "running"
+            return "partial"
+    except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired):
+        return "unknown"
     command = ["launchctl", "print", f"gui/{os.getuid()}/{launchd_label(instance.name)}"] if platform == "darwin" else ["systemctl", "--user", "show", service_name(instance.name) + ".service", "--property=ActiveState", "--value"]
     try:
         result = subprocess.run(command, capture_output=True, text=True, timeout=3, check=False)
@@ -863,6 +901,11 @@ def release_uninstalled_name(instance: Instance, registry: Registry) -> None:
 
 def control(instance: Instance, action: str, platform: str = sys.platform):
     validate_binding(instance, platform)
+    layout = split_layout(instance, platform)
+    if layout is not None:
+        from execution_manage import LifecycleController
+        LifecycleController(layout).run(action)
+        return
     if not instance.service_file(platform).exists():
         raise ValueError(f"{instance.name}: no installed service.")
     if platform == "darwin":
@@ -1080,13 +1123,13 @@ def main(argv: list[str] | None = None) -> int:
                         control(item, args.command)
                     if args.command != "remove":
                         print(f"{item.name}: {args.command} completed", flush=True)
-                except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as exc:
+                except (OSError, ValueError, RuntimeError, KeyError, subprocess.CalledProcessError) as exc:
                     print(f"{item.name}: failed ({exc})", file=sys.stderr)
                     failures += 1
             if args.command == "remove" and not failures:
                 print("\n" + terminal_color("Successful!", "32"), flush=True)
             return int(bool(failures))
-    except (OSError, ValueError, KeyError) as exc:
+    except (OSError, ValueError, RuntimeError, KeyError) as exc:
         print(f"Instance manager: {exc}", file=sys.stderr)
         return 1
 

package/server/update_handoff.py

@@ -30,9 +30,11 @@ def _no_activation(root: Path) -> None:
 
 def _no_handoff_recovery_overlap(root: Path) -> None:
     _no_activation(root)
-    marker = root / ".execution-uninstall.json"
-    if marker.exists() or marker.is_symlink():
-        raise RuntimeError("uninstall already owns execution recovery")
+    for name in (".execution-uninstall.json", ".execution-lifecycle.json"):
+        marker = root / name
+        if marker.exists() or marker.is_symlink():
+            owner = "uninstall" if name == ".execution-uninstall.json" else "native lifecycle"
+            raise RuntimeError(owner + " already owns execution recovery")
 
 
 def _read_handoff(root: Path, path: Path) -> dict[str, Any]:
@@ -68,14 +70,7 @@ def _read_handoff(root: Path, path: Path) -> dict[str, Any]:
 
 
 def _installed_layout(root: Path) -> files.ExecutionLayout:
-    data, _mode = files._read_file(root / files.LAYOUT_NAME, private=True)
-    value = json.loads(data)
-    if not isinstance(value, dict):
-        raise ValueError("installed execution layout is invalid")
-    layout = files.ExecutionLayout.from_dict(value.get("layout"))
-    if layout.install_root != root or value != files.layout_manifest(layout):
-        raise ValueError("installed execution layout changed")
-    return layout
+    return files.installed_layout(root)
 
 
 def _matching_status(handoff: dict, layout: files.ExecutionLayout, record: dict,