aether-colony 3.1.17 → 5.1.0

package/{runtime → .aether}/utils/error-handler.sh

@@ -13,10 +13,13 @@ E_REPO_NOT_INITIALIZED="E_REPO_NOT_INITIALIZED"
 E_FILE_NOT_FOUND="E_FILE_NOT_FOUND"
 E_JSON_INVALID="E_JSON_INVALID"
 E_LOCK_FAILED="E_LOCK_FAILED"
+E_LOCK_STALE="E_LOCK_STALE"
 E_GIT_ERROR="E_GIT_ERROR"
 E_VALIDATION_FAILED="E_VALIDATION_FAILED"
 E_FEATURE_UNAVAILABLE="E_FEATURE_UNAVAILABLE"
 E_BASH_ERROR="E_BASH_ERROR"
+E_DEPENDENCY_MISSING="E_DEPENDENCY_MISSING"
+E_RESOURCE_NOT_FOUND="E_RESOURCE_NOT_FOUND"
 
 # --- Recovery Suggestion Functions (internal, prefixed with _) ---
 _recovery_hub_not_found() { echo '"Run: aether install"'; }
@@ -24,8 +27,11 @@ _recovery_repo_not_init() { echo '"Run /ant:init in this repo first"'; }
 _recovery_file_not_found() { echo '"Check file path and permissions"'; }
 _recovery_json_invalid() { echo '"Validate JSON syntax"'; }
 _recovery_lock_failed() { echo '"Wait for other operations to complete"'; }
+_recovery_lock_stale() { echo '"Remove the stale lock file manually or run: aether force-unlock"'; }
 _recovery_git_error() { echo '"Check git status and resolve conflicts"'; }
 _recovery_default() { echo 'null'; }
+_recovery_dependency_missing() { echo '"Install the required dependency"'; }
+_recovery_resource_not_found() { echo '"Check that the resource exists and try again"'; }
 
 # Get recovery suggestion based on error code
 _get_recovery() {
@@ -36,7 +42,10 @@ _get_recovery() {
     "$E_FILE_NOT_FOUND") _recovery_file_not_found ;;
     "$E_JSON_INVALID") _recovery_json_invalid ;;
     "$E_LOCK_FAILED") _recovery_lock_failed ;;
+    "$E_LOCK_STALE") _recovery_lock_stale ;;
     "$E_GIT_ERROR") _recovery_git_error ;;
+    "$E_DEPENDENCY_MISSING") _recovery_dependency_missing ;;
+    "$E_RESOURCE_NOT_FOUND") _recovery_resource_not_found ;;
     *) _recovery_default ;;
   esac
 }
@@ -78,8 +87,8 @@ json_err() {
     "$code" "$escaped_message" "$details_json" "$recovery" "$timestamp" >&2
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] ERROR $code: $escaped_message" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]]; then
+    echo "[$timestamp] ERROR $code: $escaped_message" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
   fi
 
   exit 1
@@ -102,8 +111,22 @@ json_warn() {
     "$code" "$escaped_message" "$timestamp"
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] WARN $code: $escaped_message" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]]; then
+    echo "[$timestamp] WARN $code: $escaped_message" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
+  fi
+}
+
+# --- _aether_log_error function for surfaced errors ---
+# Dual output: [error] prefix to stderr (screen) + timestamped entry to errors.log (file)
+# Distinct from: json_err (structured JSON), json_warn (non-fatal JSON), ⚠ (recovery), [trimmed] (budget)
+_aether_log_error() {
+  local message="$1"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  echo "[error] $message" >&2
+  if [[ -n "${COLONY_DATA_DIR:-}" ]]; then
+    mkdir -p "$DATA_DIR" 2>/dev/null  # SUPPRESS:OK -- idempotent: ensure dir exists
+    echo "[$timestamp] $message" >> "$COLONY_DATA_DIR/errors.log" 2>/dev/null  # SUPPRESS:OK -- cleanup: log write is best-effort
   fi
 }
 
@@ -130,8 +153,8 @@ error_handler() {
     "$E_BASH_ERROR" "$details" "$(_recovery_default)" "$timestamp" >&2
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] ERROR $E_BASH_ERROR: Command failed at line $line_num (exit $exit_code)" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]]; then
+    echo "[$timestamp] ERROR $E_BASH_ERROR: Command failed at line $line_num (exit $exit_code)" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
   fi
 
   exit 1
@@ -189,12 +212,15 @@ feature_log_degradation() {
 }
 
 # --- Export all functions and variables ---
-export -f json_err json_warn error_handler
+export -f json_err json_warn _aether_log_error error_handler
 export -f feature_enable feature_disable feature_enabled feature_log_degradation
 export -f _get_recovery _recovery_hub_not_found _recovery_repo_not_init
 export -f _recovery_file_not_found _recovery_json_invalid _recovery_lock_failed
+export -f _recovery_lock_stale
 export -f _recovery_git_error _recovery_default _feature_reason
+export -f _recovery_dependency_missing _recovery_resource_not_found
 export E_UNKNOWN E_HUB_NOT_FOUND E_REPO_NOT_INITIALIZED E_FILE_NOT_FOUND
-export E_JSON_INVALID E_LOCK_FAILED E_GIT_ERROR E_VALIDATION_FAILED
+export E_JSON_INVALID E_LOCK_FAILED E_LOCK_STALE E_GIT_ERROR E_VALIDATION_FAILED
 export E_FEATURE_UNAVAILABLE E_BASH_ERROR
+export E_DEPENDENCY_MISSING E_RESOURCE_NOT_FOUND
 export _FEATURES_DISABLED

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

@@ -0,0 +1,313 @@
+#!/bin/bash
+# Aether File Lock Utility
+# Implements file locking for concurrent colony access prevention
+#
+# Usage:
+#   source .aether/utils/file-lock.sh
+#   acquire_lock /path/to/file.lock
+#   # ... critical section ...
+#   release_lock
+
+# 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}"
+
+# Create lock directory if it doesn't exist
+mkdir -p "$LOCK_DIR"
+
+# Acquire a file lock using noclobber
+# 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
+
+        # 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
+            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 ))
+
+        # 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 [[ -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"
+                    # 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
+                    ;;
+            esac
+        fi
+    fi
+
+    # Try to acquire lock with timeout
+    local retry_count=0
+    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" 2>/dev/null || true
+            export LOCK_ACQUIRED=true
+            export CURRENT_LOCK="$lock_file"
+            return 0
+        fi
+
+        retry_count=$((retry_count + 1))
+        if [ $retry_count -lt $LOCK_MAX_RETRIES ]; then
+            sleep $LOCK_RETRY_INTERVAL
+        fi
+    done
+
+    echo "Failed to acquire lock for $file_path after $LOCK_MAX_RETRIES attempts" >&2
+    return 1
+}
+
+# Release a file lock
+# Arguments: None (uses CURRENT_LOCK global set by acquire_lock)
+release_lock() {
+    if [ "$LOCK_ACQUIRED" = "true" ] && [ -n "$CURRENT_LOCK" ]; then
+        rm -f "$CURRENT_LOCK" "${CURRENT_LOCK}.pid"
+        export LOCK_ACQUIRED=false
+        export CURRENT_LOCK=""
+        return 0
+    fi
+    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
+trap cleanup_locks EXIT TERM INT HUP
+
+# Check if a file is currently locked
+is_locked() {
+    local file_path="$1"
+    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
+    [ -f "$lock_file" ]
+}
+
+# Get PID of process holding lock
+get_lock_holder() {
+    local file_path="$1"
+    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock.pid"
+    cat "$lock_file" 2>/dev/null || echo ""
+}
+
+# Wait for lock to be released
+wait_for_lock() {
+    local file_path="$1"
+    local max_wait=${2:-$LOCK_TIMEOUT}
+    local waited=0
+
+    while is_locked "$file_path" && [ $waited -lt $max_wait ]; do
+        sleep 1
+        waited=$((waited + 1))
+    done
+
+    if [ $waited -ge $max_wait ]; then
+        return 1
+    fi
+    return 0
+}
+
+# Export functions for use in other scripts
+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,267 @@
+#!/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
+
+    # Build jq filter
+    jq_filter='.flags'
+
+    if [[ "$show_all" != "true" ]]; then
+      jq_filter+=' | [.[] | select(.resolved_at == null)]'
+    fi
+
+    if [[ -n "$filter_type" ]]; then
+      jq_filter+=" | [.[] | select(.type == \"$filter_type\")]"
+    fi
+
+    if [[ -n "$filter_phase" && "$filter_phase" =~ ^[0-9]+$ ]]; then
+      jq_filter+=" | [.[] | select(.phase == $filter_phase or .phase == null)]"
+    fi
+
+    result=$(jq "{flags: ($jq_filter), count: ($jq_filter | length)}" "$flags_file")
+    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}')"
+}