aether-colony 3.1.17 → 5.0.0

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

@@ -16,7 +16,7 @@ trap 'if type error_handler &>/dev/null; then error_handler ${LINENO} "$BASH_COM
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 AETHER_ROOT="$(cd "$SCRIPT_DIR/.." && pwd 2>/dev/null || echo "$SCRIPT_DIR")"
-DATA_DIR="$AETHER_ROOT/.aether/data"
+DATA_DIR="${DATA_DIR:-$AETHER_ROOT/.aether/data}"
 
 # Initialize lock state before sourcing (file-lock.sh trap needs these)
 LOCK_ACQUIRED=${LOCK_ACQUIRED:-false}
@@ -28,6 +28,7 @@ CURRENT_LOCK=${CURRENT_LOCK:-""}
 [[ -f "$SCRIPT_DIR/utils/error-handler.sh" ]] && source "$SCRIPT_DIR/utils/error-handler.sh"
 [[ -f "$SCRIPT_DIR/utils/chamber-utils.sh" ]] && source "$SCRIPT_DIR/utils/chamber-utils.sh"
 [[ -f "$SCRIPT_DIR/utils/xml-utils.sh" ]] && source "$SCRIPT_DIR/utils/xml-utils.sh"
+[[ -f "$SCRIPT_DIR/utils/semantic-cli.sh" ]] && source "$SCRIPT_DIR/utils/semantic-cli.sh"
 
 # Fallback error constants if error-handler.sh wasn't sourced
 # This prevents "unbound variable" errors in older installations
@@ -37,26 +38,13 @@ CURRENT_LOCK=${CURRENT_LOCK:-""}
 : "${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}"
-
-# Feature detection for graceful degradation
-# These checks run silently - failures are logged but don't block operation
-if type feature_disable &>/dev/null; then
-  # Check if DATA_DIR is writable for activity logging
-  [[ -w "$DATA_DIR" ]] 2>/dev/null || feature_disable "activity_log" "DATA_DIR not writable"
-
-  # Check if git is available for git integration
-  command -v git &>/dev/null || feature_disable "git_integration" "git not installed"
-
-  # Check if jq is available for JSON processing
-  command -v jq &>/dev/null || feature_disable "json_processing" "jq not installed"
-
-  # Check if lock utilities are available
-  [[ -f "$SCRIPT_DIR/utils/file-lock.sh" ]] || feature_disable "file_locking" "lock utilities not available"
-fi
+: "${E_DEPENDENCY_MISSING:=E_DEPENDENCY_MISSING}"
+: "${E_RESOURCE_NOT_FOUND:=E_RESOURCE_NOT_FOUND}"
 
 # Fallback atomic_write if not sourced (uses temp file + mv for true atomicity)
 if ! type atomic_write &>/dev/null; then
@@ -77,14 +65,62 @@ json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
 # Error: JSON to stderr, exit 1
 # Use enhanced json_err from error-handler.sh if available, otherwise fallback
 if ! type json_err &>/dev/null; then
-  # Fallback: simple error format for backward compatibility
+  # Fallback: error-handler.sh failed to load. Emits minimal but parseable JSON.
+  # Diagnostic note tells the user their installation may be incomplete.
   json_err() {
-    local message="${2:-$1}"
-    printf '{"ok":false,"error":"%s"}\n' "$message" >&2
+    local code="${1:-E_UNKNOWN}"
+    local message="${2:-An unknown error occurred}"
+    printf '[aether] Warning: error-handler.sh not loaded — using minimal fallback\n' >&2
+    printf '{"ok":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message" >&2
     exit 1
   }
 fi
 
+# Feature detection for graceful degradation
+# ARCH-09: runs AFTER all fallback definitions (atomic_write, json_ok, json_err)
+# so feature_disable is never called before those functions exist.
+# These checks run silently - failures are logged but don't block operation
+if type feature_disable &>/dev/null; then
+  # Check if DATA_DIR is writable for activity logging
+  [[ -w "$DATA_DIR" ]] 2>/dev/null || feature_disable "activity_log" "DATA_DIR not writable"
+
+  # Check if git is available for git integration
+  command -v git &>/dev/null || feature_disable "git_integration" "git not installed"
+
+  # Check if jq is available for JSON processing
+  command -v jq &>/dev/null || feature_disable "json_processing" "jq not installed"
+
+  # Check if lock utilities are available
+  [[ -f "$SCRIPT_DIR/utils/file-lock.sh" ]] || feature_disable "file_locking" "lock utilities not available"
+fi
+
+# Composed exit cleanup — replaces individual traps from file-lock.sh and atomic-write.sh
+# ARCH-10: bash traps are single-valued per signal — last trap set wins.
+# This function ensures both lock and temp cleanup run on every exit path.
+# Must be set AFTER file-lock.sh is sourced so it overrides the individual
+# 'trap cleanup_locks EXIT TERM INT HUP' set by file-lock.sh.
+_aether_exit_cleanup() {
+    cleanup_locks 2>/dev/null || true
+    cleanup_temp_files 2>/dev/null || true
+}
+trap '_aether_exit_cleanup' EXIT TERM INT HUP
+
+# Startup cleanup — remove temp files from dead sessions (PID-based orphan detection)
+# ARCH-10: runs once at startup, silent (matches lock cleanup behavior)
+_cleanup_orphaned_temp_files() {
+    local temp_dir="${TEMP_DIR:-$AETHER_ROOT/.aether/temp}"
+    [[ -d "$temp_dir" ]] || return 0
+    while IFS= read -r -d '' tmp_file; do
+        local file_pid
+        file_pid=$(basename "$tmp_file" | awk -F'.' '{print $(NF-2)}')
+        if [[ "$file_pid" =~ ^[0-9]+$ ]] && ! kill -0 "$file_pid" 2>/dev/null; then
+            rm -f "$tmp_file" 2>/dev/null || true
+        fi
+    done < <(find "$temp_dir" -maxdepth 1 -name "*.tmp" -print0 2>/dev/null)
+}
+# Run orphan cleanup on startup (silent — matches cleanup_locks behavior)
+type cleanup_temp_files &>/dev/null && _cleanup_orphaned_temp_files
+
 # --- Caste emoji helper ---
 get_caste_emoji() {
   case "$1" in
@@ -110,10 +146,88 @@ get_caste_emoji() {
     *Probe*|*probe*|*Test*|*Excavat*|*Uncover*|*Edge*|*Case*|*Mutant*) echo "🧪🐜" ;;
     *Tracker*|*tracker*|*Debug*|*Trace*|*Follow*|*Bug*|*Hunt*|*Root*) echo "🐛🐜" ;;
     *Weaver*|*weaver*|*Refactor*|*Restruct*|*Transform*|*Clean*|*Pattern*|*Weave*) echo "🔄🐜" ;;
+    *Dreamer*|*dreamer*|*Dream*|*Muse*|*Imagine*|*Wonder*|*Ponder*|*Reverie*) echo "💭🐜" ;;
     *) echo "🐜" ;;
   esac
 }
 
+# --- Progress bar helper ---
+# Usage: generate-progress-bar <current> <total> [width]
+# Returns: "[████████░░░░░░░░] 8/20" format string
+generate-progress-bar() {
+  local current="${1:-0}"
+  local total="${2:-1}"
+  local width="${3:-20}"
+
+  # Prevent division by zero
+  [[ "$total" -lt 1 ]] && total=1
+  [[ "$current" -lt 0 ]] && current=0
+  [[ "$current" -gt "$total" ]] && current="$total"
+
+  # Calculate filled/empty segments
+  local filled=$(( (current * width) / total ))
+  local empty=$(( width - filled ))
+
+  # Build bar with Unicode block characters
+  local bar=""
+  for ((i=0; i<filled; i++)); do bar+="█"; done
+  for ((i=0; i<empty; i++)); do bar+="░"; done
+
+  echo "[$bar] $current/$total"
+}
+
+# --- Standard banner helper ---
+# Usage: print-standard-banner <title>
+# Outputs a standardized banner with heavy horizontal lines (U+2501)
+print-standard-banner() {
+  local title="$1"
+
+  # Convert title to spaced uppercase
+  local spaced_title
+  spaced_title=$(echo "$title" | tr '[:lower:]' '[:upper:]' | sed 's/./& /g' | sed 's/ $//')
+
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "   $spaced_title"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+}
+
+# --- Next Up block helper ---
+# Usage: print-next-up <state> [current_phase] [total_phases]
+# Outputs a Next Up block with state-based suggestions
+print-next-up() {
+  local state="${1:-IDLE}"
+  local current_phase="${2:-0}"
+  local total_phases="${3:-0}"
+  local next_phase=$((current_phase + 1))
+
+  echo "──────────────────────────────────────────────────"
+  echo "🐜 Next Up"
+  echo "──────────────────────────────────────────────────"
+
+  case "$state" in
+    IDLE)
+      echo "   /ant:init               🌱 Start a new colony"
+      echo "   /ant:status             📊 Check current state"
+      ;;
+    READY)
+      echo "   /ant:build $next_phase            🔨 Build phase $next_phase"
+      echo "   /ant:phase $next_phase            📋 Review phase details"
+      echo "   /ant:focus              🎯 Guide colony attention"
+      ;;
+    EXECUTING)
+      echo "   /ant:continue           ➡️  Continue current build"
+      echo "   /ant:status             📊 Check build progress"
+      ;;
+    PLANNING)
+      echo "   /ant:plan               📝 Create execution plan"
+      echo "   /ant:status             📊 Check current state"
+      ;;
+    *)
+      echo "   /ant:status             📊 Check colony state"
+      ;;
+  esac
+}
+
 # ============================================
 # CONTEXT UPDATE HELPER FUNCTION
 # (Defined outside case block to fix SC2168: local outside function)
@@ -125,6 +239,19 @@ _cmd_context_update() {
   local ctx_ts
   ctx_ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
+  # Check for empty action first - show usage message
+  if [[ -z "$ctx_action" ]]; then
+    json_err "$E_VALIDATION_FAILED" "No action specified. Suggestion: Use one of: init, update-phase, activity, constraint, decision, safe-to-clear, build-start, worker-spawn, worker-complete, build-progress, build-complete"
+  fi
+
+  # Acquire lock for context-update operations (LOCK-04: prevent concurrent corruption)
+  local _ctx_lock_held=false
+  if type acquire_lock &>/dev/null && type feature_enabled &>/dev/null && feature_enabled "file_locking"; then
+    acquire_lock "$ctx_file" || json_err "$E_LOCK_FAILED" "Failed to acquire CONTEXT.md lock for context-update"
+    _ctx_lock_held=true
+    trap 'release_lock 2>/dev/null || true' EXIT
+  fi
+
   ensure_context_dir() {
     local dir
     dir=$(dirname "$ctx_file")
@@ -186,7 +313,7 @@ Colony initialization in progress...
 
 | Constraint | Source | Date Set |
 |------------|--------|----------|
-| In the Aether repo, \`.aether/\` IS the source of truth — \`runtime/\` is auto-populated on publish | CLAUDE.md | Permanent |
+| In the Aether repo, \`.aether/\` IS the source of truth — published directly via npm (private dirs excluded by .npmignore) | CLAUDE.md | Permanent |
 | Never push without explicit user approval | CLAUDE.md Safety | Permanent |
 
 ---
@@ -268,7 +395,7 @@ EOF
       local safe_clear="${4:-NO}"
       local safe_reason="${5:-Phase in progress}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found. Run context-update init first."; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
       sed -i.bak "s/| \*\*Current Phase\*\* | .*/| **Current Phase** | $new_phase |/" "$ctx_file" && rm -f "$ctx_file.bak"
@@ -283,7 +410,7 @@ EOF
       local result="${3:-}"
       local files_changed="${4:-—}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -309,7 +436,7 @@ EOF
       local safe="${2:-NO}"
       local reason="${3:-Unknown state}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
       sed -i.bak "s/| \*\*Safe to Clear?\*\* | .*/| **Safe to Clear?** | $safe — $reason |/" "$ctx_file" && rm -f "$ctx_file.bak"
@@ -322,7 +449,7 @@ EOF
       local c_message="${3:-}"
       local c_source="${4:-User}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -344,7 +471,7 @@ EOF
       local rationale="${3:-}"
       local made_by="${4:-Colony}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -376,7 +503,7 @@ EOF
       local worker_count="${3:-0}"
       local tasks_count="${4:-0}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
       sed -i.bak "s/## 📍 What's In Progress/## 📍 What's In Progress\n\n**Phase $phase_id Build IN PROGRESS**\n- Workers: $worker_count | Tasks: $tasks_count\n- Started: $ctx_ts/" "$ctx_file" && rm -f "$ctx_file.bak"
@@ -390,7 +517,7 @@ EOF
       local caste="${3:-}"
       local task="${4:-}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       awk -v ant="$ant_name" -v caste="$caste" -v task="$task" -v ts="$ctx_ts" '
         /^## 📍 What'\''s In Progress/ { in_progress=1 }
@@ -410,7 +537,7 @@ EOF
       local ant_name="${2:-}"
       local status="${3:-completed}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/- .*$ant_name .*$/- $ant_name: $status (updated $ctx_ts)/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -422,7 +549,7 @@ EOF
       local total="${3:-1}"
       local percentage=$(( completed * 100 / total ))
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/Build IN PROGRESS/Build IN PROGRESS ($percentage% complete)/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -433,7 +560,7 @@ EOF
       local status="${2:-completed}"
       local result="${3:-success}"
 
-      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+      [[ -f "$ctx_file" ]] || { json_err "$E_FILE_NOT_FOUND" "Couldn't find CONTEXT.md. Try: run context-update init first."; }
 
       sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
 
@@ -456,9 +583,20 @@ EOF
       ;;
 
     *)
-      json_err "$E_VALIDATION_FAILED" "Unknown context action: $ctx_action"
+      json_err "$E_VALIDATION_FAILED" "Unknown context action: '$ctx_action'. Suggestion: Use one of: init, update-phase, activity, constraint, decision, safe-to-clear, build-start, worker-spawn, worker-complete, build-progress, build-complete"
       ;;
   esac
+
+  # Release lock on success (LOCK-04)
+  # NOTE: Do NOT clear the EXIT trap here. This function RETURNS (it does not
+  # call exit), so clearing the trap would remove the safety net without benefit.
+  # The EXIT trap remains active as a true safety net for unexpected exit calls
+  # elsewhere in the process. The _ctx_lock_held variable is the primary gate
+  # for this function's own cleanup.
+  if [[ "$_ctx_lock_held" == "true" ]]; then
+    release_lock 2>/dev/null || true
+    _ctx_lock_held=false
+  fi
 }
 
 # --- Subcommand dispatch ---
@@ -467,17 +605,140 @@ shift 2>/dev/null || true
 
 case "$cmd" in
   help)
-    cat <<'EOF'
-{"ok":true,"commands":["help","version","validate-state","load-state","unload-state","error-add","error-pattern-check","error-summary","activity-log","activity-log-init","activity-log-read","learning-promote","learning-inject","generate-ant-name","spawn-log","spawn-complete","spawn-can-spawn","spawn-get-depth","spawn-tree-load","spawn-tree-active","spawn-tree-depth","update-progress","check-antipattern","error-flag-pattern","signature-scan","signature-match","flag-add","flag-check-blockers","flag-resolve","flag-acknowledge","flag-list","flag-auto-resolve","autofix-checkpoint","autofix-rollback","spawn-can-spawn-swarm","swarm-findings-init","swarm-findings-add","swarm-findings-read","swarm-solution-set","swarm-cleanup","swarm-activity-log","swarm-display-init","swarm-display-update","swarm-display-get","swarm-timing-start","swarm-timing-get","swarm-timing-eta","view-state-init","view-state-get","view-state-set","view-state-toggle","view-state-expand","view-state-collapse","grave-add","grave-check","generate-commit-message","version-check","registry-add","bootstrap-system","model-profile","model-get","model-list","chamber-create","chamber-verify","chamber-list","milestone-detect","queen-init","queen-read","queen-promote","survey-load","survey-verify","pheromone-export"],"description":"Aether Colony Utility Layer — deterministic ops for the ant colony"}
-EOF
+    # Build help JSON with sections for discoverability.
+    # The flat 'commands' array is kept for backward compatibility
+    # (callers use: jq '.commands[]')
+    cat <<'HELP_EOF'
+{
+  "ok": true,
+  "commands": ["help","version","validate-state","load-state","unload-state","error-add","error-pattern-check","error-summary","activity-log","activity-log-init","activity-log-read","learning-promote","learning-inject","generate-ant-name","spawn-log","spawn-complete","spawn-can-spawn","spawn-get-depth","spawn-tree-load","spawn-tree-active","spawn-tree-depth","update-progress","check-antipattern","error-flag-pattern","signature-scan","signature-match","flag-add","flag-check-blockers","flag-resolve","flag-acknowledge","flag-list","flag-auto-resolve","autofix-checkpoint","autofix-rollback","spawn-can-spawn-swarm","swarm-findings-init","swarm-findings-add","swarm-findings-read","swarm-solution-set","swarm-cleanup","swarm-activity-log","swarm-display-init","swarm-display-update","swarm-display-get","swarm-display-text","swarm-timing-start","swarm-timing-get","swarm-timing-eta","view-state-init","view-state-get","view-state-set","view-state-toggle","view-state-expand","view-state-collapse","grave-add","grave-check","generate-commit-message","version-check","registry-add","bootstrap-system","model-profile","model-get","model-list","chamber-create","chamber-verify","chamber-list","milestone-detect","queen-init","queen-read","queen-promote","survey-load","survey-verify","pheromone-export","pheromone-write","pheromone-count","pheromone-read","instinct-read","pheromone-prime","pheromone-expire","eternal-init","pheromone-export-xml","pheromone-import-xml","pheromone-validate-xml","wisdom-export-xml","wisdom-import-xml","registry-export-xml","registry-import-xml","force-unlock"],
+  "sections": {
+    "Core": [
+      {"name": "help", "description": "List all available commands with sections"},
+      {"name": "version", "description": "Show installed version"}
+    ],
+    "Colony State": [
+      {"name": "validate-state", "description": "Validate COLONY_STATE.json or constraints.json"},
+      {"name": "load-state", "description": "Load and lock COLONY_STATE.json"},
+      {"name": "unload-state", "description": "Release COLONY_STATE.json lock"}
+    ],
+    "Queen Commands": [
+      {"name": "queen-init", "description": "Initialize a new colony QUEEN.md from template"},
+      {"name": "queen-read", "description": "Read QUEEN.md wisdom as JSON for worker priming"},
+      {"name": "queen-promote", "description": "Promote a validated learning to QUEEN.md wisdom"}
+    ],
+    "Model Routing": [
+      {"name": "model-profile", "description": "Manage caste-to-model assignments"},
+      {"name": "model-get", "description": "Get model assignment for a caste"},
+      {"name": "model-list", "description": "List all model assignments"}
+    ],
+    "Spawn Management": [
+      {"name": "spawn-log", "description": "Log a spawn event to spawn-tree.txt"},
+      {"name": "spawn-complete", "description": "Record spawn completion in spawn-tree.txt"},
+      {"name": "spawn-can-spawn", "description": "Check if spawn budget allows another worker"},
+      {"name": "spawn-get-depth", "description": "Get spawn depth for an ant name"},
+      {"name": "spawn-tree-load", "description": "Load spawn-tree.txt as JSON"},
+      {"name": "spawn-tree-active", "description": "List currently active spawns"},
+      {"name": "spawn-tree-depth", "description": "Get depth for a named ant"}
+    ],
+    "Flag Management": [
+      {"name": "flag-add", "description": "Add a flag to flags.json"},
+      {"name": "flag-check-blockers", "description": "Check for flags blocking a task"},
+      {"name": "flag-resolve", "description": "Mark a flag as resolved"},
+      {"name": "flag-acknowledge", "description": "Acknowledge a flag without resolving"},
+      {"name": "flag-list", "description": "List all flags"},
+      {"name": "flag-auto-resolve", "description": "Auto-resolve flags matching criteria"}
+    ],
+    "Chamber Management": [
+      {"name": "chamber-create", "description": "Entomb a colony into a named chamber"},
+      {"name": "chamber-verify", "description": "Verify chamber integrity"},
+      {"name": "chamber-list", "description": "List all available chambers"}
+    ],
+    "Swarm Operations": [
+      {"name": "swarm-findings-init", "description": "Initialize swarm findings file"},
+      {"name": "swarm-findings-add", "description": "Add a finding to swarm results"},
+      {"name": "swarm-findings-read", "description": "Read all swarm findings"},
+      {"name": "swarm-solution-set", "description": "Set the chosen swarm solution"},
+      {"name": "swarm-cleanup", "description": "Clean up swarm state files"},
+      {"name": "swarm-display-init", "description": "Initialize swarm progress display"},
+      {"name": "swarm-display-update", "description": "Update swarm display for an ant"},
+      {"name": "swarm-timing-start", "description": "Start timing for a swarm operation"},
+      {"name": "swarm-timing-get", "description": "Get elapsed time for a swarm"},
+      {"name": "swarm-timing-eta", "description": "Estimate remaining time for a swarm"}
+    ],
+    "Pheromone System": [
+      {"name": "pheromone-write", "description": "Write a pheromone signal"},
+      {"name": "pheromone-read", "description": "Read pheromone signals"},
+      {"name": "pheromone-count", "description": "Count active pheromone signals"},
+      {"name": "pheromone-prime", "description": "Prime the pheromone system"},
+      {"name": "pheromone-expire", "description": "Expire old pheromone signals"},
+      {"name": "pheromone-export", "description": "Export pheromone data to JSON"},
+      {"name": "pheromone-export-xml", "description": "Export pheromone data to XML"},
+      {"name": "pheromone-import-xml", "description": "Import pheromone data from XML"},
+      {"name": "pheromone-validate-xml", "description": "Validate pheromone XML against schema"}
+    ],
+    "Utilities": [
+      {"name": "generate-ant-name", "description": "Generate a unique ant name with caste prefix"},
+      {"name": "activity-log", "description": "Append an entry to the activity log"},
+      {"name": "activity-log-init", "description": "Initialize the activity log file"},
+      {"name": "activity-log-read", "description": "Read recent activity log entries"},
+      {"name": "generate-commit-message", "description": "Generate a commit message from git diff"},
+      {"name": "version-check", "description": "Check if Aether version meets requirement"},
+      {"name": "registry-add", "description": "Register a repo with Aether"},
+      {"name": "bootstrap-system", "description": "Bootstrap minimal system files if missing"},
+      {"name": "force-unlock", "description": "Emergency unlock — remove stale lock files"}
+    ]
+  },
+  "description": "Aether Colony Utility Layer — deterministic ops for the ant colony"
+}
+HELP_EOF
     ;;
   version)
     json_ok '"1.0.0"'
     ;;
   validate-state)
+    # Schema migration helper: auto-upgrades pre-3.0 state files to v3.0
+    # Additive only (never removes fields) — idempotent and safe for concurrent access
+    _migrate_colony_state() {
+      local state_file="$1"
+      [[ -f "$state_file" ]] || return 0
+
+      # First: verify file is parseable JSON at all
+      if ! jq -e . "$state_file" >/dev/null 2>&1; then
+        # Corrupt state file — backup and error
+        if type create_backup &>/dev/null; then
+          create_backup "$state_file" 2>/dev/null || true
+        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
+
+      local current_version
+      current_version=$(jq -r '.version // "1.0"' "$state_file" 2>/dev/null)
+
+      if [[ "$current_version" != "3.0" ]]; then
+        # Add missing v3.0 fields (additive only — idempotent and safe for concurrent access)
+        local updated
+        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
+        ' "$state_file" 2>/dev/null)
+
+        if [[ -n "$updated" ]]; then
+          atomic_write "$state_file" "$updated"
+          # 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' "$current_version" >&2
+        fi
+      fi
+    }
+
     case "${1:-}" in
       colony)
         [[ -f "$DATA_DIR/COLONY_STATE.json" ]] || json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
+        # Run schema migration before field validation (ensures v3.0 fields always present)
+        _migrate_colony_state "$DATA_DIR/COLONY_STATE.json"
         json_ok "$(jq '
           def chk(f;t): if has(f) then (if (.[f]|type) as $a | t | any(. == $a) then "pass" else "fail: \(f) is \(.[f]|type), expected \(t|join("|"))" end) else "fail: missing \(f)" end;
           def opt(f;t): if has(f) then (if (.[f]|type) as $a | t | any(. == $a) then "pass" else "fail: \(f) is \(.[f]|type), expected \(t|join("|"))" end) else "pass" end;
@@ -492,7 +753,7 @@ EOF
             opt("session_id";["string","null"]),
             opt("initialized_at";["string","null"]),
             opt("build_started_at";["string","null"])
-          ]} | . + {pass: ([.checks[] | select(. == "pass")] | length) == (.checks | length)}
+          ]} | . + {pass: (([.checks[] | select(. == "pass")] | length) == (.checks | length))}
         ' "$DATA_DIR/COLONY_STATE.json")"
         ;;
       constraints)
@@ -502,7 +763,7 @@ EOF
           {file:"constraints.json", checks:[
             arr("focus"),
             arr("constraints")
-          ]} | . + {pass: ([.checks[] | select(. == "pass")] | length) == (.checks | length)}
+          ]} | . + {pass: (([.checks[] | select(. == "pass")] | length) == (.checks | length))}
         ' "$DATA_DIR/constraints.json")"
         ;;
       all)
@@ -727,6 +988,18 @@ EOF
     echo "[$ts] $status_icon $emoji $ant_name: $status${summary:+ - $summary}" >> "$DATA_DIR/activity.log"
     # Update spawn tree
     echo "$ts_full|$ant_name|$status|$summary" >> "$DATA_DIR/spawn-tree.txt"
+    # Log failed spawns to COLONY_STATE.json events array for audit trail (ARCH-04)
+    if [[ "$status" == "failed" ]] || [[ "$status" == "error" ]]; then
+      spawn_complete_state_file="$DATA_DIR/COLONY_STATE.json"
+      if [[ -f "$spawn_complete_state_file" ]]; then
+        spawn_complete_updated=$(jq --arg ts "$ts_full" --arg name "$ant_name" --arg st "$status" --arg sum "${summary:-unknown}" \
+          '.events += [{"type":"spawn_failed","ant":$name,"status":$st,"summary":$sum,"timestamp":$ts}]' \
+          "$spawn_complete_state_file" 2>/dev/null)
+        if [[ -n "$spawn_complete_updated" ]]; then
+          atomic_write "$spawn_complete_state_file" "$spawn_complete_updated"
+        fi
+      fi
+    fi
     # Return emoji-formatted result for display
     json_ok "\"$status_icon $emoji $ant_name: ${summary:-$status}\""
     ;;
@@ -1172,7 +1445,6 @@ EOF
     ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
     # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
-    lock_acquired=false
     if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
       json_warn "W_DEGRADED" "File locking disabled - proceeding without lock: $(type _feature_reason &>/dev/null && _feature_reason file_locking || echo 'unknown')"
     else
@@ -1184,9 +1456,8 @@ EOF
           exit 1
         fi
       }
-      lock_acquired=true
       # Ensure lock is always released on exit (BUG-002 fix)
-      trap 'release_lock "$flags_file" 2>/dev/null || true' EXIT
+      trap 'release_lock 2>/dev/null || true' EXIT
     fi
 
     # Map type to severity
@@ -1224,8 +1495,8 @@ EOF
     ' "$flags_file") || { json_err "$E_JSON_INVALID" "Failed to add flag"; }
 
     atomic_write "$flags_file" "$updated"
-    # Lock released by trap on exit (BUG-002 fix)
     trap - EXIT
+    release_lock 2>/dev/null || true
     json_ok "{\"id\":\"$id\",\"type\":\"$type\",\"severity\":\"$severity\"}"
     ;;
   flag-check-blockers)
@@ -1274,6 +1545,7 @@ EOF
       json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
     else
       acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+      trap 'release_lock 2>/dev/null || true' EXIT
     fi
 
     updated=$(jq --arg id "$flag_id" --arg res "$resolution" --arg ts "$ts" '
@@ -1282,14 +1554,12 @@ EOF
         .resolution = $res
       else . end]
     ' "$flags_file") || {
-      if type feature_enabled &>/dev/null && feature_enabled "file_locking"; then
-        release_lock "$flags_file"
-      fi
       json_err "$E_JSON_INVALID" "Failed to resolve flag"
     }
 
     atomic_write "$flags_file" "$updated"
-    release_lock "$flags_file"
+    trap - EXIT
+    release_lock 2>/dev/null || true
     json_ok "{\"resolved\":\"$flag_id\"}"
     ;;
   flag-acknowledge)
@@ -1308,6 +1578,7 @@ EOF
       json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
     else
       acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
+      trap 'release_lock 2>/dev/null || true' EXIT
     fi
 
     updated=$(jq --arg id "$flag_id" --arg ts "$ts" '
@@ -1315,14 +1586,12 @@ EOF
         .acknowledged_at = $ts
       else . end]
     ' "$flags_file") || {
-      if type feature_enabled &>/dev/null && feature_enabled "file_locking"; then
-        release_lock "$flags_file"
-      fi
       json_err "$E_JSON_INVALID" "Failed to acknowledge flag"
     }
 
     atomic_write "$flags_file" "$updated"
-    release_lock "$flags_file"
+    trap - EXIT
+    release_lock 2>/dev/null || true
     json_ok "{\"acknowledged\":\"$flag_id\"}"
     ;;
   flag-list)
@@ -1376,14 +1645,12 @@ EOF
     ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
     # Acquire lock for atomic flag update (degrade gracefully if locking unavailable)
-    lock_acquired=false
     if type feature_enabled &>/dev/null && ! feature_enabled "file_locking"; then
       json_warn "W_DEGRADED" "File locking disabled - proceeding without lock"
     else
       acquire_lock "$flags_file" || json_err "$E_LOCK_FAILED" "Failed to acquire lock on flags.json"
-      lock_acquired=true
       # Ensure lock is always released on exit (BUG-005/BUG-011 fix)
-      trap 'release_lock "$flags_file" 2>/dev/null || true' EXIT
+      trap 'release_lock 2>/dev/null || true' EXIT
     fi
 
     # Count how many will be resolved
@@ -1404,10 +1671,8 @@ EOF
     }
 
     atomic_write "$flags_file" "$updated"
-    # Lock released by trap on exit (BUG-005/BUG-011 fix)
-    if [[ "$lock_acquired" == "true" ]]; then
-      trap - EXIT
-    fi
+    trap - EXIT
+    release_lock 2>/dev/null || true
     json_ok "{\"resolved\":$count,\"trigger\":\"$trigger\"}"
     ;;
   generate-ant-name)
@@ -1456,7 +1721,7 @@ EOF
     if git rev-parse --git-dir >/dev/null 2>&1; then
       # Check if there are changes to Aether-managed files only
       # Target directories that Aether is allowed to modify
-      target_dirs=".aether .claude/commands/ant .claude/commands/st .opencode runtime bin"
+      target_dirs=".aether .claude/commands/ant .claude/commands/st .opencode bin"
       has_changes=false
 
       for dir in $target_dirs; do
@@ -1535,7 +1800,7 @@ EOF
 
     current=0
     if [[ -f "$DATA_DIR/spawn-tree.txt" ]]; then
-      current=$(grep -c "|swarm:$swarm_id$" "$DATA_DIR/spawn-tree.txt" 2>/dev/null || echo 0)
+      current=$(grep -c "|swarm:$swarm_id$" "$DATA_DIR/spawn-tree.txt" 2>/dev/null) || current=0
     fi
 
     if [[ $current -lt $swarm_cap ]]; then
@@ -1870,6 +2135,33 @@ Files: ${files_changed} files changed"
     fi
     ;;
 
+  version-check-cached)
+    # Cached version of version-check — skips if checked within TTL (3600s = 1 hour)
+    # Usage: version-check-cached
+    cache_file="$AETHER_ROOT/.aether/data/.version-check-cache"
+    now=$(date +%s)
+
+    if [[ -f "$cache_file" ]]; then
+      cached_at=$(cat "$cache_file" 2>/dev/null || echo "0")
+      age=$((now - cached_at))
+      if [[ $age -lt 3600 ]]; then
+        # Within TTL — skip silently
+        json_ok '""'
+        exit 0
+      fi
+    fi
+
+    # Cache miss or stale — run actual check
+    mkdir -p "$(dirname "$cache_file")" 2>/dev/null || true
+    result=$("$0" version-check 2>/dev/null) || true
+    echo "$now" > "$cache_file" 2>/dev/null || true
+    if [[ -n "$result" ]]; then
+      echo "$result"
+    else
+      json_ok '""'
+    fi
+    ;;
+
   registry-add)
     # Add or update a repo entry in ~/.aether/registry.json
     # Usage: registry-add <repo_path> <version>
@@ -1924,15 +2216,14 @@ Files: ${files_changed} files changed"
     # Allowlist of system files to copy (relative to system/)
     allowlist=(
       "aether-utils.sh"
-      "coding-standards.md"
-      "debugging.md"
-      "DISCIPLINES.md"
-      "learning.md"
-      "planning.md"
-      "QUEEN_ANT_ARCHITECTURE.md"
-      "tdd.md"
-      "verification-loop.md"
-      "verification.md"
+      "docs/disciplines/coding-standards.md"
+      "docs/disciplines/debugging.md"
+      "docs/disciplines/DISCIPLINES.md"
+      "docs/disciplines/learning.md"
+      "docs/disciplines/tdd.md"
+      "docs/disciplines/verification-loop.md"
+      "docs/disciplines/verification.md"
+      "docs/QUEEN_ANT_ARCHITECTURE.md"
       "workers.md"
       "docs/constraints.md"
       "docs/pathogen-schema-example.json"
@@ -2143,15 +2434,29 @@ NODESCRIPT
   model-get)
     # Shortcut: model-get <caste>
     caste="${1:-}"
-    [[ -z "$caste" ]] && json_err "$E_VALIDATION_FAILED" "Usage: model-get <caste>"
-
-    # Delegate to model-profile get
-    exec bash "$0" model-profile get "$caste"
+    [[ -z "$caste" ]] && json_err "$E_VALIDATION_FAILED" "Usage: model-get <caste>. Try: provide a caste name (e.g., builder, scout, surveyor)."
+
+    # Delegate to model-profile get via subprocess (not exec) so errors can be captured
+    set +e
+    result=$(bash "$0" model-profile get "$caste" 2>&1)
+    exit_code=$?
+    set -e
+    if [[ $exit_code -ne 0 ]]; then
+      json_err "$E_BASH_ERROR" "Couldn't get model assignment for caste '$caste'. Try: check that .aether/model-profiles.yaml exists and is valid YAML."
+    fi
+    echo "$result"
     ;;
 
   model-list)
-    # Shortcut: list all models
-    exec bash "$0" model-profile list
+    # Shortcut: list all models via subprocess (not exec) so errors can be captured
+    set +e
+    result=$(bash "$0" model-profile list 2>&1)
+    exit_code=$?
+    set -e
+    if [[ $exit_code -ne 0 ]]; then
+      json_err "$E_BASH_ERROR" "Couldn't list model assignments. Try: run 'aether verify-models' to check model configuration."
+    fi
+    echo "$result"
     ;;
 
   # ============================================
@@ -2697,6 +3002,106 @@ ANTLOGO
     json_ok "{\"displayed\":true,\"ants\":$total_active}"
     ;;
 
+  swarm-display-text)
+    # Plain-text swarm display for Claude conversation (no ANSI codes)
+    # Usage: swarm-display-text [swarm_id]
+    swarm_id="${1:-default-swarm}"
+    display_file="$DATA_DIR/swarm-display.json"
+
+    # Check for display file
+    if [[ ! -f "$display_file" ]]; then
+      echo "🐜 Colony idle"
+      json_ok '{"displayed":false,"reason":"no_data"}'
+      exit 0
+    fi
+
+    # Check for jq
+    if ! command -v jq >/dev/null 2>&1; then
+      echo "🐜 Swarm active (details unavailable)"
+      json_ok '{"displayed":true,"warning":"jq_missing"}'
+      exit 0
+    fi
+
+    # Read swarm data — handle both flat total_active and nested .summary.total_active
+    total_active=$(jq -r '(.total_active // .summary.total_active // 0)' "$display_file" 2>/dev/null || echo "0")
+
+    if [[ "$total_active" -eq 0 ]]; then
+      echo "🐜 Colony idle"
+      json_ok '{"displayed":true,"ants":0}'
+      exit 0
+    fi
+
+    # Compact header
+    echo "🐜 COLONY ACTIVITY"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    # Caste emoji lookup
+    get_emoji() {
+      case "$1" in
+        builder)       echo "🔨🐜" ;;
+        watcher)       echo "👁️🐜" ;;
+        scout)         echo "🔍🐜" ;;
+        chaos)         echo "🎲🐜" ;;
+        prime)         echo "👑🐜" ;;
+        oracle)        echo "🔮🐜" ;;
+        route_setter)  echo "🧭🐜" ;;
+        archaeologist) echo "🏺🐜" ;;
+        surveyor)      echo "📊🐜" ;;
+        *)             echo "🐜" ;;
+      esac
+    }
+
+    # Format tool counts (only non-zero)
+    format_tools_text() {
+      local r="${1:-0}" g="${2:-0}" e="${3:-0}" b="${4:-0}"
+      local result=""
+      [[ "$r" -gt 0 ]] && result="${result}📖${r} "
+      [[ "$g" -gt 0 ]] && result="${result}🔍${g} "
+      [[ "$e" -gt 0 ]] && result="${result}✏️${e} "
+      [[ "$b" -gt 0 ]] && result="${result}⚡${b}"
+      echo "$result"
+    }
+
+    # Progress bar using block characters (no ANSI)
+    render_bar_text() {
+      local pct="${1:-0}" w="${2:-10}"
+      [[ "$pct" -lt 0 ]] && pct=0
+      [[ "$pct" -gt 100 ]] && pct=100
+      local filled=$((pct * w / 100))
+      local empty=$((w - filled))
+      local bar=""
+      for ((i=0; i<filled; i++)); do bar+="█"; done
+      for ((i=0; i<empty; i++)); do bar+="░"; done
+      echo "[$bar] ${pct}%"
+    }
+
+    # Render each ant (max 5)
+    jq -r '.active_ants[0:5][] | "\(.name)|\(.caste)|\(.task // "")|\(.tools.read // 0)|\(.tools.grep // 0)|\(.tools.edit // 0)|\(.tools.bash // 0)|\(.progress // 0)"' "$display_file" 2>/dev/null | while IFS='|' read -r name caste task r g e b progress; do
+      emoji=$(get_emoji "$caste")
+      tools=$(format_tools_text "$r" "$g" "$e" "$b")
+      bar=$(render_bar_text "${progress:-0}" 10)
+
+      # Truncate task to 25 chars
+      [[ ${#task} -gt 25 ]] && task="${task:0:22}..."
+
+      echo "${emoji} ${name} ${bar} ${task}"
+      [[ -n "$tools" ]] && echo "   ${tools}"
+      echo ""
+    done
+
+    # Overflow indicator
+    if [[ "$total_active" -gt 5 ]]; then
+      echo "   +$((total_active - 5)) more ants..."
+      echo ""
+    fi
+
+    # Footer
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "${total_active} ants active"
+
+    json_ok "{\"displayed\":true,\"ants\":$total_active}"
+    ;;
+
   swarm-timing-start)
     # Record start time for an ant
     # Usage: swarm-timing-start <ant_name>
@@ -2970,12 +3375,12 @@ ANTLOGO
     queen_file="$AETHER_ROOT/.aether/docs/QUEEN.md"
 
     # Check multiple locations for template
-    # Order: dev (runtime/) -> npm install (hub) -> legacy
+    # Order: hub (system/) -> dev (.aether/) -> repo local -> legacy
     template_file=""
     for path in \
-      "$AETHER_ROOT/runtime/templates/QUEEN.md.template" \
-      "$HOME/.aether/templates/QUEEN.md.template" \
-      "$AETHER_ROOT/.aether/templates/QUEEN.md.template"; do
+      "$HOME/.aether/system/templates/QUEEN.md.template" \
+      "$AETHER_ROOT/.aether/templates/QUEEN.md.template" \
+      "$HOME/.aether/templates/QUEEN.md.template"; do
       if [[ -f "$path" ]]; then
         template_file="$path"
         break
@@ -2993,7 +3398,9 @@ ANTLOGO
 
     # Check if template was found
     if [[ -z "$template_file" ]]; then
-      json_err "$E_FILE_NOT_FOUND" "Template not found" '{"templates_checked":["runtime/templates/QUEEN.md.template","~/.aether/templates/QUEEN.md.template",".aether/templates/QUEEN.md.template"]}'
+      json_err "$E_FILE_NOT_FOUND" \
+        "Template not found. Run: npm install -g aether && aether install to restore it." \
+        '{"templates_checked":["~/.aether/system/templates/QUEEN.md.template",".aether/templates/QUEEN.md.template","~/.aether/templates/QUEEN.md.template"]}'
       exit 1
     fi
 
@@ -3028,6 +3435,12 @@ ANTLOGO
       metadata='{"version":"unknown","last_evolved":null,"colonies_contributed":[],"promotion_thresholds":{},"stats":{}}'
     fi
 
+    # Gate 1: Validate metadata is parseable JSON BEFORE using as --argjson
+    if ! echo "$metadata" | jq -e . >/dev/null 2>&1; then
+      json_err "$E_JSON_INVALID" \
+        "QUEEN.md has a malformed METADATA block — the JSON between <!-- METADATA and --> is invalid. Try: fix the JSON in .aether/docs/QUEEN.md or run queen-init to reset."
+    fi
+
     # Extract sections content for worker priming
     # Use awk to parse markdown sections - remove header line and trailing section header
     philosophies=$(awk '/^## 📜 Philosophies$/,/^## /' "$queen_file" | tail -n +2 | sed '$d' | sed '/^$/d' | jq -Rs '.')
@@ -3062,6 +3475,41 @@ ANTLOGO
         }
       }')
 
+    # Gate 2: Validate assembled result before returning
+    if [[ -z "$result" ]] || ! echo "$result" | jq -e . >/dev/null 2>&1; then
+      json_err "$E_JSON_INVALID" \
+        "Couldn't assemble queen-read output. QUEEN.md may have formatting issues. Try: run queen-init to reset."
+    fi
+    json_ok "$result"
+    ;;
+
+  pheromone-read)
+    # Read active pheromones (FOCUS/REDIRECT) from constraints.json
+    # Used to inject active signals into worker prompts
+    constraints_file="$AETHER_ROOT/.aether/data/constraints.json"
+
+    # Initialize defaults (no local - script-level)
+    priorities='[]'
+    avoid='[]'
+
+    # Check if constraints file exists
+    if [[ -f "$constraints_file" ]]; then
+      # Read focus array as priorities
+      priorities=$(jq -c '.focus // []' "$constraints_file" 2>/dev/null || echo '[]')
+
+      # Read constraints array, extract content and source
+      avoid=$(jq -c '[.constraints[]? | {content: .content, source: .source}] // []' "$constraints_file" 2>/dev/null || echo '[]')
+    fi
+
+    # Build JSON output
+    result=$(jq -n \
+      --argjson priorities "$priorities" \
+      --argjson avoid "$avoid" \
+      '{
+        priorities: $priorities,
+        avoid: $avoid
+      }')
+
     json_ok "$result"
     ;;
 
@@ -3339,8 +3787,6 @@ ${entry}" "$queen_file" > "$tmp_file"
         is_system=true
       elif [[ "$file" == .opencode/agents/*.md ]] || [[ "$file" == .opencode/agents/**/*.md ]]; then
         is_system=true
-      elif [[ "$file" == runtime/* ]]; then
-        is_system=true
       elif [[ "$file" == bin/* ]]; then
         is_system=true
       fi
@@ -3670,8 +4116,1055 @@ ${entry}" "$queen_file" > "$tmp_file"
     if type pheromone-export &>/dev/null; then
       pheromone-export "$input_json" "$output_xml" "$schema_file"
     else
-      json_err "$E_DEPENDENCY_MISSING" "xml-utils.sh not available for pheromone export"
+      json_err "$E_DEPENDENCY_MISSING" "xml-utils.sh not available. Try: run aether update to restore utility scripts."
+    fi
+    ;;
+
+  pheromone-write)
+    # Write a pheromone signal to pheromones.json
+    # Usage: pheromone-write <type> <content> [--strength N] [--ttl TTL] [--source SOURCE] [--reason REASON]
+    #   type:       FOCUS, REDIRECT, or FEEDBACK
+    #   content:    signal text (required, max 500 chars)
+    #   --strength: 0.0-1.0 (defaults: REDIRECT=0.9, FOCUS=0.8, FEEDBACK=0.7)
+    #   --ttl:      phase_end (default), 2h, 1d, 7d, 30d, etc.
+    #   --source:   user (default), worker:builder, system
+    #   --reason:   human-readable explanation
+
+    pw_type="${1:-}"
+    pw_content="${2:-}"
+
+    # Validate type
+    if [[ -z "$pw_type" ]]; then
+      json_err "$E_VALIDATION_FAILED" "pheromone-write requires <type> argument (FOCUS, REDIRECT, or FEEDBACK)"
+    fi
+
+    pw_type=$(echo "$pw_type" | tr '[:lower:]' '[:upper:]')
+    case "$pw_type" in
+      FOCUS|REDIRECT|FEEDBACK) ;;
+      *) json_err "$E_VALIDATION_FAILED" "Invalid pheromone type: $pw_type. Must be FOCUS, REDIRECT, or FEEDBACK" ;;
+    esac
+
+    if [[ -z "$pw_content" ]]; then
+      json_err "$E_VALIDATION_FAILED" "pheromone-write requires <content> argument"
+    fi
+
+    # Parse optional flags from remaining args (after type and content)
+    pw_strength=""
+    pw_ttl="phase_end"
+    pw_source="user"
+    pw_reason=""
+
+    shift 2  # shift past type and content
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --strength) pw_strength="$2"; shift 2 ;;
+        --ttl)      pw_ttl="$2"; shift 2 ;;
+        --source)   pw_source="$2"; shift 2 ;;
+        --reason)   pw_reason="$2"; shift 2 ;;
+        *) shift ;;
+      esac
+    done
+
+    # Apply default strength by type
+    if [[ -z "$pw_strength" ]]; then
+      case "$pw_type" in
+        REDIRECT) pw_strength="0.9" ;;
+        FOCUS)    pw_strength="0.8" ;;
+        FEEDBACK) pw_strength="0.7" ;;
+      esac
+    fi
+
+    # Apply default reason by type
+    if [[ -z "$pw_reason" ]]; then
+      pw_type_lower_r=$(echo "$pw_type" | tr '[:upper:]' '[:lower:]')
+      pw_reason="User emitted via /ant:${pw_type_lower_r}"
+    fi
+
+    # Set priority by type
+    case "$pw_type" in
+      REDIRECT) pw_priority="high" ;;
+      FOCUS)    pw_priority="normal" ;;
+      FEEDBACK) pw_priority="low" ;;
+    esac
+
+    # Generate ID and timestamps
+    pw_epoch=$(date +%s)
+    pw_epoch_ms="${pw_epoch}000"
+    pw_type_lower=$(echo "$pw_type" | tr '[:upper:]' '[:lower:]')
+    pw_id="sig_${pw_type_lower}_${pw_epoch_ms}"
+    pw_created=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Compute expires_at from TTL
+    if [[ "$pw_ttl" == "phase_end" ]]; then
+      pw_expires="phase_end"
+    else
+      pw_ttl_secs=0
+      if [[ "$pw_ttl" =~ ^([0-9]+)m$ ]]; then
+        pw_ttl_secs=$(( ${BASH_REMATCH[1]} * 60 ))
+      elif [[ "$pw_ttl" =~ ^([0-9]+)h$ ]]; then
+        pw_ttl_secs=$(( ${BASH_REMATCH[1]} * 3600 ))
+      elif [[ "$pw_ttl" =~ ^([0-9]+)d$ ]]; then
+        pw_ttl_secs=$(( ${BASH_REMATCH[1]} * 86400 ))
+      fi
+      if [[ $pw_ttl_secs -gt 0 ]]; then
+        pw_expires_epoch=$(( pw_epoch + pw_ttl_secs ))
+        pw_expires=$(date -u -r "$pw_expires_epoch" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+                     date -u -d "@$pw_expires_epoch" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+                     echo "phase_end")
+      else
+        pw_expires="phase_end"
+      fi
+    fi
+
+    pw_file="$DATA_DIR/pheromones.json"
+
+    # Initialize pheromones.json if missing
+    if [[ ! -f "$pw_file" ]]; then
+      pw_colony_id="aether-dev"
+      if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+        pw_colony_id=$(jq -r '.session_id // "aether-dev"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "aether-dev")
+      fi
+      printf '{\n  "version": "1.0.0",\n  "colony_id": "%s",\n  "generated_at": "%s",\n  "signals": []\n}\n' \
+        "$pw_colony_id" "$pw_created" > "$pw_file"
+    fi
+
+    # Build signal object and append to pheromones.json
+    pw_signal=$(jq -n \
+      --arg id "$pw_id" \
+      --arg type "$pw_type" \
+      --arg priority "$pw_priority" \
+      --arg source "$pw_source" \
+      --arg created_at "$pw_created" \
+      --arg expires_at "$pw_expires" \
+      --argjson active true \
+      --argjson strength "$pw_strength" \
+      --arg reason "$pw_reason" \
+      --arg content "$pw_content" \
+      '{id: $id, type: $type, priority: $priority, source: $source, created_at: $created_at, expires_at: $expires_at, active: $active, strength: ($strength | tonumber), reason: $reason, content: {text: $content}}')
+
+    pw_updated=$(jq --argjson sig "$pw_signal" '.signals += [$sig]' "$pw_file" 2>/dev/null)
+    if [[ -z "$pw_updated" ]]; then
+      json_err "${E_JSON_INVALID:-E_JSON_INVALID}" "Failed to update pheromones.json — jq parse error"
+    fi
+    echo "$pw_updated" > "$pw_file"
+
+    # Backward compatibility: also write to constraints.json
+    pw_cfile="$DATA_DIR/constraints.json"
+    if [[ "$pw_type" == "FOCUS" ]]; then
+      if [[ ! -f "$pw_cfile" ]]; then
+        echo '{"version":"1.0","focus":[],"constraints":[]}' > "$pw_cfile"
+      fi
+      pw_cfile_updated=$(jq --arg txt "$pw_content" '
+        .focus += [$txt] |
+        if (.focus | length) > 5 then .focus = .focus[-5:] else . end
+      ' "$pw_cfile" 2>/dev/null)
+      [[ -n "$pw_cfile_updated" ]] && echo "$pw_cfile_updated" > "$pw_cfile"
+    elif [[ "$pw_type" == "REDIRECT" ]]; then
+      if [[ ! -f "$pw_cfile" ]]; then
+        echo '{"version":"1.0","focus":[],"constraints":[]}' > "$pw_cfile"
+      fi
+      pw_constraint=$(jq -n \
+        --arg id "c_${pw_epoch}" \
+        --arg content "$pw_content" \
+        --arg source "user:redirect" \
+        --arg created_at "$pw_created" \
+        '{id: $id, type: "AVOID", content: $content, source: $source, created_at: $created_at}')
+      pw_cfile_updated=$(jq --argjson c "$pw_constraint" '
+        .constraints += [$c] |
+        if (.constraints | length) > 10 then .constraints = .constraints[-10:] else . end
+      ' "$pw_cfile" 2>/dev/null)
+      [[ -n "$pw_cfile_updated" ]] && echo "$pw_cfile_updated" > "$pw_cfile"
+    fi
+
+    # Get active signal count
+    pw_active_count=$(jq '[.signals[] | select(.active == true)] | length' "$pw_file" 2>/dev/null || echo "0")
+
+    json_ok "{\"signal_id\":\"$pw_id\",\"type\":\"$pw_type\",\"active_count\":$pw_active_count}"
+    ;;
+
+  pheromone-count)
+    # Count active pheromone signals by type
+    # Usage: pheromone-count
+    # Returns: JSON with per-type counts
+
+    pc_file="$DATA_DIR/pheromones.json"
+
+    if [[ ! -f "$pc_file" ]]; then
+      json_ok '{"focus":0,"redirect":0,"feedback":0,"total":0}'
+    else
+      pc_result=$(jq -c '{
+        focus:    ([.signals[] | select(.active == true and .type == "FOCUS")]    | length),
+        redirect: ([.signals[] | select(.active == true and .type == "REDIRECT")] | length),
+        feedback: ([.signals[] | select(.active == true and .type == "FEEDBACK")] | length),
+        total:    ([.signals[] | select(.active == true)]                          | length)
+      }' "$pc_file" 2>/dev/null)
+      if [[ -z "$pc_result" ]]; then
+        json_ok '{"focus":0,"redirect":0,"feedback":0,"total":0}'
+      else
+        json_ok "$pc_result"
+      fi
+    fi
+    ;;
+
+  pheromone-read)
+    # Read pheromones from colony data with decay calculation
+    # Usage: pheromone-read [type]
+    #   type: Filter by pheromone type (focus, redirect, feedback) or 'all' (default: all)
+    # Returns: JSON object with pheromones array including effective_strength
+
+    pher_type="${1:-all}"
+    pher_file="$DATA_DIR/pheromones.json"
+
+    # Check if file exists
+    if [[ ! -f "$pher_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "Pheromones file not found. Run /ant:colonize first to initialize the colony."
+    fi
+
+    # Get current epoch for decay calculation
+    pher_now=$(date +%s)
+
+    # Apply decay and expiry at read time
+    # Decay rates: FOCUS=30d, REDIRECT=60d, FEEDBACK/PATTERN=90d
+    # effective_strength = original_strength * (1 - elapsed_days / decay_days)
+    # If effective_strength < 0.1, mark inactive
+    # Also check expires_at: if not "phase_end" and past expiry, mark inactive
+    pher_type_upper=$(echo "$pher_type" | tr '[:lower:]' '[:upper:]')
+
+    pher_result=$(jq -c \
+      --argjson now "$pher_now" \
+      --arg type_filter "$pher_type_upper" \
+      '
+      # Rough ISO-8601 to epoch: accumulate years*365d + month*30d + days + time
+      def to_epoch(ts):
+        if ts == null or ts == "" or ts == "phase_end" then null
+        else
+          (ts | split("T")) as $parts |
+          ($parts[0] | split("-")) as $d |
+          ($parts[1] | rtrimstr("Z") | split(":")) as $t |
+          (($d[0] | tonumber) - 1970) * 365 * 86400 +
+          (($d[1] | tonumber) - 1) * 30 * 86400 +
+          (($d[2] | tonumber) - 1) * 86400 +
+          ($t[0] | tonumber) * 3600 +
+          ($t[1] | tonumber) * 60 +
+          ($t[2] | rtrimstr("Z") | tonumber)
+        end;
+
+      def decay_days(t):
+        if t == "FOCUS"    then 30
+        elif t == "REDIRECT" then 60
+        else 90
+        end;
+
+      .signals | map(
+        (to_epoch(.created_at)) as $created_epoch |
+        (if $created_epoch != null then ($now - $created_epoch) / 86400 else 0 end) as $elapsed_days |
+        (decay_days(.type)) as $dd |
+        ((.strength // 0.8) * (1 - ($elapsed_days / $dd))) as $eff_raw |
+        (if $eff_raw < 0 then 0 else $eff_raw end) as $eff |
+        (to_epoch(.expires_at)) as $exp_epoch |
+        ($exp_epoch != null and $exp_epoch <= $now) as $expired |
+        ($eff < 0.1 or $expired) as $deactivate |
+        . + {
+          effective_strength: (($eff * 100 | round) / 100),
+          active: (if $deactivate then false else (.active // true) end)
+        }
+      ) |
+      map(select(.active == true)) |
+      if $type_filter != "ALL" then
+        map(select(.type == $type_filter))
+      else
+        .
+      end
+      ' "$pher_file" 2>/dev/null)
+
+    if [[ -z "$pher_result" || "$pher_result" == "null" ]]; then
+      json_ok '{"version":"1.0.0","signals":[]}'
+    else
+      pher_version=$(jq -r '.version // "1.0.0"' "$pher_file" 2>/dev/null || echo "1.0.0")
+      pher_colony=$(jq -r '.colony_id // "unknown"' "$pher_file" 2>/dev/null || echo "unknown")
+      json_ok "{\"version\":\"$pher_version\",\"colony_id\":\"$pher_colony\",\"signals\":$pher_result}"
+    fi
+    ;;
+
+  instinct-read)
+    # Read learned instincts from COLONY_STATE.json memory
+    # Usage: instinct-read [--min-confidence N] [--max N] [--domain DOMAIN]
+    # Returns: JSON with filtered, confidence-sorted instincts
+
+    ir_min_confidence="0.5"
+    ir_max="5"
+    ir_domain=""
+
+    # Parse flags from positional args
+    ir_shift=1
+    while [[ $ir_shift -le $# ]]; do
+      eval "ir_arg=\${$ir_shift}"
+      ir_shift=$((ir_shift + 1))
+      case "$ir_arg" in
+        --min-confidence)
+          eval "ir_min_confidence=\${$ir_shift}"
+          ir_shift=$((ir_shift + 1))
+          ;;
+        --max)
+          eval "ir_max=\${$ir_shift}"
+          ir_shift=$((ir_shift + 1))
+          ;;
+        --domain)
+          eval "ir_domain=\${$ir_shift}"
+          ir_shift=$((ir_shift + 1))
+          ;;
+      esac
+    done
+
+    ir_state_file="$DATA_DIR/COLONY_STATE.json"
+
+    if [[ ! -f "$ir_state_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found. Run /ant:init first."
+    fi
+
+    # Check if memory.instincts exists
+    ir_has_instincts=$(jq 'if .memory.instincts then "yes" else "no" end' "$ir_state_file" 2>/dev/null || echo "no")
+    if [[ "$ir_has_instincts" != '"yes"' ]]; then
+      json_ok '{"instincts":[],"total":0,"filtered":0}'
+    fi
+
+    ir_result=$(jq -c \
+      --argjson min_conf "$ir_min_confidence" \
+      --argjson max_count "$ir_max" \
+      --arg domain_filter "$ir_domain" \
+      '
+      (.memory.instincts // []) as $all |
+      ($all | length) as $total |
+      $all
+      | map(select(
+          (.confidence // 0) >= $min_conf
+          and (.status // "hypothesis") != "disproven"
+          and (if $domain_filter != "" then (.domain // "") == $domain_filter else true end)
+        ))
+      | sort_by(-.confidence)
+      | .[:$max_count]
+      | {
+          instincts: .,
+          total: $total,
+          filtered: (. | length)
+        }
+      ' "$ir_state_file" 2>/dev/null)
+
+    if [[ -z "$ir_result" || "$ir_result" == "null" ]]; then
+      json_ok '{"instincts":[],"total":0,"filtered":0}'
+    else
+      json_ok "$ir_result"
+    fi
+    ;;
+
+  pheromone-prime)
+    # Combine active pheromone signals and learned instincts into a prompt-ready block
+    # Usage: pheromone-prime
+    # Returns: JSON with signal_count, instinct_count, prompt_section, log_line
+
+    pp_pher_file="$DATA_DIR/pheromones.json"
+    pp_state_file="$DATA_DIR/COLONY_STATE.json"
+    pp_now=$(date +%s)
+
+    # Read active signals (same decay logic as pheromone-read)
+    pp_signals="[]"
+    if [[ -f "$pp_pher_file" ]]; then
+      pp_signals=$(jq -c \
+        --argjson now "$pp_now" \
+        '
+        def to_epoch(ts):
+          if ts == null or ts == "" or ts == "phase_end" then null
+          else
+            (ts | split("T")) as $parts |
+            ($parts[0] | split("-")) as $d |
+            ($parts[1] | rtrimstr("Z") | split(":")) as $t |
+            (($d[0] | tonumber) - 1970) * 365 * 86400 +
+            (($d[1] | tonumber) - 1) * 30 * 86400 +
+            (($d[2] | tonumber) - 1) * 86400 +
+            ($t[0] | tonumber) * 3600 +
+            ($t[1] | tonumber) * 60 +
+            ($t[2] | rtrimstr("Z") | tonumber)
+          end;
+
+        def decay_days(t):
+          if t == "FOCUS"    then 30
+          elif t == "REDIRECT" then 60
+          else 90
+          end;
+
+        .signals | map(
+          (to_epoch(.created_at)) as $created_epoch |
+          (if $created_epoch != null then ($now - $created_epoch) / 86400 else 0 end) as $elapsed_days |
+          (decay_days(.type)) as $dd |
+          ((.strength // 0.8) * (1 - ($elapsed_days / $dd))) as $eff_raw |
+          (if $eff_raw < 0 then 0 else $eff_raw end) as $eff |
+          (to_epoch(.expires_at)) as $exp_epoch |
+          ($exp_epoch != null and $exp_epoch <= $now) as $expired |
+          ($eff < 0.1 or $expired) as $deactivate |
+          . + {
+            effective_strength: (($eff * 100 | round) / 100),
+            active: (if $deactivate then false else (.active // true) end)
+          }
+        ) |
+        map(select(.active == true))
+        ' "$pp_pher_file" 2>/dev/null || echo "[]")
+    fi
+
+    if [[ -z "$pp_signals" || "$pp_signals" == "null" ]]; then
+      pp_signals="[]"
+    fi
+
+    # Read instincts (confidence >= 0.5, not disproven, max 5)
+    pp_instincts="[]"
+    if [[ -f "$pp_state_file" ]]; then
+      pp_instincts=$(jq -c \
+        '
+        (.memory.instincts // [])
+        | map(select(
+            (.confidence // 0) >= 0.5
+            and (.status // "hypothesis") != "disproven"
+          ))
+        | sort_by(-.confidence)
+        | .[:5]
+        ' "$pp_state_file" 2>/dev/null || echo "[]")
+    fi
+
+    if [[ -z "$pp_instincts" || "$pp_instincts" == "null" ]]; then
+      pp_instincts="[]"
+    fi
+
+    pp_signal_count=$(echo "$pp_signals" | jq 'length' 2>/dev/null || echo "0")
+    pp_instinct_count=$(echo "$pp_instincts" | jq 'length' 2>/dev/null || echo "0")
+
+    # Build prompt section
+    if [[ "$pp_signal_count" -eq 0 && "$pp_instinct_count" -eq 0 ]]; then
+      pp_section=""
+      pp_log_line="Primed: 0 signals, 0 instincts"
+    else
+      pp_section="--- ACTIVE SIGNALS (Colony Guidance) ---"$'\n'
+
+      # FOCUS signals
+      pp_focus=$(echo "$pp_signals" | jq -r 'map(select(.type == "FOCUS")) | .[] | "[" + ((.effective_strength * 10 | round) / 10 | tostring) + "] " + (.content.text // (if (.content | type) == "string" then .content else "" end))' 2>/dev/null || echo "")
+      if [[ -n "$pp_focus" ]]; then
+        pp_section+=$'\n'"FOCUS (Pay attention to):"$'\n'"$pp_focus"$'\n'
+      fi
+
+      # REDIRECT signals
+      pp_redirect=$(echo "$pp_signals" | jq -r 'map(select(.type == "REDIRECT")) | .[] | "[" + ((.effective_strength * 10 | round) / 10 | tostring) + "] " + (.content.text // (if (.content | type) == "string" then .content else "" end))' 2>/dev/null || echo "")
+      if [[ -n "$pp_redirect" ]]; then
+        pp_section+=$'\n'"REDIRECT (HARD CONSTRAINTS - MUST follow):"$'\n'"$pp_redirect"$'\n'
+      fi
+
+      # FEEDBACK signals
+      pp_feedback=$(echo "$pp_signals" | jq -r 'map(select(.type == "FEEDBACK")) | .[] | "[" + ((.effective_strength * 10 | round) / 10 | tostring) + "] " + (.content.text // (if (.content | type) == "string" then .content else "" end))' 2>/dev/null || echo "")
+      if [[ -n "$pp_feedback" ]]; then
+        pp_section+=$'\n'"FEEDBACK (Flexible guidance):"$'\n'"$pp_feedback"$'\n'
+      fi
+
+      # Instincts section
+      if [[ "$pp_instinct_count" -gt 0 ]]; then
+        pp_section+=$'\n'"--- INSTINCTS (Learned Behaviors) ---"$'\n'
+        pp_section+="Weight by confidence - higher = stronger guidance:"$'\n'
+        pp_instinct_lines=$(echo "$pp_instincts" | jq -r '.[] | "[" + ((.confidence * 10 | round) / 10 | tostring) + "] When " + .trigger + " -> " + .action + " (" + (.domain // "general") + ")"' 2>/dev/null || echo "")
+        if [[ -n "$pp_instinct_lines" ]]; then
+          pp_section+=$'\n'"$pp_instinct_lines"$'\n'
+        fi
+      fi
+
+      pp_section+=$'\n'"--- END COLONY CONTEXT ---"
+
+      pp_log_line="Primed: ${pp_signal_count} signals, ${pp_instinct_count} instincts"
     fi
+
+    # Escape section for JSON embedding (use printf to avoid appending extra newline)
+    pp_section_json=$(printf '%s' "$pp_section" | jq -Rs '.' 2>/dev/null || echo '""')
+    pp_log_json=$(printf '%s' "$pp_log_line" | jq -Rs '.' 2>/dev/null || echo '"Primed: 0 signals, 0 instincts"')
+
+    json_ok "{\"signal_count\":$pp_signal_count,\"instinct_count\":$pp_instinct_count,\"prompt_section\":$pp_section_json,\"log_line\":$pp_log_json}"
+    ;;
+
+  pheromone-expire)
+    # Archive expired pheromone signals to midden
+    # Usage: pheromone-expire [--phase-end-only]
+    #
+    # Two modes:
+    #   --phase-end-only  Only expire signals where expires_at == "phase_end"
+    #   (no flag)         Expire signals where expires_at is an ISO-8601 timestamp
+    #                     <= now, AND signals where effective_strength < 0.1
+
+    phe_phase_end_only="false"
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --phase-end-only) phe_phase_end_only="true"; shift ;;
+        *) shift ;;
+      esac
+    done
+
+    phe_pheromones_file="$DATA_DIR/pheromones.json"
+    phe_midden_dir="$DATA_DIR/midden"
+    phe_midden_file="$phe_midden_dir/midden.json"
+
+    # Handle missing pheromones.json gracefully
+    if [[ ! -f "$phe_pheromones_file" ]]; then
+      json_ok '{"expired_count":0,"remaining_active":0,"midden_total":0}'
+      exit 0
+    fi
+
+    # Ensure midden directory and file exist
+    mkdir -p "$phe_midden_dir"
+    if [[ ! -f "$phe_midden_file" ]]; then
+      printf '%s\n' '{"version":"1.0.0","archived_at_count":0,"signals":[]}' > "$phe_midden_file"
+    fi
+
+    phe_now_epoch=$(date +%s)
+    phe_archived_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Compute pause_duration from COLONY_STATE.json (pause-aware TTL)
+    phe_pause_duration=0
+    if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+      phe_paused_at=$(jq -r '.paused_at // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || true)
+      phe_resumed_at=$(jq -r '.resumed_at // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || true)
+      if [[ -n "$phe_paused_at" && -n "$phe_resumed_at" ]]; then
+        phe_paused_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$phe_paused_at" +%s 2>/dev/null || date -d "$phe_paused_at" +%s 2>/dev/null || echo 0)
+        phe_resumed_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$phe_resumed_at" +%s 2>/dev/null || date -d "$phe_resumed_at" +%s 2>/dev/null || echo 0)
+        if [[ "$phe_resumed_epoch" -gt "$phe_paused_epoch" ]]; then
+          phe_pause_duration=$(( phe_resumed_epoch - phe_paused_epoch ))
+        fi
+      fi
+    fi
+
+    # Identify expired signal IDs
+    # We'll use jq to find signals to expire, then update in bash
+    if [[ "$phe_phase_end_only" == "true" ]]; then
+      # Only expire signals where expires_at == "phase_end"
+      phe_expired_ids=$(jq -r '.signals[] | select(.active == true and .expires_at == "phase_end") | .id' "$phe_pheromones_file" 2>/dev/null || true)
+    else
+      # Expire time-based expired signals (pause-aware) AND decay-expired signals
+      phe_expired_ids=$(jq -r --argjson now "$phe_now_epoch" --argjson pause_secs "$phe_pause_duration" '
+        .signals[] |
+        select(.active == true) |
+        select(
+          (.expires_at != "phase_end" and .expires_at != null and .expires_at != "") and
+          (
+            # ISO-8601 timestamp expiry (pause-aware: add pause_duration to expires_at before comparing)
+            (
+              .expires_at |
+              # Convert ISO-8601 to approximate epoch via string parsing
+              (
+                (split("T")[0] | split("-")) as $d |
+                (split("T")[1] | split(":")) as $t |
+                ($d[0] | tonumber) as $y |
+                ($d[1] | tonumber) as $mo |
+                ($d[2] | tonumber) as $day |
+                ($t[0] | tonumber) as $h |
+                ($t[1] | tonumber) as $m |
+                (($t[2] // "0") | gsub("[^0-9]";"") | if . == "" then 0 else tonumber end) as $s |
+                # Rough epoch: years*365.25*86400 + months*30.44*86400 + day*86400 + time
+                (($y - 1970) * 31557600) + (($mo - 1) * 2629800) + (($day - 1) * 86400) + ($h * 3600) + ($m * 60) + $s
+              )
+            ) + $pause_secs <= $now
+          )
+        ) |
+        .id
+      ' "$phe_pheromones_file" 2>/dev/null || true)
+    fi
+
+    # Count expired signals
+    phe_expired_count=0
+    if [[ -n "$phe_expired_ids" ]]; then
+      phe_expired_count=$(echo "$phe_expired_ids" | grep -c . 2>/dev/null || echo 0)
+    fi
+
+    # If nothing to expire, return counts
+    if [[ "$phe_expired_count" -eq 0 ]]; then
+      phe_remaining=$(jq '[.signals[] | select(.active == true)] | length' "$phe_pheromones_file" 2>/dev/null || echo 0)
+      phe_midden_total=$(jq '.signals | length' "$phe_midden_file" 2>/dev/null || echo 0)
+      json_ok "{\"expired_count\":0,\"remaining_active\":$phe_remaining,\"midden_total\":$phe_midden_total}"
+      exit 0
+    fi
+
+    # Build jq args for IDs to expire
+    phe_id_array=$(echo "$phe_expired_ids" | jq -R . | jq -s . 2>/dev/null || echo '[]')
+
+    # Extract expired signal objects (with archived_at added)
+    phe_expired_objects=$(jq --argjson ids "$phe_id_array" --arg archived_at "$phe_archived_at" '
+      [.signals[] | select(.id as $id | $ids | any(. == $id)) | . + {"archived_at": $archived_at, "active": false}]
+    ' "$phe_pheromones_file" 2>/dev/null || echo '[]')
+
+    # Update pheromones.json: set active=false for expired signals (do NOT remove them)
+    phe_updated_pheromones=$(jq --argjson ids "$phe_id_array" '
+      .signals = [.signals[] | if (.id as $id | $ids | any(. == $id)) then .active = false else . end]
+    ' "$phe_pheromones_file" 2>/dev/null)
+
+    if [[ -n "$phe_updated_pheromones" ]]; then
+      printf '%s\n' "$phe_updated_pheromones" > "$phe_pheromones_file"
+    fi
+
+    # Append expired signals to midden.json
+    phe_midden_updated=$(jq --argjson new_signals "$phe_expired_objects" '
+      .signals += $new_signals |
+      .archived_at_count = (.signals | length)
+    ' "$phe_midden_file" 2>/dev/null)
+
+    if [[ -n "$phe_midden_updated" ]]; then
+      printf '%s\n' "$phe_midden_updated" > "$phe_midden_file"
+    fi
+
+    phe_remaining_active=$(jq '[.signals[] | select(.active == true)] | length' "$phe_pheromones_file" 2>/dev/null || echo 0)
+    phe_midden_total=$(jq '.signals | length' "$phe_midden_file" 2>/dev/null || echo 0)
+
+    json_ok "{\"expired_count\":$phe_expired_count,\"remaining_active\":$phe_remaining_active,\"midden_total\":$phe_midden_total}"
+    ;;
+
+  eternal-init)
+    # Initialize the ~/.aether/eternal/ directory and memory.json schema
+    # Usage: eternal-init
+    # Idempotent: safe to call multiple times
+
+    ei_eternal_dir="$HOME/.aether/eternal"
+    ei_memory_file="$ei_eternal_dir/memory.json"
+    ei_already_existed="false"
+
+    mkdir -p "$ei_eternal_dir"
+
+    if [[ -f "$ei_memory_file" ]]; then
+      ei_already_existed="true"
+    else
+      ei_created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"created_at\": \"$ei_created_at\",
+  \"colonies\": [],
+  \"high_value_signals\": [],
+  \"cross_session_patterns\": []
+}" > "$ei_memory_file"
+    fi
+
+    json_ok "{\"dir\":\"$ei_eternal_dir\",\"initialized\":true,\"already_existed\":$ei_already_existed}"
+    ;;
+
+  # ============================================================================
+  # XML Exchange Commands
+  # ============================================================================
+
+  pheromone-export-xml)
+    # Export pheromones.json to XML format
+    # Usage: pheromone-export-xml [output_file]
+    # Default output: .aether/exchange/pheromones.xml
+
+    pex_output="${1:-$SCRIPT_DIR/exchange/pheromones.xml}"
+    pex_pheromones="$DATA_DIR/pheromones.json"
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Check pheromones.json exists
+    if [[ ! -f "$pex_pheromones" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "Couldn't find pheromones.json. Try: run /ant:init first."
+    fi
+
+    # Ensure output directory exists
+    mkdir -p "$(dirname "$pex_output")"
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/pheromone-xml.sh"
+
+    # Call the export function
+    xml-pheromone-export "$pex_pheromones" "$pex_output"
+    ;;
+
+  pheromone-import-xml)
+    # Import pheromone signals from XML into pheromones.json
+    # Usage: pheromone-import-xml <xml_file> [colony_prefix]
+    # When colony_prefix is provided, imported signal IDs are tagged with "${prefix}:" before merge
+
+    pix_xml="${1:-}"
+    pix_colony_prefix="${2:-}"
+    pix_pheromones="$DATA_DIR/pheromones.json"
+
+    if [[ -z "$pix_xml" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Missing XML file argument. Try: pheromone-import-xml <xml_file> [colony_prefix]."
+    fi
+
+    if [[ ! -f "$pix_xml" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "XML file not found: $pix_xml. Try: check the file path."
+    fi
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/pheromone-xml.sh"
+
+    # Import XML to get JSON signals
+    pix_imported=$(xml-pheromone-import "$pix_xml")
+
+    # Extract actual signal array from result.json | fromjson | .signals
+    # (result.signals is an integer count — must unpack result.json to get the array)
+    pix_raw_signals=$(echo "$pix_imported" | jq -r '.result.json // "{}"' | jq -c '.signals // []' 2>/dev/null || echo '[]')
+
+    # Apply colony prefix to imported signal IDs (when provided)
+    # This prevents ID collisions and tags signals with their source colony
+    if [[ -n "$pix_colony_prefix" ]]; then
+      pix_prefixed_signals=$(echo "$pix_raw_signals" | jq --arg prefix "$pix_colony_prefix" '[.[] | .id = ($prefix + ":" + .id)]' 2>/dev/null || echo '[]')
+    else
+      pix_prefixed_signals="$pix_raw_signals"
+    fi
+
+    # If pheromones.json exists, merge; otherwise create
+    if [[ -f "$pix_pheromones" ]]; then
+      # Merge: imported signals first, existing signals last
+      # map(last) keeps current colony's version on ID collision — current colony always wins
+      pix_merged=$(jq -s --argjson new_signals "$pix_prefixed_signals" '
+        .[0] as $existing |
+        {
+          signals: ([$new_signals[], $existing.signals[]] | group_by(.id) | map(last)),
+          version: $existing.version,
+          colony_id: $existing.colony_id
+        }
+      ' "$pix_pheromones" 2>/dev/null)
+
+      if [[ -n "$pix_merged" ]]; then
+        printf '%s\n' "$pix_merged" > "$pix_pheromones"
+      fi
+    fi
+
+    pix_count=$(echo "$pix_raw_signals" | jq 'length' 2>/dev/null || echo 0)
+    json_ok "{\"imported\":true,\"signal_count\":$pix_count,\"source\":\"$pix_xml\"}"
+    ;;
+
+  pheromone-validate-xml)
+    # Validate pheromone XML against XSD schema
+    # Usage: pheromone-validate-xml <xml_file>
+
+    pvx_xml="${1:-}"
+    pvx_xsd="$SCRIPT_DIR/schemas/pheromone.xsd"
+
+    if [[ -z "$pvx_xml" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Missing XML file argument. Try: pheromone-validate-xml <xml_file>."
+    fi
+
+    if [[ ! -f "$pvx_xml" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "XML file not found: $pvx_xml. Try: check the file path."
+    fi
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/pheromone-xml.sh"
+
+    # Call validate function
+    xml-pheromone-validate "$pvx_xml" "$pvx_xsd"
+    ;;
+
+  wisdom-export-xml)
+    # Export queen wisdom to XML format
+    # Usage: wisdom-export-xml [input_json] [output_xml]
+    # Default input: .aether/data/queen-wisdom.json
+    # Default output: .aether/exchange/queen-wisdom.xml
+
+    wex_input="${1:-$DATA_DIR/queen-wisdom.json}"
+    wex_output="${2:-$SCRIPT_DIR/exchange/queen-wisdom.xml}"
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Look for wisdom data: check specified file, then COLONY_STATE memory
+    if [[ ! -f "$wex_input" ]]; then
+      # Try to extract from COLONY_STATE.json memory field
+      if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+        wex_memory=$(jq '.memory // {}' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo '{}')
+        if [[ "$wex_memory" != "{}" && "$wex_memory" != "null" ]]; then
+          # Create minimal wisdom JSON from colony memory
+          wex_created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"metadata\": {\"created\": \"$wex_created_at\", \"colony_id\": \"$(jq -r '.goal // \"unknown\"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null)\"},
+  \"philosophies\": [],
+  \"patterns\": $(echo "$wex_memory" | jq '[.instincts // [] | .[] | {\"id\": (. | @base64), \"content\": ., \"confidence\": 0.7, \"domain\": \"general\", \"source\": \"colony_memory\"}]' 2>/dev/null || echo '[]')
+}" > "$wex_input"
+        fi
+      fi
+    fi
+
+    # If still no wisdom data, create minimal skeleton
+    if [[ ! -f "$wex_input" ]]; then
+      wex_created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      mkdir -p "$(dirname "$wex_input")"
+      printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"metadata\": {\"created\": \"$wex_created_at\", \"colony_id\": \"unknown\"},
+  \"philosophies\": [],
+  \"patterns\": []
+}" > "$wex_input"
+    fi
+
+    # Ensure output directory exists
+    mkdir -p "$(dirname "$wex_output")"
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/wisdom-xml.sh"
+
+    # Call the export function
+    xml-wisdom-export "$wex_input" "$wex_output"
+    ;;
+
+  wisdom-import-xml)
+    # Import wisdom from XML into JSON format
+    # Usage: wisdom-import-xml <xml_file> [output_json]
+
+    wix_xml="${1:-}"
+    wix_output="${2:-$DATA_DIR/queen-wisdom.json}"
+
+    if [[ -z "$wix_xml" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Missing XML file argument. Try: wisdom-import-xml <xml_file> [output_json]."
+    fi
+
+    if [[ ! -f "$wix_xml" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "XML file not found: $wix_xml. Try: check the file path."
+    fi
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Ensure output directory exists
+    mkdir -p "$(dirname "$wix_output")"
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/wisdom-xml.sh"
+
+    # Call the import function
+    xml-wisdom-import "$wix_xml" "$wix_output"
+    ;;
+
+  registry-export-xml)
+    # Export colony registry to XML format
+    # Usage: registry-export-xml [input_json] [output_xml]
+    # Default input: .aether/data/colony-registry.json
+    # Default output: .aether/exchange/colony-registry.xml
+
+    rex_input="${1:-$DATA_DIR/colony-registry.json}"
+    rex_output="${2:-$SCRIPT_DIR/exchange/colony-registry.xml}"
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # If no registry file exists, generate from chambers
+    if [[ ! -f "$rex_input" ]]; then
+      rex_chambers_dir="$AETHER_ROOT/.aether/chambers"
+      rex_generated_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      rex_colonies="[]"
+
+      if [[ -d "$rex_chambers_dir" ]]; then
+        # Scan chambers for manifest.json files
+        rex_colonies=$(
+          for manifest in "$rex_chambers_dir"/*/manifest.json; do
+            [[ -f "$manifest" ]] || continue
+            jq -c '{
+              id: (.colony_id // .goal // "unknown"),
+              name: (.goal // "Unnamed Colony"),
+              created_at: (.created_at // "unknown"),
+              sealed_at: (.sealed_at // null),
+              status: (if .sealed_at then "sealed" else "active" end),
+              chamber: input_filename
+            }' "$manifest" 2>/dev/null || true
+          done | jq -s '.' 2>/dev/null || echo '[]'
+        )
+      fi
+
+      mkdir -p "$(dirname "$rex_input")"
+      printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"generated_at\": \"$rex_generated_at\",
+  \"colonies\": $rex_colonies
+}" > "$rex_input"
+    fi
+
+    # Ensure output directory exists
+    mkdir -p "$(dirname "$rex_output")"
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/registry-xml.sh"
+
+    # Call the export function
+    xml-registry-export "$rex_input" "$rex_output"
+    ;;
+
+  registry-import-xml)
+    # Import colony registry from XML into JSON format
+    # Usage: registry-import-xml <xml_file> [output_json]
+
+    rix_xml="${1:-}"
+    rix_output="${2:-$DATA_DIR/colony-registry.json}"
+
+    if [[ -z "$rix_xml" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Missing XML file argument. Try: registry-import-xml <xml_file> [output_json]."
+    fi
+
+    if [[ ! -f "$rix_xml" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "XML file not found: $rix_xml. Try: check the file path."
+    fi
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    # Ensure output directory exists
+    mkdir -p "$(dirname "$rix_output")"
+
+    # Source the exchange script
+    source "$SCRIPT_DIR/exchange/registry-xml.sh"
+
+    # Call the import function
+    xml-registry-import "$rix_xml" "$rix_output"
+    ;;
+
+  colony-archive-xml)
+    # Export combined colony archive XML containing pheromones, wisdom, and registry
+    # Usage: colony-archive-xml [output_file]
+    # Default output: .aether/exchange/colony-archive.xml
+    # Always filters to active-only pheromone signals
+
+    # Graceful degradation: check for xmllint
+    if ! command -v xmllint >/dev/null 2>&1; then
+      json_err "$E_FEATURE_UNAVAILABLE" "xmllint is not installed. Try: xcode-select --install on macOS."
+    fi
+
+    cax_output="${1:-$SCRIPT_DIR/exchange/colony-archive.xml}"
+    mkdir -p "$(dirname "$cax_output")"
+
+    # Step 1: Filter active-only pheromone signals to a temp file
+    cax_tmp_pheromones=$(mktemp)
+    if [[ -f "$DATA_DIR/pheromones.json" ]]; then
+      jq '{
+        version: .version,
+        colony_id: .colony_id,
+        generated_at: .generated_at,
+        signals: [.signals[] | select(.active == true)]
+      }' "$DATA_DIR/pheromones.json" > "$cax_tmp_pheromones" 2>/dev/null
+    else
+      printf '%s\n' '{"version":"1.0","colony_id":"unknown","generated_at":"","signals":[]}' > "$cax_tmp_pheromones"
+    fi
+
+    # Step 2: Export each section to temp XML files
+    cax_tmp_dir=$(mktemp -d)
+
+    # Pheromone section (using filtered active-only)
+    source "$SCRIPT_DIR/exchange/pheromone-xml.sh"
+    xml-pheromone-export "$cax_tmp_pheromones" "$cax_tmp_dir/pheromones.xml" 2>/dev/null || true
+
+    # Wisdom section — reuse wisdom-export-xml fallback logic
+    source "$SCRIPT_DIR/exchange/wisdom-xml.sh"
+    cax_wisdom_input="$DATA_DIR/queen-wisdom.json"
+    if [[ ! -f "$cax_wisdom_input" ]]; then
+      # Try extracting from COLONY_STATE.json memory field
+      if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+        cax_wex_memory=$(jq '.memory // {}' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo '{}')
+        if [[ "$cax_wex_memory" != "{}" && "$cax_wex_memory" != "null" ]]; then
+          cax_wex_created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+          cax_wisdom_input="$cax_tmp_dir/wisdom-input.json"
+          printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"metadata\": {\"created\": \"$cax_wex_created_at\", \"colony_id\": \"$(jq -r '.goal // \"unknown\"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null)\"},
+  \"philosophies\": [],
+  \"patterns\": $(echo "$cax_wex_memory" | jq '[.instincts // [] | .[] | {"id": (. | @base64), "content": ., "confidence": 0.7, "domain": "general", "source": "colony_memory"}]' 2>/dev/null || echo '[]')
+}" > "$cax_wisdom_input"
+        fi
+      fi
+    fi
+    if [[ -f "$cax_wisdom_input" ]]; then
+      xml-wisdom-export "$cax_wisdom_input" "$cax_tmp_dir/wisdom.xml" 2>/dev/null || true
+    fi
+
+    # Registry section — reuse registry-export-xml on-demand generation logic
+    source "$SCRIPT_DIR/exchange/registry-xml.sh"
+    cax_registry_input="$DATA_DIR/colony-registry.json"
+    if [[ ! -f "$cax_registry_input" ]]; then
+      cax_rex_chambers_dir="$AETHER_ROOT/.aether/chambers"
+      cax_rex_generated_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      cax_rex_colonies="[]"
+      if [[ -d "$cax_rex_chambers_dir" ]]; then
+        cax_rex_colonies=$(
+          for manifest in "$cax_rex_chambers_dir"/*/manifest.json; do
+            [[ -f "$manifest" ]] || continue
+            jq -c '{
+              id: (.colony_id // .goal // "unknown"),
+              name: (.goal // "Unnamed Colony"),
+              created_at: (.created_at // "unknown"),
+              sealed_at: (.sealed_at // null),
+              status: (if .sealed_at then "sealed" else "active" end),
+              chamber: input_filename
+            }' "$manifest" 2>/dev/null || true
+          done | jq -s '.' 2>/dev/null || echo '[]'
+        )
+      fi
+      cax_registry_input="$cax_tmp_dir/registry-input.json"
+      printf '%s\n' "{
+  \"version\": \"1.0.0\",
+  \"generated_at\": \"$cax_rex_generated_at\",
+  \"colonies\": $cax_rex_colonies
+}" > "$cax_registry_input"
+    fi
+    xml-registry-export "$cax_registry_input" "$cax_tmp_dir/registry.xml" 2>/dev/null || true
+
+    # Step 3: Build combined XML
+    cax_colony_id=$(jq -r '.goal // "unknown"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '-' | sed 's/^-//;s/-$//')
+    [[ -z "$cax_colony_id" || "$cax_colony_id" == "unknown" ]] && cax_colony_id="unknown"
+    cax_sealed_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    cax_pheromone_count=$(jq '.signals | length' "$cax_tmp_pheromones" 2>/dev/null || echo 0)
+
+    {
+      printf '<?xml version="1.0" encoding="UTF-8"?>\n'
+      printf '<colony-archive\n'
+      printf '    xmlns="http://aether.colony/schemas/archive/1.0"\n'
+      printf '    colony_id="%s"\n' "$cax_colony_id"
+      printf '    sealed_at="%s"\n' "$cax_sealed_at"
+      printf '    version="1.0.0"\n'
+      printf '    pheromone_count="%s">\n' "$cax_pheromone_count"
+
+      # Append pheromone section (strip XML declaration)
+      if [[ -f "$cax_tmp_dir/pheromones.xml" ]]; then
+        sed '1{/^<?xml/d;}' "$cax_tmp_dir/pheromones.xml"
+      fi
+
+      # Append wisdom section (strip XML declaration)
+      if [[ -f "$cax_tmp_dir/wisdom.xml" ]]; then
+        sed '1{/^<?xml/d;}' "$cax_tmp_dir/wisdom.xml"
+      fi
+
+      # Append registry section (strip XML declaration)
+      if [[ -f "$cax_tmp_dir/registry.xml" ]]; then
+        sed '1{/^<?xml/d;}' "$cax_tmp_dir/registry.xml"
+      fi
+
+      printf '</colony-archive>\n'
+    } > "$cax_output"
+
+    # Step 4: Validate well-formedness
+    if xmllint --noout "$cax_output" 2>/dev/null; then
+      cax_valid=true
+    else
+      cax_valid=false
+    fi
+
+    # Step 5: Cleanup temp files
+    rm -rf "$cax_tmp_dir" "$cax_tmp_pheromones"
+
+    json_ok "{\"path\":\"$cax_output\",\"valid\":$cax_valid,\"colony_id\":\"$cax_colony_id\",\"pheromone_count\":$cax_pheromone_count}"
     ;;
 
   # ============================================================================
@@ -3684,7 +5177,24 @@ ${entry}" "$queen_file" > "$tmp_file"
     session_id="${2:-$(date +%s)_$(openssl rand -hex 4 2>/dev/null || echo $$)}"
     goal="${3:-}"
 
+    # ARCH-03: Rotate spawn-tree.txt at session start to prevent unbounded growth.
+    # Archives previous session's tree to a timestamped file; caps archive count at 5.
+    _rotate_spawn_tree() {
+        local tree_file="$DATA_DIR/spawn-tree.txt"
+        [[ -f "$tree_file" ]] && [[ -s "$tree_file" ]] || return 0
+        mkdir -p "$DATA_DIR/spawn-tree-archive"
+        local archive_ts
+        archive_ts=$(date +%Y%m%d_%H%M%S)
+        cp "$tree_file" "$DATA_DIR/spawn-tree-archive/spawn-tree.${archive_ts}.txt" 2>/dev/null || true
+        > "$tree_file"  # Truncate in-place — preserves file handle for tail -f watchers
+        # Keep only 5 archives
+        ls -t "$DATA_DIR/spawn-tree-archive"/spawn-tree.*.txt 2>/dev/null \
+            | tail -n +6 | xargs rm -f 2>/dev/null || true
+    }
+    _rotate_spawn_tree
+
     session_file="$DATA_DIR/session.json"
+    baseline=$(git rev-parse HEAD 2>/dev/null || echo "")
 
     cat > "$session_file" << EOF
 {
@@ -3697,6 +5207,7 @@ ${entry}" "$queen_file" > "$tmp_file"
   "current_milestone": "First Mound",
   "suggested_next": "/ant:plan",
   "context_cleared": false,
+  "baseline_commit": "$baseline",
   "resumed_at": null,
   "active_todos": [],
   "summary": "Session initialized"
@@ -3740,6 +5251,9 @@ EOF
       current_milestone=$(jq -r '.milestone // "First Mound"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "$current_milestone")
     fi
 
+    # Capture current git HEAD for drift detection
+    baseline=$(git rev-parse HEAD 2>/dev/null || echo "")
+
     # Build updated session
     echo "$current_session" | jq --arg cmd "$cmd_run" \
       --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
@@ -3749,6 +5263,7 @@ EOF
       --argjson phase "$current_phase" \
       --arg milestone "$current_milestone" \
       --argjson todos "$todos" \
+      --arg baseline "$baseline" \
       '.last_command = $cmd |
        .last_command_at = $ts |
        .suggested_next = $suggested |
@@ -3756,7 +5271,8 @@ EOF
        .colony_goal = $goal |
        .current_phase = $phase |
        .current_milestone = $milestone |
-       .active_todos = $todos' > "$session_file"
+       .active_todos = $todos |
+       .baseline_commit = $baseline' > "$session_file"
 
     json_ok "{\"updated\":true,\"command\":\"$cmd_run\"}"
     ;;
@@ -3790,18 +5306,18 @@ EOF
     ;;
 
   session-is-stale)
-    # Check if session is stale (returns true/false)
+    # Check if session is stale (returns JSON with is_stale boolean)
     session_file="$DATA_DIR/session.json"
 
     if [[ ! -f "$session_file" ]]; then
-      echo "true"
+      json_ok '{"is_stale":true}'
       exit 0
     fi
 
     last_cmd_ts=$(jq -r '.last_command_at // .started_at // empty' "$session_file" 2>/dev/null)
 
     if [[ -z "$last_cmd_ts" ]]; then
-      echo "true"
+      json_ok '{"is_stale":true}'
       exit 0
     fi
 
@@ -3809,7 +5325,11 @@ EOF
     now_epoch=$(date +%s)
     age_hours=$(( (now_epoch - last_epoch) / 3600 ))
 
-    [[ $age_hours -gt 24 ]] && echo "true" || echo "false"
+    if [[ $age_hours -gt 24 ]]; then
+      json_ok '{"is_stale":true}'
+    else
+      json_ok '{"is_stale":false}'
+    fi
     ;;
 
   session-clear)
@@ -3841,16 +5361,34 @@ EOF
          '.resumed_at = $ts | .context_cleared = false' "$session_file" > "$session_file.tmp" && mv "$session_file.tmp" "$session_file"
       json_ok "{\"resumed\":true,\"timestamp\":\"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\"}"
     else
-      json_err "$E_RESOURCE_NOT_FOUND" "No session to mark as resumed"
+      json_err "$E_RESOURCE_NOT_FOUND" "No active session to mark as resumed. Try: run /ant:init to start a new session."
     fi
     ;;
 
   session-summary)
-    # Get human-readable session summary
+    # Get session summary (human-readable or JSON)
     session_file="$DATA_DIR/session.json"
+    json_mode="false"
+
+    # Parse --json flag (command name already shifted by main dispatch)
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --json)
+          json_mode="true"
+          shift
+          ;;
+        *)
+          shift
+          ;;
+      esac
+    done
 
     if [[ ! -f "$session_file" ]]; then
-      echo "No active session found."
+      if [[ "$json_mode" == "true" ]]; then
+        json_ok '{"exists":false,"goal":null,"phase":0}'
+      else
+        echo "No active session found."
+      fi
       exit 0
     fi
 
@@ -3862,15 +5400,151 @@ EOF
     suggested=$(jq -r '.suggested_next // "None"' "$session_file")
     cleared=$(jq -r '.context_cleared // false' "$session_file")
 
-    echo "📋 Session Summary"
-    echo "=================="
-    echo "Goal: $goal"
-    [[ "$phase" != "0" ]] && echo "Phase: $phase"
-    echo "Milestone: $milestone"
-    echo "Last Command: $last_cmd"
-    echo "Last Active: $last_at"
-    [[ "$suggested" != "None" ]] && echo "Suggested Next: $suggested"
-    [[ "$cleared" == "true" ]] && echo "Status: Context was cleared"
+    if [[ "$json_mode" == "true" ]]; then
+      # Escape goal for JSON
+      goal_escaped=$(echo "$goal" | jq -Rs . | tr -d '\n')
+      milestone_escaped=$(echo "$milestone" | jq -Rs . | tr -d '\n')
+      last_cmd_escaped=$(echo "$last_cmd" | jq -Rs . | tr -d '\n')
+      last_at_escaped=$(echo "$last_at" | jq -Rs . | tr -d '\n')
+      suggested_escaped=$(echo "$suggested" | jq -Rs . | tr -d '\n')
+      json_ok "{\"exists\":true,\"goal\":$goal_escaped,\"phase\":$phase,\"milestone\":$milestone_escaped,\"last_command\":$last_cmd_escaped,\"last_active\":$last_at_escaped,\"suggested_next\":$suggested_escaped,\"context_cleared\":$cleared}"
+    else
+      echo "Session Summary"
+      echo "=================="
+      echo "Goal: $goal"
+      [[ "$phase" != "0" ]] && echo "Phase: $phase"
+      echo "Milestone: $milestone"
+      echo "Last Command: $last_cmd"
+      echo "Last Active: $last_at"
+      [[ "$suggested" != "None" ]] && echo "Suggested Next: $suggested"
+      [[ "$cleared" == "true" ]] && echo "Status: Context was cleared"
+    fi
+    ;;
+
+  generate-progress-bar)
+    generate-progress-bar "$@"
+    ;;
+  print-standard-banner)
+    print-standard-banner "$@"
+    ;;
+  print-next-up)
+    print-next-up "$@"
+    ;;
+
+  # ============================================
+  # LOCK MANAGEMENT
+  # ============================================
+
+  force-unlock)
+    # Emergency lock cleanup — removes all lock files
+    # Usage: force-unlock [--yes]
+    # Without --yes, lists locks and asks for confirmation in interactive mode
+    lock_dir="${AETHER_ROOT:-.}/.aether/locks"
+    auto_yes=false
+    [[ "${1:-}" == "--yes" ]] && auto_yes=true
+
+    if [[ ! -d "$lock_dir" ]]; then
+      json_ok '{"removed":0,"message":"No locks directory found"}'
+      exit 0
+    fi
+
+    lock_files=$(find "$lock_dir" -name "*.lock" -o -name "*.lock.pid" 2>/dev/null)
+
+    if [[ -z "$lock_files" ]]; then
+      json_ok '{"removed":0,"message":"No lock files found"}'
+      exit 0
+    fi
+
+    lock_count=$(echo "$lock_files" | grep -c '\.lock$' || echo "0")
+
+    if [[ "$auto_yes" != "true" ]]; then
+      if [[ -t 2 ]]; then
+        echo "" >&2
+        echo "Lock files found in $lock_dir:" >&2
+        echo "$lock_files" | while read -r f; do
+          [[ "$f" == *.pid ]] && continue
+          pid_content=$(cat "${f}.pid" 2>/dev/null || echo "unknown")
+          echo "  $f (PID: $pid_content)" >&2
+        done
+        printf "Remove all %d lock(s)? [y/N] " "$lock_count" >&2
+        read -r response < /dev/tty
+        if [[ ! "$response" =~ ^[Yy]$ ]]; then
+          json_ok '{"removed":0,"message":"Cancelled by user"}'
+          exit 0
+        fi
+      else
+        json_err "$E_VALIDATION_FAILED" "force-unlock requires --yes flag in non-interactive mode"
+      fi
+    fi
+
+    rm -f "$lock_dir"/*.lock "$lock_dir"/*.lock.pid 2>/dev/null || true
+    export LOCK_ACQUIRED=false
+    export CURRENT_LOCK=""
+    json_ok "{\"removed\":$lock_count,\"message\":\"All locks cleared\"}"
+    ;;
+
+  #=============================================================================
+  # SEMANTIC COMMANDS
+  #=============================================================================
+
+  semantic-init)
+    # Initialize semantic store
+    semantic-init
+    ;;
+
+  semantic-index)
+    # Index text for semantic search
+    # Usage: semantic-index <text> <source> [entry_id]
+    text="${2:-}"
+    source="${3:-unknown}"
+    entry_id="${4:-}"
+
+    if [[ -z "$text" ]]; then
+      json_err "$E_VALIDATION_FAILED" "semantic-index requires text argument"
+      exit 1
+    fi
+
+    semantic-index "$text" "$source" "$entry_id"
+    ;;
+
+  semantic-search)
+    # Search for similar entries
+    # Usage: semantic-search <query> [top_k] [threshold] [source_filter]
+    query="${2:-}"
+    top_k="${3:-5}"
+    threshold="${4:-0.5}"
+    source_filter="${5:-}"
+
+    if [[ -z "$query" ]]; then
+      json_err "$E_VALIDATION_FAILED" "semantic-search requires query argument"
+      exit 1
+    fi
+
+    semantic-search "$query" "$top_k" "$threshold" "$source_filter"
+    ;;
+
+  semantic-rebuild)
+    # Rebuild semantic index from all data sources
+    semantic-rebuild
+    ;;
+
+  semantic-status)
+    # Get semantic layer status
+    semantic-status
+    ;;
+
+  semantic-context)
+    # Get context for task (for worker injection)
+    # Usage: semantic-context <task_description> [max_results]
+    task="${2:-}"
+    max_results="${3:-3}"
+
+    if [[ -z "$task" ]]; then
+      json_ok "[]" "No task provided"
+      exit 0
+    fi
+
+    semantic-get-context "$task" "$max_results"
     ;;
 
   *)