aether-colony 5.0.0 → 5.1.0

package/.aether/utils/spawn.sh

@@ -0,0 +1,260 @@
+#!/bin/bash
+# Spawn utility functions — extracted from aether-utils.sh
+# Provides: _spawn_log, _spawn_complete, _spawn_can_spawn, _spawn_get_depth, _spawn_can_spawn_swarm, _spawn_tree_load, _spawn_tree_active, _spawn_tree_depth, _spawn_efficiency
+#
+# 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.
+# Note: get_caste_emoji is defined in the main file and available to this module at call time.
+
+_spawn_log() {
+    # Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]
+    parent_id="${1:-}"
+    child_caste="${2:-}"
+    child_name="${3:-}"
+    task_summary="${4:-}"
+    model="${5:-default}"
+    status="${6:-spawned}"
+    # Model slot resolution removed (archived: .aether/archive/model-routing/)
+    # Agent frontmatter model: fields handle routing natively via Claude Code.
+    [[ "$model" == "default" ]] && model="inherit"
+    [[ -z "$parent_id" || -z "$child_caste" || -z "$task_summary" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]"
+    mkdir -p "$COLONY_DATA_DIR"
+    ts=$(date -u +"%H:%M:%S")
+    ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    emoji=$(get_caste_emoji "$child_caste")
+    parent_emoji=$(get_caste_emoji "$parent_id")
+    # Log to activity log with spawn format, emojis, and model info
+    echo "[$ts] ⚡ SPAWN $parent_emoji $parent_id -> $emoji $child_name ($child_caste): $task_summary [model: $model]" >> "$COLONY_DATA_DIR/activity.log"
+    # Log to spawn tree file for visualization (NEW FORMAT: includes model field)
+    echo "$ts_full|$parent_id|$child_caste|$child_name|$task_summary|$model|$status" >> "$COLONY_DATA_DIR/spawn-tree.txt"
+    # Return emoji-formatted result for display (jq-safe: child_name may contain JSON-special chars)
+    json_ok "$(jq -n --arg msg "⚡ $emoji $child_name spawned" '$msg')"
+}
+
+_spawn_complete() {
+    # Migrated to state-api facade: uses _state_mutate for failed spawn event logging
+    # Usage: spawn-complete <ant_name> <status> [summary]
+    ant_name="${1:-}"
+    status="${2:-completed}"
+    summary="${3:-}"
+    [[ -z "$ant_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-complete <ant_name> <status> [summary]"
+    mkdir -p "$COLONY_DATA_DIR"
+    ts=$(date -u +"%H:%M:%S")
+    ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    emoji=$(get_caste_emoji "$ant_name")
+    status_icon="✅"
+    [[ "$status" == "failed" ]] && status_icon="❌"
+    [[ "$status" == "blocked" ]] && status_icon="🚫"
+    echo "[$ts] $status_icon $emoji $ant_name: $status${summary:+ - $summary}" >> "$COLONY_DATA_DIR/activity.log"
+    # Update spawn tree
+    echo "$ts_full|$ant_name|$status|$summary" >> "$COLONY_DATA_DIR/spawn-tree.txt"
+    # Log failed spawns to events array as pipe-delimited strings (matching template format)
+    if [[ "$status" == "failed" ]] || [[ "$status" == "error" ]]; then
+      if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+        SC_EVENT="$ts_full|spawn_failed|$ant_name|${summary:-unknown}" \
+          _state_mutate '
+            .events += [env.SC_EVENT]
+          ' >/dev/null 2>&1 || _aether_log_error "Failed to log spawn failure to colony state"
+      fi
+    fi
+    # Return emoji-formatted result for display (jq-safe: ant_name/summary may contain JSON-special chars)
+    json_ok "$(jq -n --arg msg "$status_icon $emoji $ant_name: ${summary:-$status}" '$msg')"
+}
+
+_spawn_can_spawn() {
+    # Check if spawning is allowed at given depth
+    # Usage: spawn-can-spawn [depth] [--enforce]
+    # Returns: {can_spawn: bool, depth: N, max_spawns: N, current_total: N, global_cap: N}
+    # --enforce: fail with non-zero exit when spawning is not allowed
+    depth=""
+    enforce_mode=false
+    for arg in "$@"; do
+      case "$arg" in
+        --enforce) enforce_mode=true ;;
+        *)
+          if [[ -z "$depth" ]]; then
+            depth="$arg"
+          else
+            json_err "$E_VALIDATION_FAILED" "Usage: spawn-can-spawn [depth] [--enforce]"
+          fi
+          ;;
+      esac
+    done
+    [[ -z "$depth" ]] && depth=1
+    [[ "$depth" =~ ^[0-9]+$ ]] || json_err "$E_VALIDATION_FAILED" "Depth must be a non-negative integer" "{\"provided\":\"$depth\"}"
+
+    # Depth limits: 1→4 spawns, 2→2 spawns, 3+→0 spawns
+    if [[ $depth -eq 1 ]]; then
+      max_for_depth=4
+    elif [[ $depth -eq 2 ]]; then
+      max_for_depth=2
+    else
+      max_for_depth=0
+    fi
+
+    # Count current spawns in this session (from spawn-tree.txt)
+    current=0
+    if [[ -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      current=$(grep -c "|spawned$" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+    fi
+
+    # Global cap of 10 workers per phase
+    global_cap=10
+
+    # Can spawn if: depth < 3 AND under global cap
+    if [[ $depth -lt 3 && $current -lt $global_cap ]]; then
+      can="true"
+    else
+      can="false"
+    fi
+
+    if [[ "$enforce_mode" == "true" && "$can" == "false" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Spawn cap exceeded: depth=$depth current=$current max=$global_cap"
+    fi
+
+    json_ok "{\"can_spawn\":$can,\"depth\":$depth,\"max_spawns\":$max_for_depth,\"current_total\":$current,\"global_cap\":$global_cap}"
+}
+
+_spawn_get_depth() {
+    # Return depth for a given ant name by tracing spawn tree
+    # Usage: spawn-get-depth <ant_name>
+    # Queen = depth 0, Queen's spawns = depth 1, their spawns = depth 2, etc.
+    ant_name="${1:-Queen}"
+
+    if [[ "$ant_name" == "Queen" ]]; then
+      json_ok '{"ant":"Queen","depth":0}'
+      exit 0
+    fi
+
+    # Check if spawn tree exists
+    if [[ ! -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      json_ok "$(jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}')"
+      exit 0
+    fi
+
+    # Check if ant exists in spawn tree (gracefully handle missing ants)
+    if ! grep -qF "|$ant_name|" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null; then  # SUPPRESS:OK -- existence-test: file may not exist; -F: ant_name may contain regex metacharacters
+      json_ok "$(jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}')"
+      exit 0
+    fi
+
+    # Find the spawn record for this ant and trace parents
+    depth=1
+    current_ant="$ant_name"
+
+    # Find who spawned this ant (look for lines with |spawned)
+    while true; do
+      # Format: timestamp|parent|caste|child_name|task|spawned
+      # SUPPRESS:OK -- read-default: returns fallback on failure
+      parent=$(grep -F "|$current_ant|" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+      if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+        break
+      fi
+
+      depth=$((depth + 1))
+      current_ant="$parent"
+
+      # Safety limit
+      if [[ $depth -gt 5 ]]; then
+        break
+      fi
+    done
+
+    json_ok "$(jq -n --arg ant "$ant_name" --argjson depth "$depth" '{ant: $ant, depth: $depth, found: true}')"
+}
+
+_spawn_can_spawn_swarm() {
+    # Check if swarm can spawn more scouts (separate from phase workers)
+    # Usage: spawn-can-spawn-swarm <swarm_id>
+    # Swarm has its own cap of 6 (4 scouts + 2 sub-scouts max)
+    swarm_id="${1:-swarm}"
+    swarm_cap=6
+
+    current=0
+    if [[ -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      # SUPPRESS:OK -- existence-test: grep returns 1 when no matches
+      # -F: swarm_id may contain regex metacharacters; anchor $ dropped (swarm_id is unique, no substring collision risk)
+      current=$(grep -cF "|swarm:$swarm_id" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null) || current=0
+    fi
+
+    if [[ $current -lt $swarm_cap ]]; then
+      can="true"
+      remaining=$((swarm_cap - current))
+    else
+      can="false"
+      remaining=0
+    fi
+
+    json_ok "$(jq -n --argjson can_spawn "$can" --argjson current "$current" \
+      --argjson cap "$swarm_cap" --argjson remaining "$remaining" --arg swarm_id "$swarm_id" \
+      '{can_spawn: $can_spawn, current: $current, cap: $cap, remaining: $remaining, swarm_id: $swarm_id}')"
+}
+
+_spawn_tree_load() {
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    tree_json=$(reconstruct_tree_json)
+    if echo "$tree_json" | jq -e . >/dev/null 2>&1; then
+      json_ok "$tree_json"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn tree reconstruction produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_tree_active() {
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    active=$(get_active_spawns)
+    if echo "$active" | jq -e . >/dev/null 2>&1; then
+      json_ok "$active"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn-tree active produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_tree_depth() {
+    ant_name="${1:-}"
+    [[ -z "$ant_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-tree-depth <ant_name>"
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    depth=$(get_spawn_depth "$ant_name")
+    if echo "$depth" | jq -e . >/dev/null 2>&1; then
+      json_ok "$depth"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn-tree depth produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_efficiency() {
+    # Calculate spawn efficiency metrics from spawn-tree.txt
+    # Usage: spawn-efficiency
+    spawn_tree_file="$COLONY_DATA_DIR/spawn-tree.txt"
+    total=0
+    completed=0
+    failed=0
+
+    if [[ -f "$spawn_tree_file" ]]; then
+      total=$(grep -c "|spawned$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+      completed=$(grep -c "|completed$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+      failed=$(grep -c "|failed$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+    fi
+
+    if [[ "$total" -gt 0 ]]; then
+      efficiency=$(( completed * 100 / total ))
+    else
+      efficiency=0
+    fi
+
+    json_ok "{\"total\":$total,\"completed\":$completed,\"failed\":$failed,\"efficiency_pct\":$efficiency}"
+}

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

@@ -0,0 +1,199 @@
+#!/bin/bash
+# State API facade -- centralized COLONY_STATE.json access
+# Provides: _state_read, _state_write, _state_read_field, _state_mutate, _state_migrate
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, acquire_lock,
+# release_lock, LOCK_DIR, DATA_DIR, SCRIPT_DIR, error constants) is available.
+
+_state_read() {
+    # Read full COLONY_STATE.json and return via json_ok
+    # Usage: state-read
+    # No lock needed for reads (jq is atomic on single files)
+    # Returns: json_ok with full state, or json_err on missing/invalid file
+
+    sr_state_file="$DATA_DIR/COLONY_STATE.json"
+
+    if [[ ! -f "$sr_state_file" ]]; then
+        json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
+    fi
+
+    sr_content=$(cat "$sr_state_file" 2>/dev/null) || {
+        json_err "$E_FILE_NOT_FOUND" "Failed to read COLONY_STATE.json"
+    }
+
+    if ! echo "$sr_content" | jq -e . >/dev/null 2>&1; then
+        json_err "$E_JSON_INVALID" "COLONY_STATE.json contains invalid JSON"
+    fi
+
+    json_ok "$sr_content"
+}
+
+_state_read_field() {
+    # Read a specific jq field path from COLONY_STATE.json
+    # Usage: state-read-field <jq_path>
+    # For internal callers: outputs raw value to stdout (no json_ok wrapper)
+    # For subcommand entry: case block wraps in json_ok
+    # Returns empty string + exit 0 for missing field (callers check emptiness)
+
+    srf_field="${1:-}"
+
+    if [[ -z "$srf_field" ]]; then
+        json_err "$E_VALIDATION_FAILED" "state-read-field requires a jq field path argument"
+    fi
+
+    srf_state_file="$DATA_DIR/COLONY_STATE.json"
+
+    if [[ ! -f "$srf_state_file" ]]; then
+        json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
+    fi
+
+    # Extract the field value (raw output, no quotes around strings)
+    srf_value=$(jq -r "$srf_field // empty" "$srf_state_file" 2>/dev/null) || srf_value=""
+
+    echo "$srf_value"
+}
+
+_state_write() {
+    # Write COLONY_STATE.json through a locked, validated, atomic path
+    # Usage: state-write '<json>'
+    #    or: cat state.json | state-write
+    # Refactored from inline state-write case block for reuse
+    # Validates JSON, acquires lock, creates backup, writes atomically
+
+    sw_content="${1:-}"
+    if [[ -z "$sw_content" ]]; then
+        sw_content=$(cat)
+    fi
+
+    # Validate JSON
+    if ! echo "$sw_content" | jq -e . >/dev/null 2>&1; then  # SUPPRESS:OK -- validation: testing JSON validity
+        json_err "$E_JSON_INVALID" "state-write received invalid JSON"
+    fi
+
+    sw_state_file="$DATA_DIR/COLONY_STATE.json"
+
+    # Acquire lock (colony-level, not hub-level)
+    acquire_lock "$sw_state_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on COLONY_STATE.json"
+
+    # Create backup before writing
+    if [[ -f "$sw_state_file" ]]; then
+        if ! create_backup "$sw_state_file"; then
+            _aether_log_error "Could not create backup of colony state before writing"
+        fi
+    fi
+
+    # Write atomically; release lock on failure
+    atomic_write "$sw_state_file" "$sw_content" || {
+        release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+        json_err "$E_UNKNOWN" "Failed to write COLONY_STATE.json"
+    }
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+
+    json_ok '{"written":true}'
+}
+
+_state_mutate() {
+    # Read-modify-write COLONY_STATE.json with a jq expression
+    # Usage: state-mutate '<jq_expression>'
+    # Acquires lock, creates backup, applies jq, validates, writes atomically
+    # Returns: json_ok with mutated:true, or json_err on failure
+
+    sm_expr="${1:-}"
+
+    if [[ -z "$sm_expr" ]]; then
+        json_err "$E_VALIDATION_FAILED" "state-mutate requires a jq expression argument"
+    fi
+
+    sm_state_file="$DATA_DIR/COLONY_STATE.json"
+
+    if [[ ! -f "$sm_state_file" ]]; then
+        json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
+    fi
+
+    # Acquire lock for safe read-modify-write
+    acquire_lock "$sm_state_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on COLONY_STATE.json"
+
+    # Create backup before mutation
+    if type create_backup &>/dev/null; then
+        if ! create_backup "$sm_state_file"; then
+            _aether_log_error "Could not create backup of colony state before mutation"
+        fi
+    fi
+
+    # Apply jq expression to current state
+    sm_updated=$(jq "$sm_expr" "$sm_state_file" 2>/dev/null) || {
+        release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+        json_err "$E_JSON_INVALID" "jq expression failed: $sm_expr"
+    }
+
+    # Validate the result is valid JSON
+    if [[ -z "$sm_updated" ]] || ! echo "$sm_updated" | jq -e . >/dev/null 2>&1; then
+        release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+        json_err "$E_JSON_INVALID" "state-mutate produced invalid JSON"
+    fi
+
+    # Write atomically
+    atomic_write "$sm_state_file" "$sm_updated" || {
+        release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+        json_err "$E_UNKNOWN" "Failed to write mutated COLONY_STATE.json"
+    }
+
+    release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+
+    json_ok '{"mutated":true}'
+}
+
+_state_migrate() {
+    # Schema migration helper: auto-upgrades pre-3.0 state files to v3.0
+    # Additive only (never removes fields) -- idempotent and safe for concurrent access
+    # Moved from validate-state case block for reuse
+
+    sm_state_file="${1:-}"
+    [[ -f "$sm_state_file" ]] || return 0
+
+    # First: verify file is parseable JSON at all
+    if ! jq -e . "$sm_state_file" >/dev/null 2>&1; then  # SUPPRESS:OK -- validation: testing JSON validity
+        # Corrupt state file -- backup and error
+        if type create_backup &>/dev/null; then
+            if ! create_backup "$sm_state_file"; then
+                _aether_log_error "Could not create backup of corrupted COLONY_STATE.json"
+            fi
+        fi
+        json_err "$E_JSON_INVALID" \
+          "COLONY_STATE.json is corrupted (invalid JSON). A backup was saved in .aether/data/backups/. Try: run /ant:init to reset colony state."
+    fi
+
+    sm_current_version=$(jq -r '.version // "1.0"' "$sm_state_file" 2>/dev/null)  # SUPPRESS:OK -- read-default: file may not exist yet
+
+    if [[ "$sm_current_version" != "3.0" ]]; then
+        sm_lock_held=false
+        # Skip lock acquisition when caller already holds the state lock
+        if [[ "${AETHER_STATE_LOCKED:-false}" != "true" ]] && type acquire_lock &>/dev/null; then
+            acquire_lock "$sm_state_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on COLONY_STATE.json for migration"
+            sm_lock_held=true
+        fi
+
+        # Add missing v3.0 fields (additive only -- idempotent and safe for concurrent access)
+        sm_updated=$(jq '
+            .version = "3.0" |
+            if .signals == null then .signals = [] else . end |
+            if .graveyards == null then .graveyards = [] else . end |
+            if .events == null then .events = [] else . end
+        ' "$sm_state_file" 2>/dev/null) || {  # SUPPRESS:OK -- read-default: file may not exist yet
+            [[ "$sm_lock_held" == "true" ]] && release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+            json_err "$E_JSON_INVALID" "Failed to migrate COLONY_STATE.json"
+        }
+
+        if [[ -n "$sm_updated" ]]; then
+            atomic_write "$sm_state_file" "$sm_updated" || {
+                [[ "$sm_lock_held" == "true" ]] && release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+                json_err "$E_JSON_INVALID" "Failed to write migrated COLONY_STATE.json"
+            }
+            # Notify user of migration (auto-migrate + notify pattern)
+            printf '{"ok":true,"warning":"W_MIGRATED","message":"Migrated colony state from v%s to v3.0"}\n' "$sm_current_version" >&2
+        fi
+
+        [[ "$sm_lock_held" == "true" ]] && release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
+    fi
+}

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

@@ -10,11 +10,13 @@
 #
 # 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)"
+# 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
 
 SCRIPT_DIR="${SCRIPT_DIR:-$AETHER_ROOT/.aether}"
@@ -70,7 +72,7 @@ load_colony_state() {
 
     # Validate state before loading
     local validation
-    validation=$(bash "$SCRIPT_DIR/aether-utils.sh" validate-state colony 2>/dev/null)
+    validation=$(AETHER_STATE_LOCKED=true 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