fix(scrape): flock on archive_root with lock holder diagnostics

Serialize scrapes across repo checkouts that share the same Documents
archive_root, write lock meta with pid/cmd, and reclaim when the holder
process is dead.

scripts/run-discord-scrape-host.sh

@@ -60,17 +60,98 @@ cleanup_compose_env() {
   fi
 }
 
+resolve_scrape_lock_file() {
+  local config_path=$1
+
+  if [[ -n "${DCE_SCRAPE_LOCK_FILE:-}" ]]; then
+    printf '%s\n' "$DCE_SCRAPE_LOCK_FILE"
+    return 0
+  fi
+
+  local archive_root=""
+  if [[ -f "$config_path" ]]; then
+    archive_root=$(jq -r '.archive_root // empty' "$config_path" 2>/dev/null) || true
+  fi
+  if [[ -n "$archive_root" && "$archive_root" != null ]]; then
+    printf '%s/.dce-scrape.lock\n' "$archive_root"
+  else
+    printf '%s/.dce-scrape.lock\n' "$REPO_ROOT"
+  fi
+}
+
+scrape_lock_meta_path() {
+  printf '%s.meta\n' "$SCRAPE_LOCK_FILE"
+}
+
+write_scrape_lock_meta() {
+  local meta_file
+  meta_file=$(scrape_lock_meta_path)
+  printf 'pid=%s\nstarted=%s\ncmd=%s\n' \
+    "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(ps -o args= -p $$ 2>/dev/null | head -c 500 || echo unknown)" >"$meta_file"
+}
+
+remove_scrape_lock_meta() {
+  rm -f "$(scrape_lock_meta_path)"
+}
+
+format_scrape_lock_holder() {
+  local meta_file=$1
+  local pid="" started="" cmd="" holder_state=""
+
+  [[ -f "$meta_file" ]] || return 0
+  pid=$(grep -E '^pid=' "$meta_file" | head -1 | cut -d= -f2- || true)
+  started=$(grep -E '^started=' "$meta_file" | head -1 | cut -d= -f2- || true)
+  cmd=$(grep -E '^cmd=' "$meta_file" | head -1 | cut -d= -f2- || true)
+  [[ -n "$pid" ]] || return 0
+
+  if kill -0 "$pid" 2>/dev/null; then
+    holder_state="running"
+  else
+    holder_state="not running"
+  fi
+  printf 'Holder pid %s (%s, started %s): %s' "$pid" "$holder_state" "${started:-unknown}" "${cmd:-unknown}"
+}
+
+try_reclaim_stale_scrape_lock() {
+  local meta_file pid
+  meta_file=$(scrape_lock_meta_path)
+  [[ -f "$meta_file" ]] || return 1
+  pid=$(grep -E '^pid=' "$meta_file" | head -1 | cut -d= -f2- || true)
+  [[ -n "$pid" ]] || return 1
+  if kill -0 "$pid" 2>/dev/null; then
+    return 1
+  fi
+  printf 'WARN: reclaiming scrape lock; previous holder pid %s is not running.\n' "$pid" >&2
+  remove_scrape_lock_meta
+  return 0
+}
+
 acquire_scrape_lock() {
+  local config_path=${1:-}
+
   if [[ "${DCE_SKIP_SCRAPE_LOCK:-0}" == "1" ]]; then
     return 0
   fi
   command -v flock >/dev/null 2>&1 || return 0
 
-  SCRAPE_LOCK_FILE="${DCE_SCRAPE_LOCK_FILE:-$REPO_ROOT/.dce-scrape.lock}"
+  [[ -n "$config_path" ]] || config_path="$REPO_ROOT/config/scrape-targets.json"
+  SCRAPE_LOCK_FILE=$(resolve_scrape_lock_file "$config_path")
+  mkdir -p "$(dirname "$SCRAPE_LOCK_FILE")"
+
   exec {SCRAPE_LOCK_FD}>>"$SCRAPE_LOCK_FILE"
   if ! flock -n "$SCRAPE_LOCK_FD"; then
+    if try_reclaim_stale_scrape_lock && flock -n "$SCRAPE_LOCK_FD"; then
+      write_scrape_lock_meta
+      return 0
+    fi
+    local holder_msg=""
+    holder_msg=$(format_scrape_lock_holder "$(scrape_lock_meta_path)") || true
+    if [[ -n "$holder_msg" ]]; then
+      die "Another scrape is already running (lock: $SCRAPE_LOCK_FILE). $holder_msg"
+    fi
     die "Another scrape is already running (lock: $SCRAPE_LOCK_FILE). Wait for it to finish or confirm no scrape is active before removing the lock."
   fi
+  write_scrape_lock_meta
 }
 
 release_scrape_lock() {
@@ -80,6 +161,7 @@ release_scrape_lock() {
   flock -u "$SCRAPE_LOCK_FD" 2>/dev/null || true
   exec {SCRAPE_LOCK_FD}>&-
   SCRAPE_LOCK_FD=""
+  remove_scrape_lock_meta
 }
 
 cleanup_on_exit() {
@@ -514,7 +596,7 @@ main() {
       run_subcommand_with_retry "$subcommand" "${passthrough_args[@]}"
       ;;
     scrape)
-      acquire_scrape_lock
+      acquire_scrape_lock "$host_config"
       run_subcommand_with_retry "$subcommand" "${passthrough_args[@]}"
       ;;
   esac

scripts/tests/run-discord-scrape-host-lock-smoke.sh

@@ -43,6 +43,7 @@ EOF
 (
   exec {lock_fd}>>"$LOCK_FILE"
   flock -n "$lock_fd" || exit 1
+  printf 'pid=%s\nstarted=2020-01-01T00:00:00Z\ncmd=mock-lock-holder\n' "$$" >"${LOCK_FILE}.meta"
   sleep 120
 ) &
 HOLDER_PID=$!
@@ -69,6 +70,11 @@ if ! grep -q 'Another scrape is already running' <<<"$output"; then
   printf '%s\n' "$output" >&2
   exit 1
 fi
+if ! grep -q 'Holder pid' <<<"$output"; then
+  echo "expected holder pid details in lock-held error" >&2
+  printf '%s\n' "$output" >&2
+  exit 1
+fi
 
 kill "$HOLDER_PID" 2>/dev/null || true
 wait "$HOLDER_PID" 2>/dev/null || true
@@ -84,4 +90,55 @@ if ! DCE_REPO_ROOT="$REPO_ROOT" \
   exit 1
 fi
 
+ARCHIVE_ROOT="$TMP_DIR/archive_shared"
+mkdir -p "$ARCHIVE_ROOT/demo"
+CONFIG_PATH="$TMP_DIR/archive-config.json"
+ARCHIVE_LOCK="$ARCHIVE_ROOT/.dce-scrape.lock"
+cat >"$CONFIG_PATH" <<JSON
+{
+  "archive_root": "$ARCHIVE_ROOT",
+  "targets": [
+    {
+      "name": "demo",
+      "kind": "guild",
+      "output_dir": "$ARCHIVE_ROOT/demo",
+      "enabled": true
+    }
+  ]
+}
+JSON
+
+(
+  exec {archive_lock_fd}>>"$ARCHIVE_LOCK"
+  flock -n "$archive_lock_fd" || exit 1
+  sleep 120
+) &
+HOLDER_PID=$!
+sleep 0.2
+
+set +e
+archive_output=$(
+  DCE_REPO_ROOT="$REPO_ROOT" \
+  DCE_DOCKER_BIN="$FAKE_DOCKER" \
+  DCE_ENV_FILE="$ENV_FILE" \
+  DCE_COMPOSE_FILE="$COMPOSE_FILE" \
+  "$REPO_ROOT/scripts/run-discord-scrape-host.sh" scrape --config "$CONFIG_PATH" --target demo 2>&1
+)
+archive_status=$?
+set -e
+
+kill "$HOLDER_PID" 2>/dev/null || true
+wait "$HOLDER_PID" 2>/dev/null || true
+HOLDER_PID=""
+
+if [[ "$archive_status" -eq 0 ]]; then
+  echo "expected archive-root lock to block scrape" >&2
+  exit 1
+fi
+if ! grep -Fq "$ARCHIVE_LOCK" <<<"$archive_output"; then
+  echo "expected archive-root lock path in error message" >&2
+  printf '%s\n' "$archive_output" >&2
+  exit 1
+fi
+
 echo "run-discord-scrape-host-lock-smoke: OK"