aether-colony 1.1.0

package/.aether/utils/chamber-utils.sh

@@ -0,0 +1,297 @@
+#!/bin/bash
+# Aether Chamber Utilities
+# Manages entombed colonies — directory management, manifest generation, integrity verification
+#
+# Usage:
+#   source .aether/utils/chamber-utils.sh
+#   chamber_create <chamber_dir> <state_file> <goal> <phases_completed> <total_phases> <milestone> <version> <decisions_json> <learnings_json>
+#   chamber_verify <chamber_dir>
+#   chamber_list <chambers_root>
+#   chamber_sanitize_goal <goal>
+
+set -euo pipefail
+
+# Initialize lock state before sourcing (file-lock.sh trap needs these)
+LOCK_ACQUIRED=${LOCK_ACQUIRED:-false}
+CURRENT_LOCK=${CURRENT_LOCK:-""}
+
+# Get script directory for sourcing (preserve parent SCRIPT_DIR if set)
+__chamber_utils_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AETHER_ROOT="$(cd "$__chamber_utils_dir/../.." && pwd 2>/dev/null || echo "$__chamber_utils_dir/../..")"
+
+# Use parent SCRIPT_DIR if available, otherwise use local
+SCRIPT_DIR="${SCRIPT_DIR:-$__chamber_utils_dir}"
+
+# Source atomic-write for safe file operations
+[[ -f "$SCRIPT_DIR/atomic-write.sh" ]] && source "$SCRIPT_DIR/atomic-write.sh"
+
+# --- JSON output helpers ---
+json_ok() { printf '{"ok":true,"result":%s}\n' "$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 ---
+
+# Sanitize goal string for use in directory names
+# Converts to lowercase, replaces spaces/special chars with hyphens, removes non-alphanumeric
+chamber_sanitize_goal() {
+  local goal="$1"
+  # Convert to lowercase, replace spaces and special chars with hyphens
+  local sanitized=$(echo "$goal" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-')
+  # Remove leading/trailing hyphens
+  sanitized=$(echo "$sanitized" | sed 's/^-//;s/-$//')
+  # Limit length to avoid overly long directory names
+  if [[ ${#sanitized} -gt 50 ]]; then
+    sanitized="${sanitized:0:50}"
+  fi
+  echo "$sanitized"
+}
+
+# Compute SHA256 hash of a file
+# Returns hash string or empty on error
+chamber_compute_hash() {
+  local file_path="$1"
+  if [[ ! -f "$file_path" ]]; then
+    echo ""
+    return 1
+  fi
+
+  # Try sha256sum first (Linux), then shasum -a 256 (macOS)
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file_path" | cut -d' ' -f1
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file_path" | cut -d' ' -f1
+  else
+    echo ""
+    return 1
+  fi
+}
+
+# Create a new chamber (entomb a colony)
+# Arguments:
+#   chamber_dir: Directory to create for this chamber
+#   state_file: Path to COLONY_STATE.json to archive
+#   goal: Colony goal string
+#   phases_completed: Number of completed phases
+#   total_phases: Total number of phases
+#   milestone: Milestone name
+#   version: Version string
+#   decisions_json: JSON array of decisions
+#   learnings_json: JSON array of learnings
+chamber_create() {
+  local chamber_dir="$1"
+  local state_file="$2"
+  local goal="$3"
+  local phases_completed="$4"
+  local total_phases="$5"
+  local milestone="$6"
+  local version="$7"
+  local decisions_json="$8"
+  local learnings_json="$9"
+
+  # Validate inputs
+  [[ -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 "$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 "$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 "$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")
+
+  # Create manifest.json
+  local manifest_file="$chamber_dir/manifest.json"
+  local manifest_content=$(cat <<EOF
+{
+  "entombed_at": "$entombed_at",
+  "goal": $(echo "$goal" | jq -Rs '.[:-1]'),
+  "phases_completed": $phases_completed,
+  "total_phases": $total_phases,
+  "milestone": $(echo "$milestone" | jq -Rs '.[:-1]'),
+  "version": $(echo "$version" | jq -Rs '.[:-1]'),
+  "decisions": $decisions_json,
+  "learnings": $learnings_json,
+  "files": {
+    "COLONY_STATE.json": "$state_hash"
+  }
+}
+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 "$E_BASH_ERROR" "Couldn't write chamber manifest. Try: check disk space."
+  else
+    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 "$E_FILE_NOT_FOUND" "Chamber manifest wasn't created. Try: check disk space and permissions."
+  fi
+
+  # Return success with chamber info
+  local result=$(cat <<EOF
+{
+  "chamber_dir": "$chamber_dir",
+  "manifest": {
+    "entombed_at": "$entombed_at",
+    "goal": $(echo "$goal" | jq -Rs '.[:-1]'),
+    "phases_completed": $phases_completed,
+    "total_phases": $total_phases,
+    "milestone": $(echo "$milestone" | jq -Rs '.[:-1]'),
+    "version": $(echo "$version" | jq -Rs '.[:-1]')
+  }
+}
+EOF
+)
+
+  json_ok "$result"
+}
+
+# Verify chamber integrity
+# Arguments:
+#   chamber_dir: Directory containing the chamber
+chamber_verify() {
+  local chamber_dir="$1"
+
+  # Validate inputs
+  [[ -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 "$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 "$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 "$E_BASH_ERROR" "Couldn't compute state file hash. Try: check that shasum is available."
+
+  # Compare hashes
+  if [[ "$stored_hash" != "$current_hash" ]]; then
+    local result=$(cat <<EOF
+{
+  "verified": false,
+  "chamber_dir": "$chamber_dir",
+  "error": "hash mismatch",
+  "stored_hash": "$stored_hash",
+  "current_hash": "$current_hash"
+}
+EOF
+)
+    json_ok "$result"
+    return 0
+  fi
+
+  # Verification passed
+  local result=$(cat <<EOF
+{
+  "verified": true,
+  "chamber_dir": "$chamber_dir",
+  "hash": "$current_hash"
+}
+EOF
+)
+
+  json_ok "$result"
+}
+
+# List all chambers
+# Arguments:
+#   chambers_root: Root directory containing chambers (default: .aether/chambers/)
+chamber_list() {
+  local chambers_root="${1:-$AETHER_ROOT/.aether/chambers}"
+
+  # Default to current directory's chambers if AETHER_ROOT not set
+  if [[ -z "$chambers_root" || "$chambers_root" == "/.aether/chambers" ]]; then
+    chambers_root="$(pwd)/.aether/chambers"
+  fi
+
+  # Check if chambers directory exists
+  if [[ ! -d "$chambers_root" ]]; then
+    json_ok "[]"
+    return 0
+  fi
+
+  # Build array of chamber summaries
+  local chambers="["
+  local first=true
+
+  # Find all directories in chambers_root
+  while IFS= read -r -d '' chamber_dir; do
+    local chamber_name=$(basename "$chamber_dir")
+    local manifest_file="$chamber_dir/manifest.json"
+
+    # Skip if no manifest
+    [[ ! -f "$manifest_file" ]] && continue
+
+    # Read manifest fields
+    local goal=$(jq -r '.goal // "unknown"' "$manifest_file" 2>/dev/null)
+    local milestone=$(jq -r '.milestone // "unknown"' "$manifest_file" 2>/dev/null)
+    local phases_completed=$(jq -r '.phases_completed // 0' "$manifest_file" 2>/dev/null)
+    local entombed_at=$(jq -r '.entombed_at // ""' "$manifest_file" 2>/dev/null)
+
+    # Escape for JSON
+    goal=$(echo "$goal" | jq -Rs '.[:-1]')
+    milestone=$(echo "$milestone" | jq -Rs '.[:-1]')
+
+    # Add comma if not first
+    if [[ "$first" == "true" ]]; then
+      first=false
+    else
+      chambers+=","
+    fi
+
+    chambers+=$(cat <<EOF
+{
+  "name": $(echo "$chamber_name" | jq -Rs '.[:-1]'),
+  "goal": $goal,
+  "milestone": $milestone,
+  "phases_completed": $phases_completed,
+  "entombed_at": $(echo "$entombed_at" | jq -Rs '.[:-1]')
+}
+EOF
+)
+  done < <(find "$chambers_root" -mindepth 1 -maxdepth 1 -type d -print0 2>/dev/null || true)
+
+  chambers+="]"
+
+  # Sort by entombed_at descending using jq
+  local sorted=$(echo "$chambers" | jq 'sort_by(.entombed_at) | reverse')
+
+  json_ok "$sorted"
+}
+
+# Export functions for use in other scripts
+export -f chamber_sanitize_goal chamber_compute_hash chamber_create chamber_verify chamber_list

package/.aether/utils/colorize-log.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# Colorized activity log stream for tmux watch pane
+# Usage: bash colorize-log.sh [log_file]
+
+LOG_FILE="${1:-.aether/data/activity.log}"
+
+# ANSI color codes by caste (as per V2 improvement plan)
+QUEEN='\033[35m'        # Magenta
+BUILDER='\033[33m'      # Yellow
+WATCHER='\033[36m'      # Cyan
+SCOUT='\033[32m'        # Green
+COLONIZER='\033[34m'    # Blue
+ARCHITECT='\033[37m'    # White
+
+# Action colors (bright variants)
+SPAWN='\033[93m'        # Bright Yellow
+COMPLETE='\033[92m'     # Bright Green
+ERROR='\033[91m'        # Bright Red
+CREATED='\033[96m'      # Bright Cyan
+MODIFIED='\033[94m'     # Bright Blue
+
+# Base colors
+YELLOW='\033[33m'
+GREEN='\033[32m'
+RED='\033[31m'
+CYAN='\033[36m'
+MAGENTA='\033[35m'
+BLUE='\033[34m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+# Get caste color from ant name patterns
+get_caste_color() {
+  case "$1" in
+    *Queen*|*QUEEN*)
+      echo "$QUEEN"
+      ;;
+    *Builder*|*Bolt*|*Hammer*|*Forge*|*Mason*|*Brick*|*Anvil*|*Weld*)
+      echo "$BUILDER"
+      ;;
+    *Watcher*|*Vigil*|*Sentinel*|*Guard*|*Keen*|*Sharp*|*Hawk*|*Watch*|*Alert*)
+      echo "$WATCHER"
+      ;;
+    *Scout*|*Swift*|*Dash*|*Ranger*|*Track*|*Seek*|*Path*|*Roam*|*Quest*)
+      echo "$SCOUT"
+      ;;
+    *Colonizer*|*Pioneer*|*Map*|*Chart*|*Venture*|*Explore*|*Compass*|*Atlas*|*Trek*)
+      echo "$COLONIZER"
+      ;;
+    *Architect*|*Blueprint*|*Draft*|*Design*|*Plan*|*Schema*|*Frame*|*Sketch*|*Model*)
+      echo "$ARCHITECT"
+      ;;
+    *Prime*|*Alpha*|*Lead*|*Chief*|*First*|*Core*|*Apex*|*Crown*)
+      echo "$MAGENTA"
+      ;;
+    *)
+      echo "$RESET"
+      ;;
+  esac
+}
+
+# Get emoji for caste
+get_emoji() {
+  case "$1" in
+    *Queen*|*QUEEN*) echo "👑" ;;
+    *Builder*|*Bolt*|*Hammer*|*Forge*|*Mason*|*Brick*|*Anvil*|*Weld*) echo "🔨" ;;
+    *Watcher*|*Vigil*|*Sentinel*|*Guard*|*Keen*|*Sharp*|*Hawk*|*Watch*|*Alert*) echo "👁️" ;;
+    *Scout*|*Swift*|*Dash*|*Ranger*|*Track*|*Seek*|*Path*|*Roam*|*Quest*) echo "🔍" ;;
+    *Colonizer*|*Pioneer*|*Map*|*Chart*|*Venture*|*Explore*|*Compass*|*Atlas*|*Trek*) echo "🗺️" ;;
+    *Architect*|*Blueprint*|*Draft*|*Design*|*Plan*|*Schema*|*Frame*|*Sketch*|*Model*) echo "🏛️" ;;
+    *Prime*|*Alpha*|*Lead*|*Chief*|*First*|*Core*|*Apex*|*Crown*) echo "👑" ;;
+    *) echo "🐜" ;;
+  esac
+}
+
+# Colony header
+echo -e "${BOLD}${MAGENTA}"
+cat << 'EOF'
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Activity Stream
+       `-`
+EOF
+echo -e "${RESET}"
+echo -e "${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+echo ""
+
+# Stream and colorize log entries
+tail -f "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+  # Extract caste color if ant name is in the line
+  caste_color=$(get_caste_color "$line")
+  emoji=$(get_emoji "$line")
+
+  case "$line" in
+    *SPAWN*)
+      printf "${SPAWN}⚡ %s${RESET}\n" "$line"
+      ;;
+    *COMPLETE*|*completed*)
+      printf "${COMPLETE}✅ %s${RESET}\n" "$line"
+      ;;
+    *ERROR*|*FAILED*|*failed*)
+      printf "${ERROR}${BOLD}❌ %s${RESET}\n" "$line"
+      ;;
+    *CREATED*)
+      printf "${caste_color}✨ %s${RESET}\n" "$line"
+      ;;
+    *MODIFIED*)
+      printf "${caste_color}📝 %s${RESET}\n" "$line"
+      ;;
+    *RESEARCH*|*EXPLORING*)
+      printf "${caste_color}🔬 %s${RESET}\n" "$line"
+      ;;
+    *EXECUTING*|*BUILDING*)
+      printf "${caste_color}⚙️  %s${RESET}\n" "$line"
+      ;;
+    "# Phase"*)
+      # Phase headers get special treatment
+      printf "\n${BOLD}${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n"
+      printf "${BOLD}${MAGENTA}🐜 %s${RESET}\n" "$line"
+      printf "${BOLD}${MAGENTA}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}\n"
+      ;;
+    *)
+      # Apply caste color if detected, otherwise default
+      if [[ "$caste_color" != "$RESET" ]]; then
+        printf "${caste_color}%s %s${RESET}\n" "$emoji" "$line"
+      else
+        echo "$line"
+      fi
+      ;;
+  esac
+done

package/.aether/utils/error-handler.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# Aether Colony Error Handler Module
+# Structured JSON error handling for bash utilities
+#
+# Usage: source "$SCRIPT_DIR/utils/error-handler.sh"
+#
+# Provides consistent error format between Node.js CLI and bash utilities
+
+# --- Error Code Constants (matching Node.js error codes) ---
+E_UNKNOWN="E_UNKNOWN"
+E_HUB_NOT_FOUND="E_HUB_NOT_FOUND"
+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"'; }
+_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() {
+  local code="$1"
+  case "$code" in
+    "$E_HUB_NOT_FOUND") _recovery_hub_not_found ;;
+    "$E_REPO_NOT_INITIALIZED") _recovery_repo_not_init ;;
+    "$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
+}
+
+# --- Enhanced json_err function ---
+# Signature: json_err [code] [message] [details] [recovery]
+# All parameters optional with sensible defaults
+json_err() {
+  local code="${1:-$E_UNKNOWN}"
+  local message="${2:-An unknown error occurred}"
+  local details="${3:-null}"
+  local recovery="${4:-}"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Get recovery suggestion if not provided
+  if [[ -z "$recovery" ]]; then
+    recovery=$(_get_recovery "$code")
+  else
+    # Escape and quote the recovery string
+    recovery=$(echo "$recovery" | sed 's/"/\\"/g' | tr '\n' ' ')
+    recovery="\"$recovery\""
+  fi
+
+  # Escape message for JSON
+  local escaped_message
+  escaped_message=$(echo "$message" | sed 's/"/\\"/g' | tr '\n' ' ')
+
+  # Build details JSON
+  local details_json
+  if [[ "$details" == "null" || -z "$details" ]]; then
+    details_json="null"
+  else
+    details_json="$details"
+  fi
+
+  # Output structured JSON to stderr
+  printf '{"ok":false,"error":{"code":"%s","message":"%s","details":%s,"recovery":%s,"timestamp":"%s"}}\n' \
+    "$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
+  fi
+
+  exit 1
+}
+
+# --- json_warn function for non-fatal warnings ---
+# Signature: json_warn [code] [message]
+json_warn() {
+  local code="${1:-W_UNKNOWN}"
+  local message="${2:-Warning}"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Escape message for JSON
+  local escaped_message
+  escaped_message=$(echo "$message" | sed 's/"/\\"/g' | tr '\n' ' ')
+
+  # Output warning JSON to stdout (not stderr - this is non-fatal)
+  printf '{"ok":true,"warning":{"code":"%s","message":"%s","timestamp":"%s"}}\n' \
+    "$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
+  fi
+}
+
+# --- error_handler function for trap ERR ---
+# Captures: line number, command, exit code
+# Usage: trap 'error_handler ${LINENO} "$BASH_COMMAND" $?' ERR
+error_handler() {
+  local line_num="${1:-unknown}"
+  local command="${2:-unknown}"
+  local exit_code="${3:-1}"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Escape command for JSON
+  local escaped_command
+  escaped_command=$(echo "$command" | sed 's/"/\\"/g' | tr '\n' ' ')
+
+  # Build details JSON
+  local details
+  details="{\"line\":$line_num,\"command\":\"$escaped_command\",\"exit_code\":$exit_code}"
+
+  # Output structured JSON to stderr
+  printf '{"ok":false,"error":{"code":"%s","message":"Bash command failed","details":%s,"recovery":%s,"timestamp":"%s"}}\n' \
+    "$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
+  fi
+
+  exit 1
+}
+
+# --- Feature flag functions for graceful degradation ---
+# Using simple variables for bash 3.2+ compatibility (no associative arrays)
+
+# Track disabled features as colon-separated list: "feature1:reason1|feature2:reason2"
+_FEATURES_DISABLED=""
+
+# Enable a feature (remove from disabled list if present)
+feature_enable() {
+  local name="$1"
+  # Remove from disabled list if present
+  _FEATURES_DISABLED=$(echo "$_FEATURES_DISABLED" | sed "s/:$name:[^|]*//g" | sed 's/^|//;s/|$//')
+}
+
+# Disable a feature with reason
+feature_disable() {
+  local name="$1"
+  local reason="${2:-disabled}"
+  # Remove existing entry if present, then add new
+  _FEATURES_DISABLED=$(echo "$_FEATURES_DISABLED" | sed "s/:$name:[^|]*//g")
+  if [[ -z "$_FEATURES_DISABLED" ]]; then
+    _FEATURES_DISABLED=":$name:$reason"
+  else
+    _FEATURES_DISABLED="${_FEATURES_DISABLED}|:$name:$reason"
+  fi
+}
+
+# Check if feature is enabled (returns 0 if enabled, 1 if disabled)
+feature_enabled() {
+  local name="$1"
+  if echo "$_FEATURES_DISABLED" | grep -q ":$name:"; then
+    return 1
+  fi
+  return 0
+}
+
+# Get reason for feature being disabled
+_feature_reason() {
+  local name="$1"
+  echo "$_FEATURES_DISABLED" | grep -o ":$name:[^|]*" | sed "s/:$name://" || echo "unknown"
+}
+
+# Log degradation warning
+feature_log_degradation() {
+  local name="$1"
+  local reason="${2:-}"
+  if [[ -z "$reason" ]]; then
+    reason=$(_feature_reason "$name")
+  fi
+  json_warn "W_DEGRADED" "Feature '$name' is disabled: $reason"
+}
+
+# --- Export all functions and variables ---
+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_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