Add full banner headers to all scripts across the codebase

Every script now has the established header format: PURPOSE with ─────── separator, OPERATIONAL MODEL, DESIGN PRINCIPLES, OPERATIONAL SAFEGUARDS, CONFIGURATION, and RUNTIME MODES — structured with full ====== banner sections throughout. Orchestrators converted from compact ── inline format to full banners. Stale emby-fallback and dirty sync references removed from Plugin/user_script_plug-in.sh.
2026-06-26 18:50:05 -04:00
parent 1003bee72a
commit f92ee4064b
51 changed files with 1822 additions and 563 deletions
@@ -2,50 +2,86 @@
 # ==============================================================================================
 # ============================ Watchdog Orchestrator ===========================================
 # ==============================================================================================
-# Runs WATCHDOG_ORCHESTRATOR_SCRIPTS in order each cron cycle.
+#
+# PURPOSE
+# ─────────────────────────────────────────────────────────────────────────────
+# Runs WATCHDOG_ORCHESTRATOR_SCRIPTS in order each cron cycle. Replaces the
+# continuous loops previously embedded in individual watchdog scripts — those
+# are now single-pass; this orchestrator provides the cadence.
 # Schedule: */15 * * * * (every 15 minutes)
 #
-# ── EXECUTION ORDER ───────────────────────────────────────────────────────────────────────────
-#   Driven by WATCHDOG_ORCHESTRATOR_SCRIPTS in master.conf — add, remove, or reorder there.
-#   Default: resource_watchdog → docker_watchdog → system_watchdog → unraid_api_key_renew → stability_watchdog
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
 #
-# ── WHY ORDER MATTERS ─────────────────────────────────────────────────────────────────────────
-#   Resource Watchdog first — frees RAM and CPU before healing attempts container restarts.
-#                            Containers restarted into a resource-pressured system just fail again.
-#   Docker Watchdog second — restarts with pressure already reduced, more likely to stabilise.
-#   System Watchdog third  — system component health after containers are healed.
-#   API key renew fourth   — self-heals unraid-api registry loss; check-first, silent when valid.
-#   Stability Watchdog last — only reboots when all prior layers could not resolve the issue.
+# Order driven by WATCHDOG_ORCHESTRATOR_SCRIPTS in master.conf.
+# Default: resource_watchdog → docker_watchdog → system_watchdog →
+#          unraid_api_key_renew → stability_watchdog
 #
-# ── ARRAY CHECK ───────────────────────────────────────────────────────────────────────────────
-#   Exits immediately if /mnt/user is not mounted as shfs (array not started).
-#   Watchdogs check Docker containers and storage — meaningless without the array.
-#   Prevents false positives and unnecessary reboots when array is stopped or stopping.
+# ARRAY CHECK
+#   Exits immediately if /mnt/user is not mounted as shfs. Watchdogs check
+#   Docker containers and storage — meaningless without the array. Prevents
+#   false positives and unnecessary reboots when array is stopped or stopping.
 #
-# ── STARTUP GRACE ─────────────────────────────────────────────────────────────────────────────
-#   No action until system uptime >= WATCHDOG_STARTUP_GRACE seconds.
-#   Prevents false positives from containers still starting at array launch.
-#   Each sub-script enforces this independently — orchestrator exits early to avoid log noise.
+# STARTUP GRACE
+#   No action until system uptime >= WATCHDOG_STARTUP_GRACE seconds. Prevents
+#   false positives from containers still starting at array launch. Each
+#   sub-script enforces this independently — orchestrator exits early to avoid
+#   log noise.
 #
-# ── OVERLAP PROTECTION ────────────────────────────────────────────────────────────────────────
-#   acquire_lock() — exits immediately if a prior cycle is still in progress.
-#   Prevents pile-up when a cycle runs long (daemon restart attempt = 30s, etc.).
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
 #
-# ── REPLACES ──────────────────────────────────────────────────────────────────────────────────
-#   Continuous loops previously in system_watchdog.sh and docker_watchdog.sh.
-#   Those scripts are now single-pass — this orchestrator provides the cadence.
+# Pressure Before Healing
+#   Resource Watchdog runs first — it frees RAM and CPU before any container
+#   restart is attempted. Containers restarted into a resource-pressured system
+#   just fail again. Docker Watchdog restarts with pressure already reduced.
+#   System Watchdog checks component health after containers are healed.
+#   Stability Watchdog reboots only when all prior layers could not resolve the
+#   issue. API key renew is check-first and silent when valid.
+#
+# Never Queue
+#   acquire_lock exits immediately if a prior cycle is still running. Prevents
+#   pile-up when a cycle runs long (daemon restart attempt = 30s, etc.).
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+#   Root check       — watchdog operations require root
+#   acquire_lock     — strict; no pile-up if prior cycle still active
+#   detect_hosts()   — MY_ID in logs and notifications
+#   Array check      — exits early if /mnt/user is not shfs-mounted
+#   Startup grace    — WATCHDOG_STARTUP_GRACE respected before any checks
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# master.conf
 #
-# ── CONFIGURATION (master.conf) ───────────────────────────────────────────────────────────────
 #   WATCHDOG_ORCHESTRATOR_SCRIPTS         — watchdogs to run, in order
 #   WATCHDOG_STARTUP_GRACE                — seconds after boot before checks activate
 #   WATCHDOG_ORCHESTRATOR_HEARTBEAT       — periodic heartbeat log toggle
 #   WATCHDOG_ORCHESTRATOR_HEARTBEAT_HOURS — heartbeat interval in hours
 #
-# ── USAGE ─────────────────────────────────────────────────────────────────────────────────────
-#   watchdog_orchestrator.sh           — normal run (called by cron every 15 minutes)
-#   watchdog_orchestrator.sh --dry-run — pass --dry-run to all sub-scripts
-#   watchdog_orchestrator.sh --status  — show script paths and current grace state
-#   watchdog_orchestrator.sh --log     — verbose output from all sub-scripts
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# watchdog_orchestrator.sh
+#     Normal run (called by cron every 15 minutes).
+#
+# watchdog_orchestrator.sh --dry-run
+#     Pass --dry-run to all sub-scripts.
+#
+# watchdog_orchestrator.sh --status
+#     Show script paths and current grace state.
+#
+# watchdog_orchestrator.sh --log
+#     Verbose output from all sub-scripts.
+#
 # ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"