diff --git a/.github/workflows/plugin-ci-workflow.yml b/.github/workflows/plugin-ci-workflow.yml
index a1d1f6f..4d9e5f1 100644
--- a/.github/workflows/plugin-ci-workflow.yml
+++ b/.github/workflows/plugin-ci-workflow.yml
@@ -39,8 +39,8 @@ jobs:
 
       - name: Lint every PHP file
         run: |
-          if find . -path ./vendor -prune -o -name '*.php' -print \
-            | xargs -n1 php -l 2>&1 | grep -iv 'no syntax errors detected'; then
+          if find . -path ./vendor -prune -o -name '*.php' -print0 \
+            | xargs -0 -n1 php -l 2>&1 | grep -iv 'no syntax errors detected'; then
             echo "Syntax errors found at the declared PHP floor"
             exit 1
           fi
@@ -153,19 +153,18 @@ jobs:
 
     - name: Create MySQL Config
       run: |
-        echo -e "[client]\nuser = root\npassword = cactiroot\nhost = 127.0.0.1\n" > ~/.my.cnf
+        printf '[client]\nuser = root\npassword = cactiroot\nhost = 127.0.0.1\n' \
+          > "$RUNNER_TEMP/gpsmap-my.cnf"
 
     - name: Initialize Cacti Database
-      env:
-        MYSQL_AUTH_USR: '--defaults-file=~/.my.cnf'
       run: |
-        mysql $MYSQL_AUTH_USR -e 'CREATE DATABASE IF NOT EXISTS cacti;'
-        mysql $MYSQL_AUTH_USR -e "CREATE USER IF NOT EXISTS 'cactiuser'@'localhost' IDENTIFIED BY 'cactiuser';"
-        mysql $MYSQL_AUTH_USR -e "GRANT ALL PRIVILEGES ON cacti.* TO 'cactiuser'@'localhost';"
-        mysql $MYSQL_AUTH_USR -e "GRANT SELECT ON mysql.time_zone_name TO 'cactiuser'@'localhost';"
-        mysql $MYSQL_AUTH_USR -e "FLUSH PRIVILEGES;"
-        mysql $MYSQL_AUTH_USR cacti < ${{ github.workspace }}/cacti/cacti.sql
-        mysql $MYSQL_AUTH_USR -e "INSERT INTO settings (name, value) VALUES ('path_php_binary', '/usr/bin/php')" cacti
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e 'CREATE DATABASE IF NOT EXISTS cacti;'
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e "CREATE USER IF NOT EXISTS 'cactiuser'@'localhost' IDENTIFIED BY 'cactiuser';"
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e "GRANT ALL PRIVILEGES ON cacti.* TO 'cactiuser'@'localhost';"
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e "GRANT SELECT ON mysql.time_zone_name TO 'cactiuser'@'localhost';"
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e "FLUSH PRIVILEGES;"
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" cacti < ${{ github.workspace }}/cacti/cacti.sql
+        mysql --defaults-file="$RUNNER_TEMP/gpsmap-my.cnf" -e "INSERT INTO settings (name, value) VALUES ('path_php_binary', '/usr/bin/php')" cacti
 
     - name: Install Composer Dependencies
       run: |
@@ -212,11 +211,15 @@ jobs:
       run: |
         cd ${{ github.workspace }}/cacti
         sudo php cli/plugin_manage.php --plugin=gpsmap --install --enable
+        mysql -u cactiuser -p'cactiuser' -h 127.0.0.1 cacti -sN \
+          -e "SELECT COUNT(*) FROM information_schema.tables
+              WHERE table_schema = 'cacti' AND table_name = 'plugin_gpsmap_dns_cache';" \
+          | grep -qx '1'
 
     - name: Check PHP Syntax for Plugin
       run: |
         cd ${{ github.workspace }}/cacti/plugins/gpsmap
-        if find . -name '*.php' -exec php -l {} 2>&1 \; | grep -iv 'no syntax errors detected'; then
+        if find . -name '*.php' -print0 | xargs -0 -n1 php -l 2>&1 | grep -iv 'no syntax errors detected'; then
           echo "Syntax errors found!"
           exit 1
         fi
@@ -293,12 +296,15 @@ jobs:
         fi
         echo "Using host_template id $TPL"
         sudo php cli/add_device.php --description=mapped --ip=127.0.0.1 --template="$TPL"
+        sudo php cli/add_device.php --description=mapped-hostname --ip=localhost --template="$TPL"
         mysql -u cactiuser -p'cactiuser' -h 127.0.0.1 cacti \
-          -e "UPDATE host SET latitude='51.5074', longitude='-0.1278' WHERE description='mapped';"
+          -e "UPDATE host SET latitude='51.5074', longitude='-0.1278'
+              WHERE description IN ('mapped', 'mapped-hostname');"
         mysql -u cactiuser -p'cactiuser' -h 127.0.0.1 cacti \
           -e "INSERT INTO gpsmap_templates (templateID, templateName, upimage, recoverimage, downimage, AP)
               SELECT host_template_id, 'ci', 'Green.png', 'Orange.png', 'Red.png', 0
               FROM host WHERE description='mapped' LIMIT 1;"
+        sudo php plugins/gpsmap/gpsmap_dns.php
 
     - name: Run Cacti Poller
       run: |
@@ -325,6 +331,11 @@ jobs:
           cat all.xml
           exit 1
         fi
+        if ! grep -q 'address="localhost"' all.xml; then
+          echo "all.xml contains no hostname-resolved marker"
+          cat all.xml
+          exit 1
+        fi
 
     - name: View Cacti Logs
       if: always()
diff --git a/.gitignore b/.gitignore
index 9e104b5..d3d6561 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
 # review pipeline scratch
 .diffcheck.php
 .rv.tar
+tests/_dbg.php
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa14bcb..de4b99d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 ## Changelog
 
+--- 2.2 ---
+
+* issue#6, issue#104, issue#107, issue#109, issue#110: Refactor the poller for single-load dual-stack maps, asynchronous last-known-good DNS, thold-aware markers, and safe artifact pruning
+
 --- 2.1 ---
 
 * issue: Add gpsmap_templates table index to be unique by device template
diff --git a/INFO b/INFO
index 2b0f08a..229defe 100644
--- a/INFO
+++ b/INFO
@@ -1,6 +1,6 @@
 [info]
 name = gpsmap
-version = 2.1
+version = 2.2
 longname = Maps Plugin
 author = Andrew Aloia, Wixiweb, The Cacti Group
 email = 
diff --git a/README.md b/README.md
index 915acf5..9dfac0b 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,9 @@ Maps tab reads a static file instead of querying the database.
 
 ## Features
 
-* Devices plotted by latitude and longitude, coloured by Up, Recovering, Down,
-  Disabled or Undefined status
+* IPv4 and IPv6 Devices plotted by latitude and longitude, coloured by Up,
+  Recovering, Down, Disabled or Undefined status.  When thold is enabled, an
+  otherwise-up Device with an active threshold uses its Down icon
 
 * Per Device Template marker icons for the Up, Recovering and Down states
 
@@ -20,7 +21,7 @@ Maps tab reads a static file instead of querying the database.
   furthest Device sharing the Access Point's group number, and optionally
   limited to an arc
 
-* Drill down by subnet, from the first octet through to individual Devices
+* Drill down by subnet: /8, /16 and /24 for IPv4, and /16, /32 and /48 for IPv6
 
 * KML export alongside the XML, so the same data opens in Google Earth
 
@@ -55,8 +56,8 @@ JavaScript, and there is no workaround inside Cacti.
 
 Installing adds seven columns to Cacti's `host` table (`latitude`, `longitude`,
 `GPScoverage`, `start`, `stop`, `groupnum`, `rdistance`) and creates the
-`gpsmap_templates` table.  Uninstalling deliberately leaves both in place so
-coordinates survive an accidental removal.
+`gpsmap_templates` and `plugin_gpsmap_dns_cache` tables.  Uninstalling
+deliberately leaves them in place so coordinates survive an accidental removal.
 
 ## Configuration
 
@@ -139,13 +140,21 @@ Understanding the order of events explains most of what can go wrong.
 1. The poller runs and Cacti calls the plugin's `poller_bottom` hook.
 
 2. The plugin selects every Device whose Device Template appears in
-   `gpsmap_templates`, resolves each hostname to an address, and discards any
-   Device without coordinates or whose name does not resolve to IPv4.
+   `gpsmap_templates`.  Literal IPv4 and IPv6 addresses are used directly;
+   configured names use the last address in `plugin_gpsmap_dns_cache`.
 
 3. It writes `plugins/gpsmap/XML/all.xml`, `all.kml` and `all-top.html`, then
    repeats for each subnet prefix so the drill-down views are prebuilt.
 
-4. Opening the Maps tab serves a page that loads Google's map library and
+4. It starts a separate DNS refresh worker after publishing.  A newly configured
+   hostname can therefore appear on the following poll, while slow DNS never
+   holds up the poller.  A failed refresh retains the last-known address.
+
+5. Generated subnet files not refreshed for three poller intervals are removed.
+   Cleanup runs only after a successful Device query; unrelated files are never
+   touched.
+
+6. Opening the Maps tab serves a page that loads Google's map library and
    fetches the matching `.xml` file over HTTP.
 
 Nothing appears until a poll cycle has completed after configuration.  If
@@ -165,9 +174,14 @@ cycle has completed since both were set; and `plugins/gpsmap/XML` contains
 files newer than the last poll.
 
 **Some Devices are missing.**  A Device is skipped when it has no coordinates,
-when its hostname does not resolve to an IPv4 address, when its Device Template
-is not in Map Templates, or when it is disabled and Display Disabled Devices is
-off.
+when its hostname has no cached address yet, when its Device Template is not in
+Map Templates, or when it is disabled and Display Disabled Devices is off.  For
+a newly added hostname, allow one additional poll cycle for the asynchronous DNS
+worker to populate the cache.
+
+**An Up Device has a red marker.**  When the thold plugin is enabled, gpsmap
+uses the configured Down icon for an otherwise-up Device with any active,
+enabled threshold.  Disable or clear the threshold to restore the Up icon.
 
 **The XML directory is empty.**  The Data Collector cannot write to it.  Check
 ownership, permissions and SELinux context.  The Cacti log records a failure
diff --git a/gpsmap.php b/gpsmap.php
index d0fba7b..05e7156 100644
--- a/gpsmap.php
+++ b/gpsmap.php
@@ -21,22 +21,24 @@
 
 chdir('../../');
 include('./include/auth.php');
+require_once('./plugins/gpsmap/gpsmap_security.php');
 include_once('./plugins/gpsmap/includes/setup/show.php');
 include_once('./plugins/gpsmap/includes/setup/gpsmapinitial.php');
 $body = '';
 
 general_header();
 
-//set headers to NOT cache a page
-header("Cache-Control: no-cache, no-store, must-revalidate");
-header("Pragma: no-cache");
-header("Expires: 0");
+// set headers to NOT cache a page
+header('Cache-Control: no-cache, no-store, must-revalidate');
+header('Pragma: no-cache');
+header('Expires: 0');
 
-//decide what needs to be shown
+// decide what needs to be shown
 switch ($show) {
-	//selected nodes
+	// selected nodes
 	case 'setup':
 		$body = __('Please make sure to properly configure Maps first under Settings > Maps', 'gpsmap');
+
 		break;
 	default:
 		if (!$parameter) {
@@ -46,44 +48,44 @@
 		/* Reject any parameter that contains directory traversal sequences or
 		 * characters outside the safe set.  basename() alone does not strip
 		 * embedded ../ so we validate the whole value first. */
-		if (!preg_match('/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$/', $parameter)) {
+		if (!gpsmap_artifact_parameter_is_valid($parameter)) {
 			$parameter = 'all';
 		}
 
 		$fileLocation = './plugins/gpsmap/XML/' . $parameter . '-top.html';
 
 		if (file_exists($fileLocation)) {
-			echo file_get_contents($fileLocation);
+			print file_get_contents($fileLocation);
 		}
 
 		break;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 
 if ($show != 'setup') { ?>
 	<script type='text/javascript'>
-		var initialLat      = <?php echo is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
-		var initialLng      = <?php echo is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
-		var initialZoom     = <?php echo json_encode((int) $initialzoom); ?>;
+		var initialLat      = <?php print is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
+		var initialLng      = <?php print is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
+		var initialZoom     = <?php print json_encode((int) $initialzoom); ?>;
 	</script>
 	<script type='text/javascript'>
-		gpsmap.refreshMap      = <?php echo json_encode((string) $refreshMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.initialLat      = <?php echo is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
-		gpsmap.initialLng      = <?php echo is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
-		gpsmap.initialZoom     = <?php echo json_encode((int) $initialzoom); ?>;
+		gpsmap.refreshMap      = <?php print json_encode((string) $refreshMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.initialLat      = <?php print is_finite((float) $initialLat) ? json_encode((float) $initialLat) : '0'; ?>;
+		gpsmap.initialLng      = <?php print is_finite((float) $initialLong) ? json_encode((float) $initialLong) : '0'; ?>;
+		gpsmap.initialZoom     = <?php print json_encode((int) $initialzoom); ?>;
 		gpsmap.initialized     = false;
-		gpsmap.liColor         = <?php echo json_encode((string) $liColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.liWidth         = <?php echo json_encode((string) $liWidth, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.liOpa           = <?php echo json_encode((string) $liOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.fillColor       = <?php echo json_encode((string) $fillColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.fillOpa         = <?php echo json_encode((string) $fillOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.circleQuality   = <?php echo json_encode((string) $circleQuality, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.enableWeather   = <?php echo json_encode((string) $enableWeather, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.coverageOverlay = <?php echo json_encode((string) $coverageMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liColor         = <?php print json_encode((string) $liColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liWidth         = <?php print json_encode((string) $liWidth, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.liOpa           = <?php print json_encode((string) $liOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.fillColor       = <?php print json_encode((string) $fillColor, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.fillOpa         = <?php print json_encode((string) $fillOpa, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.circleQuality   = <?php print json_encode((string) $circleQuality, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.enableWeather   = <?php print json_encode((string) $enableWeather, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.coverageOverlay = <?php print json_encode((string) $coverageMap, JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
 		gpsmap.markerArray     = [];
-		gpsmap.downloadURL     = <?php echo json_encode($config['url_path'] . 'plugins/gpsmap/XML/' . $parameter . '.xml', JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
-		gpsmap.t_error         = <?php echo is_finite((float) $terror) ? json_encode((float) $terror) : '0'; ?>;
+		gpsmap.downloadURL     = <?php print json_encode($config['url_path'] . 'plugins/gpsmap/XML/' . $parameter . '.xml', JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_UNESCAPED_SLASHES); ?>;
+		gpsmap.t_error         = <?php print is_finite((float) $terror) ? json_encode((float) $terror) : '0'; ?>;
 
 		<?php include_once('plugins/gpsmap/includes/icons.php'); ?>
 		<?php include_once('plugins/gpsmap/includes/customicons.php'); ?>
@@ -101,7 +103,6 @@
 <div id="mouse-position"></div>
 <div id="map"></div>
 ';
-echo $body;
+print $body;
 
 bottom_footer();
-
diff --git a/gpsmap_dns.php b/gpsmap_dns.php
new file mode 100644
index 0000000..b9a4162
--- /dev/null
+++ b/gpsmap_dns.php
@@ -0,0 +1,13 @@
+#!/usr/bin/env php
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+chdir(__DIR__ . '/../../');
+require_once('./include/cli_check.php');
+require_once($config['base_path'] . '/plugins/gpsmap/includes/dns.php');
+
+exit(gpsmap_dns_refresh_exit_code());
diff --git a/gpsmap_security.php b/gpsmap_security.php
index c740535..fb36bc0 100644
--- a/gpsmap_security.php
+++ b/gpsmap_security.php
@@ -13,7 +13,29 @@
  * includes setup.php on install, uninstall and config check, so the poller
  * would not have them. */
 if (!defined('GPSMAP_ICON_EXTENSIONS')) {
-	define('GPSMAP_ICON_EXTENSIONS', array('png', 'jpg', 'jpeg', 'gif'));
+	define('GPSMAP_ICON_EXTENSIONS', ['png', 'jpg', 'jpeg', 'gif']);
+}
+
+if (!defined('GPSMAP_ARTIFACT_STEM_PATTERN')) {
+	define('GPSMAP_ARTIFACT_STEM_PATTERN', '/^(?:all|[0-9]+(?:\.[0-9]+){0,2}|v6-(?:16-[0-9a-f]{4}|32-[0-9a-f]{8}|48-[0-9a-f]{12}))$/');
+}
+
+if (!defined('GPSMAP_ARTIFACT_SUFFIXES')) {
+	define('GPSMAP_ARTIFACT_SUFFIXES', ['.xml', '.kml', '-top.html']);
+}
+
+function gpsmap_artifact_parameter_is_valid(string $value): bool {
+	return preg_match(GPSMAP_ARTIFACT_STEM_PATTERN, $value) === 1;
+}
+
+function gpsmap_artifact_filename_is_valid(string $filename): bool {
+	foreach (GPSMAP_ARTIFACT_SUFFIXES as $suffix) {
+		if (str_ends_with($filename, $suffix)) {
+			return gpsmap_artifact_parameter_is_valid(substr($filename, 0, -strlen($suffix)));
+		}
+	}
+
+	return false;
 }
 
 /* An icon's base name is emitted as a JavaScript assignment target
@@ -38,3 +60,47 @@ function gpsmap_normalize_icon_name($value, $icon_array, $default = 'Green.png')
 
 	return $value;
 }
+
+// ---------------------------------------------------------------
+function getIcons() {
+	$iconArray = [];
+	global $config;
+
+	/* Built from base_path so poller and CLI callers resolve it too; only web
+	 * entry points chdir() to the Cacti root. */
+	$dir = $config['base_path'] . '/plugins/gpsmap/images/icons';
+
+	/* Suppressed rather than warned: this runs on the Map Templates page, and a
+	 * missing icon folder should not print a PHP warning into the form. */
+	$icons = @opendir($dir);
+
+	if ($icons === false) {
+		cacti_log('WARNING: gpsmap could not open icon directory ' . $dir, false, 'GPSMAP');
+
+		return $iconArray;
+	}
+
+	while (false !== ($icon = readdir($icons))) {
+		if (!is_file($dir . '/' . $icon)) {
+			continue;
+		}
+
+		/* Offer only names the map can actually render.  icons.php emits each
+		 * base name as a JavaScript identifier, so a file this rule rejects
+		 * would appear in the dropdown, save cleanly, and then silently fail
+		 * to draw. */
+		if (!in_array(strtolower(pathinfo($icon, PATHINFO_EXTENSION)), GPSMAP_ICON_EXTENSIONS, true)) {
+			continue;
+		}
+
+		if (gpsmap_icon_identifier($icon) === null) {
+			continue;
+		}
+
+		$iconArray[$icon] = $icon;
+	}
+
+	closedir($icons);
+
+	return $iconArray;
+}
diff --git a/gpstemplates.php b/gpstemplates.php
index ebc57ff..a0fd6f5 100644
--- a/gpstemplates.php
+++ b/gpstemplates.php
@@ -23,9 +23,9 @@
 include_once('./include/auth.php');
 include_once('./plugins/gpsmap/gpsmap_security.php');
 
-$ds_actions = array(
+$ds_actions = [
 	1 => __('Delete')
-);
+];
 
 set_default_action();
 
@@ -52,10 +52,11 @@
 		top_header();
 		templates();
 		bottom_footer();
+
 		break;
 }
 
-//------------------------------------------------------------------------------
+// ------------------------------------------------------------------------------
 function templates() {
 	global $config, $ds_actions;
 
@@ -63,13 +64,13 @@ function templates() {
 
 	html_start_box(__('Map Templates', 'gpsmap'), '100%', false, '3', 'center', 'gpstemplates.php?action=edit');
 
-	$display_text = array(
-		__('Host Template', 'gpsmap'), 
-		__('Up Image', 'gpsmap'), 
-		__('Recovering Image', 'gpsmap'), 
-		__('Down Image', 'gpsmap'), 
+	$display_text = [
+		__('Host Template', 'gpsmap'),
+		__('Up Image', 'gpsmap'),
+		__('Recovering Image', 'gpsmap'),
+		__('Down Image', 'gpsmap'),
 		__('Is AP', 'gpsmap')
-	);
+	];
 
 	html_header_checkbox($display_text);
 
@@ -79,7 +80,7 @@ function templates() {
 
 	if (cacti_sizeof($template_list)) {
 		foreach ($template_list as $template) {
-			if($template['AP']) {
+			if ($template['AP']) {
 				$isAP = __('True', 'gpsmap');
 			} else {
 				$isAP = __('False', 'gpsmap');
@@ -88,7 +89,7 @@ function templates() {
 			$url = $config['url_path'] . 'plugins/gpsmap/gpstemplates.php?action=edit&id=' . $template['templateID'];
 
 			form_alternate_row('line' . $template['templateID'], true);
-			form_selectable_cell("<a class='linkEditMain' href='$url'>" . html_escape($template['templateName']) . "</a>", $template['templateID']);
+			form_selectable_cell("<a class='linkEditMain' href='" . html_escape($url) . "'>" . html_escape($template['templateName']) . '</a>', $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['upimage']) . "'>", $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['recoverimage']) . "'>", $template['templateID']);
 			form_selectable_cell("<img src='" . $config['url_path'] . 'plugins/gpsmap/images/icons/' . html_escape($template['downimage']) . "'>", $template['templateID']);
@@ -107,12 +108,12 @@ function templates() {
 	form_end();
 }
 
-//------------------------------------------------------------------------------
+// ------------------------------------------------------------------------------
 function template_delete() {
-	foreach($_POST as $t=>$v) {
+	foreach ($_POST as $t=>$v) {
 		if (substr($t, 0,4) == 'chk_') {
 			$id = substr($t, 4);
-			db_execute_prepared('DELETE FROM gpsmap_templates WHERE templateID = ?', array($id));
+			db_execute_prepared('DELETE FROM gpsmap_templates WHERE templateID = ?', [$id]);
 		}
 	}
 
@@ -120,61 +121,61 @@ function template_delete() {
 	exit;
 }
 
-//------------------------------------------------------------------------------
+// ------------------------------------------------------------------------------
 function template_edit() {
 	global $config;
 
 	$template = db_fetch_row_prepared('SELECT * 
 		FROM `gpsmap_templates` 
-		WHERE templateID = ?', 
-		array(get_filter_request_var('id')));
+		WHERE templateID = ?',
+		[get_filter_request_var('id')]);
 
-	//get all icons in the icon folder
+	// get all icons in the icon folder
 	$iconArray = getIcons();
 
-	$form_template = array(
-		'templateID' => array(
+	$form_template = [
+		'templateID' => [
 			'method'        => 'drop_sql',
 			'friendly_name' => __('Device Template', 'gpsmap'),
 			'description'   => __('Choose the Device Template to base this Map Template type.', 'gpsmap'),
 			'value'         => '|arg1:templateID|',
 			'sql'           => 'SELECT id, name FROM host_template ORDER BY name ASC'
-		),
-		'upimage' => array(
+		],
+		'upimage' => [
 			'method'        => 'drop_array',
 			'friendly_name' => __('Up Image', 'gpsmap'),
 			'description'   => __('Select the Image to Show for an Up Device', 'gpsmap'),
 			'value'         => '|arg1:upimage|',
 			'default'       => 'Green.png',
 			'array'         => $iconArray
-		),
-		'recoverimage' => array(
+		],
+		'recoverimage' => [
 			'method'        => 'drop_array',
 			'friendly_name' => __('Recovering Image', 'gpsmap'),
 			'description'   => __('Select the Image to Show for a Recovering Device', 'gpsmap'),
 			'value'         => '|arg1:recoverimage|',
 			'default'       => 'Orange.png',
 			'array'         => $iconArray
-		),
-		'downimage' => array(
+		],
+		'downimage' => [
 			'method'        => 'drop_array',
 			'friendly_name' => __('Down Image', 'gpsmap'),
 			'description'   => __('Select the Image to Show for a Down Device', 'gpsmap'),
 			'value'         => '|arg1:downimage|',
 			'default'       => 'Red.png',
 			'array'         => $iconArray
-		),
-		'AP' => array(
+		],
+		'AP' => [
 			'method'        => 'drop_array',
 			'friendly_name' => __('Access Point', 'gpsmap'),
 			'description'   => __('Does this Device Template Represent an Access Point.', 'gpsmap'),
 			'value'         => '|arg1:AP|',
-			'array'         => array(
+			'array'         => [
 				0 => __('No', 'gpsmap'),
 				1 => __('Yes', 'gpsmap')
-			)
-		)
-	);
+			]
+		]
+	];
 
 	top_header();
 
@@ -183,10 +184,10 @@ function template_edit() {
 	html_start_box(__('Map Template Edit', 'gpsmap'), '100%', '', '3', 'center', '');
 
 	draw_edit_form(
-		array(
-			'config' => array('no_form_tag' => true),
+		[
+			'config' => ['no_form_tag' => true],
 			'fields' => inject_form_variables($form_template, $template)
-		)
+		]
 	);
 
 	?>
@@ -225,15 +226,14 @@ function template_edit() {
 	bottom_footer();
 }
 
-
-//------------------------------------------------------------------------------
+// ------------------------------------------------------------------------------
 function gpsmap_save_template() {
 	global $config;
 
 	$iconArray            = getIcons();
-	$save                 = array();
+	$save                 = [];
 	$save['templateID']   = get_filter_request_var('templateID');
-	$save['templateName'] = db_fetch_cell_prepared('SELECT name FROM host_template WHERE id = ?', array($save['templateID']));
+	$save['templateName'] = db_fetch_cell_prepared('SELECT name FROM host_template WHERE id = ?', [$save['templateID']]);
 	$save['upimage']      = gpsmap_normalize_icon_name(get_nfilter_request_var('upimage'), $iconArray, 'Green.png');
 	$save['recoverimage'] = gpsmap_normalize_icon_name(get_nfilter_request_var('recoverimage'), $iconArray, 'Orange.png');
 	$save['downimage']    = gpsmap_normalize_icon_name(get_nfilter_request_var('downimage'), $iconArray, 'Red.png');
@@ -251,30 +251,4 @@ function gpsmap_save_template() {
 	exit;
 }
 
-//------------------------------------------------------------------------------
-function getIcons() {
-	$iconArray = array();
-	$icons     = opendir('./plugins/gpsmap/images/icons');
-
-	while (false !== ($icon = readdir($icons))) {
-		if ($icon != '.' && $icon != '..') {
-			$iconExplode    = explode('.', $icon);
-			$iconExplode[1] = $iconExplode[1];
-
-			switch ($iconExplode[1]) {
-				case 'png':
-				case 'jpg':
-				case 'jpeg':
-				case 'gif':
-					$iconArray[$icon] = $icon;
-					break;
-				default:
-					break;
-			}
-		}
-	}
-
-	closedir($icons);
-
-	return $iconArray;
-}
+// ------------------------------------------------------------------------------
diff --git a/includes/customicons.php b/includes/customicons.php
index 97a4aba..c09bff6 100644
--- a/includes/customicons.php
+++ b/includes/customicons.php
@@ -20,9 +20,9 @@
 */
 
 require_once(__DIR__ . '/../gpsmap_security.php');
-//This file takes care of the individual assignments for each custom icon set for the map templates
-//This pulls the template from MySQL and attaches the Up/Down/Recover icon reference.
-//Basically this makes a mapping between template and icon.
+// This file takes care of the individual assignments for each custom icon set for the map templates
+// This pulls the template from MySQL and attaches the Up/Down/Recover icon reference.
+// Basically this makes a mapping between template and icon.
 
 $customiconlist = "gpsmap.customIcons = {};\n";
 
@@ -32,7 +32,8 @@ function gpsmap_safe_icon_base(string $filename): string {
 	return gpsmap_icon_identifier($filename) ?? 'undefined';
 }
 
-$results = db_fetch_assoc_prepared('SELECT * FROM gpsmap_templates ORDER BY templateID', array());
+$results = db_fetch_assoc_prepared('SELECT * FROM gpsmap_templates ORDER BY templateID', []);
+
 if (cacti_sizeof($results)) {
 	foreach ($results as $row) {
 		$tid          = (int) $row['templateID'];
@@ -40,18 +41,19 @@ function gpsmap_safe_icon_base(string $filename): string {
 		$down_base    = gpsmap_safe_icon_base($row['downimage']);
 		$recover_base = gpsmap_safe_icon_base($row['recoverimage']);
 
-		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'up')        . '] = gpsmap.' . $up_base      . ";\n";
-		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'down')       . '] = gpsmap.' . $down_base    . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'up') . '] = gpsmap.' . $up_base . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'down') . '] = gpsmap.' . $down_base . ";\n";
 		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'recovering') . '] = gpsmap.' . $recover_base . ";\n";
+		$customiconlist .= 'gpsmap.customIcons[' . json_encode($tid . 'alert') . '] = gpsmap.' . $down_base . ";\n";
 	}
 }
 
-//DO NOT REMOVE THESE
+// DO NOT REMOVE THESE
 $customiconlist .= "gpsmap.customIcons['up'] = gpsmap.Green;\n";
 $customiconlist .= "gpsmap.customIcons['recovering'] = gpsmap.Orange;\n";
+$customiconlist .= "gpsmap.customIcons['alert'] = gpsmap.Red;\n";
 $customiconlist .= "gpsmap.customIcons['down'] = gpsmap.Red;\n";
 $customiconlist .= "gpsmap.customIcons['disabled'] = gpsmap.Black;\n";
 $customiconlist .= "gpsmap.customIcons['undefined'] = gpsmap.Black;\n";
 
-echo $customiconlist;
-
+print $customiconlist;
diff --git a/includes/dns.php b/includes/dns.php
new file mode 100644
index 0000000..0df40de
--- /dev/null
+++ b/includes/dns.php
@@ -0,0 +1,162 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+*/
+
+function gpsmap_resolve_hostname(string $hostname, ?callable $lookup = null, ?callable $systemLookup = null): string {
+	if (filter_var($hostname, FILTER_VALIDATE_IP)) {
+		return $hostname;
+	}
+
+	$lookup ??= static fn (string $name): array|false => dns_get_record($name, DNS_A | DNS_AAAA);
+	$systemLookup ??= static fn (string $name): string|false => gethostbyname($name);
+	$records = @$lookup($hostname);
+
+	if (is_array($records)) {
+		// Preserve the resolver's ordering; both families are valid map addresses.
+		foreach ($records as $record) {
+			$address = $record['ip'] ?? $record['ipv6'] ?? '';
+
+			if (filter_var($address, FILTER_VALIDATE_IP)) {
+				return $address;
+			}
+		}
+	}
+
+	/* dns_get_record() bypasses the operating system's NSS sources. Keep this
+	 * fallback in the background worker so /etc/hosts, NIS and mDNS names work
+	 * without putting a blocking lookup back on the poller path. */
+	$address = @$systemLookup($hostname);
+
+	return is_string($address) && $address !== $hostname && filter_var($address, FILTER_VALIDATE_IP)
+		? $address
+		: '';
+}
+
+if (!defined('GPSMAP_DNS_REFRESH_BATCH_SIZE')) {
+	define('GPSMAP_DNS_REFRESH_BATCH_SIZE', 100);
+}
+
+if (!defined('GPSMAP_DNS_REFRESH_TIME_BUDGET')) {
+	define('GPSMAP_DNS_REFRESH_TIME_BUDGET', 300.0);
+}
+
+function gpsmap_refresh_dns_cache(?callable $resolver = null, ?callable $clock = null): int|false {
+	$resolver ??= static fn (string $name): string => gpsmap_resolve_hostname($name);
+	$clock ??= static fn (): float => hrtime(true) / 1e9;
+	$started = $clock();
+	$rows    = db_fetch_assoc_prepared('SELECT h.hostname, MIN(dc.attempted_at) AS attempted_at
+		FROM host AS h
+		INNER JOIN gpsmap_templates AS gt ON gt.templateID = h.host_template_id
+		LEFT JOIN plugin_gpsmap_dns_cache AS dc
+			ON dc.hostname_hash = UNHEX(SHA2(h.hostname, 256))
+		WHERE INET6_ATON(h.hostname) IS NULL
+			AND (dc.hostname_hash IS NULL
+				OR dc.attempted_at IS NULL
+				OR (dc.failure_count = 0 AND dc.attempted_at < NOW() - INTERVAL 1 HOUR)
+				OR (dc.failure_count BETWEEN 1 AND 3 AND dc.attempted_at < NOW() - INTERVAL 4 HOUR)
+				OR (dc.failure_count >= 4 AND dc.attempted_at < NOW() - INTERVAL 24 HOUR))
+		GROUP BY h.hostname
+		ORDER BY MIN(dc.attempted_at) IS NULL DESC, MIN(dc.attempted_at)
+		LIMIT ' . GPSMAP_DNS_REFRESH_BATCH_SIZE, []);
+
+	if ($rows === false) {
+		cacti_log('ERROR: gpsmap DNS refresh could not read the hostname cache work queue', false, 'GPSMAP');
+
+		return false;
+	}
+
+	$updated = 0;
+
+	foreach (array_slice($rows, 0, GPSMAP_DNS_REFRESH_BATCH_SIZE) as $row) {
+		if ($clock() - $started >= GPSMAP_DNS_REFRESH_TIME_BUDGET) {
+			cacti_log('WARNING: gpsmap DNS refresh reached its time budget; remaining names are deferred to the next worker run', false, 'GPSMAP');
+
+			break;
+		}
+
+		$hostname = (string) $row['hostname'];
+		$address = $resolver($hostname);
+
+		/* Keep the last successful address and its refreshed_at timestamp, but
+		 * record failed attempts. The poller uses that count to stop preserving a
+		 * permanently unresolved Device after a bounded grace period. */
+		if (!filter_var($address, FILTER_VALIDATE_IP)) {
+			cacti_log('WARNING: gpsmap DNS refresh could not resolve a configured hostname; retaining any last-known-good address', false, 'GPSMAP');
+			if (!db_execute_prepared('INSERT INTO plugin_gpsmap_dns_cache
+				(hostname_hash, hostname, address, attempted_at, failure_count)
+				VALUES (UNHEX(SHA2(?, 256)), ?, ?, NOW(), 1)
+				ON DUPLICATE KEY UPDATE
+					hostname = VALUES(hostname),
+					attempted_at = NOW(),
+					failure_count = LEAST(failure_count + 1, 65535)',
+				[$hostname, $hostname, ''])) {
+				cacti_log('ERROR: gpsmap DNS refresh could not record a failed hostname lookup', false, 'GPSMAP');
+
+				return false;
+			}
+
+			continue;
+		}
+
+		if (!db_execute_prepared('INSERT INTO plugin_gpsmap_dns_cache
+			(hostname_hash, hostname, address, refreshed_at, attempted_at, failure_count)
+			VALUES (UNHEX(SHA2(?, 256)), ?, ?, NOW(), NOW(), 0)
+			ON DUPLICATE KEY UPDATE
+				hostname = VALUES(hostname),
+				address = VALUES(address),
+				refreshed_at = NOW(),
+				attempted_at = NOW(),
+				failure_count = 0',
+			[$hostname, $hostname, $address])) {
+			cacti_log('ERROR: gpsmap DNS refresh could not store a resolved hostname', false, 'GPSMAP');
+
+			return false;
+		}
+
+		$updated++;
+	}
+
+	return $updated;
+}
+
+function gpsmap_run_dns_refresh_worker(?callable $refresh = null, ?callable $shutdownRegistrar = null): bool {
+	if (!register_process_start('gpsmap', 'dns-refresh', 0, 3600)) {
+		cacti_log('WARNING: gpsmap DNS refresh did not start because another worker owns the process registration', false, 'GPSMAP');
+
+		return false;
+	}
+
+	$refresh           ??= 'gpsmap_refresh_dns_cache';
+	$shutdownRegistrar ??= 'register_shutdown_function';
+	$registered          = true;
+	$release              = static function () use (&$registered): void {
+		if (!$registered) {
+			return;
+		}
+
+		unregister_process('gpsmap', 'dns-refresh', 0);
+		$registered = false;
+	};
+	$shutdownRegistrar($release);
+
+	try {
+		$result = $refresh();
+	} finally {
+		$release();
+	}
+
+	if ($result === false) {
+		return false;
+	}
+
+	set_config_option('plugin_gpsmap_dns_last_success', (string) time());
+
+	return true;
+}
+
+function gpsmap_dns_refresh_exit_code(): int {
+	return gpsmap_run_dns_refresh_worker() ? 0 : 1;
+}
diff --git a/includes/polling.php b/includes/polling.php
index 587abd8..4d498e0 100644
--- a/includes/polling.php
+++ b/includes/polling.php
@@ -19,87 +19,114 @@
  +-------------------------------------------------------------------------+
 */
 
+function gpsmap_schedule_dns_refresh(): void {
+	global $config;
+
+	if (!db_table_exists('plugin_gpsmap_dns_cache')) {
+		cacti_log('WARNING: gpsmap DNS cache table is unavailable; run the plugin upgrade to restore asynchronous hostname resolution', false, 'GPSMAP');
+
+		return;
+	}
+
+	$php = trim((string) read_config_option('path_php_binary'));
+
+	if ($php === '') {
+		cacti_log('WARNING: gpsmap DNS refresh was not scheduled because the PHP binary path is not configured', false, 'GPSMAP');
+
+		return;
+	}
+
+	exec_background($php, cacti_escapeshellarg($config['base_path'] . '/plugins/gpsmap/gpsmap_dns.php'));
+}
+
 function gpsmap_poller_bottom() {
 	global $config;
 
-	//Here we are getting the available hostnames (Numbers only) and
-	//Processing them to create our XML index arrays. So that it can
-	//pass an partial IP as a parameter to the region() function in
-	//the processregion.php file. Start with high subnet and work down.
 	include_once($config['base_path'] . '/plugins/gpsmap/includes/polling/functions.php');
+	include_once($config['base_path'] . '/plugins/gpsmap/includes/polling/processregion.php');
+
+	$start = microtime(true);
+	$state = new GpsmapPollState();
+
+	/* Load once.  Every subnet below is rendered from this same set, so the
+	 * device query and the DNS lookups happen a single time per poller cycle
+	 * rather than once per subnet. */
+	$hostArrays = gpsmap_load_devices(gpsmap_enable_all(), $state);
+	$mapped     = cacti_sizeof($hostArrays[0]) + cacti_sizeof($hostArrays[1]);
+
+	/* Start the resolver even when this cycle cannot safely publish. A cold
+	 * cache therefore heals in the background for the next poller cycle. */
+	gpsmap_schedule_dns_refresh();
+
+	/* Withhold publication only when the Device query itself failed.  An estate
+	 * with no mapped Devices is a real answer and has to be published, or a new
+	 * install never gets an all.xml at all and the map page fetches a 404. */
+	if ($state->loadFailed) {
+		cacti_log('WARNING: gpsmap could not read the Device list this cycle; the existing map has been left in place', false, 'GPSMAP');
 
-	$result      =  db_fetch_assoc('SELECT hostname, latitude, longitude
-		FROM host AS h
-		INNER JOIN gpsmap_templates AS gt
-		ON h.host_template_id = gt.templateID');
-
-	$firstArray  = array();
-	$secondArray = array();
-	$thirdArray  = array();
-	$totals      = 0;
-
-	if (cacti_sizeof($result)) {
-		foreach($result as $row){
-			if ($row['latitude'] != '0.000' && $row['longitude'] != '0.000') {
-				$totals++;
-
-				$hostname = gethostbyname($row['hostname']);
-
-				$indexes = explode('.', $hostname);
-
-				if (isset($indexes[0])) {
-					$first = $indexes[0];
-				} else {
-					$first = '';
-				}
-
-				if (isset($indexes[1])) {
-					$second = $indexes[1];
-				} else {
-					$second = '';
-				}
-
-				if (isset($indexes[2])) {
-					$third = $indexes[2];
-				} else {
-					$third = '';
-				}
-
-				if (isset($indexes[3])) {
-					$fourth = $indexes[3];
-				} else {
-					$fourth = '';
-				}
-
-				if (!in_array($first . '.', $firstArray)){
-					$firstArray[] = $first . '.';
-				}
-
-				if (!in_array($first . '.' . $second . '.', $secondArray)){
-					$secondArray[] = $first . '.' . $second . '.';
-				}
-
-				if (!in_array($first . '.' . $second . '.' . $third . '.', $thirdArray)){
-					$thirdArray[] = $first . '.' . $second . '.' . $third . '.';
-				}
-			}
-		}
+		return;
 	}
 
-	callRegion('all');
+	if ($state->unresolvedHostnames !== []) {
+		$unresolved_ids = implode(', ', array_slice($state->unresolvedDeviceIds, 0, 10));
 
-	if ($totals > 0) {
-		foreach($firstArray as $ip) {
-			callRegion($ip);
-		}
+		cacti_log(sprintf(
+			'WARNING: gpsmap has %d hostname(s) without a cached address (Device IDs: %s); last-known markers are retained and artifact pruning is deferred while the background resolver runs',
+			cacti_sizeof($state->unresolvedHostnames),
+			$unresolved_ids
+		), false, 'GPSMAP');
+	}
 
-		foreach($secondArray as $ip) {
-			callRegion($ip);
-		}
+	if ($state->expiredHostnames !== []) {
+		$expired_ids = implode(', ', array_slice($state->expiredDeviceIds, 0, 10));
 
-		foreach($thirdArray as $ip) {
-			callRegion($ip);
-		}
+		cacti_log(sprintf(
+			'WARNING: gpsmap omitted %d hostname(s) after repeated DNS failures or an expired cached address (Device IDs: %s); successful Devices and artifact pruning will continue',
+			cacti_sizeof($state->expiredHostnames),
+			$expired_ids
+		), false, 'GPSMAP');
 	}
-}
 
+	if ($state->staleHostnames !== []) {
+		$stale_ids = implode(', ', array_slice($state->staleDeviceIds, 0, 10));
+
+		cacti_log(sprintf(
+			'WARNING: gpsmap rendered %d hostname(s) from explicitly stale last-known-good DNS addresses (Device IDs: %s); verify the DNS worker configuration',
+			cacti_sizeof($state->staleHostnames),
+			$stale_ids
+		), false, 'GPSMAP');
+	}
+
+	if ($mapped === 0) {
+		cacti_log('NOTICE: gpsmap has no Devices to map.  Check that a Device Template is listed under Templates -> Map and that Devices have coordinates.', false, 'GPSMAP');
+	}
+
+	$prefixes = gpsmap_subnet_prefixes($hostArrays);
+
+	$published = gpsmap_render_region($hostArrays, 'all', $state);
+
+	foreach ($prefixes as $prefix) {
+		$rendered  = gpsmap_render_region($hostArrays, $prefix, $state);
+		$published = $rendered && $published;
+	}
+
+	/* Only a successful cycle may age out old snapshots. Three poller intervals
+	 * make absence persistent evidence instead of a transient partial result. */
+	$pruned = 0;
+
+	if ($published && $state->preservedArtifacts === []) {
+		$poller_interval = max(60, (int) read_config_option('poller_interval'));
+		$pruned          = gpsmap_prune_artifacts(time() - (3 * $poller_interval));
+	} elseif (!$published) {
+		cacti_log('WARNING: gpsmap did not prune artifacts because at least one map snapshot could not be published', false, 'GPSMAP');
+	}
+
+	cacti_log(sprintf(
+		'GPSMAP STATS: Mapped:%d Towers:%d Subnets:%d Pruned:%d Time:%0.2f',
+		$mapped,
+		cacti_sizeof($hostArrays[0]),
+		cacti_sizeof($prefixes),
+		$pruned,
+		microtime(true) - $start
+	), false, 'GPSMAP');
+}
diff --git a/includes/polling/functions.php b/includes/polling/functions.php
index d1b158f..ff9e0b3 100644
--- a/includes/polling/functions.php
+++ b/includes/polling/functions.php
@@ -20,7 +20,7 @@
 */
 
 require_once(__DIR__ . '/../../gpsmap_security.php');
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function callRegion(string $subnet): void {
 	global $config;
 
@@ -30,18 +30,18 @@ function callRegion(string $subnet): void {
 	region($subnet);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function getTowerIds(): array {
 	$results = db_fetch_assoc_prepared('SELECT `templateID`
 		FROM `gpsmap_templates`
-		WHERE `AP` = 1', array());
+		WHERE `AP` = 1', []);
 
 	/* 9999 is a sentinel that matches no host_template_id, so an empty
 	 * result set still produces a usable in_array() haystack. */
-	return cacti_sizeof($results) ? array_column($results, 'templateID') : array(9999);
+	return cacti_sizeof($results) ? array_column($results, 'templateID') : [9999];
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Returns the great-circle distance in kilometres (not metres, the constant
  * 6378.7 is Earth's mean radius in km).  Renamed from calcMeters to reflect
  * the actual unit; callers treating the result as metres will be off by 1000x.
@@ -58,15 +58,15 @@ function calcMeters(float $Lat1, float $Lon1, float $Lat2, float $Lon2): float {
 	return calcKm($Lat1, $Lon1, $Lat2, $Lon2);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function coordCheck(string $coords): string {
 	$coords = trim($coords);
 
-	//return 0.000 for anything unparseable, the user can correct the device
+	// return 0.000 for anything unparseable, the user can correct the device
 	return preg_match('#^-?\d{1,3}\.\d+$#', $coords) ? $coords : '0.000';
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Single writer for every generated artefact (XML, KML, top HTML) so the
  * failure path and its log message stay identical across all three. */
 function gpsmap_write_file(string $filename, string $contents): bool {
@@ -80,6 +80,10 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 	 * poller rewrites them, and rename() is atomic within a filesystem.  A
 	 * short write is a failure, so disk pressure cannot publish a truncated
 	 * document while reporting success. */
+	/* The temp file is a new inode, so it starts at 0666 & ~umask rather than
+	 * inheriting the destination's mode.  These files are read by the web
+	 * server, not the poller, so losing the mode breaks the map silently. */
+	$mode = file_exists($filename) ? (fileperms($filename) & 0777) : 0;
 	$temp = $filename . '.' . getmypid() . '.tmp';
 	$f    = @fopen($temp, 'w');
 
@@ -95,6 +99,14 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 		return $fail();
 	}
 
+	/* rename() already replaces an existing destination on every supported
+	 * platform, so a failure here is a filesystem or permission problem.
+	 * Unlinking first would destroy the last-good document without any
+	 * guarantee the retry succeeds, turning a stale map into a missing one. */
+	if ($mode !== 0) {
+		@chmod($temp, $mode);
+	}
+
 	if (!@rename($temp, $filename)) {
 		@unlink($temp);
 
@@ -104,20 +116,227 @@ function gpsmap_write_file(string $filename, string $contents): bool {
 	return true;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function gpsmap_xml_path(string $preemptive, string $extension): string {
 	global $config;
+	$stem = gpsmap_require_artifact_stem($preemptive);
+
+	return $config['base_path'] . '/plugins/gpsmap/XML/' . $stem . '.' . $extension;
+}
+
+// ---------------------------------------------------------------
+/* IPv4 keeps its historical dotted tokens.  IPv6 uses a reversible, filename
+ * safe token: v6-<prefix length>-<significant hex>. */
+function gpsmap_ipv6_prefix_token(string $address, int $length): ?string {
+	$packed = @inet_pton($address);
+
+	if ($packed === false || strlen($packed) !== 16 || !in_array($length, [16, 32, 48], true)) {
+		return null;
+	}
 
-	return $config['base_path'] . '/plugins/gpsmap/XML/' . trim($preemptive, '.') . '.' . $extension;
+	return 'v6-' . $length . '-' . substr(bin2hex($packed), 0, intdiv($length, 4));
 }
 
-//---------------------------------------------------------------
-function createDoc(array $hostArrays, string $preemptive): void {
-	xmlCreate($hostArrays, $preemptive);
-	kmlCreate($hostArrays, $preemptive);
+// ---------------------------------------------------------------
+function gpsmap_ipv6_prefix_label(string $token): ?string {
+	if (!preg_match('/^v6-(16|32|48)-([0-9a-f]+)$/', $token, $matches)) {
+		return null;
+	}
+
+	$length = (int) $matches[1];
+
+	if (strlen($matches[2]) !== intdiv($length, 4)) {
+		return null;
+	}
+
+	$packed = hex2bin(str_pad($matches[2], 32, '0'));
+
+	return inet_ntop($packed) . '/' . $length;
+}
+
+// ---------------------------------------------------------------
+function gpsmap_ipv6_prefix_contains(string $token, string $address): bool {
+	if (!preg_match('/^v6-(16|32|48)-([0-9a-f]+)$/', $token, $matches)) {
+		return false;
+	}
+
+	if (strlen($matches[2]) !== intdiv((int) $matches[1], 4)) {
+		return false;
+	}
+
+	$packed = @inet_pton($address);
+
+	return $packed !== false && strlen($packed) === 16 && str_starts_with(bin2hex($packed), $matches[2]);
+}
+
+// ---------------------------------------------------------------
+function gpsmap_artifact_stem(string $subnet): ?string {
+	$subnet = $subnet === '' ? 'all' : trim($subnet, '.');
+
+	return gpsmap_artifact_parameter_is_valid($subnet)
+		? $subnet
+		: null;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
+function gpsmap_require_artifact_stem(string $subnet): string {
+	$stem = gpsmap_artifact_stem($subnet);
+
+	if ($stem === null) {
+		throw new InvalidArgumentException('Invalid gpsmap artifact subnet');
+	}
+
+	return $stem;
+}
+
+// ---------------------------------------------------------------
+function gpsmap_artifact_subnet_is_valid(string $subnet): bool {
+	$normalized = $subnet === '' ? 'all' : trim($subnet, '.');
+
+	return gpsmap_artifact_stem($subnet) === $normalized;
+}
+
+final class GpsmapPollState {
+	public bool $loadFailed = false;
+	/** @var list<string> */
+	public array $unresolvedHostnames = [];
+	/** @var list<string> */
+	public array $unresolvedDeviceIds = [];
+	/** @var list<string> */
+	public array $expiredHostnames = [];
+	/** @var list<string> */
+	public array $expiredDeviceIds = [];
+	/** @var list<string> */
+	public array $staleHostnames = [];
+	/** @var list<string> */
+	public array $staleDeviceIds = [];
+	/** @var array<string, bool> */
+	public array $preservedArtifacts = [];
+
+	public function reset(): void {
+		$this->loadFailed          = false;
+		$this->unresolvedHostnames = [];
+		$this->unresolvedDeviceIds = [];
+		$this->expiredHostnames    = [];
+		$this->expiredDeviceIds    = [];
+		$this->staleHostnames      = [];
+		$this->staleDeviceIds      = [];
+		$this->preservedArtifacts  = [];
+	}
+}
+
+// Compatibility state for direct region() callers; the poller passes its own.
+function gpsmap_poll_state(): GpsmapPollState {
+	/** @var ?GpsmapPollState $state */
+	static $state = null;
+
+	return $state ??= new GpsmapPollState();
+}
+
+if (!defined('GPSMAP_PRESERVED_MARKER_TTL')) {
+	define('GPSMAP_PRESERVED_MARKER_TTL', 86400);
+}
+
+// ---------------------------------------------------------------
+function gpsmap_prune_artifacts(int $olderThan): int {
+	global $config;
+
+	$directory = $config['base_path'] . '/plugins/gpsmap/XML';
+	$removed   = 0;
+
+	foreach (glob($directory . '/*') ?: [] as $path) {
+		$name = basename($path);
+
+		if (!is_file($path) || filemtime($path) >= $olderThan || !gpsmap_artifact_filename_is_valid($name)) {
+			continue;
+		}
+
+		if (@unlink($path)) {
+			$removed++;
+		}
+	}
+
+	return $removed;
+}
+
+// ---------------------------------------------------------------
+function createDoc(array $hostArrays, string $preemptive, ?GpsmapPollState $state = null): bool {
+	$state ??= gpsmap_poll_state();
+	$xml_written = xmlCreate($hostArrays, $preemptive, $state);
+	$kml_written = kmlCreate($hostArrays, $preemptive, $state);
+
+	return $xml_written && $kml_written;
+}
+
+// ---------------------------------------------------------------
+function gpsmap_preserve_unresolved_markers(string $doc, string $preemptive, ?GpsmapPollState $state = null): string {
+	$state ??= gpsmap_poll_state();
+	$unresolved = array_fill_keys($state->unresolvedDeviceIds, true);
+
+	if ($unresolved === []) {
+		return $doc;
+	}
+
+	$stem     = gpsmap_require_artifact_stem($preemptive);
+	$previous = @file_get_contents(gpsmap_xml_path($stem, 'xml'));
+
+	if (!is_string($previous) || $previous === '') {
+		return $doc;
+	}
+
+	$current_xml  = new DOMDocument();
+	$previous_xml = new DOMDocument();
+
+	if (!@$current_xml->loadXML($doc, LIBXML_NONET) || !@$previous_xml->loadXML($previous, LIBXML_NONET)) {
+		return $doc;
+	}
+
+	$current_ids = [];
+
+	foreach ($current_xml->getElementsByTagName('marker') as $marker) {
+		$current_ids[$marker->getAttribute('id')] = true;
+	}
+
+	$preserved = false;
+	/** @var DOMElement $root */
+	$root      = $current_xml->documentElement;
+
+	foreach ($previous_xml->getElementsByTagName('marker') as $marker) {
+		$id = $marker->getAttribute('id');
+
+		if (!isset($unresolved[$id]) || isset($current_ids[$id])) {
+			continue;
+		}
+
+		$preserved_at = (int) $marker->getAttribute('gpsmapPreservedAt');
+
+		if ($preserved_at > 0 && $preserved_at < time() - GPSMAP_PRESERVED_MARKER_TTL) {
+			continue;
+		}
+
+		$copy = $current_xml->importNode($marker, true);
+
+		if ($copy instanceof DOMElement) {
+			$copy->setAttribute('gpsmapPreservedAt', (string) ($preserved_at > 0 ? $preserved_at : time()));
+			$copy->setAttribute('status', 'undefined');
+		}
+
+		$root->appendChild($copy);
+		$current_ids[$id] = true;
+		$preserved        = true;
+	}
+
+	if (!$preserved) {
+		return $doc;
+	}
+
+	$state->preservedArtifacts[$stem] = true;
+	$merged                           = $current_xml->saveXML($root);
+
+	return is_string($merged) ? $merged : $doc;
+}
+
+// ---------------------------------------------------------------
 /* The previous implementation processed '&' last, which re-encoded the '&'
  * already introduced by the earlier substitutions (e.g. '<' -> '&lt;' -> '&amp;lt;').
  * htmlspecialchars() with ENT_XML1 handles the correct order atomically. */
@@ -125,17 +344,18 @@ function parseToXML($htmlStr): string {
 	return htmlspecialchars((string) $htmlStr, ENT_XML1 | ENT_QUOTES, 'UTF-8');
 }
 
-//---------------------------------------------------------------
-function xmlCreate(array $hostArrays, string $preemptive): void {
+// ---------------------------------------------------------------
+function xmlCreate(array $hostArrays, string $preemptive, ?GpsmapPollState $state = null): bool {
 	$doc = '<markers>'
 		. createXMLNodes($hostArrays[1])
 		. coverageXML($hostArrays)
 		. '</markers>';
+	$doc = gpsmap_preserve_unresolved_markers($doc, $preemptive, $state);
 
-	gpsmap_write_file(gpsmap_xml_path($preemptive, 'xml'), $doc);
+	return gpsmap_write_file(gpsmap_xml_path($preemptive, 'xml'), $doc);
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function coverageXML(array $hostArrays): string {
 	global $config;
 
@@ -145,19 +365,58 @@ function coverageXML(array $hostArrays): string {
 	return $doc;
 }
 
-//---------------------------------------------------------------
-function kmlCreate(array $hostArrays, string $preemptive): void {
+// ---------------------------------------------------------------
+function kmlCreate(array $hostArrays, string $preemptive, ?GpsmapPollState $state = null): bool {
 	global $config;
+	gpsmap_require_artifact_stem($preemptive);
+
+	return (bool) require($config['base_path'] . '/plugins/gpsmap/includes/polling/kmlcreation.php');
+}
+
+// ---------------------------------------------------------------
+function gpsmap_preserved_kml_placemarks(string $preemptive): string {
+	$xml = new DOMDocument();
+
+	if (!@$xml->load(gpsmap_xml_path($preemptive, 'xml'), LIBXML_NONET)) {
+		return '';
+	}
+
+	$placemarks = '';
+
+	foreach ($xml->getElementsByTagName('marker') as $marker) {
+		if (!$marker->hasAttribute('gpsmapPreservedAt')) {
+			continue;
+		}
+
+		$lat = $marker->getAttribute('lat');
+		$lng = $marker->getAttribute('lng');
+
+		if (!is_numeric($lat) || !is_numeric($lng)) {
+			continue;
+		}
+
+		$name         = $marker->getAttribute('name');
+		$address      = $marker->getAttribute('address');
+		$availability = $marker->getAttribute('availability');
+		$placemarks  .= '<Placemark>'
+			. '<name>' . parseToXML($name) . '</name>'
+			. '<styleUrl>pushpin</styleUrl> '
+			. '<description>' . parseToXML($name) . PHP_EOL
+				. 'Availability: ' . parseToXML($availability) . PHP_EOL
+				. 'Address: ' . parseToXML($address) . '</description>'
+			. '<Point><coordinates>' . parseToXML($lng) . ',' . parseToXML($lat) . '</coordinates></Point>'
+			. '</Placemark>' . PHP_EOL;
+	}
 
-	require($config['base_path'] . '/plugins/gpsmap/includes/polling/kmlcreation.php');
+	return $placemarks;
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function createTypeArray(): array {
-	return array_column(db_fetch_assoc_prepared('SELECT `id`, `name` FROM `host_template`', array()), 'name', 'id');
+	return array_column(db_fetch_assoc_prepared('SELECT `id`, `name` FROM `host_template`', []), 'name', 'id');
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 /* Renders one <marker/>.  Device markers carry no radius and no schedule;
  * tower markers carry the computed coverage radius and their active window. */
 function gpsmap_marker(host $host, array $typeArray, string $radius, bool $withSchedule): string {
@@ -182,7 +441,7 @@ function gpsmap_marker(host $host, array $typeArray, string $radius, bool $withS
 	return $doc . 'group="' . parseToXML($host->group) . '" />' . "\n";
 }
 
-//---------------------------------------------------------------
+// ---------------------------------------------------------------
 function createXMLNodes(array $hostArray): string {
 	$typeArray = createTypeArray();
 	$doc       = '';
diff --git a/includes/polling/kmlcreation.php b/includes/polling/kmlcreation.php
index e920575..d8ba0c9 100644
--- a/includes/polling/kmlcreation.php
+++ b/includes/polling/kmlcreation.php
@@ -30,7 +30,7 @@
 $kmldoc .= '<name>Map Points</name>' . "\n";
 $kmldoc .= iconskml();
 
-//fallback style for any placemark whose icon is not in the icon folder
+// fallback style for any placemark whose icon is not in the icon folder
 $kmldoc .= '<Style id="pushpin">'
 	. '<IconStyle id="mystyle">'
 	. '<Icon>'
@@ -42,8 +42,13 @@
 
 foreach ($hostArrays as $hostArray) {
 	foreach ($hostArray as $host) {
+		if ($host->showMap !== 1) {
+			continue;
+		}
+
 		$image = match ($host->status) {
-			'down'       => $host->downimage,
+			'down',
+			'alert'      => $host->downimage,
 			'recovering' => $host->recoverimage,
 			default      => $host->upimage,
 		};
@@ -72,6 +77,8 @@
 	}
 }
 
+$kmldoc .= gpsmap_preserved_kml_placemarks($preemptive);
+
 $kmldoc .= '</Document></kml>';
 
-gpsmap_write_file(gpsmap_xml_path($preemptive, 'kml'), $kmldoc);
+return gpsmap_write_file(gpsmap_xml_path($preemptive, 'kml'), $kmldoc);
diff --git a/includes/polling/processregion.php b/includes/polling/processregion.php
index 3ad8e7c..a9efaa2 100644
--- a/includes/polling/processregion.php
+++ b/includes/polling/processregion.php
@@ -19,65 +19,147 @@
  +-------------------------------------------------------------------------+
 */
 
-//this function is called to process the nodes and get them ready for analysis
-//---------------------------------------------------------------
+/* The poller renders one file set per subnet prefix.  Loading the device list
+ * is the expensive part -- one query plus a DNS lookup per device -- so it
+ * happens once in gpsmap_load_devices() and every render reuses the result.
+ * region() keeps the old load-then-render shape for single callers. */
+
+if (!defined('GPSMAP_DNS_PRESERVE_FAILURE_LIMIT')) {
+	define('GPSMAP_DNS_PRESERVE_FAILURE_LIMIT', 3);
+}
+
+// ---------------------------------------------------------------
 function region(string $subnet): void {
-	global $config;
+	$state      = gpsmap_poll_state();
+	$hostArrays = gpsmap_load_devices(gpsmap_enable_all(), $state);
+
+	gpsmap_render_region($hostArrays, $subnet, $state);
+}
 
-	/* Read the setting here rather than through a global.  pollinginitial.php
-	 * assigns $enableAll, but it is include_once'd from inside callRegion(), so
-	 * the assignment binds to that function's scope and the global was always
-	 * null: the setting has never taken effect.  Cacti's checkbox convention is
-	 * 'on' when ticked and '' otherwise. */
-	$enableAll = (read_config_option('gpsmap_enableall') === 'on');
-	$towerIds  = getTowerIds();
+// ---------------------------------------------------------------
+/* One query and no synchronous DNS. Returns array(towers, devices) in the
+ * order coveragexml.php and xmlCreate() expect. */
+function gpsmap_enable_all(): bool {
+	/* pollinginitial.php assigns $enableAll from inside callRegion(), so the
+	 * global that used to be read here was never bound and the setting was
+	 * inert.  Read it where it is needed instead. */
+	return read_config_option('gpsmap_enableall') === 'on';
+}
+
+// ---------------------------------------------------------------
+function gpsmap_load_devices(bool $enableAll, ?GpsmapPollState $state = null, ?callable $fallbackResolver = null): array {
+	global $config;
+	$state ??= gpsmap_poll_state();
+	$state->reset();
 
 	include_once($config['base_path'] . '/plugins/gpsmap/class/hosts_class.php');
 
-	/* Per-call output.  This used to be a global that region() had to blank on
-	 * the way out; the poller calls region() once per subnet, so a missed reset
-	 * concatenated every earlier subnet's navigation into the next file. */
-	$body       = '';
-	$kmlDomain  = read_config_option('base_url');
-	$iparray    = array();
-	$ipwriteout = array();
-	$hostArray  = array();
-	$towerArray = array();
+	$towerIds = getTowerIds();
 
-	/* Select only the columns used by region()/createDoc().  Avoids pulling
-	 * SNMP credentials (snmp_community, snmp_auth_passphrase, etc.) into PHP
+	/* Select only the columns used by the renderers.  Avoids pulling SNMP
+	 * credentials (snmp_community, snmp_auth_passphrase, etc.) into PHP
 	 * memory on every poller cycle. */
-	$sql = 'SELECT h.id, h.host_template_id, h.hostname, h.description,
+	$has_dns   = db_table_exists('plugin_gpsmap_dns_cache');
+
+	if (!$has_dns) {
+		include_once($config['base_path'] . '/plugins/gpsmap/includes/dns.php');
+		$fallbackResolver ??= 'gpsmap_resolve_hostname';
+		cacti_log('WARNING: gpsmap DNS cache table is unavailable; resolving configured hostnames synchronously until the plugin upgrade succeeds', false, 'GPSMAP');
+	}
+
+	$has_thold = api_plugin_is_enabled('thold')
+		&& db_table_exists('thold_data')
+		&& db_column_exists('thold_data', 'host_id', false)
+		&& db_column_exists('thold_data', 'thold_alert', false)
+		&& db_column_exists('thold_data', 'thold_enabled', false);
+	$sql       = 'SELECT h.id, h.host_template_id, h.hostname, h.description,
 		h.status, h.disabled, h.availability, h.cur_time,
 		h.latitude, h.longitude, h.start, h.stop, h.rdistance,
 		h.groupnum, h.GPScoverage,
-		gt.AP, gt.upimage, gt.downimage, gt.recoverimage
+		gt.AP, gt.upimage, gt.downimage, gt.recoverimage'
+		. ($has_dns ? ', dc.address AS cached_address,
+			dc.failure_count AS cache_failures,
+			(dc.refreshed_at >= NOW() - INTERVAL 24 HOUR) AS cache_is_fresh' : ', NULL AS cached_address,
+			0 AS cache_failures, 0 AS cache_is_fresh')
+		. ($has_thold ? ', COALESCE(td.thold_alarm, 0) AS thold_alarm' : ', 0 AS thold_alarm') . '
 		FROM `host` AS h
 		INNER JOIN gpsmap_templates AS gt
-		ON h.host_template_id = gt.templateID';
-
-	/* Cacti stores '' for enabled and 'on' for disabled. */
+		ON h.host_template_id = gt.templateID'
+		. ($has_dns ? '
+		LEFT JOIN plugin_gpsmap_dns_cache AS dc
+			ON dc.hostname_hash = UNHEX(SHA2(h.hostname, 256))' : '')
+		. ($has_thold ? '
+		LEFT JOIN (
+			SELECT host_id, MAX(thold_alert > 0) AS thold_alarm
+			FROM thold_data
+			WHERE thold_enabled = ?
+			GROUP BY host_id
+		) AS td ON td.host_id = h.id' : '');
+
+	// Cacti stores '' for enabled and 'on' for disabled.
 	$sql_where  = $enableAll ? '' : ' WHERE h.disabled = ?';
-	$sql_params = $enableAll ? array() : array('');
+	$sql_params = $has_thold ? ['on'] : [];
+
+	if (!$enableAll) {
+		$sql_params[] = '';
+	}
 
 	$results = db_fetch_assoc_prepared($sql . $sql_where . ' ORDER BY h.hostname', $sql_params);
 
-	/* Cache hostname -> IP resolutions so each hostname is resolved at most
-	 * once per region() call rather than twice (here and in the subnet loop).
-	 * Intentionally per-invocation with no TTL: the poller is batch-oriented
-	 * and stale entries within a single cycle are acceptable. If poller cycles
-	 * exceed 5 minutes, consider adding a TTL-based expiry. */
-	$dns_cache = array();
+	/* A failed query and an estate with no mapped Devices both arrive here as
+	 * an empty set.  Only the first is a reason to withhold publication, so the
+	 * caller is told which happened.
+	 *
+	 * false really is reachable: db_fetch_assoc_prepared() delegates to
+	 * db_execute_prepared(), which returns false on a connection failure, a
+	 * failed re-connect and an exhausted retry loop, and db_fetch_assoc_return()
+	 * documents itself as returning "the associated array of data, or false on
+	 * failure" (Cacti 1.2.x lib/database.php). */
+	$state->loadFailed = ($results === false);
+
+	$towerArray = [];
+	$hostArray  = [];
+
+	if (!cacti_sizeof($results)) {
+		return [$towerArray, $hostArray];
+	}
 
 	foreach ($results as $row) {
 		if ($row['latitude'] == '0.000' || $row['longitude'] == '0.000') {
 			continue;
 		}
 
-		$dns_cache[$row['hostname']] ??= gethostbyname($row['hostname']);
-		$hostip = $dns_cache[$row['hostname']];
+		/* Literal addresses need no DNS. Names use a recent asynchronously
+		 * refreshed cache value; the poller never blocks on a resolver. */
+		$is_literal = is_ipaddress($row['hostname']);
+		$cached     = (string) ($row['cached_address'] ?? '');
+
+		if (!$is_literal && !$has_dns && $fallbackResolver !== null) {
+			$cached = $fallbackResolver((string) $row['hostname']);
+		}
+
+		$hostip     = $is_literal ? $row['hostname'] : $cached;
+
+		/* A stale last-known-good address is degraded, not silently fresh. Maps are
+		 * operational context rather than an authorization boundary, so retaining
+		 * the last known position is safer than making the Device disappear when
+		 * the background worker is unavailable. */
+		if (!$is_literal && is_ipaddress($cached) && empty($row['cache_is_fresh'])) {
+			$state->staleHostnames[] = (string) $row['hostname'];
+			$state->staleDeviceIds[] = (string) $row['id'];
+		}
+
+		if (!is_ipaddress($hostip)) {
+			$failures = (int) ($row['cache_failures'] ?? 0);
+
+			if ($failures <= GPSMAP_DNS_PRESERVE_FAILURE_LIMIT) {
+				$state->unresolvedHostnames[] = (string) $row['hostname'];
+				$state->unresolvedDeviceIds[] = (string) $row['id'];
+			} else {
+				$state->expiredHostnames[] = (string) $row['hostname'];
+				$state->expiredDeviceIds[] = (string) $row['id'];
+			}
 
-		if (!is_ipaddress($hostip) || substr_count($hostip, '.') != 3) {
 			continue;
 		}
 
@@ -90,9 +172,11 @@ function region(string $subnet): void {
 
 		if ($row['disabled'] == 'on') {
 			$status = 'disabled';
+		} elseif ($status === 'up' && !empty($row['thold_alarm'])) {
+			$status = 'alert';
 		}
 
-		$is_tower = in_array($row['host_template_id'], $towerIds);
+		$is_tower = in_array($row['host_template_id'], $towerIds, true);
 
 		$host = new host(
 			$row['id'],
@@ -110,7 +194,7 @@ function region(string $subnet): void {
 			$row['upimage'] ?: 'Green',
 			$row['downimage'] ?: 'Red',
 			$row['recoverimage'] ?: 'Yellow',
-			/* Only towers carry a coverage window; devices use the full day. */
+			// Only towers carry a coverage window; devices use the full day.
 			$is_tower ? $row['start'] : '0',
 			$is_tower ? $row['stop'] : '360',
 			$row['groupnum'],
@@ -123,29 +207,122 @@ function region(string $subnet): void {
 		}
 	}
 
-	$hostArrays = array($towerArray, $hostArray);
-	$preempt    = ($subnet == 'all') ? 0 : str_word_count($subnet, 0, '.');
+	return [$towerArray, $hostArray];
+}
+
+// ---------------------------------------------------------------
+/* Rendering mutates showMap and grows tower radii, so the shared device set
+ * has to be returned to its loaded state before each subnet. */
+function gpsmap_reset_devices(array $hostArrays): void {
+	foreach ($hostArrays as $group) {
+		foreach ($group as $host) {
+			$host->showMap = 1;
+			$host->radius  = '0';
+		}
+	}
+}
+
+// ---------------------------------------------------------------
+/* Every distinct /8, /16 and /24 prefix present in the loaded device set.
+ * Derived from the already-resolved addresses, so no second DNS pass. */
+function gpsmap_subnet_prefixes(array $hostArrays): array {
+	/* Keyed rather than searched: in_array() over a growing list is quadratic in
+	 * the number of prefixes, which is material on a large estate. */
+	$prefixes = [];
 
-	//This section deals with traversal of the subnets
-	//sort by top level, and display all top IP range so they can be selected, and iterate this down through level 4
-	//if subnet level is met we want to display the lower ones.
-	//for 1 we want to display all top level IP
 	foreach ($hostArrays as $group) {
 		foreach ($group as $host) {
-			$dns_cache[$host->hostname] ??= gethostbyname($host->hostname);
+			if (filter_var($host->iprange, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
+				for ($depth = 1; $depth <= 3; $depth++) {
+					$token = gpsmap_ipv6_prefix_token($host->iprange, $depth * 16);
 
-			/* pad to 4 elements so destructuring is safe when the name did not
-			 * resolve to a dotted-quad. */
-			[$first, $second, $third, $fourth] = array_pad(explode('.', $dns_cache[$host->hostname]), 4, '0');
+					if ($token !== null) {
+						$prefixes[$token] = true;
+					}
+				}
+
+				continue;
+			}
+
+			$octets = array_pad(explode('.', $host->iprange), 4, '0');
+
+			for ($depth = 1; $depth <= 3; $depth++) {
+				$prefixes[implode('.', array_slice($octets, 0, $depth)) . '.'] = true;
+			}
+		}
+	}
+
+	return array_keys($prefixes);
+}
+
+// ---------------------------------------------------------------
+function gpsmap_render_region(array $hostArrays, string $subnet, ?GpsmapPollState $state = null): bool {
+	global $config;
+	$state ??= gpsmap_poll_state();
+
+	if (!gpsmap_artifact_subnet_is_valid($subnet)) {
+		cacti_log('WARNING: gpsmap refused to render an invalid subnet artifact target', false, 'GPSMAP');
+
+		return false;
+	}
+
+	$subnet = gpsmap_require_artifact_stem($subnet);
+
+	gpsmap_reset_devices($hostArrays);
+
+	$kmlDomain  = read_config_option('base_url');
+	$body       = '';
+	$iparray    = [];
+	$ipwriteout = [];
+	$is_all     = $subnet === 'all';
+	$is_v6      = str_starts_with($subnet, 'v6-');
+	$preempt    = $is_all ? 0 : ($is_v6 ? (int) explode('-', $subnet, 3)[1] / 16 : substr_count($subnet, '.') + 1);
+
+	// This section deals with traversal of the subnets
+	// sort by top level, and display all top IP range so they can be selected, and iterate this down through level 4
+	// if subnet level is met we want to display the lower ones.
+	// for 1 we want to display all top level IP
+	foreach ($hostArrays as $group) {
+		foreach ($group as $host) {
+			$host_is_v6 = filter_var($host->iprange, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6) !== false;
+
+			if ($is_v6 || ($is_all && $host_is_v6)) {
+				if (!$host_is_v6 || (!$is_all && !gpsmap_ipv6_prefix_contains($subnet, $host->iprange))) {
+					$host->showMap = 0;
+
+					continue;
+				}
+
+				$child = gpsmap_ipv6_prefix_token($host->iprange, ($preempt + 1) * 16);
+
+				if ($preempt === 3) {
+					if (!in_array($host->iprange, $iparray, true)) {
+						$iparray[]    = $host->iprange;
+						$ipwriteout[] = '<a href="' . $config['url_path'] . 'graph_view.php?action=preview&amp;reset=1&amp;host_id=' . $host->id . '">' . __('IP %s', html_escape($host->iprange), 'gpsmap') . '</a><br/>';
+					}
+				} elseif ($child !== null && !in_array($child, $iparray, true)) {
+					$iparray[] = $child;
+				}
+
+				continue;
+			}
+
+			if ($host_is_v6) {
+				$host->showMap = 0;
+
+				continue;
+			}
+
+			// iprange is the address gpsmap_load_devices() already resolved.
+			$octets = array_pad(explode('.', $host->iprange), 4, '0');
 
 			/* The prefix this host would contribute at the current depth, and
 			 * the prefix the requested subnet has to match for it to count. */
-			$octets = array($first, $second, $third, $fourth);
-			$parent = implode('.', array_slice($octets, 0, $preempt)) . '.';
+			$parent = implode('.', array_slice($octets, 0, $preempt));
 			$child  = implode('.', array_slice($octets, 0, $preempt + 1)) . '.';
 
 			if ($preempt > 3 || ($preempt > 0 && strcasecmp($subnet, $parent) !== 0)) {
-				//outside the requested subnet, keep it off the map
+				// outside the requested subnet, keep it off the map
 				$host->showMap = 0;
 
 				continue;
@@ -157,41 +334,42 @@ function region(string $subnet): void {
 				 * two Devices resolving to one address each emit a link. */
 				$leaf = rtrim($child, '.');
 
-				if (!in_array($leaf, $iparray)) {
+				if (!in_array($leaf, $iparray, true)) {
 					$iparray[]    = $leaf;
 					$ipwriteout[] = '<a href="' . $config['url_path'] . 'graph_view.php?action=preview&reset=1&host_id=' . $host->id . '">' . __('IP %s', $leaf) . '</a><br/>';
 				}
-			} elseif (!in_array($child, $iparray)) {
+			} elseif (!in_array($child, $iparray, true)) {
 				$iparray[] = $child;
 			}
 		}
 	}
 
-	//process data collected and create interface output
+	// process data collected and create interface output
 	if ($preempt != 3) {
 		foreach ($iparray as $ipout) {
-			$ipout = trim($ipout, '.');
+			$token = trim($ipout, '.');
+			$label = gpsmap_ipv6_prefix_label($token) ?? $token;
 
-			$ipwriteout[] = '<a href="' . html_escape($config['url_path'] . 'plugins/gpsmap/gpsmap.php?subnet=' . $ipout) . '">' . __('IP %s', $ipout, 'gpsmap') . '</a>-(<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $ipout . '.xml">X</a>-<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $ipout . '.kml">K</a>)<br/>';
+			$ipwriteout[] = '<a href="' . html_escape($config['url_path'] . 'plugins/gpsmap/gpsmap.php?subnet=' . rawurlencode($token)) . '">' . __('IP %s', html_escape($label), 'gpsmap') . '</a>-(<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $token . '.xml">X</a>-<a href="' . $kmlDomain . $config['url_path'] . 'plugins/gpsmap/XML/' . $token . '.kml">K</a>)<br/>';
 		}
 	}
 
-	//print out the information we have gathered.
+	// print out the information we have gathered.
 	$body .= '<div id="gpstopmenu" style="overflow: auto; width:100%; ">';
 	$body .= '<div id="gpsnav" style="overflow:auto; float:left; position:relative;"><input type="button" value="' . __esc('Start Over', 'gpsmap') . '" onclick="window.location.reload(true);" />';
 	$body .= '<input type="button" class="print" alt="" value="' . __esc('Print', 'gpsmap') . '" onclick="window.open(\'print.php\')" />';
 	$body .= '</div>';
 
-	//six links per column block
+	// six links per column block
 	foreach (array_chunk($ipwriteout, 6) as $chunk) {
 		$body .= '<div id="iplevels" style="display:table-cell;vertical-align:middle;overflow:auto;float:left;position:relative;"> ' . implode('', $chunk) . '</div>';
 	}
 
 	$body .= '</div>';
 
-	createDoc($hostArrays, $subnet === '' ? 'all' : $subnet);
-
-	$top = $config['base_path'] . '/plugins/gpsmap/XML/' . trim($subnet === '' ? 'all' : $subnet, '.') . '-top.html';
+	$documents_written = createDoc($hostArrays, $subnet, $state);
+	$menu_path         = $config['base_path'] . '/plugins/gpsmap/XML/' . $subnet . '-top.html';
+	$menu_written      = gpsmap_write_file($menu_path, $body);
 
-	gpsmap_write_file($top, $body);
+	return $documents_written && $menu_written;
 }
diff --git a/includes/setup/database.php b/includes/setup/database.php
index 5dc1926..5898554 100644
--- a/includes/setup/database.php
+++ b/includes/setup/database.php
@@ -19,52 +19,140 @@
  +-------------------------------------------------------------------------+
 */
 
-function gpsmap_upgrade_database() {
-	global $config, $database_default, $old;
+/* $old is the version being upgraded from.  It used to be read from a global
+ * that nothing ever set, which made every comparison below true and re-ran the
+ * whole migration history on every version change. */
+/* Backoff between attempts, so a failing migration cannot re-run an ALTER on
+ * Cacti's host table from every page view. */
+if (!defined('GPSMAP_UPGRADE_RETRY_SECONDS')) {
+	define('GPSMAP_UPGRADE_RETRY_SECONDS', 300);
+}
+
+if (!defined('GPSMAP_UPGRADE_MAX_FAILURES')) {
+	define('GPSMAP_UPGRADE_MAX_FAILURES', 5);
+}
+
+function gpsmap_upgrade_database(string $old = '', bool $force = false): void {
+	global $config;
 
 	include_once($config['library_path'] . '/database.php');
 
-	gpsmap_setup_database();
+	$v = plugin_gpsmap_version();
+
+	$retry_after = (int) read_config_option('plugin_gpsmap_upgrade_retry_after', true);
+	$failures    = (int) read_config_option('plugin_gpsmap_upgrade_failures', true);
+
+	if (!$force && $failures >= GPSMAP_UPGRADE_MAX_FAILURES) {
+		cacti_log('ERROR: gpsmap schema upgrade is suspended after repeated failures; use Plugin Management to retry after correcting the database error', false, 'GPSMAP');
+
+		return;
+	}
+
+	if (!$force && $retry_after > time()) {
+		cacti_log('NOTICE: gpsmap schema upgrade retry is deferred for another ' . ($retry_after - time()) . ' seconds', false, 'GPSMAP');
+
+		return;
+	}
+
+	/* gpsmap_setup_database() adds the host columns and creates the template
+	 * table, so its result belongs in the same gate as the migrations below. */
+	$ok = gpsmap_setup_database();
 
-	if ($old < '1.6'){
-		db_execute('ALTER TABLE host CHANGE COLUMN latitude latitude DECIMAL(13,10) NOT NULL;');
-		db_execute('ALTER TABLE host ALTER COLUMN latitude SET DEFAULT `0.0000000000`;');
-		db_execute('ALTER TABLE host CHANGE COLUMN longitude longitude DECIMAL(13,10) NOT NULL;');
-		db_execute('ALTER TABLE host ALTER COLUMN longitude SET DEFAULT `0.0000000000`;');
+	if (version_compare($old, '1.6', '<')) {
+		$ok = db_execute('ALTER TABLE host CHANGE COLUMN latitude latitude DECIMAL(13,10) NOT NULL DEFAULT 0.0000000000;') && $ok;
+		$ok = db_execute('ALTER TABLE host CHANGE COLUMN longitude longitude DECIMAL(13,10) NOT NULL DEFAULT 0.0000000000;') && $ok;
 	}
 
-	if ($old < '2.1') {
+	if (version_compare($old, '2.1', '<')) {
 		if (!db_index_exists('gpsmap_templates', 'templateID')) {
-			db_add_index('gpsmap_templates', 'unique', 'templateID', array('templateID'));
+			$ok = db_add_index('gpsmap_templates', 'unique', 'templateID', ['templateID']) && $ok;
 		}
 	}
 
 	include_once($config['base_path'] . '/plugins/gpsmap/setup.php');
+
+	/* Recorded last, and only when every migration reported success.
+	 * gpsmap_check_upgrade() gates on this option, so writing it earlier would
+	 * mark the plugin current even though a failed ALTER left the schema
+	 * behind, with no log line and no retry. */
+	if ($ok) {
+		/* Both records, together and only on success.  Plugin Management reads
+		 * plugin_config; gpsmap_check_upgrade() reads the settings option.
+		 * Writing either early reports the plugin current while the schema is
+		 * still behind. */
+		$ok = db_execute_prepared('UPDATE plugin_config SET version = ? WHERE directory = ?', [$v['version'], 'gpsmap']);
+	}
+
+	if ($ok) {
+		set_config_option('plugin_gpsmap_version', $v['version']);
+		set_config_option('plugin_gpsmap_upgrade_retry_after', '0');
+		set_config_option('plugin_gpsmap_upgrade_failures', '0');
+
+		return;
+	}
+
+	/* Never record the version here: doing so would report a schema the upgrade
+	 * knows is incomplete as current, and nothing would re-arm the migration
+	 * when the transient cause clears.  Back off instead, so a lock timeout
+	 * cannot turn ordinary page views into sustained contention on host. */
+	$failures++;
+	$retry_seconds = min(3600, GPSMAP_UPGRADE_RETRY_SECONDS * (2 ** min($failures - 1, 4)));
+	set_config_option('plugin_gpsmap_upgrade_failures', (string) $failures);
+	set_config_option('plugin_gpsmap_upgrade_retry_after', (string) (time() + $retry_seconds));
+
+	cacti_log('WARNING: gpsmap schema upgrade did not complete and will be retried after ' . $retry_seconds . ' seconds.  If it keeps failing, correct the database error and retry from Plugin Management.', false, 'GPSMAP');
 }
 
-function gpsmap_setup_database() {
-	$v = plugin_gpsmap_version();
+function gpsmap_setup_database(): bool {
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'latitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'longitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'GPScoverage', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'start', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'stop', 'type' => 'int(3)', 'NULL' => false, 'default' => '360', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'groupnum', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
+	api_plugin_db_add_column('gpsmap', 'host', ['name' => 'rdistance', 'type' => 'decimal(10,6)', 'NULL' => false, 'default' => '0', 'after' => 'availability']);
 
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'latitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'longitude', 'type' => 'decimal(13,10)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'GPScoverage', 'type' => 'varchar(3)', 'NULL' => false, 'default' => 'on', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'start', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'stop', 'type' => 'int(3)', 'NULL' => false, 'default' => '360', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'groupnum', 'type' => 'int(3)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-	api_plugin_db_add_column('gpsmap', 'host', array('name' => 'rdistance', 'type' => 'decimal(10,6)', 'NULL' => false, 'default' => '0', 'after' => 'availability'));
-
-	$data = array();
-	$data['columns'][] = array('name' => 'templateID', 'type' => 'int(11)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'templateName', 'type' => 'varchar(100)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'upimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'recoverimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'downimage', 'type' => 'varchar(255)', 'NULL' => true);
-	$data['columns'][] = array('name' => 'AP', 'type' => 'int(1)', 'NULL' => true);
-	$data['type'] = 'MyISAM';
-	$data['unique_keys'][] = array('name' => 'templateID' , 'columns' => 'templateID', 'unique' => true);
-	$data['comment'] = 'Map icon template';
+	$data                  = [];
+	$data['columns'][]     = ['name' => 'templateID', 'type' => 'int(11)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'templateName', 'type' => 'varchar(100)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'upimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'recoverimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'downimage', 'type' => 'varchar(255)', 'NULL' => true];
+	$data['columns'][]     = ['name' => 'AP', 'type' => 'int(1)', 'NULL' => true];
+	$data['type']          = 'InnoDB';
+	$data['unique_keys'][] = ['name' => 'templateID', 'columns' => 'templateID', 'unique' => true];
+	$data['comment']       = 'Map icon template';
 	api_plugin_db_table_create('gpsmap', 'gpsmap_templates', $data);
 
-	db_execute_prepared('UPDATE plugin_config SET version = ? WHERE directory = "gpsmap"', array($v['version']));
-}
+	$data                  = [];
+	/* The fixed-width hash supports the full DNS hostname length without
+	 * exceeding the 767-byte key limit on older InnoDB installations. */
+	$data['columns'][]     = ['name' => 'hostname_hash', 'type' => 'binary(32)', 'NULL' => false];
+	$data['columns'][]     = ['name' => 'hostname', 'type' => 'varchar(255)', 'NULL' => false, 'default' => ''];
+	$data['columns'][]     = ['name' => 'address', 'type' => 'varchar(45)', 'NULL' => false, 'default' => ''];
+	$data['columns'][]     = ['name' => 'refreshed_at', 'type' => 'timestamp', 'NULL' => false, 'default' => 'CURRENT_TIMESTAMP'];
+	$data['columns'][]     = ['name' => 'attempted_at', 'type' => 'timestamp', 'NULL' => true, 'default' => null];
+	$data['columns'][]     = ['name' => 'failure_count', 'type' => 'int(5) unsigned', 'NULL' => false, 'default' => '0'];
+	$data['primary']       = 'hostname_hash';
+	$data['keys'][]        = ['name' => 'refreshed_at', 'columns' => 'refreshed_at'];
+	$data['keys'][]        = ['name' => 'attempted_at', 'columns' => 'attempted_at'];
+	$data['type']          = 'InnoDB';
+	$data['comment']       = 'Asynchronously refreshed gpsmap hostname addresses';
+	api_plugin_db_table_create('gpsmap', 'plugin_gpsmap_dns_cache', $data);
+	api_plugin_db_add_column('gpsmap', 'plugin_gpsmap_dns_cache', ['name' => 'attempted_at', 'type' => 'timestamp', 'NULL' => true, 'default' => null, 'after' => 'refreshed_at']);
+	api_plugin_db_add_column('gpsmap', 'plugin_gpsmap_dns_cache', ['name' => 'failure_count', 'type' => 'int(5) unsigned', 'NULL' => false, 'default' => '0', 'after' => 'attempted_at']);
+
+	/* The Cacti helpers do not report failure consistently, so confirm the
+	 * schema directly rather than trusting their return values. */
+	foreach (['latitude', 'longitude', 'GPScoverage', 'start', 'stop', 'groupnum', 'rdistance'] as $column) {
+		if (!db_column_exists('host', $column)) {
+			return false;
+		}
+	}
 
+	return db_table_exists('gpsmap_templates')
+		&& db_table_exists('plugin_gpsmap_dns_cache')
+		&& db_column_exists('plugin_gpsmap_dns_cache', 'hostname_hash')
+		&& db_column_exists('plugin_gpsmap_dns_cache', 'attempted_at')
+		&& db_column_exists('plugin_gpsmap_dns_cache', 'failure_count');
+}
diff --git a/includes/towerSelect.php b/includes/towerSelect.php
deleted file mode 100644
index e42082c..0000000
--- a/includes/towerSelect.php
+++ /dev/null
@@ -1,47 +0,0 @@
-<?php
-/*
- +-------------------------------------------------------------------------+
- | Copyright (C) 2009-2013 Andrew Aloia                                    |
- | Copyright (C) 2014 Wixiweb                                              |
- | Copyright (C) 2004-2026 The Cacti Group                                 |
- |                                                                         |
- | This program is free software; you can redistribute it and/or           |
- | modify it under the terms of the GNU General Public License             |
- | as published by the Free Software Foundation; either version 2          |
- | of the License, or (at your option) any later version.                  |
- |                                                                         |
- | This program is distributed in the hope that it will be useful,         |
- | but WITHOUT ANY WARRANTY; without even the implied warranty of          |
- | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the           |
- | GNU General Public License for more details.                            |
- +-------------------------------------------------------------------------+
- | http://www.cacti.net/                                                   |
- +-------------------------------------------------------------------------+
-*/
-
-chdir('../../../');
-require_once('./include/auth.php');
-
-if (!isset($_SESSION['sess_user_id'])) {
-	exit;
-}
-
-if (function_exists('api_user_realm_auth') && !api_user_realm_auth('gpsmap.php')) {
-	exit;
-}
-
-$results = db_fetch_assoc_prepared("SELECT name, id FROM host_template", array());
-
-$body = '<ul>';
-
-if (cacti_sizeof($results)) {
-	foreach ($results as $row) {
-		$body .= '<li>' . html_escape($row['name']) . ' (ID: ' . html_escape($row['id']) . ')</li>';
-	}
-}
-
-$body .= '</ul>';
-
-print('<html>');
-print($body);
-print('</html>');
diff --git a/print.php b/print.php
index 7f4c628..79a53b8 100644
--- a/print.php
+++ b/print.php
@@ -20,9 +20,9 @@
 */
 
 chdir('../../');
+/* auth.php halts execution (exit/redirect) for unauthenticated users, so the
+ * markup below is only reached after successful authentication. */
 require_once('./include/auth.php');
-
-
 ?>
 <script language='javascript'>
 var mapEl = window.opener.document.getElementById('map');
diff --git a/setup.php b/setup.php
index ba181bd..728b248 100644
--- a/setup.php
+++ b/setup.php
@@ -37,9 +37,14 @@ function plugin_gpsmap_install() {
 
 	include_once($config['base_path'] . '/plugins/gpsmap/includes/setup/database.php');
 
-	gpsmap_setup_database();
-}
+	if (gpsmap_setup_database()) {
+		$version = plugin_gpsmap_version()['version'];
 
+		if (db_execute_prepared('UPDATE plugin_config SET version = ? WHERE directory = ?', [$version, 'gpsmap'])) {
+			set_config_option('plugin_gpsmap_version', $version);
+		}
+	}
+}
 
 function plugin_gpsmap_uninstall() {
 	/* Tables and settings created on install are intentionally left in place
@@ -50,11 +55,13 @@ function plugin_gpsmap_uninstall() {
 
 function plugin_gpsmap_check_config() {
 	gpsmap_check_upgrade();
+
 	return true;
 }
 
 function plugin_gpsmap_upgrade() {
-	gpsmap_check_upgrade();
+	gpsmap_check_upgrade(true);
+
 	return false;
 }
 
@@ -62,21 +69,22 @@ function plugin_gpsmap_version() {
 	return gpsmap_version();
 }
 
-function gpsmap_check_upgrade() {
+function gpsmap_check_upgrade(bool $force = false) {
 	global $config;
 
-	$files = array('gpsmap.php','gpstemplates.php','poller.php');
+	$files = ['gpsmap.php', 'gpstemplates.php', 'plugins.php', 'poller.php'];
 
-	if (!in_array(get_current_page(), $files)) {
+	if (!$force && !in_array(get_current_page(), $files, true)) {
 		return;
 	}
 
-	$info = plugin_gpsmap_version();
+	$info    = plugin_gpsmap_version();
 	$current = $info['version'];
-	$old = read_config_option('plugin_gpsmap_version', TRUE);
+	$old     = read_config_option('plugin_gpsmap_version', true);
+
 	if ($current != $old) {
 		include_once($config['base_path'] . '/plugins/gpsmap/includes/setup/database.php');
-		gpsmap_upgrade_database();
+		gpsmap_upgrade_database((string) $old, $force);
 	}
 
 	/* Migrate the misspelled 'gpsmap_latutude' key to 'gpsmap_latitude'.
@@ -86,12 +94,14 @@ function gpsmap_check_upgrade() {
 	 * against all known return values so the DELETE only fires when the old
 	 * key actually exists with a non-empty value. */
 	$old_lat = read_config_option('gpsmap_latutude');
+
 	if ($old_lat !== false && $old_lat !== null && $old_lat !== '') {
 		$current_lat = read_config_option('gpsmap_latitude');
+
 		if ($current_lat === false || $current_lat === null || $current_lat === '') {
 			set_config_option('gpsmap_latitude', $old_lat);
 		}
-		db_execute_prepared("DELETE FROM settings WHERE name = ?", array('gpsmap_latutude'));
+		db_execute_prepared('DELETE FROM settings WHERE name = ?', ['gpsmap_latutude']);
 	}
 }
 
@@ -108,49 +118,51 @@ function gpsmap_page_head() {
 function gpsmap_version() {
 	global $config;
 	$info = parse_ini_file($config['base_path'] . '/plugins/gpsmap/INFO', true);
+
 	return $info['info'];
 }
 
-//defines latitude and longitude for devices
+// defines latitude and longitude for devices
 function gpsmap_config_form() {
 	global $fields_host_edit, $url_path;
 
 	$fields_host_edit2 = $fields_host_edit;
-	$fields_host_edit3 = array();
+	$fields_host_edit3 = [];
 
 	foreach ($fields_host_edit2 as $f => $a) {
 		$fields_host_edit3[$f] = $a;
+
 		if ($f == 'disabled') {
-			$fields_host_edit3['gpsSpacer'] = array(
+			$fields_host_edit3['gpsSpacer'] = [
 				'friendly_name' => __('Map Settings', 'gpsmap'),
-				'method' => 'spacer',
-			);
+				'method'        => 'spacer',
+			];
 
-			$fields_host_edit3['GPScoverage'] = array(
+			$fields_host_edit3['GPScoverage'] = [
 				'friendly_name' => __('Overlay Inclusion', 'gpsmap'),
-				'description' => __('Disable to plot host only, not included in coverage overlay.', 'gpsmap'),
-				'method' => 'checkbox',
-				'value' => '|arg1:GPScoverage|',
-				'default' => 'on',
-			);
+				'description'   => __('Disable to plot host only, not included in coverage overlay.', 'gpsmap'),
+				'method'        => 'checkbox',
+				'value'         => '|arg1:GPScoverage|',
+				'default'       => 'on',
+			];
 
-			$fields_host_edit3['latitude'] = array(
+			$fields_host_edit3['latitude'] = [
 				'friendly_name' => __('Latitude', 'gpsmap'),
-				'description' => __('The devices latitude coordinates', 'gpsmap'),
-				'method' => 'textbox',
-				'max_length' => 13,
-				'value' => '|arg1:latitude|',
-				'default' => '',
-			);
-
-			$fields_host_edit3['longitude'] = array(
+				'description'   => __('The devices latitude coordinates', 'gpsmap'),
+				'method'        => 'textbox',
+				'max_length'    => 13,
+				'value'         => '|arg1:latitude|',
+				'default'       => '',
+			];
+
+			$fields_host_edit3['longitude'] = [
 				'friendly_name' => __('Longitude', 'gpsmap'),
-				'description' => __('The devices longitude coordinates', 'gpsmap'),
-				'method' => 'textbox',
-				'max_length' => 13,
-				'value' => '|arg1:longitude|',
-				'default' => '',
-			);
+				'description'   => __('The devices longitude coordinates', 'gpsmap'),
+				'method'        => 'textbox',
+				'max_length'    => 13,
+				'value'         => '|arg1:longitude|',
+				'default'       => '',
+			];
 
 			if (isset_request_var('id') && get_current_page() == $url_path . 'host.php') {
 				$did = get_filter_request_var('id');
@@ -160,50 +172,48 @@ function gpsmap_config_form() {
 					RIGHT JOIN gpsmap_templates
 					ON host.host_template_id = gpsmap_templates.templateID
 					WHERE id = ?',
-					array($did));
+					[$did]);
 
 				if (cacti_sizeof($row) && $row['AP'] == 1) {
-					$fields_host_edit3['start'] = array(
+					$fields_host_edit3['start'] = [
 						'friendly_name' => __('Starting Degree', 'gpsmap'),
-						'description' => __('Starting degree for directional area between 0-360', 'gpsmap'),
-						'method' => 'textbox',
-						'max_length' => 4,
-						'value' => '|arg1:start|',
-						'default' => '0',
-					);
-
-					$fields_host_edit3['stop'] = array(
+						'description'   => __('Starting degree for directional area between 0-360', 'gpsmap'),
+						'method'        => 'textbox',
+						'max_length'    => 4,
+						'value'         => '|arg1:start|',
+						'default'       => '0',
+					];
+
+					$fields_host_edit3['stop'] = [
 						'friendly_name' => __('Stopping Degree', 'gpsmap'),
-						'description' => __('Stopping degree for directional area, must be greater than the Starting Degree', 'gpsmap'),
-						'method' => 'textbox',
-						'max_length' => 4,
-						'value' => '|arg1:stop|',
-						'default' => '360',
-					);
-
-					$fields_host_edit3['rdistance'] = array(
+						'description'   => __('Stopping degree for directional area, must be greater than the Starting Degree', 'gpsmap'),
+						'method'        => 'textbox',
+						'max_length'    => 4,
+						'value'         => '|arg1:stop|',
+						'default'       => '360',
+					];
+
+					$fields_host_edit3['rdistance'] = [
 						'friendly_name' => __('Specify Radius', 'gpsmap'),
-						'description' => __('Manually specify radius for Access Point. Set to 0 to determine radius based on grouped devices', 'gpsmap'),
-						'method' => 'textbox',
-						'max_length' => 10,
-						'value' => '|arg1:rdistance|',
-						'default' => '0',
-					);
+						'description'   => __('Manually specify radius for Access Point. Set to 0 to determine radius based on grouped devices', 'gpsmap'),
+						'method'        => 'textbox',
+						'max_length'    => 10,
+						'value'         => '|arg1:rdistance|',
+						'default'       => '0',
+					];
 				}
 			}
 
-			$fields_host_edit3['groupnum'] = array(
+			$fields_host_edit3['groupnum'] = [
 				'friendly_name' => __('Group ID', 'gpsmap'),
-				'description' => __('Groups define what devices are included in the coverage overlay. Will be checked against AP device group number. 0 to disable', 'gpsmap'),
-				'method' => 'textbox',
-				'max_length' => 3,
-				'value' => '|arg1:groupnum|',
-				'default' => '0',
-			);
-
+				'description'   => __('Groups define what devices are included in the coverage overlay. Will be checked against AP device group number. 0 to disable', 'gpsmap'),
+				'method'        => 'textbox',
+				'max_length'    => 3,
+				'value'         => '|arg1:groupnum|',
+				'default'       => '0',
+			];
 		}
 	}
 
 	$fields_host_edit = $fields_host_edit3;
 }
-
diff --git a/tests/coverage.php b/tests/coverage.php
index 3229ae2..accac42 100644
--- a/tests/coverage.php
+++ b/tests/coverage.php
@@ -28,12 +28,15 @@
 }
 
 /* Files that hold logic.  The web entry points (gpsmap.php, gpstemplates.php,
- * print.php, includes/towerSelect.php) chdir() to the Cacti root and include
+ * print.php) chdir() to the Cacti root and include
  * include/auth.php, so they cannot execute outside a real installation and are
  * deliberately out of scope here. */
-$targets = array(
+$targets = [
 	'class/hosts_class.php',
 	'gpsmap_security.php',
+	'includes/dns.php',
+	'includes/setup/database.php',
+	'includes/polling.php',
 	'includes/polling/functions.php',
 	'includes/polling/processregion.php',
 	'includes/polling/coveragexml.php',
@@ -41,7 +44,7 @@
 	'includes/polling/iconskml.php',
 	'includes/icons.php',
 	'includes/customicons.php',
-);
+];
 
 /* run.php ends in exit(), so the report runs from a shutdown
  * handler and preserves the suite's own exit status when it fails. */
@@ -54,16 +57,16 @@
 require __DIR__ . '/run.php';
 
 function gpsmap_coverage_report(array $targets): void {
-		$status = 0;
+	$status = 0;
 
-		$coverage = xdebug_get_code_coverage();
-		xdebug_stop_code_coverage();
+	$coverage = xdebug_get_code_coverage();
+	xdebug_stop_code_coverage();
 
 	$root       = dirname(__DIR__);
 	$totalLines = 0;
-	$missing    = array();
+	$missing    = [];
 	$hitLines   = 0;
-	$rows       = array();
+	$rows       = [];
 
 	foreach ($targets as $rel) {
 		$abs = $root . '/' . $rel;
@@ -72,7 +75,7 @@ function gpsmap_coverage_report(array $targets): void {
 			/* A target that never executed would otherwise score 0/0 and drop
 			 * out of the total, letting the gate pass on a file the suite
 			 * never loaded. */
-			$rows[]    = array($rel, 0, 0, 0.0);
+			$rows[]    = [$rel, 0, 0, 0.0];
 			$missing[] = $rel;
 
 			continue;
@@ -82,7 +85,7 @@ function gpsmap_coverage_report(array $targets): void {
 		$hit        = 0;
 
 		foreach ($coverage[$abs] as $state) {
-			/* 1 = executed, -1 = executable but not executed, -2 = dead code. */
+			// 1 = executed, -1 = executable but not executed, -2 = dead code.
 			if ($state === -2) {
 				continue;
 			}
@@ -96,33 +99,33 @@ function gpsmap_coverage_report(array $targets): void {
 
 		$totalLines += $executable;
 		$hitLines   += $hit;
-		$rows[]      = array($rel, $hit, $executable, $executable ? $hit / $executable * 100 : 0.0);
-}
+		$rows[]      = [$rel, $hit, $executable, $executable ? $hit / $executable * 100 : 0.0];
+	}
 
-	echo "\nLine coverage\n";
-	echo str_repeat('-', 62) . "\n";
+	print "\nLine coverage\n";
+	print str_repeat('-', 62) . "\n";
 
 	foreach ($rows as $r) {
 		printf("%-42s %4d/%-4d %6.1f%%\n", $r[0], $r[1], $r[2], $r[3]);
-}
+	}
 
-	echo str_repeat('-', 62) . "\n";
+	print str_repeat('-', 62) . "\n";
 	$pct = $totalLines ? $hitLines / $totalLines * 100 : 0.0;
 	printf("%-42s %4d/%-4d %6.1f%%\n\n", 'TOTAL', $hitLines, $totalLines, $pct);
 
-		if ($missing !== array()) {
-			printf("FAIL: never executed, so not counted: %s\n", implode(', ', $missing));
-			exit(1);
-		}
+	if ($missing !== []) {
+		printf("FAIL: never executed, so not counted: %s\n", implode(', ', $missing));
+		exit(1);
+	}
 
-		$threshold = (float) (getenv('GPSMAP_COVERAGE_MIN') ?: 100);
+	$threshold = (float) (getenv('GPSMAP_COVERAGE_MIN') ?: 100);
 
-		if ($pct + 0.001 < $threshold) {
-			printf("FAIL: coverage %.1f%% is below the %.1f%% threshold\n", $pct, $threshold);
-			$status = 1;
-		}
+	if ($pct + 0.001 < $threshold) {
+		printf("FAIL: coverage %.1f%% is below the %.1f%% threshold\n", $pct, $threshold);
+		$status = 1;
+	}
 
-		if ($status !== 0) {
-			exit($status);
-		}
+	if ($status !== 0) {
+		exit($status);
+	}
 }
diff --git a/tests/harness.php b/tests/harness.php
index 527203f..48f895a 100644
--- a/tests/harness.php
+++ b/tests/harness.php
@@ -19,18 +19,19 @@
 $GLOBALS['gpsmap_test_pass'] = 0;
 $GLOBALS['gpsmap_test_fail'] = 0;
 
-/* Rows the db stubs hand back.  Tests overwrite these per case. */
-$GLOBALS['gpsmap_stub_rows']     = array();
-$GLOBALS['gpsmap_stub_settings'] = array('base_url' => 'https://cacti.example/');
+// Rows the db stubs hand back.  Tests overwrite these per case.
+$GLOBALS['gpsmap_stub_rows']     = [];
+$GLOBALS['gpsmap_stub_settings'] = ['base_url' => 'https://cacti.example/'];
+$GLOBALS['gpsmap_stub_plugins']  = [];
 
 function assert_equal($label, $expected, $actual) {
 	if ($expected === $actual) {
-		echo "PASS  $label\n";
+		print "PASS  $label\n";
 		$GLOBALS['gpsmap_test_pass']++;
 	} else {
-		echo "FAIL  $label\n";
-		echo '      expected: ' . var_export($expected, true) . "\n";
-		echo '      actual:   ' . var_export($actual, true) . "\n";
+		print "FAIL  $label\n";
+		print '      expected: ' . var_export($expected, true) . "\n";
+		print '      actual:   ' . var_export($actual, true) . "\n";
 		$GLOBALS['gpsmap_test_fail']++;
 	}
 }
@@ -52,33 +53,60 @@ function assert_not_contains($label, string $needle, string $haystack) {
 }
 
 function gpsmap_test_summary(): int {
-	echo "\n";
-	echo 'Results: ' . $GLOBALS['gpsmap_test_pass'] . ' passed, ' . $GLOBALS['gpsmap_test_fail'] . " failed\n";
+	print "\n";
+	print 'Results: ' . $GLOBALS['gpsmap_test_pass'] . ' passed, ' . $GLOBALS['gpsmap_test_fail'] . " failed\n";
 
 	return $GLOBALS['gpsmap_test_fail'] > 0 ? 1 : 0;
 }
 
-/* ------------------------------------------------------------------ */
-/* Cacti stubs                                                         */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// Cacti stubs
+// ------------------------------------------------------------------
 
 if (!isset($GLOBALS['config'])) {
-	$GLOBALS['config'] = array(
+	$GLOBALS['config'] = [
 		'base_path' => dirname(__DIR__, 3) . '/cacti-stub',
 		'url_path'  => '/cacti/',
-	);
+	];
 }
 
 if (!function_exists('cacti_sizeof')) {
-	function cacti_sizeof($var) { return is_array($var) ? count($var) : 0; }
+	function cacti_sizeof($var) {
+		return is_array($var) ? count($var) : 0;
+	}
 }
 
 if (!function_exists('db_fetch_assoc')) {
-	function db_fetch_assoc($sql) { return gpsmap_stub_query($sql); }
+	function db_fetch_assoc($sql) {
+		return gpsmap_stub_query($sql);
+	}
 }
 
 if (!function_exists('db_fetch_assoc_prepared')) {
-	function db_fetch_assoc_prepared($sql, $params = array()) { return gpsmap_stub_query($sql); }
+	function db_fetch_assoc_prepared($sql, $params = []) {
+		$GLOBALS['gpsmap_stub_last_params'] = $params;
+
+		return gpsmap_stub_query($sql);
+	}
+}
+
+if (!function_exists('db_table_exists')) {
+	function db_table_exists($table, $log = true, $db_conn = false) {
+		return !in_array($table, $GLOBALS['gpsmap_stub_missing_tables'] ?? [], true);
+	}
+}
+
+if (!function_exists('db_column_exists')) {
+	function db_column_exists($table, $column, $log = true, $db_conn = false) {
+		return empty($GLOBALS['gpsmap_stub_missing_column'])
+			&& !in_array($table . '.' . $column, $GLOBALS['gpsmap_stub_missing_columns'] ?? [], true);
+	}
+}
+
+if (!function_exists('api_plugin_is_enabled')) {
+	function api_plugin_is_enabled($plugin) {
+		return in_array($plugin, $GLOBALS['gpsmap_stub_plugins'], true);
+	}
 }
 
 /* Route each query to a named fixture bucket so a test can set them
@@ -89,22 +117,33 @@ function gpsmap_stub_query($sql) {
 	if (str_contains($sql, 'FROM `host` AS h')) {
 		$GLOBALS['gpsmap_stub_host_sql'] = $sql;
 
-		return $GLOBALS['gpsmap_stub_rows']['hosts'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['hosts'] ?? [];
 	}
 
 	if (str_contains($sql, '`AP` = 1')) {
-		return $GLOBALS['gpsmap_stub_rows']['towers'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['towers'] ?? [];
 	}
 
 	if (str_contains($sql, '`host_template`')) {
-		return $GLOBALS['gpsmap_stub_rows']['templates'] ?? array();
+		return $GLOBALS['gpsmap_stub_rows']['templates'] ?? [];
 	}
 
 	if (str_contains($sql, 'gpsmap_templates')) {
-		return $GLOBALS['gpsmap_stub_rows']['icons'] ?? array();
+		if (str_contains($sql, 'MIN(dc.attempted_at)')) {
+			$rows = $GLOBALS['gpsmap_stub_rows']['dns'] ?? [];
+
+			if (is_array($rows) && str_contains($sql, 'INET6_ATON(h.hostname) IS NULL')) {
+				$rows = array_values(array_filter($rows,
+					static fn (array $row): bool => filter_var($row['hostname'], FILTER_VALIDATE_IP) === false));
+			}
+
+			return $rows;
+		}
+
+		return $GLOBALS['gpsmap_stub_rows']['icons'] ?? [];
 	}
 
-	return array();
+	return [];
 }
 
 if (!function_exists('read_config_option')) {
@@ -113,31 +152,57 @@ function read_config_option($name, $force = false) {
 	}
 }
 
+if (!function_exists('set_config_option')) {
+	function set_config_option($name, $value) {
+		$GLOBALS['gpsmap_stub_settings'][$name] = (string) $value;
+	}
+}
+
+if (!function_exists('cacti_escapeshellarg')) {
+	function cacti_escapeshellarg($arg) {
+		return escapeshellarg((string) $arg);
+	}
+}
+
 if (!function_exists('cacti_log')) {
 	function cacti_log($message, $stdout = false, $env = '') {
 		$GLOBALS['gpsmap_stub_log'][] = $message;
 	}
 }
 
+if (!function_exists('exec_background')) {
+	function exec_background($command, $args) {
+		$GLOBALS['gpsmap_stub_background'][] = [$command, $args];
+	}
+}
+
 if (!function_exists('is_ipaddress')) {
-	function is_ipaddress($ip) { return filter_var($ip, FILTER_VALIDATE_IP) !== false; }
+	function is_ipaddress($ip) {
+		return filter_var($ip, FILTER_VALIDATE_IP) !== false;
+	}
 }
 
 if (!function_exists('html_escape')) {
-	function html_escape($text) { return htmlspecialchars((string) $text, ENT_QUOTES, 'UTF-8'); }
+	function html_escape($text) {
+		return htmlspecialchars((string) $text, ENT_QUOTES, 'UTF-8');
+	}
 }
 
 if (!function_exists('__')) {
 	function __($format, ...$args) {
-		/* Cacti's last argument is the text domain when more than one is given. */
-		if (count($args) > 1) { array_pop($args); }
+		// Cacti's last argument is the text domain when more than one is given.
+		if (count($args) > 1) {
+			array_pop($args);
+		}
 
-		return $args === array() ? $format : vsprintf($format, $args);
+		return $args === [] ? $format : vsprintf($format, $args);
 	}
 }
 
 if (!function_exists('__esc')) {
-	function __esc($format, ...$args) { return html_escape(__($format, ...$args)); }
+	function __esc($format, ...$args) {
+		return html_escape(__($format, ...$args));
+	}
 }
 
 /* Scratch Cacti root.  class/ and includes/ are symlinked back to the real
@@ -157,7 +222,7 @@ function gpsmap_test_tmpdir(): string {
 	@mkdir($plugin . '/XML', 0700, true);
 	@mkdir($plugin . '/images/icons', 0700, true);
 
-	foreach (array('class', 'includes') as $link) {
+	foreach (['class', 'includes', 'INFO', 'setup.php', 'gpsmap_security.php'] as $link) {
 		if (!file_exists($plugin . '/' . $link)) {
 			@symlink($repo . '/' . $link, $plugin . '/' . $link);
 		}
@@ -181,18 +246,18 @@ function gpsmap_test_rmtree(string $path): void {
 		return;
 	}
 
-	foreach (array_diff(scandir($path), array('.', '..')) as $entry) {
+	foreach (array_diff(scandir($path), ['.', '..']) as $entry) {
 		gpsmap_test_rmtree($path . '/' . $entry);
 	}
 
 	@rmdir($path);
 }
 
-/* Replaces the icon fixture folder with exactly the given file names. */
+// Replaces the icon fixture folder with exactly the given file names.
 function gpsmap_test_icons(array $names): string {
 	$dir = gpsmap_test_tmpdir() . '/plugins/gpsmap/images/icons';
 
-	foreach (array_diff(scandir($dir), array('.', '..')) as $entry) {
+	foreach (array_diff(scandir($dir), ['.', '..']) as $entry) {
 		@unlink($dir . '/' . $entry);
 	}
 
@@ -203,7 +268,7 @@ function gpsmap_test_icons(array $names): string {
 	return $dir;
 }
 
-/* Points $config at the scratch root for the duration of a test file. */
+// Points $config at the scratch root for the duration of a test file.
 function gpsmap_test_use_tmp_root(): void {
 	$GLOBALS['config']['base_path'] = gpsmap_test_tmpdir();
 }
@@ -213,15 +278,33 @@ function gpsmap_test_use_tmp_root(): void {
 class GpsmapShortWriteStream {
 	public $context;
 
-	public function stream_open($path, $mode, $options, &$opened_path) { return true; }
-	public function stream_write($data) { return max(0, strlen($data) - 1); }
-	public function stream_close() { return true; }
-	public function stream_flush() { return true; }
-	public function stream_eof() { return true; }
-	public function stream_stat() { return array(); }
-	public function url_stat($path, $flags) { return array(); }
-	public function unlink($path) { return true; }
-	public function rename($from, $to) { return false; }
+	public function stream_open($path, $mode, $options, &$opened_path) {
+		return true;
+	}
+	public function stream_write($data) {
+		return max(0, strlen($data) - 1);
+	}
+	public function stream_close() {
+		return true;
+	}
+	public function stream_flush() {
+		return true;
+	}
+	public function stream_eof() {
+		return true;
+	}
+	public function stream_stat() {
+		return [];
+	}
+	public function url_stat($path, $flags) {
+		return [];
+	}
+	public function unlink($path) {
+		return true;
+	}
+	public function rename($from, $to) {
+		return false;
+	}
 }
 
 if (!in_array('gpsmapshort', stream_get_wrappers(), true)) {
diff --git a/tests/run.php b/tests/run.php
index 36a55f9..e45a222 100644
--- a/tests/run.php
+++ b/tests/run.php
@@ -20,8 +20,8 @@
 
 require_once __DIR__ . '/harness.php';
 
-foreach (array('test_functions.php', 'test_host.php', 'test_security.php', 'test_icons.php', 'test_poller_isolation.php', 'test_polling.php') as $file) {
-	echo "\n--- $file ---\n";
+foreach (['test_functions.php', 'test_host.php', 'test_security.php', 'test_icons.php', 'test_poller_isolation.php', 'test_dns_cli.php', 'test_upgrade.php', 'test_polling.php'] as $file) {
+	print "\n--- $file ---\n";
 
 	require __DIR__ . '/' . $file;
 }
diff --git a/tests/test_dns_cli.php b/tests/test_dns_cli.php
new file mode 100644
index 0000000..331e353
--- /dev/null
+++ b/tests/test_dns_cli.php
@@ -0,0 +1,58 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | Exercise the deployed CLI entry point, including its process exit code. |
+ +-------------------------------------------------------------------------+
+*/
+
+if (PHP_SAPI !== 'cli') {
+	exit;
+}
+
+require_once __DIR__ . '/harness.php';
+
+$root   = gpsmap_test_tmpdir();
+$plugin = $root . '/plugins/gpsmap';
+@mkdir($root . '/include', 0700, true);
+copy(dirname(__DIR__) . '/gpsmap_dns.php', $plugin . '/gpsmap_dns.php');
+
+$bootstrap = <<<'PHP'
+<?php
+$config = ['base_path' => %s];
+
+function register_process_start($process, $task, $id = 0, $timeout = 0) {
+	return ($GLOBALS['argv'][1] ?? '') !== 'fail';
+}
+
+function unregister_process($process, $task, $id = 0) {
+}
+
+function db_fetch_assoc_prepared($sql, $params = []) {
+	return [];
+}
+
+function db_execute_prepared($sql, $params = []) {
+	return true;
+}
+
+function set_config_option($name, $value) {
+}
+
+function cacti_log($message, $stdout = false, $env = '') {
+}
+PHP;
+
+file_put_contents($root . '/include/cli_check.php', sprintf($bootstrap, var_export($root, true)));
+
+foreach (['success' => 0, 'fail' => 1] as $mode => $expected) {
+	$output = [];
+	$status = 0;
+	exec(escapeshellarg(PHP_BINARY) . ' ' . escapeshellarg($plugin . '/gpsmap_dns.php') . ' ' . escapeshellarg($mode) . ' 2>&1', $output, $status);
+	assert_equal('dns CLI: ' . $mode . ' worker exit status', $expected, $status);
+}
+
+if (!defined('GPSMAP_TEST_SUITE')) {
+	exit(gpsmap_test_summary());
+}
diff --git a/tests/test_functions.php b/tests/test_functions.php
index 01bd653..be07ac3 100644
--- a/tests/test_functions.php
+++ b/tests/test_functions.php
@@ -25,16 +25,16 @@
 require_once __DIR__ . '/harness.php';
 require_once __DIR__ . '/../includes/polling/functions.php';
 
-/* ------------------------------------------------------------------ */
-/* parseToXML — encoding correctness                                   */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// parseToXML — encoding correctness
+// ------------------------------------------------------------------
 
-/* Basic entity encoding. */
+// Basic entity encoding.
 assert_equal('parseToXML: ampersand',      '&amp;',       parseToXML('&'));
 assert_equal('parseToXML: less-than',      '&lt;',        parseToXML('<'));
 assert_equal('parseToXML: greater-than',   '&gt;',        parseToXML('>'));
 assert_equal('parseToXML: double-quote',   '&quot;',      parseToXML('"'));
-/* ENT_XML1 uses &apos; for single quotes (XML 1.0 named entity, not &#039;). */
+// ENT_XML1 uses &apos; for single quotes (XML 1.0 named entity, not &#039;).
 assert_equal('parseToXML: single-quote',   '&apos;',      parseToXML("'"));
 
 /* The old implementation double-encoded: '<br>' became '&amp;lt;br&amp;gt;'
@@ -46,26 +46,26 @@
 	parseToXML('<br>')
 );
 
-/* An already-encoded string must not be double-encoded. */
+// An already-encoded string must not be double-encoded.
 assert_equal(
 	'parseToXML: no double-encoding of existing entity',
 	'&amp;amp;',
 	parseToXML('&amp;')
 );
 
-/* Plain strings pass through unchanged. */
+// Plain strings pass through unchanged.
 assert_equal('parseToXML: plain string',   'hello world', parseToXML('hello world'));
 assert_equal('parseToXML: numeric string', '42',          parseToXML(42));
 assert_equal('parseToXML: empty string',   '',            parseToXML(''));
 
-/* ------------------------------------------------------------------ */
-/* calcKm — distance calculation and backward-compat alias            */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — distance calculation and backward-compat alias
+// ------------------------------------------------------------------
 
-/* Same point — distance must be 0. */
+// Same point — distance must be 0.
 assert_equal('calcKm: same point is 0', 0.0, calcKm(0, 0, 0, 0));
 
-/* Known approximate: London (51.5, -0.1) to Paris (48.8, 2.3) ~ 341 km. */
+// Known approximate: London (51.5, -0.1) to Paris (48.8, 2.3) ~ 341 km.
 $dist = calcKm(51.5, -0.1, 48.8, 2.3);
 assert_true('calcKm: London-Paris between 330 and 360 km', $dist >= 330 && $dist <= 360);
 
@@ -77,22 +77,19 @@
 	calcMeters(51.5, -0.1, 48.8, 2.3)
 );
 
-/* ------------------------------------------------------------------ */
-/* Subnet parameter validation regex (mirrors gpsmap.php logic)       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// Subnet parameter validation regex (mirrors gpsmap.php logic)
+// ------------------------------------------------------------------
 
-$valid_re   = '/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$/';
+$valid_re = GPSMAP_ARTIFACT_STEM_PATTERN;
 
-/* Valid values. */
+// Valid values.
 assert_true('subnet regex: "all"',              preg_match($valid_re, 'all'));
-assert_true('subnet regex: IP octets with -',   preg_match($valid_re, '192-168-1'));
-assert_true('subnet regex: alphanumeric',       preg_match($valid_re, 'region1'));
-assert_true('subnet regex: underscore',         preg_match($valid_re, 'region_1'));
-assert_true('subnet regex: uppercase',          preg_match($valid_re, 'RegionA'));
+assert_true('subnet regex: IPv6 token',          preg_match($valid_re, 'v6-32-20010db8'));
 assert_true('subnet regex: dotted subnet',      preg_match($valid_re, '10.0.0'));
-assert_true('subnet regex: dotted with dash',   preg_match($valid_re, '192-168-1.0'));
+assert_false('subnet regex: arbitrary region',  preg_match($valid_re, 'region1'));
 
-/* Values that must be rejected (path traversal and other dangerous input). */
+// Values that must be rejected (path traversal and other dangerous input).
 assert_false('subnet regex: ".."',              preg_match($valid_re, '..'));
 assert_false('subnet regex: "."',               preg_match($valid_re, '.'));
 assert_false('subnet regex: "../etc/passwd"',   preg_match($valid_re, '../etc/passwd'));
@@ -104,16 +101,21 @@
 assert_false('subnet regex: percent-encoded',   preg_match($valid_re, '..%2fetc'));
 assert_false('subnet regex: space',             preg_match($valid_re, 'a b'));
 
-/* ------------------------------------------------------------------ */
-/* parseToXML — multibyte UTF-8                                        */
-/* ------------------------------------------------------------------ */
+foreach (['all', '10', '10.20', '10.20.30', 'v6-16-2001', 'v6-32-20010db8', '../escape', 'v6-64-20010db800000000'] as $candidate) {
+	assert_equal('subnet contract: page and poller agree for ' . $candidate,
+		gpsmap_artifact_parameter_is_valid($candidate), gpsmap_artifact_stem($candidate) === $candidate);
+}
+
+// ------------------------------------------------------------------
+// parseToXML — multibyte UTF-8
+// ------------------------------------------------------------------
 
 assert_equal('parseToXML: multibyte CJK', '日本語', parseToXML('日本語'));
 assert_equal('parseToXML: multibyte with entities', '&lt;日本語&gt;', parseToXML('<日本語>'));
 
-/* ------------------------------------------------------------------ */
-/* calcKm — negative coordinates (southern/western hemispheres)        */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — negative coordinates (southern/western hemispheres)
+// ------------------------------------------------------------------
 
 /* Southern hemisphere: Cape Town (-33.9, 18.4) to Buenos Aires (-34.6, -58.4).
  * The flat-earth approximation in calcKm overestimates at large longitude
@@ -122,9 +124,9 @@
 assert_true('calcKm: negative coords (CapeTown-BuenosAires) > 0', $dist_neg > 0);
 assert_true('calcKm: negative coords is finite and positive', is_finite($dist_neg) && $dist_neg > 0);
 
-/* ------------------------------------------------------------------ */
-/* calcKm — symmetry: distance(A,B) === distance(B,A)                 */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — symmetry: distance(A,B) === distance(B,A)
+// ------------------------------------------------------------------
 
 assert_equal(
 	'calcKm: symmetry London-Paris',
@@ -138,18 +140,18 @@
 	calcKm(-34.6, -58.4, -33.9, 18.4)
 );
 
-/* ------------------------------------------------------------------ */
-/* calcKm — antipodal points (max distance ~20,000 km)                */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// calcKm — antipodal points (max distance ~20,000 km)
+// ------------------------------------------------------------------
 
 $dist_anti = calcKm(0, 0, 0, 180);
 assert_true('calcKm: antipodal not NaN', !is_nan($dist_anti));
 assert_true('calcKm: antipodal > 0', $dist_anti > 0);
 assert_true('calcKm: antipodal <= 21000 km', $dist_anti <= 21000);
 
-/* ------------------------------------------------------------------ */
-/* coordCheck — validation                                             */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// coordCheck — validation
+// ------------------------------------------------------------------
 
 assert_equal('coordCheck: valid positive',    '45.123',  coordCheck('45.123'));
 assert_equal('coordCheck: valid negative',    '-90.000', coordCheck('-90.000'));
@@ -159,7 +161,7 @@
 assert_equal('coordCheck: valid zero',        '0.000',   coordCheck('0.000'));
 assert_equal('coordCheck: negative longitude', '-122.4194', coordCheck('-122.4194'));
 
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
 if (!defined('GPSMAP_TEST_SUITE')) {
 	exit(gpsmap_test_summary());
 }
diff --git a/tests/test_icons.php b/tests/test_icons.php
index 31d97ae..e8d846e 100644
--- a/tests/test_icons.php
+++ b/tests/test_icons.php
@@ -18,13 +18,14 @@
 
 require_once __DIR__ . '/harness.php';
 require_once __DIR__ . '/../setup.php';
+require_once __DIR__ . '/../gpsmap_security.php';
 require_once __DIR__ . '/../includes/polling/iconskml.php';
 
 gpsmap_test_use_tmp_root();
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_icon_identifier                                              */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_icon_identifier
+// ------------------------------------------------------------------
 
 assert_equal('identifier: simple name',      'Green',   gpsmap_icon_identifier('Green.png'));
 assert_equal('identifier: underscore start', '_x',      gpsmap_icon_identifier('_x.png'));
@@ -37,11 +38,11 @@
 assert_equal('identifier: quote injection',  null,      gpsmap_icon_identifier("x';alert(1);//.png"));
 assert_equal('identifier: space',            null,      gpsmap_icon_identifier('two words.png'));
 
-/* ------------------------------------------------------------------ */
-/* includes/icons.php - JavaScript emitted into an inline <script>      */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// includes/icons.php - JavaScript emitted into an inline <script>
+// ------------------------------------------------------------------
 
-gpsmap_test_icons(array('Green.png', 'GoogleBlue.PNG', 'ap.v2.png', 'my-icon.png', 'notes.txt', 'noext'));
+gpsmap_test_icons(['Green.png', 'GoogleBlue.PNG', 'ap.v2.png', 'my-icon.png', 'notes.txt', 'noext']);
 
 $cwd = getcwd();
 chdir(gpsmap_test_tmpdir());
@@ -58,13 +59,14 @@
 assert_not_contains('icons.php: ignores extensionless', 'gpsmap.noext',         $js);
 assert_contains('icons.php: url is json encoded',      '"/cacti/plugins/gpsmap/images/icons/Green.png"', $js);
 
-/* Every emitted assignment target must be a bare identifier. */
+// Every emitted assignment target must be a bare identifier.
 preg_match_all('/gpsmap\.([^ ]+) = \{/', $js, $m);
+
 foreach ($m[1] as $name) {
 	assert_true('icons.php: identifier is bare - ' . $name, (bool) preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $name));
 }
 
-/* An unreadable icon directory must not emit anything. */
+// An unreadable icon directory must not emit anything.
 $cwd = getcwd();
 chdir(sys_get_temp_dir());
 ob_start();
@@ -73,11 +75,11 @@
 chdir($cwd);
 assert_not_contains('icons.php: missing directory emits no icons', 'gpsmap.', $empty);
 
-/* ------------------------------------------------------------------ */
-/* iconskml() - KML Style ids                                          */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// iconskml() - KML Style ids
+// ------------------------------------------------------------------
 
-gpsmap_test_icons(array('Green.png', 'Red.jpg', 'Amber.jpeg', 'Node.gif', 'ap.v2.png', 'notes.txt'));
+gpsmap_test_icons(['Green.png', 'Red.jpg', 'Amber.jpeg', 'Node.gif', 'ap.v2.png', 'notes.txt']);
 
 $kml = iconskml();
 
@@ -89,34 +91,81 @@
 assert_not_contains('iconskml: ignores non-images', 'notes',       $kml);
 assert_contains('iconskml: absolute href',  'https://cacti.example//cacti/plugins/gpsmap/images/icons/Green.png', $kml);
 
-/* Missing directory is logged, not fatal. */
-$GLOBALS['gpsmap_stub_log']      = array();
+// Missing directory is logged, not fatal.
+$GLOBALS['gpsmap_stub_log']      = [];
 $saved                           = $GLOBALS['config']['base_path'];
 $GLOBALS['config']['base_path']  = sys_get_temp_dir() . '/gpsmap-no-such-root';
 assert_equal('iconskml: missing directory returns empty', '', @iconskml());
 assert_true('iconskml: logs the missing directory', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'could not open icon directory'));
 $GLOBALS['config']['base_path'] = $saved;
 
-/* ------------------------------------------------------------------ */
-/* customicons.php - property-access position, degrades to undefined   */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// customicons.php - property-access position, degrades to undefined
+// ------------------------------------------------------------------
 
-$GLOBALS['gpsmap_stub_rows']['icons'] = array(
-	array('templateID' => '10', 'upimage' => 'Green.png', 'downimage' => 'Red.png',    'recoverimage' => 'Yellow.png'),
-	array('templateID' => '11', 'upimage' => 'ap.v2.png', 'downimage' => 'my-icon.png', 'recoverimage' => ''),
-);
+$GLOBALS['gpsmap_stub_rows']['icons'] = [
+	['templateID' => '10', 'upimage' => 'Green.png', 'downimage' => 'Red.png',    'recoverimage' => 'Yellow.png'],
+	['templateID' => '11', 'upimage' => 'ap.v2.png', 'downimage' => 'my-icon.png', 'recoverimage' => ''],
+];
 
 ob_start();
 include __DIR__ . '/../includes/customicons.php';
 $custom = ob_get_clean();
 
 assert_contains('customicons: maps a good icon',   '["10up"] = gpsmap.Green;',    $custom);
+assert_contains('customicons: alert uses down icon', '["10alert"] = gpsmap.Red;', $custom);
 assert_contains('customicons: unsafe degrades',    '["11up"] = gpsmap.undefined;', $custom);
 assert_contains('customicons: keeps builtin ups',  "gpsmap.customIcons['up'] = gpsmap.Green;", $custom);
 assert_contains('customicons: keeps disabled',     "gpsmap.customIcons['disabled'] = gpsmap.Black;", $custom);
 assert_equal('gpsmap_safe_icon_base: good name',   'Green',     gpsmap_safe_icon_base('Green.png'));
 assert_equal('gpsmap_safe_icon_base: bad name',    'undefined', gpsmap_safe_icon_base('ap.v2.png'));
 
+// ------------------------------------------------------------------
+// getIcons() must offer exactly what the renderers can draw
+// ------------------------------------------------------------------
+
+// getIcons() reads a path relative to the Cacti root.
+$iconDir = gpsmap_test_icons(['Green.png', 'Node2.gif', 'my-icon.png', 'ap.v2.png', 'notes.txt', 'noext']);
+mkdir($iconDir . '/Nested.png');
+
+$cwd = getcwd();
+chdir(gpsmap_test_tmpdir());
+$offered = getIcons();
+chdir($cwd);
+
+assert_true('getIcons: offers a renderable icon',      isset($offered['Green.png']));
+assert_true('getIcons: offers a digit-bearing name',   isset($offered['Node2.gif']));
+assert_false('getIcons: hides hyphenated name',        isset($offered['my-icon.png']));
+assert_false('getIcons: hides dotted name',            isset($offered['ap.v2.png']));
+assert_false('getIcons: hides non-images',             isset($offered['notes.txt']));
+assert_false('getIcons: hides extensionless files',    isset($offered['noext']));
+assert_false('getIcons: hides directories with image-like names', isset($offered['Nested.png']));
+
+/* The dropdown and the JavaScript emitter must never disagree: anything
+ * offered here has to survive gpsmap_icon_identifier(). */
+foreach (array_keys($offered) as $name) {
+	assert_true('getIcons: offered name is renderable - ' . $name, gpsmap_icon_identifier($name) !== null);
+}
+
+/* The path comes from base_path, not the working directory, so poller and CLI
+ * callers see the same list as the web pages. */
+$savedRoot = $GLOBALS['config']['base_path'];
+$cwd       = getcwd();
+chdir(sys_get_temp_dir());
+assert_true('getIcons: resolves regardless of the working directory', isset(getIcons()['Green.png']));
+chdir($cwd);
+
+$GLOBALS['config']['base_path'] = sys_get_temp_dir() . '/gpsmap-no-such-root';
+$GLOBALS['gpsmap_stub_log']     = [];
+assert_equal('getIcons: missing directory yields no icons', [], @getIcons());
+assert_true('getIcons: missing directory is logged',
+	(bool) preg_grep('/could not open icon directory/', $GLOBALS['gpsmap_stub_log']));
+$GLOBALS['config']['base_path'] = $savedRoot;
+
+// Saving still falls back when a name is not on the list.
+assert_equal('save: hyphenated name rejected on save', 'Green.png', gpsmap_normalize_icon_name('my-icon.png', $offered));
+assert_equal('save: offered name accepted on save',    'Green.png', gpsmap_normalize_icon_name('Green.png', $offered));
+
 if (!defined('GPSMAP_TEST_SUITE')) {
 	exit(gpsmap_test_summary());
 }
diff --git a/tests/test_polling.php b/tests/test_polling.php
index c26a19c..afb036f 100644
--- a/tests/test_polling.php
+++ b/tests/test_polling.php
@@ -20,12 +20,33 @@
 require_once __DIR__ . '/../class/hosts_class.php';
 require_once __DIR__ . '/../includes/polling/functions.php';
 require_once __DIR__ . '/../includes/polling/processregion.php';
+require_once __DIR__ . '/../includes/dns.php';
+
+if (!function_exists('db_execute_prepared')) {
+	function db_execute_prepared($sql, $params = [], $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_execute'][] = [$sql, $params];
+
+		return $GLOBALS['gpsmap_stub_execute_result'] ?? true;
+	}
+}
+
+if (!function_exists('register_process_start')) {
+	function register_process_start($process, $task, $id = 0, $timeout = 0) {
+		return $GLOBALS['gpsmap_stub_process_registration'] ?? true;
+	}
+}
+
+if (!function_exists('unregister_process')) {
+	function unregister_process($process, $task, $id = 0) {
+		$GLOBALS['gpsmap_stub_process_unregisters'] = ($GLOBALS['gpsmap_stub_process_unregisters'] ?? 0) + 1;
+	}
+}
 
 gpsmap_test_use_tmp_root();
-gpsmap_test_icons(array('Green.png', 'Red.png', 'Yellow.png', 'GoogleBlue.png', 'ap.v2.png', 'readme.txt'));
+gpsmap_test_icons(['Green.png', 'Red.png', 'Yellow.png', 'GoogleBlue.png', 'ap.v2.png', 'readme.txt']);
 
-function gpsmap_test_row(array $over = array()): array {
-	return $over + array(
+function gpsmap_test_row(array $over = []): array {
+	return $over + [
 		'id'               => '1',
 		'host_template_id' => '10',
 		'hostname'         => '10.1.2.3',
@@ -45,12 +66,16 @@ function gpsmap_test_row(array $over = array()): array {
 		'upimage'          => 'Green.png',
 		'downimage'        => 'Red.png',
 		'recoverimage'     => 'Yellow.png',
-	);
+		'cached_address'   => null,
+		'cache_is_fresh'   => '1',
+		'cache_failures'   => '0',
+		'thold_alarm'      => '0',
+	];
 }
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_xml_path / gpsmap_write_file                                 */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_xml_path / gpsmap_write_file
+// ------------------------------------------------------------------
 
 $root = gpsmap_test_tmpdir();
 
@@ -65,34 +90,35 @@ function gpsmap_test_row(array $over = array()): array {
 	gpsmap_xml_path('all', 'kml')
 );
 
-assert_true('gpsmap_write_file: writes', gpsmap_write_file(gpsmap_xml_path('probe', 'xml'), 'body'));
-assert_equal('gpsmap_write_file: contents', 'body', file_get_contents(gpsmap_xml_path('probe', 'xml')));
+$writeProbe = gpsmap_xml_path('192.0.2', 'xml');
+assert_true('gpsmap_write_file: writes', gpsmap_write_file($writeProbe, 'body'));
+assert_equal('gpsmap_write_file: contents', 'body', file_get_contents($writeProbe));
 
-$GLOBALS['gpsmap_stub_log'] = array();
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('gpsmap_write_file: unwritable path returns false', gpsmap_write_file($root . '/no/such/dir/x.xml', 'body'));
 assert_true('gpsmap_write_file: logs the failure', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
 
-/* ------------------------------------------------------------------ */
-/* getTowerIds / createTypeArray                                       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// getTowerIds / createTypeArray
+// ------------------------------------------------------------------
 
-$GLOBALS['gpsmap_stub_rows']['towers'] = array();
-assert_equal('getTowerIds: sentinel when no towers', array(9999), getTowerIds());
+$GLOBALS['gpsmap_stub_rows']['towers'] = [];
+assert_equal('getTowerIds: sentinel when no towers', [9999], getTowerIds());
 
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'), array('templateID' => '11'));
-assert_equal('getTowerIds: template ids', array('10', '11'), getTowerIds());
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10'], ['templateID' => '11']];
+assert_equal('getTowerIds: template ids', ['10', '11'], getTowerIds());
 
-$GLOBALS['gpsmap_stub_rows']['templates'] = array(
-	array('id' => '10', 'name' => 'Tower'),
-	array('id' => '20', 'name' => 'Switch'),
-);
-assert_equal('createTypeArray: id keyed names', array('10' => 'Tower', '20' => 'Switch'), createTypeArray());
+$GLOBALS['gpsmap_stub_rows']['templates'] = [
+	['id' => '10', 'name' => 'Tower'],
+	['id' => '20', 'name' => 'Switch'],
+];
+assert_equal('createTypeArray: id keyed names', ['10' => 'Tower', '20' => 'Switch'], createTypeArray());
 
-/* ------------------------------------------------------------------ */
-/* gpsmap_marker                                                       */
-/* ------------------------------------------------------------------ */
+// ------------------------------------------------------------------
+// gpsmap_marker
+// ------------------------------------------------------------------
 
-$typeArray = array('10' => 'Tower');
+$typeArray = ['10' => 'Tower'];
 $marker    = gpsmap_marker(gpsmap_test_marker_host(), $typeArray, '0', false);
 
 assert_contains('gpsmap_marker: id',        'id="5"',            $marker);
@@ -114,38 +140,38 @@ function gpsmap_test_marker_host(string $type = '10'): host {
 		0, '99', 'up', '1', 'on', 'Green.png', 'Red.png', 'Yellow.png', '0', '360', '1');
 }
 
-/* createXMLNodes skips anything the traversal switched off. */
-$visible = gpsmap_test_marker_host();
-$hidden  = gpsmap_test_marker_host();
+// createXMLNodes skips anything the traversal switched off.
+$visible         = gpsmap_test_marker_host();
+$hidden          = gpsmap_test_marker_host();
 $hidden->showMap = 0;
 
-$nodes = createXMLNodes(array($visible, $hidden));
+$nodes = createXMLNodes([$visible, $hidden]);
 assert_equal('createXMLNodes: hidden hosts are skipped', 1, substr_count($nodes, '<marker '));
-assert_equal('createXMLNodes: empty input', '', createXMLNodes(array()));
-
-/* ------------------------------------------------------------------ */
-/* region(): full poller pass                                          */
-/* ------------------------------------------------------------------ */
-
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10', 'groupnum' => '1')),
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.1.2.4', 'host_template_id' => '20', 'groupnum' => '1', 'status' => '1',
-		/* same group as the tower but 250km away, so the coverage radius has to grow */
-		'latitude' => '53.4808', 'longitude' => '-2.2426')),
-	gpsmap_test_row(array('id' => '3', 'hostname' => '10.9.9.9', 'host_template_id' => '20', 'groupnum' => '2', 'status' => '2')),
-	/* filtered: no coordinates */
-	gpsmap_test_row(array('id' => '4', 'latitude' => '0.000', 'longitude' => '0.000')),
-	gpsmap_test_row(array('id' => '5', 'longitude' => '0.000')),
-	/* filtered: name does not resolve to a dotted quad */
-	gpsmap_test_row(array('id' => '6', 'hostname' => 'not-an-ip')),
-	/* disabled device keeps its own status label */
-	gpsmap_test_row(array('id' => '7', 'hostname' => '10.1.2.7', 'disabled' => 'on', 'status' => '3')),
-	/* status outside 1/2/3 falls through to 'undefined' */
-	gpsmap_test_row(array('id' => '8', 'hostname' => '10.1.2.8', 'status' => '9')),
-	/* GoogleXxx icons map onto Google's own KML styles */
-	gpsmap_test_row(array('id' => '9', 'hostname' => '10.1.2.9', 'upimage' => 'GoogleBlue.png')),
-);
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
+assert_equal('createXMLNodes: empty input', '', createXMLNodes([]));
+
+// ------------------------------------------------------------------
+// region(): full poller pass
+// ------------------------------------------------------------------
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10', 'groupnum' => '1']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.1.2.4', 'host_template_id' => '20', 'groupnum' => '1', 'status' => '1',
+		// same group as the tower but 250km away, so the coverage radius has to grow
+		'latitude' => '53.4808', 'longitude' => '-2.2426']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '10.9.9.9', 'host_template_id' => '20', 'groupnum' => '2', 'status' => '2']),
+	// filtered: no coordinates
+	gpsmap_test_row(['id' => '4', 'latitude' => '0.000', 'longitude' => '0.000']),
+	gpsmap_test_row(['id' => '5', 'longitude' => '0.000']),
+	// filtered: name does not resolve to a dotted quad
+	gpsmap_test_row(['id' => '6', 'hostname' => 'not-an-ip']),
+	// disabled device keeps its own status label
+	gpsmap_test_row(['id' => '7', 'hostname' => '10.1.2.7', 'disabled' => 'on', 'status' => '3']),
+	// status outside 1/2/3 falls through to 'undefined'
+	gpsmap_test_row(['id' => '8', 'hostname' => '10.1.2.8', 'status' => '9']),
+	// GoogleXxx icons map onto Google's own KML styles
+	gpsmap_test_row(['id' => '9', 'hostname' => '10.1.2.9', 'upimage' => 'GoogleBlue.png']),
+];
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
 
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('all');
@@ -169,29 +195,44 @@ function gpsmap_test_marker_host(string $type = '10'): host {
 assert_contains('region: top html nav',          'gpstopmenu',  $top);
 assert_contains('region: top html subnet link',  'subnet=10',   $top);
 
-/* Tower markers carry the coverage radius grown to the furthest group member. */
+$missingPreservedKmlState                            = new GpsmapPollState();
+$missingPreservedKmlState->preservedArtifacts['all'] = true;
+unlink(gpsmap_xml_path('all', 'kml'));
+assert_true('kml: a missing preserved file falls through to rendering',
+	kmlCreate(gpsmap_load_devices(true), 'all', $missingPreservedKmlState));
+assert_true('kml: the missing preserved file is recreated', is_file(gpsmap_xml_path('all', 'kml')));
+assert_equal('kml: a missing XML snapshot has no preserved placemarks', '',
+	gpsmap_preserved_kml_placemarks('203.0.1'));
+gpsmap_write_file(gpsmap_xml_path('203.0.1', 'xml'),
+	'<markers><marker gpsmapPreservedAt="1" lat="invalid" lng="invalid" /></markers>');
+assert_equal('kml: invalid preserved coordinates are ignored', '',
+	gpsmap_preserved_kml_placemarks('203.0.1'));
+
+// Tower markers carry the coverage radius grown to the furthest group member.
 assert_true('region: coverage radius grows beyond zero', (bool) preg_match('/radius="[1-9][0-9]*(\.[0-9]+)?"/', $xml));
 
-/* enableAll off takes the WHERE-clause branch. */
+// enableAll off takes the WHERE-clause branch.
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = '';
 region('10.1.2.');
 $deep = file_get_contents(gpsmap_xml_path('10.1.2.', 'xml'));
 assert_contains('region: subnet pass writes its own file', '<markers>', $deep);
 
-/* Deepest level emits per-device graph links. */
+// Deepest level emits per-device graph links.
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('10.1.2.');
 assert_contains('region: preempt 3 links to graphs', 'graph_view.php', file_get_contents($root . '/plugins/gpsmap/XML/10.1.2-top.html'));
 
-/* Beyond the deepest level every host is switched off. */
-region('10.1.2.3.4.');
-assert_not_contains('region: past deepest level draws no markers', '<marker ', file_get_contents(gpsmap_xml_path('10.1.2.3.4.', 'xml')));
+// Invalid render targets must not fall through to and overwrite all.xml.
+$allBeforeInvalid = file_get_contents(gpsmap_xml_path('all', 'xml'));
+assert_false('region: past deepest level is rejected', gpsmap_render_region(gpsmap_load_devices(true), '10.1.2.3.4.'));
+assert_equal('region: an invalid target leaves all.xml untouched', $allBeforeInvalid,
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
 
-/* Empty subnet is treated as 'all'. */
+// Empty subnet is treated as 'all'.
 region('');
 assert_true('region: empty subnet writes the all- files', file_exists($root . '/plugins/gpsmap/XML/all-top.html'));
 
-/* callRegion wires the includes together. */
+// callRegion wires the includes together.
 callRegion('all');
 assert_contains('callRegion: writes the navigation file', 'gpstopmenu', file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
 
@@ -220,66 +261,350 @@ function gpsmap_test_tower_radius(string $xml): ?float {
 
 /* Coverage radius: only devices sharing the tower's group widen it, and it
  * lands on the furthest member rather than the last one seen. */
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
-$GLOBALS['gpsmap_stub_rows']['hosts']  = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	/* different group, must not widen the tower */
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '7',
-		'latitude' => '-33.8688', 'longitude' => '151.2093')),
-);
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	// different group, must not widen the tower
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '7',
+		'latitude'           => '-33.8688', 'longitude' => '151.2093']),
+];
 region('all');
 assert_equal('coverageXML: other groups do not widen the radius', 0.0, gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))));
 
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	/* furthest member listed first, nearest last: the radius must keep the max */
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
-		'latitude' => '-33.8688', 'longitude' => '151.2093')),
-	gpsmap_test_row(array('id' => '3', 'hostname' => '10.5.0.3', 'host_template_id' => '20', 'groupnum' => '1',
-		'latitude' => '51.5080', 'longitude' => '-0.1280')),
-);
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	// furthest member listed first, nearest last: the radius must keep the max
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
+		'latitude'           => '-33.8688', 'longitude' => '151.2093']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '10.5.0.3', 'host_template_id' => '20', 'groupnum' => '1',
+		'latitude'           => '51.5080', 'longitude' => '-0.1280']),
+];
 region('all');
 assert_true('coverageXML: radius keeps the furthest member, not the last', gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))) > 1000.0);
 
-/* A device with coverage switched off is ignored by the overlay. */
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(
-	gpsmap_test_row(array('id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1')),
-	gpsmap_test_row(array('id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
-		'GPScoverage' => '', 'latitude' => '-33.8688', 'longitude' => '151.2093')),
-);
+// A device with coverage switched off is ignored by the overlay.
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.5.0.1', 'host_template_id' => '10', 'groupnum' => '1']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.5.0.2', 'host_template_id' => '20', 'groupnum' => '1',
+		'GPScoverage'        => '', 'latitude' => '-33.8688', 'longitude' => '151.2093']),
+];
 region('all');
 assert_equal('coverageXML: coverage-off devices are ignored', 0.0, gpsmap_test_tower_radius(file_get_contents(gpsmap_xml_path('all', 'xml'))));
 
+// ------------------------------------------------------------------
+// Single-pass loading: one query and one DNS pass for the whole cycle
+// ------------------------------------------------------------------
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '1', 'hostname' => '10.1.2.3', 'host_template_id' => '10']),
+	gpsmap_test_row(['id' => '2', 'hostname' => '10.1.9.4', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '3', 'hostname' => '192.168.1.5', 'host_template_id' => '20']),
+];
+
+// No mapped devices at all is a normal state on a fresh install.
+$savedHosts                           = $GLOBALS['gpsmap_stub_rows']['hosts'];
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+assert_equal('load: empty result set yields empty groups', [[], []], gpsmap_load_devices(true));
+$GLOBALS['gpsmap_stub_rows']['hosts'] = $savedHosts;
+
+$loaded = gpsmap_load_devices(true);
+assert_equal('load: towers separated', 1, cacti_sizeof($loaded[0]));
+assert_equal('load: devices separated', 2, cacti_sizeof($loaded[1]));
+assert_equal('load: iprange holds the resolved address', '10.1.2.3', $loaded[0][0]->iprange);
+
+$prefixes = gpsmap_subnet_prefixes($loaded);
+assert_equal('prefixes: every depth, de-duplicated', ['10.', '10.1.', '10.1.2.', '10.1.9.', '192.', '192.168.', '192.168.1.'], $prefixes);
+assert_equal('prefixes: empty set yields none', [], gpsmap_subnet_prefixes([[], []]));
+
+/* IPv6 uses filename-safe reversible tokens while remaining in the same
+ * three-level navigation model. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '21', 'hostname' => '2001:db8:1234::5', 'host_template_id' => '20']),
+];
+$v6loaded = gpsmap_load_devices(true);
+assert_equal('ipv6: literal address is mapped', 1, cacti_sizeof($v6loaded[1]));
+assert_equal('ipv6: safe prefixes', ['v6-16-2001', 'v6-32-20010db8', 'v6-48-20010db81234'], gpsmap_subnet_prefixes($v6loaded));
+assert_equal('ipv6: token has a readable label', '2001:db8::/32', gpsmap_ipv6_prefix_label('v6-32-20010db8'));
+assert_true('ipv6: prefix membership', gpsmap_ipv6_prefix_contains('v6-32-20010db8', '2001:db8:ffff::1'));
+assert_false('ipv6: rejects another prefix', gpsmap_ipv6_prefix_contains('v6-32-20010db8', '2001:db9::1'));
+assert_equal('ipv6: invalid token has no label', null, gpsmap_ipv6_prefix_label('v6-31-nope'));
+assert_equal('ipv6: wrong token length has no label', null, gpsmap_ipv6_prefix_label('v6-32-2001'));
+assert_equal('ipv6: invalid address has no token', null, gpsmap_ipv6_prefix_token('nope', 32));
+assert_equal('ipv6: unsupported prefix length has no token', null, gpsmap_ipv6_prefix_token('2001:db8::1', 64));
+assert_false('ipv6: malformed prefix never matches', gpsmap_ipv6_prefix_contains('not-a-prefix', '2001:db8::1'));
+assert_false('ipv6: short prefix token never matches', gpsmap_ipv6_prefix_contains('v6-32-2001', '2001:db8::1'));
+
+foreach ([16, 32, 48] as $prefixLength) {
+	$token = gpsmap_ipv6_prefix_token('2001:db8:1234::5', $prefixLength);
+	assert_true("ipv6: $prefixLength-bit token round-trips through label", $token !== null && gpsmap_ipv6_prefix_label($token) !== null);
+	assert_true("ipv6: $prefixLength-bit token contains its source", $token !== null && gpsmap_ipv6_prefix_contains($token, '2001:db8:1234::5'));
+}
+
+$v6PreserveState                      = new GpsmapPollState();
+$v6PreserveState->unresolvedDeviceIds = ['21'];
+gpsmap_write_file(gpsmap_xml_path('v6-32-20010db8', 'xml'),
+	'<markers><marker id="21" name="IPv6 previous" lat="51.5" lng="-0.1" /></markers>');
+assert_contains('ipv6: an unresolved Device is preserved in a v6 artifact', 'id="21"',
+	gpsmap_preserve_unresolved_markers('<markers></markers>', 'v6-32-20010db8', $v6PreserveState));
+
+assert_equal('artefact: invalid name has no stem', null, gpsmap_artifact_stem('../escape'));
+$invalidPathRejected = false;
+
+try {
+	gpsmap_xml_path('../escape', 'xml');
+} catch (InvalidArgumentException) {
+	$invalidPathRejected = true;
+}
+
+assert_true('artefact: invalid name cannot alias all.xml', $invalidPathRejected);
+
+gpsmap_render_region($v6loaded, 'v6-32-20010db8');
+assert_true('ipv6: safe artefact filename is written', file_exists(gpsmap_xml_path('v6-32-20010db8', 'xml')));
+assert_contains('ipv6: marker survives drilldown', 'id="21"', file_get_contents(gpsmap_xml_path('v6-32-20010db8', 'xml')));
+
+gpsmap_render_region($v6loaded, 'v6-48-20010db81234');
+assert_contains('ipv6: deepest level links to Device graphs', 'host_id=21',
+	file_get_contents($root . '/plugins/gpsmap/XML/v6-48-20010db81234-top.html'));
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '24', 'hostname' => '10.20.30.40', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '25', 'hostname' => '2001:db8:abcd::1', 'description' => 'IPv6 only', 'host_template_id' => '20']),
+];
+$mixed = gpsmap_load_devices(true);
+gpsmap_render_region($mixed, 'all');
+assert_contains('dual stack: all view includes IPv4', 'id="24"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_contains('dual stack: all view includes IPv6', 'id="25"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+gpsmap_render_region($mixed, '10.20');
+assert_contains('dual stack: dotless IPv4 drilldown includes its IPv4 Device', 'id="24"',
+	file_get_contents(gpsmap_xml_path('10.20', 'xml')));
+assert_not_contains('dual stack: IPv4 drilldown hides IPv6', 'id="25"', file_get_contents(gpsmap_xml_path('10.20', 'xml')));
+assert_contains('dual stack: IPv4 KML includes its IPv4 Device', '<name>Device &lt;one&gt;</name>',
+	file_get_contents(gpsmap_xml_path('10.20', 'kml')));
+assert_not_contains('dual stack: IPv4 KML hides IPv6', '<name>IPv6 only</name>',
+	file_get_contents(gpsmap_xml_path('10.20', 'kml')));
+
+$dotlessTwoLevel = file_get_contents(gpsmap_xml_path('10.20', 'xml'));
+gpsmap_render_region($mixed, '10.20.');
+assert_equal('subnet: dotted and dotless two-level forms select the same Devices', $dotlessTwoLevel,
+	file_get_contents(gpsmap_xml_path('10.20', 'xml')));
+gpsmap_render_region($mixed, '10');
+assert_contains('subnet: dotless one-level form includes an in-prefix Device', 'id="24"',
+	file_get_contents(gpsmap_xml_path('10', 'xml')));
+assert_not_contains('subnet: dotless one-level form excludes IPv6', 'id="25"',
+	file_get_contents(gpsmap_xml_path('10', 'xml')));
+gpsmap_render_region($mixed, 'v6-32-20010db9');
+assert_not_contains('dual stack: nonmatching IPv6 prefix is hidden', 'id="25"',
+	file_get_contents(gpsmap_xml_path('v6-32-20010db9', 'xml')));
+
+// A configured hostname consumes only a cached value during the poll.
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '22', 'hostname' => 'router.example', 'cached_address' => '2001:db8::22', 'host_template_id' => '20']),
+];
+assert_equal('dns cache: cached hostname is mapped without a lookup', 1, cacti_sizeof(gpsmap_load_devices(true)[1]));
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row([
+		'id'             => '22', 'hostname' => 'router.example', 'cached_address' => '2001:db8::22',
+		'cache_is_fresh' => '0', 'host_template_id' => '20',
+	]),
+];
+$staleState = new GpsmapPollState();
+assert_equal('dns cache: an expired cached address remains mapped as degraded', 1,
+	cacti_sizeof(gpsmap_load_devices(true, $staleState)[1]));
+assert_equal('dns cache: an expired cached address is explicitly tracked', ['22'], $staleState->staleDeviceIds);
+
+/* thold stays optional; when enabled an alerting, otherwise-up Device receives
+ * the alert marker state while disabled/down precedence stays intact. */
+$GLOBALS['gpsmap_stub_plugins']       = ['thold'];
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '23', 'hostname' => '10.2.3.4', 'thold_alarm' => '1']),
+];
+assert_equal('thold: alert overrides healthy status', 'alert', gpsmap_load_devices(true)[0][0]->status);
+assert_contains('thold: enabled state uses a placeholder', 'WHERE thold_enabled = ?', $GLOBALS['gpsmap_stub_host_sql']);
+assert_not_contains('thold: query is safe under ANSI_QUOTES', 'thold_enabled = "on"', $GLOBALS['gpsmap_stub_host_sql']);
+gpsmap_load_devices(false);
+assert_equal('thold: disabled-Device filter parameters follow SQL placeholder order', ['on', ''],
+	$GLOBALS['gpsmap_stub_last_params']);
+gpsmap_render_region(gpsmap_load_devices(true), 'all');
+assert_contains('thold: alert reaches XML', 'status="alert"', file_get_contents(gpsmap_xml_path('all', 'xml')));
+$GLOBALS['gpsmap_stub_missing_tables'] = ['plugin_gpsmap_dns_cache', 'thold_data'];
+$GLOBALS['gpsmap_stub_log']            = [];
+assert_equal('soft dependencies: missing optional tables keep literal Devices', 1, cacti_sizeof(gpsmap_load_devices(true)[0]));
+assert_true('soft dependencies: synchronous DNS fallback is logged with its upgrade remedy',
+	(bool) preg_grep('/resolving configured hostnames synchronously until the plugin upgrade succeeds/', $GLOBALS['gpsmap_stub_log']));
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '26', 'hostname' => 'legacy-name.example', 'cached_address' => null]),
+];
+$fallbackState = new GpsmapPollState();
+assert_equal('soft dependencies: a missing DNS table temporarily resolves named Devices', 1,
+	cacti_sizeof(gpsmap_load_devices(true, $fallbackState,
+		static fn (string $name): string => '192.0.2.26')[0]));
+$GLOBALS['gpsmap_stub_missing_tables'] = [];
+$GLOBALS['gpsmap_stub_plugins']        = [];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = $savedHosts;
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+
+// Rendering mutates the shared set, so it must be restored between subnets.
+gpsmap_render_region($loaded, '10.1.2.');
+$hidden = 0;
+
+foreach ($loaded as $g) {
+	foreach ($g as $h) {
+		if ($h->showMap == 0) {
+			$hidden++;
+		}
+	}
+}
+assert_true('render: a narrow subnet hides the others', $hidden > 0);
+
+gpsmap_render_region($loaded, 'all');
+$hidden = 0;
+
+foreach ($loaded as $g) {
+	foreach ($g as $h) {
+		if ($h->showMap == 0) {
+			$hidden++;
+		}
+	}
+}
+assert_equal('render: state is reset before each subnet', 0, $hidden);
+
+// Reusing the set must give the same bytes as rendering it fresh.
+gpsmap_render_region($loaded, '10.1.2.');
+$reused = file_get_contents(gpsmap_xml_path('10.1.2.', 'xml'));
+region('10.1.2.');
+assert_equal('render: reused set matches a fresh load', $reused, file_get_contents(gpsmap_xml_path('10.1.2.', 'xml')));
+
+// ------------------------------------------------------------------
+// Atomic writes
+// ------------------------------------------------------------------
+
+$xmldir = $root . '/plugins/gpsmap/XML';
+assert_equal('write: leaves no temp files behind', [], preg_grep('/\.tmp$/', scandir($xmldir)));
+
+/* Prefix de-duplication must stay correct now that it is keyed rather than
+ * searched: many Devices in one subnet still yield one prefix per depth. */
+$dupHosts = [];
+
+for ($i = 1; $i <= 5; $i++) {
+	$dupHosts[] = gpsmap_test_row(['id' => (string) (60 + $i), 'hostname' => '10.3.3.' . $i]);
+}
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = $dupHosts;
+
+$dupPrefixes = gpsmap_subnet_prefixes(gpsmap_load_devices(true));
+
+assert_equal('prefixes: repeated addresses collapse', ['10.', '10.3.', '10.3.3.'], $dupPrefixes);
+assert_equal('prefixes: no duplicates survive', count($dupPrefixes), count(array_unique($dupPrefixes)));
+
+/* rename() into an occupied directory name fails, exercising the staged-write
+ * rollback: the temp file is removed and the failure is logged. */
+$blocked = $xmldir . '/occupied';
+@mkdir($blocked, 0700, true);
+file_put_contents($blocked . '/child', 'x');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+assert_false('write: failed rename returns false', gpsmap_write_file($blocked, 'body'));
+assert_true('write: failed rename is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
+assert_equal('write: failed rename leaves no temp file', [], preg_grep('/occupied\..*\.tmp$/', scandir($xmldir)));
+
+/* A short write must not be renamed into place: the previous document has to
+ * survive and the failure has to be logged. */
+$target = $xmldir . '/shortwrite.xml';
+file_put_contents($target, 'original');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+$full                       = str_repeat('x', 64);
+
+assert_false('write: short write returns false', gpsmap_write_file('gpsmapshort://target', $full));
+assert_true('write: short write is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
+
+assert_equal('write: previous document survives a failure', 'original', file_get_contents($target));
+
 /* Two Devices resolving to one address must yield one graph link, not two.
  * The de-duplication guard used to test a different string than it stored. */
-$GLOBALS['gpsmap_stub_rows']['towers'] = array(array('templateID' => '10'));
-$GLOBALS['gpsmap_stub_rows']['hosts']  = array(
-	gpsmap_test_row(array('id' => '11', 'hostname' => '10.4.4.4', 'host_template_id' => '20')),
-	gpsmap_test_row(array('id' => '12', 'hostname' => '10.4.4.4', 'host_template_id' => '20')),
-);
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '11', 'hostname' => '10.4.4.4', 'host_template_id' => '20']),
+	gpsmap_test_row(['id' => '12', 'hostname' => '10.4.4.4', 'host_template_id' => '20']),
+];
 region('10.4.4.');
 $deepest = file_get_contents($root . '/plugins/gpsmap/XML/10.4.4-top.html');
 assert_equal('region: one link per address at the deepest level', 1, substr_count($deepest, 'graph_view.php'));
 
-/* Disk pressure must not publish a truncated document while reporting success. */
-$GLOBALS['gpsmap_stub_log'] = array();
+/* Overwriting an existing artefact is the normal case: the poller rewrites the
+ * same names every cycle. */
+$overwrite = gpsmap_xml_path('192.0.10', 'xml');
+assert_true('write: first write creates the file', gpsmap_write_file($overwrite, 'first'));
+assert_true('write: second write replaces it', gpsmap_write_file($overwrite, 'second'));
+assert_equal('write: contents are the newer document', 'second', file_get_contents($overwrite));
+assert_equal('write: no temp files survive', [],
+	preg_grep('/192\.0\.10\.xml\..*\.tmp$/', scandir(dirname($overwrite))));
+
+// Pruning is age based and restricted to names gpsmap owns.
+$staleMap = gpsmap_xml_path('10.99', 'xml');
+$freshMap = gpsmap_xml_path('10.98', 'xml');
+$foreign  = dirname($staleMap) . '/operator-note.txt';
+file_put_contents($staleMap, 'stale');
+file_put_contents($freshMap, 'fresh');
+file_put_contents($foreign, 'keep');
+touch($staleMap, time() - 1000);
+assert_equal('prune: removes one stale generated artefact', 1, gpsmap_prune_artifacts(time() - 500));
+assert_false('prune: stale generated artefact is gone', file_exists($staleMap));
+assert_true('prune: fresh generated artefact remains', file_exists($freshMap));
+assert_true('prune: foreign file remains', file_exists($foreign));
+
+$topLevelArtifacts = [
+	gpsmap_xml_path('all', 'xml'),
+	gpsmap_xml_path('all', 'kml'),
+	dirname($staleMap) . '/all-top.html',
+];
+
+foreach ($topLevelArtifacts as $artifact) {
+	file_put_contents($artifact, 'stale top level');
+	touch($artifact, time() - 1000);
+}
+
+assert_equal('prune: stale top-level XML, KML and navigation are all generated artifacts', 3,
+	gpsmap_prune_artifacts(time() - 500));
+
+foreach ($topLevelArtifacts as $artifact) {
+	assert_false('prune: stale top-level artifact is removed - ' . basename($artifact), file_exists($artifact));
+}
+
+/* A failed rename must leave the previous document in place rather than
+ * deleting it and hoping the retry works. */
+$xd   = $root . '/plugins/gpsmap/XML';
+$live = $xd . '/rename-guard.xml';
+file_put_contents($live, 'previous');
+@mkdir($xd . '/rename-guard-dir', 0700, true);
+file_put_contents($xd . '/rename-guard-dir/child', 'x');
+
+$GLOBALS['gpsmap_stub_log'] = [];
+assert_false('write: a failed rename reports failure', gpsmap_write_file($xd . '/rename-guard-dir', 'body'));
+assert_equal('write: the previous document is untouched', 'previous', file_get_contents($live));
+
+// Disk pressure must not publish a truncated document while reporting success.
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('write: a short write fails', gpsmap_write_file('gpsmapshort://target', str_repeat('x', 64)));
 assert_true('write: a short write is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
 
-/* A failed rename must roll back rather than leave a stray temp file. */
+// A failed rename must roll back rather than leave a stray temp file.
 $blocked = gpsmap_test_tmpdir() . '/plugins/gpsmap/XML/occupied';
 @mkdir($blocked, 0700, true);
 file_put_contents($blocked . '/child', 'x');
-$GLOBALS['gpsmap_stub_log'] = array();
+$GLOBALS['gpsmap_stub_log'] = [];
 assert_false('write: a failed rename fails', gpsmap_write_file($blocked, 'body'));
 assert_true('write: a failed rename is logged', str_contains($GLOBALS['gpsmap_stub_log'][0] ?? '', 'Unable to write to'));
-assert_equal('write: a failed rename leaves no temp file', array(),
+assert_equal('write: a failed rename leaves no temp file', [],
 	preg_grep('/occupied\..*\.tmp$/', scandir(gpsmap_test_tmpdir() . '/plugins/gpsmap/XML')));
 
 /* The Display Disabled Devices setting has to reach the query.  It never did:
  * pollinginitial.php assigns $enableAll inside callRegion(), so the global
  * region() read was always null and the setting was inert. */
-$GLOBALS['gpsmap_stub_rows']['hosts'] = array(gpsmap_test_row(array('id' => '31', 'hostname' => '10.7.7.1')));
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [gpsmap_test_row(['id' => '31', 'hostname' => '10.7.7.1'])];
 
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = '';
 region('all');
@@ -289,14 +614,441 @@ function gpsmap_test_tower_radius(string $xml): ?float {
 region('all');
 assert_not_contains('enableAll on: query does not filter disabled Devices', 'h.disabled = ?', $GLOBALS['gpsmap_stub_host_sql']);
 
-/* And it must not depend on a global the caller happens to have set. */
-$GLOBALS['enableAll'] = '';
+// And it must not depend on a global the caller happens to have set.
+$GLOBALS['enableAll']                                = '';
 $GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
 region('all');
 assert_not_contains('enableAll: a stale global does not override the setting', 'h.disabled = ?', $GLOBALS['gpsmap_stub_host_sql']);
 unset($GLOBALS['enableAll']);
 
-/* calcMeters is the retained deprecated alias. */
+/* A failed Device query and an estate with no mapped Devices both arrive as an
+ * empty set, but only the first is a reason to withhold publication.  Treating
+ * them alike meant a fresh install never got an all.xml at all. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = false;
+$loadState                            = new GpsmapPollState();
+gpsmap_load_devices(true, $loadState);
+assert_true('load: a failed query is reported', $loadState->loadFailed);
+
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+gpsmap_load_devices(true, $loadState);
+assert_false('load: an empty estate is not a failure', $loadState->loadFailed);
+
+$failedState                          = new GpsmapPollState();
+$emptyState                           = new GpsmapPollState();
+$GLOBALS['gpsmap_stub_rows']['hosts'] = false;
+gpsmap_load_devices(true, $failedState);
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+gpsmap_load_devices(true, $emptyState);
+assert_true('load: explicit poll state does not leak between cycles',
+	$failedState->loadFailed && !$emptyState->loadFailed);
+
+// An empty estate still publishes, so the map reflects reality.
+$emptyXml = gpsmap_xml_path('198.51.100', 'xml');
+assert_true('render: an empty estate reports successful publication',
+	gpsmap_render_region([[], []], '198.51.100'));
+assert_true('render: an empty estate still writes its documents', file_exists($emptyXml));
+assert_contains('render: the empty document is well formed', '<markers>', file_get_contents($emptyXml));
+
+// The staged write keeps the destination's mode, which the web server relies on.
+$modeTarget = gpsmap_xml_path('203.0.113', 'xml');
+gpsmap_write_file($modeTarget, 'first');
+chmod($modeTarget, 0644);
+$before = fileperms($modeTarget) & 0777;
+gpsmap_write_file($modeTarget, 'second');
+assert_equal('write: the destination mode survives the rename', $before, fileperms($modeTarget) & 0777);
+
+/* gpsmap_poller_bottom() is the refactor's only production entry point, so it
+ * is exercised directly rather than only through region(). */
+require_once __DIR__ . '/../includes/polling.php';
+
+$GLOBALS['gpsmap_stub_rows']['towers'] = [['templateID' => '10']];
+$GLOBALS['gpsmap_stub_rows']['hosts']  = [
+	gpsmap_test_row(['id' => '41', 'hostname' => '10.8.1.1', 'host_template_id' => '10']),
+	gpsmap_test_row(['id' => '42', 'hostname' => '10.8.2.2', 'host_template_id' => '20']),
+];
+$GLOBALS['gpsmap_stub_settings']['gpsmap_enableall'] = 'on';
+$GLOBALS['gpsmap_stub_settings']['path_php_binary']  = '/usr/bin/php';
+$GLOBALS['gpsmap_stub_log']                          = [];
+$GLOBALS['gpsmap_stub_background']                   = [];
+
+gpsmap_poller_bottom();
+
+assert_true('poller: publishes the top level', file_exists(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: publishes a subnet', file_exists(gpsmap_xml_path('10.8.1', 'xml')));
+assert_true('poller: logs a stats line',
+	(bool) preg_grep('/GPSMAP STATS: Mapped:2 /', $GLOBALS['gpsmap_stub_log']));
+assert_true('poller: schedules DNS refresh outside the poller',
+	(bool) preg_grep('/gpsmap_dns\.php/', array_column($GLOBALS['gpsmap_stub_background'], 1)));
+
+$savedBasePath                               = $GLOBALS['config']['base_path'];
+$GLOBALS['config']['base_path']              = '/opt/network tools/cacti';
+$GLOBALS['gpsmap_stub_background']           = [];
+gpsmap_schedule_dns_refresh();
+assert_equal('dns schedule: a path containing spaces is shell-safe',
+	cacti_escapeshellarg('/opt/network tools/cacti/plugins/gpsmap/gpsmap_dns.php'),
+	$GLOBALS['gpsmap_stub_background'][0][1]);
+$GLOBALS['config']['base_path'] = $savedBasePath;
+
+/* If the worker is unavailable long enough for the cache to become stale, a
+ * previously known Device remains visible but is never presented as fresh. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row([
+		'id'             => '46', 'hostname' => 'stale.example', 'cached_address' => '192.0.2.46',
+		'cache_is_fresh' => '0', 'cache_failures' => '8',
+	]),
+];
+$GLOBALS['gpsmap_stub_log'] = [];
+gpsmap_poller_bottom();
+assert_contains('poller: a stale last-known-good Device remains visible', 'id="46"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: stale last-known-good rendering is explicit in the log',
+	(bool) preg_grep('/explicitly stale last-known-good/', $GLOBALS['gpsmap_stub_log']));
+
+// Resolver/cache helpers are deterministic under an injected lookup.
+assert_equal('dns: literal bypasses lookup', '192.0.2.1', gpsmap_resolve_hostname('192.0.2.1'));
+assert_equal('dns: accepts A answers', '192.0.2.9', gpsmap_resolve_hostname('router-v4.example',
+	static fn (string $name): array => [['ip' => '192.0.2.9']]));
+assert_equal('dns: accepts AAAA answers', '2001:db8::9', gpsmap_resolve_hostname('router.example',
+	static fn (string $name): array => [['ipv6' => '2001:db8::9']]));
+assert_equal('dns: failed lookup is empty', '', gpsmap_resolve_hostname('missing.example',
+	static fn (string $name): bool => false,
+	static fn (string $name): string => $name));
+assert_equal('dns: invalid answers are empty', '', gpsmap_resolve_hostname('bad.example',
+	static fn (string $name): array => [['ip' => 'not-an-ip']],
+	static fn (string $name): string => $name));
+assert_equal('dns: NSS fallback accepts an address', '127.0.0.1', gpsmap_resolve_hostname('local.test',
+	static fn (string $name): bool => false,
+	static fn (string $name): string => '127.0.0.1'));
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [
+	['hostname' => '192.0.2.2'],
+	['hostname' => 'localhost.invalid'],
+];
+$GLOBALS['gpsmap_stub_execute'] = [];
+assert_equal('dns: refresh skips literal rows', 1, gpsmap_refresh_dns_cache(
+	static fn (string $name): string => '2001:db8::10'));
+assert_equal('dns: refresh writes one cache row', 1, count($GLOBALS['gpsmap_stub_execute']));
+assert_contains('dns: the work queue excludes literal addresses before LIMIT', 'INET6_ATON(h.hostname) IS NULL',
+	$GLOBALS['gpsmap_stub_last_sql']);
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [];
+
+for ($i = 0; $i < GPSMAP_DNS_REFRESH_BATCH_SIZE + 3; $i++) {
+	$GLOBALS['gpsmap_stub_rows']['dns'][] = ['hostname' => '192.0.2.' . ($i % 255)];
+}
+
+$GLOBALS['gpsmap_stub_rows']['dns'][] = ['hostname' => 'not-starved.example'];
+$resolvedNames                       = [];
+gpsmap_refresh_dns_cache(static function (string $name) use (&$resolvedNames): string {
+	$resolvedNames[] = $name;
+
+	return '192.0.2.61';
+});
+assert_equal('dns: literal-heavy estates do not starve hostname work', ['not-starved.example'], $resolvedNames);
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [['hostname' => 'missing.example']];
+$GLOBALS['gpsmap_stub_execute']     = [];
+$GLOBALS['gpsmap_stub_log']         = [];
+assert_equal('dns: a failed refresh reports no update', 0, gpsmap_refresh_dns_cache(
+	static fn (string $name): string => ''));
+assert_equal('dns: a failed refresh records one bounded failure', 1, count($GLOBALS['gpsmap_stub_execute']));
+assert_contains('dns: cache identity hashes rather than truncates the hostname', 'UNHEX(SHA2(?, 256))',
+	$GLOBALS['gpsmap_stub_execute'][0][0]);
+assert_contains('dns: a failed refresh increments the failure counter', 'failure_count = LEAST',
+	$GLOBALS['gpsmap_stub_execute'][0][0]);
+assert_true('dns: a failed refresh is logged',
+	(bool) preg_grep('/could not resolve a configured hostname/', $GLOBALS['gpsmap_stub_log']));
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [];
+
+for ($i = 0; $i < GPSMAP_DNS_REFRESH_BATCH_SIZE + 3; $i++) {
+	$GLOBALS['gpsmap_stub_rows']['dns'][] = ['hostname' => 'batch-' . $i . '.example'];
+}
+
+$GLOBALS['gpsmap_stub_execute'] = [];
+$batchLookups                   = 0;
+gpsmap_refresh_dns_cache(static function (string $name) use (&$batchLookups): string {
+	$batchLookups++;
+
+	return '192.0.2.50';
+});
+assert_equal('dns: one worker run is batch bounded', GPSMAP_DNS_REFRESH_BATCH_SIZE, $batchLookups);
+assert_contains('dns: the database query carries the same batch limit',
+	'LIMIT ' . GPSMAP_DNS_REFRESH_BATCH_SIZE, $GLOBALS['gpsmap_stub_last_sql']);
+assert_contains('dns: repeated failures use a wider retry window', 'failure_count >= 4',
+	$GLOBALS['gpsmap_stub_last_sql']);
+assert_contains('dns: the work queue is compatible with ONLY_FULL_GROUP_BY', 'GROUP BY h.hostname',
+	$GLOBALS['gpsmap_stub_last_sql']);
+assert_contains('dns: ordering uses an aggregate compatible with ONLY_FULL_GROUP_BY', 'ORDER BY MIN(dc.attempted_at) IS NULL',
+	$GLOBALS['gpsmap_stub_last_sql']);
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [['hostname' => 'deferred.example']];
+$GLOBALS['gpsmap_stub_execute']     = [];
+$GLOBALS['gpsmap_stub_log']         = [];
+$clockReads                         = 0;
+$timedLookups                       = 0;
+assert_equal('dns: an exhausted time budget reports no updates', 0, gpsmap_refresh_dns_cache(
+	static function (string $name) use (&$timedLookups): string {
+		$timedLookups++;
+
+		return '192.0.2.51';
+	},
+	static function () use (&$clockReads): float {
+		return $clockReads++ === 0 ? 0.0 : GPSMAP_DNS_REFRESH_TIME_BUDGET;
+	}
+));
+assert_equal('dns: an exhausted time budget defers lookup work', 0, $timedLookups);
+assert_true('dns: an exhausted time budget is logged',
+	(bool) preg_grep('/reached its time budget/', $GLOBALS['gpsmap_stub_log']));
+
+$shutdownCleanup                                  = null;
+$GLOBALS['gpsmap_stub_process_registration']      = true;
+$GLOBALS['gpsmap_stub_process_unregisters']       = 0;
+$GLOBALS['gpsmap_stub_rows']['dns']               = [];
+assert_true('dns worker: shutdown cleanup completes the worker', gpsmap_run_dns_refresh_worker(
+	static function () use (&$shutdownCleanup): void {
+		assert(is_callable($shutdownCleanup));
+		$shutdownCleanup();
+	},
+	static function (callable $cleanup) use (&$shutdownCleanup): void {
+		$shutdownCleanup = $cleanup;
+	}
+));
+assert_equal('dns worker: shutdown cleanup releases registration exactly once', 1,
+	$GLOBALS['gpsmap_stub_process_unregisters']);
+
+$GLOBALS['gpsmap_stub_process_registration'] = true;
+$GLOBALS['gpsmap_stub_process_unregisters']  = 0;
+$refreshThrew                                = false;
+
+try {
+	gpsmap_run_dns_refresh_worker(
+		static function (): void {
+			throw new RuntimeException('refresh failed');
+		},
+		static function (callable $cleanup): void {
+		}
+	);
+} catch (RuntimeException) {
+	$refreshThrew = true;
+}
+
+assert_true('dns worker: refresh exceptions propagate to the CLI boundary', $refreshThrew);
+assert_equal('dns worker: refresh exceptions still release registration', 1,
+	$GLOBALS['gpsmap_stub_process_unregisters']);
+
+$GLOBALS['gpsmap_stub_rows']['dns']                                  = false;
+$GLOBALS['gpsmap_stub_log']                                          = [];
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_dns_last_success']   = '';
+assert_equal('dns worker: a failed work-queue query returns failure status', 1, gpsmap_dns_refresh_exit_code());
+assert_equal('dns worker: a failed work-queue query does not claim success', '',
+	$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_dns_last_success']);
+assert_true('dns worker: a failed work-queue query is logged',
+	(bool) preg_grep('/could not read the hostname cache work queue/', $GLOBALS['gpsmap_stub_log']));
+
+$GLOBALS['gpsmap_stub_rows']['dns']      = [['hostname' => 'missing-write.example']];
+$GLOBALS['gpsmap_stub_execute_result']   = false;
+$GLOBALS['gpsmap_stub_log']              = [];
+assert_false('dns: a failed lookup-counter write fails the cycle', gpsmap_refresh_dns_cache(
+	static fn (string $name): string => ''));
+assert_true('dns: a failed lookup-counter write is logged',
+	(bool) preg_grep('/could not record a failed hostname lookup/', $GLOBALS['gpsmap_stub_log']));
+
+$GLOBALS['gpsmap_stub_rows']['dns'] = [['hostname' => 'resolved-write.example']];
+$GLOBALS['gpsmap_stub_log']         = [];
+assert_false('dns: a failed resolved-address write fails the cycle', gpsmap_refresh_dns_cache(
+	static fn (string $name): string => '192.0.2.60'));
+assert_true('dns: a failed resolved-address write is logged',
+	(bool) preg_grep('/could not store a resolved hostname/', $GLOBALS['gpsmap_stub_log']));
+unset($GLOBALS['gpsmap_stub_execute_result']);
+
+$GLOBALS['gpsmap_stub_process_registration']  = false;
+$GLOBALS['gpsmap_stub_process_unregisters']   = 0;
+$GLOBALS['gpsmap_stub_log']                   = [];
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_dns_last_success'] = '';
+assert_equal('dns worker: a registration conflict returns failure status', 1, gpsmap_dns_refresh_exit_code());
+assert_equal('dns worker: a registration conflict does not unregister another worker', 0,
+	$GLOBALS['gpsmap_stub_process_unregisters']);
+assert_equal('dns worker: a registration conflict does not claim success', '',
+	$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_dns_last_success']);
+assert_true('dns worker: a registration conflict is logged',
+	(bool) preg_grep('/another worker owns the process registration/', $GLOBALS['gpsmap_stub_log']));
+
+$GLOBALS['gpsmap_stub_process_registration'] = true;
+$GLOBALS['gpsmap_stub_rows']['dns']          = [];
+assert_equal('dns worker: a registered worker returns success status', 0, gpsmap_dns_refresh_exit_code());
+assert_equal('dns worker: a registered worker always unregisters', 1,
+	$GLOBALS['gpsmap_stub_process_unregisters']);
+assert_true('dns worker: a completed worker records liveness',
+	(int) $GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_dns_last_success'] > 0);
+
+// A failed Device query must leave the published map alone.
+file_put_contents(gpsmap_xml_path('all', 'xml'), '<markers><marker id="99"/></markers>');
+$GLOBALS['gpsmap_stub_rows']['hosts'] = false;
+$GLOBALS['gpsmap_stub_log']           = [];
+
+gpsmap_poller_bottom();
+
+assert_contains('poller: a failed query keeps the previous map', 'id="99"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: the failure is logged',
+	(bool) preg_grep('/could not read the Device list/', $GLOBALS['gpsmap_stub_log']));
+
+/* A cold DNS cache does not stop healthy Devices from publishing, but pruning
+ * remains deferred so the unresolved Device's last-known subnet survives. */
+$coldPrefix = gpsmap_xml_path('10.77', 'xml');
+file_put_contents($coldPrefix, 'previous subnet');
+touch($coldPrefix, time() - 10000);
+file_put_contents(gpsmap_xml_path('all', 'xml'), '<markers><marker id="43" name="Last known" '
+	. 'address="cold-cache.example" lat="51.5" lng="-0.1" availability="99" /></markers>');
+file_put_contents(gpsmap_xml_path('all', 'kml'), 'last-known kml');
+file_put_contents($root . '/plugins/gpsmap/XML/all-top.html', 'last-known menu');
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row(['id' => '43', 'hostname' => 'cold-cache.example', 'cached_address' => null]),
+	gpsmap_test_row(['id' => '44', 'hostname' => '10.88.1.1']),
+];
+$GLOBALS['gpsmap_stub_log']        = [];
+$GLOBALS['gpsmap_stub_background'] = [];
+
+gpsmap_poller_bottom();
+
+assert_contains('poller: unresolved hostname does not block healthy Devices', 'id="44"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_contains('poller: unresolved hostname retains its last-known marker', 'id="43"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_contains('poller: a preserved marker is visibly downgraded', 'status="undefined"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_contains('poller: unresolved hostname retains a degraded KML placemark', 'Last known',
+	file_get_contents(gpsmap_xml_path('all', 'kml')));
+assert_contains('poller: one unresolved hostname does not freeze healthy KML', 'Device &lt;one&gt;',
+	file_get_contents(gpsmap_xml_path('all', 'kml')));
+assert_not_contains('poller: one unresolved hostname does not freeze navigation', 'last-known menu',
+	file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
+assert_contains('poller: healthy subnet navigation remains current', 'subnet=10',
+	file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
+assert_true('poller: unresolved hostname cannot trigger pruning', file_exists($coldPrefix));
+assert_true('poller: unresolved hostname is logged',
+	(bool) preg_grep('/Device IDs: 43/', $GLOBALS['gpsmap_stub_log']));
+assert_true('poller: cold cache schedules the background resolver',
+	(bool) preg_grep('/gpsmap_dns\.php/', array_column($GLOBALS['gpsmap_stub_background'], 1)));
+
+$malformedPreviousState                      = new GpsmapPollState();
+$malformedPreviousState->unresolvedDeviceIds = ['43'];
+$freshDocument                               = '<markers><marker id="44" /></markers>';
+gpsmap_write_file(gpsmap_xml_path('10.79', 'xml'), '<markers><broken></markers>');
+assert_equal('poller: malformed previous XML leaves the fresh snapshot unchanged', $freshDocument,
+	gpsmap_preserve_unresolved_markers($freshDocument, '10.79', $malformedPreviousState));
+
+$unrelatedPreservationState                               = new GpsmapPollState();
+$unrelatedPreservationState->preservedArtifacts['10.77'] = true;
+gpsmap_write_file($root . '/plugins/gpsmap/XML/10.88-top.html', 'stale unrelated menu');
+assert_true('poller: preservation in one subnet does not suppress another subnet',
+	gpsmap_render_region(gpsmap_load_devices(true), '10.88', $unrelatedPreservationState));
+assert_not_contains('poller: unrelated subnet navigation is regenerated', 'stale unrelated menu',
+	file_get_contents($root . '/plugins/gpsmap/XML/10.88-top.html'));
+
+preg_match('/gpsmapPreservedAt="([0-9]+)"/', file_get_contents(gpsmap_xml_path('all', 'xml')), $firstPreservedAt);
+gpsmap_poller_bottom();
+preg_match('/gpsmapPreservedAt="([0-9]+)"/', file_get_contents(gpsmap_xml_path('all', 'xml')), $secondPreservedAt);
+assert_true('poller: a preserved marker receives an absolute expiry timestamp',
+	(int) ($firstPreservedAt[1] ?? 0) > 0);
+assert_equal('poller: republication does not refresh the preservation timestamp',
+	$firstPreservedAt[1] ?? null, $secondPreservedAt[1] ?? null);
+
+/* The XML timestamp is independent of the DNS failure counter, so a failed
+ * counter update cannot make a republished marker immortal. */
+$expiredAt = time() - GPSMAP_PRESERVED_MARKER_TTL - 1;
+file_put_contents(gpsmap_xml_path('all', 'xml'),
+	'<markers><marker id="43" name="Expired" gpsmapPreservedAt="' . $expiredAt . '" /></markers>');
+file_put_contents(gpsmap_xml_path('all', 'kml'), 'expired kml');
+file_put_contents($root . '/plugins/gpsmap/XML/all-top.html', 'expired menu');
+touch($coldPrefix, time() - 10000);
+$GLOBALS['gpsmap_stub_log'] = [];
+
+gpsmap_poller_bottom();
+
+assert_not_contains('poller: preservation TTL expires a stale marker independently', 'id="43"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_not_contains('poller: preservation TTL releases KML publication', 'expired kml',
+	file_get_contents(gpsmap_xml_path('all', 'kml')));
+assert_not_contains('poller: preservation TTL releases navigation publication', 'expired menu',
+	file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
+assert_false('poller: preservation TTL releases artifact pruning', file_exists($coldPrefix));
+
+/* Repeated permanent failures must eventually stop freezing KML, navigation,
+ * and pruning. The last-known marker is a grace mechanism, not an immortal
+ * record for a Device that can no longer resolve. */
+touch($coldPrefix, time() - 10000);
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [
+	gpsmap_test_row([
+		'id'             => '43', 'hostname' => 'cold-cache.example', 'cached_address' => null,
+		'cache_is_fresh' => '0', 'cache_failures' => '4',
+	]),
+	gpsmap_test_row(['id' => '44', 'hostname' => '10.88.1.1']),
+];
+$GLOBALS['gpsmap_stub_log'] = [];
+
+gpsmap_poller_bottom();
+
+assert_not_contains('poller: repeated DNS failures expire the old marker', 'id="43"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_not_contains('poller: repeated DNS failures refresh KML', 'last-known kml',
+	file_get_contents(gpsmap_xml_path('all', 'kml')));
+assert_not_contains('poller: repeated DNS failures refresh navigation', 'last-known menu',
+	file_get_contents($root . '/plugins/gpsmap/XML/all-top.html'));
+assert_false('poller: repeated DNS failures allow stale artifact pruning', file_exists($coldPrefix));
+assert_true('poller: an expired DNS entry is logged',
+	(bool) preg_grep('/repeated DNS failures/', $GLOBALS['gpsmap_stub_log']));
+
+// Missing schema and configuration fail visibly without launching junk work.
+$GLOBALS['gpsmap_stub_missing_tables'] = ['plugin_gpsmap_dns_cache'];
+$GLOBALS['gpsmap_stub_log']            = [];
+$GLOBALS['gpsmap_stub_background']     = [];
+gpsmap_schedule_dns_refresh();
+assert_equal('dns schedule: missing cache table launches nothing', [], $GLOBALS['gpsmap_stub_background']);
+assert_true('dns schedule: missing cache table is logged',
+	(bool) preg_grep('/DNS cache table is unavailable/', $GLOBALS['gpsmap_stub_log']));
+$GLOBALS['gpsmap_stub_missing_tables'] = [];
+
+$GLOBALS['gpsmap_stub_settings']['path_php_binary']  = '';
+$GLOBALS['gpsmap_stub_log']                          = [];
+gpsmap_schedule_dns_refresh();
+assert_true('dns schedule: missing PHP path is logged',
+	(bool) preg_grep('/PHP binary path is not configured/', $GLOBALS['gpsmap_stub_log']));
+$GLOBALS['gpsmap_stub_settings']['path_php_binary'] = '/usr/bin/php';
+
+/* A failed snapshot write must suppress pruning. This models a full or
+ * read-only artifact filesystem by making all.xml an unwritable directory. */
+$writeGuard = gpsmap_xml_path('10.76', 'xml');
+file_put_contents($writeGuard, 'last good subnet');
+touch($writeGuard, time() - 10000);
+$allXml = gpsmap_xml_path('all', 'xml');
+unlink($allXml);
+mkdir($allXml);
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [gpsmap_test_row(['id' => '45', 'hostname' => '10.89.1.1'])];
+$GLOBALS['gpsmap_stub_log']           = [];
+assert_false('render: a failed snapshot write reports failure',
+	gpsmap_render_region(gpsmap_load_devices(true), 'all', new GpsmapPollState()));
+gpsmap_poller_bottom();
+assert_true('poller: a failed snapshot write suppresses pruning', file_exists($writeGuard));
+assert_true('poller: a failed snapshot write is logged',
+	(bool) preg_grep('/did not prune artifacts/', $GLOBALS['gpsmap_stub_log']));
+rmdir($allXml);
+file_put_contents($allXml, '<markers><marker id="99"/></markers>');
+
+/* An estate with no mapped Devices still publishes, so a new install is not
+ * left fetching a 404 forever. */
+$GLOBALS['gpsmap_stub_rows']['hosts'] = [];
+$GLOBALS['gpsmap_stub_log']           = [];
+
+gpsmap_poller_bottom();
+
+assert_not_contains('poller: an empty estate republishes', 'id="99"',
+	file_get_contents(gpsmap_xml_path('all', 'xml')));
+assert_true('poller: the empty estate is explained',
+	(bool) preg_grep('/no Devices to map/', $GLOBALS['gpsmap_stub_log']));
+
+// calcMeters is the retained deprecated alias.
 assert_equal('calcMeters: delegates to calcKm', calcKm(1.0, 2.0, 3.0, 4.0), calcMeters(1.0, 2.0, 3.0, 4.0));
 
 if (!defined('GPSMAP_TEST_SUITE')) {
diff --git a/tests/test_upgrade.php b/tests/test_upgrade.php
new file mode 100644
index 0000000..985269c
--- /dev/null
+++ b/tests/test_upgrade.php
@@ -0,0 +1,302 @@
+<?php
+/*
+ +-------------------------------------------------------------------------+
+ | Copyright (C) 2004-2026 The Cacti Group                                 |
+ +-------------------------------------------------------------------------+
+ | The upgrade path used to re-run every migration on each request because  |
+ | the version it gates on was never persisted.  On a large host table that |
+ | is a full rebuild plus a metadata lock, per page load.                   |
+ +-------------------------------------------------------------------------+
+*/
+
+if (PHP_SAPI !== 'cli') {
+	exit;
+}
+
+require_once __DIR__ . '/harness.php';
+
+/* Record the DDL the migration issues, and let set_config_option write to the
+ * same store read_config_option reads. */
+$GLOBALS['gpsmap_stub_ddl'] = [];
+
+if (!function_exists('db_execute')) {
+	function db_execute($sql, $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = $sql;
+
+		return empty($GLOBALS['gpsmap_stub_fail_ddl']);
+	}
+}
+
+if (!function_exists('db_execute_prepared')) {
+	function db_execute_prepared($sql, $params = [], $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = $sql;
+
+		if (isset($GLOBALS['gpsmap_stub_execute'])) {
+			$GLOBALS['gpsmap_stub_execute'][] = [$sql, $params];
+		}
+
+		if (!empty($GLOBALS['gpsmap_stub_reject_double_quoted_literals']) && str_contains($sql, '"gpsmap"')) {
+			return false;
+		}
+
+		return $GLOBALS['gpsmap_stub_execute_result'] ?? true;
+	}
+}
+
+if (!function_exists('set_config_option')) {
+	function set_config_option($name, $value) {
+		$GLOBALS['gpsmap_stub_settings'][$name] = (string) $value;
+	}
+}
+
+if (!function_exists('db_column_exists')) {
+	function db_column_exists($table, $column, $log = true, $db_conn = false) {
+		return empty($GLOBALS['gpsmap_stub_missing_column']);
+	}
+}
+
+if (!function_exists('db_table_exists')) {
+	function db_table_exists($table, $log = true, $db_conn = false) {
+		return true;
+	}
+}
+
+if (!function_exists('db_index_exists')) {
+	function db_index_exists($table, $index, $log = true, $db_conn = false) {
+		return $GLOBALS['gpsmap_stub_index_exists'] ?? true;
+	}
+}
+
+if (!function_exists('db_add_index')) {
+	function db_add_index($table, $type, $name, $columns, $log = true, $db_conn = false) {
+		$GLOBALS['gpsmap_stub_ddl'][] = 'ADD INDEX ' . $name;
+
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_db_add_column')) {
+	function api_plugin_db_add_column($plugin, $table, $column) {
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_db_table_create')) {
+	function api_plugin_db_table_create($plugin, $table, $data) {
+		$GLOBALS['gpsmap_stub_tables'][$table] = $data;
+
+		return true;
+	}
+}
+
+if (!function_exists('api_plugin_register_hook')) {
+	function api_plugin_register_hook(...$args) {
+	}
+}
+
+if (!function_exists('api_plugin_register_realm')) {
+	function api_plugin_register_realm(...$args) {
+	}
+}
+
+if (!function_exists('get_current_page')) {
+	function get_current_page() {
+		return $GLOBALS['gpsmap_stub_current_page'] ?? 'gpsmap.php';
+	}
+}
+
+gpsmap_test_use_tmp_root();
+$GLOBALS['config']['library_path'] = sys_get_temp_dir();
+file_put_contents(sys_get_temp_dir() . '/database.php', "<?php\n");
+
+require_once __DIR__ . '/../setup.php';
+require_once __DIR__ . '/../includes/setup/database.php';
+
+$info = plugin_gpsmap_version();
+
+// A successful fresh install records its schema version before any page check.
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version'] = '';
+$GLOBALS['gpsmap_stub_ddl']                               = [];
+$GLOBALS['gpsmap_stub_execute']                           = [];
+plugin_gpsmap_install();
+assert_equal('install: a successful schema install records the current version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+assert_equal('install: plugin_config version update uses two placeholders',
+	'UPDATE plugin_config SET version = ? WHERE directory = ?', $GLOBALS['gpsmap_stub_execute'][0][0]);
+assert_equal('install: plugin_config directory is bound safely under ANSI_QUOTES',
+	[$info['version'], 'gpsmap'], $GLOBALS['gpsmap_stub_execute'][0][1]);
+$GLOBALS['gpsmap_stub_current_page'] = 'plugins.php';
+$GLOBALS['gpsmap_stub_ddl']          = [];
+gpsmap_check_upgrade();
+assert_equal('install: the first plugins.php check issues no ALTER TABLE', [],
+	preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl']));
+$GLOBALS['gpsmap_stub_current_page']                      = 'gpsmap.php';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version'] = '';
+unset($GLOBALS['gpsmap_stub_execute']);
+
+// First run from an unknown previous version: the migrations fire.
+$GLOBALS['gpsmap_stub_ddl']                           = [];
+$GLOBALS['gpsmap_stub_reject_double_quoted_literals'] = true;
+gpsmap_upgrade_database('');
+$first = $GLOBALS['gpsmap_stub_ddl'];
+unset($GLOBALS['gpsmap_stub_reject_double_quoted_literals']);
+
+assert_true('upgrade: a fresh install runs the column migration', (bool) preg_grep('/ALTER TABLE host CHANGE COLUMN latitude/', $first));
+assert_equal('upgrade: no backticked literal default reaches MySQL', [], preg_grep('/SET DEFAULT `/', $first));
+assert_equal('upgrade: plugin_config update remains valid under ANSI_QUOTES', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+assert_equal('upgrade: DNS cache key fits legacy InnoDB limits', 'binary(32)',
+	$GLOBALS['gpsmap_stub_tables']['plugin_gpsmap_dns_cache']['columns'][0]['type']);
+assert_equal('upgrade: DNS cache retains the full configured hostname', 'varchar(255)',
+	$GLOBALS['gpsmap_stub_tables']['plugin_gpsmap_dns_cache']['columns'][1]['type']);
+
+// The version has to be persisted where gpsmap_check_upgrade() reads it.
+assert_equal(
+	'upgrade: version is persisted to the option the guard reads',
+	$info['version'],
+	read_config_option('plugin_gpsmap_version', true)
+);
+
+// Second run, now that the version matches: no DDL against host at all.
+$GLOBALS['gpsmap_stub_ddl'] = [];
+gpsmap_upgrade_database((string) $info['version']);
+
+assert_equal(
+	'upgrade: a current install issues no ALTER TABLE',
+	[],
+	preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl'])
+);
+
+// Pre-2.1 installs without the unique index get it added exactly once.
+$GLOBALS['gpsmap_stub_index_exists'] = false;
+$GLOBALS['gpsmap_stub_ddl']          = [];
+gpsmap_upgrade_database('2.0');
+assert_true('upgrade: missing unique index is added', (bool) preg_grep('/ADD INDEX templateID/', $GLOBALS['gpsmap_stub_ddl']));
+
+$GLOBALS['gpsmap_stub_index_exists'] = true;
+$GLOBALS['gpsmap_stub_ddl']          = [];
+gpsmap_upgrade_database('2.0');
+assert_equal('upgrade: existing index is not re-added', [], preg_grep('/ADD INDEX/', $GLOBALS['gpsmap_stub_ddl']));
+
+// And the guard itself now goes quiet.
+assert_true(
+	'upgrade: the guard is satisfied after one run',
+	$info['version'] == read_config_option('plugin_gpsmap_version', true)
+);
+
+/* A failed migration must not mark the plugin as current, or the upgrade never
+ * runs again and the schema stays behind silently. */
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version'] = '';
+$GLOBALS['gpsmap_stub_ddl']                               = [];
+$GLOBALS['gpsmap_stub_fail_ddl']                          = true;
+
+gpsmap_upgrade_database('');
+
+assert_equal('upgrade: a failed migration leaves the version unrecorded', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+assert_true('upgrade: the failure is logged',
+	str_contains(implode(' ', $GLOBALS['gpsmap_stub_log'] ?? []), 'did not complete'));
+
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = false;
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+gpsmap_upgrade_database('');
+assert_equal('upgrade: a successful migration records the version',
+	$info['version'], read_config_option('plugin_gpsmap_version', true));
+
+/* A failed migration must back off rather than retry from every page view, and
+ * must never record the version while the schema is behind. */
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = true;
+$GLOBALS['gpsmap_stub_log']                                           = [];
+
+gpsmap_upgrade_database('');
+
+assert_equal('upgrade: a failure never records the version', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+assert_true('upgrade: a backoff is recorded',
+	(int) read_config_option('plugin_gpsmap_upgrade_retry_after', true) > time());
+
+// While the backoff is live, no further DDL is attempted.
+$GLOBALS['gpsmap_stub_ddl'] = [];
+$GLOBALS['gpsmap_stub_log'] = [];
+gpsmap_upgrade_database('');
+assert_equal('upgrade: the backoff suppresses the retry', [], $GLOBALS['gpsmap_stub_ddl']);
+assert_true('upgrade: the deferred retry is logged',
+	(bool) preg_grep('/retry is deferred/', $GLOBALS['gpsmap_stub_log']));
+
+// An explicit operator upgrade bypasses the automatic retry backoff.
+$GLOBALS['gpsmap_stub_fail_ddl'] = false;
+$GLOBALS['gpsmap_stub_ddl']      = [];
+gpsmap_upgrade_database('', true);
+assert_true('upgrade: an operator retry bypasses the backoff',
+	(bool) preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl']));
+assert_equal('upgrade: an operator retry records the version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+
+/* Automatic requests stop issuing schema DDL after a bounded number of
+ * failures. An explicit Plugin Management action remains the recovery path. */
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_failures']    = (string) GPSMAP_UPGRADE_MAX_FAILURES;
+$GLOBALS['gpsmap_stub_ddl']                                           = [];
+$GLOBALS['gpsmap_stub_log']                                           = [];
+gpsmap_upgrade_database('');
+assert_equal('upgrade: repeated failures suspend automatic DDL', [], $GLOBALS['gpsmap_stub_ddl']);
+assert_true('upgrade: suspended automatic DDL is logged',
+	(bool) preg_grep('/suspended after repeated failures/', $GLOBALS['gpsmap_stub_log']));
+
+$GLOBALS['gpsmap_stub_ddl'] = [];
+gpsmap_upgrade_database('', true);
+assert_true('upgrade: an explicit retry bypasses the failure limit',
+	(bool) preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl']));
+assert_equal('upgrade: a successful explicit retry clears the failure count', '0',
+	(string) read_config_option('plugin_gpsmap_upgrade_failures', true));
+
+/* Plugin Management invokes the explicit upgrade hook from plugins.php. That
+ * operator action must bypass both the page filter and the retry backoff. */
+$GLOBALS['gpsmap_stub_current_page']                                  = 'plugins.php';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = (string) (time() + 300);
+$GLOBALS['gpsmap_stub_ddl']                                           = [];
+gpsmap_check_upgrade(true);
+assert_true('upgrade: Plugin Management bypasses the page filter',
+	(bool) preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl']));
+assert_equal('upgrade: Plugin Management records the version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+$GLOBALS['gpsmap_stub_current_page'] = 'gpsmap.php';
+
+// The normal plugins.php configuration check also performs a pending upgrade.
+$GLOBALS['gpsmap_stub_current_page']                                  = 'plugins.php';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_ddl']                                           = [];
+gpsmap_check_upgrade();
+assert_true('upgrade: plugins.php automatically runs a pending migration',
+	(bool) preg_grep('/ALTER TABLE/', $GLOBALS['gpsmap_stub_ddl']));
+assert_equal('upgrade: plugins.php records the completed version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+$GLOBALS['gpsmap_stub_current_page'] = 'gpsmap.php';
+
+// Once it expires and the cause clears, the upgrade completes and re-arms.
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_fail_ddl']                                      = false;
+gpsmap_upgrade_database('');
+assert_equal('upgrade: recovery records the version', $info['version'],
+	read_config_option('plugin_gpsmap_version', true));
+assert_equal('upgrade: recovery clears the backoff', '0',
+	(string) read_config_option('plugin_gpsmap_upgrade_retry_after', true));
+
+// A missing host column means the schema work failed, whatever the helpers say.
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_version']             = '';
+$GLOBALS['gpsmap_stub_settings']['plugin_gpsmap_upgrade_retry_after'] = '0';
+$GLOBALS['gpsmap_stub_missing_column']                                = true;
+gpsmap_upgrade_database('');
+assert_equal('upgrade: a missing column blocks the version write', '',
+	(string) read_config_option('plugin_gpsmap_version', true));
+$GLOBALS['gpsmap_stub_missing_column'] = false;
+
+if (!defined('GPSMAP_TEST_SUITE')) {
+	exit(gpsmap_test_summary());
+}