aether-colony 1.1.0

package/.aether/utils/spawn-tree.sh

@@ -0,0 +1,428 @@
+#!/bin/bash
+# Spawn Tree Reconstruction Module
+# Parses spawn-tree.txt and provides tree traversal functions
+#
+# Usage: source .aether/utils/spawn-tree.sh
+# All functions output JSON to stdout
+
+# Data directory - can be overridden
+SPAWN_TREE_DATA_DIR="${SPAWN_TREE_DATA_DIR:-.aether/data}"
+SPAWN_TREE_FILE="${SPAWN_TREE_FILE:-$SPAWN_TREE_DATA_DIR/spawn-tree.txt}"
+
+# Parse spawn-tree.txt into structured data
+# Usage: parse_spawn_tree [file_path]
+# Outputs: JSON representation of all spawns
+parse_spawn_tree() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+
+  # Check if file exists
+  if [[ ! -f "$file_path" ]]; then
+    echo '{"spawns":[],"metadata":{"total_count":0,"active_count":0,"completed_count":0,"file_exists":false}}'
+    return 0
+  fi
+
+  # Temporary files for data storage (Bash 3.2 compatible)
+  local tmpdir
+  tmpdir=$(mktemp -d)
+  local names_file="$tmpdir/names"
+  local parents_file="$tmpdir/parents"
+  local castes_file="$tmpdir/castes"
+  local tasks_file="$tmpdir/tasks"
+  local statuses_file="$tmpdir/statuses"
+  local timestamps_file="$tmpdir/timestamps"
+  local completed_file="$tmpdir/completed"
+  local children_file="$tmpdir/children"
+
+  touch "$names_file" "$parents_file" "$castes_file" "$tasks_file" "$statuses_file" "$timestamps_file" "$completed_file" "$children_file"
+
+  # Read file line by line
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    # Skip empty lines
+    [[ -z "$line" ]] && continue
+
+    # Count pipe separators to determine line type
+    local pipe_count
+    pipe_count=$(echo "$line" | tr -cd '|' | wc -c | tr -d ' ')
+
+    if [[ $pipe_count -eq 6 ]]; then
+      # Spawn event: timestamp|parent|caste|child_name|task|model|status
+      local timestamp parent caste child_name task model spawn_status
+      timestamp=$(echo "$line" | cut -d'|' -f1)
+      parent=$(echo "$line" | cut -d'|' -f2)
+      caste=$(echo "$line" | cut -d'|' -f3)
+      child_name=$(echo "$line" | cut -d'|' -f4)
+      task=$(echo "$line" | cut -d'|' -f5)
+      model=$(echo "$line" | cut -d'|' -f6)
+      spawn_status=$(echo "$line" | cut -d'|' -f7)
+
+      # Add to files
+      echo "$child_name" >> "$names_file"
+      echo "$parent" >> "$parents_file"
+      echo "$caste" >> "$castes_file"
+      echo "$task" >> "$tasks_file"
+      echo "$spawn_status" >> "$statuses_file"
+      echo "$timestamp" >> "$timestamps_file"
+      echo "" >> "$completed_file"
+      echo "" >> "$children_file"
+
+    elif [[ $pipe_count -eq 3 ]]; then
+      # Completion event: timestamp|ant_name|status|summary
+      local timestamp ant_name complete_status summary
+      timestamp=$(echo "$line" | cut -d'|' -f1)
+      ant_name=$(echo "$line" | cut -d'|' -f2)
+      complete_status=$(echo "$line" | cut -d'|' -f3)
+
+      # Find the ant and update its status
+      local idx=0
+      local found=0
+      while IFS= read -r name; do
+        if [[ "$name" == "$ant_name" ]]; then
+          found=1
+          break
+        fi
+        ((idx++))
+      done < "$names_file"
+
+      if [[ $found -eq 1 ]]; then
+        # Update status at line idx+1 (sed is 1-indexed)
+        sed -i.bak "${idx}d" "$statuses_file" 2>/dev/null || sed -i "${idx}d" "$statuses_file"
+        sed -i.bak "${idx}i\\
+$complete_status" "$statuses_file" 2>/dev/null || sed -i "${idx}i\\
+$complete_status" "$statuses_file"
+        sed -i.bak "${idx}d" "$completed_file" 2>/dev/null || sed -i "${idx}d" "$completed_file"
+        sed -i.bak "${idx}i\\
+$timestamp" "$completed_file" 2>/dev/null || sed -i "${idx}i\\
+$timestamp" "$completed_file"
+        rm -f "$statuses_file.bak" "$completed_file.bak" 2>/dev/null
+      fi
+    fi
+  done < "$file_path"
+
+  # Build parent-child relationships
+  local total_count
+  total_count=$(wc -l < "$names_file" | tr -d ' ')
+
+  if [[ $total_count -gt 0 ]]; then
+    local i
+    for ((i = 1; i <= total_count; i++)); do
+      local parent
+      parent=$(sed -n "${i}p" "$parents_file")
+
+      # Find parent index
+      local parent_idx=0
+      local found=0
+      while IFS= read -r name; do
+        if [[ "$name" == "$parent" ]]; then
+          found=1
+          break
+        fi
+        ((parent_idx++))
+      done < "$names_file"
+
+      if [[ $found -eq 1 ]]; then
+        # Add child i-1 to parent's children (0-indexed)
+        local child_idx=$((i - 1))
+        local current_children
+        current_children=$(sed -n "$((parent_idx + 1))p" "$children_file")
+        if [[ -z "$current_children" ]]; then
+          sed -i.bak "$((parent_idx + 1))d" "$children_file" 2>/dev/null || sed -i "$((parent_idx + 1))d" "$children_file"
+          sed -i.bak "$((parent_idx + 1))i\\
+$child_idx" "$children_file" 2>/dev/null || sed -i "$((parent_idx + 1))i\\
+$child_idx" "$children_file"
+        else
+          sed -i.bak "$((parent_idx + 1))d" "$children_file" 2>/dev/null || sed -i "$((parent_idx + 1))d" "$children_file"
+          sed -i.bak "$((parent_idx + 1))i\\
+$current_children $child_idx" "$children_file" 2>/dev/null || sed -i "$((parent_idx + 1))i\\
+$current_children $child_idx" "$children_file"
+        fi
+        rm -f "$children_file.bak" 2>/dev/null
+      fi
+    done
+  fi
+
+  # Count statuses
+  local active_count=0
+  local completed_count=0
+  while IFS= read -r status; do
+    if [[ "$status" == "active" || "$status" == "spawned" ]]; then
+      ((active_count++))
+    elif [[ "$status" == "completed" || "$status" == "failed" || "$status" == "blocked" ]]; then
+      ((completed_count++))
+    fi
+  done < "$statuses_file"
+
+  # Build spawns array
+  local spawns_json="["
+  local i
+  for ((i = 1; i <= total_count; i++)); do
+    if [[ $i -gt 1 ]]; then
+      spawns_json+=","
+    fi
+
+    local name parent caste task status timestamp completed children
+    name=$(sed -n "${i}p" "$names_file")
+    parent=$(sed -n "${i}p" "$parents_file")
+    caste=$(sed -n "${i}p" "$castes_file")
+    task=$(sed -n "${i}p" "$tasks_file")
+    status=$(sed -n "${i}p" "$statuses_file")
+    timestamp=$(sed -n "${i}p" "$timestamps_file")
+    completed=$(sed -n "${i}p" "$completed_file")
+    children=$(sed -n "${i}p" "$children_file")
+
+    # Build children array
+    local children_json="["
+    if [[ -n "$children" ]]; then
+      local first_child=true
+      for child_idx in $children; do
+        if [[ "$first_child" == "true" ]]; then
+          first_child=false
+        else
+          children_json+=","
+        fi
+        local child_name
+        child_name=$(sed -n "$((child_idx + 1))p" "$names_file")
+        children_json+="\"$child_name\""
+      done
+    fi
+    children_json+="]"
+
+    # Escape task for JSON
+    task=$(echo "$task" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g')
+
+    spawns_json+="{"
+    spawns_json+="\"name\":\"$name\","
+    spawns_json+="\"parent\":\"$parent\","
+    spawns_json+="\"caste\":\"$caste\","
+    spawns_json+="\"task\":\"$task\","
+    spawns_json+="\"status\":\"$status\","
+    spawns_json+="\"spawned_at\":\"$timestamp\","
+    spawns_json+="\"completed_at\":\"$completed\","
+    spawns_json+="\"children\":$children_json"
+    spawns_json+="}"
+  done
+  spawns_json+="]"
+
+  # Output JSON
+  echo "{"
+  echo "  \"spawns\": $spawns_json,"
+  echo "  \"metadata\": {"
+  echo "    \"total_count\": $total_count,"
+  echo "    \"active_count\": $active_count,"
+  echo "    \"completed_count\": $completed_count,"
+  echo "    \"file_exists\": true"
+  echo "  }"
+  echo "}"
+
+  # Cleanup
+  rm -rf "$tmpdir"
+}
+
+# Get spawn depth for a given ant name
+# Usage: get_spawn_depth <ant_name>
+# Returns: JSON with ant name and depth
+get_spawn_depth() {
+  local ant_name="${1:-}"
+
+  if [[ -z "$ant_name" || "$ant_name" == "Queen" ]]; then
+    echo "{\"ant\":\"${ant_name:-Queen}\",\"depth\":0}"
+    return 0
+  fi
+
+  local file_path="${SPAWN_TREE_FILE}"
+
+  if [[ ! -f "$file_path" ]]; then
+    echo "{\"ant\":\"$ant_name\",\"depth\":1,\"found\":false}"
+    return 0
+  fi
+
+  # Check if ant exists
+  if ! grep -q "|$ant_name|" "$file_path" 2>/dev/null; then
+    echo "{\"ant\":\"$ant_name\",\"depth\":1,\"found\":false}"
+    return 0
+  fi
+
+  # Calculate depth by traversing parent chain
+  local depth=1
+  local current="$ant_name"
+  local safety=0
+
+  while [[ $safety -lt 5 ]]; do
+    # Find who spawned this ant
+    local parent
+    parent=$(grep "|$current|" "$file_path" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+    if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+      break
+    fi
+
+    ((depth++))
+    current="$parent"
+    ((safety++))
+  done
+
+  echo "{\"ant\":\"$ant_name\",\"depth\":$depth,\"found\":true}"
+}
+
+# Get list of active spawns
+# Usage: get_active_spawns [file_path]
+# Returns: JSON array of active spawns
+get_active_spawns() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+
+  if [[ ! -f "$file_path" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  local active_json="["
+  local first=true
+
+  # Read spawn events and check if completed
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" ]] && continue
+
+    local pipe_count
+    pipe_count=$(echo "$line" | tr -cd '|' | wc -c | tr -d ' ')
+
+    if [[ $pipe_count -eq 6 ]]; then
+      # Spawn event: timestamp|parent|caste|child_name|task|model|status
+      local timestamp parent caste child_name task model spawn_status
+      timestamp=$(echo "$line" | cut -d'|' -f1)
+      parent=$(echo "$line" | cut -d'|' -f2)
+      caste=$(echo "$line" | cut -d'|' -f3)
+      child_name=$(echo "$line" | cut -d'|' -f4)
+      task=$(echo "$line" | cut -d'|' -f5)
+      model=$(echo "$line" | cut -d'|' -f6)
+
+      # Check if this ant has a completion event
+      local is_completed=false
+      if grep -q "^[^|]*|$child_name|completed\|^[^|]*|$child_name|failed\|^[^|]*|$child_name|blocked" "$file_path" 2>/dev/null; then
+        is_completed=true
+      fi
+
+      if [[ "$is_completed" == "false" ]]; then
+        if [[ "$first" == "true" ]]; then
+          first=false
+        else
+          active_json+=","
+        fi
+
+        # Escape task for JSON
+        task=$(echo "$task" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g')
+
+        active_json+="{"
+        active_json+="\"name\":\"$child_name\","
+        active_json+="\"caste\":\"$caste\","
+        active_json+="\"parent\":\"$parent\","
+        active_json+="\"task\":\"$task\","
+        active_json+="\"spawned_at\":\"$timestamp\""
+        active_json+="}"
+      fi
+    fi
+  done < "$file_path"
+
+  active_json+="]"
+  echo "$active_json"
+}
+
+# Get direct children of a spawn
+# Usage: get_spawn_children <ant_name> [file_path]
+# Returns: JSON array of child names
+get_spawn_children() {
+  local ant_name="${1:-}"
+  local file_path="${2:-$SPAWN_TREE_FILE}"
+
+  if [[ -z "$ant_name" || ! -f "$file_path" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  local children_json="["
+  local first=true
+
+  # Find all spawns where parent matches
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" ]] && continue
+
+    local pipe_count
+    pipe_count=$(echo "$line" | tr -cd '|' | wc -c | tr -d ' ')
+
+    if [[ $pipe_count -eq 6 ]]; then
+      local parent child_name
+      parent=$(echo "$line" | cut -d'|' -f2)
+      child_name=$(echo "$line" | cut -d'|' -f4)
+
+      if [[ "$parent" == "$ant_name" ]]; then
+        if [[ "$first" == "true" ]]; then
+          first=false
+        else
+          children_json+=","
+        fi
+        children_json+="\"$child_name\""
+      fi
+    fi
+  done < "$file_path"
+
+  children_json+="]"
+  echo "$children_json"
+}
+
+# Get full lineage from ant up to Queen
+# Usage: get_spawn_lineage <ant_name> [file_path]
+# Returns: JSON array from ant up to Queen (inclusive)
+get_spawn_lineage() {
+  local ant_name="${1:-}"
+  local file_path="${2:-$SPAWN_TREE_FILE}"
+
+  if [[ -z "$ant_name" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  if [[ ! -f "$file_path" ]]; then
+    echo "[\"$ant_name\",\"Queen\"]"
+    return 0
+  fi
+
+  # Build lineage array (ant first, then ancestors)
+  local lineage=""
+  local current="$ant_name"
+  local safety=0
+
+  lineage="\"$current\""
+
+  while [[ $safety -lt 5 ]]; do
+    # Find who spawned this ant
+    local parent
+    parent=$(grep "|$current|" "$file_path" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+    if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+      lineage+=",\"Queen\""
+      break
+    fi
+
+    lineage+=",\"$parent\""
+    current="$parent"
+    ((safety++))
+  done
+
+  echo "[$lineage]"
+}
+
+# Reconstruct full tree as JSON
+# Usage: reconstruct_tree_json [file_path]
+# Returns: Complete spawn tree with metadata
+reconstruct_tree_json() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+  parse_spawn_tree "$file_path"
+}
+
+# Export functions if being sourced (Bash 3.2 compatible)
+if [[ "${BASH_SOURCE[0]:-}" != "${0}" ]]; then
+  export -f parse_spawn_tree 2>/dev/null || true
+  export -f get_spawn_depth 2>/dev/null || true
+  export -f get_active_spawns 2>/dev/null || true
+  export -f get_spawn_children 2>/dev/null || true
+  export -f get_spawn_lineage 2>/dev/null || true
+  export -f reconstruct_tree_json 2>/dev/null || true
+fi

package/.aether/utils/spawn-with-model.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Aether Colony Spawn Helper with Model Assignment
+# Usage: spawn-with-model.sh <caste> <task_description> [project_root]
+#
+# This script sets up the correct environment variables for model routing
+# through the LiteLLM proxy before spawning Claude Code.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AETHER_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Arguments
+CASTE="${1:-}"
+TASK="${2:-}"
+PROJECT_ROOT="${3:-$AETHER_ROOT}"
+
+# Validate arguments
+[[ -z "$CASTE" ]] && { echo "Usage: spawn-with-model.sh <caste> <task_description> [project_root]" >&2; exit 1; }
+[[ -z "$TASK" ]] && { echo "Usage: spawn-with-model.sh <caste> <task_description> [project_root]" >&2; exit 1; }
+
+# Get model for this caste
+model_info=$(bash "$AETHER_ROOT/.aether/aether-utils.sh" model-profile get "$CASTE" 2>/dev/null || echo '{"ok":true,"result":{"model":"kimi-k2.5"}}')
+model=$(echo "$model_info" | jq -r '.result.model // "kimi-k2.5"')
+
+# Log the spawn with model
+ant_name=$(bash "$AETHER_ROOT/.aether/aether-utils.sh" generate-ant-name "$CASTE" 2>/dev/null || echo "${CASTE}-$(date +%s)")
+bash "$AETHER_ROOT/.aether/aether-utils.sh" spawn-log "Queen" "$CASTE" "$ant_name" "$TASK" 2>/dev/null || true
+bash "$AETHER_ROOT/.aether/aether-utils.sh" activity-log "SPAWN" "$ant_name ($CASTE)" "Model: $model - $TASK" 2>/dev/null || true
+
+# Export environment for Claude Code
+export ANTHROPIC_BASE_URL="${ANTHROPIC_BASE_URL:-http://localhost:4000}"
+export ANTHROPIC_AUTH_TOKEN="${ANTHROPIC_AUTH_TOKEN:-sk-litellm-local}"
+export ANTHROPIC_MODEL="$model"
+
+echo "[$(date '+%H:%M:%S')] Spawning $ant_name ($CASTE) with model: $model"
+echo "  Task: $TASK"
+echo "  Project: $PROJECT_ROOT"
+
+# Check proxy health
+if curl -s http://localhost:4000/health | grep -q "healthy" 2>/dev/null; then
+    echo "  Proxy: healthy"
+else
+    echo "  Proxy: unavailable (will use default routing)"
+fi
+
+# Start Claude Code with the environment set
+# Note: This assumes claude is in PATH
+if command -v claude &> /dev/null; then
+    claude --cwd "$PROJECT_ROOT"
+else
+    echo "Claude Code not found in PATH. Environment prepared:"
+    echo "  ANTHROPIC_BASE_URL=$ANTHROPIC_BASE_URL"
+    echo "  ANTHROPIC_MODEL=$ANTHROPIC_MODEL"
+    exit 0
+fi

package/.aether/utils/state-loader.sh

@@ -0,0 +1,215 @@
+#!/bin/bash
+# Aether Colony State Loader
+# Loads and validates COLONY_STATE.json with file lock protection
+#
+# Usage:
+#   source .aether/utils/state-loader.sh
+#   load_colony_state
+#   # ... use state ...
+#   unload_colony_state
+#
+# Provides: load_colony_state, unload_colony_state, get_handoff_summary, display_resumption_context
+
+# 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
+
+SCRIPT_DIR="${SCRIPT_DIR:-$AETHER_ROOT/.aether}"
+DATA_DIR="$AETHER_ROOT/.aether/data"
+
+# Initialize lock state before sourcing (file-lock.sh trap needs these)
+LOCK_ACQUIRED=${LOCK_ACQUIRED:-false}
+CURRENT_LOCK=${CURRENT_LOCK:-""}
+
+# Source shared infrastructure if available
+[[ -f "$SCRIPT_DIR/utils/file-lock.sh" ]] && source "$SCRIPT_DIR/utils/file-lock.sh"
+[[ -f "$SCRIPT_DIR/utils/error-handler.sh" ]] && source "$SCRIPT_DIR/utils/error-handler.sh"
+
+# State loading globals
+LOADED_STATE=""
+STATE_LOCK_ACQUIRED=false
+HANDOFF_DETECTED=false
+HANDOFF_CONTENT=""
+
+# --- load_colony_state ---
+# Main loading function that acquires lock, validates, and loads state
+# Returns: 0 on success, 1 on failure
+# Exports: LOADED_STATE, STATE_LOCK_ACQUIRED, HANDOFF_DETECTED, HANDOFF_CONTENT
+load_colony_state() {
+    local state_file="$DATA_DIR/COLONY_STATE.json"
+
+    # Check file exists
+    if [[ ! -f "$state_file" ]]; then
+        if type json_err &>/dev/null; then
+            json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}' "Run /ant:init to initialize colony"
+        else
+            echo '{"ok":false,"error":{"code":"E_FILE_NOT_FOUND","message":"COLONY_STATE.json not found"}}' >&2
+        fi
+        return 1
+    fi
+
+    # Acquire lock
+    if type acquire_lock &>/dev/null; then
+        if ! acquire_lock "$state_file"; then
+            if type json_err &>/dev/null; then
+                json_err "$E_LOCK_FAILED" "Failed to acquire state lock" '{"file":"COLONY_STATE.json"}' "Wait for other operations to complete"
+            else
+                echo '{"ok":false,"error":{"code":"E_LOCK_FAILED","message":"Failed to acquire state lock"}}' >&2
+            fi
+            return 1
+        fi
+    else
+        # Locking unavailable - proceed with warning
+        if type json_warn &>/dev/null; then
+            json_warn "W_DEGRADED" "File locking unavailable - proceeding without lock"
+        fi
+    fi
+
+    # Validate state before loading
+    local validation
+    validation=$(bash "$SCRIPT_DIR/aether-utils.sh" validate-state colony 2>/dev/null)
+    if ! echo "$validation" | jq -e '.result.pass' >/dev/null 2>&1; then
+        # Validation failed - release lock and report error
+        if type release_lock &>/dev/null; then
+            release_lock
+        fi
+
+        local validation_error
+        validation_error=$(echo "$validation" | jq -r '.result.checks[] | select(. != "pass") | .' 2>/dev/null | head -1 || echo "unknown validation error")
+
+        if type json_err &>/dev/null; then
+            json_err "$E_VALIDATION_FAILED" "State validation failed" "{\"details\":\"$validation_error\"}" "Check COLONY_STATE.json for errors or run /ant:init to reset"
+        else
+            echo "{\"ok\":false,\"error\":{\"code\":\"E_VALIDATION_FAILED\",\"message\":\"State validation failed: $validation_error\"}}" >&2
+        fi
+        return 1
+    fi
+
+    # Read state into variable
+    local state
+    state=$(cat "$state_file")
+    if [[ -z "$state" ]]; then
+        if type release_lock &>/dev/null; then
+            release_lock
+        fi
+        if type json_err &>/dev/null; then
+            json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json is empty" '{"file":"COLONY_STATE.json"}' "Run /ant:init to initialize colony"
+        else
+            echo '{"ok":false,"error":{"code":"E_FILE_NOT_FOUND","message":"COLONY_STATE.json is empty"}}' >&2
+        fi
+        return 1
+    fi
+
+    # Check for handoff document
+    local handoff_file="$AETHER_ROOT/.aether/HANDOFF.md"
+    if [[ -f "$handoff_file" ]]; then
+        HANDOFF_DETECTED=true
+        HANDOFF_CONTENT=$(cat "$handoff_file")
+    else
+        HANDOFF_DETECTED=false
+        HANDOFF_CONTENT=""
+    fi
+
+    # Export loaded state
+    LOADED_STATE="$state"
+    STATE_LOCK_ACQUIRED=true
+
+    return 0
+}
+
+# --- unload_colony_state ---
+# Cleanup function that releases lock and unsets state
+# Should be called when done with state
+unload_colony_state() {
+    if [[ "$STATE_LOCK_ACQUIRED" == "true" ]]; then
+        if type release_lock &>/dev/null; then
+            release_lock
+        fi
+        STATE_LOCK_ACQUIRED=false
+    fi
+    LOADED_STATE=""
+    HANDOFF_DETECTED=false
+    HANDOFF_CONTENT=""
+}
+
+# --- get_handoff_summary ---
+# Extract brief summary from handoff content
+# Returns: "Phase X - Name" format or empty string
+get_handoff_summary() {
+    if [[ "$HANDOFF_DETECTED" != "true" || -z "$HANDOFF_CONTENT" ]]; then
+        echo ""
+        return 1
+    fi
+
+    # Parse HANDOFF.md for Phase line
+    # Format: "Phase: X - Name" or "## Phase X: Name"
+    local phase_line
+    phase_line=$(echo "$HANDOFF_CONTENT" | grep -E "^(Phase:|## Phase)" | head -1)
+
+    if [[ -n "$phase_line" ]]; then
+        # Extract phase number and name
+        local phase_num
+        local phase_name
+        phase_num=$(echo "$phase_line" | grep -oE "[0-9]+" | head -1)
+        phase_name=$(echo "$phase_line" | sed -E 's/.*Phase:?[[:space:]]*[0-9]+[[:space:]-]+//' | sed 's/^[[:space:]]*//')
+
+        if [[ -n "$phase_num" && -n "$phase_name" ]]; then
+            echo "Phase $phase_num - $phase_name"
+        elif [[ -n "$phase_num" ]]; then
+            echo "Phase $phase_num"
+        else
+            echo "Resuming colony session"
+        fi
+    else
+        echo "Resuming colony session"
+    fi
+}
+
+# --- display_resumption_context ---
+# Show brief resume message and clean up handoff
+# Returns: 0 on success
+display_resumption_context() {
+    if [[ "$HANDOFF_DETECTED" != "true" ]]; then
+        return 0
+    fi
+
+    local summary
+    summary=$(get_handoff_summary)
+
+    if [[ -n "$summary" ]]; then
+        echo "Resuming: $summary"
+    fi
+
+    # Remove handoff file after successful display
+    local handoff_file="$AETHER_ROOT/.aether/HANDOFF.md"
+    if [[ -f "$handoff_file" ]]; then
+        rm -f "$handoff_file"
+    fi
+
+    HANDOFF_DETECTED=false
+    HANDOFF_CONTENT=""
+
+    return 0
+}
+
+# --- ensure_cleanup ---
+# Internal function to ensure lock is released on script exit
+_ensure_cleanup() {
+    if [[ "$STATE_LOCK_ACQUIRED" == "true" ]]; then
+        unload_colony_state
+    fi
+}
+
+# Register cleanup on exit
+# Note: This works alongside file-lock.sh's trap
+_original_trap_exit() {
+    _ensure_cleanup
+}
+
+# Export functions for use in other scripts
+export -f load_colony_state unload_colony_state get_handoff_summary display_resumption_context
+export -f _ensure_cleanup _original_trap_exit
+export LOADED_STATE STATE_LOCK_ACQUIRED HANDOFF_DETECTED HANDOFF_CONTENT