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.

Orchestrators/transcode_management.sh

@@ -50,12 +50,37 @@
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
-#   Root check      — mount and docker operations require root
-#   acquire_lock    — prevents concurrent 7-minute cycles overlapping
-#   detect_hosts()  — aliases RAMDISK_PATH, TRANSCODE_SSD, RAMDISK_WARN_GB per host
-#   --dry-run       — passed through to every script in TRANSCODE_MANAGEMENT_SCRIPTS
-#   Exit code       — worst exit code across all scripts returned to cron
-#   notify()        — pushed on failure, skipped in --dry-run
+# Root Enforcement
+#   Mount and docker operations require root.
+#
+# Lock Acquisition
+#   acquire_lock prevents concurrent 7-minute cycles overlapping. Cleanup and the manager
+#   both touch the same ramdisk, and two cycles at once could have one deleting files
+#   while the other is measuring usage to decide whether to flip.
+#
+# Host Detection
+#   detect_hosts() aliases RAMDISK_PATH, TRANSCODE_SSD and RAMDISK_WARN_GB per host.
+#
+# Empty Job List Guard
+#   Exits with an error and a notification if TRANSCODE_MANAGEMENT_SCRIPTS is empty —
+#   without it the ramdisk would silently stop being cleaned or flipped, and the first
+#   symptom would be a full ramdisk stalling playback.
+#
+# Ordering Is Load-Bearing
+#   Cleanup runs before the manager so the manager measures real active-session usage
+#   rather than usage inflated by stale files. Reversing them would trigger flips that
+#   a cleanup two seconds later would have made unnecessary.
+#
+# Dry Run Propagation
+#   --dry-run is passed through to every script in TRANSCODE_MANAGEMENT_SCRIPTS.
+#
+# Any-Failure Exit Code
+#   Exits 1 if any child failed, 0 otherwise — the individual exit codes are not
+#   propagated, only whether anything failed. A failure in an early child is therefore
+#   never masked by a later success.
+#
+# Notification Contract
+#   notify() fires on failure and is skipped in --dry-run.
 #
 # ==============================================================================================
 # CONFIGURATION
@@ -112,6 +137,16 @@ fi
 # detect_hosts() sets MY_ID and aliases all HOST*_TRANSCODE_* vars
 detect_hosts
 
+# An unconfigured job list would run nothing and still report "0/0 passed" — indistinguishable
+# from a healthy run. Fail loudly instead of silently doing no work.
+if [[ ${#TRANSCODE_MANAGEMENT_SCRIPTS[@]} -eq 0 ]]; then
+    error "TRANSCODE_MANAGEMENT_SCRIPTS is empty — no transcode management scripts will run"
+    error "Check TRANSCODE_MANAGEMENT_SCRIPTS in master.conf"
+    notify "transcode management scripts skipped on $(hostname) ($MY_ID) — TRANSCODE_MANAGEMENT_SCRIPTS is empty" \
+        "$(basename "$0" .sh)" "warning"
+    exit 1
+fi
+
 [[ "$DRY_RUN" == true ]] && warn "DRY RUN — passing through to child scripts"
 
 # ==============================================================================================