aether-colony 3.1.17 → 5.0.0

package/{runtime → .aether}/utils/chamber-compare.sh

@@ -7,13 +7,26 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CHAMBERS_DIR="${CHAMBERS_DIR:-.aether/chambers}"
 
+# Source error-handler.sh for E_* constants and enhanced json_err
+[[ -f "$SCRIPT_DIR/error-handler.sh" ]] && source "$SCRIPT_DIR/error-handler.sh"
+
+# Fallback E_* constants (no-ops when error-handler.sh is already loaded)
+: "${E_UNKNOWN:=E_UNKNOWN}"
+: "${E_FILE_NOT_FOUND:=E_FILE_NOT_FOUND}"
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+
 # JSON output helpers
 json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
-json_err() {
-  local message="${2:-$1}"
-  printf '{"ok":false,"error":"%s"}\n' "$message" >&2
-  exit 1
-}
+
+# Guard: yield to error-handler.sh's enhanced json_err when already loaded
+if ! type json_err &>/dev/null; then
+  json_err() {
+    local code="${1:-E_UNKNOWN}"
+    local message="${2:-An unknown error occurred}"
+    printf '{"ok":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message" >&2
+    exit 1
+  }
+fi
 
 # Load chamber manifest
 load_chamber() {
@@ -21,7 +34,7 @@ load_chamber() {
   local manifest_file="$CHAMBERS_DIR/$chamber_name/manifest.json"
 
   if [[ ! -f "$manifest_file" ]]; then
-    json_err "Chamber not found: $chamber_name"
+    json_err "$E_FILE_NOT_FOUND" "Chamber not found: $chamber_name. Try: check the chamber name with /ant:tunnels."
   fi
 
   cat "$manifest_file"
@@ -41,7 +54,7 @@ EOF
   compare)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: compare <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: compare <chamber_a> <chamber_b>."
 
     # Load both manifests
     manifest_a=$(load_chamber "$chamber_a")
@@ -93,7 +106,7 @@ EOF
   diff)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: diff <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: diff <chamber_a> <chamber_b>."
 
     manifest_a=$(load_chamber "$chamber_a")
     manifest_b=$(load_chamber "$chamber_b")
@@ -138,7 +151,7 @@ EOF
   stats)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: stats <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: stats <chamber_a> <chamber_b>."
 
     manifest_a=$(load_chamber "$chamber_a")
     manifest_b=$(load_chamber "$chamber_b")
@@ -175,6 +188,6 @@ EOF
     ;;
 
   *)
-    json_err "Unknown command: $cmd. Use: compare, diff, stats"
+    json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd. Try: compare, diff, or stats."
     ;;
 esac

package/{runtime → .aether}/utils/chamber-utils.sh

@@ -27,11 +27,23 @@ SCRIPT_DIR="${SCRIPT_DIR:-$__chamber_utils_dir}"
 
 # --- JSON output helpers ---
 json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
-json_err() {
-  local message="${2:-$1}"
-  printf '{"ok":false,"error":"%s"}\n' "$message" >&2
-  exit 1
-}
+
+# Guard: yield to error-handler.sh's enhanced json_err when already loaded
+if ! type json_err &>/dev/null; then
+  json_err() {
+    local code="${1:-E_UNKNOWN}"
+    local message="${2:-An unknown error occurred}"
+    printf '{"ok":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message" >&2
+    exit 1
+  }
+fi
+
+# Fallback E_* constants (no-ops when error-handler.sh is already loaded)
+: "${E_UNKNOWN:=E_UNKNOWN}"
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+: "${E_FILE_NOT_FOUND:=E_FILE_NOT_FOUND}"
+: "${E_BASH_ERROR:=E_BASH_ERROR}"
+: "${E_JSON_INVALID:=E_JSON_INVALID}"
 
 # --- Chamber Functions ---
 
@@ -93,20 +105,20 @@ chamber_create() {
   local learnings_json="$9"
 
   # Validate inputs
-  [[ -z "$chamber_dir" ]] && json_err "chamber_dir is required"
-  [[ -z "$state_file" ]] && json_err "state_file is required"
-  [[ ! -f "$state_file" ]] && json_err "State file not found: $state_file"
+  [[ -z "$chamber_dir" ]] && json_err "$E_VALIDATION_FAILED" "chamber_dir argument is required. Try: pass the chamber directory path."
+  [[ -z "$state_file" ]] && json_err "$E_VALIDATION_FAILED" "state_file argument is required. Try: pass the state file path."
+  [[ ! -f "$state_file" ]] && json_err "$E_FILE_NOT_FOUND" "State file not found: $state_file. Try: check the file path."
 
   # Create chamber directory
-  mkdir -p "$chamber_dir" || json_err "Failed to create chamber directory: $chamber_dir"
+  mkdir -p "$chamber_dir" || json_err "$E_BASH_ERROR" "Couldn't create chamber directory: $chamber_dir. Try: check disk space and permissions."
 
   # Copy state file to chamber
   local target_state="$chamber_dir/COLONY_STATE.json"
-  cp "$state_file" "$target_state" || json_err "Failed to copy state file"
+  cp "$state_file" "$target_state" || json_err "$E_BASH_ERROR" "Couldn't copy the state file. Try: check disk space and permissions."
 
   # Compute hash of the copied state file
   local state_hash=$(chamber_compute_hash "$target_state")
-  [[ -z "$state_hash" ]] && json_err "Failed to compute hash of state file"
+  [[ -z "$state_hash" ]] && json_err "$E_BASH_ERROR" "Couldn't compute state file hash. Try: check that shasum is available."
 
   # Generate timestamp
   local entombed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -132,14 +144,14 @@ EOF
 
   # Write manifest atomically if atomic_write is available, otherwise direct
   if type atomic_write &>/dev/null; then
-    atomic_write "$manifest_file" "$manifest_content" || json_err "Failed to write manifest"
+    atomic_write "$manifest_file" "$manifest_content" || json_err "$E_BASH_ERROR" "Couldn't write chamber manifest. Try: check disk space."
   else
-    echo "$manifest_content" > "$manifest_file" || json_err "Failed to write manifest"
+    echo "$manifest_content" > "$manifest_file" || json_err "$E_BASH_ERROR" "Couldn't write chamber manifest. Try: check disk space."
   fi
 
   # Verify the manifest was written correctly
   if [[ ! -f "$manifest_file" ]]; then
-    json_err "Manifest file not created"
+    json_err "$E_FILE_NOT_FOUND" "Chamber manifest wasn't created. Try: check disk space and permissions."
   fi
 
   # Return success with chamber info
@@ -168,23 +180,23 @@ chamber_verify() {
   local chamber_dir="$1"
 
   # Validate inputs
-  [[ -z "$chamber_dir" ]] && json_err "chamber_dir is required"
-  [[ ! -d "$chamber_dir" ]] && json_err "Chamber directory not found: $chamber_dir"
+  [[ -z "$chamber_dir" ]] && json_err "$E_VALIDATION_FAILED" "chamber_dir argument is required. Try: pass the chamber directory path."
+  [[ ! -d "$chamber_dir" ]] && json_err "$E_FILE_NOT_FOUND" "Chamber directory not found: $chamber_dir. Try: check the path."
 
   local manifest_file="$chamber_dir/manifest.json"
   local state_file="$chamber_dir/COLONY_STATE.json"
 
   # Check required files exist
-  [[ ! -f "$manifest_file" ]] && json_err "Manifest not found in chamber"
-  [[ ! -f "$state_file" ]] && json_err "COLONY_STATE.json not found in chamber"
+  [[ ! -f "$manifest_file" ]] && json_err "$E_FILE_NOT_FOUND" "Manifest not found in chamber. Try: verify the chamber was created correctly."
+  [[ ! -f "$state_file" ]] && json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found in chamber. Try: re-entomb the colony."
 
   # Read stored hash from manifest
   local stored_hash=$(jq -r '.files["COLONY_STATE.json"] // empty' "$manifest_file" 2>/dev/null)
-  [[ -z "$stored_hash" ]] && json_err "No hash found in manifest for COLONY_STATE.json"
+  [[ -z "$stored_hash" ]] && json_err "$E_JSON_INVALID" "No hash found in manifest. Try: re-entomb the colony."
 
   # Compute current hash
   local current_hash=$(chamber_compute_hash "$state_file")
-  [[ -z "$current_hash" ]] && json_err "Failed to compute hash of state file"
+  [[ -z "$current_hash" ]] && json_err "$E_BASH_ERROR" "Couldn't compute state file hash. Try: check that shasum is available."
 
   # Compare hashes
   if [[ "$stored_hash" != "$current_hash" ]]; then

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
 }
@@ -193,8 +202,11 @@ export -f json_err json_warn 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/{runtime → .aether}/utils/file-lock.sh

@@ -6,7 +6,7 @@
 #   source .aether/utils/file-lock.sh
 #   acquire_lock /path/to/file.lock
 #   # ... critical section ...
-#   release_lock /path/to/file.lock
+#   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
@@ -20,13 +20,16 @@ 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
 
+# 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 flock
+# 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)
+# Globals: LOCK_ACQUIRED (set to true when lock acquired), CURRENT_LOCK (set to lock file path)
 acquire_lock() {
     local file_path="$1"
     local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
@@ -34,12 +37,45 @@ acquire_lock() {
 
     # Check if lock file exists and is stale
     if [ -f "$lock_file" ]; then
-        local lock_pid=$(cat "$lock_pid_file" 2>/dev/null || echo "")
-        if [ -n "$lock_pid" ]; then
-            # Check if process is still running
-            if ! kill -0 "$lock_pid" 2>/dev/null; then
-                echo "Lock stale (PID $lock_pid not running), cleaning up..."
-                rm -f "$lock_file" "$lock_pid_file"
+        local lock_pid
+        lock_pid=$(cat "$lock_pid_file" 2>/dev/null || echo "")
+        local is_stale=false
+
+        # Check age FIRST (before PID check) to handle PID reuse race
+        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 ))
+
+        if [[ $lock_age -gt $LOCK_TIMEOUT ]]; then
+            is_stale=true
+        elif [[ -n "$lock_pid" ]] && ! kill -0 "$lock_pid" 2>/dev/null; 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
+                    rm -f "$lock_file" "$lock_pid_file"
+                else
+                    echo "Lock removal declined. Remove manually: rm $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
         fi
     fi
@@ -61,12 +97,12 @@ acquire_lock() {
         fi
     done
 
-    echo "Failed to acquire lock for $file_path after $LOCK_MAX_RETRIES attempts"
+    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 from acquire_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"
@@ -84,8 +120,8 @@ cleanup_locks() {
     fi
 }
 
-# Register cleanup on exit
-trap cleanup_locks EXIT TERM INT
+# 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() {