aether-colony 3.1.4 → 3.1.15

package/runtime/aether-utils.sh

@@ -27,6 +27,20 @@ CURRENT_LOCK=${CURRENT_LOCK:-""}
 [[ -f "$SCRIPT_DIR/utils/atomic-write.sh" ]] && source "$SCRIPT_DIR/utils/atomic-write.sh"
 [[ -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"
+
+# Fallback error constants if error-handler.sh wasn't sourced
+# This prevents "unbound variable" errors in older installations
+: "${E_UNKNOWN:=E_UNKNOWN}"
+: "${E_HUB_NOT_FOUND:=E_HUB_NOT_FOUND}"
+: "${E_REPO_NOT_INITIALIZED:=E_REPO_NOT_INITIALIZED}"
+: "${E_FILE_NOT_FOUND:=E_FILE_NOT_FOUND}"
+: "${E_JSON_INVALID:=E_JSON_INVALID}"
+: "${E_LOCK_FAILED:=E_LOCK_FAILED}"
+: "${E_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
@@ -74,20 +88,379 @@ fi
 # --- Caste emoji helper ---
 get_caste_emoji() {
   case "$1" in
-    *Queen*|*QUEEN*|*queen*) echo "👑" ;;
-    *Builder*|*builder*|*Bolt*|*Hammer*|*Forge*|*Mason*|*Brick*|*Anvil*|*Weld*) echo "🔨" ;;
-    *Watcher*|*watcher*|*Vigil*|*Sentinel*|*Guard*|*Keen*|*Sharp*|*Hawk*|*Alert*) echo "👁️" ;;
-    *Scout*|*scout*|*Swift*|*Dash*|*Ranger*|*Track*|*Seek*|*Path*|*Roam*|*Quest*) echo "🔍" ;;
-    *Colonizer*|*colonizer*|*Pioneer*|*Map*|*Chart*|*Venture*|*Explore*|*Compass*|*Atlas*|*Trek*) echo "🗺️" ;;
-    *Architect*|*architect*|*Blueprint*|*Draft*|*Design*|*Plan*|*Schema*|*Frame*|*Sketch*|*Model*) echo "🏛️" ;;
-    *Chaos*|*chaos*|*Probe*|*Stress*|*Shake*|*Twist*|*Snap*|*Breach*|*Surge*|*Jolt*) echo "🎲" ;;
-    *Archaeologist*|*archaeologist*|*Relic*|*Fossil*|*Dig*|*Shard*|*Epoch*|*Strata*|*Lore*|*Glyph*) echo "🏺" ;;
-    *Oracle*|*oracle*|*Sage*|*Seer*|*Vision*|*Augur*|*Mystic*|*Sibyl*|*Delph*|*Pythia*) echo "🔮" ;;
-    *Route*|*route*) echo "📋" ;;
+    *Queen*|*QUEEN*|*queen*) echo "👑🐜" ;;
+    *Builder*|*builder*|*Bolt*|*Hammer*|*Forge*|*Mason*|*Brick*|*Anvil*|*Weld*) echo "🔨🐜" ;;
+    *Watcher*|*watcher*|*Vigil*|*Sentinel*|*Guard*|*Keen*|*Sharp*|*Hawk*|*Alert*) echo "👁️🐜" ;;
+    *Scout*|*scout*|*Swift*|*Dash*|*Ranger*|*Track*|*Seek*|*Path*|*Roam*|*Quest*) echo "🔍🐜" ;;
+    *Colonizer*|*colonizer*|*Pioneer*|*Map*|*Chart*|*Venture*|*Explore*|*Compass*|*Atlas*|*Trek*) echo "🗺️🐜" ;;
+    *Surveyor*|*surveyor*|*Chart*|*Plot*|*Survey*|*Measure*|*Assess*|*Gauge*|*Sound*|*Fathom*) echo "📊🐜" ;;
+    *Architect*|*architect*|*Blueprint*|*Draft*|*Design*|*Plan*|*Schema*|*Frame*|*Sketch*|*Model*) echo "🏛️🐜" ;;
+    *Chaos*|*chaos*|*Probe*|*Stress*|*Shake*|*Twist*|*Snap*|*Breach*|*Surge*|*Jolt*) echo "🎲🐜" ;;
+    *Archaeologist*|*archaeologist*|*Relic*|*Fossil*|*Dig*|*Shard*|*Epoch*|*Strata*|*Lore*|*Glyph*) echo "🏺🐜" ;;
+    *Oracle*|*oracle*|*Sage*|*Seer*|*Vision*|*Augur*|*Mystic*|*Sibyl*|*Delph*|*Pythia*) echo "🔮🐜" ;;
+    *Route*|*route*) echo "📋🐜" ;;
+    *Ambassador*|*ambassador*|*Bridge*|*Connect*|*Link*|*Diplomat*|*Network*|*Protocol*) echo "🔌🐜" ;;
+    *Auditor*|*auditor*|*Review*|*Inspect*|*Examine*|*Scrutin*|*Critical*|*Verify*) echo "👥🐜" ;;
+    *Chronicler*|*chronicler*|*Document*|*Record*|*Write*|*Chronicle*|*Archive*|*Scribe*) echo "📝🐜" ;;
+    *Gatekeeper*|*gatekeeper*|*Guard*|*Protect*|*Secure*|*Shield*|*Depend*|*Supply*) echo "📦🐜" ;;
+    *Guardian*|*guardian*|*Defend*|*Patrol*|*Secure*|*Vigil*|*Watch*|*Safety*|*Security*) echo "🛡️🐜" ;;
+    *Includer*|*includer*|*Access*|*Inclusive*|*A11y*|*WCAG*|*Barrier*|*Universal*) echo "♿🐜" ;;
+    *Keeper*|*keeper*|*Archive*|*Store*|*Curate*|*Preserve*|*Knowledge*|*Wisdom*|*Pattern*) echo "📚🐜" ;;
+    *Measurer*|*measurer*|*Metric*|*Benchmark*|*Profile*|*Optimize*|*Performance*|*Speed*) echo "⚡🐜" ;;
+    *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 "🔄🐜" ;;
     *) echo "🐜" ;;
   esac
 }
 
+# ============================================
+# CONTEXT UPDATE HELPER FUNCTION
+# (Defined outside case block to fix SC2168: local outside function)
+# ============================================
+_cmd_context_update() {
+  local ctx_action="${1:-}"
+  local ctx_file="${AETHER_ROOT:-.}/.aether/CONTEXT.md"
+  local ctx_tmp="${ctx_file}.tmp"
+  local ctx_ts
+  ctx_ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  ensure_context_dir() {
+    local dir
+    dir=$(dirname "$ctx_file")
+    [[ -d "$dir" ]] || mkdir -p "$dir"
+  }
+
+  read_colony_state() {
+    local state_file="${AETHER_ROOT:-.}/.aether/data/COLONY_STATE.json"
+    if [[ -f "$state_file" ]]; then
+      current_phase=$(jq -r '.current_phase // "unknown"' "$state_file" 2>/dev/null)
+      milestone=$(jq -r '.milestone // "unknown"' "$state_file" 2>/dev/null)
+      goal=$(jq -r '.goal // ""' "$state_file" 2>/dev/null)
+    else
+      current_phase="unknown"
+      milestone="unknown"
+      goal=""
+    fi
+  }
+
+  case "$ctx_action" in
+    init)
+      local init_goal="${2:-}"
+      ensure_context_dir
+      read_colony_state
+
+      cat > "$ctx_file" << EOF
+# Aether Colony — Current Context
+
+> **This document is the colony's memory. If context collapses, read this file first.**
+
+---
+
+## 🚦 System Status
+
+| Field | Value |
+|-------|-------|
+| **Last Updated** | $ctx_ts |
+| **Current Phase** | 1 |
+| **Phase Name** | initialization |
+| **Milestone** | First Mound |
+| **Colony Status** | initializing |
+| **Safe to Clear?** | ⚠️ NO — Colony just initialized |
+
+---
+
+## 🎯 Current Goal
+
+$init_goal
+
+---
+
+## 📍 What's In Progress
+
+Colony initialization in progress...
+
+---
+
+## ⚠️ Active Constraints (REDIRECT Signals)
+
+| Constraint | Source | Date Set |
+|------------|--------|----------|
+| In the Aether repo, \`.aether/\` IS the source of truth — \`runtime/\` is auto-populated on publish | CLAUDE.md | Permanent |
+| Never push without explicit user approval | CLAUDE.md Safety | Permanent |
+
+---
+
+## 💭 Active Pheromones (FOCUS Signals)
+
+*None active*
+
+---
+
+## 📝 Recent Decisions
+
+| Date | Decision | Rationale | Made By |
+|------|----------|-----------|---------|
+
+---
+
+## 📊 Recent Activity (Last 10 Actions)
+
+| Timestamp | Command | Result | Files Changed |
+|-----------|---------|--------|---------------|
+| $ctx_ts | init | Colony initialized | — |
+
+---
+
+## 🔄 Next Steps
+
+1. Run \`/ant:plan\` to generate phases for the goal
+2. Run \`/ant:build 1\` to start building
+
+---
+
+## 🆘 If Context Collapses
+
+**READ THIS SECTION FIRST**
+
+### Immediate Recovery
+
+1. **Read this file** — You're looking at it. Good.
+2. **Check git status** — \`git status\` and \`git log --oneline -5\`
+3. **Verify COLONY_STATE.json** — \`cat .aether/data/COLONY_STATE.json | jq .current_phase\`
+4. **Resume work** — Continue from "Next Steps" above
+
+### What We Were Doing
+
+Colony was just initialized with goal: $init_goal
+
+### Is It Safe to Continue?
+
+- ✅ Colony is initialized
+- ⚠️ No work completed yet
+- ✅ All state in COLONY_STATE.json
+
+**You can proceed safely.**
+
+---
+
+## 🐜 Colony Health
+
+\`\`\`
+Milestone:    First Mound   ░░░░░░░░░░ 0%
+Phase:        1             ░░░░░░░░░░ initializing
+Context:      Active        ░░░░░░░░░░ 0%
+Git Commits:  0
+\`\`\`
+
+---
+
+*This document updates automatically with every ant command. If you see old timestamps, run \`/ant:status\` to refresh.*
+
+**Colony Memory Active** 🧠🐜
+EOF
+      json_ok "{\"updated\":true,\"action\":\"init\",\"file\":\"$ctx_file\"}"
+      ;;
+
+    update-phase)
+      local new_phase="${2:-}"
+      local new_phase_name="${3:-}"
+      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."; }
+
+      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"
+      sed -i.bak "s/| \*\*Phase Name\*\* | .*/| **Phase Name** | $new_phase_name |/" "$ctx_file" && rm -f "$ctx_file.bak"
+      sed -i.bak "s/| \*\*Safe to Clear?\*\* | .*/| **Safe to Clear?** | $safe_clear — $safe_reason |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      json_ok "{\"updated\":true,\"action\":\"update-phase\",\"phase\":$new_phase}"
+      ;;
+
+    activity)
+      local cmd="${2:-}"
+      local result="${3:-}"
+      local files_changed="${4:-—}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      local activity_line="| $ctx_ts | $cmd | $result | $files_changed |"
+
+      awk -v line="$activity_line" '
+        /\| Timestamp \| Command \| Result \| Files Changed \|/ {
+          print
+          getline
+          print
+          print line
+          next
+        }
+        /^## 🆘 If Context Collapses/ { exit }
+        { print }
+      ' "$ctx_file" > "$ctx_tmp"
+
+      mv "$ctx_tmp" "$ctx_file"
+      json_ok "{\"updated\":true,\"action\":\"activity\",\"command\":\"$cmd\"}"
+      ;;
+
+    safe-to-clear)
+      local safe="${2:-NO}"
+      local reason="${3:-Unknown state}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      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"
+
+      json_ok "{\"updated\":true,\"action\":\"safe-to-clear\",\"safe\":\"$safe\"}"
+      ;;
+
+    constraint)
+      local c_type="${2:-}"
+      local c_message="${3:-}"
+      local c_source="${4:-User}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      if [[ "$c_type" == "redirect" ]]; then
+        sed -i.bak "/^## ⚠️ Active Constraints/,/^## /{ /^| Constraint |/a\\
+| $c_message | $c_source | $ctx_ts |
+}" "$ctx_file" && rm -f "$ctx_file.bak"
+      elif [[ "$c_type" == "focus" ]]; then
+        sed -i.bak "/^## 💭 Active Pheromones/,/^## /{ /^| Signal |/a\\
+| FOCUS | $c_message | normal |
+}" "$ctx_file" && rm -f "$ctx_file.bak"
+      fi
+
+      json_ok "{\"updated\":true,\"action\":\"constraint\",\"type\":\"$c_type\"}"
+      ;;
+
+    decision)
+      local decision="${2:-}"
+      local rationale="${3:-}"
+      local made_by="${4:-Colony}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      local decision_line="| $(echo $ctx_ts | cut -dT -f1) | $decision | $rationale | $made_by |"
+
+      awk -v line="$decision_line" '
+        /^## 📝 Recent Decisions/ { in_section=1 }
+        in_section && /^\| [0-9]{4}-[0-9]{2}-[0-9]{2} / { last_decision=NR }
+        in_section && /^## 📊 Recent Activity/ { in_section=0 }
+        { lines[NR] = $0 }
+        END {
+          for (i=1; i<=NR; i++) {
+            if (i == last_decision) {
+              print lines[i]
+              print line
+            } else {
+              print lines[i]
+            }
+          }
+        }
+      ' "$ctx_file" > "$ctx_tmp"
+
+      mv "$ctx_tmp" "$ctx_file"
+      json_ok "{\"updated\":true,\"action\":\"decision\"}"
+      ;;
+
+    build-start)
+      local phase_id="${2:-}"
+      local worker_count="${3:-0}"
+      local tasks_count="${4:-0}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      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"
+      sed -i.bak "s/| \*\*Safe to Clear?\*\* | .*/| **Safe to Clear?** | ⚠️ NO — Build in progress |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      json_ok "{\"updated\":true,\"action\":\"build-start\",\"workers\":$worker_count}"
+      ;;
+
+    worker-spawn)
+      local ant_name="${2:-}"
+      local caste="${3:-}"
+      local task="${4:-}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      awk -v ant="$ant_name" -v caste="$caste" -v task="$task" -v ts="$ctx_ts" '
+        /^## 📍 What'\''s In Progress/ { in_progress=1 }
+        in_progress && /^## / && $0 !~ /What'\''s In Progress/ { in_progress=0 }
+        in_progress && /Workers:/ {
+          print
+          print "  - " ts ": Spawned " ant " (" caste ") for: " task
+          next
+        }
+        { print }
+      ' "$ctx_file" > "$ctx_tmp" && mv "$ctx_tmp" "$ctx_file"
+
+      json_ok "{\"updated\":true,\"action\":\"worker-spawn\",\"ant\":\"$ant_name\"}"
+      ;;
+
+    worker-complete)
+      local ant_name="${2:-}"
+      local status="${3:-completed}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/- .*$ant_name .*$/- $ant_name: $status (updated $ctx_ts)/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      json_ok "{\"updated\":true,\"action\":\"worker-complete\",\"ant\":\"$ant_name\"}"
+      ;;
+
+    build-progress)
+      local completed="${2:-0}"
+      local total="${3:-1}"
+      local percentage=$(( completed * 100 / total ))
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/Build IN PROGRESS/Build IN PROGRESS ($percentage% complete)/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      json_ok "{\"updated\":true,\"action\":\"build-progress\",\"percent\":$percentage}"
+      ;;
+
+    build-complete)
+      local status="${2:-completed}"
+      local result="${3:-success}"
+
+      [[ -f "$ctx_file" ]] || { json_err "CONTEXT.md not found"; }
+
+      sed -i.bak "s/| \*\*Last Updated\*\* | .*/| **Last Updated** | $ctx_ts |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      awk -v status="$status" -v result="$result" '
+        /^## 📍 What'\''s In Progress/ { in_progress=1 }
+        in_progress && /^## / && $0 !~ /What'\''s In Progress/ { in_progress=0 }
+        in_progress && /Build IN PROGRESS/ {
+          print "## 📍 What'\''s In Progress"
+          print ""
+          print "**Build " status "** — " result
+          next
+        }
+        in_progress { next }
+        { print }
+      ' "$ctx_file" > "$ctx_tmp" && mv "$ctx_tmp" "$ctx_file"
+
+      sed -i.bak "s/| \*\*Safe to Clear?\*\* | .*/| **Safe to Clear?** | ✅ YES — Build $status |/" "$ctx_file" && rm -f "$ctx_file.bak"
+
+      json_ok "{\"updated\":true,\"action\":\"build-complete\",\"status\":\"$status\"}"
+      ;;
+
+    *)
+      json_err "$E_VALIDATION_FAILED" "Unknown context action: $ctx_action"
+      ;;
+  esac
+}
+
 # --- Subcommand dispatch ---
 cmd="${1:-help}"
 shift 2>/dev/null || true
@@ -95,7 +468,7 @@ 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"],"description":"Aether Colony Utility Layer — deterministic ops for the ant colony"}
+{"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
     ;;
   version)
@@ -253,7 +626,7 @@ EOF
     json_ok "$(echo "$content" | jq -Rs '.')"
     ;;
   learning-promote)
-    [[ $# -ge 3 ]] || json_err "Usage: learning-promote <content> <source_project> <source_phase> [tags]"
+    [[ $# -ge 3 ]] || json_err "$E_VALIDATION_FAILED" "Usage: learning-promote <content> <source_project> <source_phase> [tags]"
     content="$1"
     source_project="$2"
     source_phase="$3"
@@ -291,13 +664,13 @@ EOF
         tags: $tags,
         promoted_at: $ts
       }]
-    ' "$global_file") || json_err "Failed to update learnings.json"
+    ' "$global_file") || json_err "$E_JSON_INVALID" "Failed to update learnings.json"
 
     echo "$updated" > "$global_file"
     json_ok "{\"promoted\":true,\"id\":\"$id\",\"count\":$((current_count + 1)),\"cap\":50}"
     ;;
   learning-inject)
-    [[ $# -ge 1 ]] || json_err "Usage: learning-inject <tech_keywords_csv>"
+    [[ $# -ge 1 ]] || json_err "$E_VALIDATION_FAILED" "Usage: learning-inject <tech_keywords_csv>"
     keywords="$1"
 
     global_file="$DATA_DIR/learnings.json"
@@ -325,7 +698,7 @@ EOF
     task_summary="${4:-}"
     model="${5:-default}"
     status="${6:-spawned}"
-    [[ -z "$parent_id" || -z "$child_caste" || -z "$task_summary" ]] && json_err "Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]"
+    [[ -z "$parent_id" || -z "$child_caste" || -z "$task_summary" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]"
     mkdir -p "$DATA_DIR"
     ts=$(date -u +"%H:%M:%S")
     ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -335,14 +708,15 @@ EOF
     echo "[$ts] ⚡ SPAWN $parent_emoji $parent_id -> $emoji $child_name ($child_caste): $task_summary [model: $model]" >> "$DATA_DIR/activity.log"
     # Log to spawn tree file for visualization (NEW FORMAT: includes model field)
     echo "$ts_full|$parent_id|$child_caste|$child_name|$task_summary|$model|$status" >> "$DATA_DIR/spawn-tree.txt"
-    json_ok '"logged"'
+    # Return emoji-formatted result for display
+    json_ok "\"⚡ $emoji $child_name spawned\""
     ;;
   spawn-complete)
     # Usage: spawn-complete <ant_name> <status> [summary]
     ant_name="${1:-}"
     status="${2:-completed}"
     summary="${3:-}"
-    [[ -z "$ant_name" ]] && json_err "Usage: spawn-complete <ant_name> <status> [summary]"
+    [[ -z "$ant_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-complete <ant_name> <status> [summary]"
     mkdir -p "$DATA_DIR"
     ts=$(date -u +"%H:%M:%S")
     ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -353,7 +727,8 @@ 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"
-    json_ok '"logged"'
+    # Return emoji-formatted result for display
+    json_ok "\"$status_icon $emoji $ant_name: ${summary:-$status}\""
     ;;
   spawn-can-spawn)
     # Check if spawning is allowed at given depth
@@ -492,7 +867,7 @@ EOF
     pattern_name="${1:-}"
     description="${2:-}"
     severity="${3:-warning}"
-    [[ -z "$pattern_name" || -z "$description" ]] && json_err "Usage: error-flag-pattern <pattern_name> <description> [severity]"
+    [[ -z "$pattern_name" || -z "$description" ]] && json_err "$E_VALIDATION_FAILED" "Usage: error-flag-pattern <pattern_name> <description> [severity]"
 
     patterns_file="$DATA_DIR/error-patterns.json"
     mkdir -p "$DATA_DIR"
@@ -515,7 +890,7 @@ EOF
           .last_seen = $ts |
           .projects = ((.projects + [$proj]) | unique)
         else . end]
-      ' "$patterns_file") || json_err "Failed to update pattern"
+      ' "$patterns_file") || json_err "$E_JSON_INVALID" "Failed to update pattern"
       echo "$updated" > "$patterns_file"
       count=$(echo "$updated" | jq --arg name "$pattern_name" '.patterns[] | select(.name == $name) | .occurrences')
       json_ok "{\"updated\":true,\"pattern\":\"$pattern_name\",\"occurrences\":$count}"
@@ -532,7 +907,7 @@ EOF
           "projects": [$proj],
           "resolved": false
         }]
-      ' "$patterns_file") || json_err "Failed to add pattern"
+      ' "$patterns_file") || json_err "$E_JSON_INVALID" "Failed to add pattern"
       echo "$updated" > "$patterns_file"
       json_ok "{\"created\":true,\"pattern\":\"$pattern_name\"}"
     fi
@@ -557,7 +932,7 @@ EOF
     # Usage: check-antipattern <file_path>
     # Returns JSON with critical issues and warnings
     file_path="${1:-}"
-    [[ -z "$file_path" ]] && json_err "Usage: check-antipattern <file_path>"
+    [[ -z "$file_path" ]] && json_err "$E_VALIDATION_FAILED" "Usage: check-antipattern <file_path>"
     [[ ! -f "$file_path" ]] && json_ok '{"critical":[],"warnings":[],"clean":true}'
 
     criticals=()
@@ -632,7 +1007,7 @@ EOF
     # Exit code 0 if no match, 1 if match found
     target_file="${1:-}"
     signature_name="${2:-}"
-    [[ -z "$target_file" || -z "$signature_name" ]] && json_err "Usage: signature-scan <target_file> <signature_name>"
+    [[ -z "$target_file" || -z "$signature_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: signature-scan <target_file> <signature_name>"
 
     # Handle missing target file gracefully
     if [[ ! -f "$target_file" ]]; then
@@ -687,14 +1062,14 @@ EOF
     if [[ -z "$file_pattern" ]]; then
       file_pattern="*"
     fi
-    [[ -z "$target_dir" ]] && json_err "Usage: signature-match <directory> [file_pattern]"
+    [[ -z "$target_dir" ]] && json_err "$E_VALIDATION_FAILED" "Usage: signature-match <directory> [file_pattern]"
 
     # Validate directory exists
-    [[ ! -d "$target_dir" ]] && json_err "Directory not found: $target_dir"
+    [[ ! -d "$target_dir" ]] && json_err "$E_FILE_NOT_FOUND" "Directory not found: $target_dir"
 
     # Path to signatures file
     signatures_file="$DATA_DIR/signatures.json"
-    [[ ! -f "$signatures_file" ]] && json_err "Signatures file not found"
+    [[ ! -f "$signatures_file" ]] && json_err "$E_FILE_NOT_FOUND" "Signatures file not found"
 
     # Read high-confidence signatures (confidence >= 0.7) using jq -c for compact single-line output
     high_conf_signatures=$(jq -c '.signatures[] | select(.confidence_threshold >= 0.7)' "$signatures_file" 2>/dev/null)
@@ -784,7 +1159,7 @@ EOF
     desc="${3:-}"
     source="${4:-manual}"
     phase="${5:-null}"
-    [[ -z "$title" ]] && json_err "Usage: flag-add <type> <title> <description> [source] [phase]"
+    [[ -z "$title" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-add <type> <title> <description> [source] [phase]"
 
     mkdir -p "$DATA_DIR"
     flags_file="$DATA_DIR/flags.json"
@@ -797,6 +1172,7 @@ 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
@@ -808,6 +1184,9 @@ 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
     fi
 
     # Map type to severity
@@ -842,10 +1221,11 @@ EOF
         resolution: null,
         auto_resolve_on: (if $type == "blocker" and ($source | test("chaos") | not) then "build_pass" else null end)
       }]
-    ' "$flags_file") || { release_lock "$flags_file"; json_err "Failed to add flag"; }
+    ' "$flags_file") || { json_err "$E_JSON_INVALID" "Failed to add flag"; }
 
     atomic_write "$flags_file" "$updated"
-    release_lock "$flags_file"
+    # Lock released by trap on exit (BUG-002 fix)
+    trap - EXIT
     json_ok "{\"id\":\"$id\",\"type\":\"$type\",\"severity\":\"$severity\"}"
     ;;
   flag-check-blockers)
@@ -882,10 +1262,10 @@ EOF
     # Usage: flag-resolve <flag_id> [resolution_message]
     flag_id="${1:-}"
     resolution="${2:-Resolved}"
-    [[ -z "$flag_id" ]] && json_err "Usage: flag-resolve <flag_id> [resolution_message]"
+    [[ -z "$flag_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-resolve <flag_id> [resolution_message]"
 
     flags_file="$DATA_DIR/flags.json"
-    [[ ! -f "$flags_file" ]] && json_err "No flags file found"
+    [[ ! -f "$flags_file" ]] && json_err "$E_FILE_NOT_FOUND" "No flags file found"
 
     ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
@@ -916,10 +1296,10 @@ EOF
     # Acknowledge a flag (issue continues but noted)
     # Usage: flag-acknowledge <flag_id>
     flag_id="${1:-}"
-    [[ -z "$flag_id" ]] && json_err "Usage: flag-acknowledge <flag_id>"
+    [[ -z "$flag_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: flag-acknowledge <flag_id>"
 
     flags_file="$DATA_DIR/flags.json"
-    [[ ! -f "$flags_file" ]] && json_err "No flags file found"
+    [[ ! -f "$flags_file" ]] && json_err "$E_FILE_NOT_FOUND" "No flags file found"
 
     ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
@@ -996,16 +1376,22 @@ 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
     fi
 
     # Count how many will be resolved
     count=$(jq --arg trigger "$trigger" '
       [.flags[] | select(.auto_resolve_on == $trigger and .resolved_at == null)] | length
-    ' "$flags_file")
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to count flags for auto-resolve"
+    }
 
     # Resolve them
     updated=$(jq --arg trigger "$trigger" --arg ts "$ts" '
@@ -1013,10 +1399,15 @@ EOF
         .resolved_at = $ts |
         .resolution = "Auto-resolved on " + $trigger
       else . end]
-    ' "$flags_file")
+    ' "$flags_file") || {
+      json_err "$E_JSON_INVALID" "Failed to auto-resolve flags"
+    }
 
     atomic_write "$flags_file" "$updated"
-    release_lock "$flags_file"
+    # Lock released by trap on exit (BUG-005/BUG-011 fix)
+    if [[ "$lock_acquired" == "true" ]]; then
+      trap - EXIT
+    fi
     json_ok "{\"resolved\":$count,\"trigger\":\"$trigger\"}"
     ;;
   generate-ant-name)
@@ -1032,6 +1423,17 @@ EOF
       chaos)    prefixes=("Probe" "Stress" "Shake" "Twist" "Snap" "Breach" "Surge" "Jolt") ;;
       archaeologist) prefixes=("Relic" "Fossil" "Dig" "Shard" "Epoch" "Strata" "Lore" "Glyph") ;;
       oracle)   prefixes=("Sage" "Seer" "Vision" "Augur" "Mystic" "Sibyl" "Delph" "Pythia") ;;
+      ambassador) prefixes=("Bridge" "Connect" "Link" "Diplomat" "Protocol" "Network" "Port" "Socket") ;;
+      auditor)   prefixes=("Review" "Inspect" "Exam" "Scrutin" "Verify" "Check" "Audit" "Assess") ;;
+      chronicler) prefixes=("Record" "Write" "Document" "Chronicle" "Scribe" "Archive" "Script" "Ledger") ;;
+      gatekeeper) prefixes=("Guard" "Protect" "Secure" "Shield" "Defend" "Bar" "Gate" "Checkpoint") ;;
+      guardian)  prefixes=("Defend" "Patrol" "Watch" "Vigil" "Shield" "Guard" "Armor" "Fort") ;;
+      includer)  prefixes=("Access" "Include" "Open" "Welcome" "Reach" "Universal" "Equal" "A11y") ;;
+      keeper)    prefixes=("Archive" "Store" "Curate" "Preserve" "Guard" "Keep" "Hold" "Save") ;;
+      measurer)  prefixes=("Metric" "Gauge" "Scale" "Measure" "Benchmark" "Track" "Count" "Meter") ;;
+      probe)     prefixes=("Test" "Probe" "Excavat" "Uncover" "Edge" "Mutant" "Trial" "Check") ;;
+      tracker)   prefixes=("Track" "Trace" "Debug" "Hunt" "Follow" "Trail" "Find" "Seek") ;;
+      weaver)    prefixes=("Weave" "Knit" "Spin" "Twine" "Transform" "Mend" "Weave" "Weave") ;;
       *)        prefixes=("Ant" "Worker" "Drone" "Toiler" "Marcher" "Runner" "Carrier" "Helper") ;;
     esac
     # Pick random prefix and add random number
@@ -1174,10 +1576,10 @@ EOF
     confidence="${3:-0.5}"
     finding="${4:-}"
 
-    [[ -z "$swarm_id" || -z "$scout_type" || -z "$finding" ]] && json_err "Usage: swarm-findings-add <swarm_id> <scout_type> <confidence> <finding_json>"
+    [[ -z "$swarm_id" || -z "$scout_type" || -z "$finding" ]] && json_err "$E_VALIDATION_FAILED" "Usage: swarm-findings-add <swarm_id> <scout_type> <confidence> <finding_json>"
 
     findings_file="$DATA_DIR/swarm-findings-$swarm_id.json"
-    [[ ! -f "$findings_file" ]] && json_err "Swarm findings file not found: $swarm_id"
+    [[ ! -f "$findings_file" ]] && json_err "$E_FILE_NOT_FOUND" "Swarm findings file not found: $swarm_id"
 
     ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
@@ -1200,10 +1602,10 @@ EOF
     # Read all findings for a swarm
     # Usage: swarm-findings-read <swarm_id>
     swarm_id="${1:-}"
-    [[ -z "$swarm_id" ]] && json_err "Usage: swarm-findings-read <swarm_id>"
+    [[ -z "$swarm_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: swarm-findings-read <swarm_id>"
 
     findings_file="$DATA_DIR/swarm-findings-$swarm_id.json"
-    [[ ! -f "$findings_file" ]] && json_err "Swarm findings file not found: $swarm_id"
+    [[ ! -f "$findings_file" ]] && json_err "$E_FILE_NOT_FOUND" "Swarm findings file not found: $swarm_id"
 
     json_ok "$(cat "$findings_file")"
     ;;
@@ -1214,10 +1616,10 @@ EOF
     swarm_id="${1:-}"
     solution="${2:-}"
 
-    [[ -z "$swarm_id" || -z "$solution" ]] && json_err "Usage: swarm-solution-set <swarm_id> <solution_json>"
+    [[ -z "$swarm_id" || -z "$solution" ]] && json_err "$E_VALIDATION_FAILED" "Usage: swarm-solution-set <swarm_id> <solution_json>"
 
     findings_file="$DATA_DIR/swarm-findings-$swarm_id.json"
-    [[ ! -f "$findings_file" ]] && json_err "Swarm findings file not found: $swarm_id"
+    [[ ! -f "$findings_file" ]] && json_err "$E_FILE_NOT_FOUND" "Swarm findings file not found: $swarm_id"
 
     ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
 
@@ -1237,7 +1639,7 @@ EOF
     swarm_id="${1:-}"
     archive="${2:-}"
 
-    [[ -z "$swarm_id" ]] && json_err "Usage: swarm-cleanup <swarm_id> [--archive]"
+    [[ -z "$swarm_id" ]] && json_err "$E_VALIDATION_FAILED" "Usage: swarm-cleanup <swarm_id> [--archive]"
 
     findings_file="$DATA_DIR/swarm-findings-$swarm_id.json"
 
@@ -1258,7 +1660,7 @@ EOF
   grave-add)
     # Record a grave marker when a builder fails at a file
     # Usage: grave-add <file> <ant_name> <task_id> <phase> <failure_summary> [function] [line]
-    [[ $# -ge 5 ]] || json_err "Usage: grave-add <file> <ant_name> <task_id> <phase> <failure_summary> [function] [line]"
+    [[ $# -ge 5 ]] || json_err "$E_VALIDATION_FAILED" "Usage: grave-add <file> <ant_name> <task_id> <phase> <failure_summary> [function] [line]"
     [[ -f "$DATA_DIR/COLONY_STATE.json" ]] || json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
     file="$1"
     ant_name="$2"
@@ -1309,7 +1711,7 @@ EOF
     # Query for grave markers near a file path
     # Usage: grave-check <file_path>
     # Read-only, never modifies state
-    [[ $# -ge 1 ]] || json_err "Usage: grave-check <file_path>"
+    [[ $# -ge 1 ]] || json_err "$E_VALIDATION_FAILED" "Usage: grave-check <file_path>"
     [[ -f "$DATA_DIR/COLONY_STATE.json" ]] || json_err "$E_FILE_NOT_FOUND" "COLONY_STATE.json not found" '{"file":"COLONY_STATE.json"}'
     check_file="$1"
     check_dir=$(dirname "$check_file")
@@ -1333,14 +1735,15 @@ EOF
 
   generate-commit-message)
     # Generate an intelligent commit message from colony context
-    # Usage: generate-commit-message <type> <phase_id> <phase_name> [summary]
-    # Types: "milestone" | "pause" | "fix"
-    # Returns: {"message": "...", "body": "...", "files_changed": N}
+    # Usage: generate-commit-message <type> <phase_id> <phase_name> [summary|ai_description] [plan_num]
+    # Types: "milestone" | "pause" | "fix" | "contextual"
+    # Returns: {"message": "...", "body": "...", "files_changed": N, ...}
 
     msg_type="${1:-milestone}"
     phase_id="${2:-0}"
     phase_name="${3:-unknown}"
-    summary="${4:-}"
+    summary="${4:-}"        # For milestone/fix types, or ai_description for contextual type
+    plan_num="${5:-01}"     # Optional: plan number for contextual type (e.g., "01")
 
     # Count changed files
     files_changed=0
@@ -1373,6 +1776,33 @@ EOF
         fi
         body="Swarm-verified fix applied and tested."
         ;;
+      contextual)
+        # NEW: Contextual commit with AI description and structured metadata
+        # Derive subsystem from phase name (e.g., "11-foraging-specialization" -> "foraging")
+        subsystem=$(echo "$phase_name" | sed -E 's/^[0-9]+-//' | sed -E 's/-[0-9]+.*$//' | tr '-' ' ')
+        [[ -z "$subsystem" ]] && subsystem="phase"
+
+        # Build message with AI description (summary parameter is reused as ai_description)
+        if [[ -n "$summary" ]]; then
+          message="aether-milestone: ${summary}"
+        else
+          # Fallback if no AI description provided
+          message="aether-milestone: phase ${phase_id}.${plan_num} complete -- ${phase_name}"
+        fi
+
+        # Build structured body with metadata
+        body="Scope: ${phase_id}.${plan_num}
+Files: ${files_changed} files changed"
+
+        # Truncate message if needed BEFORE JSON construction
+        if [[ ${#message} -gt 72 ]]; then
+          message="${message:0:69}..."
+        fi
+
+        # Return enhanced JSON with additional metadata
+        json_ok "{\"message\":\"$message\",\"body\":\"$body\",\"files_changed\":$files_changed,\"subsystem\":\"$subsystem\",\"scope\":\"${phase_id}.${plan_num}\"}"
+        exit 0
+        ;;
       *)
         message="aether-checkpoint: phase ${phase_id}"
         body=""
@@ -1387,6 +1817,32 @@ EOF
     json_ok "{\"message\":\"$message\",\"body\":\"$body\",\"files_changed\":$files_changed}"
     ;;
 
+  # ============================================
+  # CONTEXT PERSISTENCE SYSTEM
+  # ============================================
+
+  context-update)
+    # Update .aether/CONTEXT.md with current colony state
+    # Usage: context-update <action> [args...]
+    #
+    # Actions:
+    #   init <goal>                              - Initialize new context
+    #   update-phase <phase_id> <name>           - Update current phase
+    #   activity <command> <result> [files]      - Log activity
+    #   constraint <type> <message> [source]     - Add constraint (redirect/focus)
+    #   decision <description> [rationale] [who] - Log decision
+    #   safe-to-clear <yes|no> <reason>          - Set safe-to-clear status
+    #   build-start <phase_id> <workers> <tasks> - Mark build starting
+    #   worker-spawn <ant_name> <caste> <task>   - Log worker spawn
+    #   worker-complete <ant_name> <status>      - Log worker completion
+    #   build-progress <completed> <total>       - Update build progress
+    #   build-complete <status> <result>         - Mark build complete
+    #
+    # Always call with explicit arguments - never rely on current directory
+    # CONTEXT_FILE must be passed or detected from AETHER_ROOT
+    _cmd_context_update "$@"
+    ;;
+
   # ============================================
   # REGISTRY & UPDATE UTILITIES
   # ============================================
@@ -1409,7 +1865,8 @@ EOF
     if [[ "$local_ver" == "$hub_ver" ]]; then
       json_ok '""'
     else
-      json_ok "\"Update available: $local_ver -> $hub_ver (run /ant:update)\""
+      printf -v msg 'Update available: %s to %s (run /ant:update)' "$local_ver" "$hub_ver"
+      json_ok "$msg"
     fi
     ;;
 
@@ -1418,7 +1875,7 @@ EOF
     # Usage: registry-add <repo_path> <version>
     repo_path="${1:-}"
     repo_version="${2:-}"
-    [[ -z "$repo_path" || -z "$repo_version" ]] && json_err "Usage: registry-add <repo_path> <version>"
+    [[ -z "$repo_path" || -z "$repo_version" ]] && json_err "$E_VALIDATION_FAILED" "Usage: registry-add <repo_path> <version>"
 
     registry_file="$HOME/.aether/registry.json"
     mkdir -p "$HOME/.aether"
@@ -1439,7 +1896,7 @@ EOF
           .version = $ver |
           .updated_at = $ts
         else . end]
-      ' "$registry_file") || json_err "Failed to update registry"
+      ' "$registry_file") || json_err "$E_JSON_INVALID" "Failed to update registry"
     else
       # Add new entry
       updated=$(jq --arg path "$repo_path" --arg ver "$repo_version" --arg ts "$ts" '
@@ -1449,7 +1906,7 @@ EOF
           "registered_at": $ts,
           "updated_at": $ts
         }]
-      ' "$registry_file") || json_err "Failed to update registry"
+      ' "$registry_file") || json_err "$E_JSON_INVALID" "Failed to update registry"
     fi
 
     echo "$updated" > "$registry_file"
@@ -1462,7 +1919,7 @@ EOF
     hub_system="$HOME/.aether/system"
     local_aether="$AETHER_ROOT/.aether"
 
-    [[ ! -d "$hub_system" ]] && json_err "Hub system directory not found: $hub_system"
+    [[ ! -d "$hub_system" ]] && json_err "$E_HUB_NOT_FOUND" "Hub system directory not found: $hub_system"
 
     # Allowlist of system files to copy (relative to system/)
     allowlist=(
@@ -2236,7 +2693,916 @@ NODESCRIPT
     json_ok "{\"item\":\"$item\",\"state\":\"collapsed\",\"view\":\"$view_name\"}"
     ;;
 
+  queen-init)
+    # Initialize QUEEN.md from template
+    # Creates .aether/QUEEN.md from template if missing
+    queen_file="$AETHER_ROOT/.aether/docs/QUEEN.md"
+
+    # Check multiple locations for template
+    # Order: dev (runtime/) -> npm install (hub) -> 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
+      if [[ -f "$path" ]]; then
+        template_file="$path"
+        break
+      fi
+    done
+
+    # Ensure docs directory exists
+    mkdir -p "$AETHER_ROOT/.aether/docs"
+
+    # Check if QUEEN.md already exists and has content
+    if [[ -f "$queen_file" ]] && [[ -s "$queen_file" ]]; then
+      json_ok '{"created":false,"path":".aether/docs/QUEEN.md","reason":"already_exists"}'
+      exit 0
+    fi
+
+    # 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"]}'
+      exit 1
+    fi
+
+    # Create QUEEN.md from template with timestamp substitution
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    sed -e "s/{TIMESTAMP}/$timestamp/g" "$template_file" > "$queen_file"
+
+    if [[ -f "$queen_file" ]]; then
+      json_ok "{\"created\":true,\"path\":\".aether/docs/QUEEN.md\",\"source\":\"$template_file\"}"
+    else
+      json_err "$E_FILE_NOT_FOUND" "Failed to create QUEEN.md" '{"path":".aether/docs/QUEEN.md"}'
+      exit 1
+    fi
+    ;;
+
+  queen-read)
+    # Read QUEEN.md and return wisdom as JSON for worker priming
+    # Extracts METADATA block and sections for colony guidance
+    queen_file="$AETHER_ROOT/.aether/docs/QUEEN.md"
+
+    # Check if QUEEN.md exists
+    if [[ ! -f "$queen_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "QUEEN.md not found" '{"path":".aether/docs/QUEEN.md"}'
+      exit 1
+    fi
+
+    # Extract METADATA JSON block (between <!-- METADATA and -->)
+    metadata=$(sed -n '/<!-- METADATA/,/-->/p' "$queen_file" | sed '1d;$d' | tr -d '\n' | sed 's/^[[:space:]]*//')
+
+    # If no metadata found, return empty structure
+    if [[ -z "$metadata" ]]; then
+      metadata='{"version":"unknown","last_evolved":null,"colonies_contributed":[],"promotion_thresholds":{},"stats":{}}'
+    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 '.')
+    patterns=$(awk '/^## 🧭 Patterns$/,/^## /' "$queen_file" | tail -n +2 | sed '$d' | sed '/^$/d' | jq -Rs '.')
+    redirects=$(awk '/^## ⚠️ Redirects$/,/^## /' "$queen_file" | tail -n +2 | sed '$d' | sed '/^$/d' | jq -Rs '.')
+    stack_wisdom=$(awk '/^## 🔧 Stack Wisdom$/,/^## /' "$queen_file" | tail -n +2 | sed '$d' | sed '/^$/d' | jq -Rs '.')
+    decrees=$(awk '/^## 🏛️ Decrees$/,/^## /' "$queen_file" | tail -n +2 | sed '$d' | sed '/^$/d' | jq -Rs '.')
+
+    # Build JSON output
+    result=$(jq -n \
+      --argjson meta "$metadata" \
+      --arg philosophies "$philosophies" \
+      --arg patterns "$patterns" \
+      --arg redirects "$redirects" \
+      --arg stack_wisdom "$stack_wisdom" \
+      --arg decrees "$decrees" \
+      '{
+        metadata: $meta,
+        wisdom: {
+          philosophies: $philosophies,
+          patterns: $patterns,
+          redirects: $redirects,
+          stack_wisdom: $stack_wisdom,
+          decrees: $decrees
+        },
+        priming: {
+          has_philosophies: ($philosophies | length) > 0 and $philosophies != "*No philosophies recorded yet.*\n",
+          has_patterns: ($patterns | length) > 0 and $patterns != "*No patterns recorded yet.*\n",
+          has_redirects: ($redirects | length) > 0 and $redirects != "*No redirects recorded yet.*\n",
+          has_stack_wisdom: ($stack_wisdom | length) > 0 and $stack_wisdom != "*No stack wisdom recorded yet.*\n",
+          has_decrees: ($decrees | length) > 0 and $decrees != "*No decrees recorded yet.*\n"
+        }
+      }')
+
+    json_ok "$result"
+    ;;
+
+  queen-promote)
+    # Promote a learning to QUEEN.md wisdom
+    # Usage: queen-promote <type> <content> <colony_name>
+    # Types: philosophy, pattern, redirect, stack, decree
+    wisdom_type="${1:-}"
+    content="${2:-}"
+    colony_name="${3:-}"
+
+    # Validate required arguments
+    [[ -z "$wisdom_type" ]] && json_err "$E_VALIDATION_FAILED" "Usage: queen-promote <type> <content> <colony_name>" '{"missing":"type"}'
+    [[ -z "$content" ]] && json_err "$E_VALIDATION_FAILED" "Usage: queen-promote <type> <content> <colony_name>" '{"missing":"content"}'
+    [[ -z "$colony_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: queen-promote <type> <content> <colony_name>" '{"missing":"colony_name"}'
+
+    # Validate type
+    valid_types=("philosophy" "pattern" "redirect" "stack" "decree")
+    type_valid=false
+    for vt in "${valid_types[@]}"; do
+      [[ "$wisdom_type" == "$vt" ]] && type_valid=true && break
+    done
+    [[ "$type_valid" == "false" ]] && json_err "$E_VALIDATION_FAILED" "Invalid type: $wisdom_type" '{"valid_types":["philosophy","pattern","redirect","stack","decree"]}'
+
+    queen_file="$AETHER_ROOT/.aether/docs/QUEEN.md"
+
+    # Check if QUEEN.md exists
+    if [[ ! -f "$queen_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "QUEEN.md not found" '{"path":".aether/docs/QUEEN.md"}'
+      exit 1
+    fi
+
+    # Extract METADATA to get promotion thresholds
+    metadata=$(sed -n '/<!-- METADATA/,/-->/p' "$queen_file" | sed '1d;$d' | tr -d '\n' | sed 's/^[[:space:]]*//')
+
+    # Get threshold for this type (default: philosophy=5, pattern=3, redirect=2, stack=1, decree=0)
+    threshold=$(echo "$metadata" | jq -r ".promotion_thresholds.${wisdom_type} // null")
+    if [[ "$threshold" == "null" ]]; then
+      case "$wisdom_type" in
+        philosophy) threshold=5 ;;
+        pattern) threshold=3 ;;
+        redirect) threshold=2 ;;
+        stack) threshold=1 ;;
+        decree) threshold=0 ;;
+        *) threshold=1 ;;
+      esac
+    fi
+
+    # For decrees, always promote immediately (threshold 0)
+    # For other types, we assume validation count is passed or threshold is met
+    # In a real implementation, this would check a validation counter
+    # For now, we append if threshold allows (decrees always, others need external validation)
+
+    ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Map type to section header and emoji
+    case "$wisdom_type" in
+      philosophy) section_header="## 📜 Philosophies" ;;
+      pattern) section_header="## 🧭 Patterns" ;;
+      redirect) section_header="## ⚠️ Redirects" ;;
+      stack) section_header="## 🔧 Stack Wisdom" ;;
+      decree) section_header="## 🏛️ Decrees" ;;
+    esac
+
+    # Build the new entry
+    entry="- **${colony_name}** (${ts}): ${content}"
+
+    # Create temp file for atomic write
+    tmp_file="${queen_file}.tmp.$$"
+
+    # Find line numbers for section boundaries
+    section_line=$(grep -n "^${section_header}$" "$queen_file" | head -1 | cut -d: -f1)
+    next_section_line=$(tail -n +$((section_line + 1)) "$queen_file" | grep -n "^## " | head -1 | cut -d: -f1)
+    if [[ -n "$next_section_line" ]]; then
+      section_end=$((section_line + next_section_line - 1))
+    else
+      section_end=$(wc -l < "$queen_file")
+    fi
+
+    # Check if section has placeholder (grep returns 1 when no matches, handle with || true)
+    has_placeholder=$(sed -n "${section_line},${section_end}p" "$queen_file" | grep -c "No.*recorded yet" || true)
+    has_placeholder=${has_placeholder:-0}
+
+    if [[ "$has_placeholder" -gt 0 ]]; then
+      # Replace placeholder with entry - only within the target section
+      # Find the specific line number of the placeholder within the section
+      placeholder_line=$(sed -n "${section_line},${section_end}p" "$queen_file" | grep -n "^\\*No .* recorded yet" | head -1 | cut -d: -f1)
+      if [[ -n "$placeholder_line" ]]; then
+        actual_line=$((section_line + placeholder_line - 1))
+        sed "${actual_line}c\\
+${entry}" "$queen_file" > "$tmp_file"
+      else
+        # Fallback: insert after section header
+        sed "${section_line}a\\
+${entry}" "$queen_file" > "$tmp_file"
+      fi
+    else
+      # Insert entry after the description paragraph (after the second empty line in section)
+      # The structure is: header, blank, description, blank, [entries...]
+      # We want to insert after the blank line following the description
+      empty_lines=$(sed -n "$((section_line + 1)),${section_end}p" "$queen_file" | grep -n "^$" | cut -d: -f1)
+      # Get the second empty line (after description)
+      insert_line=$(echo "$empty_lines" | sed -n '2p')
+      if [[ -n "$insert_line" ]]; then
+        insert_line=$((section_line + insert_line))
+      else
+        # Fallback: use first empty line
+        insert_line=$(echo "$empty_lines" | head -1)
+        if [[ -n "$insert_line" ]]; then
+          insert_line=$((section_line + insert_line))
+        else
+          insert_line=$((section_line + 1))
+        fi
+      fi
+      # Insert the entry after the found line
+      sed "${insert_line}a\\
+${entry}" "$queen_file" > "$tmp_file"
+    fi
+
+    # Update Evolution Log in temp file
+    ev_entry="| ${ts} | ${colony_name} | promoted_${wisdom_type} | Added: ${content:0:50}... |"
+    # Find the line after the separator in Evolution Log table
+    ev_separator=$(grep -n "^|------|" "$tmp_file" | tail -1 | cut -d: -f1)
+
+    # Use awk for cross-platform insertion
+    awk -v line="$ev_separator" -v entry="$ev_entry" 'NR==line{print; print entry; next}1' "$tmp_file" > "${tmp_file}.ev" && mv "${tmp_file}.ev" "$tmp_file"
+
+    # Update METADATA stats in temp file
+    # Map wisdom_type to stat key (irregular plurals handled)
+    case "$wisdom_type" in
+      stack) stat_key="total_stack_entries" ;;
+      philosophy) stat_key="total_philosophies" ;;
+      *) stat_key="total_${wisdom_type}s" ;;
+    esac
+    # Read current count from temp file (which has the latest state)
+    current_count=$(grep "\"${stat_key}\":" "$tmp_file" 2>/dev/null | grep -o '[0-9]*' | head -1 || true)
+    current_count=${current_count:-0}
+    new_count=$((current_count + 1))
+
+    # Update last_evolved using awk
+    awk -v ts="$ts" '/"last_evolved":/ { gsub(/"last_evolved": "[^"]*"/, "\"last_evolved\": \"" ts "\""); } {print}' "$tmp_file" > "${tmp_file}.meta" && mv "${tmp_file}.meta" "$tmp_file"
+
+    # Update stats count using awk
+    awk -v type="$stat_key" -v count="$new_count" '{
+      gsub("\"" type "\": [0-9]*", "\"" type "\": " count)
+      print
+    }' "$tmp_file" > "${tmp_file}.stats" && mv "${tmp_file}.stats" "$tmp_file"
+
+    # Add colony to colonies_contributed if not present
+    if ! grep -q "\"${colony_name}\"" "$tmp_file"; then
+      # Add to colonies_contributed array using awk - handle empty and non-empty arrays
+      awk -v colony="$colony_name" '
+        /"colonies_contributed": \[\]/ {
+          gsub(/"colonies_contributed": \[\]/, "\"colonies_contributed\": [\"" colony "\"]")
+          print
+          next
+        }
+        /"colonies_contributed": \[/ && !/\]/ {
+          # Multi-line array, add at next closing bracket
+          print
+          next
+        }
+        /"colonies_contributed": \[/ {
+          # Single-line array with elements
+          gsub(/\]$/, "\"" colony "\", ]")
+          print
+          next
+        }
+        { print }
+      ' "$tmp_file" > "${tmp_file}.col" && mv "${tmp_file}.col" "$tmp_file"
+    fi
+
+    # Atomic move
+    mv "$tmp_file" "$queen_file"
+
+    json_ok "{\"promoted\":true,\"type\":\"$wisdom_type\",\"colony\":\"$colony_name\",\"timestamp\":\"$ts\",\"threshold\":$threshold,\"new_count\":$new_count}"
+    ;;
+
+  survey-load)
+    phase_type="${1:-}"
+    survey_dir=".aether/data/survey"
+
+    if [[ ! -d "$survey_dir" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "No survey found"
+    fi
+
+    docs=""
+    case "$phase_type" in
+      *frontend*|*component*|*UI*|*page*|*button*)
+        docs="DISCIPLINES.md,CHAMBERS.md"
+        ;;
+      *API*|*endpoint*|*backend*|*route*)
+        docs="BLUEPRINT.md,DISCIPLINES.md"
+        ;;
+      *database*|*schema*|*model*|*migration*)
+        docs="BLUEPRINT.md,PROVISIONS.md"
+        ;;
+      *test*|*spec*|*coverage*)
+        docs="SENTINEL-PROTOCOLS.md,DISCIPLINES.md"
+        ;;
+      *integration*|*external*|*client*)
+        docs="TRAILS.md,PROVISIONS.md"
+        ;;
+      *refactor*|*cleanup*|*debt*)
+        docs="PATHOGENS.md,BLUEPRINT.md"
+        ;;
+      *setup*|*config*|*initialize*)
+        docs="PROVISIONS.md,CHAMBERS.md"
+        ;;
+      *)
+        docs="PROVISIONS.md,BLUEPRINT.md"
+        ;;
+    esac
+
+    json_ok "{\"ok\":true,\"docs\":\"$docs\",\"dir\":\"$survey_dir\"}"
+    ;;
+
+  survey-verify)
+    survey_dir=".aether/data/survey"
+    required="PROVISIONS.md TRAILS.md BLUEPRINT.md CHAMBERS.md DISCIPLINES.md SENTINEL-PROTOCOLS.md PATHOGENS.md"
+    missing=""
+    counts=""
+
+    for doc in $required; do
+      if [[ ! -f "$survey_dir/$doc" ]]; then
+        missing="$missing $doc"
+      else
+        lines=$(wc -l < "$survey_dir/$doc" | tr -d ' ')
+        counts="$counts $doc:$lines"
+      fi
+    done
+
+    if [[ -n "$missing" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "Missing survey documents" "{\"missing\":\"$missing\"}"
+    fi
+
+    json_ok "{\"ok\":true,\"counts\":\"$counts\"}"
+    ;;
+
+  checkpoint-check)
+    allowlist_file="$DATA_DIR/checkpoint-allowlist.json"
+
+    if [[ ! -f "$allowlist_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "Allowlist not found" "{\"path\":\"$allowlist_file\"}"
+    fi
+
+    # Get dirty files from git (staged or unstaged)
+    dirty_files=$(git status --porcelain 2>/dev/null | awk '{print $2}' || true)
+
+    if [[ -z "$dirty_files" ]]; then
+      json_ok '{"ok":true,"system_files":[],"user_files":[],"has_user_files":false}'
+      exit 0
+    fi
+
+    # Temporary files for building JSON
+    system_files_tmp=$(mktemp)
+    user_files_tmp=$(mktemp)
+
+    # Check each file against allowlist patterns
+    for file in $dirty_files; do
+      is_system=false
+
+      # Check against system file patterns
+      if [[ "$file" == ".aether/aether-utils.sh" ]]; then
+        is_system=true
+      elif [[ "$file" == ".aether/workers.md" ]]; then
+        is_system=true
+      elif [[ "$file" == .aether/docs/*.md ]]; then
+        is_system=true
+      elif [[ "$file" == .claude/commands/ant/*.md ]] || [[ "$file" == .claude/commands/ant/**/*.md ]]; then
+        is_system=true
+      elif [[ "$file" == .claude/commands/st/*.md ]] || [[ "$file" == .claude/commands/st/**/*.md ]]; then
+        is_system=true
+      elif [[ "$file" == .opencode/commands/ant/*.md ]] || [[ "$file" == .opencode/commands/ant/**/*.md ]]; then
+        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
+
+      if [[ "$is_system" == "true" ]]; then
+        echo "$file" >> "$system_files_tmp"
+      else
+        echo "$file" >> "$user_files_tmp"
+      fi
+    done
+
+    # Build JSON using jq if available, otherwise use simple format
+    if command -v jq >/dev/null 2>&1; then
+      result=$(jq -n \
+        --argjson system "$(jq -R . < "$system_files_tmp" 2>/dev/null | jq -s .)" \
+        --argjson user "$(jq -R . < "$user_files_tmp" 2>/dev/null | jq -s .)" \
+        '{ok: true, system_files: $system, user_files: $user, has_user_files: ($user | length > 0)}')
+    else
+      # Fallback without jq - simple output
+      system_count=$(wc -l < "$system_files_tmp" 2>/dev/null | tr -d ' ' || echo "0")
+      user_count=$(wc -l < "$user_files_tmp" 2>/dev/null | tr -d ' ' || echo "0")
+      has_user=false
+      [[ "$user_count" -gt 0 ]] && has_user=true
+      result="{\"ok\":true,\"system_files\":[],\"user_files\":[],\"has_user_files\":$has_user}"
+    fi
+
+    rm -f "$system_files_tmp" "$user_files_tmp"
+    echo "$result"
+    exit 0
+    ;;
+
+  normalize-args)
+    # Normalize arguments from Claude Code ($ARGUMENTS) or OpenCode ($@)
+    # Usage: bash .aether/aether-utils.sh normalize-args [args...]
+    # Or: eval "$(bash .aether/aether-utils.sh normalize-args)"
+    #
+    # Claude Code passes args in $ARGUMENTS variable
+    # OpenCode passes args in $@ (positional parameters)
+    # This command outputs the normalized arguments as a single string
+
+    normalized=""
+
+    # Try Claude Code style first ($ARGUMENTS environment variable)
+    if [ -n "${ARGUMENTS:-}" ]; then
+      normalized="$ARGUMENTS"
+    # Fall back to OpenCode style ($@ positional params)
+    elif [ $# -gt 0 ]; then
+      # Preserve arguments with spaces by quoting
+      for arg in "$@"; do
+        if [[ "$arg" == *" "* ]] || [[ "$arg" == *"\t"* ]] || [[ "$arg" == *"\n"* ]]; then
+          # Quote arguments containing whitespace
+          normalized="$normalized \"$arg\""
+        else
+          normalized="$normalized $arg"
+        fi
+      done
+      # Trim leading space
+      normalized="${normalized# }"
+    fi
+
+    # Output normalized arguments
+    echo "$normalized"
+    exit 0
+    ;;
+
+  # Backward compatibility wrappers for session commands
+  survey-verify-fresh)
+    # Backward compatibility: delegate to session-verify-fresh --command survey
+    # Usage: bash .aether/aether-utils.sh survey-verify-fresh [--force] <survey_start_unixtime>
+
+    force_mode=""
+    survey_start_time=""
+
+    # Parse arguments
+    for arg in "$@"; do
+      if [[ "$arg" == "--force" ]]; then
+        force_mode="--force"
+      elif [[ "$arg" =~ ^[0-9]+$ ]]; then
+        survey_start_time="$arg"
+      fi
+    done
+
+    # Delegate to generic command
+    if [[ -n "$force_mode" ]]; then
+      $0 session-verify-fresh --command survey --force "$survey_start_time"
+    else
+      $0 session-verify-fresh --command survey "$survey_start_time"
+    fi
+    ;;
+
+  survey-clear)
+    # Backward compatibility: delegate to session-clear --command survey
+    # Usage: bash .aether/aether-utils.sh survey-clear [--dry-run]
+
+    dry_run=""
+
+    # Parse arguments
+    for arg in "$@"; do
+      if [[ "$arg" == "--dry-run" ]]; then
+        dry_run="--dry-run"
+      fi
+    done
+
+    # Delegate to generic command
+    if [[ "$dry_run" == "--dry-run" ]]; then
+      $0 session-clear --command survey --dry-run
+    else
+      $0 session-clear --command survey
+    fi
+    ;;
+
+  session-verify-fresh)
+    # Generic session freshness verification
+    # Usage: bash .aether/aether-utils.sh session-verify-fresh --command <name> [--force] <session_start_unixtime>
+    # Returns: JSON with pass/fail status and file details
+
+    # Parse arguments
+    command_name=""
+    force_mode=""
+    session_start_time=""
+
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --command) command_name="$2"; shift 2 ;;
+        --force) force_mode="--force"; shift ;;
+        *) session_start_time="$1"; shift ;;
+      esac
+    done
+
+    # Validate command name
+    [[ -z "$command_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: session-verify-fresh --command <name> [--force] <session_start>"
+
+    # Map command to directory and files (using env var override pattern)
+    case "$command_name" in
+      survey)
+        session_dir="${SURVEY_DIR:-.aether/data/survey}"
+        required_docs="PROVISIONS.md TRAILS.md BLUEPRINT.md CHAMBERS.md DISCIPLINES.md SENTINEL-PROTOCOLS.md PATHOGENS.md"
+        ;;
+      oracle)
+        session_dir="${ORACLE_DIR:-.aether/oracle}"
+        required_docs="progress.md research.json"
+        ;;
+      watch)
+        session_dir="${WATCH_DIR:-.aether/data}"
+        required_docs="watch-status.txt watch-progress.txt"
+        ;;
+      swarm)
+        session_dir="${SWARM_DIR:-.aether/data/swarm}"
+        required_docs="findings.json"
+        ;;
+      init)
+        session_dir="${INIT_DIR:-.aether/data}"
+        required_docs="COLONY_STATE.json constraints.json"
+        ;;
+      seal|entomb)
+        session_dir="${ARCHIVE_DIR:-.aether/data/archive}"
+        required_docs="manifest.json"
+        ;;
+      *)
+        json_err "$E_VALIDATION_FAILED" "Unknown command: $command_name" '{"commands":["survey","oracle","watch","swarm","init","seal","entomb"]}'
+        ;;
+    esac
+
+    # Initialize result arrays
+    fresh_docs=""
+    stale_docs=""
+    missing_docs=""
+    total_lines=0
+
+    for doc in $required_docs; do
+      doc_path="$session_dir/$doc"
+
+      if [[ ! -f "$doc_path" ]]; then
+        missing_docs="${missing_docs:+$missing_docs }$doc"
+        continue
+      fi
+
+      # Get line count
+      lines=$(wc -l < "$doc_path" 2>/dev/null | tr -d ' ' || echo "0")
+      total_lines=$((total_lines + lines))
+
+      # In force mode, accept any existing file
+      if [[ "$force_mode" == "--force" ]]; then
+        fresh_docs="${fresh_docs:+$fresh_docs }$doc"
+        continue
+      fi
+
+      # Check timestamp if session_start_time provided
+      if [[ -n "$session_start_time" ]]; then
+        # Cross-platform stat: macOS uses -f %m, Linux uses -c %Y
+        file_mtime=$(stat -f %m "$doc_path" 2>/dev/null || stat -c %Y "$doc_path" 2>/dev/null || echo "0")
+
+        if [[ "$file_mtime" -ge "$session_start_time" ]]; then
+          fresh_docs="${fresh_docs:+$fresh_docs }$doc"
+        else
+          stale_docs="${stale_docs:+$stale_docs }$doc"
+        fi
+      else
+        # No start time provided - accept existing file (backward compatible)
+        fresh_docs="${fresh_docs:+$fresh_docs }$doc"
+      fi
+    done
+
+    # Determine pass/fail
+    # pass = true if: no stale files (fresh files can coexist with missing files)
+    # missing files are ok - they will be created during the session
+    pass=false
+    if [[ "$force_mode" == "--force" ]] || [[ -z "$stale_docs" ]]; then
+      pass=true
+    fi
+
+    # Build JSON response
+    fresh_json=""
+    for item in $fresh_docs; do fresh_json="$fresh_json\"$item\","; done
+    fresh_json="[${fresh_json%,}]"
+
+    stale_json=""
+    for item in $stale_docs; do stale_json="$stale_json\"$item\","; done
+    stale_json="[${stale_json%,}]"
+
+    missing_json=""
+    for item in $missing_docs; do missing_json="$missing_json\"$item\","; done
+    missing_json="[${missing_json%,}]"
+
+    echo "{\"ok\":$pass,\"command\":\"$command_name\",\"fresh\":$fresh_json,\"stale\":$stale_json,\"missing\":$missing_json,\"total_lines\":$total_lines}"
+    exit 0
+    ;;
+
+  session-clear)
+    # Generic session file clearing
+    # Usage: bash .aether/aether-utils.sh session-clear --command <name> [--dry-run]
+
+    # Parse arguments
+    command_name=""
+    dry_run=""
+
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --command) command_name="$2"; shift 2 ;;
+        --dry-run) dry_run="--dry-run"; shift ;;
+        *) shift ;;
+      esac
+    done
+
+    [[ -z "$command_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: session-clear --command <name> [--dry-run]"
+
+    # Map command to directory and files
+    case "$command_name" in
+      survey)
+        session_dir="${SURVEY_DIR:-.aether/data/survey}"
+        files="PROVISIONS.md TRAILS.md BLUEPRINT.md CHAMBERS.md DISCIPLINES.md SENTINEL-PROTOCOLS.md PATHOGENS.md"
+        ;;
+      oracle)
+        session_dir="${ORACLE_DIR:-.aether/oracle}"
+        files="progress.md research.json .stop"
+        # Also clear discoveries subdirectory
+        subdir_files="discoveries/*"
+        ;;
+      watch)
+        session_dir="${WATCH_DIR:-.aether/data}"
+        files="watch-status.txt watch-progress.txt"
+        ;;
+      swarm)
+        session_dir="${SWARM_DIR:-.aether/data/swarm}"
+        files="findings.json display.json timing.json"
+        ;;
+      init)
+        # Init clear is destructive - blocked for auto-clear
+        json_err "$E_VALIDATION_FAILED" "Command 'init' is protected and cannot be auto-cleared. Use manual removal of COLONY_STATE.json if absolutely necessary."
+        ;;
+      seal|entomb)
+        # Archive operations should never be auto-cleared
+        json_err "$E_VALIDATION_FAILED" "Command '$command_name' is protected and cannot be auto-cleared. Archives and chambers must be managed manually."
+        ;;
+      *)
+        json_err "$E_VALIDATION_FAILED" "Unknown command: $command_name"
+        ;;
+    esac
+
+    cleared=""
+    errors=""
+
+    if [[ -d "$session_dir" && -n "$files" ]]; then
+      for doc in $files; do
+        doc_path="$session_dir/$doc"
+        if [[ -f "$doc_path" ]]; then
+          if [[ "$dry_run" == "--dry-run" ]]; then
+            cleared="$cleared $doc"
+          else
+            if rm -f "$doc_path" 2>/dev/null; then
+              cleared="$cleared $doc"
+            else
+              errors="$errors $doc"
+            fi
+          fi
+        fi
+      done
+
+      # Handle oracle discoveries subdirectory
+      if [[ "$command_name" == "oracle" && -d "$session_dir/discoveries" ]]; then
+        if [[ "$dry_run" == "--dry-run" ]]; then
+          cleared="$cleared discoveries/"
+        else
+          rm -rf "$session_dir/discoveries" 2>/dev/null && cleared="$cleared discoveries/" || errors="$errors discoveries/"
+        fi
+      fi
+    fi
+
+    json_ok "{\"command\":\"$command_name\",\"cleared\":\"${cleared// /}\",\"errors\":\"${errors// /}\",\"dry_run\":$([[ "$dry_run" == "--dry-run" ]] && echo "true" || echo "false")}"
+    ;;
+
+  pheromone-export)
+    # Export pheromones to eternal XML format
+    # Usage: pheromone-export [input_json] [output_xml]
+    #   input_json: Path to pheromones.json (default: .aether/data/pheromones.json)
+    #   output_xml: Path to output XML (default: ~/.aether/eternal/pheromones.xml)
+
+    input_json="${1:-.aether/data/pheromones.json}"
+    output_xml="${2:-$HOME/.aether/eternal/pheromones.xml}"
+    schema_file="${3:-$SCRIPT_DIR/schemas/pheromone.xsd}"
+
+    # Ensure xml-utils.sh is sourced
+    if ! type pheromone-export &>/dev/null; then
+      [[ -f "$SCRIPT_DIR/utils/xml-utils.sh" ]] && source "$SCRIPT_DIR/utils/xml-utils.sh"
+    fi
+
+    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"
+    fi
+    ;;
+
+  # ============================================================================
+  # Session Continuity Commands
+  # ============================================================================
+
+  session-init)
+    # Initialize a new session tracking file
+    # Usage: session-init [session_id] [goal]
+    session_id="${2:-$(date +%s)_$(openssl rand -hex 4 2>/dev/null || echo $$)}"
+    goal="${3:-}"
+
+    session_file="$DATA_DIR/session.json"
+
+    cat > "$session_file" << EOF
+{
+  "session_id": "$session_id",
+  "started_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "last_command": null,
+  "last_command_at": null,
+  "colony_goal": "$goal",
+  "current_phase": 0,
+  "current_milestone": "First Mound",
+  "suggested_next": "/ant:plan",
+  "context_cleared": false,
+  "resumed_at": null,
+  "active_todos": [],
+  "summary": "Session initialized"
+}
+EOF
+    json_ok "{\"session_id\":\"$session_id\",\"goal\":\"$goal\",\"file\":\"$session_file\"}"
+    ;;
+
+  session-update)
+    # Update session with latest activity
+    # Usage: session-update <command> [suggested_next] [summary]
+    cmd_run="${2:-}"
+    suggested="${3:-}"
+    summary="${4:-}"
+
+    session_file="$DATA_DIR/session.json"
+
+    if [[ ! -f "$session_file" ]]; then
+      # Auto-initialize if doesn't exist
+      bash "$0" session-init "auto_$(date +%s)" ""
+    fi
+
+    # Read current session
+    current_session=$(cat "$session_file" 2>/dev/null || echo '{}')
+
+    # Extract current values for preservation
+    current_goal=$(echo "$current_session" | jq -r '.colony_goal // empty')
+    current_phase=$(echo "$current_session" | jq -r '.current_phase // 0')
+    current_milestone=$(echo "$current_session" | jq -r '.current_milestone // "First Mound"')
+
+    # Get top 3 TODOs if TO-DOs.md exists
+    todos="[]"
+    if [[ -f "TO-DOs.md" ]]; then
+      todos=$(grep "^### " TO-DOs.md 2>/dev/null | head -3 | sed 's/^### //' | jq -R . | jq -s .)
+    fi
+
+    # Get colony state if exists
+    if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+      current_goal=$(jq -r '.goal // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "$current_goal")
+      current_phase=$(jq -r '.current_phase // 0' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "$current_phase")
+      current_milestone=$(jq -r '.milestone // "First Mound"' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null || echo "$current_milestone")
+    fi
+
+    # Build updated session
+    echo "$current_session" | jq --arg cmd "$cmd_run" \
+      --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+      --arg suggested "$suggested" \
+      --arg summary "$summary" \
+      --arg goal "$current_goal" \
+      --argjson phase "$current_phase" \
+      --arg milestone "$current_milestone" \
+      --argjson todos "$todos" \
+      '.last_command = $cmd |
+       .last_command_at = $ts |
+       .suggested_next = $suggested |
+       .summary = $summary |
+       .colony_goal = $goal |
+       .current_phase = $phase |
+       .current_milestone = $milestone |
+       .active_todos = $todos' > "$session_file"
+
+    json_ok "{\"updated\":true,\"command\":\"$cmd_run\"}"
+    ;;
+
+  session-read)
+    # Read and return current session state
+    session_file="$DATA_DIR/session.json"
+
+    if [[ ! -f "$session_file" ]]; then
+      json_ok "{\"exists\":false,\"session\":null}"
+      exit 0
+    fi
+
+    session_data=$(cat "$session_file" 2>/dev/null || echo '{}')
+
+    # Check if stale (> 24 hours)
+    last_cmd_ts="" is_stale="" age_hours=""
+    last_cmd_ts=$(echo "$session_data" | jq -r '.last_command_at // .started_at // empty')
+    if [[ -n "$last_cmd_ts" ]]; then
+      last_epoch=0 now_epoch=0
+      last_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$last_cmd_ts" +%s 2>/dev/null || echo 0)
+      now_epoch=$(date +%s)
+      age_hours=$(( (now_epoch - last_epoch) / 3600 ))
+      [[ $age_hours -gt 24 ]] && is_stale=true || is_stale=false
+    else
+      is_stale="false"
+      age_hours="unknown"
+    fi
+
+    json_ok "{\"exists\":true,\"is_stale\":$is_stale,\"age_hours\":$age_hours,\"session\":$session_data}"
+    ;;
+
+  session-is-stale)
+    # Check if session is stale (returns true/false)
+    session_file="$DATA_DIR/session.json"
+
+    if [[ ! -f "$session_file" ]]; then
+      echo "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"
+      exit 0
+    fi
+
+    last_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$last_cmd_ts" +%s 2>/dev/null || echo 0)
+    now_epoch=$(date +%s)
+    age_hours=$(( (now_epoch - last_epoch) / 3600 ))
+
+    [[ $age_hours -gt 24 ]] && echo "true" || echo "false"
+    ;;
+
+  session-clear)
+    # Mark session as cleared (preserves file but marks context_cleared)
+    preserve="${2:-false}"
+    session_file="$DATA_DIR/session.json"
+
+    if [[ -f "$session_file" ]]; then
+      if [[ "$preserve" == "true" ]]; then
+        # Just mark as cleared
+        jq '.context_cleared = true' "$session_file" > "$session_file.tmp" && mv "$session_file.tmp" "$session_file"
+        json_ok "{\"cleared\":true,\"preserved\":true}"
+      else
+        # Remove file entirely
+        rm -f "$session_file"
+        json_ok "{\"cleared\":true,\"preserved\":false}"
+      fi
+    else
+      json_ok "{\"cleared\":false,\"reason\":\"no_session_exists\"}"
+    fi
+    ;;
+
+  session-mark-resumed)
+    # Mark session as resumed
+    session_file="$DATA_DIR/session.json"
+
+    if [[ -f "$session_file" ]]; then
+      jq --arg ts "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
+         '.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"
+    fi
+    ;;
+
+  session-summary)
+    # Get human-readable session summary
+    session_file="$DATA_DIR/session.json"
+
+    if [[ ! -f "$session_file" ]]; then
+      echo "No active session found."
+      exit 0
+    fi
+
+    goal=$(jq -r '.colony_goal // "No goal set"' "$session_file")
+    phase=$(jq -r '.current_phase // 0' "$session_file")
+    milestone=$(jq -r '.current_milestone // "First Mound"' "$session_file")
+    last_cmd=$(jq -r '.last_command // "None"' "$session_file")
+    last_at=$(jq -r '.last_command_at // "Unknown"' "$session_file")
+    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"
+    ;;
+
   *)
-    json_err "Unknown command: $cmd"
+    json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd"
     ;;
 esac