@agentsdock/server 1.0.7-beta.5

package/server/uninstall.sh

@@ -0,0 +1,359 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_ROOT="${AGENTS_SERVER_INSTALL_DIR:-$HOME/.local/share/agents-server}"
+CONFIG_ROOT="${AGENTS_SERVER_CONFIG_DIR:-$HOME/.config/agents-server}"
+LEGACY_STATE_ROOT="$HOME/.zenithbot-agent"
+if [[ -n "${AGENTSDOCK_STATE_DIR:-}" ]]; then
+  STATE_ROOT="$AGENTSDOCK_STATE_DIR"
+elif [[ -n "${AGENTS_SERVER_STATE_DIR:-}" ]]; then
+  STATE_ROOT="$AGENTS_SERVER_STATE_DIR"
+elif [[ -n "${ZENITHBOT_AGENT_DIR:-}" ]]; then
+  STATE_ROOT="$ZENITHBOT_AGENT_DIR"
+else
+  STATE_ROOT="$HOME/.agentsdock"
+fi
+SERVICE_NAME="agents-server"
+OS_NAME="$(uname -s)"
+
+ASSUME_YES="false"
+PURGE_STATE="false"
+
+normalize_managed_path() {
+  local label="$1"
+  local candidate="$2"
+  local parent leaf physical_parent normalized home_physical
+
+  if [[ -z "$candidate" || "$candidate" != /* || "$candidate" == *$'\n'* || "$candidate" == *$'\r'* ]]; then
+    echo "$label must be a non-empty absolute path without control characters." >&2
+    return 1
+  fi
+  while [[ "$candidate" != "/" && "$candidate" == */ ]]; do
+    candidate="${candidate%/}"
+  done
+  case "$candidate/" in
+    *"/../"*|*"/./"*|*"//"*)
+      echo "$label must not contain '.', '..', or repeated-slash path components: $candidate" >&2
+      return 1
+      ;;
+  esac
+
+  # Resolve existing parent directories without following the final component.
+  # Removing a final symlink must remove only that link, while an intermediate
+  # symlink still needs to be accounted for by the safety checks below.
+  parent="$(dirname -- "$candidate")"
+  leaf="$(basename -- "$candidate")"
+  while [[ ! -d "$parent" && "$parent" != "/" ]]; do
+    leaf="$(basename -- "$parent")/$leaf"
+    parent="$(dirname -- "$parent")"
+  done
+  physical_parent="$(cd -P -- "$parent" 2>/dev/null && pwd -P)" || {
+    echo "Could not resolve the parent of $label: $candidate" >&2
+    return 1
+  }
+  if [[ "$physical_parent" == "/" ]]; then
+    normalized="/$leaf"
+  else
+    normalized="$physical_parent/$leaf"
+  fi
+  home_physical="$(cd -P -- "$HOME" 2>/dev/null && pwd -P)" || {
+    echo "Could not resolve HOME safely: $HOME" >&2
+    return 1
+  }
+
+  case "$normalized" in
+    "/"|"/Applications"|"/Library"|"/System"|"/Users"|"/Volumes"|"/bin"|"/etc"|"/home"|"/opt"|"/private"|"/sbin"|"/tmp"|"/usr"|"/var"|\
+    "$home_physical"|"$home_physical/.config"|"$home_physical/.local"|"$home_physical/.local/share"|"$home_physical/Library"|"$home_physical/Library/LaunchAgents")
+      echo "Refusing unsafe $label target: $normalized" >&2
+      return 1
+      ;;
+  esac
+  printf '%s\n' "$normalized"
+}
+
+paths_overlap() {
+  local first="$1"
+  local second="$2"
+  [[ "$first" == "$second" || "$first" == "$second/"* || "$second" == "$first/"* ]]
+}
+
+INSTALL_ROOT="$(normalize_managed_path AGENTS_SERVER_INSTALL_DIR "$INSTALL_ROOT")" || exit 2
+CONFIG_ROOT="$(normalize_managed_path AGENTS_SERVER_CONFIG_DIR "$CONFIG_ROOT")" || exit 2
+STATE_ROOT="$(normalize_managed_path AGENTSDOCK_STATE_DIR "$STATE_ROOT")" || exit 2
+for managed_root in "$INSTALL_ROOT" "$CONFIG_ROOT" "$STATE_ROOT"; do
+  if [[ -L "$managed_root" ]]; then
+    echo "Refusing symbolic-link managed root: $managed_root" >&2
+    exit 2
+  fi
+done
+if paths_overlap "$INSTALL_ROOT" "$CONFIG_ROOT" || \
+  paths_overlap "$INSTALL_ROOT" "$STATE_ROOT" || \
+  paths_overlap "$CONFIG_ROOT" "$STATE_ROOT"; then
+  echo "Refusing overlapping install, configuration, and state roots; each must be a separate directory." >&2
+  exit 2
+fi
+
+usage() {
+  cat <<USAGE
+Usage: ./uninstall.sh [--yes] [--purge-state]
+
+Stops and removes the AgentsServer user service, versioned release runtime,
+and generated configuration (including the access token). Chat history, jobs,
+files, secure-peer credentials, and terminals under $STATE_ROOT are preserved
+by default so a later ./install.sh picks ordinary AgentsServer state back up.
+Preserved Team Hub state is not auto-reactivated in this beta; it requires
+signed managed recovery or support-assisted restoration.
+
+  --yes           Do not prompt before removing the service, releases, and
+                   configuration.
+  --purge-state   Also delete $STATE_ROOT (chat history, jobs, files, tokens,
+                   and secure-peer credentials). This cannot be undone and
+                   always requires typing the exact state path interactively;
+                   --yes never bypasses it.
+USAGE
+}
+
+while (($#)); do
+  case "$1" in
+    --yes) ASSUME_YES="true"; shift ;;
+    --purge-state) PURGE_STATE="true"; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+# The split lifecycle validates its installed layout, obtains an exact idle
+# execution hold, and owns the shared lock through both native service stops
+# and filesystem removal. Keep legacy uninstall unchanged for old layouts.
+if [[ -f "$INSTALL_ROOT/execution-layout.json" && ! -L "$INSTALL_ROOT/execution-layout.json" ]]; then
+  UNINSTALL_SOURCE="$(cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+  UNINSTALL_PYTHON="$UNINSTALL_SOURCE/.venv/bin/python"
+  if [[ ! -x "$UNINSTALL_PYTHON" ]]; then
+    UNINSTALL_PYTHON="$(command -v python3 || true)"
+  fi
+  if [[ -z "$UNINSTALL_PYTHON" || ! -f "$UNINSTALL_SOURCE/execution_uninstall.py" || -L "$UNINSTALL_SOURCE/execution_uninstall.py" ]]; then
+    echo "Cannot uninstall the separate gateway/execution layout: its maintained Python helper is unavailable; no services were changed." >&2
+    exit 1
+  fi
+  execution_arguments=(--root "$INSTALL_ROOT" --config-root "$CONFIG_ROOT" --state-root "$STATE_ROOT" --home "$HOME")
+  [[ "$ASSUME_YES" != "true" ]] || execution_arguments+=(--yes)
+  [[ "$PURGE_STATE" != "true" ]] || execution_arguments+=(--purge-state)
+  exec "$UNINSTALL_PYTHON" -B "$UNINSTALL_SOURCE/execution_uninstall.py" "${execution_arguments[@]}"
+fi
+
+refuse_execution_layout() {
+  local marker=""
+  for marker in "$INSTALL_ROOT/execution-layout.json" "$INSTALL_ROOT/.execution-transaction"; do
+    if [[ -e "$marker" || -L "$marker" ]]; then
+      echo "This uninstaller does not support the separate gateway/execution layout or its pending transaction." >&2
+      echo "Use the execution-aware managed lifecycle; the pinned worker has not been changed." >&2
+      return 1
+    fi
+  done
+}
+
+refuse_execution_layout || exit 1
+
+INSTALL_LOCK_DIR="$INSTALL_ROOT/.install-lock"
+UNINSTALL_LOCK_HELD="false"
+INSTALL_ROOT_CREATED_FOR_LOCK="false"
+
+release_operation_lock() {
+  [[ "$UNINSTALL_LOCK_HELD" == "true" ]] || return 0
+  if [[ "$(cat "$INSTALL_LOCK_DIR/pid" 2>/dev/null || true)" == "$$" ]]; then
+    rm -rf "$INSTALL_LOCK_DIR"
+  fi
+  UNINSTALL_LOCK_HELD="false"
+  if [[ "$INSTALL_ROOT_CREATED_FOR_LOCK" == "true" ]]; then
+    rmdir "$INSTALL_ROOT" 2>/dev/null || true
+  fi
+}
+
+acquire_operation_lock() {
+  if [[ ! -d "$INSTALL_ROOT" ]]; then
+    mkdir -p "$INSTALL_ROOT"
+    INSTALL_ROOT_CREATED_FOR_LOCK="true"
+  fi
+  if ! mkdir "$INSTALL_LOCK_DIR" 2>/dev/null; then
+    local owner_pid=""
+    owner_pid="$(cat "$INSTALL_LOCK_DIR/pid" 2>/dev/null || true)"
+    if [[ "$owner_pid" =~ ^[0-9]+$ ]] && kill -0 "$owner_pid" >/dev/null 2>&1; then
+      echo "Refusing to uninstall while an AgentsServer install/update is active (PID $owner_pid)." >&2
+      return 1
+    fi
+    local stale_lock="$INSTALL_ROOT/.uninstall-stale-lock-$$"
+    if ! mv "$INSTALL_LOCK_DIR" "$stale_lock" 2>/dev/null; then
+      echo "An AgentsServer install/update started while uninstall was checking the operation lock." >&2
+      return 1
+    fi
+    rm -rf "$stale_lock"
+    if ! mkdir "$INSTALL_LOCK_DIR" 2>/dev/null; then
+      echo "An AgentsServer install/update is already running." >&2
+      return 1
+    fi
+  fi
+  printf '%s\n' "$$" > "$INSTALL_LOCK_DIR/pid"
+  chmod 700 "$INSTALL_LOCK_DIR"
+  UNINSTALL_LOCK_HELD="true"
+}
+
+acquire_operation_lock || exit 1
+trap release_operation_lock EXIT
+trap 'exit 130' HUP INT TERM
+refuse_execution_layout || exit 1
+
+confirm() {
+  local prompt="$1"
+  [[ "$ASSUME_YES" != "true" ]] || return 0
+  if [[ ! -t 0 ]]; then
+    echo "Refusing to $prompt without --yes on a non-interactive run." >&2
+    return 1
+  fi
+  local reply=""
+  read -r -p "$prompt [y/N] " reply || return 1
+  case "$reply" in
+    y|Y|yes|YES) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+confirm_state_purge() {
+  local reply=""
+  if [[ ! -t 0 ]]; then
+    echo "Refusing to purge state without an interactive terminal; --yes never bypasses the state guard." >&2
+    return 1
+  fi
+  echo "Permanent deletion requested for chat history, jobs, files, and tokens."
+  read -r -p "Type the exact state path to confirm ($STATE_ROOT): " reply || return 1
+  if [[ "$reply" != "$STATE_ROOT" ]]; then
+    echo "State path did not match; nothing was changed." >&2
+    return 1
+  fi
+}
+
+if [[ "$PURGE_STATE" == "true" ]] && ! confirm_state_purge; then
+  exit 1
+fi
+
+echo "This will stop and remove the AgentsServer service, release runtime at"
+echo "$INSTALL_ROOT, and configuration at $CONFIG_ROOT (including the access token)."
+if confirm "Proceed?"; then
+  :
+else
+  echo "Aborted; nothing was changed." >&2
+  exit 1
+fi
+
+case "$OS_NAME" in
+  Darwin)
+    LABEL="com.agentsdock.server"
+    PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
+    SERVICE_TARGET="gui/$(id -u)/$LABEL"
+    if launchctl print "$SERVICE_TARGET" >/dev/null 2>&1; then
+      echo "Stopping $LABEL"
+      if ! launchctl bootout "$SERVICE_TARGET" >/dev/null 2>&1 && \
+        launchctl print "$SERVICE_TARGET" >/dev/null 2>&1; then
+        echo "Could not stop $LABEL; no files were removed." >&2
+        exit 1
+      fi
+      stopped="false"
+      for ((_attempt = 1; _attempt <= 50; _attempt++)); do
+        if ! launchctl print "$SERVICE_TARGET" >/dev/null 2>&1; then
+          stopped="true"
+          break
+        fi
+        sleep 0.1
+      done
+      if [[ "$stopped" != "true" ]]; then
+        echo "$LABEL did not stop; no files were removed." >&2
+        exit 1
+      fi
+    fi
+    if [[ -f "$PLIST" ]]; then
+      echo "Removing $PLIST"
+      rm -f "$PLIST"
+    fi
+    LOG_DIR="$HOME/Library/Logs/AgentsServer"
+    if [[ -d "$LOG_DIR" ]]; then
+      echo "Removing $LOG_DIR"
+      rm -rf "$LOG_DIR"
+    fi
+    ;;
+  Linux)
+    SERVICE_FILE="$HOME/.config/systemd/user/$SERVICE_NAME.service"
+    if ! systemctl --user show-environment >/dev/null 2>&1; then
+      echo "The systemd user service manager is unavailable; no files were removed." >&2
+      exit 1
+    fi
+    if [[ -f "$SERVICE_FILE" ]] || systemctl --user is-active --quiet "$SERVICE_NAME.service"; then
+      echo "Stopping $SERVICE_NAME.service"
+      if ! systemctl --user disable --now "$SERVICE_NAME.service" >/dev/null 2>&1 && \
+        systemctl --user is-active --quiet "$SERVICE_NAME.service"; then
+        echo "Could not stop $SERVICE_NAME.service; no files were removed." >&2
+        exit 1
+      fi
+      stopped="false"
+      for ((_attempt = 1; _attempt <= 50; _attempt++)); do
+        if ! systemctl --user is-active --quiet "$SERVICE_NAME.service"; then
+          stopped="true"
+          break
+        fi
+        sleep 0.1
+      done
+      if [[ "$stopped" != "true" ]]; then
+        echo "$SERVICE_NAME.service did not stop; no files were removed." >&2
+        exit 1
+      fi
+    fi
+    if [[ -f "$SERVICE_FILE" ]]; then
+      echo "Removing $SERVICE_FILE"
+      rm -f "$SERVICE_FILE"
+      systemctl --user daemon-reload || true
+    fi
+    ;;
+  *)
+    echo "Unsupported host OS: $OS_NAME; no files were removed." >&2
+    exit 1
+    ;;
+esac
+
+if [[ -d "$INSTALL_ROOT" ]]; then
+  echo "Removing release runtime at $INSTALL_ROOT"
+  shopt -s dotglob nullglob
+  for install_entry in "$INSTALL_ROOT"/*; do
+    [[ "$install_entry" == "$INSTALL_LOCK_DIR" ]] || rm -rf -- "$install_entry"
+  done
+  shopt -u dotglob nullglob
+fi
+
+if [[ -d "$CONFIG_ROOT" ]]; then
+  echo "Removing configuration at $CONFIG_ROOT"
+  rm -rf "$CONFIG_ROOT"
+fi
+
+if [[ "$PURGE_STATE" == "true" ]]; then
+  if [[ -e "$STATE_ROOT" || -L "$LEGACY_STATE_ROOT" ]]; then
+    [[ ! -L "$LEGACY_STATE_ROOT" ]] || rm -f "$LEGACY_STATE_ROOT"
+    [[ ! -e "$STATE_ROOT" ]] || rm -rf "$STATE_ROOT"
+    echo "Deleted $STATE_ROOT"
+  fi
+elif [[ -e "$STATE_ROOT" ]]; then
+  echo "Preserved chat history, jobs, files, tokens, and secure-peer credentials at $STATE_ROOT."
+  echo "Re-running ./install.sh will pick ordinary AgentsServer state back up. Pass --purge-state to also delete it."
+  if [[ -e "$STATE_ROOT/team-hub/team-hub.sqlite3" || -L "$STATE_ROOT/team-hub/team-hub.sqlite3" ]]; then
+    echo "Preserved Team Hub state is not auto-reactivated in this beta; use a signed managed recovery or support-assisted restoration."
+  fi
+fi
+
+# Keep the shared install/update lock alive until every requested removal has
+# completed. Removing the install root while the lock still lives inside it
+# would let a new installer race with configuration or state deletion.
+release_operation_lock
+if [[ -d "$INSTALL_ROOT" ]] && ! rmdir "$INSTALL_ROOT"; then
+  echo "Could not remove the now-unlocked install directory at $INSTALL_ROOT." >&2
+  exit 1
+fi
+
+echo "AgentsServer service, release runtime, and configuration removed."
+echo "Note: any persistent chat terminals (tmux sessions named zd_*) keep running"
+echo "independently and are not touched by this script. List them with: tmux ls"

package/server/update_handoff.py

@@ -0,0 +1,237 @@
+"""Release only an unchanged, idle split-worker handoff before installer entry.
+
+The detached update runner first settles its own failed status and Hub fence.
+Once it invokes the installer, the installer's activation journals exclusively
+own recovery. This helper never stops processes, changes update status, deletes
+evidence, or guesses that a legacy monolith owns a split-worker lease.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+from pathlib import Path
+import re
+import stat
+from typing import Any
+import uuid
+
+import execution_install as files
+from execution_manage import InstallationLock, NativeServices, WorkerControl
+
+
+def _no_activation(root: Path) -> None:
+    for name in (".activation-transaction", ".execution-transaction"):
+        path = root / name
+        if path.exists() or path.is_symlink():
+            raise RuntimeError("activation already owns handoff recovery")
+
+
+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")
+
+
+def _read_handoff(root: Path, path: Path) -> dict[str, Any]:
+    path = files._path(path)
+    if (path.parent.parent != root / ".update-preparations"
+            or re.fullmatch(r"[0-9a-f]{32}", path.parent.name) is None
+            or re.fullmatch(r"handoff-[0-9a-f]{32}\.json", path.name) is None):
+        raise ValueError("handoff is outside its owned preparation directory")
+    files._owned_directory(path.parent.parent, private=True)
+    files._owned_directory(path.parent, private=True)
+    data, _mode = files._read_file(path, private=True)
+
+    def unique(pairs):
+        value = {}
+        for key, item in pairs:
+            if key in value:
+                raise ValueError("duplicate handoff field")
+            value[key] = item
+        return value
+
+    value = json.loads(data, object_pairs_hook=unique)
+    expected = {"schema", "operation_id", "worker_instance_id", "lease_id", "expected_server_identity"}
+    if (not isinstance(value, dict) or set(value) != expected
+            or type(value["schema"]) is not int or value["schema"] != 1):
+        raise ValueError("invalid handoff schema")
+    for key in ("operation_id", "lease_id"):
+        if not isinstance(value[key], str) or str(uuid.UUID(value[key])) != value[key]:
+            raise ValueError("invalid handoff operation or lease")
+    for key in ("worker_instance_id", "expected_server_identity"):
+        if (not isinstance(value[key], str) or not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", value[key])):
+            raise ValueError("invalid handoff worker or server identity")
+    return value
+
+
+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
+
+
+def _matching_status(handoff: dict, layout: files.ExecutionLayout, record: dict,
+                     status: dict, native: dict, *, allow_released: bool = False) -> bool:
+    lease = status.get("lease")
+    blockers = status.get("blockers")
+    unheld = allow_released and "lease" in status and lease is None
+    if ((not unheld and record.get("instance_id") != handoff["worker_instance_id"])
+            or status.get("worker_instance_id") != record.get("instance_id")
+            or record.get("release_root") != str(layout.worker_release)
+            or native.get("worker", {}).get("state") != "running"
+            or type(record.get("pid")) is not int or record["pid"] <= 0
+            or native["worker"].get("pid") != record["pid"]):
+        raise RuntimeError("native worker no longer owns the handoff")
+    if (not isinstance(blockers, dict) or not blockers
+            or any(type(value) is not int or value < 0 for value in blockers.values())):
+        raise RuntimeError("worker cleanup or admission has not settled")
+    if unheld:
+        return False
+    if status.get("idle") is not True or any(blockers.values()):
+        raise RuntimeError("worker cleanup or admission has not settled")
+    if (not isinstance(lease, dict) or lease.get("operation_id") != handoff["operation_id"]
+            or lease.get("lease_id") != handoff["lease_id"] or lease.get("sealed") is not True
+            or lease.get("expires_at", "missing") is not None):
+        raise RuntimeError("worker no longer holds the exact sealed handoff")
+    return True
+
+
+def _held_state_ownership(layout: files.ExecutionLayout) -> tuple[int, int]:
+    """Prove an exclusive state owner exists, without claiming flock exposes PID.
+
+    Native service and authenticated callback probes bind the maintained worker
+    PID separately. This checks that its lifetime ownership boundary is intact.
+    """
+    parent = files._path(layout.state_root / "admin")
+    files._owned_directory(parent, private=True)
+    path = parent / "state-owner.lock"
+    descriptor = os.open(path, os.O_RDWR | os.O_NOFOLLOW | os.O_NONBLOCK)
+    try:
+        info = os.fstat(descriptor)
+        if (not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid()
+                or info.st_nlink != 1 or stat.S_IMODE(info.st_mode) != 0o600):
+            raise PermissionError("worker state ownership lock is unsafe")
+        try:
+            fcntl.flock(descriptor, fcntl.LOCK_SH | fcntl.LOCK_NB)
+        except BlockingIOError:
+            pass
+        else:
+            raise RuntimeError("replacement worker does not hold exclusive state ownership")
+        linked = path.lstat()
+        identity = info.st_dev, info.st_ino
+        if (linked.st_dev, linked.st_ino) != identity:
+            raise RuntimeError("worker state ownership lock changed")
+        return identity
+    finally:
+        os.close(descriptor)
+
+
+def release_existing_handoff(root: Path, handoff_file: Path, *,
+                             control: WorkerControl | None = None,
+                             services: NativeServices | None = None) -> dict[str, Any]:
+    """Release once with epoch/operation/lease CAS; propagate every uncertain result.
+
+    The caller must have atomically changed only its owned update to failed and
+    settled provider teardown. The private status confirms quiescence again.
+    ``control`` and ``services`` are injectable for isolated boundary tests.
+    """
+    return _release_handoff(root, handoff_file, control=control, services=services)
+
+
+def retry_failed_handoff(root: Path, status_path: Path, expected_status: dict[str, Any], *,
+                         control: WorkerControl | None = None,
+                         services: NativeServices | None = None) -> dict[str, Any]:
+    """Finish only the exact saved failed cleanup, including a lost release reply.
+
+    The caller holds its update operation lock, never the status flock across
+    this call, then CASes its status after success. No saved evidence is changed.
+    An unheld authenticated replacement worker needs no maintenance POST either;
+    its native process and exclusive state ownership must also remain unchanged.
+    """
+    root, status_path = files._path(root), files._path(status_path)
+    if not isinstance(expected_status, dict):
+        raise ValueError("failed handoff status is invalid")
+    # Freeze the caller's snapshot across callback requests.
+    expected_status = json.loads(json.dumps(expected_status))
+    update_id = expected_status.get("update_id")
+    preparation_id = expected_status.get("preparation_id") or update_id
+    if (not isinstance(update_id, str) or re.fullmatch(r"[0-9a-f]{32}", update_id) is None
+            or not isinstance(preparation_id, str) or re.fullmatch(r"[0-9a-f]{32}", preparation_id) is None
+            or expected_status.get("phase") != "failed"
+            or expected_status.get("error_code") != "server_update_handoff_release_failed"
+            or expected_status.get("retryable") is not True
+            or expected_status.get("runner_pid") is not None):
+        raise ValueError("status does not own a failed preinstaller handoff")
+    handoff_file = root / ".update-preparations" / preparation_id / f"handoff-{update_id}.json"
+
+    def verify_status(layout: files.ExecutionLayout, handoff: dict) -> None:
+        if status_path != layout.state_root / "admin/server-update.json":
+            raise ValueError("handoff status is outside the installed state directory")
+        files._owned_directory(status_path.parent, private=True)
+        data, _mode = files._read_file(status_path, private=True)
+        if json.loads(data) != expected_status:
+            raise RuntimeError("failed update status changed before handoff recovery")
+        if (expected_status.get("_execution_handoff") != handoff
+                or handoff["operation_id"] != str(uuid.UUID(hex=update_id))):
+            raise RuntimeError("saved failed status does not own this handoff")
+
+    return _release_handoff(root, handoff_file, control=control, services=services,
+                            allow_released=True, verify_status=verify_status)
+
+
+def _release_handoff(root: Path, handoff_file: Path, *, control=None, services=None,
+                     allow_released: bool = False, verify_status=None) -> dict[str, Any]:
+    root = files._path(root)
+    files._owned_directory(root)
+    with InstallationLock(root):
+        _no_handoff_recovery_overlap(root)
+        handoff = _read_handoff(root, handoff_file)
+        layout = _installed_layout(root)
+        if verify_status is not None:
+            verify_status(layout, handoff)
+        control = control or WorkerControl()
+        services = services or NativeServices(layout)
+        record, status = control.status(layout)
+        _matching_status(handoff, layout, record, status, services.snapshot(), allow_released=allow_released)
+        replacement = allow_released and record.get("instance_id") != handoff["worker_instance_id"]
+        state_owner = _held_state_ownership(layout) if replacement else None
+        # Authenticate the stable worker callback itself; a public gateway can
+        # be unavailable without changing ownership of this execution epoch.
+        health = control.callback_health(layout, record)
+        execution = health.get("execution_service")
+        if (health.get("ok") is not True or health.get("server_identity") != handoff["expected_server_identity"]
+                or not isinstance(execution, dict) or execution.get("instance_id") != record["instance_id"]
+                or execution.get("pid") != record["pid"]):
+            raise RuntimeError("authenticated worker identity does not match handoff")
+        # Re-read local provenance and live admission after the health request.
+        # A takeover or failed provider close must not disappear in that gap.
+        _no_handoff_recovery_overlap(root)
+        if _read_handoff(root, handoff_file) != handoff or _installed_layout(root) != layout:
+            raise RuntimeError("handoff provenance changed before release")
+        latest_record, latest_status = control.status(layout)
+        held = _matching_status(handoff, layout, latest_record, latest_status, services.snapshot(),
+                                allow_released=allow_released)
+        if latest_record != record:
+            raise RuntimeError("worker process receipt changed before release")
+        if replacement and _held_state_ownership(layout) != state_owner:
+            raise RuntimeError("worker state ownership changed before acknowledgment")
+        if verify_status is not None:
+            verify_status(layout, handoff)
+        if not held:
+            return {"released": True, "already_released": True, "operation_id": handoff["operation_id"],
+                    "worker_instance_id": record["instance_id"]}
+        result = control._maintenance(layout, latest_record, action="release",
+                                      operation=handoff["operation_id"], lease_id=handoff["lease_id"])
+        if (result.get("worker_instance_id") != handoff["worker_instance_id"]
+                or result.get("lease", "missing") is not None):
+            raise RuntimeError("worker did not confirm exact handoff release")
+        return {"released": True, "already_released": False, "operation_id": handoff["operation_id"],
+                "worker_instance_id": handoff["worker_instance_id"]}