#!/usr/bin/env bash
set -euo pipefail

# A managed update can be launched by a long-lived tmux server that itself was
# started from a translated Intel process. On Apple silicon that makes
# universal tools such as bash and uname inherit the x86_64 slice, even though
# the host and the release runtime are arm64-capable. Re-enter the installer
# natively before parsing arguments, reading configuration, creating paths, or
# changing service state. A real Intel Mac has no hw.optional.arm64 capability
# and continues to the explicit unsupported-architecture rejection below.
bootstrap_native_macos_architecture() {
  local operating_system=""
  local process_architecture=""
  local physical_arm64=""
  local sysctl_binary=""
  local arch_binary=""

  operating_system="$(uname -s 2>/dev/null || true)"
  process_architecture="$(uname -m 2>/dev/null || true)"
  [[ "$operating_system" == "Darwin" \
    && "$process_architecture" == "x86_64" ]] || return 0

  sysctl_binary="$(command -v sysctl 2>/dev/null || true)"
  [[ "$sysctl_binary" == /* && -x "$sysctl_binary" ]] || return 0
  physical_arm64="$("$sysctl_binary" -n hw.optional.arm64 2>/dev/null || true)"
  [[ "$physical_arm64" == "1" ]] || return 0

  if [[ "${AGENTS_SERVER_NATIVE_ARCH_REEXEC:-}" == "1" ]]; then
    echo "Could not leave the translated x86_64 macOS process environment." >&2
    echo "Run the installer from a native arm64 shell; no state, release, configuration, or service changes were made." >&2
    exit 1
  fi
  arch_binary="$(command -v arch 2>/dev/null || true)"
  if [[ "$arch_binary" != /* || ! -x "$arch_binary" \
    || ! -x /bin/bash ]]; then
    echo "Apple silicon was detected, but the native macOS launcher is unavailable." >&2
    echo "Run the installer from a native arm64 shell; no state, release, configuration, or service changes were made." >&2
    exit 1
  fi

  export AGENTS_SERVER_NATIVE_ARCH_REEXEC=1
  exec "$arch_binary" -arm64 /bin/bash "$0" "$@"
}

bootstrap_native_macos_architecture "$@"
unset AGENTS_SERVER_NATIVE_ARCH_REEXEC

PORT="7850"
BIND_ADDRESS="0.0.0.0"
RELEASE_VERSION=""
DEPENDENCY_SYNC_TIMEOUT_SECONDS="${AGENTS_SERVER_DEPENDENCY_TIMEOUT_SECONDS:-1200}"
INSTALL_HEARTBEAT_SECONDS="${AGENTS_SERVER_INSTALL_HEARTBEAT_SECONDS:-15}"
HEALTH_CHECK_ATTEMPTS="${AGENTS_SERVER_HEALTH_CHECK_ATTEMPTS:-45}"
ROLLBACK_HEALTH_CHECK_MAX_ATTEMPTS=45
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"
INSTANCE_NAME="${AGENTS_SERVER_INSTANCE:-default}"
INSTANCE_EXPLICIT="false"
LABEL="com.agentsdock.server"
INSTANCE_LOG_DIR="$HOME/Library/Logs/AgentsServer"
LEGACY_SERVICE_NAME="zenithbot-agent"
# AgentsServer's cooperative shutdown has 18 independently bounded cleanup
# phases in addition to uvicorn's graceful window.  Five seconds was shorter
# than even an ordinary slow shutdown: launchctl had already accepted bootout,
# then the installer abandoned activation/rollback and could leave the service
# unloaded.  Keep this wait bounded, but long enough for the server's complete
# worst-case graceful budget before declaring the exact launchd job wedged.
# AgentsServer caps the configurable uvicorn window at 60 seconds; 185 seconds
# covers that window, all 18 five-second teardown phases, the watchdog margin,
# and another 30 seconds for launchd to reap the terminated process.
LAUNCHCTL_STOP_ATTEMPTS=1850
LAUNCHCTL_STOP_DELAY=0.1
LAUNCHCTL_BOOTSTRAP_ATTEMPTS=3
NON_INTERACTIVE="false"
PORT_EXPLICIT="false"
BIND_EXPLICIT="false"
SERVER_NAME=""
PORT_FALLBACK="auto"
PORT_FALLBACK_ATTEMPTS=5
TEAM_HUB_MODE_OVERRIDE=""
TEAM_HUB_MODE="disabled"
TEAM_HUB_REACTIVATION_REQUESTED="false"
TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED="false"
TEAM_HUB_REACTIVATION_SNAPSHOT=""
TEAM_HUB_REACTIVATION_HUB_ID=""
TEAM_HUB_REACTIVATION_OPERATION_ID=""
TEAM_HUB_REACTIVATION_FENCE_PENDING="false"
TEAM_HUB_REACTIVATION_FINALIZED="false"
TEAM_HUB_TRANSPORT_OVERRIDE=""
TEAM_HUB_TRANSPORT="loopback"
TEAM_HUB_URL_OVERRIDE=""
TEAM_HUB_URL=""
TEAM_HUB_DIRECT_IP_URL_OVERRIDE=""
TEAM_HUB_DIRECT_IP_URL=""
EXPECTED_SERVER_IDENTITY=""
EXPECTED_TEAM_HUB_ID=""
EXPECTED_TEAM_HUB_TRANSPORT=""
EXPECTED_TEAM_HUB_TRANSPORT_SET="false"
EXPECTED_TEAM_HUB_URL=""
EXPECTED_TEAM_HUB_URL_SET="false"
EXPECTED_TEAM_HUB_DIRECT_IP_URL=""
EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET="false"
TEAM_HUB_SNAPSHOT=""
TEAM_HUB_DATA_DIR=""
TEAM_HUB_OPERATION_ID=""
# The detached updater passes these private continuity fields in its
# environment so a beta-to-stable transition remains compatible with older
# signed installers that do not recognize new CLI flags. Explicit CLI values
# below override these defaults for current-version callers.
MANAGED_UPDATE_ID="${AGENTSDOCK_MANAGED_UPDATE_ID:-}"
EXPECTED_SERVICE_CGROUP="${AGENTSDOCK_EXPECTED_SERVICE_CGROUP:-}"
unset AGENTSDOCK_MANAGED_UPDATE_ID AGENTSDOCK_EXPECTED_SERVICE_CGROUP
SYSTEMD_MANAGED_STOP_ATTEMPTS=50
SYSTEMD_MANAGED_STOP_DELAY=0.1
SYSTEMD_MANAGED_KILL_ATTEMPTS=20

if [[ -t 1 ]] && [[ "${TERM:-}" != "dumb" ]] && [[ -z "${NO_COLOR+x}" ]]; then
  COLOR_GREEN=$'\033[32m'
  COLOR_RED=$'\033[31m'
  COLOR_YELLOW=$'\033[33m'
  COLOR_BOLD=$'\033[1m'
  COLOR_RESET=$'\033[0m'
else
  COLOR_GREEN=""
  COLOR_RED=""
  COLOR_YELLOW=""
  COLOR_BOLD=""
  COLOR_RESET=""
fi
CHECK_MARK="${COLOR_GREEN}✓${COLOR_RESET}"
CROSS_MARK="${COLOR_RED}✗${COLOR_RESET}"
DOT_MARK="${COLOR_YELLOW}○${COLOR_RESET}"

usage() {
  cat <<'USAGE'
Usage: ./install.sh [--port PORT] [--bind ADDRESS] [--release-version VERSION] [--team-hub-host|--reactivate-team-hub-host|--no-team-hub-host] [--team-hub-tailscale-serve-url URL] [--team-hub-direct-ip-url URL] [--non-interactive] [--allow-port-fallback|--no-port-fallback]

--instance NAME updates a named instance (use ./instances.sh new to create one
with an automatically selected name/port). No arguments retain default setup.

Installs or updates AgentsServer for the current user. Releases and Python
runtimes are versioned, the previous healthy release is retained for rollback,
and existing chat state and generated tokens are preserved. No sudo privileges
are required.

--non-interactive skips optional prompts (including clipboard copy); use it for
unattended/SSH-driven runs.

--port pins the exact requested port unless --allow-port-fallback is also set.
Without --port, setup may select one of the next 5 ports when the default is
already occupied by a service that does not authenticate as AgentsServer.

--allow-port-fallback enables nearby-port selection even with an explicit
--port value.

--no-port-fallback disables automatically retrying on the next free port when
the default port is already held by another process.

--team-hub-host designates this server as the one Team Hub host. It defaults
to host-local access. For remote private-tailnet access, also pass the exact
Tailscale Serve URL ending in /api/team-hub.
--team-hub-tailscale-serve-url selects private Tailscale Serve HTTPS transport
for this host. It implies --team-hub-host and rejects Funnel-capable ports.
--team-hub-direct-ip-url adds an advanced, unencrypted raw IPv4 route on the
same AgentsServer origin. It implies --team-hub-host. IP shape is not identity
or Tailscale attestation; credentials and messages are plaintext on this route.
--reactivate-team-hub-host explicitly reactivates preserved Hub state after
verifying its managed binding matches this server's durable identity and
writing a verified pre-reactivation snapshot. It may be combined with either
Team Hub route option above.
--no-team-hub-host stops Team Hub hosting while preserving its state. This beta
never silently reactivates preserved state. Without an explicit host option, an
existing host/disabled setting is preserved; new installs default to disabled.

--show-token prints the current access token for an already-installed
AgentsServer without reinstalling or restarting. Interactive terminals offer
optional clipboard copy; redirected output remains just the raw token.
USAGE
}

SHOW_TOKEN="false"

while (($#)); do
  case "$1" in
    --instance) INSTANCE_NAME="${2:?--instance requires a name}"; INSTANCE_EXPLICIT="true"; shift 2 ;;
    --port) PORT="${2:-}"; PORT_EXPLICIT="true"; shift 2 ;;
    --bind) BIND_ADDRESS="${2:-}"; BIND_EXPLICIT="true"; shift 2 ;;
    --release-version) RELEASE_VERSION="${2:-}"; shift 2 ;;
    --non-interactive) NON_INTERACTIVE="true"; shift ;;
    --allow-port-fallback) PORT_FALLBACK="true"; shift ;;
    --no-port-fallback) PORT_FALLBACK="false"; shift ;;
    --team-hub-host)
      if [[ "$TEAM_HUB_MODE_OVERRIDE" == "disabled" ]]; then
        echo "--team-hub-host and --no-team-hub-host cannot be combined." >&2
        exit 2
      fi
      TEAM_HUB_MODE_OVERRIDE="host"
      shift
      ;;
    --reactivate-team-hub-host)
      if [[ "$TEAM_HUB_MODE_OVERRIDE" == "disabled" ]]; then
        echo "--reactivate-team-hub-host and --no-team-hub-host cannot be combined." >&2
        exit 2
      fi
      TEAM_HUB_REACTIVATION_REQUESTED="true"
      TEAM_HUB_MODE_OVERRIDE="host"
      shift
      ;;
    # Internal: emitted only by an admitted detached updater after the live
    # host reported a bounded startup failure. The installer independently
    # rebinds and snapshots the cold generation before takeover.
    --repair-failed-team-hub-host)
      TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED="true"
      shift
      ;;
    --team-hub-tailscale-serve-url)
      if [[ "$TEAM_HUB_MODE_OVERRIDE" == "disabled" ]]; then
        echo "--team-hub-tailscale-serve-url and --no-team-hub-host cannot be combined." >&2
        exit 2
      fi
      if (($# < 2)) || [[ -z "${2:-}" || "${2:-}" == --* ]]; then
        echo "--team-hub-tailscale-serve-url requires a URL." >&2
        exit 2
      fi
      TEAM_HUB_URL_OVERRIDE="${2:-}"
      TEAM_HUB_TRANSPORT_OVERRIDE="tailscale_serve"
      TEAM_HUB_MODE_OVERRIDE="host"
      shift 2
      ;;
    --team-hub-direct-ip-url)
      if [[ "$TEAM_HUB_MODE_OVERRIDE" == "disabled" ]]; then
        echo "--team-hub-direct-ip-url and --no-team-hub-host cannot be combined." >&2
        exit 2
      fi
      if (($# < 2)) || [[ -z "${2:-}" || "${2:-}" == --* ]]; then
        echo "--team-hub-direct-ip-url requires a URL." >&2
        exit 2
      fi
      TEAM_HUB_DIRECT_IP_URL_OVERRIDE="${2:-}"
      TEAM_HUB_MODE_OVERRIDE="host"
      shift 2
      ;;
    --no-team-hub-host)
      if [[ "$TEAM_HUB_MODE_OVERRIDE" == "host" ]]; then
        echo "Team Hub host/reactivation options and --no-team-hub-host cannot be combined." >&2
        exit 2
      fi
      TEAM_HUB_MODE_OVERRIDE="disabled"
      shift
      ;;
    # Internal, fail-closed continuity assertions passed only by the
    # authenticated managed updater.
    --expected-server-identity) EXPECTED_SERVER_IDENTITY="${2:-}"; shift 2 ;;
    --expected-team-hub-id) EXPECTED_TEAM_HUB_ID="${2:-}"; shift 2 ;;
    --expected-team-hub-transport)
      if (($# < 2)); then
        echo "--expected-team-hub-transport requires a value." >&2
        exit 2
      fi
      EXPECTED_TEAM_HUB_TRANSPORT="${2:-}"
      EXPECTED_TEAM_HUB_TRANSPORT_SET="true"
      shift 2
      ;;
    --expected-team-hub-url)
      if (($# < 2)); then
        echo "--expected-team-hub-url requires a value (empty for loopback)." >&2
        exit 2
      fi
      EXPECTED_TEAM_HUB_URL="${2:-}"
      EXPECTED_TEAM_HUB_URL_SET="true"
      shift 2
      ;;
    --expected-team-hub-direct-ip-url)
      if (($# < 2)); then
        echo "--expected-team-hub-direct-ip-url requires a value (empty when absent)." >&2
        exit 2
      fi
      EXPECTED_TEAM_HUB_DIRECT_IP_URL="${2:-}"
      EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET="true"
      shift 2
      ;;
    --team-hub-snapshot) TEAM_HUB_SNAPSHOT="${2:-}"; shift 2 ;;
    --team-hub-data-dir) TEAM_HUB_DATA_DIR="${2:-}"; shift 2 ;;
    --team-hub-operation-id) TEAM_HUB_OPERATION_ID="${2:-}"; shift 2 ;;
    --managed-update-id) MANAGED_UPDATE_ID="${2:-}"; shift 2 ;;
    --expected-service-cgroup) EXPECTED_SERVICE_CGROUP="${2:-}"; shift 2 ;;
    --show-token) SHOW_TOKEN="true"; shift ;;
    -h|--help) usage; exit 0 ;;
    *) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
  esac
done

if [[ ! "$INSTANCE_NAME" =~ ^[a-z][a-z0-9-]{0,31}$ ]]; then
  echo "Invalid instance name." >&2
  exit 2
fi
if [[ "$INSTANCE_NAME" != "default" || ( "$INSTANCE_EXPLICIT" == "true" && "${AGENTS_SERVER_INSTANCE:-default}" != "default" ) ]]; then
  INSTANCE_SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
  instance_bindings="$(bash "$INSTANCE_SCRIPT_DIR/instances.sh" _bindings "$INSTANCE_NAME")" || exit 2
  eval "$instance_bindings"
  # Never inherit the default instance's token, Hub designation or history.
  unset AGENTSDOCK_AGENT_TOKEN ZENITHDOCK_AGENT_TOKEN ZENITHBOT_AGENT_TOKEN
  export AGENTS_SERVER_INSTANCE="$INSTANCE_NAME"
  export AGENTS_SERVER_INSTALL_DIR="$INSTALL_ROOT" AGENTS_SERVER_CONFIG_DIR="$CONFIG_ROOT" AGENTSDOCK_STATE_DIR="$STATE_ROOT"
  [[ -n "${AGENTSDOCK_SERVER_NAME:-}" ]] || export AGENTSDOCK_SERVER_NAME="$INSTANCE_NAME"
  PORT_FALLBACK="false"
fi
export AGENTS_SERVER_INSTANCE="$INSTANCE_NAME"
if [[ "$INSTANCE_NAME" != "default" && ! -f "$CONFIG_ROOT/env" && "$PORT_EXPLICIT" != "true" && "$SHOW_TOKEN" != "true" ]]; then
  echo "A new named instance needs --port; use ./instances.sh new for automatic allocation." >&2
  exit 2
fi

if [[ "$PORT_FALLBACK" == "auto" ]]; then
  if [[ "$PORT_EXPLICIT" == "true" ]]; then
    PORT_FALLBACK="false"
  else
    PORT_FALLBACK="true"
  fi
fi

if [[ ! "$PORT" =~ ^[0-9]+$ ]] || ((PORT < 1 || PORT > 65535)); then
  echo "Port must be an integer between 1 and 65535." >&2
  exit 2
fi

if [[ -n "$EXPECTED_SERVER_IDENTITY" ]] && [[ ! "$EXPECTED_SERVER_IDENTITY" =~ ^[A-Za-z0-9_.:-]{8,240}$ ]]; then
  echo "Expected server identity is invalid." >&2
  exit 2
fi
if [[ -n "$EXPECTED_TEAM_HUB_ID" ]] && [[ ! "$EXPECTED_TEAM_HUB_ID" =~ ^[A-Za-z0-9_.:-]{8,240}$ ]]; then
  echo "Expected Team Hub identity is invalid." >&2
  exit 2
fi
if [[ -n "$TEAM_HUB_OPERATION_ID" ]] && [[ ! "$TEAM_HUB_OPERATION_ID" =~ ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ ]]; then
  echo "Managed Team Hub operation ID is invalid." >&2
  exit 2
fi
if [[ -n "$MANAGED_UPDATE_ID" ]] && [[ ! "$MANAGED_UPDATE_ID" =~ ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ ]]; then
  echo "Managed update ID is invalid." >&2
  exit 2
fi
if [[ -n "$EXPECTED_SERVICE_CGROUP" ]] && [[ ! "$EXPECTED_SERVICE_CGROUP" =~ ^/([A-Za-z0-9_.@:-]+/)*[A-Za-z0-9_.@:-]+$ ]]; then
  echo "Expected service cgroup is invalid." >&2
  exit 2
fi
if [[ -n "$EXPECTED_SERVICE_CGROUP" && -z "$MANAGED_UPDATE_ID" ]]; then
  echo "Expected service cgroup requires a managed update ID." >&2
  exit 2
fi
if [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
  if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_MODE_OVERRIDE" == "disabled" ]]; then
    echo "Failed Team Hub repair cannot change or reactivate host mode." >&2
    exit 2
  fi
  if [[ -z "$EXPECTED_SERVER_IDENTITY" || -z "$MANAGED_UPDATE_ID" ]]; then
    echo "Failed Team Hub repair requires an identity-bound managed update." >&2
    exit 2
  fi
  if [[ -n "$EXPECTED_TEAM_HUB_ID" || -n "$TEAM_HUB_SNAPSHOT" \
    || -n "$TEAM_HUB_DATA_DIR" || -n "$TEAM_HUB_OPERATION_ID" ]]; then
    echo "Failed Team Hub repair cannot reuse live-host rollback arguments." >&2
    exit 2
  fi
  if [[ "$EXPECTED_TEAM_HUB_TRANSPORT_SET" != "true" \
    || "$EXPECTED_TEAM_HUB_URL_SET" != "true" \
    || "$EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET" != "true" ]]; then
    echo "Failed Team Hub repair requires exact transport continuity assertions." >&2
    exit 2
  fi
fi
if [[ -n "$EXPECTED_TEAM_HUB_ID" ]]; then
  if [[ "$EXPECTED_TEAM_HUB_TRANSPORT_SET" == "false" && "$EXPECTED_TEAM_HUB_URL_SET" == "false" ]]; then
    # A beta.2 managed updater cannot pass these additive continuity fields.
    # Its only supported Team Hub transport was loopback, so bind that legacy
    # operation to loopback explicitly rather than consulting mutable env.
    EXPECTED_TEAM_HUB_TRANSPORT="loopback"
    EXPECTED_TEAM_HUB_TRANSPORT_SET="true"
    EXPECTED_TEAM_HUB_URL=""
    EXPECTED_TEAM_HUB_URL_SET="true"
  elif [[ "$EXPECTED_TEAM_HUB_TRANSPORT_SET" != "$EXPECTED_TEAM_HUB_URL_SET" ]]; then
    echo "Managed Team Hub transport and URL assertions must be supplied together." >&2
    exit 2
  fi
  if [[ "$EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET" != "true" ]]; then
    # Runners predating the Direct IP route contract could only have accepted
    # a route set without Direct IP. Preserve that exact absence rather than
    # adopting a previously ignored environment value during the update.
    EXPECTED_TEAM_HUB_DIRECT_IP_URL=""
    EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET="true"
  fi
fi
if [[ "$EXPECTED_TEAM_HUB_TRANSPORT_SET" == "true" && "$EXPECTED_TEAM_HUB_TRANSPORT" != "loopback" && "$EXPECTED_TEAM_HUB_TRANSPORT" != "tailscale_serve" && "$EXPECTED_TEAM_HUB_TRANSPORT" != "direct_ip" ]]; then
  echo "Expected Team Hub transport is invalid." >&2
  exit 2
fi
if [[ -n "$EXPECTED_TEAM_HUB_ID" || "$EXPECTED_TEAM_HUB_TRANSPORT_SET" == "true" || "$EXPECTED_TEAM_HUB_URL_SET" == "true" || "$EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET" == "true" || -n "$TEAM_HUB_SNAPSHOT" || -n "$TEAM_HUB_DATA_DIR" || -n "$TEAM_HUB_OPERATION_ID" ]]; then
  if [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" != "true" ]] && { \
    [[ -z "$EXPECTED_SERVER_IDENTITY" || -z "$EXPECTED_TEAM_HUB_ID" \
      || "$EXPECTED_TEAM_HUB_TRANSPORT_SET" != "true" \
      || "$EXPECTED_TEAM_HUB_URL_SET" != "true" \
      || -z "$TEAM_HUB_SNAPSHOT" || -z "$TEAM_HUB_DATA_DIR" \
      || -z "$TEAM_HUB_OPERATION_ID" ]]; \
  }; then
    echo "Managed Team Hub rollback arguments must be supplied together with the expected server identity." >&2
    exit 2
  fi
fi

SOURCE_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"

normalize_managed_path() {
  local label="$1"
  local candidate="$2"
  local parent=""
  local leaf=""
  local physical_parent=""
  local normalized=""
  local 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
  leaf="${candidate##*/}"
  parent="${candidate%/*}"
  [[ -n "$parent" ]] || parent="/"
  while [[ ! -d "$parent" && "$parent" != "/" ]]; do
    leaf="${parent##*/}/$leaf"
    parent="${parent%/*}"
    [[ -n "$parent" ]] || 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)" || 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
LEGACY_STATE_GUARD="$(normalize_managed_path LEGACY_STATE_ROOT "$LEGACY_STATE_ROOT")" \
  || exit 2
DEFAULT_STATE_GUARD="$(normalize_managed_path DEFAULT_STATE_ROOT \
  "$HOME/.agentsdock")" || exit 2
LEGACY_STATE_ROOT="$LEGACY_STATE_GUARD"
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" \
  || paths_overlap "$INSTALL_ROOT" "$LEGACY_STATE_GUARD" \
  || paths_overlap "$CONFIG_ROOT" "$LEGACY_STATE_GUARD" \
  || paths_overlap "$STATE_ROOT" "$LEGACY_STATE_GUARD"; then
  echo "Refusing overlapping install, configuration, and state roots; each must be a separate directory." >&2
  exit 2
fi
if [[ "$STATE_ROOT" == "$DEFAULT_STATE_GUARD" \
  && ( -e "$LEGACY_STATE_ROOT" || -L "$LEGACY_STATE_ROOT" ) \
  && ! -L "$LEGACY_STATE_ROOT" \
  && ! -e "$STATE_ROOT" ]]; then
  legacy_state_mode=""
  if [[ ! -d "$LEGACY_STATE_ROOT" || ! -O "$LEGACY_STATE_ROOT" ]]; then
    echo "The legacy state path is not a safe owned directory; refusing to migrate it." >&2
    exit 2
  fi
  legacy_state_mode="$(stat -c '%a' "$LEGACY_STATE_ROOT" 2>/dev/null \
    || stat -f '%Lp' "$LEGACY_STATE_ROOT" 2>/dev/null)" || exit 2
  if [[ ! "$legacy_state_mode" =~ ^[0-7]{3,4}$ \
    || $((8#$legacy_state_mode & 8#022)) -ne 0 ]]; then
    echo "The legacy state directory is group/world writable; refusing to migrate it." >&2
    exit 2
  fi
fi

if [[ -z "$RELEASE_VERSION" && -f "$SOURCE_DIR/VERSION" ]]; then
  RELEASE_VERSION="$(tr -d '[:space:]' < "$SOURCE_DIR/VERSION")"
fi
if [[ ! "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-+][A-Za-z0-9.-]+)?$ ]]; then
  echo "Release version is missing or invalid." >&2
  exit 2
fi
REQUESTED_RELEASE_VERSION="$RELEASE_VERSION"

validate_positive_integer() {
  local name="$1"
  local value="$2"
  if [[ ! "$value" =~ ^[0-9]+$ ]] || ((value < 1)); then
    echo "$name must be a positive integer, got: $value" >&2
    exit 2
  fi
}

validate_positive_integer "AGENTS_SERVER_DEPENDENCY_TIMEOUT_SECONDS" "$DEPENDENCY_SYNC_TIMEOUT_SECONDS"
validate_positive_integer "AGENTS_SERVER_INSTALL_HEARTBEAT_SECONDS" "$INSTALL_HEARTBEAT_SECONDS"
validate_positive_integer "AGENTS_SERVER_HEALTH_CHECK_ATTEMPTS" "$HEALTH_CHECK_ATTEMPTS"

RELEASES_ROOT="$INSTALL_ROOT/releases"
RELEASE_DIR="$RELEASES_ROOT/$RELEASE_VERSION"
STAGE_DIR="$RELEASES_ROOT/.staging-$RELEASE_VERSION-$$"
STAGE_DIR_DEVICE=""
STAGE_DIR_INODE=""
CANDIDATE_RUNTIME_ROOT="$STAGE_DIR"
CURRENT_LINK="$INSTALL_ROOT/current"
PREVIOUS_LINK="$INSTALL_ROOT/previous"
ACTIVATION_TRANSACTION_DIR="$INSTALL_ROOT/.activation-transaction"
ACTIVATION_TRANSACTION_RESUMED="false"
ACTIVATION_TRANSACTION_PHASE=""
ACTIVATION_ROLLBACK_FROM=""
ACTIVATION_TRANSACTION_ID=""
ACTIVATION_INTENT="ordinary"
ACTIVATION_HUB_KIND=""
ORIGINAL_OLD_SOURCE=""
ROLLBACK_RELEASE_ROOT=""
ENV_FILE="$CONFIG_ROOT/env"
LEGACY_SERVICE_FILE="$HOME/.config/systemd/user/$LEGACY_SERVICE_NAME.service"
OLD_TARGET=""
RELEASE_ACTIVATED="false"
CANDIDATE_SERVICE_MAY_HAVE_STARTED="false"
SERVICE_STOPPED_FOR_COLD_HANDOFF="false"
TEAM_HUB_COLD_GUARD_PENDING="false"
TEAM_HUB_COLD_GUARD_ID=""
TEAM_HUB_COLD_GUARD_DEVICE=""
TEAM_HUB_COLD_GUARD_INODE=""
TEAM_HUB_REACTIVATION_FENCE_DEVICE=""
TEAM_HUB_REACTIVATION_FENCE_INODE=""
TEAM_HUB_OPERATION_FENCE_DEVICE=""
TEAM_HUB_OPERATION_FENCE_INODE=""
TEAM_HUB_STARTUP_AUTHORITY_PENDING="false"
TEAM_HUB_RECOVERY_ATTEMPTED="false"
TEAM_HUB_OPERATION_FINALIZED="false"
TEAM_HUB_OPERATION_PENDING="false"
[[ -z "$EXPECTED_TEAM_HUB_ID" ]] || TEAM_HUB_OPERATION_PENDING="true"
if [[ ( "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
  || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ) \
  && "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  echo "Explicit Team Hub reactivation cannot be combined with a managed Team Hub update." >&2
  exit 2
fi
IN_EXIT_CLEANUP="false"
ENV_CONFIG_BACKUP=""
ENV_CONFIG_EXISTED="false"
ENV_CONFIG_CAPTURED="false"
SERVICE_CONFIG_BACKUP=""
SERVICE_CONFIG_EXISTED="false"
SERVICE_CONFIG_CAPTURED="false"
PRIOR_SERVICE_STATE="absent"
PRIOR_SERVICE_ENABLED="false"
PRIOR_LEGACY_SERVICE_STATE="absent"
PRIOR_LEGACY_SERVICE_ENABLED="false"
# Canonical, non-secret continuity proof captured from the authenticated old
# server immediately before takeover.  A disabled static host mode may still
# be an active secure-peer Teamspace client, so candidate health must preserve
# that exact pairing rather than misclassifying the client as a disabled Hub.
EXPECTED_TEAM_HUB_CLIENT_BINDING=""

scrub_staged_process_environment() {
  unset \
    AGENTSDOCK_AGENT_TOKEN \
    AGENTSDOCK_PROVIDER_AUTHORITY_FILE \
    AGENTSDOCK_PUBLISH_TOKEN \
    ZENITHBOT_AGENT_TOKEN \
    ZENITHDOCK_AGENT_TOKEN
}

run_without_server_secrets() (
  scrub_staged_process_environment
  "$@"
)

team_hub_control_runtime() {
  local preferred_root="${1:-}"
  local candidate=""
  for candidate in \
    "$ACTIVATION_TRANSACTION_DIR/candidate.retired" \
    "$preferred_root" \
    "${OLD_TARGET:-}" \
    "$CURRENT_LINK" \
    "$RELEASE_DIR" \
    "$STAGE_DIR" \
    "$SOURCE_DIR"; do
    [[ -n "$candidate" ]] || continue
    if [[ -f "$candidate/agentsdock_team_hub/store.py" && -x "$candidate/.venv/bin/python" ]]; then
      printf '%s\n%s\n' "$candidate/.venv/bin/python" "$candidate"
      return 0
    fi
  done
  return 1
}

clear_team_hub_operation_fence() {
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]] || return 0
  local allow_missing="${2:-false}"
  local runtime=""
  local python_path=""
  local source_root=""
  runtime="$(team_hub_control_runtime "${1:-}")" || {
    echo "No installed runtime can verify the Team Hub maintenance fence." >&2
    return 1
  }
  python_path="${runtime%%$'\n'*}"
  source_root="${runtime#*$'\n'}"
  run_without_server_secrets env PYTHONPATH="$source_root" "$python_path" -c '
from pathlib import Path
import sys
from agentsdock_team_hub.store import HubStore

cleared = HubStore.clear_maintenance_fence_control(
    Path(sys.argv[1]),
    expected_hub_id=sys.argv[2],
    expected_host_identity=sys.argv[3],
    expected_reason="server-update",
    expected_operation_id=sys.argv[4],
    expected_snapshot=Path(sys.argv[5]),
    expected_device=int(sys.argv[6]),
    expected_inode=int(sys.argv[7]),
)
if not cleared and sys.argv[8] != "true":
    raise RuntimeError("the exact Team Hub maintenance fence is missing")
' \
    "$TEAM_HUB_DATA_DIR" \
    "$EXPECTED_TEAM_HUB_ID" \
    "$EXPECTED_SERVER_IDENTITY" \
    "$TEAM_HUB_OPERATION_ID" \
    "$TEAM_HUB_SNAPSHOT" \
    "$TEAM_HUB_OPERATION_FENCE_DEVICE" \
    "$TEAM_HUB_OPERATION_FENCE_INODE" \
    "$allow_missing"
}

clear_team_hub_reactivation_fence() {
  [[ "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]] || return 0
  local allow_missing="${2:-false}"
  local runtime=""
  local python_path=""
  local source_root=""
  runtime="$(team_hub_control_runtime "${1:-}")" || {
    echo "No installed runtime can verify the Team Hub reactivation fence." >&2
    return 1
  }
  python_path="${runtime%%$'\n'*}"
  source_root="${runtime#*$'\n'}"
  run_without_server_secrets env PYTHONPATH="$source_root" "$python_path" -c '
from pathlib import Path
import sys
from agentsdock_team_hub.store import HubStore

cleared = HubStore.clear_maintenance_fence_control(
    Path(sys.argv[1]),
    expected_hub_id=sys.argv[2],
    expected_host_identity=sys.argv[3],
    expected_reason="host-reactivation",
    expected_operation_id=sys.argv[4],
    expected_snapshot=Path(sys.argv[5]),
    expected_device=int(sys.argv[6]),
    expected_inode=int(sys.argv[7]),
)
if not cleared and sys.argv[8] != "true":
    raise RuntimeError("the exact Team Hub reactivation fence is missing")
' \
    "$TEAM_HUB_CANONICAL_DATA_DIR" \
    "$TEAM_HUB_REACTIVATION_HUB_ID" \
    "$EXPECTED_SERVER_IDENTITY" \
    "$TEAM_HUB_REACTIVATION_OPERATION_ID" \
    "$TEAM_HUB_REACTIVATION_SNAPSHOT" \
    "$TEAM_HUB_REACTIVATION_FENCE_DEVICE" \
    "$TEAM_HUB_REACTIVATION_FENCE_INODE" \
    "$allow_missing"
}

team_hub_startup_authority_control() {
  local action="$1"
  local runtime_root="${2:-$RELEASE_DIR}"
  local allow_missing="${3:-false}"
  local data_dir=""
  local hub_id=""
  local reason=""
  local operation_id=""
  local snapshot=""
  if [[ "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
    data_dir="$TEAM_HUB_CANONICAL_DATA_DIR"
    hub_id="$TEAM_HUB_REACTIVATION_HUB_ID"
    reason="host-reactivation"
    operation_id="$TEAM_HUB_REACTIVATION_OPERATION_ID"
    snapshot="$TEAM_HUB_REACTIVATION_SNAPSHOT"
  elif [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
    data_dir="$TEAM_HUB_DATA_DIR"
    hub_id="$EXPECTED_TEAM_HUB_ID"
    reason="server-update"
    operation_id="$TEAM_HUB_OPERATION_ID"
    snapshot="$TEAM_HUB_SNAPSHOT"
  else
    return 0
  fi
  local arguments=(
    "${action}-fenced-start-authority"
    --data-dir "$data_dir"
    --snapshot "$snapshot"
    --expected-host-identity "$EXPECTED_SERVER_IDENTITY"
    --expected-hub-id "$hub_id"
    --expected-reason "$reason"
    --expected-operation-id "$operation_id"
  )
  if [[ "$action" == "clear" && "$allow_missing" == "true" ]]; then
    arguments+=(--allow-missing)
  fi
  run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
    "${arguments[@]}" >/dev/null
}

publish_team_hub_startup_authority() {
  if team_hub_startup_authority_control publish "${1:-$RELEASE_DIR}"; then
    TEAM_HUB_STARTUP_AUTHORITY_PENDING="true"
    return 0
  fi
  return 1
}

clear_team_hub_startup_authority() {
  [[ "$TEAM_HUB_STARTUP_AUTHORITY_PENDING" == "true" ]] || return 0
  if team_hub_startup_authority_control \
      clear "${1:-$RELEASE_DIR}" "${2:-false}"; then
    TEAM_HUB_STARTUP_AUTHORITY_PENDING="false"
    return 0
  fi
  return 1
}

mask_install_signals() {
  trap '' HUP INT TERM
}

resume_install_signals() {
  trap 'exit 130' HUP INT TERM
}

verify_team_hub_operation_fence() {
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]] || return 0
  local runtime=""
  local python_path=""
  local source_root=""
  local result=""
  local returned_device=""
  local returned_inode=""
  runtime="$(team_hub_control_runtime "${1:-}")" || {
    echo "No installed runtime can verify the Team Hub maintenance fence." >&2
    return 1
  }
  python_path="${runtime%%$'\n'*}"
  source_root="${runtime#*$'\n'}"
  result="$(run_without_server_secrets env PYTHONPATH="$source_root" "$python_path" -c '
import os
from pathlib import Path
import sys
from agentsdock_team_hub.store import HubStore

fence = Path(sys.argv[1]) / "maintenance-fence.json"
before = fence.lstat()
matched = HubStore.maintenance_fence_matches_control(
    Path(sys.argv[1]),
    expected_hub_id=sys.argv[2],
    expected_host_identity=sys.argv[3],
    expected_reason="server-update",
    expected_operation_id=sys.argv[4],
    expected_snapshot=Path(sys.argv[5]),
)
if not matched:
    raise RuntimeError("the exact Team Hub maintenance fence is missing")
after = fence.lstat()
if (before.st_dev, before.st_ino) != (after.st_dev, after.st_ino):
    raise RuntimeError("the exact Team Hub maintenance fence changed")
print(after.st_dev)
print(after.st_ino)
' \
    "$TEAM_HUB_DATA_DIR" \
    "$EXPECTED_TEAM_HUB_ID" \
    "$EXPECTED_SERVER_IDENTITY" \
    "$TEAM_HUB_OPERATION_ID" \
    "$TEAM_HUB_SNAPSHOT")" || return 1
  returned_device="${result%%$'\n'*}"
  returned_inode="${result#*$'\n'}"
  if [[ "$result" != *$'\n'* \
    || ! "$returned_device" =~ ^[1-9][0-9]*$ \
    || ! "$returned_inode" =~ ^[1-9][0-9]*$ \
    || "$returned_inode" == *$'\n'* ]]; then
    echo "Team Hub maintenance fence verifier returned invalid ownership." >&2
    return 1
  fi
  TEAM_HUB_OPERATION_FENCE_DEVICE="$returned_device"
  TEAM_HUB_OPERATION_FENCE_INODE="$returned_inode"
}

verify_team_hub_rollback_snapshot() {
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]] || return 0
  local runtime=""
  local python_path=""
  local source_root=""
  runtime="$(team_hub_control_runtime "${1:-}")" || {
    echo "No installed runtime can verify the Team Hub rollback snapshot." >&2
    return 1
  }
  python_path="${runtime%%$'\n'*}"
  source_root="${runtime#*$'\n'}"
  run_without_server_secrets env PYTHONPATH="$source_root" "$python_path" -m agentsdock_team_hub.cli \
    verify-snapshot \
    --data-dir "$TEAM_HUB_DATA_DIR" \
    --snapshot "$TEAM_HUB_SNAPSHOT" \
    --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
    --expected-hub-id "$EXPECTED_TEAM_HUB_ID" \
    --expected-operation-id "$TEAM_HUB_OPERATION_ID"
}

rebase_team_hub_rollback_snapshot() {
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]] || return 0
  run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
    "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" -m agentsdock_team_hub.cli \
    rebase-snapshot \
    --data-dir "$TEAM_HUB_DATA_DIR" \
    --snapshot "$TEAM_HUB_SNAPSHOT" \
    --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
    --expected-hub-id "$EXPECTED_TEAM_HUB_ID" \
    --expected-operation-id "$TEAM_HUB_OPERATION_ID" >/dev/null
}

verify_team_hub_reactivation_snapshot() {
  [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]] || return 0
  local runtime_root="$1"
  run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
    verify-host-reactivation-snapshot \
    --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
      --snapshot "$TEAM_HUB_REACTIVATION_SNAPSHOT" \
      --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
      --expected-hub-id "$TEAM_HUB_REACTIVATION_HUB_ID" \
      --expected-operation-id "$TEAM_HUB_REACTIVATION_OPERATION_ID" >/dev/null
}

early_operation_cleanup() {
  local exit_status=$?
  trap - EXIT
  mask_install_signals
  set +e
  if [[ "$exit_status" != "0" && "$TEAM_HUB_OPERATION_PENDING" == "true" && "$TEAM_HUB_OPERATION_FINALIZED" != "true" ]]; then
    if clear_team_hub_operation_fence "$CURRENT_LINK"; then
      TEAM_HUB_OPERATION_FINALIZED="true"
    else
      echo "AgentsServer install failed before takeover and could not clear the exact Team Hub maintenance fence." >&2
    fi
  fi
  exit "$exit_status"
}

trap early_operation_cleanup EXIT
trap 'exit 130' HUP INT TERM

safe_config_python() {
  local candidate=""
  for candidate in \
    "/usr/bin/python3" \
    "$(command -v python3 2>/dev/null || true)" \
    "$STAGE_DIR/.venv/bin/python" \
    "$INSTALL_ROOT/current/.venv/bin/python"; do
    [[ -n "$candidate" && -x "$candidate" ]] || continue
    if [[ "$("$candidate" -c 'print("agentsdock-safe-config-v1")' 2>/dev/null || true)" \
      == "agentsdock-safe-config-v1" ]]; then
      printf '%s\n' "$candidate"
      return 0
    fi
  done
  return 1
}

validate_bind_address() {
  local value="$1"
  local supplied_python="${2:-}"
  case "$value" in
    localhost|0.0.0.0|127.0.0.1|::|::1) return 0 ;;
  esac
  if [[ -z "$value" || ${#value} -gt 64 \
    || ! "$value" =~ ^[0-9A-Fa-f:.]+$ ]]; then
    return 1
  fi
  local python_path=""
  if [[ -n "$supplied_python" ]]; then
    [[ -x "$supplied_python" ]] || return 1
    python_path="$supplied_python"
  else
    # A fresh host may intentionally let uv create the release Python. The
    # strict canonical check is repeated with that staged interpreter before
    # any configuration or service publication; this early branch only needs
    # to reject control/config-injection characters without requiring Python.
    python_path="$(safe_config_python)" || return 0
  fi
  "$python_path" - "$value" <<'PY'
import ipaddress
import sys

value = sys.argv[1]
try:
    parsed = ipaddress.ip_address(value)
except ValueError:
    raise SystemExit(1)
if str(parsed) != value:
    raise SystemExit(1)
PY
}

read_owned_config_file() {
  local file="$1"
  local python_path=""
  python_path="$(safe_config_python)" || {
    echo "A trusted Python runtime is required to read existing AgentsServer configuration safely." >&2
    return 1
  }
  "$python_path" - "$file" <<'PY'
import os
from pathlib import Path
import stat
import sys

path = Path(os.path.abspath(os.path.expanduser(sys.argv[1])))
maximum = 16 * 1024 * 1024
flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
try:
    descriptor = os.open(path, flags)
except FileNotFoundError:
    raise SystemExit(3)
try:
    before = os.fstat(descriptor)
    if (
        not stat.S_ISREG(before.st_mode)
        or before.st_uid != os.geteuid()
        or before.st_nlink != 1
        or stat.S_IMODE(before.st_mode) & 0o022
        or not 0 <= before.st_size <= maximum
    ):
        raise PermissionError("configuration source is unsafe")
    chunks = []
    remaining = maximum + 1
    while remaining:
        chunk = os.read(descriptor, min(remaining, 1024 * 1024))
        if not chunk:
            break
        chunks.append(chunk)
        remaining -= len(chunk)
    payload = b"".join(chunks)
    after = os.fstat(descriptor)
    linked = path.lstat()
    if (
        len(payload) > maximum
        or len(payload) != before.st_size
        or b"\0" in payload
        or (before.st_dev, before.st_ino, before.st_size, before.st_mtime_ns)
        != (after.st_dev, after.st_ino, after.st_size, after.st_mtime_ns)
        or (before.st_dev, before.st_ino) != (linked.st_dev, linked.st_ino)
    ):
        raise RuntimeError("configuration source changed while reading")
    sys.stdout.buffer.write(payload)
finally:
    os.close(descriptor)
PY
}

if ! validate_bind_address "$BIND_ADDRESS"; then
  echo "Bind address must be localhost or one canonical IPv4/IPv6 literal." >&2
  exit 2
fi

read_env_value() {
  local file="$1"
  local name="$2"
  local contents=""
  [[ -n "$file" && ( -e "$file" || -L "$file" ) ]] || return 0
  contents="$(read_owned_config_file "$file")" || return 1
  printf '%s\n' "$contents" | sed -n "s/^${name}=//p" | tail -n 1
}

env_file_has_key() {
  local file="$1"
  local name="$2"
  local contents=""
  [[ -n "$file" && ( -e "$file" || -L "$file" ) ]] || return 1
  contents="$(read_owned_config_file "$file")" || {
    echo "$file changed or became unsafe while reading configuration." >&2
    exit 1
  }
  printf '%s\n' "$contents" | grep -q "^${name}="
}

decode_server_name_env_value() {
  local value="$1"
  local python_path=""
  python_path="$(safe_config_python)" || return 1
  "$python_path" - "$value" <<'PY'
import json
import sys

raw = sys.argv[1]
if raw.startswith('"'):
    try:
        value = json.loads(raw)
    except (TypeError, ValueError):
        raise SystemExit(1)
    if not isinstance(value, str):
        raise SystemExit(1)
else:
    value = raw
sys.stdout.write(value)
PY
}

canonical_server_name() {
  local value="$1"
  local python_path=""
  python_path="$(safe_config_python)" || return 1
  "$python_path" - "$value" <<'PY'
import sys
import unicodedata

value = sys.argv[1]
if any(unicodedata.category(character) == "Cc" for character in value):
    raise SystemExit(1)
value = value.strip()
try:
    encoded = value.encode("utf-8")
except UnicodeEncodeError:
    raise SystemExit(1)
if value and len(encoded) > 160:
    raise SystemExit(1)
sys.stdout.write(value)
PY
}

runtime_env_server_name() {
  local python_path=""
  python_path="$(safe_config_python)" || return 1
  "$python_path" - "$1" <<'PY'
import json
import sys

sys.stdout.write(json.dumps(sys.argv[1], ensure_ascii=False))
PY
}

xml_server_name() {
  local python_path=""
  python_path="$(safe_config_python)" || return 1
  "$python_path" - "$1" <<'PY'
import sys
from xml.sax.saxutils import escape

sys.stdout.write(escape(sys.argv[1], {'"': "&quot;", "'": "&apos;"}))
PY
}

read_persisted_team_hub_config() {
  RESOLVED_TEAM_HUB_MODE=""
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE; then
    RESOLVED_TEAM_HUB_MODE="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE)"
  elif env_file_has_key "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE; then
    RESOLVED_TEAM_HUB_MODE="$(read_env_value "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE)"
  else
    RESOLVED_TEAM_HUB_MODE="${AGENTSDOCK_TEAM_HUB_MODE:-}"
  fi

  RESOLVED_TEAM_HUB_TRANSPORT=""
  RESOLVED_TEAM_HUB_TRANSPORT_SET="false"
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT; then
    RESOLVED_TEAM_HUB_TRANSPORT="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT)"
    RESOLVED_TEAM_HUB_TRANSPORT_SET="true"
  elif env_file_has_key "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT; then
    RESOLVED_TEAM_HUB_TRANSPORT="$(read_env_value "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT)"
    RESOLVED_TEAM_HUB_TRANSPORT_SET="true"
  elif [[ "${AGENTSDOCK_TEAM_HUB_TRANSPORT+x}" == "x" ]]; then
    RESOLVED_TEAM_HUB_TRANSPORT="$AGENTSDOCK_TEAM_HUB_TRANSPORT"
    RESOLVED_TEAM_HUB_TRANSPORT_SET="true"
  fi

  RESOLVED_TEAM_HUB_URL=""
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_URL; then
    RESOLVED_TEAM_HUB_URL="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_URL)"
  elif env_file_has_key "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_URL; then
    RESOLVED_TEAM_HUB_URL="$(read_env_value "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_URL)"
  else
    RESOLVED_TEAM_HUB_URL="${AGENTSDOCK_TEAM_HUB_URL:-}"
  fi

  RESOLVED_TEAM_HUB_DIRECT_IP_URL=""
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL; then
    RESOLVED_TEAM_HUB_DIRECT_IP_URL="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL)"
  elif env_file_has_key "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL; then
    RESOLVED_TEAM_HUB_DIRECT_IP_URL="$(read_env_value "$LEGACY_ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL)"
  else
    RESOLVED_TEAM_HUB_DIRECT_IP_URL="${AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL:-}"
  fi
}

canonical_team_hub_tailnet_hostname() {
  local hostname="$1"
  local label=""
  local -a labels=()
  [[ "$hostname" != *. ]] || return 1
  IFS='.' read -r -a labels <<< "$hostname"
  ((${#labels[@]} >= 4)) || return 1
  [[ "${labels[${#labels[@]} - 2]}" == "ts" && "${labels[${#labels[@]} - 1]}" == "net" ]] || return 1
  for label in "${labels[@]}"; do
    (( ${#label} >= 1 && ${#label} <= 63 )) || return 1
    [[ "$label" != xn--* ]] || return 1
    if [[ ! "$label" =~ ^[a-z0-9]$ && ! "$label" =~ ^[a-z0-9][a-z0-9-]*[a-z0-9]$ ]]; then
      return 1
    fi
  done
}

canonical_team_hub_direct_ipv4_url() {
  local value="$1"
  local expected_port="$2"
  local direct_host=""
  local octet=""
  local -a octets=()
  [[ "$value" =~ ^http://([0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}):([0-9]{1,5})/api/team-hub$ ]] || return 1
  [[ "${BASH_REMATCH[2]}" == "$expected_port" ]] || return 1
  direct_host="${BASH_REMATCH[1]}"
  IFS='.' read -r -a octets <<< "$direct_host"
  ((${#octets[@]} == 4)) || return 1
  for octet in "${octets[@]}"; do
    [[ "$octet" =~ ^0$|^[1-9][0-9]{0,2}$ ]] || return 1
    ((10#$octet <= 255)) || return 1
  done
  ((10#${octets[0]} != 0 && 10#${octets[0]} != 127 && 10#${octets[0]} < 224)) || return 1
  [[ "$BIND_ADDRESS" == "0.0.0.0" \
    || "$BIND_ADDRESS" == "$direct_host" ]] || return 1
}

LEGACY_ENV_FILE=""
LEGACY_SERVICE_CONTENTS=""
if [[ "$INSTANCE_NAME" == "default" && ( -e "$LEGACY_SERVICE_FILE" || -L "$LEGACY_SERVICE_FILE" ) ]]; then
  if ! LEGACY_SERVICE_CONTENTS="$(read_owned_config_file "$LEGACY_SERVICE_FILE")"; then
    echo "$LEGACY_SERVICE_FILE is not a safe regular legacy service file." >&2
    exit 1
  fi
  LEGACY_ENV_FILE="$(printf '%s\n' "$LEGACY_SERVICE_CONTENTS" \
    | sed -n 's/^EnvironmentFile=//p' | tail -n 1)"
  LEGACY_ENV_FILE="${LEGACY_ENV_FILE#-}"
  LEGACY_ENV_FILE="${LEGACY_ENV_FILE#\"}"
  LEGACY_ENV_FILE="${LEGACY_ENV_FILE%\"}"
  if [[ "$LEGACY_ENV_FILE" == %h/* ]]; then
    LEGACY_ENV_FILE="$HOME/${LEGACY_ENV_FILE#%h/}"
  elif [[ -n "$LEGACY_ENV_FILE" && "$LEGACY_ENV_FILE" != /* ]]; then
    echo "$LEGACY_SERVICE_FILE has a non-absolute EnvironmentFile path." >&2
    exit 1
  fi
fi
if [[ "$INSTANCE_NAME" == "default" && -z "$LEGACY_ENV_FILE" \
  && ( -e "$HOME/Zenithbot/.env" || -L "$HOME/Zenithbot/.env" ) ]]; then
  LEGACY_ENV_FILE="$HOME/Zenithbot/.env"
fi

for existing_config in "$ENV_FILE" "$LEGACY_ENV_FILE"; do
  [[ -n "$existing_config" && ( -e "$existing_config" || -L "$existing_config" ) ]] \
    || continue
  if ! read_owned_config_file "$existing_config" >/dev/null; then
    echo "$existing_config is not a safe regular configuration file." >&2
    exit 1
  fi
done

find_existing_token() {
  local candidate found_token
  for candidate in "$ENV_FILE" "$LEGACY_ENV_FILE"; do
    [[ -n "$candidate" && ( -e "$candidate" || -L "$candidate" ) ]] || continue
    found_token="$(read_env_value "$candidate" AGENTSDOCK_AGENT_TOKEN)" || return 1
    if [[ -z "$found_token" ]]; then
      found_token="$(read_env_value "$candidate" ZENITHDOCK_AGENT_TOKEN)" \
        || return 1
    fi
    if [[ -z "$found_token" ]]; then
      found_token="$(read_env_value "$candidate" ZENITHBOT_AGENT_TOKEN)" \
        || return 1
    fi
    [[ -z "$found_token" ]] || { printf '%s' "$found_token"; return 0; }
  done
  if [[ -n "$LEGACY_SERVICE_CONTENTS" ]]; then
    found_token="$(printf '%s\n' "$LEGACY_SERVICE_CONTENTS" \
      | grep -E '^Environment="?ZENITHDOCK_AGENT_TOKEN=' | tail -n 1 || true)"
    found_token="${found_token#*ZENITHDOCK_AGENT_TOKEN=}"
    found_token="${found_token%\"}"
    [[ -z "$found_token" ]] || { printf '%s' "$found_token"; return 0; }
  fi
  return 1
}

interactive_token_output() {
  [[ "$NON_INTERACTIVE" != "true" && -t 0 && -t 1 && -z "$EXPECTED_SERVER_IDENTITY" ]]
}

print_token_for_copy() {
  local access_token="$1"
  local copy_reply=""
  local clipboard_command=()
  printf '\nAccess token (%s):\n%s\n\n' "$INSTANCE_NAME" "$access_token"
  # A remote clipboard is not the user's local clipboard. Do not emit OSC 52
  # sequences or attempt to modify a remote desktop's clipboard over SSH.
  if [[ -n "${SSH_CONNECTION:-}${SSH_CLIENT:-}${SSH_TTY:-}" ]]; then
    printf '%s\n' 'Clipboard copy is unavailable over SSH; copy the token line above manually.'
    return 0
  fi
  if [[ "$(uname -s)" == "Darwin" ]] && command -v pbcopy >/dev/null 2>&1; then
    clipboard_command=(pbcopy)
  elif [[ -n "${WAYLAND_DISPLAY:-}" ]] && command -v wl-copy >/dev/null 2>&1; then
    clipboard_command=(wl-copy)
  elif [[ -n "${DISPLAY:-}" ]] && command -v xclip >/dev/null 2>&1; then
    clipboard_command=(xclip -selection clipboard)
  elif [[ -n "${DISPLAY:-}" ]] && command -v xsel >/dev/null 2>&1; then
    clipboard_command=(xsel --clipboard --input)
  fi
  if ((${#clipboard_command[@]} == 0)); then
    printf '%s\n' 'Clipboard copy is unavailable here; copy the token line above manually.'
    return 0
  fi
  read -r -p "Copy token to this machine's clipboard? [y/N] " copy_reply || return 0
  case "$copy_reply" in
    y|Y|[yY][eE][sS]) ;;
    *) return 0 ;;
  esac
  # Pass the credential via stdin, never an external process's argv. Optional
  # clipboard failures must not turn a successful installation into a failure.
  if printf '%s' "$access_token" | "${clipboard_command[@]}" >/dev/null 2>&1; then
    printf '%s\n' 'Copied to your clipboard.'
  else
    printf '%s\n' 'Could not copy to the clipboard; copy the token line above manually.'
  fi
}

if [[ "$SHOW_TOKEN" == "true" ]]; then
  if TOKEN_TO_SHOW="$(find_existing_token)"; then
    if interactive_token_output; then
      print_token_for_copy "$TOKEN_TO_SHOW"
    else
      printf '%s\n' "$TOKEN_TO_SHOW"
    fi
    exit 0
  fi
  echo "No AgentsServer access token found at $ENV_FILE. Run install.sh first." >&2
  exit 1
fi

OS_NAME="$(uname -s)"
SYSTEMD_SERVICE_FILE="$HOME/.config/systemd/user/$SERVICE_NAME.service"
LABEL="${LABEL:-com.agentsdock.server}"
PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
SERVER_PATH=""
append_server_path() {
  local candidate="$1"
  [[ -n "$candidate" ]] || return 0
  case ":$SERVER_PATH:" in
    *":$candidate:"*) ;;
    *) SERVER_PATH="${SERVER_PATH:+$SERVER_PATH:}$candidate" ;;
  esac
}

append_server_path_list() {
  local path_list="$1"
  local candidate
  local old_ifs="$IFS"
  IFS=":"
  for candidate in $path_list; do
    append_server_path "$candidate"
  done
  IFS="$old_ifs"
}

EXISTING_PATH="$(read_env_value "$ENV_FILE" PATH)"
[[ -n "$EXISTING_PATH" ]] || EXISTING_PATH="$(read_env_value "$LEGACY_ENV_FILE" PATH)"
# Prefer the previously saved runtime PATH when present, otherwise retain the
# launcher's PATH. Add standard user and Homebrew locations without allowing
# repeated installs to grow the saved value indefinitely.
append_server_path_list "${EXISTING_PATH:-${PATH:-}}"
append_server_path "$HOME/.local/bin"
append_server_path "$HOME/.cargo/bin"
append_server_path "/opt/homebrew/bin"
append_server_path "/usr/local/bin"
append_server_path "/usr/bin"
append_server_path "/bin"
export PATH="$SERVER_PATH"

if [[ "$PORT_EXPLICIT" != "true" ]]; then
  existing_network_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_AGENT_PORT)" \
    || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" AGENTSDOCK_AGENT_PORT)" || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" ZENITHBOT_AGENT_PORT)" || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" ZENITHDOCK_AGENT_PORT)" || exit 1
  if [[ -n "$existing_network_value" ]]; then
    if [[ ! "$existing_network_value" =~ ^[0-9]+$ \
      || "$existing_network_value" -lt 1 \
      || "$existing_network_value" -gt 65535 ]]; then
      echo "The persisted AgentsServer port is invalid." >&2
      exit 2
    fi
    PORT="$existing_network_value"
  fi
fi
if [[ "$BIND_EXPLICIT" != "true" ]]; then
  existing_network_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_AGENT_BIND)" \
    || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" AGENTSDOCK_AGENT_BIND)" || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" ZENITHBOT_AGENT_BIND)" || exit 1
  [[ -n "$existing_network_value" ]] || existing_network_value="$(read_env_value \
    "$LEGACY_ENV_FILE" ZENITHDOCK_AGENT_BIND)" || exit 1
  if [[ -n "$existing_network_value" ]]; then
    validate_bind_address "$existing_network_value" || {
      echo "The persisted AgentsServer bind address is invalid." >&2
      exit 2
    }
    BIND_ADDRESS="$existing_network_value"
  fi
fi

EXISTING_ENV_TEAM_HUB_MODE_SET="false"
EXISTING_ENV_TEAM_HUB_MODE_VALUE=""
EXISTING_ENV_TEAM_HUB_TRANSPORT_SET="false"
EXISTING_ENV_TEAM_HUB_TRANSPORT_VALUE=""
EXISTING_ENV_TEAM_HUB_URL_SET="false"
EXISTING_ENV_TEAM_HUB_URL_VALUE=""
EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_SET="false"
EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_VALUE=""
EXISTING_ENV_SERVER_NAME_SET="false"
EXISTING_ENV_SERVER_NAME_VALUE=""
if [[ -f "$ENV_FILE" && ! -L "$ENV_FILE" ]]; then
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_SERVER_NAME; then
    EXISTING_ENV_SERVER_NAME_SET="true"
    EXISTING_ENV_SERVER_NAME_VALUE="$(read_env_value "$ENV_FILE" AGENTSDOCK_SERVER_NAME)"
  fi
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE; then
    EXISTING_ENV_TEAM_HUB_MODE_SET="true"
    EXISTING_ENV_TEAM_HUB_MODE_VALUE="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE)"
  fi
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT; then
    EXISTING_ENV_TEAM_HUB_TRANSPORT_SET="true"
    EXISTING_ENV_TEAM_HUB_TRANSPORT_VALUE="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT)"
  fi
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_URL; then
    EXISTING_ENV_TEAM_HUB_URL_SET="true"
    EXISTING_ENV_TEAM_HUB_URL_VALUE="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_URL)"
  fi
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL; then
    EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_SET="true"
    EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_VALUE="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL)"
  fi
fi

raw_server_name=""
if [[ "$EXISTING_ENV_SERVER_NAME_SET" == "true" ]]; then
  raw_server_name="$EXISTING_ENV_SERVER_NAME_VALUE"
elif env_file_has_key "$LEGACY_ENV_FILE" AGENTSDOCK_SERVER_NAME; then
  raw_server_name="$(read_env_value "$LEGACY_ENV_FILE" AGENTSDOCK_SERVER_NAME)"
elif [[ "${AGENTSDOCK_SERVER_NAME+x}" == "x" ]]; then
  raw_server_name="$AGENTSDOCK_SERVER_NAME"
fi
decoded_server_name="$(decode_server_name_env_value "$raw_server_name")" || {
  echo "AGENTSDOCK_SERVER_NAME has invalid persisted quoting." >&2
  exit 2
}
SERVER_NAME="$(canonical_server_name "$decoded_server_name")" || {
  echo "AGENTSDOCK_SERVER_NAME must be empty or at most 160 UTF-8 bytes and contain no control characters." >&2
  exit 2
}

read_persisted_team_hub_config
EXISTING_TEAM_HUB_MODE="$RESOLVED_TEAM_HUB_MODE"
TEAM_HUB_MODE="${TEAM_HUB_MODE_OVERRIDE:-${EXISTING_TEAM_HUB_MODE:-disabled}}"
if [[ "$TEAM_HUB_MODE" != "host" && "$TEAM_HUB_MODE" != "disabled" ]]; then
  echo "AGENTSDOCK_TEAM_HUB_MODE must be host or disabled." >&2
  exit 2
fi
if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" && "$EXISTING_TEAM_HUB_MODE" != "disabled" ]]; then
  echo "Explicit Team Hub reactivation requires a previously disabled Hub host." >&2
  exit 2
fi
if [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" \
  && "$EXISTING_TEAM_HUB_MODE" != "host" ]]; then
  echo "Failed Team Hub repair requires an existing configured Hub host." >&2
  exit 2
fi
EXISTING_TEAM_HUB_TRANSPORT="$RESOLVED_TEAM_HUB_TRANSPORT"
EXISTING_TEAM_HUB_TRANSPORT_SET="$RESOLVED_TEAM_HUB_TRANSPORT_SET"
EXISTING_TEAM_HUB_URL="$RESOLVED_TEAM_HUB_URL"
EXISTING_TEAM_HUB_DIRECT_IP_URL="$RESOLVED_TEAM_HUB_DIRECT_IP_URL"
PREVIOUS_TEAM_HUB_TRANSPORT="loopback"
PREVIOUS_TEAM_HUB_MODE="${EXISTING_TEAM_HUB_MODE:-disabled}"
if [[ "$EXISTING_TEAM_HUB_TRANSPORT_SET" == "true" ]]; then
  PREVIOUS_TEAM_HUB_TRANSPORT="$EXISTING_TEAM_HUB_TRANSPORT"
fi
PREVIOUS_TEAM_HUB_URL="$EXISTING_TEAM_HUB_URL"
PREVIOUS_TEAM_HUB_DIRECT_IP_URL="$EXISTING_TEAM_HUB_DIRECT_IP_URL"
PRIOR_PORT="$PORT"
PRIOR_BIND_ADDRESS="$BIND_ADDRESS"
if [[ "$TEAM_HUB_MODE" == "disabled" ]]; then
  TEAM_HUB_TRANSPORT="loopback"
  TEAM_HUB_URL=""
else
  if [[ -n "$TEAM_HUB_TRANSPORT_OVERRIDE" ]]; then
    TEAM_HUB_TRANSPORT="$TEAM_HUB_TRANSPORT_OVERRIDE"
  elif [[ "$EXISTING_TEAM_HUB_TRANSPORT_SET" == "true" ]]; then
    TEAM_HUB_TRANSPORT="$EXISTING_TEAM_HUB_TRANSPORT"
  else
    TEAM_HUB_TRANSPORT="loopback"
  fi
  TEAM_HUB_URL="${TEAM_HUB_URL_OVERRIDE:-$EXISTING_TEAM_HUB_URL}"
  TEAM_HUB_DIRECT_IP_URL="${TEAM_HUB_DIRECT_IP_URL_OVERRIDE:-$EXISTING_TEAM_HUB_DIRECT_IP_URL}"
  if [[ -n "$TEAM_HUB_DIRECT_IP_URL_OVERRIDE" && -z "$TEAM_HUB_TRANSPORT_OVERRIDE" ]] && {
    [[ "$EXISTING_TEAM_HUB_TRANSPORT_SET" != "true" ]] \
      || [[ "$EXISTING_TEAM_HUB_MODE" != "host" ]]
  }; then
    TEAM_HUB_TRANSPORT="direct_ip"
    TEAM_HUB_URL="$TEAM_HUB_DIRECT_IP_URL"
  fi
fi
case "$TEAM_HUB_TRANSPORT" in
  loopback)
    if [[ -n "$TEAM_HUB_URL" ]]; then
      echo "Loopback Team Hub transport does not accept an external Hub URL." >&2
      exit 2
    fi
    ;;
  tailscale_serve)
    if [[ "$TEAM_HUB_MODE" != "host" ]]; then
      echo "Tailscale Serve Team Hub transport requires host mode." >&2
      exit 2
    fi
    TEAM_HUB_URL_LOWER="$(printf '%s' "$TEAM_HUB_URL" | tr '[:upper:]' '[:lower:]')"
    if [[ "$TEAM_HUB_URL" != "$TEAM_HUB_URL_LOWER" ]]; then
      echo "Team Hub Tailscale Serve URL must be canonical HTTPS on an explicit *.ts.net port and end in /api/team-hub." >&2
      exit 2
    fi
    if [[ "$TEAM_HUB_URL" =~ ^https://([a-z0-9][a-z0-9.-]*\.ts\.net):([0-9]{1,5})/api/team-hub$ ]]; then
      TEAM_HUB_SERVE_HOST="${BASH_REMATCH[1]}"
      TEAM_HUB_SERVE_PORT="${BASH_REMATCH[2]}"
    else
      echo "Team Hub Tailscale Serve URL must be canonical HTTPS on an explicit *.ts.net port and end in /api/team-hub." >&2
      exit 2
    fi
    if [[ "$TEAM_HUB_SERVE_PORT" == "443" || "$TEAM_HUB_SERVE_PORT" == "8443" || "$TEAM_HUB_SERVE_PORT" == "10000" ]]; then
      echo "Team Hub Tailscale Serve URL is invalid or uses a Funnel-capable port." >&2
      exit 2
    fi
    if [[ "$TEAM_HUB_SERVE_PORT" != "8444" ]]; then
      echo "Team Hub Tailscale Serve URL must use the private beta port 8444." >&2
      exit 2
    fi
    if ! canonical_team_hub_tailnet_hostname "$TEAM_HUB_SERVE_HOST"; then
      echo "Team Hub Tailscale Serve URL has a noncanonical tailnet hostname." >&2
      exit 2
    fi
    ;;
  direct_ip)
    if [[ "$TEAM_HUB_MODE" != "host" || -z "$TEAM_HUB_URL" || "$TEAM_HUB_URL" != "$TEAM_HUB_DIRECT_IP_URL" ]]; then
      echo "Direct-IP Team Hub transport requires the exact configured direct-IP URL in host mode." >&2
      exit 2
    fi
    ;;
  *)
    echo "AGENTSDOCK_TEAM_HUB_TRANSPORT must be loopback, tailscale_serve, or direct_ip." >&2
    exit 2
    ;;
esac
if [[ -n "$TEAM_HUB_DIRECT_IP_URL" ]] && ! canonical_team_hub_direct_ipv4_url "$TEAM_HUB_DIRECT_IP_URL" "$PORT"; then
  echo "Team Hub Direct IP URL must be exact http://<literal-ip>:$PORT/api/team-hub on the AgentsServer port." >&2
  exit 2
fi
if [[ "$EXPECTED_TEAM_HUB_DIRECT_IP_URL_SET" == "true" ]] && [[ "$TEAM_HUB_DIRECT_IP_URL" != "$EXPECTED_TEAM_HUB_DIRECT_IP_URL" ]]; then
  echo "Managed Team Hub Direct IP route changed after update acceptance." >&2
  exit 2
fi
if [[ -n "$EXPECTED_TEAM_HUB_ID" \
  || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]] && {
  [[ "$TEAM_HUB_TRANSPORT" != "$EXPECTED_TEAM_HUB_TRANSPORT" ]] \
    || [[ "$TEAM_HUB_URL" != "$EXPECTED_TEAM_HUB_URL" ]]
}; then
  echo "Managed Team Hub transport or URL changed after update acceptance." >&2
  exit 2
fi
if [[ "$EXISTING_TEAM_HUB_MODE" == "host" && "$TEAM_HUB_MODE" == "host" ]] && {
  [[ "$PREVIOUS_TEAM_HUB_TRANSPORT" != "$TEAM_HUB_TRANSPORT" ]] \
    || [[ "$PREVIOUS_TEAM_HUB_URL" != "$TEAM_HUB_URL" ]]
}; then
  echo "Changing an existing Team Hub origin is not supported by this beta." >&2
  exit 2
fi
if [[ "$EXISTING_TEAM_HUB_MODE" == "host" && "$TEAM_HUB_MODE" == "host" && "$PREVIOUS_TEAM_HUB_DIRECT_IP_URL" != "$TEAM_HUB_DIRECT_IP_URL" ]]; then
  echo "Changing an existing Team Hub Direct IP origin is not supported by this beta." >&2
  exit 2
fi
if [[ -n "$EXPECTED_TEAM_HUB_ID" && "$TEAM_HUB_MODE" != "host" ]]; then
  echo "Managed Team Hub continuity requires AGENTSDOCK_TEAM_HUB_MODE=host." >&2
  exit 2
fi
TEAM_HUB_CANONICAL_DATA_DIR="$STATE_ROOT/team-hub"
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  TEAM_HUB_DATA_DIR="$(normalize_managed_path \
    TEAM_HUB_DATA_DIR "$TEAM_HUB_DATA_DIR")" || exit 2
  TEAM_HUB_SNAPSHOT="$(normalize_managed_path \
    TEAM_HUB_SNAPSHOT "$TEAM_HUB_SNAPSHOT")" || exit 2
  if [[ "$TEAM_HUB_DATA_DIR" != "$TEAM_HUB_CANONICAL_DATA_DIR" ]]; then
    echo "Managed Team Hub data must use the configured AgentsServer state directory." >&2
    exit 2
  fi
fi
if [[ "$TEAM_HUB_MODE" == "host" && "$TEAM_HUB_OPERATION_PENDING" != "true" ]]; then
  TEAM_HUB_EXISTING_STATE="false"
  for candidate in \
    "$TEAM_HUB_CANONICAL_DATA_DIR/team-hub.sqlite3" \
    "$TEAM_HUB_CANONICAL_DATA_DIR/team-hub.sqlite3-wal" \
    "$TEAM_HUB_CANONICAL_DATA_DIR/team-hub.sqlite3-shm" \
    "$TEAM_HUB_CANONICAL_DATA_DIR/access-token-signing.key" \
    "$TEAM_HUB_CANONICAL_DATA_DIR/maintenance-fence.json"; do
    if [[ -e "$candidate" || -L "$candidate" ]]; then
      TEAM_HUB_EXISTING_STATE="true"
      break
    fi
  done
  if [[ "$TEAM_HUB_EXISTING_STATE" != "true" && -d "$TEAM_HUB_CANONICAL_DATA_DIR" ]]; then
    if find "$TEAM_HUB_CANONICAL_DATA_DIR" -maxdepth 1 -type f -name '*.proof' -print -quit | grep -q .; then
      TEAM_HUB_EXISTING_STATE="true"
    fi
  fi
  if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" && "$TEAM_HUB_EXISTING_STATE" != "true" ]]; then
    echo "No preserved Team Hub state is available for explicit reactivation." >&2
    echo "  Use --team-hub-host to create a new Hub host instead." >&2
    exit 1
  fi
  if [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" \
    && "$TEAM_HUB_EXISTING_STATE" != "true" ]]; then
    echo "Failed Team Hub repair requires preserved bound Hub state." >&2
    exit 1
  fi
  if [[ "$TEAM_HUB_EXISTING_STATE" == "true" \
    && "$TEAM_HUB_REACTIVATION_REQUESTED" != "true" \
    && "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" != "true" ]]; then
    echo "Existing Team Hub state requires explicit verified reactivation." >&2
    echo "  Re-run with --reactivate-team-hub-host to verify its managed binding and write a pre-reactivation snapshot." >&2
    exit 1
  fi
fi

RELEASE_FILES=(activation_transaction.py agent_server.py workspace_git.py team_hub_host.py secure_peer_runtime.py team_mail_runtime.py team_mail_websocket.py team_mail_grants.py secure_peer_delivery.py agentsdock_jobs.py agentsdock_chats.py chat_mailbox.py agentsdock_emergency.py agentsdock_publish.py agentsdock_mail.py agentsdock_team.py provider_commands.py claude_sdk_client.py claude_background_reconciliation.py codex_app_server.py codex_auth.py codex_provider.py side_questions.py codex_side_question.py claude_side_question.py cursor_agent_client.py opencode_agent_client.py cursor_process_guard.py claude_history_repair.py claude_history_provenance.py codex_history_repair.py public_chat_shares.py public_chat_transcript.py public_chat_share_routes.py interactive_chat_shares.py interactive_chat_share_routes.py interactive_chat_share_web.py interactive_chat_projection.py interactive_chat_runtime.py interactive_chat_native.py shared_chat_videos.py shared_chat_video_stream.py interactive_chat_controls.py install.sh uninstall.sh instances.sh server_instances.py update_runner.py pyproject.toml uv.lock VERSION release-public-key.pem LICENSE NOTICE)
RELEASE_DIRECTORIES=(agentsdock_team_hub)
TEAM_HUB_RELEASE_FILES=(
  __init__.py
  auth.py
  cli.py
  database.py
  mail_hints.py
  mail_hint_streams.py
  notification_hints.py
  security.py
  secure_peer.py
  secure_peer_hub.py
  service.py
  store.py
  migrations/__init__.py
  migrations/0001_identity_auth.sql
  migrations/0002_teamspace_ledger.sql
  migrations/0003_service_runtime.sql
  migrations/0004_managed_host_binding.sql
  migrations/0005_tailnet_bootstrap_delegations.sql
  migrations/0006_team_network_mailbox.sql
  migrations/0007_local_agent_mail.sql
  migrations/0008_managed_server_session.sql
  migrations/0009_team_messages.sql
  migrations/0010_team_attachment_orphan_reclamation.sql
  migrations/0011_human_admin_paging.sql
  migrations/0012_network_content_deletions.sql
  migrations/0013_team_message_revisions.sql
  migrations/0014_managed_network_owner.sql
  migrations/0015_team_message_inbox_dismissals.sql
  migrations/0016_team_message_all_servers.sql
  migrations/0017_skill_announcement_deletions.sql
  migrations/0018_team_mail_subjects.sql
  migrations/0019_team_mailbox_state.sql
  migrations/0020_team_mail_arrivals.sql
  migrations/0021_team_mail_threads.sql
  migrations/0022_team_bulletin_changes.sql
  migrations/0023_team_message_search.sql
)

for name in "${RELEASE_FILES[@]}"; do
  if [[ ! -f "$SOURCE_DIR/$name" || -L "$SOURCE_DIR/$name" ]]; then
    echo "$name is missing beside install.sh or is not a regular release file." >&2
    exit 1
  fi
done
for name in "${RELEASE_DIRECTORIES[@]}"; do
  if [[ ! -d "$SOURCE_DIR/$name" || -L "$SOURCE_DIR/$name" ]]; then
    echo "$name is missing beside install.sh or is not a real directory." >&2
    exit 1
  fi
  # Local Python runs create bytecode caches. Never copy those (staging uses
  # the explicit manifest below), but still reject links/special files anywhere,
  # including inside a cache directory.
  if find "$SOURCE_DIR/$name" \( -type l -o \( ! -type d ! -type f \) \) -print -quit | grep -q .; then
    echo "$name contains linked or special entries and cannot be installed." >&2
    exit 1
  fi
done
for name in "${TEAM_HUB_RELEASE_FILES[@]}"; do
  if [[ ! -f "$SOURCE_DIR/agentsdock_team_hub/$name" || -L "$SOURCE_DIR/agentsdock_team_hub/$name" ]]; then
    echo "agentsdock_team_hub/$name is missing or is not a regular release file." >&2
    exit 1
  fi
done
TEAM_HUB_RELEASE_FILE_COUNT="$(find "$SOURCE_DIR/agentsdock_team_hub" -type d -name '__pycache__' -prune -o -type f ! -name '*.pyc' ! -name '*.pyo' -print | wc -l)"
TEAM_HUB_RELEASE_FILE_COUNT="${TEAM_HUB_RELEASE_FILE_COUNT//[[:space:]]/}"
if [[ "$TEAM_HUB_RELEASE_FILE_COUNT" != "${#TEAM_HUB_RELEASE_FILES[@]}" ]]; then
  echo "agentsdock_team_hub contains unexpected release files." >&2
  exit 1
fi
TEAM_HUB_RELEASE_DIRECTORY_COUNT="$(find "$SOURCE_DIR/agentsdock_team_hub" -type d -name '__pycache__' -prune -o -type d -print | wc -l)"
TEAM_HUB_RELEASE_DIRECTORY_COUNT="${TEAM_HUB_RELEASE_DIRECTORY_COUNT//[[:space:]]/}"
if [[ "$TEAM_HUB_RELEASE_DIRECTORY_COUNT" != "2" ]]; then
  echo "agentsdock_team_hub contains unexpected release directories." >&2
  exit 1
fi

current_release_binding() {
  if [[ -L "$CURRENT_LINK" ]]; then
    printf 'symlink:%s' "$(readlink "$CURRENT_LINK")"
  elif [[ -d "$CURRENT_LINK" ]]; then
    printf 'directory'
  elif [[ -e "$CURRENT_LINK" ]]; then
    return 1
  else
    printf 'missing'
  fi
}

assert_team_hub_config_unchanged() {
  read_persisted_team_hub_config
  if [[ "$RESOLVED_TEAM_HUB_MODE" != "$EXISTING_TEAM_HUB_MODE" \
    || "$RESOLVED_TEAM_HUB_TRANSPORT_SET" != "$EXISTING_TEAM_HUB_TRANSPORT_SET" \
    || "$RESOLVED_TEAM_HUB_TRANSPORT" != "$EXISTING_TEAM_HUB_TRANSPORT" \
    || "$RESOLVED_TEAM_HUB_URL" != "$EXISTING_TEAM_HUB_URL" \
    || "$RESOLVED_TEAM_HUB_DIRECT_IP_URL" != "$EXISTING_TEAM_HUB_DIRECT_IP_URL" ]]; then
    echo "Team Hub configuration changed while the installer was preparing." >&2
    return 1
  fi
}

validate_managed_team_hub_inputs() {
  local runtime_root="$1"
  local current_binding=""
  local expected_current_binding=""
  local candidate=""
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]] || return 0
  expected_current_binding="$INITIAL_CURRENT_LINK_BINDING"
  assert_team_hub_config_unchanged || return
  current_binding="$(current_release_binding)" || {
    echo "The current release changed to an unsafe path while the installer was preparing." >&2
    return 1
  }
  if [[ "$RELEASE_ACTIVATED" == "true" ]]; then
    expected_current_binding="symlink:$RELEASE_DIR"
  fi
  if [[ "$current_binding" != "$expected_current_binding" ]]; then
    echo "The current release changed while the installer was preparing." >&2
    return 1
  fi
  if [[ ! -d "$TEAM_HUB_DATA_DIR" || -L "$TEAM_HUB_DATA_DIR" || ! -d "$TEAM_HUB_SNAPSHOT" || -L "$TEAM_HUB_SNAPSHOT" ]]; then
    echo "Managed Team Hub data or snapshot directory changed or became unsafe." >&2
    return 1
  fi
  for candidate in manifest.json team-hub.sqlite3 access-token-signing.key; do
    if [[ ! -f "$TEAM_HUB_SNAPSHOT/$candidate" || -L "$TEAM_HUB_SNAPSHOT/$candidate" ]]; then
      echo "Managed Team Hub snapshot changed or has an unsafe $candidate file." >&2
      return 1
    fi
  done
  if ! verify_team_hub_operation_fence "$runtime_root"; then
    echo "Managed Team Hub installer no longer owns the exact live maintenance fence." >&2
    return 1
  fi
  if ! verify_team_hub_rollback_snapshot "$runtime_root"; then
    echo "Managed Team Hub rollback snapshot no longer passes full read-only verification." >&2
    return 1
  fi
}

validate_team_hub_reactivation_inputs() {
  local runtime_root="$1"
  local current_binding=""
  local expected_current_binding=""
  local candidate=""
  [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]] || return 0
  expected_current_binding="$INITIAL_CURRENT_LINK_BINDING"
  assert_team_hub_config_unchanged || return
  current_binding="$(current_release_binding)" || {
    echo "The current release changed to an unsafe path while Team Hub reactivation was preparing." >&2
    return 1
  }
  if [[ "$RELEASE_ACTIVATED" == "true" ]]; then
    expected_current_binding="symlink:$RELEASE_DIR"
  fi
  if [[ "$current_binding" != "$expected_current_binding" ]]; then
    echo "The current release changed while Team Hub reactivation was preparing." >&2
    return 1
  fi
  if [[ ! -d "$TEAM_HUB_CANONICAL_DATA_DIR" \
    || -L "$TEAM_HUB_CANONICAL_DATA_DIR" \
    || ! -d "$TEAM_HUB_REACTIVATION_SNAPSHOT" \
    || -L "$TEAM_HUB_REACTIVATION_SNAPSHOT" ]]; then
    echo "Team Hub reactivation data or snapshot changed or became unsafe." >&2
    return 1
  fi
  for candidate in manifest.json team-hub.sqlite3 access-token-signing.key; do
    if [[ ! -f "$TEAM_HUB_REACTIVATION_SNAPSHOT/$candidate" \
      || -L "$TEAM_HUB_REACTIVATION_SNAPSHOT/$candidate" ]]; then
      echo "Team Hub reactivation snapshot changed or has an unsafe $candidate file." >&2
      return 1
    fi
  done
  if ! verify_team_hub_reactivation_snapshot "$runtime_root"; then
    echo "Team Hub reactivation snapshot no longer passes exact read-only verification." >&2
    return 1
  fi
  if ! run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
    verify-server-identity \
    --server-state-dir "$STATE_ROOT" \
    --expected-identity "$EXPECTED_SERVER_IDENTITY" >/dev/null; then
    echo "AgentsServer identity changed while Team Hub reactivation was preparing." >&2
    return 1
  fi
}

if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  INITIAL_CURRENT_LINK_BINDING="$(current_release_binding)" || {
    echo "Managed Team Hub update requires a safe current release path." >&2
    exit 1
  }
  TEAM_HUB_SNAPSHOT_PARENT="${TEAM_HUB_SNAPSHOT%/*}"
  TEAM_HUB_SNAPSHOT_NAME="${TEAM_HUB_SNAPSHOT##*/}"
  if [[ "$TEAM_HUB_SNAPSHOT_PARENT" != "$TEAM_HUB_DATA_DIR/maintenance-backups" || ! "$TEAM_HUB_SNAPSHOT_NAME" =~ ^snapshot_[A-Za-z0-9_]+$ ]]; then
    echo "Managed Team Hub snapshot is not an exact maintenance generation." >&2
    exit 2
  fi
  if [[ ! -d "$TEAM_HUB_DATA_DIR" || -L "$TEAM_HUB_DATA_DIR" || ! -d "$TEAM_HUB_SNAPSHOT" || -L "$TEAM_HUB_SNAPSHOT" ]]; then
    echo "Managed Team Hub data or snapshot directory is unavailable or unsafe." >&2
    exit 1
  fi
  for candidate in manifest.json team-hub.sqlite3 access-token-signing.key; do
    if [[ ! -f "$TEAM_HUB_SNAPSHOT/$candidate" || -L "$TEAM_HUB_SNAPSHOT/$candidate" ]]; then
      echo "Managed Team Hub snapshot is missing a safe $candidate file." >&2
      exit 1
    fi
  done
  if ! verify_team_hub_operation_fence "$CURRENT_LINK"; then
    echo "Managed Team Hub installer takeover does not own the exact live maintenance fence." >&2
    exit 1
  fi
  if ! verify_team_hub_rollback_snapshot "$CURRENT_LINK"; then
    echo "Managed Team Hub rollback snapshot failed full read-only verification before candidate activation." >&2
    exit 1
  fi
elif [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
  || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
  INITIAL_CURRENT_LINK_BINDING="$(current_release_binding)" || {
    echo "Team Hub reactivation requires a safe current release path." >&2
    exit 1
  }
fi

PREFLIGHT_FAILED="false"
MISSING_PREREQUISITE_NAMES=()
MISSING_PREREQUISITE_GUIDANCE=()
record_prerequisite_failure() {
  local prerequisite_name="$1"
  local guidance="$2"
  PREFLIGHT_FAILED="true"
  MISSING_PREREQUISITE_NAMES+=("$prerequisite_name")
  MISSING_PREREQUISITE_GUIDANCE+=("$guidance")
  echo "Unavailable prerequisite: $prerequisite_name" >&2
  echo "  $guidance" >&2
}

require_command() {
  local command_name="$1"
  local guidance="$2"
  command -v "$command_name" >/dev/null 2>&1 || record_prerequisite_failure "$command_name" "$guidance"
}

require_uv_runtime() {
  local guidance="$1"
  if command -v uv >/dev/null 2>&1 && uv --version >/dev/null 2>&1; then
    return 0
  fi
  record_prerequisite_failure "uv" "$guidance"
}

probe_service_manager() {
  local output=""
  if [[ "$OS_NAME" == "Darwin" ]] && command -v launchctl >/dev/null 2>&1; then
    if ! output="$(launchctl print "gui/$UID" 2>&1)"; then
      [[ -z "$output" ]] || echo "  launchctl: ${output//$'\n'/ }" >&2
      record_prerequisite_failure \
        "macOS launchd user domain gui/$UID" \
        "Log into a macOS GUI user session and verify: launchctl print gui/$UID"
    fi
  elif [[ "$OS_NAME" == "Linux" ]] && command -v systemctl >/dev/null 2>&1; then
    if ! output="$(systemctl --user show-environment 2>&1)"; then
      [[ -z "$output" ]] || echo "  systemctl: ${output//$'\n'/ }" >&2
      record_prerequisite_failure \
        "systemctl --user session" \
        "Log into a systemd user session and verify: systemctl --user show-environment"
    fi
  fi
}

cgroup_path_is_within() {
  local path="/${1#/}"
  local ancestor="/${2#/}"
  [[ "$path" == "$ancestor" || "$path" == "$ancestor/"* ]]
}

verify_managed_update_runner_isolated() {
  [[ -n "$MANAGED_UPDATE_ID" && "$OS_NAME" == "Linux" ]] || return 0
  if [[ -z "$EXPECTED_SERVICE_CGROUP" ]]; then
    record_prerequisite_failure \
      "managed updater service-cgroup proof" \
      "Retry from AgentsDock; the authenticated updater did not bind this install to the exact AgentsServer service cgroup."
    return
  fi
  if [[ ! -r /proc/self/cgroup ]]; then
    record_prerequisite_failure \
      "managed updater service-cgroup proof" \
      "Retry after checking the host's /proc and systemd user session."
    return
  fi
  local hierarchy=""
  local controllers=""
  local path=""
  local inspected="false"
  while IFS=: read -r hierarchy controllers path; do
    [[ -n "$path" ]] || continue
    inspected="true"
    if cgroup_path_is_within "$path" "$EXPECTED_SERVICE_CGROUP"; then
      record_prerequisite_failure \
        "managed updater isolation" \
        "Retry after AgentsServer creates its detached updater outside agents-server.service."
      return
    fi
  done < /proc/self/cgroup
  if [[ "$inspected" != "true" ]]; then
    record_prerequisite_failure \
      "managed updater service-cgroup proof" \
      "Retry after checking the host's /proc and systemd user session."
  fi
}

TMUX_WARNING=""

tmux_working() {
  command -v tmux >/dev/null 2>&1 && tmux -V >/dev/null 2>&1
}

offer_brew_tmux_install() {
  # Only ever offered on macOS with Homebrew present; never attempted over a
  # non-interactive/SSH-driven run, where there is no one to answer a prompt.
  [[ "$NON_INTERACTIVE" != "true" && -t 0 ]] || return 1
  command -v brew >/dev/null 2>&1 || return 1
  local reply=""
  read -r -p "      tmux was not found. Install it now with Homebrew (brew install tmux)? [y/N] " reply || return 1
  case "$reply" in
    y|Y|yes|YES) ;;
    *) return 1 ;;
  esac
  echo "      Installing tmux with Homebrew"
  brew install tmux
}

check_tmux_prerequisite() {
  # tmux is optional: it only backs the persistent chat terminal, tmux-pane
  # inspection, and in-app managed updates. The rest of AgentsServer (chats,
  # turns, jobs, files) runs without it, so a missing tmux is a warning, not
  # a preflight failure.
  local guidance=""
  tmux_working && return 0
  if [[ "$OS_NAME" == "Darwin" ]]; then
    if offer_brew_tmux_install && tmux_working; then
      return 0
    fi
    guidance="Install tmux with Homebrew: brew install tmux"
  else
    guidance="Install tmux with your package manager, for example: sudo apt install tmux, sudo dnf install tmux, or sudo pacman -S tmux."
  fi
  TMUX_WARNING="tmux is unavailable, so the persistent chat terminal, tmux-pane inspection, and in-app managed updates will not work. $guidance Then rerun install.sh to enable them; everything else about AgentsServer works without it."
  echo "Optional prerequisite unavailable: tmux" >&2
  echo "  $TMUX_WARNING" >&2
}

check_darwin_architecture() {
  local architecture=""
  architecture="$(uname -m 2>/dev/null || true)"
  if [[ "$architecture" == "arm64" ]]; then
    return 0
  fi
  echo "Unsupported macOS architecture: ${architecture:-unknown}." >&2
  echo "AgentsServer requires a native Apple silicon (arm64) macOS environment because patched cryptography releases no longer support Intel macOS. Use Apple silicon or Linux; no state, release, configuration, or service changes were made." >&2
  return 1
}

preflight_prerequisites() {
  case "$OS_NAME" in
    Darwin)
      check_darwin_architecture || return 1
      require_uv_runtime "Install the trusted uv package manager before running this installer: brew install uv."
      require_command "launchctl" "launchctl is included with macOS; run this installer from a supported macOS user session."
      ;;
    Linux)
      require_uv_runtime "Install the trusted uv package manager from your OS/package-management environment, then rerun install.sh."
      require_command "systemctl" "AgentsServer's Linux installer requires systemd and a working systemctl --user session."
      ;;
    *)
      echo "Unsupported host OS: $OS_NAME" >&2
      PREFLIGHT_FAILED="true"
      ;;
  esac
  case "$OS_NAME" in
    Darwin|Linux) check_tmux_prerequisite ;;
  esac
  probe_service_manager
  verify_managed_update_runner_isolated
  if [[ "$PREFLIGHT_FAILED" == "true" ]]; then
    local names=""
    local actions=""
    local index
    for ((index = 0; index < ${#MISSING_PREREQUISITE_NAMES[@]}; index++)); do
      [[ -z "$names" ]] || names+=", "
      names+="${MISSING_PREREQUISITE_NAMES[$index]}"
      [[ -z "$actions" ]] || actions+=" "
      actions+="${MISSING_PREREQUISITE_GUIDANCE[$index]}"
    done
    if [[ -n "$names" ]]; then
      echo "Missing prerequisites: $names. $actions Then run install.sh again; no state, release, configuration, or service changes were made." >&2
    else
      echo "Prerequisite check failed for unsupported host OS $OS_NAME; no state, release, configuration, or service changes were made." >&2
    fi
    return 1
  fi
}

# This deliberately runs before the cleanup trap, directory creation, state
# migration, release staging, or service changes.
preflight_prerequisites || exit 1
UV_BIN="$(command -v uv)" || exit 1
[[ "$UV_BIN" == /* && -x "$UV_BIN" ]] || {
  echo "The trusted uv executable must resolve to an absolute executable path." >&2
  exit 1
}

ACTIVE_STAGE_PID=""
ACTIVE_STAGE_PGID=""
INSTALL_LOCK_DIR="$INSTALL_ROOT/.install-lock"
INSTALL_LOCK_HELD="false"
INSTALL_LOCK_DEVICE=""
INSTALL_LOCK_INODE=""
PREVIOUS_LINK_WAS_SYMLINK="false"
PREVIOUS_LINK_TARGET=""
PREVIOUS_LINK_STATE_CAPTURED="false"
CURRENT_LINK_STATE_CAPTURED="false"
CURRENT_LINK_WAS_SYMLINK="false"
CURRENT_LINK_WAS_DIRECTORY="false"
CURRENT_LINK_TARGET=""

validate_install_layout_paths() {
  local candidate=""
  local candidate_mode=""
  for candidate in "$INSTALL_ROOT" "$RELEASES_ROOT"; do
    if [[ -L "$candidate" \
      || ( -e "$candidate" && ! -d "$candidate" ) \
      || ( -d "$candidate" && ! -O "$candidate" ) ]]; then
      echo "The AgentsServer install layout contains an unsafe directory: $candidate" >&2
      return 1
    fi
    [[ -d "$candidate" ]] || continue
    candidate_mode="$(stat -c '%a' "$candidate" 2>/dev/null \
      || stat -f '%Lp' "$candidate" 2>/dev/null)" || return 1
    if [[ ! "$candidate_mode" =~ ^[0-7]{3,4}$ \
      || $((8#$candidate_mode & 8#022)) -ne 0 ]]; then
      echo "The AgentsServer install layout is group/world writable: $candidate" >&2
      return 1
    fi
  done
}

systemd_unit_snapshot() {
  local unit="$1"
  local config_exists="$2"
  local load_state=""
  local active_state=""
  local enabled_state=""
  local enabled_status=0
  load_state="$(systemctl --user show "$unit" \
    --property=LoadState --value 2>/dev/null)" || return 1
  active_state="$(systemctl --user show "$unit" \
    --property=ActiveState --value 2>/dev/null)" || return 1
  [[ "$load_state" != *$'\n'* && "$active_state" != *$'\n'* ]] || return 1
  case "$load_state" in
    loaded|not-found) ;;
    *) return 1 ;;
  esac
  case "$active_state" in
    active) active_state="running" ;;
    inactive|failed) active_state="stopped" ;;
    *) return 1 ;;
  esac
  if enabled_state="$(systemctl --user is-enabled "$unit" 2>/dev/null)"; then
    enabled_status=0
  else
    enabled_status=$?
  fi
  [[ "$enabled_state" != *$'\n'* ]] || return 1
  case "$enabled_status:$enabled_state" in
    0:enabled|0:enabled-runtime) enabled_state="true" ;;
    1:disabled) enabled_state="false" ;;
    1:not-found|4:not-found)
      [[ "$load_state" == "not-found" && "$config_exists" != "true" ]] \
        || return 1
      enabled_state="false"
      ;;
    *) return 1 ;;
  esac
  if [[ "$config_exists" != "true" && ( \
      "$load_state" != "not-found" \
      || "$active_state" != "stopped" \
      || "$enabled_state" != "false" ) ]]; then
    return 1
  fi
  if [[ "$config_exists" != "true" ]]; then
    active_state="absent"
  fi
  printf '%s|%s|%s\n' "$active_state" "$enabled_state" "$load_state"
}

backup_runtime_configuration() {
  local activation_intent="ordinary"
  if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
    activation_intent="server-update"
  elif [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
    activation_intent="failed-host-repair"
  elif [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" ]]; then
    activation_intent="host-reactivation"
  fi
  ACTIVATION_INTENT="$activation_intent"
  local captured_value=""
  local prior_network_config=""
  if [[ -f "$ENV_FILE" && ! -L "$ENV_FILE" ]]; then
    prior_network_config="$ENV_FILE"
  elif [[ -n "$LEGACY_ENV_FILE" \
    && -f "$LEGACY_ENV_FILE" \
    && ! -L "$LEGACY_ENV_FILE" ]]; then
    prior_network_config="$LEGACY_ENV_FILE"
  fi
  if [[ -n "$prior_network_config" ]]; then
    captured_value="$(read_env_value \
      "$prior_network_config" AGENTSDOCK_AGENT_PORT)" || return 1
    [[ -n "$captured_value" ]] || captured_value="$(read_env_value \
      "$prior_network_config" ZENITHBOT_AGENT_PORT)" || return 1
    [[ -n "$captured_value" ]] || captured_value="$(read_env_value \
      "$prior_network_config" ZENITHDOCK_AGENT_PORT)" || return 1
    if [[ -n "$captured_value" ]]; then
      [[ "$captured_value" =~ ^[0-9]+$ \
        && "$captured_value" -ge 1 \
        && "$captured_value" -le 65535 ]] || return 1
      PRIOR_PORT="$captured_value"
    fi
    captured_value="$(read_env_value \
      "$prior_network_config" AGENTSDOCK_AGENT_BIND)" || return 1
    [[ -n "$captured_value" ]] || captured_value="$(read_env_value \
      "$prior_network_config" ZENITHBOT_AGENT_BIND)" || return 1
    [[ -n "$captured_value" ]] || captured_value="$(read_env_value \
      "$prior_network_config" ZENITHDOCK_AGENT_BIND)" || return 1
    if [[ -n "$captured_value" ]]; then
      validate_bind_address "$captured_value" "$STAGE_DIR/.venv/bin/python" \
        || return 1
      PRIOR_BIND_ADDRESS="$captured_value"
    fi
  fi
  if [[ -f "$ENV_FILE" && ! -L "$ENV_FILE" ]]; then
    ENV_CONFIG_EXISTED="true"
  elif [[ -e "$ENV_FILE" || -L "$ENV_FILE" ]]; then
    echo "$ENV_FILE is not a regular configuration file." >&2
    return 1
  fi
  ENV_CONFIG_CAPTURED="true"

  local service_file="$SYSTEMD_SERVICE_FILE"
  [[ "$OS_NAME" != "Darwin" ]] || service_file="$PLIST"
  if [[ -f "$service_file" && ! -L "$service_file" ]]; then
    SERVICE_CONFIG_EXISTED="true"
  elif [[ -e "$service_file" || -L "$service_file" ]]; then
    echo "$service_file is not a regular service configuration file." >&2
    return 1
  fi
  SERVICE_CONFIG_CAPTURED="true"
  if [[ "$OS_NAME" == "Darwin" ]]; then
    local launchd_state=""
    launchd_state="$(launchd_target_snapshot "gui/$(id -u)/$LABEL")" \
      || return 1
    if [[ "$SERVICE_CONFIG_EXISTED" != "true" ]]; then
      [[ "$launchd_state" == "not-found" ]] || {
        echo "The loaded AgentsServer service has no safely restorable plist." >&2
        return 1
      }
      PRIOR_SERVICE_STATE="absent"
    elif [[ "$launchd_state" == "loaded" ]]; then
      PRIOR_SERVICE_STATE="running"
    elif [[ "$launchd_state" == "not-found" ]]; then
      PRIOR_SERVICE_STATE="stopped"
    else
      return 1
    fi
    local disabled_services=""
    disabled_services="$(launchctl print-disabled "gui/$(id -u)" 2>/dev/null)" \
      || return 1
    if printf '%s\n' "$disabled_services" \
      | grep -Eq "\"$LABEL\"[[:space:]]*=>[[:space:]]*true"; then
      PRIOR_SERVICE_ENABLED="false"
    else
      PRIOR_SERVICE_ENABLED="true"
    fi
  else
    local current_snapshot=""
    current_snapshot="$(systemd_unit_snapshot \
      "$SERVICE_NAME.service" "$SERVICE_CONFIG_EXISTED")" || {
      echo "The current AgentsServer service state could not be captured authoritatively." >&2
      return 1
    }
    PRIOR_SERVICE_STATE="${current_snapshot%%|*}"
    current_snapshot="${current_snapshot#*|}"
    PRIOR_SERVICE_ENABLED="${current_snapshot%%|*}"
  fi
  if [[ "$OS_NAME" == "Linux" && "${INSTANCE_NAME:-default}" == "default" ]]; then
    local legacy_exists="false"
    local legacy_snapshot=""
    if [[ -e "$LEGACY_SERVICE_FILE" || -L "$LEGACY_SERVICE_FILE" ]]; then
      if ! read_owned_config_file "$LEGACY_SERVICE_FILE" >/dev/null; then
        echo "$LEGACY_SERVICE_FILE cannot be captured safely for rollback." >&2
        return 1
      fi
      legacy_exists="true"
    fi
    legacy_snapshot="$(systemd_unit_snapshot \
      "$LEGACY_SERVICE_NAME.service" "$legacy_exists")" || {
      echo "The legacy service state could not be captured authoritatively." >&2
      return 1
    }
    PRIOR_LEGACY_SERVICE_STATE="${legacy_snapshot%%|*}"
    legacy_snapshot="${legacy_snapshot#*|}"
    PRIOR_LEGACY_SERVICE_ENABLED="${legacy_snapshot%%|*}"
    if [[ "$legacy_exists" != "true" \
      && "$PRIOR_LEGACY_SERVICE_STATE" != "absent" ]]; then
      echo "The loaded legacy service has no safely restorable unit file." >&2
      return 1
    fi
  fi

  if [[ -L "$CURRENT_LINK" ]]; then
    CURRENT_LINK_WAS_SYMLINK="true"
    CURRENT_LINK_TARGET="$(readlink "$CURRENT_LINK")"
  elif [[ -d "$CURRENT_LINK" ]]; then
    CURRENT_LINK_WAS_DIRECTORY="true"
  elif [[ -e "$CURRENT_LINK" ]]; then
    echo "$CURRENT_LINK is not a supported release link or directory." >&2
    return 1
  fi
  CURRENT_LINK_STATE_CAPTURED="true"

  if [[ -L "$PREVIOUS_LINK" ]]; then
    PREVIOUS_LINK_WAS_SYMLINK="true"
    PREVIOUS_LINK_TARGET="$(readlink "$PREVIOUS_LINK")"
  elif [[ -e "$PREVIOUS_LINK" ]]; then
    echo "$PREVIOUS_LINK is not a symbolic link." >&2
    return 1
  fi
  PREVIOUS_LINK_STATE_CAPTURED="true"

  ACTIVATION_TRANSACTION_ID="$(
    run_without_server_secrets env PYTHONPATH="$STAGE_DIR" \
      "$STAGE_DIR/.venv/bin/python" -m activation_transaction begin \
      --root "$INSTALL_ROOT" \
      --current "$CURRENT_LINK" \
      --previous "$PREVIOUS_LINK" \
      --env "$ENV_FILE" \
      --service "$service_file" \
      --release-dir "$RELEASE_DIR" \
      --release-version "$RELEASE_VERSION" \
      --old-source "$ORIGINAL_OLD_SOURCE" \
      --old-target "$OLD_TARGET" \
      --candidate-source "$STAGE_DIR" \
      --service-state "$PRIOR_SERVICE_STATE" \
      --service-enabled "$PRIOR_SERVICE_ENABLED" \
      --legacy-service-state "$PRIOR_LEGACY_SERVICE_STATE" \
      --legacy-service-enabled "$PRIOR_LEGACY_SERVICE_ENABLED" \
      --prior-port "$PRIOR_PORT" \
      --prior-bind-address "$PRIOR_BIND_ADDRESS" \
      --intent "$activation_intent" \
      --client-binding "$EXPECTED_TEAM_HUB_CLIENT_BINDING"
  )" || return
  if [[ ! "$ACTIVATION_TRANSACTION_ID" =~ ^activation-[0-9a-f]{24}$ \
    || "$ACTIVATION_TRANSACTION_ID" == *$'\n'* ]]; then
    echo "Activation transaction returned an invalid identity." >&2
    return 1
  fi
  ACTIVATION_TRANSACTION_PHASE="prepared"
  ACTIVATION_ROLLBACK_FROM=""
  ENV_CONFIG_BACKUP="$ACTIVATION_TRANSACTION_DIR/env.backup"
  SERVICE_CONFIG_BACKUP="$ACTIVATION_TRANSACTION_DIR/service.backup"
}

activation_service_config_path() {
  if [[ "$OS_NAME" == "Darwin" ]]; then
    printf '%s\n' "$PLIST"
  else
    printf '%s\n' "$SYSTEMD_SERVICE_FILE"
  fi
}

activation_transaction_command() {
  local preferred_root="$1"
  shift
  local runtime_root=""
  local candidate=""
  for candidate in \
    "$ACTIVATION_TRANSACTION_DIR/candidate.retired" \
    "$preferred_root" \
    "$STAGE_DIR" \
    "$RELEASE_DIR" \
    "$SOURCE_DIR"; do
    [[ -n "$candidate" ]] || continue
    if [[ -f "$candidate/activation_transaction.py" \
      && -x "$candidate/.venv/bin/python" ]]; then
      runtime_root="$candidate"
      break
    fi
  done
  [[ -n "$runtime_root" ]] || return 1
  run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m activation_transaction "$@"
}

record_activation_phase() {
  local phase="$1"
  local runtime_root="${2:-$CANDIDATE_RUNTIME_ROOT}"
  local previous_phase="$ACTIVATION_TRANSACTION_PHASE"
  [[ -n "$ACTIVATION_TRANSACTION_ID" ]] || return 0
  local service_file=""
  local hub_kind=""
  local hub_data_dir=""
  local hub_id=""
  local operation_id=""
  local snapshot=""
  local fence_device="0"
  local fence_inode="0"
  local result=""
  service_file="$(activation_service_config_path)"
  if [[ "$phase" != "rolled-back" && "$phase" != "rollback-healthy" \
    && "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
    hub_kind="host-reactivation"
    hub_data_dir="$TEAM_HUB_CANONICAL_DATA_DIR"
    hub_id="$TEAM_HUB_REACTIVATION_HUB_ID"
    operation_id="$TEAM_HUB_REACTIVATION_OPERATION_ID"
    snapshot="$TEAM_HUB_REACTIVATION_SNAPSHOT"
    fence_device="$TEAM_HUB_REACTIVATION_FENCE_DEVICE"
    fence_inode="$TEAM_HUB_REACTIVATION_FENCE_INODE"
  elif [[ "$phase" != "rolled-back" && "$phase" != "rollback-healthy" \
    && "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
    hub_kind="server-update"
    hub_data_dir="$TEAM_HUB_DATA_DIR"
    hub_id="$EXPECTED_TEAM_HUB_ID"
    operation_id="$TEAM_HUB_OPERATION_ID"
    snapshot="$TEAM_HUB_SNAPSHOT"
    fence_device="${TEAM_HUB_OPERATION_FENCE_DEVICE:-0}"
    fence_inode="${TEAM_HUB_OPERATION_FENCE_INODE:-0}"
  fi
  local arguments=(
    record
    --root "$INSTALL_ROOT"
    --current "$CURRENT_LINK"
    --previous "$PREVIOUS_LINK"
    --env "$ENV_FILE"
    --service "$service_file"
    --release-dir "$RELEASE_DIR"
    --release-version "$RELEASE_VERSION"
    --transaction-id "$ACTIVATION_TRANSACTION_ID"
    --phase "$phase"
    --authority-pending "$TEAM_HUB_STARTUP_AUTHORITY_PENDING"
  )
  if [[ -n "$hub_kind" ]]; then
    ACTIVATION_HUB_KIND="$hub_kind"
    arguments+=(
      --hub-kind "$hub_kind"
      --hub-data-dir "$hub_data_dir"
      --hub-id "$hub_id"
      --host-identity "$EXPECTED_SERVER_IDENTITY"
      --operation-id "$operation_id"
      --snapshot "$snapshot"
      --fence-device "$fence_device"
      --fence-inode "$fence_inode"
    )
  fi
  if [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]]; then
    arguments+=(
      --guard-id "$TEAM_HUB_COLD_GUARD_ID"
      --guard-device "$TEAM_HUB_COLD_GUARD_DEVICE"
      --guard-inode "$TEAM_HUB_COLD_GUARD_INODE"
    )
  fi
  result="$(activation_transaction_command "$runtime_root" "${arguments[@]}")" \
    || return 1
  if [[ -n "$hub_kind" ]]; then
    local returned_device="${result%%$'\n'*}"
    local returned_inode="${result#*$'\n'}"
    if [[ "$result" != *$'\n'* \
      || ! "$returned_device" =~ ^[1-9][0-9]*$ \
      || ! "$returned_inode" =~ ^[1-9][0-9]*$ \
      || "$returned_inode" == *$'\n'* ]]; then
      echo "Activation transaction returned invalid Team Hub fence ownership." >&2
      return 1
    fi
    if [[ "$hub_kind" == "server-update" ]]; then
      TEAM_HUB_OPERATION_FENCE_DEVICE="$returned_device"
      TEAM_HUB_OPERATION_FENCE_INODE="$returned_inode"
    else
      TEAM_HUB_REACTIVATION_FENCE_DEVICE="$returned_device"
      TEAM_HUB_REACTIVATION_FENCE_INODE="$returned_inode"
    fi
  elif [[ -n "$result" ]]; then
    echo "Activation transaction returned unexpected output." >&2
    return 1
  fi
  ACTIVATION_TRANSACTION_PHASE="$phase"
  if [[ "$phase" == "rolling-back" && -z "$ACTIVATION_ROLLBACK_FROM" ]]; then
    ACTIVATION_ROLLBACK_FROM="$previous_phase"
  fi
}

replace_activation_config() {
  local kind="$1"
  local source="$2"
  local mode="$3"
  local runtime_root="${4:-$CANDIDATE_RUNTIME_ROOT}"
  [[ -n "$ACTIVATION_TRANSACTION_ID" ]] || return 1
  activation_transaction_command "$runtime_root" replace-config \
    --root "$INSTALL_ROOT" \
    --current "$CURRENT_LINK" \
    --previous "$PREVIOUS_LINK" \
    --env "$ENV_FILE" \
    --service "$(activation_service_config_path)" \
    --release-dir "$RELEASE_DIR" \
    --release-version "$RELEASE_VERSION" \
    --transaction-id "$ACTIVATION_TRANSACTION_ID" \
    --kind "$kind" \
    --source "$source" \
    --mode "$mode" >/dev/null
}

restore_activation_files() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  activation_transaction_command "$runtime_root" restore-files \
    --root "$INSTALL_ROOT" \
    --current "$CURRENT_LINK" \
    --previous "$PREVIOUS_LINK" \
    --env "$ENV_FILE" \
    --service "$(activation_service_config_path)" \
    --release-dir "$RELEASE_DIR" \
    --release-version "$RELEASE_VERSION" \
    --transaction-id "$ACTIVATION_TRANSACTION_ID" >/dev/null
}

activate_transaction_files() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  activation_transaction_command "$runtime_root" activate-files \
    --root "$INSTALL_ROOT" \
    --current "$CURRENT_LINK" \
    --previous "$PREVIOUS_LINK" \
    --env "$ENV_FILE" \
    --service "$(activation_service_config_path)" \
    --release-dir "$RELEASE_DIR" \
    --release-version "$RELEASE_VERSION" \
    --transaction-id "$ACTIVATION_TRANSACTION_ID" >/dev/null
}

finish_activation_transaction() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  [[ -n "$ACTIVATION_TRANSACTION_ID" ]] || return 0
  if activation_transaction_command "$runtime_root" finish \
      --root "$INSTALL_ROOT" \
      --current "$CURRENT_LINK" \
      --previous "$PREVIOUS_LINK" \
      --env "$ENV_FILE" \
      --service "$(activation_service_config_path)" \
      --release-dir "$RELEASE_DIR" \
      --release-version "$RELEASE_VERSION" \
      --transaction-id "$ACTIVATION_TRANSACTION_ID" >/dev/null; then
    ACTIVATION_TRANSACTION_ID=""
    ACTIVATION_TRANSACTION_PHASE=""
    ACTIVATION_ROLLBACK_FROM=""
    ACTIVATION_HUB_KIND=""
    return 0
  fi
  return 1
}

assert_env_backup_team_hub_config() {
  [[ "$ENV_CONFIG_EXISTED" == "true" ]] || return 0
  [[ -n "$ENV_CONFIG_BACKUP" && -f "$ENV_CONFIG_BACKUP" ]] || return 1
  local mismatch="false"
  local actual_set="false"
  actual_set="false"
  env_file_has_key "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_MODE && actual_set="true"
  if [[ "$actual_set" != "$EXISTING_ENV_TEAM_HUB_MODE_SET" ]] \
    || { [[ "$actual_set" == "true" ]] \
      && [[ "$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_MODE)" != "$EXISTING_ENV_TEAM_HUB_MODE_VALUE" ]]; }; then
    mismatch="true"
  fi
  actual_set="false"
  env_file_has_key "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_TRANSPORT && actual_set="true"
  if [[ "$actual_set" != "$EXISTING_ENV_TEAM_HUB_TRANSPORT_SET" ]] \
    || { [[ "$actual_set" == "true" ]] \
      && [[ "$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_TRANSPORT)" != "$EXISTING_ENV_TEAM_HUB_TRANSPORT_VALUE" ]]; }; then
    mismatch="true"
  fi
  actual_set="false"
  env_file_has_key "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_URL && actual_set="true"
  if [[ "$actual_set" != "$EXISTING_ENV_TEAM_HUB_URL_SET" ]] \
    || { [[ "$actual_set" == "true" ]] \
      && [[ "$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_URL)" != "$EXISTING_ENV_TEAM_HUB_URL_VALUE" ]]; }; then
    mismatch="true"
  fi
  actual_set="false"
  env_file_has_key "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL && actual_set="true"
  if [[ "$actual_set" != "$EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_SET" ]] \
    || { [[ "$actual_set" == "true" ]] \
      && [[ "$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL)" != "$EXISTING_ENV_TEAM_HUB_DIRECT_IP_URL_VALUE" ]]; }; then
    mismatch="true"
  fi
  actual_set="false"
  env_file_has_key "$ENV_CONFIG_BACKUP" AGENTSDOCK_SERVER_NAME && actual_set="true"
  if [[ "$actual_set" != "$EXISTING_ENV_SERVER_NAME_SET" ]] \
    || { [[ "$actual_set" == "true" ]] \
      && [[ "$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_SERVER_NAME)" != "$EXISTING_ENV_SERVER_NAME_VALUE" ]]; }; then
    mismatch="true"
  fi
  if [[ "$mismatch" == "true" ]]; then
    echo "The captured rollback configuration does not match the verified Team Hub configuration." >&2
    return 1
  fi
}

restore_regular_configuration() {
  local target="$1"
  local backup="$2"
  local existed="$3"
  if [[ "$existed" == "true" ]]; then
    [[ -n "$backup" && -f "$backup" ]] || return 1
    cp -p "$backup" "$target"
  else
    if [[ -d "$target" && ! -L "$target" ]]; then
      echo "Refusing to replace unexpected configuration directory $target." >&2
      return 1
    fi
    if [[ -e "$target" || -L "$target" ]]; then
      rm -f "$target"
    fi
  fi
}

restore_runtime_configuration() {
  [[ "$ENV_CONFIG_CAPTURED" != "true" ]] || \
    restore_regular_configuration "$ENV_FILE" "$ENV_CONFIG_BACKUP" "$ENV_CONFIG_EXISTED" || return
  local service_file="$SYSTEMD_SERVICE_FILE"
  [[ "$OS_NAME" != "Darwin" ]] || service_file="$PLIST"
  [[ "$SERVICE_CONFIG_CAPTURED" != "true" ]] || \
    restore_regular_configuration "$service_file" "$SERVICE_CONFIG_BACKUP" "$SERVICE_CONFIG_EXISTED" || return
}

restore_release_links() {
  [[ "$CURRENT_LINK_STATE_CAPTURED" == "true" ]] || return 0
  if [[ "$CURRENT_LINK_WAS_DIRECTORY" == "true" ]]; then
    if [[ -n "$OLD_TARGET" && -d "$OLD_TARGET" ]]; then
      if [[ -e "$CURRENT_LINK" && ! -L "$CURRENT_LINK" ]]; then
        echo "Refusing to replace unexpected current release path $CURRENT_LINK." >&2
        return 1
      fi
      ln -sfn "$OLD_TARGET" "$CURRENT_LINK" || return
    elif [[ ! -d "$CURRENT_LINK" || -L "$CURRENT_LINK" ]]; then
      echo "The original current release directory cannot be recovered." >&2
      return 1
    fi
  elif [[ "$CURRENT_LINK_WAS_SYMLINK" == "true" ]]; then
    if [[ -n "$OLD_TARGET" && -e "$OLD_TARGET" ]]; then
      ln -sfn "$OLD_TARGET" "$CURRENT_LINK" || return
    elif [[ -L "$CURRENT_LINK" && "$(readlink "$CURRENT_LINK")" == "$CURRENT_LINK_TARGET" ]]; then
      :
    else
      echo "The original current release link cannot be recovered." >&2
      return 1
    fi
  elif [[ -L "$CURRENT_LINK" ]]; then
    rm -f "$CURRENT_LINK" || return
  elif [[ -e "$CURRENT_LINK" ]]; then
    echo "Refusing to replace unexpected current release path $CURRENT_LINK." >&2
    return 1
  fi

  if [[ "$PREVIOUS_LINK_STATE_CAPTURED" == "true" ]]; then
    if [[ "$PREVIOUS_LINK_WAS_SYMLINK" == "true" ]]; then
      ln -sfn "$PREVIOUS_LINK_TARGET" "$PREVIOUS_LINK" || return
    elif [[ -L "$PREVIOUS_LINK" ]]; then
      rm -f "$PREVIOUS_LINK" || return
    elif [[ -e "$PREVIOUS_LINK" ]]; then
      echo "Refusing to replace unexpected previous release path $PREVIOUS_LINK." >&2
      return 1
    fi
  fi
}

restore_pre_candidate_changes() {
  restore_release_links || return
  restore_runtime_configuration || return
}

signal_active_stage() {
  local signal_name="$1"
  if [[ -n "$ACTIVE_STAGE_PGID" ]] && kill "-$signal_name" -- "-$ACTIVE_STAGE_PGID" >/dev/null 2>&1; then
    return 0
  fi
  [[ -z "$ACTIVE_STAGE_PID" ]] || kill "-$signal_name" "$ACTIVE_STAGE_PID" >/dev/null 2>&1 || true
}

stop_active_stage() {
  [[ -n "$ACTIVE_STAGE_PID" ]] || return 0
  signal_active_stage TERM
  local attempt
  for attempt in $(seq 1 20); do
    kill -0 "$ACTIVE_STAGE_PID" >/dev/null 2>&1 || break
    sleep 0.05
  done
  if kill -0 "$ACTIVE_STAGE_PID" >/dev/null 2>&1; then
    signal_active_stage KILL
  fi
  wait "$ACTIVE_STAGE_PID" 2>/dev/null || true
  ACTIVE_STAGE_PID=""
  ACTIVE_STAGE_PGID=""
}

install_lock_python() {
  local candidate=""
  local probe=""
  for candidate in \
    "$STAGE_DIR/.venv/bin/python" \
    "$RELEASE_DIR/.venv/bin/python" \
    "$CURRENT_LINK/.venv/bin/python" \
    "$ACTIVATION_TRANSACTION_DIR/candidate.retired/.venv/bin/python" \
    "$(command -v python3 2>/dev/null || true)" \
    "/usr/bin/python3"; do
    [[ -n "$candidate" && -x "$candidate" ]] || continue
    probe="$("$candidate" -c 'print("agentsdock-install-lock-v1")' 2>/dev/null || true)"
    [[ "$probe" == "agentsdock-install-lock-v1" ]] || continue
    printf '%s\n' "$candidate"
    return 0
  done
  return 1
}

install_lock_control() {
  local action="$1"
  local expected_device="${2:-0}"
  local expected_inode="${3:-0}"
  local python_path=""
  python_path="$(install_lock_python)" || return 1
  "$python_path" - \
    "$action" "$INSTALL_ROOT" "$$" "$expected_device" "$expected_inode" <<'PY'
import errno
import os
from pathlib import Path
import secrets
import stat
import sys

action, raw_root, raw_pid, raw_device, raw_inode = sys.argv[1:]
root = Path(os.path.abspath(raw_root))
pid = int(raw_pid)
lock = root / ".install-lock"

root_info = root.lstat()
if (
    not stat.S_ISDIR(root_info.st_mode)
    or root_info.st_uid != os.geteuid()
    or stat.S_IMODE(root_info.st_mode) & 0o022
):
    raise PermissionError("AgentsServer install root is unsafe")
releases = root / "releases"
try:
    releases_info = releases.lstat()
except FileNotFoundError:
    pass
else:
    if (
        not stat.S_ISDIR(releases_info.st_mode)
        or releases_info.st_uid != os.geteuid()
        or stat.S_IMODE(releases_info.st_mode) & 0o022
    ):
        raise PermissionError("AgentsServer releases root is unsafe")


def fsync_directory(path: Path) -> None:
    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_DIRECTORY", 0)
    descriptor = os.open(path, flags)
    try:
        os.fsync(descriptor)
    finally:
        os.close(descriptor)


def open_lock_directory() -> tuple[int, os.stat_result]:
    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_DIRECTORY", 0)
    descriptor = os.open(lock, flags)
    info = os.fstat(descriptor)
    if (
        not stat.S_ISDIR(info.st_mode)
        or info.st_uid != os.geteuid()
        or stat.S_IMODE(info.st_mode) & 0o077
    ):
        os.close(descriptor)
        raise PermissionError("AgentsServer install lock directory is unsafe")
    return descriptor, info


def read_owner(directory_descriptor: int) -> tuple[int, tuple[int, int]]:
    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0)
    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
    descriptor = os.open("pid", flags, dir_fd=directory_descriptor)
    try:
        info = os.fstat(descriptor)
        if (
            not stat.S_ISREG(info.st_mode)
            or info.st_uid != os.geteuid()
            or info.st_nlink != 1
            or stat.S_IMODE(info.st_mode) not in {0o600, 0o644}
            or not 1 <= info.st_size <= 32
        ):
            raise PermissionError("AgentsServer install lock owner is unsafe")
        raw = os.read(descriptor, 33)
        if len(raw) > 32 or os.read(descriptor, 1):
            raise RuntimeError("AgentsServer install lock owner is invalid")
    finally:
        os.close(descriptor)
    try:
        value = raw.decode("ascii").strip()
    except UnicodeError as exc:
        raise RuntimeError("AgentsServer install lock owner is invalid") from exc
    if not value.isdigit() or int(value) <= 1:
        raise RuntimeError("AgentsServer install lock owner is invalid")
    return int(value), (int(info.st_dev), int(info.st_ino))


if action == "acquire":
    candidate = root / f".install-lock.{pid}.{secrets.token_hex(12)}.tmp"
    os.mkdir(candidate, 0o700)
    os.chmod(candidate, 0o700)
    candidate_info = candidate.lstat()
    owned = False
    try:
        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
        flags |= getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
        descriptor = os.open(candidate / "pid", flags, 0o600)
        try:
            os.fchmod(descriptor, 0o600)
            payload = f"{pid}\n".encode("ascii")
            offset = 0
            while offset < len(payload):
                offset += os.write(descriptor, payload[offset:])
            os.fsync(descriptor)
        finally:
            os.close(descriptor)
        fsync_directory(candidate)
        for _attempt in range(32):
            try:
                os.rename(candidate, lock)
            except OSError as exc:
                if exc.errno not in {errno.EEXIST, errno.ENOTEMPTY}:
                    raise
                directory_descriptor, directory_info = open_lock_directory()
                try:
                    try:
                        owner_pid, owner_identity = read_owner(directory_descriptor)
                    except FileNotFoundError:
                        # An old installer may have crashed in mkdir->pid. The
                        # next atomic directory rename replaces only that
                        # exact empty namespace; a populated replacement wins.
                        continue
                    try:
                        os.kill(owner_pid, 0)
                    except ProcessLookupError:
                        pass
                    except PermissionError:
                        raise RuntimeError(
                            f"another AgentsServer installation is active ({owner_pid})"
                        )
                    else:
                        raise RuntimeError(
                            f"another AgentsServer installation is active ({owner_pid})"
                        )
                    # unlinkat is relative to the pinned old directory. If a
                    # competing reaper has already replaced the lock path,
                    # this can never remove the new owner's pid.
                    try:
                        current_owner, current_identity = read_owner(
                            directory_descriptor
                        )
                    except FileNotFoundError:
                        continue
                    if current_owner != owner_pid or current_identity != owner_identity:
                        continue
                    try:
                        os.unlink("pid", dir_fd=directory_descriptor)
                    except FileNotFoundError:
                        continue
                    os.fsync(directory_descriptor)
                finally:
                    os.close(directory_descriptor)
                continue
            else:
                owned = True
                for _ in range(3):
                    try:
                        fsync_directory(root)
                        break
                    except OSError:
                        continue
                else:
                    raise RuntimeError("AgentsServer install lock was not durable")
                published = lock.lstat()
                if (
                    published.st_dev != candidate_info.st_dev
                    or published.st_ino != candidate_info.st_ino
                ):
                    raise RuntimeError("AgentsServer install lock ownership changed")
                print(published.st_dev)
                print(published.st_ino)
                raise SystemExit(0)
        raise RuntimeError("AgentsServer install lock ownership kept changing")
    finally:
        if not owned:
            try:
                (candidate / "pid").unlink()
            except FileNotFoundError:
                pass
            try:
                candidate.rmdir()
            except FileNotFoundError:
                pass
elif action == "release":
    expected = (int(raw_device), int(raw_inode))
    directory_descriptor, directory_info = open_lock_directory()
    try:
        if (directory_info.st_dev, directory_info.st_ino) != expected:
            raise RuntimeError("AgentsServer install lock ownership changed")
        owner_pid, _owner_identity = read_owner(directory_descriptor)
        if owner_pid != pid:
            raise RuntimeError("AgentsServer install lock owner changed")
        os.unlink("pid", dir_fd=directory_descriptor)
        os.fsync(directory_descriptor)
    finally:
        os.close(directory_descriptor)
    linked = lock.lstat()
    if (linked.st_dev, linked.st_ino) != expected:
        raise RuntimeError("AgentsServer install lock ownership changed")
    os.rmdir(lock)
    for _ in range(3):
        try:
            fsync_directory(root)
            break
        except OSError:
            continue
    else:
        raise RuntimeError("AgentsServer install lock release was not durable")
else:
    raise RuntimeError("AgentsServer install lock action is invalid")
PY
}

release_install_lock() {
  [[ "$INSTALL_LOCK_HELD" == "true" ]] || return 0
  if install_lock_control release \
      "$INSTALL_LOCK_DEVICE" "$INSTALL_LOCK_INODE" >/dev/null; then
    INSTALL_LOCK_HELD="false"
    INSTALL_LOCK_DEVICE=""
    INSTALL_LOCK_INODE=""
    return 0
  fi
  echo "The exact AgentsServer install lock could not be released safely." >&2
  return 1
}

team_hub_transaction_requires_recovery() {
  [[ "$TEAM_HUB_OPERATION_PENDING" == "true" \
    && "$TEAM_HUB_OPERATION_FINALIZED" != "true" ]] && return 0
  [[ "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" \
    && "$TEAM_HUB_REACTIVATION_FINALIZED" != "true" ]] && return 0
  return 1
}

cleanup() {
  local exit_status=$?
  trap - EXIT
  mask_install_signals
  IN_EXIT_CLEANUP="true"
  set +e
  stop_active_stage
  if [[ "$exit_status" != "0" \
    && -n "$ACTIVATION_TRANSACTION_ID" \
    && "$TEAM_HUB_RECOVERY_ATTEMPTED" != "true" ]]; then
    TEAM_HUB_RECOVERY_ATTEMPTED="true"
    case "$ACTIVATION_TRANSACTION_PHASE" in
      committing|committed)
        if declare -F complete_activation_commit >/dev/null \
          && ! complete_activation_commit; then
          echo "The candidate passed its commit boundary; exact finalization remains pending for retry." >&2
        fi
        ;;
      rollback-healthy)
        if declare -F finish_activation_transaction >/dev/null \
          && ! finish_activation_transaction "$STAGE_DIR"; then
          echo "The verified rollback remains durably journaled for retirement." >&2
        fi
        ;;
      *)
        if declare -F restore_previous_release_transaction >/dev/null \
          && ! restore_previous_release_transaction; then
          echo "Activation rollback is incomplete; the exact transaction remains fail-closed for retry." >&2
        fi
        ;;
    esac
  fi
  if [[ "$exit_status" != "0" \
    && -z "$ACTIVATION_TRANSACTION_ID" \
    && "$TEAM_HUB_RECOVERY_ATTEMPTED" != "true" ]] \
    && { team_hub_transaction_requires_recovery \
      || [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]] \
      || [[ "$SERVICE_STOPPED_FOR_COLD_HANDOFF" == "true" ]]; }; then
    TEAM_HUB_RECOVERY_ATTEMPTED="true"
    if [[ "$CANDIDATE_SERVICE_MAY_HAVE_STARTED" == "true" ]]; then
      if declare -F restore_previous_release >/dev/null && restore_previous_release; then
        [[ "$TEAM_HUB_OPERATION_PENDING" != "true" ]] || TEAM_HUB_OPERATION_FINALIZED="true"
      elif [[ "$TEAM_HUB_OPERATION_PENDING" == "true" \
        || "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
        echo "Team Hub rollback is incomplete; the exact maintenance fence remains fail-closed when present." >&2
      fi
    elif restore_pre_candidate_changes; then
      local cold_handoff_released="true"
      if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
        cold_handoff_released="false"
        if clear_team_hub_operation_fence "$CANDIDATE_RUNTIME_ROOT"; then
          TEAM_HUB_OPERATION_FINALIZED="true"
          cold_handoff_released="true"
        else
          echo "AgentsServer install failed before candidate health and could not safely release Team Hub maintenance." >&2
        fi
      elif [[ "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" \
        && "$TEAM_HUB_REACTIVATION_FINALIZED" != "true" ]]; then
        cold_handoff_released="false"
        if clear_team_hub_reactivation_fence "$CANDIDATE_RUNTIME_ROOT"; then
          TEAM_HUB_REACTIVATION_FINALIZED="true"
          cold_handoff_released="true"
        else
          echo "AgentsServer install failed before takeover and could not safely release Team Hub reactivation maintenance." >&2
        fi
      fi
      if [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]]; then
        if ! clear_team_hub_cold_guard "$CANDIDATE_RUNTIME_ROOT"; then
          cold_handoff_released="false"
          echo "AgentsServer install could not clear the exact Team Hub startup guard." >&2
        fi
      fi
      if [[ "$SERVICE_STOPPED_FOR_COLD_HANDOFF" == "true" \
        && "$cold_handoff_released" == "true" ]]; then
        if restart_service && wait_for_previous_release_health; then
          SERVICE_STOPPED_FOR_COLD_HANDOFF="false"
        else
          echo "The pre-candidate Team Hub fence was released, but the previous service did not recover." >&2
        fi
      fi
    elif [[ "$TEAM_HUB_OPERATION_PENDING" == "true" \
      || "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
      echo "AgentsServer install failed before candidate health and could not restore local configuration; Team Hub remains fail-closed." >&2
    fi
  fi
  release_install_lock
  if [[ -n "$STAGE_DIR_DEVICE" && -n "$STAGE_DIR_INODE" ]]; then
    local cleanup_python=""
    cleanup_python="$(install_lock_python 2>/dev/null \
      || command -v python3 2>/dev/null || true)"
    if [[ -n "$cleanup_python" ]]; then
      "$cleanup_python" - \
        "$STAGE_DIR" "$STAGE_DIR_DEVICE" "$STAGE_DIR_INODE" <<'PY' || true
import os
from pathlib import Path
import shutil
import stat
import sys

path = Path(sys.argv[1])
expected = (int(sys.argv[2]), int(sys.argv[3]))
try:
    info = path.lstat()
except FileNotFoundError:
    raise SystemExit(0)
if (
    (info.st_dev, info.st_ino) != expected
    or not stat.S_ISDIR(info.st_mode)
    or info.st_uid != os.geteuid()
    or stat.S_IMODE(info.st_mode) & 0o022
):
    # The original stage was activated/renamed or the pathname was replaced.
    # Never recurse through a namespace that is no longer ours.
    raise SystemExit(0)
if not shutil.rmtree.avoids_symlink_attacks:
    raise RuntimeError("safe staged-release cleanup is unavailable")
shutil.rmtree(path)
PY
    fi
  fi
  exit "$exit_status"
}
trap cleanup EXIT
trap 'exit 130' HUP INT TERM

acquire_install_lock() {
  validate_install_layout_paths || return 1
  if [[ ! -e "$INSTALL_ROOT" && ! -L "$INSTALL_ROOT" ]]; then
    (umask 077; mkdir -p "$INSTALL_ROOT") || return 1
  fi
  validate_install_layout_paths || return 1
  local result=""
  if ! result="$(install_lock_control acquire)"; then
    echo "Another AgentsServer installation is already running or its lock is unsafe." >&2
    echo "  Wait for it to finish, or cancel it from AgentsDock before retrying." >&2
    return 1
  fi
  INSTALL_LOCK_DEVICE="${result%%$'\n'*}"
  INSTALL_LOCK_INODE="${result#*$'\n'}"
  if [[ "$result" != *$'\n'* \
    || ! "$INSTALL_LOCK_DEVICE" =~ ^[1-9][0-9]*$ \
    || ! "$INSTALL_LOCK_INODE" =~ ^[1-9][0-9]*$ \
    || "$INSTALL_LOCK_INODE" == *$'\n'* ]]; then
    echo "The AgentsServer install lock returned invalid ownership." >&2
    return 1
  fi
  INSTALL_LOCK_HELD="true"
}

validate_exclusive_install_state() {
  if [[ -d "$ACTIVATION_TRANSACTION_DIR" \
    && ! -L "$ACTIVATION_TRANSACTION_DIR" ]]; then
    ACTIVATION_TRANSACTION_RESUMED="true"
  elif [[ -e "$ACTIVATION_TRANSACTION_DIR" \
    || -L "$ACTIVATION_TRANSACTION_DIR" ]]; then
    echo "The pending activation transaction path is unsafe." >&2
    return 1
  elif ! validate_managed_team_hub_inputs "$CURRENT_LINK"; then
    echo "Managed Team Hub inputs changed before the installer acquired exclusive ownership." >&2
    return 1
  fi
}

# Existing installs and ordinary supported hosts have a trusted Python before
# staging, so exclusion precedes even dependency work. A truly fresh host
# without Python may build only its PID-unique staging runtime first; no
# release link, configuration, state, or service mutation occurs before the
# same lock is acquired below.
validate_install_layout_paths || exit 1
if install_lock_python >/dev/null 2>&1; then
  acquire_install_lock || exit 1
  validate_exclusive_install_state || exit 1
fi

run_timed_stage() {
  local label="$1"
  local timeout_seconds="$2"
  local guidance="$3"
  shift 3
  local started_at="$SECONDS"
  local next_heartbeat=$((SECONDS + INSTALL_HEARTBEAT_SECONDS))
  local elapsed=0
  local status=0

  echo "      $label (timeout: ${timeout_seconds}s)"
  # A separate process group lets timeout/cancellation terminate workers
  # spawned by uv or by the uv bootstrap script, not only their parent shell.
  set -m
  "$@" &
  ACTIVE_STAGE_PID="$!"
  ACTIVE_STAGE_PGID="$ACTIVE_STAGE_PID"
  set +m
  while kill -0 "$ACTIVE_STAGE_PID" >/dev/null 2>&1; do
    elapsed=$((SECONDS - started_at))
    if ((SECONDS >= next_heartbeat)); then
      echo "      Still working on $label (${elapsed}s elapsed)"
      next_heartbeat=$((SECONDS + INSTALL_HEARTBEAT_SECONDS))
    fi
    if ((elapsed >= timeout_seconds)); then
      echo "$label timed out after ${timeout_seconds}s." >&2
      echo "  $guidance" >&2
      stop_active_stage
      return 124
    fi
    sleep 1
  done

  if wait "$ACTIVE_STAGE_PID"; then
    ACTIVE_STAGE_PID=""
    ACTIVE_STAGE_PGID=""
    return 0
  else
    status=$?
  fi
  ACTIVE_STAGE_PID=""
  ACTIVE_STAGE_PGID=""
  echo "$label failed with exit code $status." >&2
  echo "  $guidance" >&2
  return "$status"
}

sync_release_dependencies() (
  # Managed updates may be launched from a long-lived tmux server. Never let
  # project/virtual-environment selectors inherited by that server redirect
  # this release sync into an unrelated workspace.
  # PEP 517 build subprocesses inherit uv's environment. Start from a narrow
  # allowlist so credentials and unrelated project selectors from the calling
  # desktop/tmux/service environment never enter third-party build hooks.
  env -i \
    HOME="$HOME" \
    LANG=C \
    LC_ALL=C \
    PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" \
    UV_PROJECT_ENVIRONMENT="$STAGE_DIR/.venv" \
    "$UV_BIN" sync \
      --project "$STAGE_DIR" \
      --python '>=3.10' \
      --no-dev \
      --quiet \
      --frozen
)

validate_staged_release_runtime() (
  scrub_staged_process_environment
  "$STAGE_DIR/.venv/bin/python" -c 'import websockets' >/dev/null
  "$STAGE_DIR/.venv/bin/python" -c 'from importlib.metadata import version; import claude_agent_sdk; sdk_version = version("claude-agent-sdk"); raise SystemExit(0 if sdk_version == "0.2.130" else f"expected claude-agent-sdk 0.2.130, got {sdk_version}")'
  "$STAGE_DIR/.venv/bin/python" -c 'import croniter, dateutil; from zoneinfo import ZoneInfo; ZoneInfo("America/Los_Angeles")' >/dev/null
  "$STAGE_DIR/.venv/bin/python" -m py_compile \
    "$STAGE_DIR/activation_transaction.py" \
    "$STAGE_DIR/agent_server.py" \
    "$STAGE_DIR/team_hub_host.py" \
    "$STAGE_DIR/secure_peer_runtime.py" \
    "$STAGE_DIR/team_mail_runtime.py" \
    "$STAGE_DIR/team_mail_websocket.py" \
    "$STAGE_DIR/team_mail_grants.py" \
    "$STAGE_DIR/secure_peer_delivery.py" \
    "$STAGE_DIR/agentsdock_jobs.py" \
    "$STAGE_DIR/agentsdock_chats.py" \
    "$STAGE_DIR/chat_mailbox.py" \
    "$STAGE_DIR/agentsdock_emergency.py" \
    "$STAGE_DIR/agentsdock_publish.py" \
    "$STAGE_DIR/agentsdock_mail.py" \
    "$STAGE_DIR/agentsdock_team.py" \
    "$STAGE_DIR/provider_commands.py" \
    "$STAGE_DIR/claude_sdk_client.py" \
    "$STAGE_DIR/claude_background_reconciliation.py" \
    "$STAGE_DIR/codex_app_server.py" \
    "$STAGE_DIR/codex_auth.py" \
    "$STAGE_DIR/codex_provider.py" \
    "$STAGE_DIR/side_questions.py" \
    "$STAGE_DIR/workspace_git.py" \
    "$STAGE_DIR/codex_side_question.py" \
    "$STAGE_DIR/claude_side_question.py" \
    "$STAGE_DIR/cursor_agent_client.py" \
    "$STAGE_DIR/opencode_agent_client.py" \
    "$STAGE_DIR/cursor_process_guard.py" \
    "$STAGE_DIR/claude_history_repair.py" \
    "$STAGE_DIR/claude_history_provenance.py" \
    "$STAGE_DIR/codex_history_repair.py" \
    "$STAGE_DIR/public_chat_shares.py" \
    "$STAGE_DIR/public_chat_transcript.py" \
    "$STAGE_DIR/public_chat_share_routes.py" \
    "$STAGE_DIR/interactive_chat_shares.py" \
    "$STAGE_DIR/interactive_chat_share_routes.py" \
    "$STAGE_DIR/interactive_chat_share_web.py" \
    "$STAGE_DIR/interactive_chat_projection.py" \
    "$STAGE_DIR/interactive_chat_runtime.py" \
    "$STAGE_DIR/interactive_chat_native.py" \
    "$STAGE_DIR/shared_chat_videos.py" \
    "$STAGE_DIR/shared_chat_video_stream.py" \
    "$STAGE_DIR/interactive_chat_controls.py" \
    "$STAGE_DIR/update_runner.py"
  "$STAGE_DIR/.venv/bin/python" -m py_compile "$STAGE_DIR/server_instances.py"
  "$STAGE_DIR/.venv/bin/python" -m compileall -q "$STAGE_DIR/agentsdock_team_hub"
  PYTHONPATH="$STAGE_DIR" "$STAGE_DIR/.venv/bin/python" -c 'import workspace_git; import codex_auth, codex_provider, side_questions, codex_side_question, claude_side_question, agentsdock_team_hub, cursor_agent_client, cursor_process_guard, secure_peer_delivery, secure_peer_runtime, team_mail_runtime, team_mail_websocket, team_mail_grants, team_hub_host, agentsdock_mail, agentsdock_team, claude_history_repair, claude_history_provenance, claude_background_reconciliation, codex_history_repair, public_chat_shares, public_chat_transcript, public_chat_share_routes, interactive_chat_shares, interactive_chat_share_routes, interactive_chat_share_web, interactive_chat_projection, interactive_chat_runtime, interactive_chat_native, shared_chat_videos, shared_chat_video_stream, interactive_chat_controls, chat_mailbox, provider_commands, opencode_agent_client; import server_instances; from agentsdock_team_hub import secure_peer, secure_peer_hub' >/dev/null
)

abort_unclaimed_team_hub_reactivation() {
  local hub_id="$1"
  local operation_id="$2"
  local snapshot="$3"
  local fence_device="$4"
  local fence_inode="$5"
  run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
    "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" -m agentsdock_team_hub.cli \
    abort-host-reactivation-preflight \
    --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
    --server-state-dir "$STATE_ROOT" \
    --expected-hub-id "$hub_id" \
    --expected-operation-id "$operation_id" \
    --expected-snapshot "$snapshot" \
    --expected-device "$fence_device" \
    --expected-inode "$fence_inode" >/dev/null 2>&1
}

adopt_team_hub_reactivation() {
  local hub_id="$1"
  local operation_id="$2"
  local snapshot="$3"
  local fence_device="$4"
  local fence_inode="$5"
  run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
    "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" -m agentsdock_team_hub.cli \
    adopt-host-reactivation-preflight \
    --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
    --server-state-dir "$STATE_ROOT" \
    --expected-hub-id "$hub_id" \
    --expected-operation-id "$operation_id" \
    --expected-snapshot "$snapshot" \
    --expected-device "$fence_device" \
    --expected-inode "$fence_inode" >/dev/null
}

begin_team_hub_cold_guard() {
  local result=""
  local identity=""
  local remainder=""
  if ! result="$(
    run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
      "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" -m agentsdock_team_hub.cli \
      begin-host-cold-handoff \
      --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
      --server-state-dir "$STATE_ROOT"
  )"; then
    return 1
  fi
  identity="${result%%$'\n'*}"
  remainder="${result#*$'\n'}"
  TEAM_HUB_COLD_GUARD_ID="${remainder%%$'\n'*}"
  remainder="${remainder#*$'\n'}"
  TEAM_HUB_COLD_GUARD_DEVICE="${remainder%%$'\n'*}"
  TEAM_HUB_COLD_GUARD_INODE="${remainder#*$'\n'}"
  if [[ "$result" != *$'\n'* \
    || ( -n "$EXPECTED_SERVER_IDENTITY" && "$identity" != "$EXPECTED_SERVER_IDENTITY" ) \
    || ! "$TEAM_HUB_COLD_GUARD_ID" =~ ^cold-handoff-[0-9a-f]{24}$ \
    || ! "$TEAM_HUB_COLD_GUARD_DEVICE" =~ ^[0-9]+$ \
    || ! "$TEAM_HUB_COLD_GUARD_INODE" =~ ^[0-9]+$ \
    || "$TEAM_HUB_COLD_GUARD_INODE" == *$'\n'* ]]; then
    echo "Team Hub cold-handoff guard returned an invalid result." >&2
    return 1
  fi
  EXPECTED_SERVER_IDENTITY="$identity"
  TEAM_HUB_COLD_GUARD_PENDING="true"
}

clear_team_hub_cold_guard() {
  [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]] || return 0
  local runtime_root="${1:-$RELEASE_DIR}"
  local allow_missing="${2:-false}"
  [[ -x "$runtime_root/.venv/bin/python" ]] || return 1
  if run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
    clear-host-cold-handoff \
    --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
    --server-state-dir "$STATE_ROOT" \
    --expected-guard-id "$TEAM_HUB_COLD_GUARD_ID" \
    --expected-device "$TEAM_HUB_COLD_GUARD_DEVICE" \
    --expected-inode "$TEAM_HUB_COLD_GUARD_INODE" >/dev/null; then
    TEAM_HUB_COLD_GUARD_PENDING="false"
    return 0
  fi
  if [[ "$allow_missing" == "true" \
    && ! -e "$TEAM_HUB_CANONICAL_DATA_DIR/.managed-startup-guard.json" \
    && ! -L "$TEAM_HUB_CANONICAL_DATA_DIR/.managed-startup-guard.json" ]]; then
    TEAM_HUB_COLD_GUARD_PENDING="false"
    return 0
  fi
  return 1
}

invalid_team_hub_reactivation_result() {
  local hub_id="$1"
  local operation_id="$2"
  local snapshot="$3"
  local fence_device="$4"
  local fence_inode="$5"
  echo "Team Hub reactivation preflight returned an invalid result." >&2
  if ! abort_unclaimed_team_hub_reactivation \
      "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode"; then
    echo "Any committed Team Hub reactivation fence remains fail-closed." >&2
  fi
  return 1
}

prepare_team_hub_reactivation() {
  [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]] || return 0
  local result=""
  local identity=""
  local remainder=""
  local hub_id=""
  local operation_id=""
  local snapshot=""
  local fence_device=""
  local fence_inode=""
  local snapshot_parent=""
  local snapshot_name=""
  if ! result="$(
    run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
      "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" -m agentsdock_team_hub.cli \
      prepare-host-reactivation \
      --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
      --server-state-dir "$STATE_ROOT"
  )"; then
    echo "Team Hub reactivation preflight failed; hosting mode and the active release were not changed." >&2
    return 1
  fi
  if [[ "$result" != *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned a truncated result; any committed fence remains fail-closed." >&2
    return 1
  fi
  identity="${result%%$'\n'*}"
  remainder="${result#*$'\n'}"
  if [[ "$remainder" != *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned a truncated result; any committed fence remains fail-closed." >&2
    return 1
  fi
  hub_id="${remainder%%$'\n'*}"
  remainder="${remainder#*$'\n'}"
  if [[ "$remainder" != *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned a truncated result; any committed fence remains fail-closed." >&2
    return 1
  fi
  operation_id="${remainder%%$'\n'*}"
  remainder="${remainder#*$'\n'}"
  if [[ "$remainder" != *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned a truncated result; any committed fence remains fail-closed." >&2
    return 1
  fi
  snapshot="${remainder%%$'\n'*}"
  remainder="${remainder#*$'\n'}"
  if [[ "$remainder" != *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned a truncated result; any committed fence remains fail-closed." >&2
    return 1
  fi
  fence_device="${remainder%%$'\n'*}"
  fence_inode="${remainder#*$'\n'}"
  if [[ ! "$identity" =~ ^[0-9a-f]{24}$ \
    || ! "$hub_id" =~ ^[A-Za-z0-9_.:-]{8,240}$ \
    || ! "$operation_id" =~ ^host-reactivation-[0-9a-f]{24}$ \
    || -z "$snapshot" \
    || "$snapshot" == *$'\n'* \
    || ! "$fence_device" =~ ^[0-9]+$ \
    || ! "$fence_inode" =~ ^[0-9]+$ \
    || "$fence_inode" == *$'\n'* ]]; then
    echo "Team Hub reactivation preflight returned an invalid identity, Hub, operation, or snapshot." >&2
    invalid_team_hub_reactivation_result \
      "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode" || true
    return 1
  fi
  snapshot_parent="${snapshot%/*}"
  snapshot_name="${snapshot##*/}"
  if [[ "$snapshot_parent" != "$TEAM_HUB_CANONICAL_DATA_DIR/maintenance-backups" \
    || ! "$snapshot_name" =~ ^snapshot_[0-9]{20}_[0-9a-f]{16}$ \
    || ! -d "$snapshot" \
    || -L "$snapshot" ]]; then
    echo "Team Hub reactivation preflight returned an unsafe snapshot path." >&2
    invalid_team_hub_reactivation_result \
      "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode" || true
    return 1
  fi
  if [[ -n "$EXPECTED_SERVER_IDENTITY" && "$EXPECTED_SERVER_IDENTITY" != "$identity" ]]; then
    echo "Team Hub reactivation identity does not match the expected AgentsServer identity." >&2
    invalid_team_hub_reactivation_result \
      "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode" || true
    return 1
  fi
  # Own the parsed operation in shell state before the durable adoption call.
  # If adoption commits its rename but reports an fsync ambiguity, EXIT cleanup
  # must see and either exactly clear this fence or keep the old host stopped;
  # it must never restart legacy code against an adopted rollback generation.
  EXPECTED_SERVER_IDENTITY="$identity"
  TEAM_HUB_REACTIVATION_HUB_ID="$hub_id"
  TEAM_HUB_REACTIVATION_OPERATION_ID="$operation_id"
  TEAM_HUB_REACTIVATION_SNAPSHOT="$snapshot"
  TEAM_HUB_REACTIVATION_FENCE_DEVICE="$fence_device"
  TEAM_HUB_REACTIVATION_FENCE_INODE="$fence_inode"
  TEAM_HUB_REACTIVATION_FENCE_PENDING="true"
  if ! adopt_team_hub_reactivation \
      "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode"; then
    echo "Team Hub reactivation preflight could not be durably adopted." >&2
    if abort_unclaimed_team_hub_reactivation \
        "$hub_id" "$operation_id" "$snapshot" "$fence_device" "$fence_inode"; then
      TEAM_HUB_REACTIVATION_FENCE_PENDING="false"
      TEAM_HUB_REACTIVATION_FINALIZED="true"
    else
      echo "The exact Team Hub reactivation operation remains fail-closed." >&2
    fi
    return 1
  fi
  echo "      Verified preserved Team Hub binding and snapshot: $snapshot"
}

migrate_legacy_state() {
  [[ "$STATE_ROOT" == "$DEFAULT_STATE_GUARD" ]] || return 0
  if [[ -L "$LEGACY_STATE_ROOT" ]]; then
    return 0
  fi
  if [[ -e "$LEGACY_STATE_ROOT" && ! -e "$STATE_ROOT" ]]; then
    local legacy_mode=""
    if [[ ! -d "$LEGACY_STATE_ROOT" \
      || ! -O "$LEGACY_STATE_ROOT" \
      || -L "$LEGACY_STATE_ROOT" ]]; then
      echo "The legacy state path is not a safe owned directory; refusing to migrate it." >&2
      return 1
    fi
    legacy_mode="$(stat -c '%a' "$LEGACY_STATE_ROOT" 2>/dev/null \
      || stat -f '%Lp' "$LEGACY_STATE_ROOT" 2>/dev/null)" || return 1
    if [[ ! "$legacy_mode" =~ ^[0-7]{3,4}$ \
      || $((8#$legacy_mode & 8#022)) -ne 0 ]]; then
      echo "The legacy state directory is group/world writable; refusing to migrate it." >&2
      return 1
    fi
    echo "      Migrating existing AgentsDock history to $STATE_ROOT"
    mv "$LEGACY_STATE_ROOT" "$STATE_ROOT"
    ln -s "$STATE_ROOT" "$LEGACY_STATE_ROOT"
  elif [[ -e "$LEGACY_STATE_ROOT" && -e "$STATE_ROOT" ]]; then
    echo "Both $LEGACY_STATE_ROOT and $STATE_ROOT exist; refusing to guess which history is canonical." >&2
    exit 1
  elif [[ -d "$STATE_ROOT" && ! -e "$LEGACY_STATE_ROOT" ]]; then
    ln -s "$STATE_ROOT" "$LEGACY_STATE_ROOT"
  fi
}

echo "[1/7] Preparing the versioned AgentsServer runtime"
if [[ ! -e "$RELEASES_ROOT" && ! -L "$RELEASES_ROOT" ]]; then
  (umask 077; mkdir -p "$RELEASES_ROOT")
fi
validate_install_layout_paths || exit 1

[[ -x "$UV_BIN" ]] \
  && "$UV_BIN" --version >/dev/null 2>&1 \
  || { echo "A trusted uv installation is not available on PATH." >&2; exit 1; }

if [[ -e "$STAGE_DIR" || -L "$STAGE_DIR" ]]; then
  echo "The staged release path already exists; refusing to delete an unowned path: $STAGE_DIR" >&2
  exit 1
fi
(umask 077; mkdir "$STAGE_DIR")
stage_identity="$(stat -c $'%d\n%i' "$STAGE_DIR" 2>/dev/null \
  || stat -f $'%d\n%i' "$STAGE_DIR" 2>/dev/null)" || exit 1
STAGE_DIR_DEVICE="${stage_identity%%$'\n'*}"
STAGE_DIR_INODE="${stage_identity#*$'\n'}"
if [[ "$stage_identity" != *$'\n'* \
  || ! "$STAGE_DIR_DEVICE" =~ ^[1-9][0-9]*$ \
  || ! "$STAGE_DIR_INODE" =~ ^[1-9][0-9]*$ \
  || "$STAGE_DIR_INODE" == *$'\n'* ]]; then
  echo "The staged release returned invalid ownership." >&2
  exit 1
fi
for name in "${RELEASE_FILES[@]}"; do
  install -m 644 "$SOURCE_DIR/$name" "$STAGE_DIR/$name"
done
mkdir -p "$STAGE_DIR/agentsdock_team_hub/migrations"
chmod 755 "$STAGE_DIR/agentsdock_team_hub" "$STAGE_DIR/agentsdock_team_hub/migrations"
for name in "${TEAM_HUB_RELEASE_FILES[@]}"; do
  install -m 644 \
    "$SOURCE_DIR/agentsdock_team_hub/$name" \
    "$STAGE_DIR/agentsdock_team_hub/$name"
done
chmod 755 "$STAGE_DIR/agent_server.py" "$STAGE_DIR/agentsdock_jobs.py" "$STAGE_DIR/agentsdock_chats.py" "$STAGE_DIR/agentsdock_emergency.py" "$STAGE_DIR/agentsdock_publish.py" "$STAGE_DIR/agentsdock_mail.py" "$STAGE_DIR/agentsdock_team.py" "$STAGE_DIR/install.sh" "$STAGE_DIR/uninstall.sh" "$STAGE_DIR/update_runner.py"
chmod 755 "$STAGE_DIR/instances.sh"

echo "[2/7] Preparing private Python dependencies for instance $INSTANCE_NAME"
echo "      Reusing uv's package cache where available; errors will still be shown."
echo "      This does not reinstall Claude Code, Codex, or tmux."
if run_timed_stage \
  "dependency resolution" \
  "$DEPENDENCY_SYNC_TIMEOUT_SECONDS" \
  "Review the uv output above. Verify disk space and outbound HTTPS access, then run install.sh again; the active release was not changed." \
  sync_release_dependencies; then
  :
else
  stage_status=$?
  exit "$stage_status"
fi
if [[ ! -d "$STAGE_DIR/.venv" || -L "$STAGE_DIR/.venv" || ! -x "$STAGE_DIR/.venv/bin/python" ]]; then
  echo "Dependency resolution did not create the isolated release runtime at $STAGE_DIR/.venv." >&2
  echo "  The active release was not changed. Review the uv output above, then run install.sh again." >&2
  exit 1
fi
validate_staged_release_runtime
if ! validate_bind_address "$BIND_ADDRESS" "$STAGE_DIR/.venv/bin/python"; then
  echo "Bind address must be localhost or one canonical IPv4/IPv6 literal." >&2
  exit 2
fi
if [[ "$INSTALL_LOCK_HELD" != "true" ]]; then
  acquire_install_lock || exit 1
  validate_exclusive_install_state || exit 1
fi
migrate_legacy_state
mkdir -p "$CONFIG_ROOT" "$STATE_ROOT" "$STATE_ROOT/admin"
chmod 700 "$CONFIG_ROOT" "$STATE_ROOT" "$STATE_ROOT/admin"
TOKEN="$(find_existing_token || true)"
generate_token() {
  if command -v openssl >/dev/null 2>&1; then
    openssl rand -hex 32
  else
    run_without_server_secrets "$STAGE_DIR/.venv/bin/python" -c 'import secrets; print(secrets.token_hex(32))'
  fi
}
[[ "$TOKEN" =~ ^[A-Za-z0-9_-]{32,}$ ]] || TOKEN="$(generate_token)"

PRESERVE_SOURCE=""
[[ -z "$LEGACY_ENV_FILE" || ( ! -e "$LEGACY_ENV_FILE" && ! -L "$LEGACY_ENV_FILE" ) ]] \
  || PRESERVE_SOURCE="$LEGACY_ENV_FILE"
[[ ! -e "$ENV_FILE" && ! -L "$ENV_FILE" ]] || PRESERVE_SOURCE="$ENV_FILE"

write_runtime_env() {
  local env_temp="$CONFIG_ROOT/.env.activation-$ACTIVATION_TRANSACTION_ID-env.source"
  (umask 077; set -o noclobber; : > "$env_temp") 2>/dev/null || return 1
  chmod 600 "$env_temp" || return 1
  if [[ -n "$PRESERVE_SOURCE" ]]; then
    local preserved_contents=""
    local filter_status=0
    preserved_contents="$(read_owned_config_file "$PRESERVE_SOURCE")" || return 1
    if printf '%s\n' "$preserved_contents" \
      | grep -Ev '^(AGENTSDOCK_(STATE_DIR|AGENT_CWD|AGENT_BIND|AGENT_PORT|AGENT_TOKEN|SERVER_NAME|TEAM_HUB_MODE|TEAM_HUB_TRANSPORT|TEAM_HUB_URL|TEAM_HUB_DIRECT_IP_URL|TEAM_HUB_REACTIVATION_HUB_ID|TEAM_HUB_REACTIVATION_OPERATION_ID|TEAM_HUB_REACTIVATION_SNAPSHOT|TEAM_HUB_UPDATE_HUB_ID|TEAM_HUB_UPDATE_OPERATION_ID|TEAM_HUB_UPDATE_SNAPSHOT)|AGENTS_SERVER_(STATE_DIR|INSTALL_DIR|CONFIG_DIR|INSTANCE)|ZENITHBOT_AGENT_(DIR|CWD|BIND|PORT|TOKEN)|ZENITHDOCK_AGENT_TOKEN|PATH)=' \
      > "$env_temp"; then
      :
    else
      filter_status=$?
      [[ "$filter_status" == "1" ]] || return "$filter_status"
    fi
  else
    : > "$env_temp"
  fi
  if [[ -n "$SERVER_NAME" ]]; then
    local encoded_server_name=""
    encoded_server_name="$(runtime_env_server_name "$SERVER_NAME")" || return 1
    printf 'AGENTSDOCK_SERVER_NAME=%s\n' "$encoded_server_name" >> "$env_temp"
  fi
  cat >> "$env_temp" <<EOF
AGENTSDOCK_STATE_DIR=$STATE_ROOT
AGENTSDOCK_AGENT_CWD=$HOME
AGENTSDOCK_AGENT_BIND=$BIND_ADDRESS
AGENTSDOCK_AGENT_PORT=$PORT
AGENTSDOCK_AGENT_TOKEN=$TOKEN
AGENTSDOCK_TEAM_HUB_MODE=$TEAM_HUB_MODE
AGENTSDOCK_TEAM_HUB_TRANSPORT=$TEAM_HUB_TRANSPORT
AGENTSDOCK_TEAM_HUB_URL=$TEAM_HUB_URL
AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL=$TEAM_HUB_DIRECT_IP_URL
AGENTS_SERVER_INSTALL_DIR=$INSTALL_ROOT
AGENTS_SERVER_CONFIG_DIR=$CONFIG_ROOT
AGENTS_SERVER_INSTANCE=${INSTANCE_NAME:-default}
PATH=$SERVER_PATH
EOF
  if ! replace_activation_config env "$env_temp" 600; then
    return 1
  fi
  PRESERVE_SOURCE="$ENV_FILE"
}

launchd_target_snapshot() {
  local target="$1"
  local output=""
  local status=0
  if output="$(launchctl print "$target" 2>&1)"; then
    printf '%s\n' "loaded"
    return 0
  else
    status=$?
  fi
  case "$output" in
    *"Could not find service"*|*"service not found"*|*"No such process"*)
      printf '%s\n' "not-found"
      return 0
      ;;
  esac
  [[ -z "$output" ]] || printf '%s\n' "$output" >&2
  return "$status"
}

wait_for_launch_agent_removal() {
  local service_target="$1"
  local attempt
  for ((attempt = 1; attempt <= LAUNCHCTL_STOP_ATTEMPTS; attempt++)); do
    local state=""
    state="$(launchd_target_snapshot "$service_target")" || return 1
    [[ "$state" != "not-found" ]] || return 0
    sleep "$LAUNCHCTL_STOP_DELAY"
  done
  echo "Timed out waiting for $LABEL to stop." >&2
  return 1
}

transient_launchctl_bootstrap_error() {
  local status="$1"
  local output="$2"
  # launchctl collapses launchd's EALREADY into status 5 and this generic EIO text.
  [[ "$output" == *"Operation already in progress"* ]] || \
    { ((status == 5)) && [[ "$output" == *"Bootstrap failed: 5: Input/output error"* ]]; }
}

bootstrap_launch_agent() {
  local domain="$1"
  local service_target="$2"
  local allow_transient_retry="$3"
  local attempt=1
  local output=""
  local status=0

  while ((attempt <= LAUNCHCTL_BOOTSTRAP_ATTEMPTS)); do
    if output="$(launchctl bootstrap "$domain" "$PLIST" 2>&1)"; then
      [[ -z "$output" ]] || printf '%s\n' "$output"
      return 0
    else
      status=$?
    fi
    if [[ "$allow_transient_retry" != "true" ]] || \
      ! transient_launchctl_bootstrap_error "$status" "$output" || \
      ((attempt == LAUNCHCTL_BOOTSTRAP_ATTEMPTS)); then
      [[ -z "$output" ]] || printf '%s\n' "$output" >&2
      return "$status"
    fi
    wait_for_launch_agent_removal "$service_target" || return 1
    sleep "$LAUNCHCTL_STOP_DELAY"
    ((attempt += 1))
  done
  return "$status"
}

systemd_service_active_state() {
  systemctl --user show "$SERVICE_NAME.service" --property=ActiveState --value
}

managed_systemd_service_is_stopped() {
  local state=""
  state="$(systemd_service_active_state 2>/dev/null)" || return 1
  state="${state%%$'\n'*}"
  [[ "$state" == "inactive" || "$state" == "failed" ]]
}

wait_for_managed_systemd_stop() {
  local attempts="$1"
  local attempt=1
  local state=""
  while ((attempt <= attempts)); do
    if ! state="$(systemd_service_active_state 2>/dev/null)"; then
      return 1
    fi
    state="${state%%$'\n'*}"
    case "$state" in
      inactive|failed) return 0 ;;
      active|activating|deactivating|reloading) ;;
      *) return 1 ;;
    esac
    sleep "$SYSTEMD_MANAGED_STOP_DELAY"
    ((attempt += 1))
  done
  return 1
}

stop_managed_systemd_service_bounded() {
  # This path is reachable only from the authenticated managed updater after
  # AgentsServer closed work admission, retired idle provider supervisors,
  # proved an empty descendant set, and the installer proved it is outside the
  # exact service cgroup. Never use a broad process match here.
  systemctl --user stop --no-block "$SERVICE_NAME.service" || return
  if wait_for_managed_systemd_stop "$SYSTEMD_MANAGED_STOP_ATTEMPTS"; then
    return 0
  fi
  # Close the poll/kill race: the exact unit may have reached inactive after
  # the final timed poll. Never turn that normal completion into a false
  # updater failure or send a signal to a later state.
  if managed_systemd_service_is_stopped; then
    return 0
  fi
  echo "AgentsServer did not finish its bounded managed-update stop; terminating the exact drained service cgroup." >&2
  if ! systemctl --user kill \
      --kill-who=all \
      --signal=SIGKILL \
      "$SERVICE_NAME.service"; then
    # systemctl may race the unit's final transition and report that there is
    # nothing left to kill. An authoritative inactive state is success.
    managed_systemd_service_is_stopped || return
  fi
  if wait_for_managed_systemd_stop "$SYSTEMD_MANAGED_KILL_ATTEMPTS"; then
    return 0
  fi
  echo "AgentsServer did not reach a stopped state after exact-unit termination." >&2
  return 1
}

restart_managed_systemd_service_bounded() {
  stop_managed_systemd_service_bounded || return
  # Do not attach the updater to the service start job. The following
  # authenticated health check proves the candidate or enters rollback.
  systemctl --user start --no-block "$SERVICE_NAME.service"
}

restart_service() {
  if [[ "$OS_NAME" == "Linux" ]]; then
    if [[ "${INSTANCE_NAME:-default}" == "default" ]]; then
      local legacy_exists="false"
      local legacy_snapshot=""
      [[ -f "$LEGACY_SERVICE_FILE" && ! -L "$LEGACY_SERVICE_FILE" ]] \
        && legacy_exists="true"
      if [[ "$PRIOR_LEGACY_SERVICE_STATE" == "absent" ]]; then
        legacy_snapshot="$(systemd_unit_snapshot \
          "$LEGACY_SERVICE_NAME.service" "$legacy_exists")" || return 1
        [[ "${legacy_snapshot%%|*}" == "absent" ]] || return 1
      else
        systemctl --user disable --now "$LEGACY_SERVICE_NAME.service" \
          >/dev/null || return 1
        legacy_snapshot="$(systemd_unit_snapshot \
          "$LEGACY_SERVICE_NAME.service" "$legacy_exists")" || return 1
        [[ "${legacy_snapshot%%|*}" == "stopped" \
          && "${legacy_snapshot#*|}" == "false|"* ]] || return 1
      fi
    fi
    systemctl --user daemon-reload || return
    systemctl --user enable "$SERVICE_NAME.service" >/dev/null || return
    if [[ -n "$MANAGED_UPDATE_ID" ]]; then
      restart_managed_systemd_service_bounded
    else
      systemctl --user restart "$SERVICE_NAME.service"
    fi
  else
    local domain="gui/$(id -u)"
    local service_target="$domain/$LABEL"
    local had_service="false"
    local service_state=""
    local output=""
    local status=0
    service_state="$(launchd_target_snapshot "$service_target")" || return 1
    if [[ "$service_state" == "loaded" ]]; then
      had_service="true"
      # bootout acknowledges the request before launchd has removed the job.
      if output="$(launchctl bootout "$service_target" 2>&1)"; then
        [[ -z "$output" ]] || printf '%s\n' "$output"
      else
        status=$?
        service_state="$(launchd_target_snapshot "$service_target")" || return 1
        if [[ "$service_state" == "loaded" ]]; then
          [[ -z "$output" ]] || printf '%s\n' "$output" >&2
          return "$status"
        fi
      fi
      wait_for_launch_agent_removal "$service_target" || return 1
    fi
    # A persistent launchd disabled override survives bootout and makes
    # bootstrap fail. Candidate installation intentionally enables its unit;
    # rollback later restores the exact captured override.
    launchctl enable "$service_target" >/dev/null || return 1
    bootstrap_launch_agent "$domain" "$service_target" "$had_service"
  fi
}

restore_previous_release_transaction() {
  [[ -n "$ACTIVATION_TRANSACTION_ID" ]] || return 1
  if [[ "$ACTIVATION_TRANSACTION_PHASE" == "committing" \
    || "$ACTIVATION_TRANSACTION_PHASE" == "committed" ]]; then
    echo "The activation transaction passed its irreversible commit boundary; rollback is forbidden." >&2
    return 1
  fi

  if [[ "$ACTIVATION_TRANSACTION_PHASE" == "rollback-healthy" ]]; then
    finish_activation_transaction "$STAGE_DIR"
    return
  fi
  local rollback_from_phase="${ACTIVATION_ROLLBACK_FROM:-$ACTIVATION_TRANSACTION_PHASE}"
  local rollback_control_runtime="$CANDIDATE_RUNTIME_ROOT"
  if [[ "$rollback_from_phase" == "fencing" \
    && "$TEAM_HUB_COLD_GUARD_PENDING" == "true" \
    && "$TEAM_HUB_REACTIVATION_FENCE_PENDING" != "true" ]]; then
    # A crash can occur after the preflight CLI durably publishes its handoff
    # but before shell receives/adopts the result. The store returns that exact
    # resumable operation; adopt it before any rollback decision.
    TEAM_HUB_REACTIVATION_REQUESTED="true"
    if ! prepare_team_hub_reactivation; then
      echo "The interrupted Team Hub reactivation preflight could not be recovered." >&2
      return 1
    fi
  fi
  if [[ "$ACTIVATION_TRANSACTION_PHASE" != "rolling-back" ]]; then
    if [[ "$ACTIVATION_TRANSACTION_PHASE" == "fencing" \
      && "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
      TEAM_HUB_OPERATION_FENCE_DEVICE=""
      TEAM_HUB_OPERATION_FENCE_INODE=""
    fi
    if ! record_activation_phase rolling-back "$CANDIDATE_RUNTIME_ROOT"; then
      echo "The activation transaction could not durably enter rollback." >&2
      return 1
    fi
  fi

  if [[ "$ACTIVATION_TRANSACTION_PHASE" != "rolled-back" ]]; then
    case "$rollback_from_phase" in
      linking|linked|stopping|stopped|fencing|fenced|authorizing|authority)
      # The link can expose the candidate to an already-loaded service unit,
      # but a first install has no unit yet: treating that proven absence as a
      # stop failure would wedge otherwise recoverable pre-service rollback.
      if [[ "$PRIOR_SERVICE_STATE" == "absent" ]]; then
        :
      elif ! suppress_service_autostart_for_rollback; then
        echo "The service manager could not durably suppress candidate restart; rollback was not attempted." >&2
        return 1
      elif ! stop_service; then
        echo "The candidate service could not be stopped, so rollback was not attempted." >&2
        return 1
      fi
      ;;
      candidate-starting|candidate-healthy)
      if ! suppress_service_autostart_for_rollback; then
        echo "The service manager could not durably suppress candidate restart; rollback was not attempted." >&2
        return 1
      fi
      if ! stop_service; then
        echo "The candidate service could not be stopped, so rollback was not attempted." >&2
        return 1
      fi
      ;;
      *) ;;
    esac

    if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" \
      || "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
      if ! restore_team_hub_snapshot; then
        echo "The verified Team Hub snapshot could not be restored; the previous release was not started." >&2
        return 1
      fi
    fi
    if ! restore_activation_files "$CANDIDATE_RUNTIME_ROOT"; then
      echo "The Team Hub snapshot was restored, but the previous release configuration could not be restored." >&2
      return 1
    fi
    if [[ -x "$ACTIVATION_TRANSACTION_DIR/candidate.retired/.venv/bin/python" ]]; then
      rollback_control_runtime="$ACTIVATION_TRANSACTION_DIR/candidate.retired"
    elif [[ ! -x "$rollback_control_runtime/.venv/bin/python" ]]; then
      rollback_control_runtime="$STAGE_DIR"
    fi
    if [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]]; then
      local allow_missing_guard="false"
      case "$rollback_from_phase" in
        authority|candidate-starting|candidate-healthy) allow_missing_guard="true" ;;
      esac
      if ! clear_team_hub_cold_guard \
          "$rollback_control_runtime" "$allow_missing_guard"; then
        echo "The previous release was restored, but its exact startup guard could not be cleared." >&2
        return 1
      fi
    fi
    # The receipt itself remains the last Hub startup blocker.  Persist exact
    # release/configuration rollback before consuming it, so a crash cannot
    # expose the restored database through candidate links.
    if ! record_activation_phase rolled-back "$rollback_control_runtime"; then
      echo "Rollback files were restored, but their durable activation state was not recorded." >&2
      return 1
    fi
  fi

  if ! clear_team_hub_startup_authority "$rollback_control_runtime" true; then
    echo "The prior release was restored, but candidate startup authority could not be retired." >&2
    return 1
  fi
  TEAM_HUB_STARTUP_AUTHORITY_PENDING="false"
  TEAM_HUB_OPERATION_FINALIZED="true"
  TEAM_HUB_REACTIVATION_FINALIZED="true"
  TEAM_HUB_OPERATION_PENDING="false"
  TEAM_HUB_REACTIVATION_FENCE_PENDING="false"
  if ! acknowledge_team_hub_restore_receipt "$rollback_control_runtime" true; then
    echo "The restored Team Hub generation could not be acknowledged safely." >&2
    return 1
  fi

  case "$rollback_from_phase" in
    linking|linked|stopping|stopped|fencing|fenced|authorizing|authority)
    if [[ "$PRIOR_SERVICE_STATE" != "absent" ]]; then
      if ! restore_prior_service_state; then
        echo "The previous release configuration was restored, but its prior service state was not." >&2
        return 1
      fi
      if [[ "$PRIOR_SERVICE_STATE" == "running" ]] \
        && ! wait_for_previous_release_health; then
        echo "The previous service restarted, but its exact server and Team Hub identities were not healthy; rollback is incomplete." >&2
        return 1
      fi
    fi
    ;;
    candidate-starting|candidate-healthy)
    if ! restore_prior_service_state; then
      echo "The previous release configuration was restored, but its prior service state was not." >&2
      return 1
    fi
    if [[ "$PRIOR_SERVICE_STATE" == "running" ]]; then
      if ! wait_for_previous_release_health; then
        echo "The previous service restarted, but its exact server and Team Hub identities were not healthy; rollback is incomplete." >&2
        return 1
      fi
    elif [[ "$OS_NAME" == "Linux" \
      && "$PRIOR_SERVICE_STATE" == "absent" \
      && "$PRIOR_LEGACY_SERVICE_STATE" == "running" ]]; then
      if ! wait_for_legacy_release_health "$rollback_control_runtime"; then
        echo "The restored legacy service did not become authenticated and healthy." >&2
        return 1
      fi
    fi
    ;;
  esac
  if ! record_activation_phase rollback-healthy "$rollback_control_runtime" \
    || ! finish_activation_transaction "$rollback_control_runtime"; then
    echo "Rollback succeeded but its activation transaction could not be retired." >&2
    return 1
  fi
  return 0
}

restore_previous_release() {
  TEAM_HUB_RECOVERY_ATTEMPTED="true"
  mask_install_signals
  local status=0
  if restore_previous_release_transaction; then
    status=0
  else
    status=$?
  fi
  if [[ "$IN_EXIT_CLEANUP" != "true" ]]; then
    resume_install_signals
  fi
  return "$status"
}

stop_service() {
  if [[ "$OS_NAME" == "Linux" ]]; then
    if [[ -n "$MANAGED_UPDATE_ID" ]]; then
      stop_managed_systemd_service_bounded
    else
      systemctl --user stop "$SERVICE_NAME.service"
    fi
    return
  fi
  local domain="gui/$(id -u)"
  local service_target="$domain/$LABEL"
  local service_state=""
  local output=""
  local status=0
  service_state="$(launchd_target_snapshot "$service_target")" || return 1
  if [[ "$service_state" == "not-found" ]]; then
    return 0
  fi
  if output="$(launchctl bootout "$service_target" 2>&1)"; then
    [[ -z "$output" ]] || printf '%s\n' "$output"
  else
    status=$?
    service_state="$(launchd_target_snapshot "$service_target")" || return 1
    if [[ "$service_state" == "loaded" ]]; then
      [[ -z "$output" ]] || printf '%s\n' "$output" >&2
      return "$status"
    fi
  fi
  wait_for_launch_agent_removal "$service_target"
}

suppress_service_autostart_for_rollback() {
  # Keep the rollback exclusion in the service manager, not only in the new
  # runtime.  An older release may not recognize the restore receipt; this
  # durable disable prevents reboot/autorestart between file restoration and
  # the journal's rolled-back boundary from opening the restored Hub.
  if [[ "$OS_NAME" == "Linux" ]]; then
    systemctl --user disable "$SERVICE_NAME.service" >/dev/null || return 1
  else
    launchctl disable "gui/$(id -u)/$LABEL" >/dev/null || return 1
  fi
}

restore_prior_service_state() {
  # Links and configuration have already been restored from the journal. Keep
  # the pre-install running/enabled state exact; a failed first install must
  # not leave its candidate running, and a previously stopped service must not
  # be started merely because rollback succeeded.
  if [[ "$OS_NAME" == "Linux" ]]; then
    systemctl --user daemon-reload || return 1
    if [[ "$PRIOR_SERVICE_ENABLED" == "true" ]]; then
      systemctl --user enable "$SERVICE_NAME.service" >/dev/null || return 1
    elif [[ "$PRIOR_SERVICE_STATE" == "absent" ]]; then
      systemctl --user disable "$SERVICE_NAME.service" >/dev/null 2>&1 || true
    else
      systemctl --user disable "$SERVICE_NAME.service" >/dev/null || return 1
    fi
    if [[ "$PRIOR_SERVICE_STATE" == "running" ]]; then
      if [[ -n "$MANAGED_UPDATE_ID" ]]; then
        systemctl --user start --no-block "$SERVICE_NAME.service" || return 1
      else
        systemctl --user start "$SERVICE_NAME.service" || return 1
      fi
      :
    else
      systemctl --user stop "$SERVICE_NAME.service" >/dev/null 2>&1 || {
        [[ "$PRIOR_SERVICE_STATE" == "absent" ]] || return 1
      }
    fi
    if [[ "${INSTANCE_NAME:-default}" == "default" ]]; then
      if [[ "$PRIOR_LEGACY_SERVICE_ENABLED" == "true" ]]; then
        systemctl --user enable "$LEGACY_SERVICE_NAME.service" >/dev/null || return 1
      elif [[ "$PRIOR_LEGACY_SERVICE_STATE" == "absent" ]]; then
        systemctl --user disable "$LEGACY_SERVICE_NAME.service" >/dev/null 2>&1 || true
      else
        systemctl --user disable "$LEGACY_SERVICE_NAME.service" >/dev/null || return 1
      fi
      if [[ "$PRIOR_LEGACY_SERVICE_STATE" == "running" ]]; then
        systemctl --user start "$LEGACY_SERVICE_NAME.service" || return 1
      else
        systemctl --user stop "$LEGACY_SERVICE_NAME.service" >/dev/null 2>&1 || {
          [[ "$PRIOR_LEGACY_SERVICE_STATE" == "absent" ]] || return 1
        }
      fi
    fi
    local current_exists="false"
    local legacy_exists="false"
    local observed_snapshot=""
    [[ -f "$SYSTEMD_SERVICE_FILE" && ! -L "$SYSTEMD_SERVICE_FILE" ]] \
      && current_exists="true"
    [[ -f "$LEGACY_SERVICE_FILE" && ! -L "$LEGACY_SERVICE_FILE" ]] \
      && legacy_exists="true"
    if [[ "$PRIOR_SERVICE_STATE" != "running" ]]; then
      observed_snapshot="$(systemd_unit_snapshot \
        "$SERVICE_NAME.service" "$current_exists")" || return 1
      [[ "${observed_snapshot%%|*}" == "$PRIOR_SERVICE_STATE" \
        && "${observed_snapshot#*|}" == "$PRIOR_SERVICE_ENABLED|"* ]] \
        || return 1
    fi
    if [[ "${INSTANCE_NAME:-default}" == "default" && "$PRIOR_LEGACY_SERVICE_STATE" != "running" ]]; then
      observed_snapshot="$(systemd_unit_snapshot \
        "$LEGACY_SERVICE_NAME.service" "$legacy_exists")" || return 1
      [[ "${observed_snapshot%%|*}" == "$PRIOR_LEGACY_SERVICE_STATE" \
        && "${observed_snapshot#*|}" == "$PRIOR_LEGACY_SERVICE_ENABLED|"* ]] \
        || return 1
    fi
    return 0
  fi

  local domain="gui/$(id -u)"
  local service_target="$domain/$LABEL"
  local launchd_state=""
  if [[ "$PRIOR_SERVICE_STATE" == "running" ]]; then
    # launchd refuses both bootstrap and kickstart while a persistent disabled
    # override is set. Temporarily enable, restore the running job, then put a
    # deliberately disabled-but-running prior state back exactly.
    launchctl enable "$service_target" >/dev/null || return 1
    launchd_state="$(launchd_target_snapshot "$service_target")" || return 1
    if [[ "$launchd_state" == "loaded" ]]; then
      launchctl kickstart -k "$service_target" >/dev/null || return 1
    else
      bootstrap_launch_agent "$domain" "$service_target" false || return 1
    fi
    if [[ "$PRIOR_SERVICE_ENABLED" != "true" ]]; then
      launchctl disable "$service_target" >/dev/null || return 1
    fi
    return 0
  fi
  if [[ "$PRIOR_SERVICE_ENABLED" == "true" ]]; then
    launchctl enable "$service_target" >/dev/null || return 1
  else
    launchctl disable "$service_target" >/dev/null || return 1
  fi
  stop_service || return 1
  launchd_state="$(launchd_target_snapshot "$service_target")" || return 1
  [[ "$launchd_state" == "not-found" ]]
}

restore_team_hub_snapshot() {
  if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
    local reactivation_python="$CANDIDATE_RUNTIME_ROOT/.venv/bin/python"
    if [[ ! -x "$reactivation_python" ]]; then
      echo "The candidate runtime cannot restore the Team Hub reactivation snapshot." >&2
      return 1
    fi
    echo "      Restoring the verified pre-reactivation Team Hub snapshot"
    if run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
      "$reactivation_python" -m agentsdock_team_hub.cli \
      restore-host-reactivation-snapshot \
      --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
      --snapshot "$TEAM_HUB_REACTIVATION_SNAPSHOT" \
      --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
      --expected-hub-id "$TEAM_HUB_REACTIVATION_HUB_ID" \
      --expected-operation-id "$TEAM_HUB_REACTIVATION_OPERATION_ID"; then
      return 0
    fi
    echo "      Verifying a previously completed reactivation restore"
    run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" \
      "$reactivation_python" -m agentsdock_team_hub.cli \
      confirm-restored-host-reactivation-snapshot \
      --data-dir "$TEAM_HUB_CANONICAL_DATA_DIR" \
      --snapshot "$TEAM_HUB_REACTIVATION_SNAPSHOT" \
      --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
      --expected-hub-id "$TEAM_HUB_REACTIVATION_HUB_ID" \
      --expected-operation-id "$TEAM_HUB_REACTIVATION_OPERATION_ID"
    return
  fi
  [[ -n "$EXPECTED_TEAM_HUB_ID" ]] || return 0
  local restore_python="$CANDIDATE_RUNTIME_ROOT/.venv/bin/python"
  if [[ ! -x "$restore_python" ]]; then
    echo "The candidate runtime cannot verify the Team Hub rollback snapshot." >&2
    return 1
  fi
  echo "      Restoring the verified Team Hub maintenance snapshot"
  if run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" "$restore_python" -m agentsdock_team_hub.cli \
      restore-snapshot \
      --data-dir "$TEAM_HUB_DATA_DIR" \
      --snapshot "$TEAM_HUB_SNAPSHOT" \
      --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
      --expected-hub-id "$EXPECTED_TEAM_HUB_ID" \
      --expected-operation-id "$TEAM_HUB_OPERATION_ID"; then
    return 0
  fi
  echo "      Verifying a previously completed maintenance restore"
  run_without_server_secrets env PYTHONPATH="$CANDIDATE_RUNTIME_ROOT" "$restore_python" -m agentsdock_team_hub.cli \
    confirm-restored-snapshot \
    --data-dir "$TEAM_HUB_DATA_DIR" \
    --snapshot "$TEAM_HUB_SNAPSHOT" \
    --expected-host-identity "$EXPECTED_SERVER_IDENTITY" \
    --expected-hub-id "$EXPECTED_TEAM_HUB_ID" \
    --expected-operation-id "$TEAM_HUB_OPERATION_ID"
}

acknowledge_team_hub_restore_receipt() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  local allow_missing="${2:-false}"
  local command=""
  local data_dir=""
  local snapshot=""
  local hub_id=""
  local operation_id=""
  case "$ACTIVATION_HUB_KIND" in
    host-reactivation)
      command="acknowledge-restored-host-reactivation-snapshot"
      data_dir="$TEAM_HUB_CANONICAL_DATA_DIR"
      snapshot="$TEAM_HUB_REACTIVATION_SNAPSHOT"
      hub_id="$TEAM_HUB_REACTIVATION_HUB_ID"
      operation_id="$TEAM_HUB_REACTIVATION_OPERATION_ID"
      ;;
    server-update)
      command="acknowledge-restored-snapshot"
      data_dir="$TEAM_HUB_DATA_DIR"
      snapshot="$TEAM_HUB_SNAPSHOT"
      hub_id="$EXPECTED_TEAM_HUB_ID"
      operation_id="$TEAM_HUB_OPERATION_ID"
      ;;
    "") return 0 ;;
    *) return 1 ;;
  esac
  local arguments=(
    "$command"
    --data-dir "$data_dir"
    --snapshot "$snapshot"
    --expected-host-identity "$EXPECTED_SERVER_IDENTITY"
    --expected-hub-id "$hub_id"
    --expected-operation-id "$operation_id"
  )
  [[ "$allow_missing" != "true" ]] || arguments+=(--allow-missing)
  run_without_server_secrets env PYTHONPATH="$runtime_root" \
    "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
    "${arguments[@]}" >/dev/null
}

port_has_listener() {
  local port="$1"
  # Keep the probe in a subshell so both the socket descriptor and diagnostic
  # redirection are scoped to this check. A bare `exec ... 2>/dev/null` here
  # would permanently silence the installer's stderr after the first probe.
  (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null || return 1
  return 0
}

describe_port_listener() {
  local port="$1"
  command -v lsof >/dev/null 2>&1 || return 0
  lsof -nP -iTCP:"$port" -sTCP:LISTEN 2>/dev/null | awk 'NR>1 {print "  " $1 " (pid " $2 ")"}' | sort -u
}

write_service_files() {
  local service_temp=""
  if [[ "$OS_NAME" == "Linux" ]]; then
    USER_SERVICE_DIR="$HOME/.config/systemd/user"
    mkdir -p "$USER_SERVICE_DIR"
    service_temp="$USER_SERVICE_DIR/.$SERVICE_NAME.service.activation-$ACTIVATION_TRANSACTION_ID-service.source"
    (umask 077; set -o noclobber; : > "$service_temp") 2>/dev/null || return 1
    chmod 600 "$service_temp" || return 1
    cat > "$service_temp" <<EOF
[Unit]
Description=AgentsServer
After=network-online.target

[Service]
Type=simple
WorkingDirectory=$CURRENT_LINK
EnvironmentFile=$ENV_FILE
ExecStart=$CURRENT_LINK/.venv/bin/python $CURRENT_LINK/agent_server.py serve --bind $BIND_ADDRESS --port $PORT
Restart=always
RestartSec=2
# Shutdown normally completes in under a second after provider admission is
# drained. Bound orphaned cgroup descendants so even a legacy updater invoking
# synchronous systemctl restart cannot be stranded behind systemd's 90s
# default. New managed updaters use the stricter external stop/start path too.
TimeoutStopSec=10s
# Keep the coordinator alive long enough to record/recover agent failures
# when systemd-oomd must choose among pressured user services. Provider
# subprocesses remain in this cgroup and are stopped with the service.
ManagedOOMPreference=avoid

[Install]
WantedBy=default.target
EOF
    if ! replace_activation_config service "$service_temp" 644; then
      return 1
    fi
    SERVICE_KIND="systemd-user"
  elif [[ "$OS_NAME" == "Darwin" ]]; then
    LAUNCH_AGENTS="$HOME/Library/LaunchAgents"
    local instance_log_dir="${INSTANCE_LOG_DIR:-$HOME/Library/Logs/AgentsServer}"
    mkdir -p "$LAUNCH_AGENTS" "$instance_log_dir"
    service_temp="$LAUNCH_AGENTS/.$LABEL.plist.activation-$ACTIVATION_TRANSACTION_ID-service.source"
    (umask 077; set -o noclobber; : > "$service_temp") 2>/dev/null || return 1
    chmod 600 "$service_temp" || return 1
    local launchd_server_name_entry=""
    if [[ -n "$SERVER_NAME" ]]; then
      local escaped_server_name=""
      escaped_server_name="$(xml_server_name "$SERVER_NAME")" || return 1
      launchd_server_name_entry="    <key>AGENTSDOCK_SERVER_NAME</key><string>$escaped_server_name</string>"
    fi
    cat > "$service_temp" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>$LABEL</string>
  <key>ProgramArguments</key><array>
    <string>$CURRENT_LINK/.venv/bin/python</string>
    <string>$CURRENT_LINK/agent_server.py</string>
    <string>serve</string><string>--bind</string><string>$BIND_ADDRESS</string>
    <string>--port</string><string>$PORT</string>
  </array>
  <key>WorkingDirectory</key><string>$CURRENT_LINK</string>
  <key>EnvironmentVariables</key><dict>
    <key>AGENTSDOCK_STATE_DIR</key><string>$STATE_ROOT</string>
    <key>AGENTSDOCK_AGENT_CWD</key><string>$HOME</string>
    <key>AGENTSDOCK_AGENT_BIND</key><string>$BIND_ADDRESS</string>
    <key>AGENTSDOCK_AGENT_PORT</key><string>$PORT</string>
    <key>AGENTSDOCK_AGENT_TOKEN</key><string>$TOKEN</string>
$launchd_server_name_entry
    <key>AGENTSDOCK_TEAM_HUB_MODE</key><string>$TEAM_HUB_MODE</string>
    <key>AGENTSDOCK_TEAM_HUB_TRANSPORT</key><string>$TEAM_HUB_TRANSPORT</string>
    <key>AGENTSDOCK_TEAM_HUB_URL</key><string>$TEAM_HUB_URL</string>
    <key>AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL</key><string>$TEAM_HUB_DIRECT_IP_URL</string>
    <key>AGENTS_SERVER_INSTALL_DIR</key><string>$INSTALL_ROOT</string>
    <key>AGENTS_SERVER_CONFIG_DIR</key><string>$CONFIG_ROOT</string>
    <key>AGENTS_SERVER_INSTANCE</key><string>${INSTANCE_NAME:-default}</string>
    <key>PATH</key><string>$SERVER_PATH</string>
  </dict>
  <key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>$instance_log_dir/server.log</string>
  <key>StandardErrorPath</key><string>$instance_log_dir/server-error.log</string>
</dict></plist>
EOF
    if ! replace_activation_config service "$service_temp" 600; then
      return 1
    fi
    SERVICE_KIND="launch-agent"
  else
    echo "Unsupported host OS: $OS_NAME" >&2
    exit 1
  fi
}

HEALTH_CHECK_HEARTBEAT_ATTEMPTS=5

health_host_for_bind() {
  local selected_bind="${1:-$BIND_ADDRESS}"
  case "$selected_bind" in
    0.0.0.0|localhost) printf '%s\n' "127.0.0.1" ;;
    ::|"[::]"|::1|"[::1]") printf '%s\n' "::1" ;;
    *) printf '%s\n' "$selected_bind" ;;
  esac
}

health_origin() {
  local port="$1"
  local host=""
  host="$(health_host_for_bind)" || return 1
  if [[ "$host" == *:* ]]; then
    printf 'http://[%s]:%s\n' "$host" "$port"
  else
    printf 'http://%s:%s\n' "$host" "$port"
  fi
}

service_manager_main_pid() {
  local service="$1"
  local value=""
  if [[ "$OS_NAME" == "Darwin" ]]; then
    value="$(launchctl print "gui/$(id -u)/$service" 2>/dev/null \
      | sed -n 's/^[[:space:]]*pid = \([0-9][0-9]*\);*$/\1/p' \
      | tail -n 1)" || return 1
  else
    value="$(systemctl --user show "$service.service" \
      --property=MainPID --value 2>/dev/null)" || return 1
  fi
  [[ "$value" =~ ^[1-9][0-9]*$ ]] || return 1
  printf '%s\n' "$value"
}

process_owns_listener() {
  local pid="$1"
  local port="$2"
  local runtime_root="$3"
  local host=""
  host="$(health_host_for_bind)" || return 1
  if command -v lsof >/dev/null 2>&1; then
    lsof -nP -a -p "$pid" -iTCP:"$port" -sTCP:LISTEN 2>/dev/null \
      | awk -v expected="$pid" -v host="$host" -v port="$port" '
          NR > 1 && $2 == expected {
            endpoint = $(NF - 1)
            if (endpoint == "*:" port || endpoint == host ":" port \
                || endpoint == "[" host "]:" port) found = 1
          }
          END { exit !found }
        '
    return
  fi
  [[ "$OS_NAME" == "Linux" && -x "$runtime_root/.venv/bin/python" ]] || return 1
  run_without_server_secrets "$runtime_root/.venv/bin/python" - \
    "$pid" "$port" "$host" <<'PY'
import os
from pathlib import Path
import ipaddress
import socket
import sys

pid = int(sys.argv[1])
port = int(sys.argv[2])
expected_host = ipaddress.ip_address(sys.argv[3])
socket_inodes = set()
for entry in (Path("/proc") / str(pid) / "fd").iterdir():
    try:
        target = os.readlink(entry)
    except OSError:
        continue
    if target.startswith("socket:[") and target.endswith("]"):
        socket_inodes.add(target[8:-1])
if not socket_inodes:
    raise SystemExit(1)
for table in (Path("/proc/net/tcp"), Path("/proc/net/tcp6")):
    try:
        lines = table.read_text(encoding="ascii").splitlines()[1:]
    except OSError:
        continue
    for line in lines:
        fields = line.split()
        if len(fields) < 10 or fields[3] != "0A":
            continue
        try:
            raw_address, raw_port = fields[1].rsplit(":", 1)
            local_port = int(raw_port, 16)
            packed = bytes.fromhex(raw_address)
            if table.name == "tcp":
                local_address = ipaddress.ip_address(packed[::-1])
            else:
                # /proc/net/tcp6 stores four little-endian 32-bit words.
                packed = b"".join(
                    packed[offset : offset + 4][::-1]
                    for offset in range(0, 16, 4)
                )
                local_address = ipaddress.ip_address(packed)
        except (IndexError, ValueError):
            continue
        if (
            local_port == port
            and fields[9] in socket_inodes
            and (local_address.is_unspecified or local_address == expected_host)
        ):
            raise SystemExit(0)
raise SystemExit(1)
PY
}

service_manager_owns_listener() {
  local port="$1"
  local runtime_root="$2"
  local service=""
  local pid=""
  local -a services=()
  if [[ "$OS_NAME" == "Darwin" ]]; then
    services=("$LABEL")
  else
    services=("$SERVICE_NAME")
    [[ "${INSTANCE_NAME:-default}" != "default" ]] || services+=("${LEGACY_SERVICE_NAME:-}")
  fi
  for service in "${services[@]}"; do
    [[ -n "$service" ]] || continue
    pid="$(service_manager_main_pid "$service")" || continue
    if process_owns_listener "$pid" "$port" "$runtime_root"; then
      return 0
    fi
  done
  return 1
}

# Open the local HTTP connection first, prove that the exact accepted socket
# belongs to the service-manager MainPID while that connection remains open,
# and only then read/send the administrator token.  A separate LISTEN check is
# insufficient: the managed process could exit and an unrelated process could
# bind the port before a separate HTTP client transmits the token.
pinned_managed_http_get() {
  local port="$1"
  local path="$2"
  local authorization_kind="$3"
  local output_file="$4"
  local runtime_root="$5"
  local selected_bind="${6:-$BIND_ADDRESS}"
  local host=""
  local service=""
  local pid=""
  local -a services=()
  host="$(health_host_for_bind "$selected_bind")" || return 1
  [[ "$path" == /* && "$path" != *$'\n'* && "$path" != *$'\r'* ]] || return 1
  case "$authorization_kind" in
    core|secure-peer) ;;
    *) return 1 ;;
  esac
  [[ -x "$runtime_root/.venv/bin/python" ]] || return 1
  if [[ "$OS_NAME" == "Darwin" ]]; then
    services=("$LABEL")
  else
    services=("$SERVICE_NAME")
    [[ "${INSTANCE_NAME:-default}" != "default" ]] || services+=("${LEGACY_SERVICE_NAME:-}")
  fi
  for service in "${services[@]}"; do
    [[ -n "$service" ]] || continue
    pid="$(service_manager_main_pid "$service")" || continue
    if run_without_server_secrets "$runtime_root/.venv/bin/python" - \
        "$OS_NAME" "$pid" "$host" "$port" "$path" \
        "$authorization_kind" "$output_file" 3<<<"$TOKEN" <<'PY'
import ipaddress
import os
from pathlib import Path
import socket
import stat
import subprocess
import sys
import time


MAXIMUM_BODY = 1024 * 1024
MAXIMUM_HEADERS = 64 * 1024
DEADLINE_SECONDS = 2.0


def fail():
    raise SystemExit(1)


def address_from_proc(raw, ipv6):
    packed = bytes.fromhex(raw)
    if not ipv6:
        packed = packed[::-1]
    else:
        packed = b"".join(
            packed[offset : offset + 4][::-1]
            for offset in range(0, 16, 4)
        )
    return ipaddress.ip_address(packed)


def linux_connection_owned(pid, server, client):
    inodes = set()
    try:
        entries = (Path("/proc") / str(pid) / "fd").iterdir()
        for entry in entries:
            try:
                target = os.readlink(entry)
            except OSError:
                continue
            if target.startswith("socket:[") and target.endswith("]"):
                inodes.add(target[8:-1])
    except OSError:
        return False
    if not inodes:
        return False
    expected_server = (ipaddress.ip_address(server[0]), int(server[1]))
    expected_client = (ipaddress.ip_address(client[0]), int(client[1]))
    for table, ipv6 in ((Path("/proc/net/tcp"), False), (Path("/proc/net/tcp6"), True)):
        try:
            lines = table.read_text(encoding="ascii").splitlines()[1:]
        except OSError:
            continue
        for line in lines:
            fields = line.split()
            if len(fields) < 10 or fields[3] != "01" or fields[9] not in inodes:
                continue
            try:
                local_address, local_port = fields[1].rsplit(":", 1)
                remote_address, remote_port = fields[2].rsplit(":", 1)
                observed_server = (
                    address_from_proc(local_address, ipv6),
                    int(local_port, 16),
                )
                observed_client = (
                    address_from_proc(remote_address, ipv6),
                    int(remote_port, 16),
                )
            except (IndexError, ValueError):
                continue
            if observed_server == expected_server and observed_client == expected_client:
                return True
    return False


def parse_lsof_endpoint(value):
    value = value.strip().split(None, 1)[0]
    if value.startswith("["):
        closing = value.find("]:")
        if closing < 0:
            raise ValueError
        host = value[1:closing]
        port = value[closing + 2 :]
    else:
        host, port = value.rsplit(":", 1)
    return ipaddress.ip_address(host), int(port)


def darwin_connection_owned(pid, server, client, timeout):
    try:
        result = subprocess.run(
            [
                "/usr/sbin/lsof",
                "-nP",
                "-a",
                "-p",
                str(pid),
                "-iTCP",
                "-sTCP:ESTABLISHED",
                "-Fn",
            ],
            stdin=subprocess.DEVNULL,
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            timeout=max(0.05, timeout),
            check=False,
            env={"PATH": "/usr/bin:/bin:/usr/sbin:/sbin", "LC_ALL": "C"},
        )
    except (OSError, subprocess.SubprocessError):
        return False
    if result.returncode != 0:
        return False
    expected_server = (ipaddress.ip_address(server[0]), int(server[1]))
    expected_client = (ipaddress.ip_address(client[0]), int(client[1]))
    for raw_line in result.stdout.decode("ascii", "strict").splitlines():
        if not raw_line.startswith("n") or "->" not in raw_line:
            continue
        try:
            local, remote = raw_line[1:].split("->", 1)
            if (
                parse_lsof_endpoint(local) == expected_server
                and parse_lsof_endpoint(remote) == expected_client
            ):
                return True
        except (UnicodeError, ValueError):
            continue
    return False


def receive_response(connection, deadline):
    payload = bytearray()
    header_end = -1
    while header_end < 0:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            fail()
        connection.settimeout(remaining)
        chunk = connection.recv(min(64 * 1024, MAXIMUM_HEADERS + 4 - len(payload)))
        if not chunk:
            fail()
        payload.extend(chunk)
        if len(payload) > MAXIMUM_HEADERS:
            fail()
        header_end = payload.find(b"\r\n\r\n")
    raw_headers = bytes(payload[:header_end])
    body = bytearray(payload[header_end + 4 :])
    try:
        lines = raw_headers.decode("latin-1").split("\r\n")
    except UnicodeError:
        fail()
    status_parts = lines[0].split(" ", 2) if lines else []
    if (
        len(status_parts) < 2
        or status_parts[0] not in ("HTTP/1.0", "HTTP/1.1")
        or status_parts[1] != "200"
    ):
        fail()
    headers = {}
    for line in lines[1:]:
        if not line or line[:1] in " \t" or ":" not in line:
            fail()
        name, value = line.split(":", 1)
        name = name.strip().lower()
        value = value.strip()
        if not name or name in headers:
            fail()
        headers[name] = value
    if "transfer-encoding" in headers:
        fail()
    content_length = None
    if "content-length" in headers:
        try:
            content_length = int(headers["content-length"], 10)
        except ValueError:
            fail()
        if content_length < 0 or content_length > MAXIMUM_BODY:
            fail()
    if len(body) > MAXIMUM_BODY or (
        content_length is not None and len(body) > content_length
    ):
        fail()
    while content_length is None or len(body) < content_length:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            fail()
        connection.settimeout(remaining)
        chunk = connection.recv(min(64 * 1024, MAXIMUM_BODY + 1 - len(body)))
        if not chunk:
            break
        body.extend(chunk)
        if len(body) > MAXIMUM_BODY:
            fail()
    if content_length is not None and len(body) != content_length:
        fail()
    return bytes(body)


def write_output(path, payload):
    flags = os.O_WRONLY | getattr(os, "O_CLOEXEC", 0)
    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
    descriptor = os.open(path, flags)
    try:
        before = os.fstat(descriptor)
        linked = Path(path).lstat()
        if (
            not stat.S_ISREG(before.st_mode)
            or before.st_uid != os.geteuid()
            or before.st_nlink != 1
            or stat.S_IMODE(before.st_mode) & 0o077
            or (before.st_dev, before.st_ino) != (linked.st_dev, linked.st_ino)
        ):
            fail()
        os.ftruncate(descriptor, 0)
        view = memoryview(payload)
        while view:
            written = os.write(descriptor, view)
            if written <= 0:
                fail()
            view = view[written:]
        os.fsync(descriptor)
    finally:
        os.close(descriptor)


def main():
    os_name, raw_pid, host, raw_port, path, authorization_kind, output = sys.argv[1:]
    pid = int(raw_pid)
    port = int(raw_port)
    if pid <= 0 or not 1 <= port <= 65535:
        fail()
    deadline = time.monotonic() + DEADLINE_SECONDS
    remaining = deadline - time.monotonic()
    connection = socket.create_connection((host, port), timeout=remaining)
    try:
        server = connection.getpeername()[:2]
        client = connection.getsockname()[:2]
        owned = False
        while time.monotonic() < deadline:
            remaining = deadline - time.monotonic()
            if os_name == "Linux":
                owned = linux_connection_owned(pid, server, client)
            elif os_name == "Darwin":
                owned = darwin_connection_owned(pid, server, client, remaining)
            else:
                fail()
            if owned:
                break
            time.sleep(min(0.01, max(0.0, deadline - time.monotonic())))
        if not owned:
            fail()
        token_parts = []
        token_size = 0
        while token_size <= 4096:
            chunk = os.read(3, min(4097 - token_size, 4096))
            if not chunk:
                break
            token_parts.append(chunk)
            token_size += len(chunk)
        token = b"".join(token_parts)
        if token.endswith(b"\n"):
            token = token[:-1]
        if (
            len(token) < 32
            or len(token) > 4096
            or any(character not in b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-" for character in token)
        ):
            fail()
        if authorization_kind == "core":
            header_name = b"Authorization"
            header_value = b"Bearer " + token
        else:
            header_name = b"X-AgentsDock-Token"
            header_value = token
        host_header = f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
        request = (
            b"GET "
            + path.encode("ascii", "strict")
            + b" HTTP/1.1\r\nHost: "
            + host_header.encode("ascii", "strict")
            + b"\r\n"
            + header_name
            + b": "
            + header_value
            + b"\r\nAccept: application/json\r\nConnection: close\r\n\r\n"
        )
        connection.settimeout(max(0.001, deadline - time.monotonic()))
        connection.sendall(request)
        response = receive_response(connection, deadline)
    finally:
        connection.close()
    write_output(output, response)


try:
    main()
except (Exception, OSError, UnicodeError, ValueError):
    raise SystemExit(1)
PY
    then
      return 0
    fi
  done
  return 1
}

health_check_once() {
  local port="$1"
  local origin=""
  origin="$(health_origin "$port")" || return 1
  if command -v curl >/dev/null 2>&1 && curl --version >/dev/null 2>&1; then
    # This probe may be talking to an unrelated occupied port. Never disclose
    # the preserved administrator token until service-manager/socket ownership
    # has been proven by the exact health path below.
    if curl -q --fail --silent --show-error --connect-timeout 1 --max-time 2 \
      --noproxy '*' --proto '=http' --max-redirs 0 \
      "$origin/api/health" >/dev/null 2>&1; then
      return 0
    fi
  fi
  return 1
}

fetch_managed_json() {
  local port="$1"
  local path="$2"
  local authorization_kind="$3"
  local output_file="$4"
  local runtime_root="$5"
  local selected_bind="${6:-$BIND_ADDRESS}"
  pinned_managed_http_get \
    "$port" "$path" "$authorization_kind" "$output_file" "$runtime_root" \
    "$selected_bind"
}

managed_secure_peer_binding_from_responses() {
  local runtime_root="$1"
  local health_file="$2"
  local status_file="$3"
  local expected_server="$4"
  local allow_legacy="${5:-false}"
  local health_size=""
  local status_size=""
  health_size="$(wc -c < "$health_file" 2>/dev/null || true)"
  health_size="${health_size//[[:space:]]/}"
  status_size="$(wc -c < "$status_file" 2>/dev/null || true)"
  status_size="${status_size//[[:space:]]/}"
  if [[ ! "$health_size" =~ ^[0-9]+$ ]] || ((health_size < 2 || health_size > 1048576)); then
    return 1
  fi
  if [[ ! "$status_size" =~ ^[0-9]+$ ]] || ((status_size > 1048576)); then
    return 1
  fi
  run_without_server_secrets "$runtime_root/.venv/bin/python" - \
    "$health_file" \
    "$status_file" \
    "$expected_server" \
    "$allow_legacy" <<'PY'
import json
import re
import sys
import uuid

health_path, status_path, expected_server, allow_legacy = sys.argv[1:]


def load_json(path):
    try:
        with open(path, "rb") as stream:
            return json.load(stream)
    except (OSError, UnicodeError, json.JSONDecodeError):
        raise SystemExit(1)


def exact_values(value, expected):
    return isinstance(value, dict) and all(
        value.get(key) == item for key, item in expected.items()
    )


def valid_identifier(value):
    return (
        isinstance(value, str)
        and re.fullmatch(r"[A-Za-z0-9_.:-]{8,240}", value) is not None
    )


def valid_uuid4(value):
    if not isinstance(value, str):
        return False
    try:
        parsed = uuid.UUID(value)
    except (ValueError, AttributeError):
        return False
    return parsed.version == 4 and str(parsed) == value


disabled_capability = {
    "available": False,
    "designated_host": False,
    "version": 1,
    "base_path": None,
    "hub_id": None,
    "host_server_identity": None,
    "transport": None,
    "hub_url": None,
}
health = load_json(health_path)
if not isinstance(health, dict) or health.get("ok") is not True:
    raise SystemExit(1)
if health.get("server_identity") != expected_server:
    raise SystemExit(1)
capabilities = health.get("capabilities")
team_hub = capabilities.get("team_hub_v1") if isinstance(capabilities, dict) else None
if not isinstance(team_hub, dict) or team_hub.get("designated_host") is not False:
    raise SystemExit(1)
secure_peer = capabilities.get("secure_peer_v1")
if secure_peer is None:
    if allow_legacy != "true" or not exact_values(team_hub, disabled_capability):
        raise SystemExit(1)
    print('{"kind":"disabled"}')
    raise SystemExit(0)
secure_required = {
    "available": True,
    "state_available": True,
    "state_error_code": None,
    "required": False,
    "version": 1,
    "control_path": "/api/admin/secure-peers/v1/status",
    "proxy_prefix": "/api/team-hub-secure",
}
if not exact_values(secure_peer, secure_required):
    raise SystemExit(1)

status = load_json(status_path)
status_version = status.get("version") if isinstance(status, dict) else None
if (
    not isinstance(status, dict)
    or status_version not in {1, 2}
    or status.get("server_identity") != expected_server
    or "active_connection_id" not in status
    or not isinstance(status.get("pairings"), list)
):
    raise SystemExit(1)
active_connection_id = status.get("active_connection_id")
if active_connection_id is not None and not valid_uuid4(active_connection_id):
    raise SystemExit(1)
fingerprint = re.compile(r"sha256:[0-9a-f]{64}")
known_statuses = {
    "requesting",
    "pending_approval",
    "approved",
    "connected",
    "rejected",
    "revoked",
    "expired",
    "error",
}
trust_statuses = {
    "pending": {"requesting", "pending_approval"},
    "approved": {"approved", "connected"},
    "rejected": {"rejected"},
    "cancelled": {"rejected"},
    "revoked": {"revoked"},
    "expired": {"expired"},
    "error": {"error"},
}
known_transport_states = {"online", "reconnecting", "offline", "disconnected", "revoked"}
durable_pairings = []
seen_pairing_ids = set()
seen_connection_ids = set()
for pairing in status["pairings"]:
    if not isinstance(pairing, dict) or pairing.get("direction") not in {"incoming", "outgoing"}:
        raise SystemExit(1)
    if pairing["direction"] != "outgoing":
        continue
    pairing_id = pairing.get("id")
    connection_id = pairing.get("connection_id")
    pairing_status = pairing.get("status")
    if (
        not valid_uuid4(pairing_id)
        or not valid_uuid4(connection_id)
        or pairing_id in seen_pairing_ids
        or connection_id in seen_connection_ids
        or pairing_status not in known_statuses
    ):
        raise SystemExit(1)
    seen_pairing_ids.add(pairing_id)
    seen_connection_ids.add(connection_id)
    if status_version == 1:
        if pairing_status in {"requesting", "pending_approval"}:
            raise SystemExit(1)
        durable = pairing_status in {"approved", "connected"}
    else:
        trust_state = pairing.get("trust_state")
        transport_state = pairing.get("transport_state")
        if (
            trust_state not in trust_statuses
            or pairing_status not in trust_statuses[trust_state]
            or transport_state not in known_transport_states
        ):
            raise SystemExit(1)
        if trust_state == "pending":
            raise SystemExit(1)
        durable = trust_state == "approved"
    if not durable:
        continue

    host_server_identity = pairing.get("host_server_identity")
    hub_id = pairing.get("hub_id")
    team_id = pairing.get("team_id")
    host_ca_fingerprint = pairing.get("host_ca_fingerprint")
    peer_public_key_fingerprint = pairing.get("peer_public_key_fingerprint")
    certificate_fingerprint = pairing.get("certificate_fingerprint")
    transcript_hash = pairing.get("transcript_hash")
    requested_scopes = pairing.get("requested_scopes")
    granted_scopes = pairing.get("granted_scopes")
    is_active = connection_id == active_connection_id
    expected_base_path = (
        f"/api/team-hub-secure/{connection_id}" if is_active else None
    )
    if (
        pairing_status != ("connected" if is_active else "approved")
        or (
            status_version == 2
            and pairing.get("transport_state")
            not in ({"online", "reconnecting", "offline"} if is_active else {"disconnected"})
        )
        or pairing.get("peer_server_identity") != host_server_identity
        or not valid_identifier(host_server_identity)
        or not valid_identifier(hub_id)
        or not valid_identifier(team_id)
        or not all(
            isinstance(value, str) and fingerprint.fullmatch(value) is not None
            for value in (
                host_ca_fingerprint,
                peer_public_key_fingerprint,
                certificate_fingerprint,
            )
        )
        or not isinstance(transcript_hash, str)
        or re.fullmatch(r"[0-9a-f]{64}", transcript_hash) is None
        or not isinstance(requested_scopes, list)
        or not 1 <= len(requested_scopes) <= 4
        or len(set(requested_scopes)) != len(requested_scopes)
        or not all(isinstance(scope, str) and scope for scope in requested_scopes)
        or not isinstance(granted_scopes, list)
        or not 1 <= len(granted_scopes) <= 4
        or len(set(granted_scopes)) != len(granted_scopes)
        or not all(isinstance(scope, str) and scope for scope in granted_scopes)
        or not set(granted_scopes).issubset(requested_scopes)
        or pairing.get("local_proxy_base_path") != expected_base_path
    ):
        raise SystemExit(1)
    durable_pairings.append(
        {
            "id": pairing_id,
            "connection_id": connection_id,
            "host_server_identity": host_server_identity,
            "hub_id": hub_id,
            "team_id": team_id,
            "host_ca_fingerprint": host_ca_fingerprint,
            "peer_public_key_fingerprint": peer_public_key_fingerprint,
            "transcript_hash": transcript_hash,
            # The leaf certificate is intentionally not a continuity key:
            # startup may renew it while retaining the durable trust anchors.
            "requested_scopes": sorted(requested_scopes),
            "granted_scopes": sorted(granted_scopes),
        }
    )

if active_connection_id is not None and active_connection_id not in {
    item["connection_id"] for item in durable_pairings
}:
    raise SystemExit(1)
if not durable_pairings:
    if active_connection_id is not None or not exact_values(team_hub, disabled_capability):
        raise SystemExit(1)
    print('{"kind":"disabled"}')
    raise SystemExit(0)

binding = {
    "kind": "secure_peer_client",
    "active_connection_id": active_connection_id,
    "pairings": sorted(durable_pairings, key=lambda item: item["connection_id"]),
}
if active_connection_id is None:
    if not exact_values(team_hub, disabled_capability):
        raise SystemExit(1)
else:
    active_pairing = next(
        item for item in durable_pairings
        if item["connection_id"] == active_connection_id
    )
    base_path = f"/api/team-hub-secure/{active_connection_id}"
    route = {
        "transport": "secure_peer",
        "hub_url": None,
        "base_path": base_path,
        "connection_id": active_connection_id,
        "host_server_identity": active_pairing["host_server_identity"],
        "hub_id": active_pairing["hub_id"],
    }
    active_capability = {
        "available": True,
        "designated_host": False,
        "version": 1,
        "base_path": base_path,
        "transport": "secure_peer",
        "hub_url": None,
        "connection_id": active_connection_id,
        "hub_id": active_pairing["hub_id"],
        "host_server_identity": active_pairing["host_server_identity"],
        "routes": [route],
    }
    # The health projection intentionally disappears while the active client
    # is offline or stale. Durable status remains authoritative in that case.
    if not (
        exact_values(team_hub, disabled_capability)
        or exact_values(team_hub, active_capability)
    ):
        raise SystemExit(1)
print(json.dumps(binding, sort_keys=True, separators=(",", ":")))
PY
}

capture_managed_team_hub_client_binding() {
  local port="$1"
  local runtime_root="$2"
  local expected_server="$3"
  local selected_bind="${4:-$BIND_ADDRESS}"
  local health_file=""
  local status_file=""
  local binding_file=""
  health_file="$(mktemp "$STATE_ROOT/admin/.install-pre-health.XXXXXX")" || return 1
  status_file="$(mktemp "$STATE_ROOT/admin/.install-pre-peer-status.XXXXXX")" || {
    rm -f "$health_file"
    return 1
  }
  binding_file="$(mktemp "$STATE_ROOT/admin/.install-client-binding.XXXXXX")" || {
    rm -f "$health_file" "$status_file"
    return 1
  }
  chmod 600 "$health_file" "$status_file" "$binding_file"
  if ! fetch_managed_json \
      "$port" "/api/health" core "$health_file" "$runtime_root" \
      "$selected_bind"; then
    rm -f "$health_file" "$status_file" "$binding_file"
    return 1
  fi
  # Legacy sources predate the control endpoint. The projection below accepts
  # a missing status response only when the health capability is also absent.
  if ! fetch_managed_json \
      "$port" \
      "/api/admin/secure-peers/v1/status" \
      secure-peer \
      "$status_file" \
      "$runtime_root" \
      "$selected_bind"; then
    : > "$status_file"
  fi
  if ! managed_secure_peer_binding_from_responses \
      "$runtime_root" \
      "$health_file" \
      "$status_file" \
      "$expected_server" \
      "true" > "$binding_file"; then
    rm -f "$health_file" "$status_file" "$binding_file"
    return 1
  fi
  EXPECTED_TEAM_HUB_CLIENT_BINDING="$(tr -d '\r\n' < "$binding_file")"
  rm -f "$health_file" "$status_file" "$binding_file"
  [[ -n "$EXPECTED_TEAM_HUB_CLIENT_BINDING" ]]
}

release_health_check_once() {
  local port="$1"
  local runtime_root="$2"
  local expected_version="$3"
  local expected_server="$4"
  local expected_hub_mode="$5"
  local expected_hub="$6"
  local expected_hub_transport="$7"
  local expected_hub_url="$8"
  local allow_legacy_transport="${9:-false}"
  local selected_bind="${10:-$BIND_ADDRESS}"
  local expected_direct_ip_url="${11:-$TEAM_HUB_DIRECT_IP_URL}"
  local response_file=""
  local status_file=""
  local observed_binding_file=""
  response_file="$(mktemp "$STATE_ROOT/admin/.install-health.XXXXXX")" || return 1
  status_file="$(mktemp "$STATE_ROOT/admin/.install-peer-status.XXXXXX")" || {
    rm -f "$response_file"
    return 1
  }
  observed_binding_file="$(mktemp "$STATE_ROOT/admin/.install-observed-binding.XXXXXX")" || {
    rm -f "$response_file" "$status_file"
    return 1
  }
  chmod 600 "$response_file" "$status_file" "$observed_binding_file"
  if ! fetch_managed_json \
      "$port" "/api/health" core "$response_file" "$runtime_root" \
      "$selected_bind"; then
    rm -f "$response_file" "$status_file" "$observed_binding_file"
    return 1
  fi
  local response_size=""
  response_size="$(wc -c < "$response_file" 2>/dev/null || true)"
  response_size="${response_size//[[:space:]]/}"
  if [[ ! "$response_size" =~ ^[0-9]+$ ]] || ((response_size > 1048576)); then
    rm -f "$response_file" "$status_file" "$observed_binding_file"
    return 1
  fi
  local result=1
  if run_without_server_secrets "$runtime_root/.venv/bin/python" - \
    "$response_file" \
    "$expected_version" \
    "$expected_server" \
    "$expected_hub_mode" \
    "$expected_hub" \
    "$expected_hub_transport" \
    "$expected_hub_url" \
    "$expected_direct_ip_url" \
    "$allow_legacy_transport" \
    "$EXPECTED_TEAM_HUB_CLIENT_BINDING" <<'PY'
import json
import re
import sys

(
    path,
    expected_version,
    expected_server,
    hub_mode,
    expected_hub,
    expected_transport,
    expected_hub_url,
    expected_direct_ip_url,
    allow_legacy_transport,
    expected_client_binding_json,
) = sys.argv[1:]
try:
    with open(path, "rb") as stream:
        health = json.load(stream)
except (OSError, UnicodeError, json.JSONDecodeError):
    raise SystemExit(1)
if not isinstance(health, dict) or health.get("ok") is not True:
    raise SystemExit(1)
if health.get("server_version") != expected_version:
    raise SystemExit(1)
server_identity = health.get("server_identity")
if not isinstance(server_identity, str) or re.fullmatch(r"[A-Za-z0-9_.:-]{8,240}", server_identity) is None:
    raise SystemExit(1)
if expected_server and server_identity != expected_server:
    raise SystemExit(1)
capabilities = health.get("capabilities")
capability = capabilities.get("team_hub_v1") if isinstance(capabilities, dict) else None
if not isinstance(capability, dict):
    raise SystemExit(1)
try:
    expected_client_binding = (
        json.loads(expected_client_binding_json)
        if expected_client_binding_json
        else None
    )
except json.JSONDecodeError:
    raise SystemExit(1)
if expected_client_binding is not None and not isinstance(expected_client_binding, dict):
    raise SystemExit(1)
if hub_mode == "host":
    required = {
        "available": True,
        "designated_host": True,
        "version": 1,
        "base_path": "/api/team-hub",
        "host_server_identity": server_identity,
    }
    if any(capability.get(key) != value for key, value in required.items()):
        raise SystemExit(1)
    hub_id = capability.get("hub_id")
    if not isinstance(hub_id, str) or re.fullmatch(r"[A-Za-z0-9_.:-]{8,240}", hub_id) is None:
        raise SystemExit(1)
    if expected_hub and hub_id != expected_hub:
        raise SystemExit(1)
    transport = capability.get("transport")
    hub_url = capability.get("hub_url")
    if (
        allow_legacy_transport == "true"
        and transport is None
        and expected_transport == "loopback"
        and not expected_hub_url
    ):
        transport = "loopback"
    if transport != expected_transport or hub_url != (expected_hub_url or None):
        raise SystemExit(1)
    routes = capability.get("routes")
    expected_routes = [{
        "transport": expected_transport,
        "hub_url": expected_hub_url or None,
    }]
    if expected_direct_ip_url and expected_transport != "direct_ip":
        expected_routes.append({
            "transport": "direct_ip",
            "hub_url": expected_direct_ip_url,
        })
    if routes != expected_routes:
        if not (allow_legacy_transport == "true" and routes is None):
            raise SystemExit(1)
elif hub_mode == "disabled":
    binding_kind = (
        expected_client_binding.get("kind")
        if expected_client_binding is not None
        else "disabled"
    )
    disabled_required = {
        "available": False,
        "designated_host": False,
        "version": 1,
        "base_path": None,
        "hub_id": None,
        "host_server_identity": None,
        "transport": None,
        "hub_url": None,
    }
    if binding_kind == "disabled":
        required = disabled_required
    elif binding_kind == "secure_peer_client":
        connection_id = expected_client_binding.get("active_connection_id")
        pairings = expected_client_binding.get("pairings")
        if not isinstance(pairings, list) or not pairings:
            raise SystemExit(1)
        if connection_id is None:
            required = disabled_required
        else:
            active = [
                item
                for item in pairings
                if isinstance(item, dict)
                and item.get("connection_id") == connection_id
            ]
            if len(active) != 1:
                raise SystemExit(1)
            hub_id = active[0].get("hub_id")
            host_server_identity = active[0].get("host_server_identity")
            identifier = re.compile(r"[A-Za-z0-9_.:-]{8,240}")
            if not all(
                isinstance(value, str) and identifier.fullmatch(value) is not None
                for value in (connection_id, hub_id, host_server_identity)
            ):
                raise SystemExit(1)
            expected_base_path = f"/api/team-hub-secure/{connection_id}"
            expected_route = {
                "transport": "secure_peer",
                "hub_url": None,
                "base_path": expected_base_path,
                "connection_id": connection_id,
                "host_server_identity": host_server_identity,
                "hub_id": hub_id,
            }
            active_required = {
                "available": True,
                "designated_host": False,
                "version": 1,
                "base_path": expected_base_path,
                "hub_id": hub_id,
                "host_server_identity": host_server_identity,
                "transport": "secure_peer",
                "hub_url": None,
                "connection_id": connection_id,
                "routes": [expected_route],
            }
            # A paired client is intentionally omitted from health while its
            # heartbeat is stale/offline. The authenticated status endpoint
            # below remains the durable continuity proof.
            required = (
                disabled_required
                if capability.get("available") is False
                else active_required
            )
    else:
        raise SystemExit(1)
    if any(capability.get(key) != value for key, value in required.items()):
        raise SystemExit(1)
elif hub_mode == "failed_host":
    required = {
        "available": False,
        "designated_host": True,
        "version": 1,
        "base_path": "/api/team-hub",
        "hub_id": None,
        "host_server_identity": server_identity,
        "transport": expected_transport,
        "hub_url": expected_hub_url or None,
    }
    if any(capability.get(key) != value for key, value in required.items()):
        raise SystemExit(1)
else:
    raise SystemExit(1)
secure_capability = capabilities.get("secure_peer_v1")
if secure_capability is None and allow_legacy_transport == "true":
    pass
else:
    secure_required = {
        "available": True,
        "state_available": True,
        "state_error_code": None,
        "required": False,
        "version": 1,
        "control_path": "/api/admin/secure-peers/v1/status",
        "proxy_prefix": "/api/team-hub-secure",
    }
    if not isinstance(secure_capability, dict) or any(
        secure_capability.get(key) != value
        for key, value in secure_required.items()
    ):
        raise SystemExit(1)
PY
  then
    result=0
    if [[ -n "$EXPECTED_TEAM_HUB_CLIENT_BINDING" ]]; then
      if ! fetch_managed_json \
          "$port" \
          "/api/admin/secure-peers/v1/status" \
          secure-peer \
          "$status_file" \
          "$runtime_root" \
          "$selected_bind"; then
        : > "$status_file"
      fi
      if ! managed_secure_peer_binding_from_responses \
          "$runtime_root" \
          "$response_file" \
          "$status_file" \
          "$expected_server" \
          "$allow_legacy_transport" > "$observed_binding_file"; then
        result=1
      elif [[ "$(tr -d '\r\n' < "$observed_binding_file")" != "$EXPECTED_TEAM_HUB_CLIENT_BINDING" ]]; then
        result=1
      fi
    fi
  fi
  rm -f "$response_file" "$status_file" "$observed_binding_file"
  return "$result"
}

wait_for_health() {
  local attempt
  for ((attempt = 1; attempt <= HEALTH_CHECK_ATTEMPTS; attempt++)); do
    if health_check_once "$PORT"; then
      return 0
    fi
    if ((attempt < HEALTH_CHECK_ATTEMPTS)) && ((attempt % HEALTH_CHECK_HEARTBEAT_ATTEMPTS == 0)); then
      echo "      Still waiting for health (${attempt}s elapsed, timeout ${HEALTH_CHECK_ATTEMPTS}s)"
    fi
    ((attempt == HEALTH_CHECK_ATTEMPTS)) || sleep 1
  done
  return 1
}

legacy_release_health_check_once() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  local response_file=""
  response_file="$(mktemp "$STATE_ROOT/admin/.install-legacy-health.XXXXXX")" \
    || return 1
  chmod 600 "$response_file" || {
    rm -f "$response_file"
    return 1
  }
  if ! fetch_managed_json \
      "$PRIOR_PORT" "/api/health" core "$response_file" \
      "$runtime_root" "$PRIOR_BIND_ADDRESS"; then
    rm -f "$response_file"
    return 1
  fi
  local result=1
  if run_without_server_secrets "$runtime_root/.venv/bin/python" - \
      "$response_file" <<'PY'
import json
import re
import sys

try:
    with open(sys.argv[1], "rb") as stream:
        value = json.load(stream)
except (OSError, UnicodeError, json.JSONDecodeError):
    raise SystemExit(1)
if not isinstance(value, dict) or value.get("ok") is not True:
    raise SystemExit(1)
if not isinstance(value.get("server_version"), str) or re.fullmatch(
    r"[0-9]+\.[0-9]+\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?",
    value["server_version"],
) is None:
    raise SystemExit(1)
if not isinstance(value.get("server_identity"), str) or re.fullmatch(
    r"[A-Za-z0-9_.:-]{8,240}", value["server_identity"]
) is None:
    raise SystemExit(1)
PY
  then
    result=0
  fi
  rm -f "$response_file"
  return "$result"
}

wait_for_legacy_release_health() {
  local runtime_root="${1:-$CANDIDATE_RUNTIME_ROOT}"
  local attempt=1
  local attempt_limit="$HEALTH_CHECK_ATTEMPTS"
  ((attempt_limit <= ROLLBACK_HEALTH_CHECK_MAX_ATTEMPTS)) \
    || attempt_limit="$ROLLBACK_HEALTH_CHECK_MAX_ATTEMPTS"
  for ((attempt = 1; attempt <= attempt_limit; attempt++)); do
    if legacy_release_health_check_once "$runtime_root"; then
      return 0
    fi
    ((attempt == attempt_limit)) || sleep 1
  done
  return 1
}

wait_for_exact_release_health() {
  local runtime_root="$1"
  local expected_version="$2"
  local expected_server="$3"
  local expected_hub_mode="$4"
  local expected_hub="$5"
  local expected_hub_transport="$6"
  local expected_hub_url="$7"
  local health_label="$8"
  local attempt_limit="${9:-$HEALTH_CHECK_ATTEMPTS}"
  local allow_legacy_transport="${10:-false}"
  local health_port="${11:-$PORT}"
  local health_bind="${12:-$BIND_ADDRESS}"
  local expected_direct_ip_url="${13:-$TEAM_HUB_DIRECT_IP_URL}"
  local attempt
  for ((attempt = 1; attempt <= attempt_limit; attempt++)); do
    if release_health_check_once \
      "$health_port" \
      "$runtime_root" \
      "$expected_version" \
      "$expected_server" \
      "$expected_hub_mode" \
      "$expected_hub" \
      "$expected_hub_transport" \
      "$expected_hub_url" \
      "$allow_legacy_transport" \
      "$health_bind" \
      "$expected_direct_ip_url"; then
      return 0
    fi
    if ((attempt < attempt_limit)) && ((attempt % HEALTH_CHECK_HEARTBEAT_ATTEMPTS == 0)); then
      echo "      Still waiting for exact $health_label health (${attempt}s elapsed, timeout ${attempt_limit}s)"
    fi
    ((attempt == attempt_limit)) || sleep 1
  done
  return 1
}

wait_for_release_health() {
  wait_for_exact_release_health \
    "$RELEASE_DIR" \
    "$RELEASE_VERSION" \
    "$EXPECTED_SERVER_IDENTITY" \
    "$TEAM_HUB_MODE" \
    "${EXPECTED_TEAM_HUB_ID:-$TEAM_HUB_REACTIVATION_HUB_ID}" \
    "$TEAM_HUB_TRANSPORT" \
    "$TEAM_HUB_URL" \
    "candidate release"
}

secure_peer_host_attachment_check_once() {
  [[ "$TEAM_HUB_MODE" == "host" ]] || return 0
  local runtime_root="$1"
  local status_file=""
  local health_file=""
  local observed_identity=""
  status_file="$(mktemp "$STATE_ROOT/admin/.install-host-peer-status.XXXXXX")" || return 1
  health_file="$(mktemp "$STATE_ROOT/admin/.install-host-health.XXXXXX")" || {
    rm -f "$status_file"
    return 1
  }
  chmod 600 "$status_file" "$health_file"
  if ! fetch_managed_json \
      "$PORT" \
      "/api/admin/secure-peers/v1/status" \
      secure-peer \
      "$status_file" \
      "$runtime_root"; then
    rm -f "$status_file" "$health_file"
    return 1
  fi
  if [[ -z "$EXPECTED_SERVER_IDENTITY" ]] \
    && ! fetch_managed_json \
      "$PORT" "/api/health" core "$health_file" "$runtime_root"; then
    rm -f "$status_file" "$health_file"
    return 1
  fi
  local result=1
  if observed_identity="$(run_without_server_secrets "$runtime_root/.venv/bin/python" - \
      "$status_file" "$health_file" "$EXPECTED_SERVER_IDENTITY" <<'PY'
import json
import re
import sys

try:
    with open(sys.argv[1], "rb") as stream:
        value = json.load(stream)
except (OSError, UnicodeError, json.JSONDecodeError):
    raise SystemExit(1)
expected_identity = sys.argv[3]
status_identity = value.get("server_identity") if isinstance(value, dict) else None
if (
    not isinstance(status_identity, str)
    or re.fullmatch(r"[A-Za-z0-9_.:-]{8,240}", status_identity) is None
):
    raise SystemExit(1)
if expected_identity:
    if status_identity != expected_identity:
        raise SystemExit(1)
else:
    try:
        with open(sys.argv[2], "rb") as stream:
            health = json.load(stream)
    except (OSError, UnicodeError, json.JSONDecodeError):
        raise SystemExit(1)
    if (
        not isinstance(health, dict)
        or health.get("ok") is not True
        or health.get("server_identity") != status_identity
    ):
        raise SystemExit(1)
host = value.get("host") if isinstance(value, dict) else None
if (
    not isinstance(host, dict)
    or host.get("available") is not True
    or host.get("error") is not None
    or host.get("error_code") is not None
):
    raise SystemExit(1)
print(status_identity)
PY
  )"; then
    if [[ -n "$EXPECTED_SERVER_IDENTITY" ]]; then
      result=0
    elif run_without_server_secrets env PYTHONPATH="$runtime_root" \
        "$runtime_root/.venv/bin/python" -m agentsdock_team_hub.cli \
        verify-server-identity \
        --server-state-dir "$STATE_ROOT" \
        --expected-identity "$observed_identity" >/dev/null; then
      result=0
    fi
  fi
  rm -f "$status_file" "$health_file"
  return "$result"
}

wait_for_final_release_health() {
  local attempt
  for ((attempt = 1; attempt <= HEALTH_CHECK_ATTEMPTS; attempt++)); do
    if release_health_check_once \
        "$PORT" \
        "$RELEASE_DIR" \
        "$RELEASE_VERSION" \
        "$EXPECTED_SERVER_IDENTITY" \
        "$TEAM_HUB_MODE" \
        "${EXPECTED_TEAM_HUB_ID:-$TEAM_HUB_REACTIVATION_HUB_ID}" \
        "$TEAM_HUB_TRANSPORT" \
        "$TEAM_HUB_URL" \
        false \
      && secure_peer_host_attachment_check_once "$RELEASE_DIR"; then
      return 0
    fi
    ((attempt == HEALTH_CHECK_ATTEMPTS)) || sleep 1
  done
  return 1
}

wait_for_previous_release_health() {
  local previous_version=""
  local previous_release_root="${ROLLBACK_RELEASE_ROOT:-$OLD_TARGET}"
  local rollback_attempts="$HEALTH_CHECK_ATTEMPTS"
  local previous_hub_mode="${PREVIOUS_TEAM_HUB_MODE:-disabled}"
  local previous_hub_id="$EXPECTED_TEAM_HUB_ID"
  local previous_hub_transport="$PREVIOUS_TEAM_HUB_TRANSPORT"
  local previous_hub_url="$PREVIOUS_TEAM_HUB_URL"
  [[ -n "$previous_release_root" && -f "$previous_release_root/VERSION" ]] || {
    echo "The previous release version cannot be verified." >&2
    return 1
  }
  previous_version="$(tr -d '[:space:]' < "$previous_release_root/VERSION")"
  if [[ ! "$previous_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-+][A-Za-z0-9.-]+)?$ ]]; then
    echo "The previous release version is invalid." >&2
    return 1
  fi
  if ((rollback_attempts > ROLLBACK_HEALTH_CHECK_MAX_ATTEMPTS)); then
    rollback_attempts="$ROLLBACK_HEALTH_CHECK_MAX_ATTEMPTS"
  fi
  if [[ "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
    previous_hub_mode="failed_host"
    previous_hub_id=""
    previous_hub_transport="$PREVIOUS_TEAM_HUB_TRANSPORT"
    previous_hub_url="$PREVIOUS_TEAM_HUB_URL"
  elif [[ "$ACTIVATION_HUB_KIND" == "host-reactivation" ]]; then
    previous_hub_mode="disabled"
    previous_hub_id=""
    previous_hub_transport="loopback"
    previous_hub_url=""
  fi
  wait_for_exact_release_health \
    "$previous_release_root" \
    "$previous_version" \
    "$EXPECTED_SERVER_IDENTITY" \
    "$previous_hub_mode" \
    "$previous_hub_id" \
    "$previous_hub_transport" \
    "$previous_hub_url" \
    "restored release" \
    "$rollback_attempts" \
    "true" \
    "$PRIOR_PORT" \
    "$PRIOR_BIND_ADDRESS" \
    "$PREVIOUS_TEAM_HUB_DIRECT_IP_URL"
}

ensure_committed_candidate_service() {
  if wait_for_release_health; then
    return 0
  fi
  if [[ "$OS_NAME" == "Linux" ]]; then
    systemctl --user daemon-reload || return 1
    systemctl --user enable "$SERVICE_NAME.service" >/dev/null || return 1
    systemctl --user start --no-block "$SERVICE_NAME.service" || return 1
  else
    local domain="gui/$(id -u)"
    local service_target="$domain/$LABEL"
    if launchctl print "$service_target" >/dev/null 2>&1; then
      launchctl kickstart -k "$service_target" >/dev/null || return 1
    else
      bootstrap_launch_agent "$domain" "$service_target" false || return 1
    fi
  fi
  wait_for_release_health
}

resume_settlement_signals() {
  [[ "$IN_EXIT_CLEANUP" == "true" ]] || resume_install_signals
}

complete_activation_commit() {
  [[ "$ACTIVATION_TRANSACTION_PHASE" == "committing" \
    || "$ACTIVATION_TRANSACTION_PHASE" == "committed" ]] || return 1
  if ! ensure_committed_candidate_service; then
    echo "The committed candidate service could not be restored to authenticated health." >&2
    return 1
  fi
  if [[ "$ACTIVATION_TRANSACTION_PHASE" == "committing" ]]; then
    mask_install_signals
    if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
      if ! clear_team_hub_operation_fence "$CANDIDATE_RUNTIME_ROOT" true; then
        echo "The committed candidate could not consume its exact Team Hub update fence." >&2
        resume_settlement_signals
        return 1
      fi
    elif [[ "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
      if ! clear_team_hub_reactivation_fence "$CANDIDATE_RUNTIME_ROOT" true; then
        echo "The committed candidate could not consume its exact Team Hub reactivation fence." >&2
        resume_settlement_signals
        return 1
      fi
    fi
    if ! clear_team_hub_startup_authority "$CANDIDATE_RUNTIME_ROOT" true; then
      echo "The committed candidate could not retire its exact startup authority." >&2
      resume_settlement_signals
      return 1
    fi
    TEAM_HUB_OPERATION_FINALIZED="true"
    TEAM_HUB_REACTIVATION_FINALIZED="true"
    TEAM_HUB_OPERATION_PENDING="false"
    TEAM_HUB_REACTIVATION_FENCE_PENDING="false"
    TEAM_HUB_STARTUP_AUTHORITY_PENDING="false"
    if [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]] \
      && ! clear_team_hub_cold_guard "$CANDIDATE_RUNTIME_ROOT" true; then
      echo "The committed candidate could not retire its startup guard." >&2
      resume_settlement_signals
      return 1
    fi
    if ! wait_for_final_release_health; then
      echo "The committed candidate did not restore full Hub and secure-peer health." >&2
      resume_settlement_signals
      return 1
    fi
    if ! record_activation_phase committed "$CANDIDATE_RUNTIME_ROOT"; then
      echo "The candidate committed, but its terminal activation state was not persisted." >&2
      resume_settlement_signals
      return 1
    fi
  elif ! wait_for_final_release_health; then
    echo "The terminal candidate no longer has authenticated final health." >&2
    return 1
  fi
  resume_settlement_signals
  finish_activation_transaction "$CANDIDATE_RUNTIME_ROOT"
}

load_pending_activation_transaction() {
  [[ "$ACTIVATION_TRANSACTION_RESUMED" == "true" ]] || return 0
  local load_file=""
  local line=""
  local loaded_state_root=""
  local loaded_port=""
  local -a fields=()
  load_file="$(mktemp "$INSTALL_ROOT/.activation-load.XXXXXXXX")" || return 1
  chmod 600 "$load_file" || {
    rm -f "$load_file"
    return 1
  }
  if ! activation_transaction_command "$STAGE_DIR" load \
      --root "$INSTALL_ROOT" \
      --current "$CURRENT_LINK" \
      --previous "$PREVIOUS_LINK" \
      --env "$ENV_FILE" \
      --service "$(activation_service_config_path)" > "$load_file"; then
    rm -f "$load_file"
    return 1
  fi
  while IFS= read -r line; do
    fields[${#fields[@]}]="$line"
  done < "$load_file"
  rm -f "$load_file"
  if (( ${#fields[@]} != 38 )) \
    || [[ "${fields[37]}" != "activation-end" ]] \
    || [[ ! "${fields[0]}" =~ ^activation-[0-9a-f]{24}$ ]] \
    || [[ ! "${fields[1]}" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-+][A-Za-z0-9.-]+)?$ ]] \
    || [[ "${fields[2]}" != "$RELEASES_ROOT/${fields[1]}" ]] \
    || [[ "${fields[3]}" != "prepared" \
      && "${fields[3]}" != "guarded" \
      && "${fields[3]}" != "linking" \
      && "${fields[3]}" != "linked" \
      && "${fields[3]}" != "stopping" \
      && "${fields[3]}" != "stopped" \
      && "${fields[3]}" != "fencing" \
      && "${fields[3]}" != "fenced" \
      && "${fields[3]}" != "authorizing" \
      && "${fields[3]}" != "authority" \
      && "${fields[3]}" != "candidate-starting" \
      && "${fields[3]}" != "candidate-healthy" \
      && "${fields[3]}" != "committing" \
      && "${fields[3]}" != "committed" \
      && "${fields[3]}" != "rolling-back" \
      && "${fields[3]}" != "rolled-back" \
      && "${fields[3]}" != "rollback-healthy" ]] \
    || [[ "${fields[11]}" != "true" && "${fields[11]}" != "false" ]] \
    || [[ "${fields[13]}" != "true" && "${fields[13]}" != "false" ]] \
    || [[ "${fields[15]}" != "absent" \
      && "${fields[15]}" != "stopped" \
      && "${fields[15]}" != "running" ]] \
    || [[ "${fields[16]}" != "true" && "${fields[16]}" != "false" ]] \
    || [[ "${fields[17]}" != "absent" \
      && "${fields[17]}" != "stopped" \
      && "${fields[17]}" != "running" ]] \
    || [[ "${fields[18]}" != "true" && "${fields[18]}" != "false" ]] \
    || [[ "${fields[19]}" != "ordinary" \
      && "${fields[19]}" != "server-update" \
      && "${fields[19]}" != "host-reactivation" \
      && "${fields[19]}" != "failed-host-repair" ]] \
    || [[ "${fields[32]}" != "true" && "${fields[32]}" != "false" ]] \
    || [[ "${fields[33]}" != "true" && "${fields[33]}" != "false" ]] \
    || [[ ! "${fields[35]}" =~ ^[0-9]+$ ]] \
    || (( 10#${fields[35]} < 1 || 10#${fields[35]} > 65535 )); then
    echo "The pending activation transaction returned an invalid recovery record." >&2
    return 1
  fi

  ACTIVATION_TRANSACTION_ID="${fields[0]}"
  RELEASE_VERSION="${fields[1]}"
  RELEASE_DIR="${fields[2]}"
  ACTIVATION_TRANSACTION_PHASE="${fields[3]}"
  ACTIVATION_ROLLBACK_FROM="${fields[4]}"
  OLD_TARGET="${fields[5]}"
  ORIGINAL_OLD_SOURCE="${fields[6]}"
  ROLLBACK_RELEASE_ROOT="$ORIGINAL_OLD_SOURCE"
  CURRENT_LINK_STATE_CAPTURED="true"
  CURRENT_LINK_WAS_SYMLINK="false"
  CURRENT_LINK_WAS_DIRECTORY="false"
  CURRENT_LINK_TARGET="${fields[8]}"
  [[ "${fields[7]}" != "symlink" ]] || CURRENT_LINK_WAS_SYMLINK="true"
  [[ "${fields[7]}" != "directory" ]] || CURRENT_LINK_WAS_DIRECTORY="true"
  PREVIOUS_LINK_STATE_CAPTURED="true"
  PREVIOUS_LINK_WAS_SYMLINK="false"
  PREVIOUS_LINK_TARGET="${fields[10]}"
  [[ "${fields[9]}" != "symlink" ]] || PREVIOUS_LINK_WAS_SYMLINK="true"
  ENV_CONFIG_EXISTED="${fields[11]}"
  ENV_CONFIG_BACKUP="${fields[12]}"
  ENV_CONFIG_CAPTURED="true"
  SERVICE_CONFIG_EXISTED="${fields[13]}"
  SERVICE_CONFIG_BACKUP="${fields[14]}"
  SERVICE_CONFIG_CAPTURED="true"
  PRIOR_SERVICE_STATE="${fields[15]}"
  PRIOR_SERVICE_ENABLED="${fields[16]}"
  PRIOR_LEGACY_SERVICE_STATE="${fields[17]}"
  PRIOR_LEGACY_SERVICE_ENABLED="${fields[18]}"
  ACTIVATION_INTENT="${fields[19]}"
  ACTIVATION_HUB_KIND="${fields[21]}"
  EXPECTED_TEAM_HUB_CLIENT_BINDING="${fields[20]}"
  TEAM_HUB_OPERATION_PENDING="false"
  TEAM_HUB_REACTIVATION_FENCE_PENDING="false"
  TEAM_HUB_OPERATION_FINALIZED="false"
  TEAM_HUB_REACTIVATION_FINALIZED="false"
  TEAM_HUB_REACTIVATION_REQUESTED="false"
  TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED="false"

  case "$ACTIVATION_INTENT" in
    server-update) ;;
    host-reactivation) TEAM_HUB_REACTIVATION_REQUESTED="true" ;;
    failed-host-repair) TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED="true" ;;
  esac
  case "${fields[21]}" in
    "") ;;
    server-update)
      [[ "$ACTIVATION_INTENT" == "server-update" ]] || return 1
      TEAM_HUB_DATA_DIR="${fields[22]}"
      EXPECTED_TEAM_HUB_ID="${fields[23]}"
      EXPECTED_SERVER_IDENTITY="${fields[24]}"
      TEAM_HUB_OPERATION_ID="${fields[25]}"
      TEAM_HUB_SNAPSHOT="${fields[26]}"
      TEAM_HUB_OPERATION_FENCE_DEVICE="${fields[27]}"
      TEAM_HUB_OPERATION_FENCE_INODE="${fields[28]}"
      TEAM_HUB_OPERATION_PENDING="true"
      ;;
    host-reactivation)
      [[ "$ACTIVATION_INTENT" == "host-reactivation" \
        || "$ACTIVATION_INTENT" == "failed-host-repair" ]] || return 1
      TEAM_HUB_CANONICAL_DATA_DIR="${fields[22]}"
      TEAM_HUB_REACTIVATION_HUB_ID="${fields[23]}"
      EXPECTED_SERVER_IDENTITY="${fields[24]}"
      TEAM_HUB_REACTIVATION_OPERATION_ID="${fields[25]}"
      TEAM_HUB_REACTIVATION_SNAPSHOT="${fields[26]}"
      TEAM_HUB_REACTIVATION_FENCE_DEVICE="${fields[27]}"
      TEAM_HUB_REACTIVATION_FENCE_INODE="${fields[28]}"
      TEAM_HUB_REACTIVATION_FENCE_PENDING="true"
      ;;
    *) return 1 ;;
  esac
  TEAM_HUB_COLD_GUARD_ID="${fields[29]}"
  TEAM_HUB_COLD_GUARD_DEVICE="${fields[30]}"
  TEAM_HUB_COLD_GUARD_INODE="${fields[31]}"
  TEAM_HUB_COLD_GUARD_PENDING="false"
  [[ -z "$TEAM_HUB_COLD_GUARD_ID" ]] || TEAM_HUB_COLD_GUARD_PENDING="true"
  TEAM_HUB_STARTUP_AUTHORITY_PENDING="${fields[32]}"
  CANDIDATE_SERVICE_MAY_HAVE_STARTED="${fields[33]}"
  CANDIDATE_RUNTIME_ROOT="${fields[34]}"
  [[ -n "$CANDIDATE_RUNTIME_ROOT" ]] || CANDIDATE_RUNTIME_ROOT="$STAGE_DIR"
  PRIOR_PORT="${fields[35]}"
  PRIOR_BIND_ADDRESS="${fields[36]}"
  validate_bind_address "$PRIOR_BIND_ADDRESS" \
    "$CANDIDATE_RUNTIME_ROOT/.venv/bin/python" || return 1
  SERVICE_STOPPED_FOR_COLD_HANDOFF="$CANDIDATE_SERVICE_MAY_HAVE_STARTED"
  RELEASE_ACTIVATED="$CANDIDATE_SERVICE_MAY_HAVE_STARTED"

  loaded_state_root="$(read_env_value "$ENV_FILE" AGENTSDOCK_STATE_DIR 2>/dev/null || true)"
  if [[ -n "$loaded_state_root" && "$loaded_state_root" == /* \
    && "$loaded_state_root" != *$'\n'* ]]; then
    STATE_ROOT="$loaded_state_root"
    TEAM_HUB_CANONICAL_DATA_DIR="$STATE_ROOT/team-hub"
  fi
  loaded_port="$(read_env_value "$ENV_FILE" AGENTSDOCK_AGENT_PORT 2>/dev/null || true)"
  [[ ! "$loaded_port" =~ ^[0-9]+$ ]] || PORT="$loaded_port"
  local loaded_value=""
  loaded_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_AGENT_BIND 2>/dev/null || true)"
  if [[ -n "$loaded_value" ]]; then
    validate_bind_address "$loaded_value" || return 1
    BIND_ADDRESS="$loaded_value"
  fi
  loaded_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_AGENT_TOKEN 2>/dev/null || true)"
  [[ -z "$loaded_value" ]] || TOKEN="$loaded_value"
  if env_file_has_key "$ENV_FILE" AGENTSDOCK_SERVER_NAME; then
    loaded_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_SERVER_NAME 2>/dev/null)" \
      || return 1
    loaded_value="$(decode_server_name_env_value "$loaded_value")" || return 1
    SERVER_NAME="$(canonical_server_name "$loaded_value")" || return 1
  else
    SERVER_NAME=""
  fi
  loaded_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_MODE 2>/dev/null || true)"
  [[ -z "$loaded_value" ]] || TEAM_HUB_MODE="$loaded_value"
  loaded_value="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_TRANSPORT 2>/dev/null || true)"
  [[ -z "$loaded_value" ]] || TEAM_HUB_TRANSPORT="$loaded_value"
  TEAM_HUB_URL="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_URL 2>/dev/null || true)"
  TEAM_HUB_DIRECT_IP_URL="$(read_env_value "$ENV_FILE" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL 2>/dev/null || true)"
  PREVIOUS_TEAM_HUB_TRANSPORT="$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_TRANSPORT 2>/dev/null || true)"
  [[ -n "$PREVIOUS_TEAM_HUB_TRANSPORT" ]] || PREVIOUS_TEAM_HUB_TRANSPORT="loopback"
  PREVIOUS_TEAM_HUB_MODE="$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_MODE 2>/dev/null || true)"
  [[ -n "$PREVIOUS_TEAM_HUB_MODE" ]] || PREVIOUS_TEAM_HUB_MODE="disabled"
  PREVIOUS_TEAM_HUB_URL="$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_URL 2>/dev/null || true)"
  PREVIOUS_TEAM_HUB_DIRECT_IP_URL="$(read_env_value "$ENV_CONFIG_BACKUP" AGENTSDOCK_TEAM_HUB_DIRECT_IP_URL 2>/dev/null || true)"
  PRESERVE_SOURCE="$ENV_FILE"
  echo "      Recovering pending activation $ACTIVATION_TRANSACTION_ID ($ACTIVATION_TRANSACTION_PHASE)"
}

recover_pending_activation_transaction() {
  [[ "$ACTIVATION_TRANSACTION_RESUMED" == "true" ]] || return 0
  case "$ACTIVATION_TRANSACTION_PHASE" in
    committing|committed)
      if ! complete_activation_commit; then
        echo "The irreversible activation commit remains pending and fail-closed." >&2
        return 1
      fi
      if [[ "$REQUESTED_RELEASE_VERSION" == "$RELEASE_VERSION" ]]; then
        echo "Recovered and verified the previously committed AgentsServer $RELEASE_VERSION activation."
        return 0
      fi
      echo "Recovered AgentsServer $RELEASE_VERSION. Run the installer again for requested $REQUESTED_RELEASE_VERSION." >&2
      return 75
      ;;
    rollback-healthy)
      if ! finish_activation_transaction "$STAGE_DIR"; then
        return 1
      fi
      echo "Retired the previously verified rollback. Run the installer again." >&2
      return 75
      ;;
    rolled-back)
      if ! restore_previous_release; then
        echo "The pending rollback could not restore its prior service state; its journal remains for retry." >&2
        return 1
      fi
      echo "Recovered the exact pre-activation release and service state. Run the installer again." >&2
      return 75
      ;;
    *)
      if ! restore_previous_release; then
        echo "The pending activation could not be rolled back safely; its journal remains for retry." >&2
        return 1
      fi
      echo "Recovered the exact pre-activation release and service state. Run the installer again." >&2
      return 75
      ;;
  esac
}

if [[ "$ACTIVATION_TRANSACTION_RESUMED" == "true" ]]; then
  if ! load_pending_activation_transaction; then
    echo "The pending activation transaction could not be verified for recovery." >&2
    exit 1
  fi
  if recover_pending_activation_transaction; then
    exit 0
  else
    recovery_status=$?
    exit "$recovery_status"
  fi
fi

if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  if ! verify_team_hub_rollback_snapshot "$STAGE_DIR"; then
    echo "Candidate Team Hub rollback verifier rejected the exact snapshot before activation." >&2
    exit 1
  fi
fi

echo "[3/7] Activating release $RELEASE_VERSION"
CURRENT_LINK_WAS_DIRECTORY="false"
if [[ -L "$CURRENT_LINK" ]]; then
  OLD_TARGET="$(readlink "$CURRENT_LINK")"
  [[ "$OLD_TARGET" == /* ]] || OLD_TARGET="$INSTALL_ROOT/$OLD_TARGET"
elif [[ -d "$CURRENT_LINK" ]]; then
  CURRENT_LINK_WAS_DIRECTORY="true"
  OLD_TARGET="$RELEASES_ROOT/legacy-$(date -u +%Y%m%d%H%M%S)"
elif [[ -e "$CURRENT_LINK" ]]; then
  echo "$CURRENT_LINK is not a supported release link or directory." >&2
  exit 1
fi
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" && "$CURRENT_LINK_WAS_DIRECTORY" == "true" ]]; then
  echo "Managed Team Hub update requires a versioned current-release symlink; legacy directory takeover is not supported." >&2
  exit 1
fi
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" && ( -z "$OLD_TARGET" || ! -d "$OLD_TARGET" ) ]]; then
  echo "Managed Team Hub update requires an existing installed release for verified rollback." >&2
  exit 1
fi
if [[ "$CURRENT_LINK_WAS_DIRECTORY" == "true" ]]; then
  ORIGINAL_OLD_SOURCE="$CURRENT_LINK"
else
  ORIGINAL_OLD_SOURCE="$OLD_TARGET"
fi
ROLLBACK_RELEASE_ROOT="$ORIGINAL_OLD_SOURCE"
if [[ -n "$OLD_TARGET" && "$OLD_TARGET" == "$RELEASE_DIR" ]]; then
  REPLACED_DIR="$RELEASES_ROOT/$RELEASE_VERSION-replaced-$(date -u +%Y%m%d%H%M%S)-$$"
  OLD_TARGET="$REPLACED_DIR"
fi
if ! validate_managed_team_hub_inputs "$CURRENT_LINK"; then
  echo "Managed Team Hub inputs changed before candidate activation." >&2
  exit 1
fi
if [[ -z "$EXPECTED_SERVER_IDENTITY" \
  && -n "$OLD_TARGET" \
  && -e "$OLD_TARGET" ]]; then
  EXPECTED_SERVER_IDENTITY="$(read_owned_config_file \
    "$STATE_ROOT/server-identity")" || {
    echo "The existing release has no safely readable durable server identity." >&2
    exit 1
  }
  if [[ ! "$EXPECTED_SERVER_IDENTITY" =~ ^[A-Za-z0-9_.:-]{8,240}$ ]]; then
    echo "The existing release has an invalid durable server identity." >&2
    exit 1
  fi
fi

backup_runtime_configuration
if [[ -n "$EXPECTED_SERVER_IDENTITY" \
  && "$PREVIOUS_TEAM_HUB_MODE" == "disabled" \
  && "$TEAM_HUB_MODE" == "disabled" \
  && -n "$OLD_TARGET" \
  && -e "$OLD_TARGET" ]]; then
  echo "      Binding current Teamspace client state before takeover"
  if ! capture_managed_team_hub_client_binding \
      "$PRIOR_PORT" \
      "$STAGE_DIR" \
      "$EXPECTED_SERVER_IDENTITY" \
      "$PRIOR_BIND_ADDRESS"; then
    echo "Could not bind the current authenticated Teamspace client before candidate activation." >&2
    exit 1
  fi
fi
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  # Bind the externally-created update fence before the first link/service
  # mutation. A restart can then recover the exact operation without relying
  # on a fresh runner invocation carrying the original arguments.
  if ! record_activation_phase prepared "$STAGE_DIR"; then
    echo "The activation transaction could not bind the managed Team Hub update." >&2
    exit 1
  fi
fi
if ! assert_team_hub_config_unchanged \
  || ! assert_env_backup_team_hub_config; then
  echo "Team Hub configuration changed while its rollback image was captured." >&2
  exit 1
fi
COLD_TEAM_HUB_HANDOFF="false"
if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
  || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" \
  || "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  COLD_TEAM_HUB_HANDOFF="true"
  mask_install_signals
  if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
    || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
    if ! begin_team_hub_cold_guard; then
      resume_install_signals
      echo "The managed Team Hub could not establish its pre-takeover startup guard." >&2
      exit 1
    fi
    if ! record_activation_phase guarded "$STAGE_DIR"; then
      resume_install_signals
      echo "The activation transaction could not persist the Team Hub guard." >&2
      exit 1
    fi
  fi
fi

# Materialize and link the new runtime before asking the service manager to
# stop the old process. The already-published server-update fence or explicit
# startup guard means every manager/manual restart through the installed
# `current` path executes new fail-closed code; legacy beta.31 can never
# reacquire the Hub lease in the stop-to-snapshot handoff window.
if ! record_activation_phase linking "$STAGE_DIR"; then
  [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
  echo "The activation transaction could not enter link takeover." >&2
  exit 1
fi
RELEASE_ACTIVATED="true"
if ! activate_transaction_files "$STAGE_DIR"; then
  [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
  echo "The activation transaction could not complete the exact release/link takeover." >&2
  exit 1
fi
CANDIDATE_RUNTIME_ROOT="$RELEASE_DIR"
if ! record_activation_phase linked "$CANDIDATE_RUNTIME_ROOT"; then
  [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
  echo "The activation transaction could not prove the candidate link." >&2
  exit 1
fi

if [[ "$COLD_TEAM_HUB_HANDOFF" == "true" ]]; then
  # Mark the stop transaction before invoking the manager: bootout/stop may
  # commit even when its final acknowledgement fails.
  SERVICE_STOPPED_FOR_COLD_HANDOFF="true"
  if ! record_activation_phase stopping "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The activation transaction could not enter service stop." >&2
    exit 1
  fi
  if ! stop_service; then
    resume_install_signals
    echo "The managed Team Hub service stop could not be confirmed for its cold handoff." >&2
    exit 1
  fi
  if ! record_activation_phase stopped "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The activation transaction could not prove the service stop." >&2
    exit 1
  fi
fi

if [[ "$TEAM_HUB_REACTIVATION_REQUESTED" == "true" \
  || "$TEAM_HUB_FAILED_HOST_REPAIR_REQUESTED" == "true" ]]; then
  if ! record_activation_phase fencing "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The activation transaction could not enter Team Hub fencing." >&2
    exit 1
  fi
  if ! prepare_team_hub_reactivation; then
    resume_install_signals
    echo "The managed Team Hub could not establish its cold reactivation snapshot." >&2
    exit 1
  fi
fi
if ! validate_team_hub_reactivation_inputs "$CANDIDATE_RUNTIME_ROOT"; then
  [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
  echo "Team Hub reactivation inputs changed before candidate activation." >&2
  exit 1
fi
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
  if ! record_activation_phase fencing "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The activation transaction could not enter Team Hub snapshot rebase." >&2
    exit 1
  fi
  if ! rebase_team_hub_rollback_snapshot \
    || ! validate_managed_team_hub_inputs "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The managed Team Hub cold update handoff could not refresh and verify its rollback generation." >&2
    exit 1
  fi
fi
if [[ "$COLD_TEAM_HUB_HANDOFF" == "true" ]]; then
  if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" ]]; then
    # Snapshot rebase atomically replaces the fence. Re-read and journal the
    # exact new inode rather than carrying the pre-rebase identity forward.
    TEAM_HUB_OPERATION_FENCE_DEVICE=""
    TEAM_HUB_OPERATION_FENCE_INODE=""
  fi
  if ! record_activation_phase fenced "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The activation transaction could not bind the exact Team Hub fence." >&2
    exit 1
  fi
fi
write_runtime_env
if [[ "$TEAM_HUB_OPERATION_PENDING" == "true" \
  || "$TEAM_HUB_REACTIVATION_FENCE_PENDING" == "true" ]]; then
  # Journal cleanup ownership before publishing the authority file. A crash
  # after file publication but before the next phase can then clear it
  # idempotently instead of leaking stale one-shot authorization.
  TEAM_HUB_STARTUP_AUTHORITY_PENDING="true"
  if ! record_activation_phase authorizing "$CANDIDATE_RUNTIME_ROOT"; then
    [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
    echo "The activation transaction could not enter candidate authorization." >&2
    exit 1
  fi
  if ! team_hub_startup_authority_control \
      publish "$CANDIDATE_RUNTIME_ROOT"; then
    [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
    echo "The exact Team Hub candidate startup authority could not be persisted." >&2
    exit 1
  fi
  if ! record_activation_phase authority "$CANDIDATE_RUNTIME_ROOT"; then
    [[ "$COLD_TEAM_HUB_HANDOFF" != "true" ]] || resume_install_signals
    echo "The activation transaction could not persist candidate authorization." >&2
    exit 1
  fi
fi
if [[ "$TEAM_HUB_COLD_GUARD_PENDING" == "true" ]]; then
  if ! clear_team_hub_cold_guard "$CANDIDATE_RUNTIME_ROOT"; then
    resume_install_signals
    echo "The managed Team Hub startup guard could not be cleared after exact candidate authority was persisted." >&2
    exit 1
  fi
fi
if [[ "$COLD_TEAM_HUB_HANDOFF" == "true" ]]; then
  resume_install_signals
fi

# A requested port held by an authenticated AgentsServer is the service being
# replaced and will be released by restart_service. A listener that is present
# before restart and rejects the preserved token is treated as a conflict.
ORIGINAL_PORT="$PORT"
PORT_AUTO_SELECTED="false"
PORT_FALLBACK_BLOCKED="false"
port_fallback_attempt=0

while true; do
  # Select a fallback only for a listener that was present before this service
  # is restarted and does not authenticate with the preserved AgentsServer
  # token. A newly started but unhealthy AgentsServer must be rolled back, not
  # mistaken for a port conflict and silently moved to another port.
  if [[ "$PORT_FALLBACK" == "true" ]] \
    && port_has_listener "$PORT" \
    && ! service_manager_owns_listener "$PORT" "$CANDIDATE_RUNTIME_ROOT"; then
    echo "Port $PORT is already held by another process:" >&2
    describe_port_listener "$PORT" >&2
    if [[ "$TEAM_HUB_MODE" == "host" \
      && ( "$TEAM_HUB_TRANSPORT" != "loopback" \
        || -n "$TEAM_HUB_URL" \
        || -n "$TEAM_HUB_DIRECT_IP_URL" ) ]]; then
      echo "Automatic port fallback is unsafe while an external Team Hub route is configured." >&2
      PORT_FALLBACK_BLOCKED="true"
      break
    fi
    port_fallback_attempt=$((port_fallback_attempt + 1))
    candidate=$((ORIGINAL_PORT + port_fallback_attempt))
    while ((port_fallback_attempt <= PORT_FALLBACK_ATTEMPTS)) && ((candidate <= 65535)) && port_has_listener "$candidate"; do
      port_fallback_attempt=$((port_fallback_attempt + 1))
      candidate=$((ORIGINAL_PORT + port_fallback_attempt))
    done
    if ((port_fallback_attempt <= PORT_FALLBACK_ATTEMPTS)) && ((candidate <= 65535)); then
      PORT="$candidate"
      PORT_AUTO_SELECTED="true"
      write_runtime_env
      echo "Selecting port $PORT instead (attempt $port_fallback_attempt/$PORT_FALLBACK_ATTEMPTS)." >&2
      continue
    fi
    echo "Ran out of nearby free ports to try." >&2
  fi

  echo "[4/7] Installing the user service (port $PORT)"
  write_service_files
  if ! record_activation_phase candidate-starting "$CANDIDATE_RUNTIME_ROOT"; then
    echo "The activation transaction could not enter candidate startup." >&2
    exit 1
  fi
  CANDIDATE_SERVICE_MAY_HAVE_STARTED="true"
  if ! restart_service; then
    echo "AgentsServer $RELEASE_VERSION could not start; restoring the previous service when possible." >&2
    if restore_previous_release; then
      echo "The previous release and service were restored." >&2
    fi
    exit 1
  fi

  echo "[5/7] Waiting for authenticated health"
  if wait_for_release_health; then
    if ! record_activation_phase candidate-healthy "$CANDIDATE_RUNTIME_ROOT"; then
      echo "The healthy candidate could not persist its recoverable activation state." >&2
      exit 1
    fi
    # This phase is the irreversible boundary. Any failure after it must
    # complete the candidate commit on retry; it must never restore a snapshot
    # whose fence may already have been consumed.
    if ! record_activation_phase committing "$CANDIDATE_RUNTIME_ROOT"; then
      echo "The healthy candidate could not enter its exact commit boundary." >&2
      exit 1
    fi
    if ! complete_activation_commit; then
      echo "AgentsServer $RELEASE_VERSION passed its commit boundary but finalization remains pending." >&2
      exit 1
    fi
    break
  fi

  echo "AgentsServer $RELEASE_VERSION did not become healthy; rolling back." >&2
  PORT="$ORIGINAL_PORT"
  if restore_previous_release; then
    echo "The previous release was restored." >&2
  fi
  if [[ "$OS_NAME" == "Linux" ]]; then
    systemctl --user status "$SERVICE_NAME.service" --no-pager -l >&2 || true
  fi
  exit 1
done
if [[ "$PORT_FALLBACK_BLOCKED" == "true" ]]; then
  PORT="$ORIGINAL_PORT"
  return 1 2>/dev/null || exit 1
fi

echo "[6/7] Checking optional agent runtimes"
check_runtime_cli() {
  local name="$1"
  local install_hint="$2"
  if command -v "$name" >/dev/null 2>&1; then
    echo "      $CHECK_MARK $name found"
    return 0
  fi
  echo "      $CROSS_MARK $name not found - $install_hint"
  return 1
}
CLAUDE_READY="false"
CODEX_READY="false"
check_runtime_cli claude "npm install -g @anthropic-ai/claude-code, then run: claude" && CLAUDE_READY="true"
check_runtime_cli codex "npm install -g @openai/codex, then run: codex login" && CODEX_READY="true"
if [[ "$CLAUDE_READY" == "false" && "$CODEX_READY" == "false" ]]; then
  echo "      Sign in to at least one before starting a chat."
fi

setup_network_summary() {
  TAILSCALE_IP=""
  TAILSCALE_STATUS="unknown"
  TAILSCALE_BIND_MATCH="false"
  SERVER_LOCAL_ONLY="false"
  NETWORK_URLS=""
  SERVER_URL="$(health_origin "$PORT")"
  local network_bindings=""
  # The shipped helper emits only fixed keys and shell-quoted validated values.
  # Optional network diagnostics must not fail an already healthy installation.
  if network_bindings="$("$CURRENT_LINK/.venv/bin/python" \
      "$CURRENT_LINK/server_instances.py" _setup-network \
      --bind "$BIND_ADDRESS" --port "$PORT" 2>/dev/null)" \
      && [[ -n "$network_bindings" ]]; then
    eval "$network_bindings"
  fi
}

print_tailscale_summary() {
  case "$TAILSCALE_STATUS" in
    connected)
      if [[ "$TAILSCALE_BIND_MATCH" == "true" ]]; then
        echo "  $CHECK_MARK Tailscale already connected: http://$TAILSCALE_IP:$PORT (tailnet access rules still apply)"
      elif [[ "$SERVER_LOCAL_ONLY" == "true" ]]; then
        echo "  $DOT_MARK Tailscale already connected; this server is bound to localhost only, so phones cannot connect directly."
        echo "    For phone access, choose a reachable server bind: https://github.com/ZhengyiLuo/AgentsServer"
      else
        echo "  $DOT_MARK Tailscale already connected; its IPv4 address is not available on this server's configured bind."
        echo "    For tailnet access, review the server bind: https://github.com/ZhengyiLuo/AgentsServer"
      fi
      ;;
    disconnected)
      echo "  $DOT_MARK Tailscale already installed but not connected; no installation or configuration changes made."
      echo "    To connect from other networks, open Tailscale and sign in/connect."
      ;;
    not-installed)
      echo "  $DOT_MARK optional: Tailscale was not found; use your LAN address on the same network, or see https://tailscale.com/download"
      ;;
    unavailable)
      echo "  $DOT_MARK Tailscale already installed; connection status could not be checked. No setup changes made."
      echo "    Open Tailscale to check the connection, or try: tailscale status"
      ;;
    *)
      echo "  $DOT_MARK Tailscale connection status could not be checked; no installation or configuration changes made."
      echo "    If you use Tailscale, check its app or try: tailscale status"
      ;;
  esac
}

print_setup_checklist() {
  local network_ready="false"
  [[ "$TAILSCALE_STATUS" != "connected" || "$TAILSCALE_BIND_MATCH" != "true" ]] || network_ready="true"
  if [[ -z "$TMUX_WARNING" && "$network_ready" == "true" \
    && ( "$CLAUDE_READY" == "true" || "$CODEX_READY" == "true" ) ]]; then
    echo "  ${COLOR_GREEN}${COLOR_BOLD}You are all set${COLOR_RESET}"
    echo "  $CHECK_MARK tmux available"
    print_tailscale_summary
    return
  fi

  echo "  ${COLOR_BOLD}You already have${COLOR_RESET}"
  echo "  $CHECK_MARK AgentsServer running"
  if [[ -z "$TMUX_WARNING" ]]; then
    echo "  $CHECK_MARK tmux available"
  fi
  if [[ "$network_ready" == "true" ]]; then
    print_tailscale_summary
  elif [[ "$TAILSCALE_STATUS" == "connected" || "$TAILSCALE_STATUS" == "disconnected" || "$TAILSCALE_STATUS" == "unavailable" ]]; then
    echo "  $CHECK_MARK Tailscale installed"
  fi

  if [[ "$CLAUDE_READY" == "false" && "$CODEX_READY" == "false" ]]; then
    echo
    echo "  ${COLOR_BOLD}To start chats${COLOR_RESET}"
    echo "  $DOT_MARK Choose one agent CLI and sign in:"
    echo "    Claude Code: npm install -g @anthropic-ai/claude-code, then run: claude"
    echo "    Codex: npm install -g @openai/codex, then run: codex login"
  fi
  if [[ -n "$TMUX_WARNING" || "$network_ready" != "true" ]]; then
    echo
    echo "  ${COLOR_BOLD}Optional next steps${COLOR_RESET}"
    echo "  You can skip these unless you need the features below."
    if [[ -n "$TMUX_WARNING" ]]; then
      echo "  $DOT_MARK For persistent terminals, pane inspection and in-app updates, install tmux:"
      if [[ "$OS_NAME" == "Darwin" ]]; then
        echo "    With Homebrew: brew install tmux"
      else
        echo "    Use your package manager, for example: sudo apt install tmux"
      fi
    fi
    if [[ "$network_ready" != "true" ]]; then
      print_tailscale_summary
    fi
  fi
}

setup_network_summary

echo "[7/7] AgentsServer $RELEASE_VERSION is ready"
if [[ "$PRIOR_SERVICE_STATE" == "absent" && "$PRIOR_LEGACY_SERVICE_STATE" == "absent" && -z "$EXPECTED_SERVER_IDENTITY" ]]; then
  printf '\n%s%s\n%s\n%s%s\n' \
    "$COLOR_GREEN" '================================' \
    'Your new service is up!' \
    '================================' "$COLOR_RESET"
fi
echo
echo "  ${COLOR_BOLD}Server URL${COLOR_RESET}    $SERVER_URL"
if [[ -n "$NETWORK_URLS" ]]; then
  echo "  Other local/network addresses (reachability depends on network/firewall):"
  while IFS= read -r network_url; do
    [[ -z "$network_url" ]] || echo "    $network_url"
  done <<< "$NETWORK_URLS"
fi
echo
print_setup_checklist
if [[ "$PORT_AUTO_SELECTED" == "true" ]]; then
  echo
  echo "  $DOT_MARK port $ORIGINAL_PORT was already in use, installed on $PORT instead (--port pins an exact port unless --allow-port-fallback is supplied)"
fi
if [[ "$TEAM_HUB_MODE" == "host" ]]; then
  echo
  if [[ "$TEAM_HUB_TRANSPORT" == "tailscale_serve" ]]; then
    echo "  ${COLOR_BOLD}Teamspace host${COLOR_RESET} $TEAM_HUB_URL"
    echo "  $CHECK_MARK server bound to the expected private Tailscale Serve URL"
    echo "  $DOT_MARK verify the separately managed Serve listener with: tailscale serve status --json"
  fi
  if [[ -n "$TEAM_HUB_DIRECT_IP_URL" ]]; then
    echo "  ${COLOR_BOLD}Teamspace Direct IP (unencrypted, advanced)${COLOR_RESET} $TEAM_HUB_DIRECT_IP_URL"
    echo "  $CROSS_MARK plaintext route: IP address is routing only, not identity or Tailscale attestation"
  fi
  echo "  ${COLOR_BOLD}Team Hub host operator commands${COLOR_RESET}"
  printf '  Bootstrap proof: PYTHONPATH='
  printf '%q ' "$CURRENT_LINK"
  printf '%q ' "$CURRENT_LINK/.venv/bin/python"
  printf '%s ' -m agentsdock_team_hub.cli bootstrap-proof --data-dir
  printf '%q\n' "$STATE_ROOT/team-hub"
  printf '  Device recovery: PYTHONPATH='
  printf '%q ' "$CURRENT_LINK"
  printf '%q ' "$CURRENT_LINK/.venv/bin/python"
  printf '%s ' -m agentsdock_team_hub.cli device-recovery --data-dir
  printf '%q ' "$STATE_ROOT/team-hub"
  printf '%s\n' '--email EMAIL --device-label LABEL'
fi
echo
if [[ -z "$EXPECTED_SERVER_IDENTITY" ]]; then
  printf 'AGENTSDOCK_SETUP_RESULT={"server_url":"%s","access_token":"%s","service":"%s","tailscale_ip":"%s","server_version":"%s"}\n' \
    "$SERVER_URL" "$TOKEN" "$SERVICE_KIND" "$TAILSCALE_IP" "$RELEASE_VERSION"
  if interactive_token_output; then
    print_token_for_copy "$TOKEN"
  fi
fi