Bring script headers onto the template and close safeguard gaps

Headers claimed protections the code never had, and several destructive paths had no
guard against a collapsed config value.

Tools/arr_rescan_monitor.sh

@@ -19,6 +19,58 @@
 # this for scans it triggers itself; this tool covers everything else.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Validate the arr type and resolve its URL / API key / API version
+#   2. Poll /command for any active rescan-type command (ARR_RESCAN_COMMANDS)
+#        none active → nothing to watch, exit cleanly
+#   3. Wait for it to leave the active state, bounded by the timeout argument
+#        (default 7200s — a full-library scan is slow by nature)
+#   4. Once finished, fetch the library and arr_cache_write() the real numbers
+#
+# Triggers nothing. It only watches a scan someone or something else started.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Watch, Never Trigger
+#   This tool deliberately starts nothing. Its whole job is to be the thing that notices a
+#   scan finished, so a rescan begun by hand, by the arr's own UI, or by another script
+#   still gets its result written through to the shared cache.
+#
+# Complement to the Write Guard
+#   arr_cache_write() refuses to write while a rescan is active, because a mid-scan snapshot
+#   reads as real data loss to consumers like check_tracked_count_floor. That guard protects
+#   the cache but leaves nobody to write the true number afterwards. arr_full_rescan.sh
+#   covers the scans it starts itself; this covers every other origin.
+#
+# Bounded Wait
+#   The wait is capped by the timeout argument, so a scan that stalls or never reports
+#   completion cannot leave this running indefinitely holding its lock.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# host*.conf (aliased by detect_hosts())
+#
+#   SONARR_URL / SONARR_API_KEY
+#   RADARR_URL / RADARR_API_KEY
+#   LIDARR_URL / LIDARR_API_KEY
+#       Connection details for whichever arr is passed as the first argument.
+#
+# common.sh
+#
+#   ARR_RESCAN_COMMANDS
+#       Command names treated as a rescan for this purpose — shared with
+#       arr_cache_write()'s own active-scan guard so both agree on what counts.
+#
+#   ARR_API_VERSION
+#       Per-arr API version map (v3 for Sonarr/Radarr, v1 for Lidarr).
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -59,6 +111,10 @@ if [[ "$EUID" -ne 0 ]]; then
     exit 1
 fi
 
+# This writes the shared tracked-data cache on completion. Two monitors watching the same
+# arr would both write it, and the loser's stale snapshot could land last.
+acquire_lock
+
 detect_hosts
 
 ARR_TYPE="${PARSED_ARGS[0]:-}"