aether-colony 5.0.0 → 5.2.1

package/.aether/utils/file-lock.sh

@@ -8,17 +8,20 @@
 #   # ... critical section ...
 #   release_lock
 
-# Aether root detection - use git root if available, otherwise use current directory
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    AETHER_ROOT="$(git rev-parse --show-toplevel)"
-else
-    AETHER_ROOT="$(pwd)"
+# Aether root detection - respect existing AETHER_ROOT, or use git root, or use current directory
+if [[ -z "${AETHER_ROOT:-}" ]]; then
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        AETHER_ROOT="$(git rev-parse --show-toplevel)"
+    else
+        AETHER_ROOT="$(pwd)"
+    fi
 fi
 
 LOCK_DIR="$AETHER_ROOT/.aether/locks"
 LOCK_TIMEOUT=300  # 5 minutes max lock time
 LOCK_RETRY_INTERVAL=0.5  # Wait 500ms between retries
 LOCK_MAX_RETRIES=100  # Total 50 seconds max wait
+LOCK_AT_FILE=""  # Tracks lock file path for acquire_lock_at/release_lock_at
 
 # Fallback constant — ensures E_LOCK_STALE is defined whether or not error-handler.sh was loaded
 : "${E_LOCK_STALE:=E_LOCK_STALE}"
@@ -30,18 +33,37 @@ mkdir -p "$LOCK_DIR"
 # Arguments: file_path (the resource to lock)
 # Returns: 0 on success, 1 on failure
 # Globals: LOCK_ACQUIRED (set to true when lock acquired), CURRENT_LOCK (set to lock file path)
+# Behavior:
+#   - In non-interactive mode, stale locks are auto-cleaned by default.
+#   - Override with AETHER_STALE_LOCK_MODE=error|prompt|auto.
 acquire_lock() {
     local file_path="$1"
     local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
     local lock_pid_file="${lock_file}.pid"
+    local stale_mode="${AETHER_STALE_LOCK_MODE:-}"
+
+    if [[ -z "$stale_mode" ]]; then
+        if [[ -t 2 ]]; then
+            stale_mode="prompt"
+        else
+            stale_mode="auto"
+        fi
+    fi
 
     # Check if lock file exists and is stale
     if [ -f "$lock_file" ]; then
         local lock_pid
         lock_pid=$(cat "$lock_pid_file" 2>/dev/null || echo "")
+        if [[ -z "$lock_pid" ]]; then
+            # Fallback to lock file payload if .pid sidecar is missing/corrupt.
+            lock_pid=$(cat "$lock_file" 2>/dev/null || echo "")
+        fi
+        lock_pid=$(echo "$lock_pid" | tr -d '[:space:]')
+        [[ "$lock_pid" =~ ^[0-9]+$ ]] || lock_pid=""
+
         local is_stale=false
 
-        # Check age FIRST (before PID check) to handle PID reuse race
+        # Compute lock age for timeout-based stale checks when PID is unavailable.
         local lock_mtime=0
         # Platform-portable mtime: macOS uses stat -f %m, Linux uses stat -c %Y
         if stat -f %m "$lock_file" >/dev/null 2>&1; then
@@ -51,32 +73,47 @@ acquire_lock() {
         fi
         local lock_age=$(( $(date +%s) - lock_mtime ))
 
-        if [[ $lock_age -gt $LOCK_TIMEOUT ]]; then
+        # Mark stale only when we can do so safely:
+        # - PID is known and not running
+        # - No PID could be determined and lock exceeded timeout
+        if [[ -n "$lock_pid" ]] && ! kill -0 "$lock_pid" 2>/dev/null; then
             is_stale=true
-        elif [[ -n "$lock_pid" ]] && ! kill -0 "$lock_pid" 2>/dev/null; then
+        elif [[ -z "$lock_pid" ]] && [[ $lock_age -gt $LOCK_TIMEOUT ]]; then
             is_stale=true
         fi
 
         if [[ "$is_stale" == "true" ]]; then
-            # TTY-gated user prompt — never auto-remove stale locks (locked user decision)
-            if [[ -t 2 ]]; then
-                echo "" >&2
-                echo "Warning: stale lock detected (PID ${lock_pid:-unknown} not running, age ${lock_age}s)" >&2
-                echo "Lock file: $lock_file" >&2
-                printf "Remove stale lock and continue? [y/N] " >&2
-                local response
-                read -r response < /dev/tty
-                if [[ "$response" =~ ^[Yy]$ ]]; then
+            case "$stale_mode" in
+                auto)
                     rm -f "$lock_file" "$lock_pid_file"
-                else
-                    echo "Lock removal declined. Remove manually: rm $lock_file" >&2
+                    # Track stale lock cleanup in safety stats (best-effort)
+                    type _safety_stats_increment &>/dev/null && _safety_stats_increment "stale_locks_cleaned" 2>/dev/null || true
+                    ;;
+                prompt)
+                    if [[ -t 2 ]]; then
+                        echo "" >&2
+                        echo "Warning: stale lock detected (PID ${lock_pid:-unknown} not running, age ${lock_age}s)" >&2
+                        echo "Lock file: $lock_file" >&2
+                        printf "Remove stale lock and continue? [y/N] " >&2
+                        local response
+                        read -r response < /dev/tty
+                        if [[ "$response" =~ ^[Yy]$ ]]; then
+                            rm -f "$lock_file" "$lock_pid_file"
+                            type _safety_stats_increment &>/dev/null && _safety_stats_increment "stale_locks_cleaned" 2>/dev/null || true
+                        else
+                            echo "Lock removal declined. Remove manually: rm $lock_file" >&2
+                            return 1
+                        fi
+                    else
+                        printf '{"ok":false,"error":{"code":"%s","message":"Stale lock found. Remove manually: %s"}}\n' "$E_LOCK_STALE" "$lock_file" >&2
+                        return 1
+                    fi
+                    ;;
+                error|*)
+                    printf '{"ok":false,"error":{"code":"%s","message":"Stale lock found. Remove manually: %s"}}\n' "$E_LOCK_STALE" "$lock_file" >&2
                     return 1
-                fi
-            else
-                # Non-interactive: fail with structured JSON error — do NOT auto-remove
-                printf '{"ok":false,"error":{"code":"%s","message":"Stale lock found. Remove manually: %s"}}\n' "$E_LOCK_STALE" "$lock_file" >&2
-                return 1
-            fi
+                    ;;
+            esac
         fi
     fi
 
@@ -85,7 +122,7 @@ acquire_lock() {
     while [ $retry_count -lt $LOCK_MAX_RETRIES ]; do
         # Try to create lock file atomically
         if (set -o noclobber; echo $$ > "$lock_file") 2>/dev/null; then
-            echo $$ > "$lock_pid_file"
+            echo $$ > "$lock_pid_file" 2>/dev/null || true
             export LOCK_ACQUIRED=true
             export CURRENT_LOCK="$lock_file"
             return 0
@@ -113,11 +150,129 @@ release_lock() {
     return 1
 }
 
+# Acquire a lock in a specified directory with optional colony tag
+# Unlike acquire_lock (which uses the global LOCK_DIR), this function takes an
+# explicit lock directory parameter — no global state mutation required.
+# Arguments:
+#   $1 = file_path (resource to lock)
+#   $2 = lock_dir (directory to place lock file in)
+#   $3 = colony_tag (optional, included in lock filename for debuggability)
+# Returns: 0 on success, 1 on failure
+# Sets: LOCK_AT_FILE (path to the acquired lock file for release)
+acquire_lock_at() {
+    local file_path="$1"
+    local lock_dir="$2"
+    local colony_tag="${3:-}"
+
+    local lock_name
+    if [[ -n "$colony_tag" ]]; then
+        lock_name="$(basename "$file_path").${colony_tag}.lock"
+    else
+        lock_name="$(basename "$file_path").lock"
+    fi
+
+    local lock_file="${lock_dir}/${lock_name}"
+    local lock_pid_file="${lock_file}.pid"
+    mkdir -p "$lock_dir"
+
+    local stale_mode="${AETHER_STALE_LOCK_MODE:-}"
+    if [[ -z "$stale_mode" ]]; then
+        if [[ -t 2 ]]; then stale_mode="prompt"; else stale_mode="auto"; fi
+    fi
+
+    # Stale lock detection (reuses same logic as acquire_lock)
+    if [[ -f "$lock_file" ]]; then
+        local lock_pid
+        lock_pid=$(cat "$lock_pid_file" 2>/dev/null || echo "")
+        [[ -z "$lock_pid" ]] && lock_pid=$(cat "$lock_file" 2>/dev/null || echo "")
+        lock_pid=$(echo "$lock_pid" | tr -d '[:space:]')
+        [[ "$lock_pid" =~ ^[0-9]+$ ]] || lock_pid=""
+
+        local is_stale=false
+        local lock_mtime=0
+        if stat -f %m "$lock_file" >/dev/null 2>&1; then
+            lock_mtime=$(stat -f %m "$lock_file" 2>/dev/null || echo 0)
+        else
+            lock_mtime=$(stat -c %Y "$lock_file" 2>/dev/null || echo 0)
+        fi
+        local lock_age=$(( $(date +%s) - lock_mtime ))
+
+        if [[ -n "$lock_pid" ]] && ! kill -0 "$lock_pid" 2>/dev/null; then
+            is_stale=true
+        elif [[ -z "$lock_pid" ]] && [[ $lock_age -gt $LOCK_TIMEOUT ]]; then
+            is_stale=true
+        fi
+
+        if [[ "$is_stale" == "true" ]]; then
+            case "$stale_mode" in
+                auto)
+                    rm -f "$lock_file" "$lock_pid_file"
+                    type _safety_stats_increment &>/dev/null && _safety_stats_increment "stale_locks_cleaned" 2>/dev/null || true
+                    ;;
+                prompt)
+                    if [[ -t 2 ]]; then
+                        echo "" >&2
+                        echo "Warning: stale lock detected (PID ${lock_pid:-unknown} not running, age ${lock_age}s)" >&2
+                        echo "Lock file: $lock_file" >&2
+                        printf "Remove stale lock and continue? [y/N] " >&2
+                        local response
+                        read -r response < /dev/tty
+                        if [[ "$response" =~ ^[Yy]$ ]]; then
+                            rm -f "$lock_file" "$lock_pid_file"
+                            type _safety_stats_increment &>/dev/null && _safety_stats_increment "stale_locks_cleaned" 2>/dev/null || true
+                        else
+                            echo "Lock removal declined. Remove manually: rm $lock_file" >&2
+                            return 1
+                        fi
+                    else
+                        printf '{"ok":false,"error":{"code":"%s","message":"Stale lock found. Remove manually: %s"}}\n' "$E_LOCK_STALE" "$lock_file" >&2
+                        return 1
+                    fi
+                    ;;
+                error|*)
+                    printf '{"ok":false,"error":{"code":"%s","message":"Stale lock found. Remove manually: %s"}}\n' "$E_LOCK_STALE" "$lock_file" >&2
+                    return 1
+                    ;;
+            esac
+        fi
+    fi
+
+    # Retry loop (same as acquire_lock)
+    local retry_count=0
+    while [[ $retry_count -lt $LOCK_MAX_RETRIES ]]; do
+        if (set -o noclobber; echo $$ > "$lock_file") 2>/dev/null; then
+            echo $$ > "$lock_pid_file" 2>/dev/null || true
+            LOCK_AT_FILE="$lock_file"
+            return 0
+        fi
+        retry_count=$((retry_count + 1))
+        [[ $retry_count -lt $LOCK_MAX_RETRIES ]] && sleep $LOCK_RETRY_INTERVAL
+    done
+
+    echo "Failed to acquire lock for $file_path in $lock_dir after $LOCK_MAX_RETRIES attempts" >&2
+    return 1
+}
+
+# Release a lock acquired with acquire_lock_at
+# Arguments: $1 = lock_file (the LOCK_AT_FILE value from acquire_lock_at)
+release_lock_at() {
+    local lock_file="${1:-$LOCK_AT_FILE}"
+    if [[ -n "$lock_file" && -f "$lock_file" ]]; then
+        rm -f "$lock_file" "${lock_file}.pid"
+        [[ "$lock_file" == "$LOCK_AT_FILE" ]] && LOCK_AT_FILE=""
+        return 0
+    fi
+    return 1
+}
+
 # Cleanup function for script exit
 cleanup_locks() {
     if [ "$LOCK_ACQUIRED" = "true" ]; then
         release_lock
     fi
+    if [[ -n "${LOCK_AT_FILE:-}" ]]; then
+        release_lock_at "$LOCK_AT_FILE"
+    fi
 }
 
 # Register cleanup on exit — includes HUP for SSH disconnect safety
@@ -155,4 +310,4 @@ wait_for_lock() {
 }
 
 # Export functions for use in other scripts
-export -f acquire_lock release_lock is_locked get_lock_holder wait_for_lock cleanup_locks
+export -f acquire_lock release_lock acquire_lock_at release_lock_at is_locked get_lock_holder wait_for_lock cleanup_locks

package/.aether/utils/flag.sh

@@ -0,0 +1,278 @@
+#!/bin/bash
+# Flag utility functions — extracted from aether-utils.sh
+# Provides: _flag_add, _flag_check_blockers, _flag_resolve, _flag_acknowledge, _flag_list, _flag_auto_resolve
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, json_warn, atomic_write, acquire_lock,
+# release_lock, feature_enabled, LOCK_DIR, DATA_DIR, SCRIPT_DIR, error constants) is available.
+
+_flag_add() {
+    # Add a project-specific flag (blocker, issue, or note)
+    # Usage: flag-add <type> <title> <description> [source] [phase]
+    # Types: blocker (critical, blocks advancement), issue (high, warning), note (low, info)
+    type="${1:-issue}"
+    title="${2:-}"
+    desc="${3:-}"
+    source="${4:-manual}"
+    phase="${5:-null}"
+    [[ -z "$title" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-add <type> <title> <description> [source] [phase]"
+
+    mkdir -p "$COLONY_DATA_DIR"
+    flags_file="$COLONY_DATA_DIR/flags.json"
+
+    if [[ ! -f "$flags_file" ]]; then
+      atomic_write "$flags_file" '{"version":1,"flags":[]}' || json_err "$E_UNKNOWN" "Failed to initialize flags file"
+    fi
+
+    id="flag_$(date -u +%s)_$(head -c 2 /dev/urandom | od -An -tx1 | tr -d ' ')"
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
+    if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
+      json_warn "W_DEGRADED" "File locking disabled - proceeding without lock: $(type _feature_reason &>/dev/null && _feature_reason file_locking || echo 'unknown')"
+    else
+      acquire_lock "$flags_file" || {
+        if type json_err &>/dev/null; then
+          json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+        else
+          echo '{"ok":false,"error":"Failed to acquire lock on flags.json"}' >&2
+          exit 1
+        fi
+      }
+      # Ensure lock is always released on exit (BUG-002 fix)
+      trap 'release_lock 2>/dev/null || true' EXIT  # SUPPRESS:OK -- cleanup: lock may not be held
+    fi
+
+    # Map type to severity
+    case "$type" in
+      blocker)  severity="critical" ;;
+      issue)    severity="high" ;;
+      note)     severity="low" ;;
+      *)        severity="medium" ;;
+    esac
+
+    # Handle phase as number or null
+    if [[ "$phase" =~ ^[0-9]+$ ]]; then
+      phase_jq="$phase"
+    else
+      phase_jq="null"
+    fi
+
+    updated=$(jq --arg id "$id" --arg type "$type" --arg sev "$severity" \
+      --arg title "$title" --arg desc "$desc" --arg source "$source" \
+      --argjson phase "$phase_jq" --arg ts "$ts" '
+      .flags += [{
+        id: $id,
+        type: $type,
+        severity: $sev,
+        title: $title,
+        description: $desc,
+        source: $source,
+        phase: $phase,
+        created_at: $ts,
+        acknowledged_at: null,
+        resolved_at: null,
+        resolution: null,
+        auto_resolve_on: (if $type == "blocker" and ($source | test("chaos") | not) then "build_pass" else null end)
+      }]
+    ' "$flags_file") || { json_err "$E_JSON_INVALID" "Failed to add flag"; }
+
+    atomic_write "$flags_file" "$updated"
+    trap - EXIT
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+    json_ok "$(jq -n --arg id "$id" --arg type "$type" --arg severity "$severity" \
+      '{id: $id, type: $type, severity: $severity}')"
+}
+
+_flag_check_blockers() {
+    # Count unresolved blockers for the current phase
+    # Usage: flag-check-blockers [phase]
+    phase="${1:-}"
+    flags_file="$COLONY_DATA_DIR/flags.json"
+
+    if [[ ! -f "$flags_file" ]]; then
+      json_ok '{"blockers":0,"issues":0,"notes":0}'
+      exit 0
+    fi
+
+    if [[ -n "$phase" && "$phase" =~ ^[0-9]+$ ]]; then
+      # Filter by phase
+      result=$(jq --argjson phase "$phase" '{
+        blockers: [.flags[] | select(.type == "blocker" and .resolved_at == null and (.phase == $phase or .phase == null))] | length,
+        issues: [.flags[] | select(.type == "issue" and .resolved_at == null and (.phase == $phase or .phase == null))] | length,
+        notes: [.flags[] | select(.type == "note" and .resolved_at == null and (.phase == $phase or .phase == null))] | length
+      }' "$flags_file")
+    else
+      # All unresolved
+      result=$(jq '{
+        blockers: [.flags[] | select(.type == "blocker" and .resolved_at == null)] | length,
+        issues: [.flags[] | select(.type == "issue" and .resolved_at == null)] | length,
+        notes: [.flags[] | select(.type == "note" and .resolved_at == null)] | length
+      }' "$flags_file")
+    fi
+
+    json_ok "$result"
+}
+
+_flag_resolve() {
+    # Resolve a flag with optional resolution message
+    # Usage: flag-resolve <flag_id> [resolution_message]
+    flag_id="${1:-}"
+    resolution="${2:-Resolved}"
+    [[ -z "$flag_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-resolve <flag_id> [resolution_message]"
+
+    flags_file="$COLONY_DATA_DIR/flags.json"
+    [[ ! -f "$flags_file" ]] && json_err "$E_FILE_NOT_FOUND" "No flags file found"
+
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
+    if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
+      json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
+    else
+      acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+      trap 'release_lock 2>/dev/null || true' EXIT  # SUPPRESS:OK -- cleanup: lock may not be held
+    fi
+
+    updated=$(jq --arg id "$flag_id" --arg res "$resolution" --arg ts "$ts" '
+      .flags = [.flags[] | if .id == $id then
+        .resolved_at = $ts |
+        .resolution = $res
+      else . end]
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to resolve flag"
+    }
+
+    atomic_write "$flags_file" "$updated"
+    trap - EXIT
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+    json_ok "$(jq -n --arg id "$flag_id" '{resolved: $id}')"
+}
+
+_flag_acknowledge() {
+    # Acknowledge a flag (issue continues but noted)
+    # Usage: flag-acknowledge <flag_id>
+    flag_id="${1:-}"
+    [[ -z "$flag_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-acknowledge <flag_id>"
+
+    flags_file="$COLONY_DATA_DIR/flags.json"
+    [[ ! -f "$flags_file" ]] && json_err "$E_FILE_NOT_FOUND" "No flags file found"
+
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
+    if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
+      json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
+    else
+      acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+      trap 'release_lock 2>/dev/null || true' EXIT  # SUPPRESS:OK -- cleanup: lock may not be held
+    fi
+
+    updated=$(jq --arg id "$flag_id" --arg ts "$ts" '
+      .flags = [.flags[] | if .id == $id then
+        .acknowledged_at = $ts
+      else . end]
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to acknowledge flag"
+    }
+
+    atomic_write "$flags_file" "$updated"
+    trap - EXIT
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+    json_ok "$(jq -n --arg id "$flag_id" '{acknowledged: $id}')"
+}
+
+_flag_list() {
+    # List flags, optionally filtered
+    # Usage: flag-list [--all] [--type blocker|issue|note] [--phase N]
+    flags_file="$COLONY_DATA_DIR/flags.json"
+    show_all="false"
+    filter_type=""
+    filter_phase=""
+
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --all) show_all="true"; shift ;;
+        --type) filter_type="$2"; shift 2 ;;
+        --phase) filter_phase="$2"; shift 2 ;;
+        *) shift ;;
+      esac
+    done
+
+    if [[ ! -f "$flags_file" ]]; then
+      json_ok '{"flags":[],"count":0}'
+      exit 0
+    fi
+
+    # Validate filter_phase as numeric (safe for --argjson)
+    if [[ -n "$filter_phase" && "$filter_phase" =~ ^[0-9]+$ ]]; then
+      phase_num="$filter_phase"
+    else
+      phase_num=""
+    fi
+
+    # Build jq command with --arg to prevent filter injection
+    # filter_type is passed via --arg (safe string interpolation in jq)
+    # phase_num is passed via --argjson (numeric-only, pre-validated)
+    if [[ -n "$phase_num" ]]; then
+      result=$(jq --arg ft "$filter_type" --argjson ph "$phase_num" --argjson all "$show_all" '
+        .flags
+        | (if $all | not then [.[] | select(.resolved_at == null)] else . end)
+        | (if $ft != "" then [.[] | select(.type == $ft)] else . end)
+        | (if $ph != null then [.[] | select(.phase == $ph or .phase == null)] else . end)
+        | {flags: ., count: length}
+      ' "$flags_file")
+    else
+      result=$(jq --arg ft "$filter_type" --argjson all "$show_all" '
+        .flags
+        | (if $all | not then [.[] | select(.resolved_at == null)] else . end)
+        | (if $ft != "" then [.[] | select(.type == $ft)] else . end)
+        | {flags: ., count: length}
+      ' "$flags_file")
+    fi
+
+    json_ok "$result"
+}
+
+_flag_auto_resolve() {
+    # Auto-resolve flags based on trigger (e.g., build_pass)
+    # Usage: flag-auto-resolve <trigger>
+    trigger="${1:-build_pass}"
+    flags_file="$COLONY_DATA_DIR/flags.json"
+
+    if [[ ! -f "$flags_file" ]]; then json_ok '{"resolved":0}'; exit 0; fi
+
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
+    if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
+      json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
+    else
+      acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+      # Ensure lock is always released on exit (BUG-005/BUG-011 fix)
+      trap 'release_lock 2>/dev/null || true' EXIT  # SUPPRESS:OK -- cleanup: lock may not be held
+    fi
+
+    # Count how many will be resolved
+    count=$(jq --arg trigger "$trigger" '
+      [.flags[] | select(.auto_resolve_on == $trigger and .resolved_at == null)] | length
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to count flags for auto-resolve"
+    }
+
+    # Resolve them
+    updated=$(jq --arg trigger "$trigger" --arg ts "$ts" '
+      .flags = [.flags[] | if .auto_resolve_on == $trigger and .resolved_at == null then
+        .resolved_at = $ts |
+        .resolution = "Auto-resolved on " + $trigger
+      else . end]
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to auto-resolve flags"
+    }
+
+    atomic_write "$flags_file" "$updated"
+    trap - EXIT
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+    json_ok "$(jq -n --argjson count "$count" --arg trigger "$trigger" \
+      '{resolved: $count, trigger: $trigger}')"
+}