aether-colony 2.0.0

package/runtime/utils/atomic-write.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# Aether Atomic Write Utility
+# Implements atomic write pattern (temp file + rename) for corruption safety
+#
+# Usage:
+#   source ~/.aether/utils/atomic-write.sh
+#   atomic_write /path/to/file.json "content"
+#   atomic_write_from_file /path/to/target.json /path/to/temp.json
+
+# Source required utilities
+# Get the directory where this script is located
+_AETHER_UTILS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# If BASH_SOURCE[0] is empty (can happen in some contexts), use relative path
+if [ -z "$_AETHER_UTILS_DIR" ] || [ "$_AETHER_UTILS_DIR" = "$(pwd)" ]; then
+    _AETHER_UTILS_DIR="$HOME/.aether/utils"
+fi
+# Verify the path exists and file-lock.sh is there
+if [ ! -f "$_AETHER_UTILS_DIR/file-lock.sh" ]; then
+    # Try one more fallback - relative to script location
+    _AETHER_UTILS_DIR="$(dirname "${BASH_SOURCE[0]}")"
+fi
+source "$_AETHER_UTILS_DIR/file-lock.sh"
+
+# 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)"
+fi
+
+TEMP_DIR="$AETHER_ROOT/.aether/temp"
+BACKUP_DIR="$AETHER_ROOT/.aether/data/backups"
+
+# Create directories
+mkdir -p "$TEMP_DIR" "$BACKUP_DIR"
+
+# Number of backups to keep
+MAX_BACKUPS=3
+
+# Atomic write: write content to file via temporary file
+# Arguments: target_file, content
+# Returns: 0 on success, 1 on failure
+atomic_write() {
+    local target_file="$1"
+    local content="$2"
+
+    # Ensure target directory exists
+    local target_dir=$(dirname "$target_file")
+    mkdir -p "$target_dir"
+
+    # Create unique temp file
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+
+    # Write content to temp file
+    if ! echo "$content" > "$temp_file"; then
+        echo "Failed to write to temp file: $temp_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Validate JSON if it's a JSON file
+    if [[ "$target_file" == *.json ]]; then
+        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+            echo "Invalid JSON in temp file: $temp_file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    fi
+
+    # Create backup if target exists
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
+    # Atomic rename (overwrites target if exists)
+    if ! mv "$temp_file" "$target_file"; then
+        echo "Failed to rename temp file to target: $target_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Sync to disk
+    if command -v sync >/dev/null 2>&1; then
+        sync "$target_file" 2>/dev/null || true
+    fi
+
+    return 0
+}
+
+# Atomic write from source file to target
+# Arguments: target_file, source_file
+# Returns: 0 on success, 1 on failure
+atomic_write_from_file() {
+    local target_file="$1"
+    local source_file="$2"
+
+    if [ ! -f "$source_file" ]; then
+        echo "Source file does not exist: $source_file"
+        return 1
+    fi
+
+    # Ensure target directory exists
+    local target_dir=$(dirname "$target_file")
+    mkdir -p "$target_dir"
+
+    # Create unique temp file
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+
+    # Copy source to temp
+    if ! cp "$source_file" "$temp_file"; then
+        echo "Failed to copy source to temp: $source_file -> $temp_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Validate JSON if it's a JSON file
+    if [[ "$target_file" == *.json ]]; then
+        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+            echo "Invalid JSON in temp file: $temp_file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    fi
+
+    # Create backup if target exists
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
+    # Atomic rename
+    if ! mv "$temp_file" "$target_file"; then
+        echo "Failed to rename temp file to target: $target_file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    # Sync to disk
+    if command -v sync >/dev/null 2>&1; then
+        sync "$target_file" 2>/dev/null || true
+    fi
+
+    return 0
+}
+
+# Create backup of file
+# Arguments: file_path
+create_backup() {
+    local file_path="$1"
+    local base_name=$(basename "$file_path")
+    local timestamp=$(date +%Y%m%d_%H%M%S)
+    local backup_file="${BACKUP_DIR}/${base_name}.${timestamp}.backup"
+
+    cp "$file_path" "$backup_file" 2>/dev/null || return 1
+
+    # Rotate old backups
+    rotate_backups "$base_name"
+
+    return 0
+}
+
+# Rotate backups, keeping only MAX_BACKUPS
+# Arguments: base_name
+rotate_backups() {
+    local base_name="$1"
+    local backups=$(ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null | wc -l)
+
+    if [ "$backups" -gt "$MAX_BACKUPS" ]; then
+        ls -t "${BACKUP_DIR}/${base_name}".*.backup | tail -n +$((MAX_BACKUPS + 1)) | xargs rm -f
+    fi
+}
+
+# Restore from backup
+# Arguments: target_file, [backup_number]
+# Returns: 0 on success, 1 on failure
+restore_backup() {
+    local target_file="$1"
+    local backup_num="${2:-1}"  # Default to most recent backup
+    local base_name=$(basename "$target_file")
+
+    local backup_file=$(ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null | sed -n "${backup_num}p")
+
+    if [ -z "$backup_file" ] || [ ! -f "$backup_file" ]; then
+        echo "No backup found for: $target_file"
+        return 1
+    fi
+
+    if ! atomic_write_from_file "$target_file" "$backup_file"; then
+        echo "Failed to restore from backup: $backup_file"
+        return 1
+    fi
+
+    echo "Restored from: $backup_file"
+    return 0
+}
+
+# List available backups
+# Arguments: file_path
+list_backups() {
+    local file_path="$1"
+    local base_name=$(basename "$file_path")
+
+    echo "Available backups for $base_name:"
+    ls -lh "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null || echo "No backups found"
+}
+
+# Cleanup temp files older than 1 hour
+cleanup_temp_files() {
+    find "$TEMP_DIR" -name "*.tmp" -mtime +1/24 -delete 2>/dev/null || true
+}
+
+# Export functions
+export -f atomic_write atomic_write_from_file create_backup rotate_backups
+export -f restore_backup list_backups cleanup_temp_files

package/runtime/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/runtime/utils/file-lock.sh

@@ -0,0 +1,122 @@
+#!/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 /path/to/file.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)"
+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
+
+# Create lock directory if it doesn't exist
+mkdir -p "$LOCK_DIR"
+
+# Acquire a file lock using flock
+# Arguments: file_path (the resource to lock)
+# Returns: 0 on success, 1 on failure
+# Globals: LOCK_ACQUIRED (set to true when lock acquired)
+acquire_lock() {
+    local file_path="$1"
+    local lock_file="${LOCK_DIR}/$(basename "$file_path").lock"
+    local lock_pid_file="${lock_file}.pid"
+
+    # 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"
+            fi
+        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"
+            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"
+    return 1
+}
+
+# Release a file lock
+# Arguments: None (uses CURRENT_LOCK from 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
+}
+
+# Cleanup function for script exit
+cleanup_locks() {
+    if [ "$LOCK_ACQUIRED" = "true" ]; then
+        release_lock
+    fi
+}
+
+# Register cleanup on exit
+trap cleanup_locks EXIT TERM INT
+
+# 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 is_locked get_lock_holder wait_for_lock cleanup_locks

package/runtime/utils/watch-spawn-tree.sh

@@ -0,0 +1,185 @@
+#!/bin/bash
+# Live spawn tree visualization for tmux watch pane
+# Usage: bash watch-spawn-tree.sh [data_dir]
+
+DATA_DIR="${1:-.aether/data}"
+SPAWN_FILE="$DATA_DIR/spawn-tree.txt"
+
+# ANSI colors
+YELLOW='\033[33m'
+GREEN='\033[32m'
+RED='\033[31m'
+CYAN='\033[36m'
+MAGENTA='\033[35m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+# Caste emojis
+get_emoji() {
+  case "$1" in
+    builder)   echo "🔨" ;;
+    watcher)   echo "👁️ " ;;
+    scout)     echo "🔍" ;;
+    colonizer) echo "🗺️ " ;;
+    architect) echo "🏛️ " ;;
+    prime)     echo "👑" ;;
+    *)         echo "🐜" ;;
+  esac
+}
+
+# Status colors
+get_status_color() {
+  case "$1" in
+    completed) echo "$GREEN" ;;
+    failed)    echo "$RED" ;;
+    spawned)   echo "$YELLOW" ;;
+    *)         echo "$CYAN" ;;
+  esac
+}
+
+render_tree() {
+  clear
+
+  # Header
+  echo -e "${BOLD}${CYAN}"
+  cat << 'EOF'
+       .-.
+      (o o)  AETHER COLONY
+      | O |  Spawn Tree
+       `-`
+EOF
+  echo -e "${RESET}"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo ""
+
+  # Always show Queen at depth 0
+  echo -e "  ${BOLD}👑 Queen${RESET} ${DIM}(depth 0)${RESET}"
+  echo -e "  ${DIM}│${RESET}"
+
+  if [[ ! -f "$SPAWN_FILE" ]]; then
+    echo -e "  ${DIM}└── (no workers spawned yet)${RESET}"
+    return
+  fi
+
+  # Parse spawn tree file
+  # Format: timestamp|parent_id|child_caste|child_name|task_summary|status
+  declare -A workers
+  declare -A worker_status
+  declare -A worker_task
+  declare -A worker_caste
+  declare -a roots
+
+  while IFS='|' read -r ts parent caste name task status rest; do
+    [[ -z "$name" ]] && continue
+
+    # Check if this is a status update (only 4 fields)
+    if [[ -z "$task" && -n "$caste" ]]; then
+      # This is a status update: ts|name|status|summary
+      worker_status["$parent"]="$caste"
+      continue
+    fi
+
+    workers["$name"]="$parent"
+    worker_caste["$name"]="$caste"
+    worker_task["$name"]="$task"
+    worker_status["$name"]="${status:-spawned}"
+
+    # Track root workers (spawned by Prime or Queen)
+    if [[ "$parent" == "Prime"* || "$parent" == "prime"* || "$parent" == "Queen" ]]; then
+      roots+=("$name")
+    fi
+  done < "$SPAWN_FILE"
+
+  # Render workers in tree structure
+  # Group by parent to show hierarchy
+  printed=()
+
+  # Function to render a worker and its children
+  render_worker() {
+    local name="$1"
+    local indent="$2"
+    local depth="$3"
+    local is_last="$4"
+
+    [[ " ${printed[*]} " =~ " $name " ]] && return
+    printed+=("$name")
+
+    emoji=$(get_emoji "${worker_caste[$name]}")
+    status="${worker_status[$name]}"
+    color=$(get_status_color "$status")
+    task="${worker_task[$name]}"
+
+    # Truncate task for display
+    [[ ${#task} -gt 30 ]] && task="${task:0:27}..."
+
+    # Tree connectors
+    if [[ "$is_last" == "true" ]]; then
+      connector="└──"
+    else
+      connector="├──"
+    fi
+
+    echo -e "${indent}${DIM}${connector}${RESET} ${emoji} ${color}${name}${RESET}: ${task} ${DIM}[depth $depth]${RESET}"
+
+    # Find children of this worker
+    local children=()
+    for child in "${!workers[@]}"; do
+      if [[ "${workers[$child]}" == "$name" ]]; then
+        children+=("$child")
+      fi
+    done
+
+    # Render children
+    local child_indent="${indent}    "
+    if [[ "$is_last" != "true" ]]; then
+      child_indent="${indent}${DIM}│${RESET}   "
+    fi
+
+    local child_count=${#children[@]}
+    local child_idx=0
+    for child in "${children[@]}"; do
+      child_idx=$((child_idx + 1))
+      local child_is_last="false"
+      [[ $child_idx -eq $child_count ]] && child_is_last="true"
+      render_worker "$child" "$child_indent" $((depth + 1)) "$child_is_last"
+    done
+  }
+
+  # Render root workers (spawned by Queen) at depth 1
+  local root_count=${#roots[@]}
+  local root_idx=0
+  for name in "${roots[@]}"; do
+    root_idx=$((root_idx + 1))
+    local is_last="false"
+    [[ $root_idx -eq $root_count ]] && is_last="true"
+    render_worker "$name" "  " 1 "$is_last"
+  done
+
+  # Summary
+  echo ""
+  echo -e "${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  completed=$(grep -c "completed" "$SPAWN_FILE" 2>/dev/null || echo "0")
+  active=$(grep -c "spawned" "$SPAWN_FILE" 2>/dev/null || echo "0")
+  echo -e "Workers: ${GREEN}$completed completed${RESET} | ${YELLOW}$active active${RESET}"
+}
+
+# Initial render
+render_tree
+
+# Watch for changes and re-render
+if command -v fswatch &>/dev/null; then
+  fswatch -o "$SPAWN_FILE" 2>/dev/null | while read; do
+    render_tree
+  done
+elif command -v inotifywait &>/dev/null; then
+  while inotifywait -q -e modify "$SPAWN_FILE" 2>/dev/null; do
+    render_tree
+  done
+else
+  # Fallback: poll every 2 seconds
+  while true; do
+    sleep 2
+    render_tree
+  done
+fi