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.

System_Essentials/conf_cache_save.sh

@@ -18,6 +18,19 @@
 # Path adapts to storage mode: $SCRIPTS_DIR/.cache/vv/d (internal or appdata).
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Gates — PARTNERSHIP_ENABLED, and a validated PERSISTENT_CONF_CACHE path
+#   2. No RAM cache present → exit 0, nothing to snapshot
+#   3. For each host*.conf in the RAM cache:
+#        own conf     → skip (always on disk, never needs saving)
+#        partner conf → copy to $PERSISTENT_CONF_CACHE, mode 600
+#
+# Counterpart to conf_cache_restore.sh, which consumes and then clears this backup
+# at the next array start.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -34,9 +47,70 @@
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
-#   require_partnership — exits early if PARTNERSHIP_ENABLED=false
-#   detect_hosts()      — determines which confs to save (partner confs only)
-#   No-cache guard      — exits cleanly if RAM cache is empty or missing
+# Root Enforcement
+#   Writes into $PERSISTENT_CONF_CACHE under the plugin directory.
+#
+# Lock Acquisition
+#   acquire_lock prevents this racing conf_cache_restore.sh or the conf cache
+#   watchdog over the same backup directory.
+#
+# Partnership Gate
+#   require_partnership exits early if PARTNERSHIP_ENABLED=false.
+#
+# Host Detection
+#   detect_hosts() determines which confs are partner confs and which is our own.
+#
+# Cache Path Sanity Guard
+#   PERSISTENT_CONF_CACHE is validated as an absolute path at least three levels
+#   deep before anything is written. It is built from ${SCRIPTS_DIR}; if that were
+#   unset the copy target would collapse to "/host2.conf", dropping partner
+#   passwords and API keys at the filesystem root.
+#
+# No-Cache Guard
+#   Exits cleanly if the RAM cache is missing or empty — nothing to snapshot is a
+#   normal state, not an error.
+#
+# Own-Conf Exclusion
+#   Our own conf is never written into the partner backup. Restoring it later
+#   would overwrite live local config with a stale copy.
+#
+# Credential File Permissions
+#   The backup directory is created 700 and each conf written 600. These files
+#   carry partner NPM/lldap passwords and API keys and must not inherit the
+#   default umask on a path that survives reboot.
+#
+# Dry Run Support
+#   --dry-run reports every file it would write and writes none.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# master.conf
+#
+#   PERSISTENT_CONF_CACHE
+#       Reboot-surviving destination for the partner conf backup. Built from
+#       ${SCRIPTS_DIR}, so it follows the active storage mode.
+#
+#   CONF_RAM_CACHE_DIR
+#       Source RAM cache (tmpfs, /tmp/.cache/vv/d) populated by conf_sync.sh.
+#
+#   PARTNERSHIP_ENABLED
+#       Checked via require_partnership().
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# conf_cache_save.sh
+#     Snapshot partner confs from the RAM cache to the persistent backup.
+#     Runs first in ARRAY_STOP_SCRIPTS.
+#
+# conf_cache_save.sh --dry-run
+#     Report what would be saved without writing anything
+#
+# conf_cache_save.sh --log
+#     Verbose per-file output
 #
 # ==============================================================================================
 
@@ -44,11 +118,30 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../load_config.sh"
 
 parse_args "$@"
+
+if [[ "$EUID" -ne 0 ]]; then
+    error "Must be run as root"
+    exit 1
+fi
+
+acquire_lock
+
 detect_hosts
 require_partnership
 
 RAM_CACHE="$CONF_RAM_CACHE_DIR"
-SAVE_DIR="$PERSISTENT_CONF_CACHE"
+SAVE_DIR="${PERSISTENT_CONF_CACHE:-}"
+
+# Credentials get written here. An empty SAVE_DIR would make the cp target "/host2.conf",
+# dropping partner passwords and API keys at the filesystem root.
+_slashes="${SAVE_DIR//[^\/]/}"
+if [[ -z "$SAVE_DIR" || "$SAVE_DIR" != /* || "${#_slashes}" -lt 3 ]]; then
+    error "PERSISTENT_CONF_CACHE is unset or unsafe ('${SAVE_DIR:-unset}') — refusing to save partner confs"
+    notify "conf_cache_save aborted on $(hostname) — PERSISTENT_CONF_CACHE is '${SAVE_DIR:-unset}'" \
+        "Conf Cache Save" "warning"
+    exit 1
+fi
+unset _slashes
 
 [[ "$DRY_RUN" == true ]] && warn "DRY RUN — no files will be written"
 
@@ -69,8 +162,10 @@ for conf in "$RAM_CACHE"/host*.conf; do
         continue
     fi
 
-    mkdir -p "$SAVE_DIR"
-    if cp "$conf" "$SAVE_DIR/$base"; then
+    # Partner confs carry credentials — restrict on write rather than leaving them at the
+    # default umask on a path that survives reboot.
+    mkdir -p "$SAVE_DIR" && chmod 700 "$SAVE_DIR"
+    if cp "$conf" "$SAVE_DIR/$base" && chmod 600 "$SAVE_DIR/$base"; then
         echo "Saved $base → $SAVE_DIR ✅"
         (( saved++ ))
     else