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.

Transcodes/transcode_cleanup.sh

@@ -15,9 +15,41 @@
 #   2. Not currently open by any process (checked via lsof pre-built map)
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# Two locations cleaned in sequence, each through the same routine:
+#
+#   Ramdisk       — only if mountpoint -q confirms it is actually mounted. An unmounted
+#                   ramdisk means the underlying directory is the real filesystem, and
+#                   cleaning it would delete from disk rather than from tmpfs.
+#   SSD fallback  — only if the directory exists.
+#
+# Per location:
+#   1. Path sanity check — refuse anything shallower than two components
+#   2. Count total and age-eligible files (-mmin +TRANSCODE_MAX_AGE)
+#   3. One lsof +D call → in-memory open-file map for the whole location
+#   4. Per eligible file: open → skip and count as active; otherwise rm -f
+#   5. Remove empty directories older than TRANSCODE_ORPHAN_AGE, never transcoding-temp
+#
+# Afterwards, if the ramdisk recovered enough headroom, the symlink is flipped back to
+# it so new sessions return to RAM.
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
+# Two Independent Conditions, Both Required
+#   Age and open-file state are checked separately and a file must pass both. Age alone
+#   would delete a long-running session's segments; lsof alone cannot see HLS segments,
+#   which are written and closed atomically. Neither signal is sufficient on its own,
+#   which is exactly why both are applied rather than picking the better one.
+#
+# Mounted-Only Ramdisk Cleaning
+#   The ramdisk is only cleaned when it is genuinely mounted. If the tmpfs failed to
+#   mount, that same path is an ordinary directory on the array — cleaning it then would
+#   delete real files from disk while believing it was clearing RAM.
+#
 # lsof Called Once, Not Per File
 #   On a busy Live TV system the ramdisk contains thousands of HLS segment files.
 #   Calling lsof once per file creates thousands of subprocess calls every 7 minutes.
@@ -55,6 +87,13 @@
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
+# Location Path Guard
+#   cleanup_location() refuses any path that is not absolute with at least two
+#   components. Neither caller's own check catches a collapsed value — mountpoint -q
+#   returns true for /, and -d is true for both / and /mnt — so the guard lives inside
+#   the function that does the deleting, covering both call sites.
+#
+#
 # Wait Lock
 #   acquire_lock "wait" — waits if a previous cleanup run is still active rather
 #   than exiting. The caller's 7-minute interval can overlap on a slow system.
@@ -188,6 +227,19 @@ cleanup_location() {
         return
     fi
 
+    # This function deletes every file under $location past the age gate. Neither caller's
+    # own check catches a collapsed path: mountpoint -q returns true for /, and -d is true
+    # for / and /mnt alike. Require at least two path components so a blank or truncated
+    # RAMDISK_PATH / TRANSCODE_SSD can never point this at a system directory.
+    local _loc_slashes="${location//[^\/]/}"
+    if [[ "$location" != /* || "${#_loc_slashes}" -lt 2 ]]; then
+        error "Refusing to clean unsafe location: '$location' ($label)"
+        notify "Transcode cleanup refused unsafe path on $(hostname): '$location'" \
+            "Transcode Cleanup" "warning"
+        LOCATION_REMOVED=0 LOCATION_FREED="0B" LOCATION_SKIPPED=0 LOCATION_ACTIVE=0 LOCATION_STREAMING=0 LOCATION_TOO_YOUNG=0 LOCATION_FAILED=0
+        return
+    fi
+
     local file_count eligible_count
     file_count=$(find "$location" -type f 2>/dev/null | wc -l)
     eligible_count=$(find "$location" -type f -mmin +"$max_age" 2>/dev/null | wc -l)