@matt82198/aesop 0.1.0-beta.5 → 0.1.0-rc.1

package/daemons/backup-fleet.sh

@@ -74,6 +74,69 @@ get_untracked_files() {
   ) | sort -u
 }
 
+scan_unpushed_commits() {
+  local repo="$1"
+  local unpushed_files
+  local range_expr
+
+  # Detect if upstream exists (no-upstream or detached HEAD scenario)
+  local upstream
+  upstream=$(cd "$repo" 2>/dev/null && git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "")
+
+  if [ -z "$upstream" ] || [ "$upstream" = "@{u}" ]; then
+    # No upstream or detached HEAD: fallback to scanning recent commits (last 20)
+    # Use git rev-list to get the base commit 20 commits back, then use git diff
+    log "WARN: Repository has no upstream or detached HEAD; falling back to bounded commit range scan for $repo"
+    local base
+    base=$(cd "$repo" && git rev-list --max-count=20 HEAD 2>/dev/null | tail -1)
+    if [ -n "$base" ] && [ "$base" != "$(cd "$repo" && git rev-parse HEAD 2>/dev/null)" ]; then
+      # Multiple commits exist: scan from base to HEAD
+      range_expr="$base..HEAD"
+      unpushed_files=$(cd "$repo" && git diff --name-only "$range_expr" 2>/dev/null | sort -u)
+    elif [ -n "$base" ]; then
+      # Single commit (or base == HEAD): diff against the empty tree so the
+      # range form below (empty_tree..HEAD) still works for a root commit
+      # that has no parent to diff against.
+      local empty_tree
+      empty_tree=$(cd "$repo" && git hash-object -t tree /dev/null 2>/dev/null || echo "4b825dc642cb6eb9a060e54bf8d69288fbee4904")
+      range_expr="$empty_tree..HEAD"
+      unpushed_files=$(cd "$repo" && git diff --name-only "$range_expr" 2>/dev/null | sort -u)
+    else
+      unpushed_files=""
+    fi
+  else
+    # Normal case: scan commits not yet pushed to upstream
+    range_expr="@{u}..HEAD"
+    unpushed_files=$(cd "$repo" && git diff --name-only @{u}..HEAD 2>/dev/null | sort -u)
+  fi
+
+  if [ -z "$unpushed_files" ]; then
+    return 0
+  fi
+
+  # P2 wave-25 fix: scan the COMMITTED BLOB content of the unpushed range
+  # (via secret_scan.py --range, which reads each changed path's git object
+  # at the range's tip commit), NOT the current working-tree copy of these
+  # files. A secret committed and then cleaned up in a LATER commit -- but
+  # still present in the unpushed range being force-pushed to the backup
+  # ref -- was previously invisible here, because the old code read
+  # "$repo/$file" straight off disk (which no longer had the secret) instead
+  # of the actual blob(s) the backup push carries. --range is also robust to
+  # deleted files (git diff --diff-filter=d inside secret_scan.py already
+  # excludes them from the file list it scans).
+  if [ -f "$AESOP_ROOT/tools/secret_scan.py" ]; then
+    if command -v python3 >/dev/null 2>&1; then
+      python3 "$AESOP_ROOT/tools/secret_scan.py" --range "$range_expr" --repo "$repo" >/dev/null 2>&1
+      return $?
+    elif command -v python >/dev/null 2>&1; then
+      python "$AESOP_ROOT/tools/secret_scan.py" --range "$range_expr" --repo "$repo" >/dev/null 2>&1
+      return $?
+    fi
+  fi
+
+  return 0
+}
+
 scan_tracked_files() {
   local repo="$1"
   local tracked_files
@@ -81,8 +144,8 @@ scan_tracked_files() {
   local -a file_paths=()
   local repo_win
 
-  # Convert repo path to Windows format for Python compatibility (Git Bash on Windows)
-  repo_win=$(cd "$repo" 2>/dev/null && pwd -W 2>/dev/null || echo "$repo")
+  # Portable path derivation (not Git-Bash pwd -W only)
+  repo_win=$(cd "$repo" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null || echo "$repo")
 
   tracked_files=$(get_tracked_modifications "$repo")
   untracked_files=$(get_untracked_files "$repo")
@@ -115,8 +178,14 @@ EOF
 
   if [ -f "$AESOP_ROOT/tools/secret_scan.py" ]; then
     # ITEM 2 fix: use "${file_paths[@]}" to properly quote array elements
-    python "$AESOP_ROOT/tools/secret_scan.py" "${file_paths[@]}" >/dev/null 2>&1
-    return $?
+    # Defect (a) fix: use python3||python probe instead of bare python (portable to python3-only systems)
+    if command -v python3 >/dev/null 2>&1; then
+      python3 "$AESOP_ROOT/tools/secret_scan.py" "${file_paths[@]}" >/dev/null 2>&1
+      return $?
+    elif command -v python >/dev/null 2>&1; then
+      python "$AESOP_ROOT/tools/secret_scan.py" "${file_paths[@]}" >/dev/null 2>&1
+      return $?
+    fi
   fi
 
   return 0
@@ -160,14 +229,27 @@ process_repo() {
       fi
     fi
 
-    local unpushed=$(git log @{u}.. --oneline 2>/dev/null | wc -l | tr -d ' ')
+    # Detect if upstream exists before trying to count unpushed commits
+    local upstream
+    upstream=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "")
+
+    local unpushed
+    if [ -z "$upstream" ] || [ "$upstream" = "@{u}" ]; then
+      # No upstream or detached HEAD: count recent commits instead (last 20)
+      log "WARN: Repository has no upstream or detached HEAD; falling back to recent commits count for $name"
+      unpushed=$(git log --oneline -20 2>/dev/null | wc -l | tr -d ' ')
+    else
+      # Normal case: count commits not yet pushed to upstream
+      unpushed=$(git log @{u}.. --oneline 2>/dev/null | wc -l | tr -d ' ')
+    fi
+
     if [ "$unpushed" -gt 0 ]; then
       local branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
       [ "$branch" = "HEAD" ] && branch="$default"
 
       if [ "$branch" = "$default" ]; then
         WIPREF="backup/master-wip-$(date +%Y%m%d)"
-        if scan_tracked_files "$repo"; then
+        if scan_unpushed_commits "$repo"; then
           if git push -qf origin "HEAD:refs/heads/$WIPREF" 2>/dev/null; then
             printf 'SNAPSHOTTED\0%s\n' "$name"
             exit 0
@@ -177,7 +259,7 @@ process_repo() {
           exit 0
         fi
       else
-        if scan_tracked_files "$repo"; then
+        if scan_unpushed_commits "$repo"; then
           if git push -q origin "$branch" 2>/dev/null; then
             printf 'PUSHED\0%s\n' "$name"
             exit 0
@@ -193,52 +275,128 @@ process_repo() {
   )
 }
 
-log "=== cycle start ==="
-temp_json=$(mktemp)
-echo "[" > "$temp_json"
-first=1
-processed_paths=""
-
-# Discover all git repos: scan home dot-directories, root directories, dev/ subdirectory
-# This pattern includes ~/.* (dot-dirs like .claude), ~/* (home root), ~/dev/* (dev subtree)
-for dir in ~/.* ~/* ~/dev/*; do
-  base=$(basename "$dir")
-  [ "$base" = "." ] || [ "$base" = ".." ] && continue
-  [ ! -d "$dir/.git" ] && continue
-
-  # Normalize path to detect duplicates (e.g., .claude vs .claude/)
-  real_dir=$(cd "$dir" && pwd 2>/dev/null)
-  if [ -z "$real_dir" ]; then continue; fi
-  if echo "$processed_paths" | grep -Fq "$real_dir"; then
-    continue
+main() {
+  log "=== cycle start ==="
+  temp_json=$(mktemp)
+  echo "[" > "$temp_json"
+  first=1
+  processed_paths=""
+
+  # AUDIT FIX 1: Check if aesop.config.json exists and has repos array
+  repos_to_scan=""
+  config_file="$AESOP_ROOT/aesop.config.json"
+  if [ -f "$config_file" ]; then
+    # Find Python interpreter (portable: prefer python3, fallback to python)
+    python_exe=""
+    if command -v python3 >/dev/null 2>&1; then
+      python_exe="python3"
+    elif command -v python >/dev/null 2>&1; then
+      python_exe="python"
+    fi
+
+    if [ -n "$python_exe" ]; then
+      # Parse repos array from config using Python (not grep)
+      # Note: Strip trailing \r (CRLF compatibility) and empty lines
+      repos_to_scan=$($python_exe -c "
+import json, sys
+try:
+  with open(sys.argv[1], 'r') as f:
+    config = json.load(f)
+    repos = config.get('repos', [])
+    if isinstance(repos, list) and len(repos) > 0:
+      for repo in repos:
+        if isinstance(repo, dict) and 'path' in repo:
+          print(repo['path'])
+except Exception as e:
+  pass
+" "$config_file" 2>/dev/null | tr -d '\r')
+    fi
   fi
-  processed_paths="$processed_paths
+
+  if [ -n "$repos_to_scan" ]; then
+    # AUDIT FIX 1: Use explicit repos from config
+    log "Loading repos from config file"
+    while IFS= read -r dir; do
+      [ -z "$dir" ] && continue
+      # Validate repo path exists
+      if [ ! -d "$dir/.git" ]; then
+        log "WARN: configured repo not found or not a git repo (skipping): $dir"
+        continue
+      fi
+      # Normalize path to detect duplicates
+      real_dir=$(cd "$dir" && pwd 2>/dev/null)
+      if [ -z "$real_dir" ]; then continue; fi
+      if echo "$processed_paths" | grep -Fxq "$real_dir"; then
+        continue
+      fi
+      processed_paths="$processed_paths
 $real_dir"
 
-  if is_touched "$dir"; then
-    # P0 FIX: Eliminate $() command substitution to preserve NUL bytes in protocol
-    # Direct redirect maintains NUL delimiters (process_repo emits STATE\0name format)
-    temp_result=$(mktemp)
-    process_repo "$dir" > "$temp_result"
-    # Read first field (state) and second field (name) using NUL delimiter
-    # Portable solution: use awk with RS="\0" instead of GNU sed \x0 (BSD/macOS compatible)
-    state=$(awk 'BEGIN{RS="\0"} NR==1 {print}' "$temp_result")
-    name=$(awk 'BEGIN{RS="\0"} NR==2 {print}' "$temp_result" | tr -d '\n')
-    rm -f "$temp_result"
-    [ -z "$state" ] && continue
-    if [ "$first" = 1 ]; then
-      first=0
-    else
-      echo "," >> "$temp_json"
-    fi
-    # P2 FIX: JSON-escape all interpolated values before emitting
-    # P2 FIX: Portable date format (not GNU-only date -Iseconds)
-    printf '{"repo":"%s","state":"%s","age":"%s"}' "$(json_escape "$name")" "$(json_escape "$state")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$temp_json"
-    log "$state: $name"
+      if is_touched "$dir"; then
+        temp_result=$(mktemp)
+        process_repo "$dir" > "$temp_result"
+        state=$(awk 'BEGIN{RS="\0"} NR==1 {print}' "$temp_result")
+        name=$(awk 'BEGIN{RS="\0"} NR==2 {print}' "$temp_result" | tr -d '\n')
+        rm -f "$temp_result"
+        [ -z "$state" ] && continue
+        if [ "$first" = 1 ]; then
+          first=0
+        else
+          echo "," >> "$temp_json"
+        fi
+        printf '{"repo":"%s","state":"%s","age":"%s"}' "$(json_escape "$name")" "$(json_escape "$state")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$temp_json"
+        log "$state: $name"
+      fi
+    done <<< "$repos_to_scan"
+  else
+    # AUDIT FIX 1: Fall back to autodiscovery only when no repos configured
+    log "No repos configured, using autodiscovery"
+    # Discover all git repos: scan home dot-directories, root directories, dev/ subdirectory
+    # This pattern includes ~/.* (dot-dirs like .claude), ~/* (home root), ~/dev/* (dev subtree)
+    for dir in ~/.* ~/* ~/dev/*; do
+      base=$(basename "$dir")
+      [ "$base" = "." ] || [ "$base" = ".." ] && continue
+      [ ! -d "$dir/.git" ] && continue
+
+      # Normalize path to detect duplicates (e.g., .claude vs .claude/)
+      real_dir=$(cd "$dir" && pwd 2>/dev/null)
+      if [ -z "$real_dir" ]; then continue; fi
+      if echo "$processed_paths" | grep -Fxq "$real_dir"; then
+        continue
+      fi
+      processed_paths="$processed_paths
+$real_dir"
+
+      if is_touched "$dir"; then
+        # P0 FIX: Eliminate $() command substitution to preserve NUL bytes in protocol
+        # Direct redirect maintains NUL delimiters (process_repo emits STATE\0name format)
+        temp_result=$(mktemp)
+        process_repo "$dir" > "$temp_result"
+        # Read first field (state) and second field (name) using NUL delimiter
+        # Portable solution: use awk with RS="\0" instead of GNU sed \x0 (BSD/macOS compatible)
+        state=$(awk 'BEGIN{RS="\0"} NR==1 {print}' "$temp_result")
+        name=$(awk 'BEGIN{RS="\0"} NR==2 {print}' "$temp_result" | tr -d '\n')
+        rm -f "$temp_result"
+        [ -z "$state" ] && continue
+        if [ "$first" = 1 ]; then
+          first=0
+        else
+          echo "," >> "$temp_json"
+        fi
+        # P2 FIX: JSON-escape all interpolated values before emitting
+        # P2 FIX: Portable date format (not GNU-only date -Iseconds)
+        printf '{"repo":"%s","state":"%s","age":"%s"}' "$(json_escape "$name")" "$(json_escape "$state")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$temp_json"
+        log "$state: $name"
+      fi
+    done
   fi
-done
 
-echo "" >> "$temp_json"
-echo "]" >> "$temp_json"
-mv "$temp_json" "$REPOS_STATUS"
-log "=== cycle end ==="
+  echo "" >> "$temp_json"
+  echo "]" >> "$temp_json"
+  mv "$temp_json" "$REPOS_STATUS"
+  log "=== cycle end ==="
+}
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  main "$@"
+fi

package/daemons/run-watchdog.sh

@@ -5,12 +5,30 @@
 #
 # Configuration: export AESOP_ROOT=/path/to/aesop before running (defaults to script directory's parent).
 # Testing: export AESOP_WATCHDOG_CYCLE_CMD to override backup-fleet.sh invocation
+#
+# Kill switch (wave-26 safety brake): if AESOP_ROOT/state/.HALT exists (see
+# tools/halt.py), every cycle logs "HALTED: <reason>" and skips all work — no
+# backup, no push, no scan — until cleared via `python tools/halt.py --clear`.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 AESOP_ROOT="${AESOP_ROOT:-$(dirname "$SCRIPT_DIR")}"
 MODE="${1:-daemon}"
 LOCK_DIR="$AESOP_ROOT/state/.watchdog-lock"
 LOCK_STALE_THRESHOLD=300
+HALT_SENTINEL="$AESOP_ROOT/state/.HALT"
+
+# Resolve Python interpreter (portable: prefer python3, fallback to python)
+PYTHON_EXE=""
+if command -v python3 >/dev/null 2>&1; then
+  PYTHON_EXE="python3"
+elif command -v python >/dev/null 2>&1; then
+  PYTHON_EXE="python"
+fi
+
+# Resolve conductor3 directory (sibling of AESOP_ROOT)
+CONDUCTOR_ROOT="$(dirname "$AESOP_ROOT")/conductor3"
+MONITOR_HB_FILE="$CONDUCTOR_ROOT/monitor/.monitor-heartbeat"
+MONITOR_HB_STALE_THRESHOLD=600
 
 # Atomic lock acquire: mkdir is atomic (POSIX guarantees)
 # Returns 0 if lock acquired, 1 if held by another process, 2 if stale lock reclaimed
@@ -30,20 +48,64 @@ acquire_lock() {
   fi
 
   # Lock directory already exists; check if it's stale
-  if [ -d "$lock_dir" ] && [ -f "$lock_dir/timestamp" ]; then
-    local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
-    local now=$(date +%s)
-    local lock_age=$((now - lock_mtime))
-
-    if [ "$lock_age" -gt "$stale_threshold" ]; then
-      # Lock is stale; try to reclaim it
-      rm -rf "$lock_dir" 2>/dev/null || true
-      if mkdir "$lock_dir" 2>/dev/null; then
-        date +%s > "$lock_dir/timestamp" 2>/dev/null
-        echo $$ > "$lock_dir/pid" 2>/dev/null
-        echo "watchdog lock was stale (${lock_age}s) — reclaimed." >&2
-        return 2
+  # AUDIT FIX 2: Verify both timestamp AND pid files exist before the stale comparison
+  if [ -d "$lock_dir" ]; then
+    # Try to read pid file to check if process is still running
+    local lock_pid=""
+    if [ -f "$lock_dir/pid" ]; then
+      lock_pid=$(cat "$lock_dir/pid" 2>/dev/null)
+    fi
+
+    # Check if both required files exist
+    if [ -f "$lock_dir/timestamp" ] && [ -f "$lock_dir/pid" ] && [ -n "$lock_pid" ]; then
+      # Both files present and pid is readable - use timestamp for stale check
+      local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
+      local now=$(date +%s)
+      local lock_age=$((now - lock_mtime))
+
+      if [ "$lock_age" -gt "$stale_threshold" ]; then
+        # Lock is stale; try to reclaim it
+        rm -rf "$lock_dir" 2>/dev/null || true
+        if mkdir "$lock_dir" 2>/dev/null; then
+          date +%s > "$lock_dir/timestamp" 2>/dev/null
+          echo $$ > "$lock_dir/pid" 2>/dev/null
+          echo "watchdog lock was stale (${lock_age}s) — reclaimed." >&2
+          return 2
+        fi
+      fi
+    else
+      # AUDIT FIX 2: Timestamp or pid file missing, or pid is empty - lock is incomplete
+      # Reclaim only if we can verify it's abandoned: dead pid OR stale timestamp
+      local should_reclaim=0
+
+      # Case 1: pid file exists and is readable - check if process is running
+      if [ -f "$lock_dir/pid" ] && [ -n "$lock_pid" ]; then
+        if ! kill -0 "$lock_pid" 2>/dev/null; then
+          should_reclaim=1
+        fi
+      fi
+
+      # Case 2: no pid file, but timestamp exists and is old (definitely abandoned)
+      if [ $should_reclaim -eq 0 ] && [ -f "$lock_dir/timestamp" ]; then
+        local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
+        local now=$(date +%s)
+        local lock_age=$((now - lock_mtime))
+        if [ "$lock_age" -gt "$stale_threshold" ]; then
+          should_reclaim=1
+        fi
       fi
+
+      if [ $should_reclaim -eq 1 ]; then
+        # Lock is abandoned - reclaim it
+        rm -rf "$lock_dir" 2>/dev/null || true
+        if mkdir "$lock_dir" 2>/dev/null; then
+          date +%s > "$lock_dir/timestamp" 2>/dev/null
+          echo $$ > "$lock_dir/pid" 2>/dev/null
+          echo "watchdog lock was stale (incomplete) — reclaimed." >&2
+          return 2
+        fi
+      fi
+      # If lock is incomplete but fresh, hold it (process might be in progress)
     fi
   fi
 
@@ -62,59 +124,143 @@ release_lock() {
   fi
 }
 
-# Try to acquire lock (applies to both --once and daemon modes)
-acquire_lock "$LOCK_DIR" "$LOCK_STALE_THRESHOLD"
-lock_result=$?
+# Check monitor heartbeat staleness; log to fleet-backup.log if missing or >600s old
+check_monitor_staleness() {
+  local hb_file="$1"
+  local stale_threshold="$2"
+  local log_file="$3"
+  if [ -z "$hb_file" ] || [ -z "$log_file" ]; then
+    return
+  fi
+  if [ ! -f "$hb_file" ]; then
+    echo "[$(date '+%F %T')] SIGNAL: monitor heartbeat missing ($hb_file)" >> "$log_file"
+    return
+  fi
+  local hb_epoch=$(cat "$hb_file" 2>/dev/null || echo 0)
+  if [ -z "$hb_epoch" ] || [ "$hb_epoch" = "0" ]; then
+    echo "[$(date '+%F %T')] SIGNAL: monitor heartbeat empty/unreadable" >> "$log_file"
+    return
+  fi
+  local now=$(date +%s)
+  local hb_age=$((now - hb_epoch))
+  if [ "$hb_age" -gt "$stale_threshold" ]; then
+    echo "[$(date '+%F %T')] SIGNAL: monitor heartbeat stale (${hb_age}s > ${stale_threshold}s threshold)" >> "$log_file"
+  fi
+}
 
-if [ $lock_result -eq 1 ]; then
-  echo "watchdog already running — not starting a duplicate."
-  exit 0
-fi
+# Kill switch check (wave-26 safety brake). Returns 0 (bash true) and logs
+# "HALTED: <reason>" if $AESOP_ROOT/state/.HALT exists; returns 1 otherwise.
+# Never runs backup/push/scan work when halted — caller must skip the cycle.
+check_halt() {
+  local log_file="$1"
+  if [ ! -f "$HALT_SENTINEL" ]; then
+    return 1
+  fi
 
-echo "==================================================================="
-echo "  FLEET WATCHDOG DAEMON  ·  backup + ensure-push + scan / 150s"
-echo "  logs: $AESOP_ROOT/state/FLEET-BACKUP.log   ·   Ctrl-C to stop"
-echo "==================================================================="
-echo "[$(date '+%F %T')] === watchdog daemon (shell) STARTED ===" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
-trap "release_lock \"$LOCK_DIR\"; echo \"[$(date '+%F %T')] === watchdog daemon (shell) STOPPED ===\" >> \"$AESOP_ROOT/state/FLEET-BACKUP.log\"; echo \"stopped.\"; exit 0" INT TERM
-
-# Allow override of backup cycle command (for testing)
-# Use array to safely handle paths with spaces (P1 fix)
-if [ -n "$AESOP_WATCHDOG_CYCLE_CMD" ]; then
-  # Override: run as-is through bash -c
-  CYCLE_CMD_ARRAY=("bash" "-c" "$AESOP_WATCHDOG_CYCLE_CMD")
-else
-  # Default: array form for proper quoting
-  CYCLE_CMD_ARRAY=("bash" "$AESOP_ROOT/daemons/backup-fleet.sh")
-fi
+  local reason="halted (reason unavailable)"
+  if [ -n "$PYTHON_EXE" ]; then
+    local parsed
+    parsed=$("$PYTHON_EXE" -c '
+import json, sys
+try:
+    with open(sys.argv[1], encoding="utf-8") as f:
+        data = json.load(f)
+    r = data.get("reason")
+    if r:
+        print(r)
+except Exception:
+    pass
+' "$HALT_SENTINEL" 2>/dev/null)
+    if [ -n "$parsed" ]; then
+      reason="$parsed"
+    fi
+  fi
 
-if [ "$MODE" = "--once" ]; then
-  full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
-  cmd_exit=$?
-  echo "$full_out"
-  if [ $cmd_exit -ne 0 ]; then
-    err_msg="[$(date '+%F %T')] ERROR: cycle #1 failed with exit code $cmd_exit"
-    echo "$err_msg" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
-    echo "[ERROR: exit $cmd_exit]" >&2
+  echo "HALTED: $reason"
+  if [ -n "$log_file" ]; then
+    echo "[$(date '+%F %T')] HALTED: $reason" >> "$log_file"
   fi
-  python "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
-  release_lock "$LOCK_DIR"
-  exit $cmd_exit
-fi
+  return 0
+}
+
+# Main execution — guarded below so sourcing this file (e.g. from tests, to
+# reuse acquire_lock/release_lock/check_halt) never runs a cycle as a
+# side effect of the source itself.
+main() {
+  # Try to acquire lock (applies to both --once and daemon modes)
+  acquire_lock "$LOCK_DIR" "$LOCK_STALE_THRESHOLD"
+  lock_result=$?
 
-n=0
-while true; do
-  n=$((n+1))
-  full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
-  cmd_exit=$?
-  if [ $cmd_exit -eq 0 ]; then
-    out=$(echo "$full_out" | tail -2)
-    printf '%s  cycle #%d\n%s\n' "$(date '+%H:%M:%S')" "$n" "$out"
+  if [ $lock_result -eq 1 ]; then
+    echo "watchdog already running — not starting a duplicate."
+    exit 0
+  fi
+
+  echo "==================================================================="
+  echo "  FLEET WATCHDOG DAEMON  ·  backup + ensure-push + scan / 150s"
+  echo "  logs: $AESOP_ROOT/state/FLEET-BACKUP.log   ·   Ctrl-C to stop"
+  echo "==================================================================="
+  echo "[$(date '+%F %T')] === watchdog daemon (shell) STARTED ===" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
+  trap "release_lock \"$LOCK_DIR\"; echo \"[$(date '+%F %T')] === watchdog daemon (shell) STOPPED ===\" >> \"$AESOP_ROOT/state/FLEET-BACKUP.log\"; echo \"stopped.\"; exit 0" INT TERM
+
+  # Allow override of backup cycle command (for testing)
+  # Use array to safely handle paths with spaces (P1 fix)
+  if [ -n "$AESOP_WATCHDOG_CYCLE_CMD" ]; then
+    # Override: run as-is through bash -c
+    CYCLE_CMD_ARRAY=("bash" "-c" "$AESOP_WATCHDOG_CYCLE_CMD")
   else
-    echo "[$(date '+%F %T')] ERROR: cycle #$n failed with exit code $cmd_exit" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
-    out=$(echo "$full_out" | tail -2)
-    printf '%s  cycle #%d [ERROR: exit %d]\n%s\n' "$(date '+%H:%M:%S')" "$n" "$cmd_exit" "$out"
+    # Default: array form for proper quoting
+    CYCLE_CMD_ARRAY=("bash" "$AESOP_ROOT/daemons/backup-fleet.sh")
   fi
-  python "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
-  sleep 150
-done
+
+  if [ "$MODE" = "--once" ]; then
+    if check_halt "$AESOP_ROOT/state/FLEET-BACKUP.log"; then
+      release_lock "$LOCK_DIR"
+      exit 0
+    fi
+    full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
+    cmd_exit=$?
+    echo "$full_out"
+    if [ $cmd_exit -ne 0 ]; then
+      err_msg="[$(date '+%F %T')] ERROR: cycle #1 failed with exit code $cmd_exit"
+      echo "$err_msg" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
+      echo "[ERROR: exit $cmd_exit]" >&2
+    fi
+    if [ -n "$PYTHON_EXE" ]; then
+      "$PYTHON_EXE" "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
+    fi
+    release_lock "$LOCK_DIR"
+    exit $cmd_exit
+  fi
+
+  n=0
+  while true; do
+    n=$((n+1))
+    if check_halt "$AESOP_ROOT/state/FLEET-BACKUP.log"; then
+      sleep 150
+      continue
+    fi
+    full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
+    cmd_exit=$?
+    if [ $cmd_exit -eq 0 ]; then
+      out=$(echo "$full_out" | tail -2)
+      printf '%s  cycle #%d\n%s\n' "$(date '+%H:%M:%S')" "$n" "$out"
+    else
+      echo "[$(date '+%F %T')] ERROR: cycle #$n failed with exit code $cmd_exit" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
+      out=$(echo "$full_out" | tail -2)
+      printf '%s  cycle #%d [ERROR: exit %d]\n%s\n' "$(date '+%H:%M:%S')" "$n" "$cmd_exit" "$out"
+    fi
+    check_monitor_staleness "$MONITOR_HB_FILE" "$MONITOR_HB_STALE_THRESHOLD" "$AESOP_ROOT/state/FLEET-BACKUP.log"
+    if [ -n "$PYTHON_EXE" ]; then
+      "$PYTHON_EXE" "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
+    fi
+    sleep 150
+  done
+}
+
+# Execution guard: only run a cycle when this script is executed directly,
+# not when it is sourced (e.g. `source run-watchdog.sh` in a test harness to
+# reuse acquire_lock/release_lock/check_halt without triggering a cycle).
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi