aether-colony 3.1.17 → 5.1.0

package/.aether/templates/crowned-anthill.template.md

@@ -0,0 +1,36 @@
+<!-- Template: crowned-anthill | Version: 2.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/CROWNED-ANTHILL.md -->
+
+# Crowned Anthill — {{GOAL}}
+
+**Sealed:** {{SEAL_DATE}}
+**Milestone:** Crowned Anthill
+**Version:** {{VERSION}}
+
+## The Achievement
+
+This colony set out to accomplish something real — and it did. Every phase pushed the anthill higher. Now it stands crowned.
+
+## Colony Stats
+- Total Phases: {{TOTAL_PHASES}}
+- Phases Completed: {{PHASES_COMPLETED}} of {{TOTAL_PHASES}}
+- Colony Age: {{COLONY_AGE_DAYS}} days of focused work
+- Wisdom Promoted: {{PROMOTIONS_MADE}} entries carried forward
+
+## Phase Recap
+
+Every phase below is a chapter in the story of this anthill's rise:
+
+{{PHASE_RECAP}}
+
+## Pheromone Legacy
+
+The colony's hard-won wisdom doesn't stop here. {{PROMOTIONS_MADE}} validated learnings and instincts have been promoted to QUEEN.md — a living record that will guide future colonies before they take their first steps.
+
+What this colony learned, the next colony inherits.
+
+## The Work
+
+{{GOAL}}
+
+The anthill stands crowned. The work endures.

package/.aether/templates/handoff-build-error.template.md

@@ -0,0 +1,30 @@
+<!-- Template: handoff-build-error | Version: 1.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — Build Errors
+
+## Build Status: ISSUES DETECTED
+
+**Phase:** {{PHASE_NUMBER}} — {{PHASE_NAME}}
+**Status:** Build completed with failures
+**Updated:** {{BUILD_TIMESTAMP}}
+
+## Failed Workers
+
+{{FAILED_WORKERS}}
+
+## Grave Markers Placed
+
+{{GRAVE_MARKERS}}
+
+## Recovery Options
+
+1. Review failures: Check `.aether/data/activity.log`
+2. Fix and retry: `/ant:build {{PHASE_NUMBER}}`
+3. Swarm fix: `/ant:swarm` for auto-repair
+4. Manual fix: Address issues, then `/ant:continue`
+
+## Session Note
+
+Build completed but workers failed. Grave markers placed.
+Review failures before advancing.

package/.aether/templates/handoff-build-success.template.md

@@ -0,0 +1,39 @@
+<!-- Template: handoff-build-success | Version: 1.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — Build Complete
+
+## Quick Resume
+
+Run `/ant:continue` to advance phase, or `/ant:resume-colony` to restore full context.
+
+## State at Build Completion
+
+- Goal: "{{GOAL}}"
+- Phase: {{PHASE_NUMBER}} — {{PHASE_NAME}}
+- Build Status: {{BUILD_STATUS}}
+- Updated: {{BUILD_TIMESTAMP}}
+
+## Build Summary
+
+{{BUILD_SUMMARY}}
+
+## Tasks
+
+- Completed: {{TASKS_COMPLETED}}
+- Failed: {{TASKS_FAILED}}
+
+## Files Changed
+
+- Created: {{FILES_CREATED}} files
+- Modified: {{FILES_MODIFIED}} files
+
+## Next Steps
+
+- If verification passed: `/ant:continue` to advance to next phase
+- If issues found: `/ant:flags` to review blockers
+- To pause: `/ant:pause-colony`
+
+## Session Note
+
+{{SESSION_NOTE}}

package/.aether/templates/handoff.template.md

@@ -0,0 +1,40 @@
+<!-- Template: handoff | Version: 2.0 -->
+<!-- Instructions: Fill all {{PLACEHOLDER}} values with real colony data. Remove this comment block before writing to .aether/HANDOFF.md -->
+
+# Colony Session — {{CHAMBER_NAME}}
+
+## A Colony's Rest
+
+This colony has been entombed. Its work is complete, its story told.
+What began with a goal has ended with a chamber — a place of quiet preservation.
+
+**Chamber:** .aether/chambers/{{CHAMBER_NAME}}/
+
+## Colony Summary
+
+- Goal: "{{GOAL}}"
+- Phases: {{PHASES_COMPLETED}} completed of {{TOTAL_PHASES}}
+- Milestone reached: {{MILESTONE}}
+- Entombed at: {{ENTOMB_TIMESTAMP}}
+
+## Chamber Contents
+
+Everything the colony built and learned rests here now:
+
+- colony-state.json — Full colony state
+- manifest.json — Archive metadata
+- CROWNED-ANTHILL.md — Seal ceremony record
+- pheromones.json — Pheromone signals
+- activity.log — Colony activity history
+- spawn-tree.txt — Worker spawn records
+- dreams/ — Dream journal (if existed)
+
+## Session Note
+
+The active colony has been reset. The chambers hold what was.
+The learnings have been carried forward to QUEEN.md — the next colony won't start from nothing.
+
+When you are ready to begin again:
+
+To start anew: /ant:lay-eggs "<new goal>"
+To revisit what came before: /ant:tunnels

package/.aether/templates/learning-observations.template.json

@@ -0,0 +1,6 @@
+{
+  "_template": "learning-observations",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/learning-observations.json. No substitution needed. Remove underscore-prefixed keys.",
+  "observations": []
+}

package/.aether/templates/midden.template.json

@@ -0,0 +1,13 @@
+{
+  "_template": "midden",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/midden/midden.json. No substitution needed. Remove underscore-prefixed keys.",
+  "version": "1.0.0",
+  "signals": [],
+  "spawn_metrics": {
+    "total_spawned": 0,
+    "completed": 0,
+    "failed": 0,
+    "efficiency_pct": 0
+  }
+}

package/.aether/templates/pheromones.template.json

@@ -0,0 +1,6 @@
+{
+  "_template": "pheromones",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/pheromones.json. No substitution needed. Remove underscore-prefixed keys.",
+  "signals": []
+}

package/.aether/templates/session.template.json

@@ -0,0 +1,9 @@
+{
+  "_template": "session",
+  "_version": "1.0",
+  "_instructions": "Write to .aether/data/session.json. Replace __SESSION_ID__, __GOAL__, __TIMESTAMP__. Remove underscore-prefixed keys.",
+  "session_id": "__SESSION_ID__",
+  "colony_goal": "__GOAL__",
+  "started_at": "__TIMESTAMP__",
+  "last_activity": "__TIMESTAMP__"
+}

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

@@ -25,11 +25,13 @@ if [ ! -f "$_AETHER_UTILS_DIR/file-lock.sh" ]; then
 fi
 source "$_AETHER_UTILS_DIR/file-lock.sh"
 
-# Aether root detection - use git root if available, otherwise use current directory
-if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    AETHER_ROOT="$(git rev-parse --show-toplevel)"
-else
-    AETHER_ROOT="$(pwd)"
+# Aether root detection - respect existing AETHER_ROOT, or use git root, or use current directory
+if [[ -z "${AETHER_ROOT:-}" ]]; then
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        AETHER_ROOT="$(git rev-parse --show-toplevel)"
+    else
+        AETHER_ROOT="$(pwd)"
+    fi
 fi
 
 TEMP_DIR="$AETHER_ROOT/.aether/temp"
@@ -41,9 +43,44 @@ mkdir -p "$TEMP_DIR" "$BACKUP_DIR"
 # Number of backups to keep
 MAX_BACKUPS=3
 
+# Safety stats file for tracking data safety events (best-effort, never fails operations)
+SAFETY_STATS_FILE="${AETHER_ROOT}/.aether/data/safety-stats.json"
+
+# Increment a safety stats counter (best-effort, never fails the calling operation)
+# Arguments: counter_name (e.g., "stale_locks_cleaned", "json_validation_rejects")
+_safety_stats_increment() {
+    local counter_name="$1"
+    local stats_file="$SAFETY_STATS_FILE"
+    local now_iso
+    now_iso=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "unknown")
+
+    # Ensure data directory exists
+    mkdir -p "$(dirname "$stats_file")" 2>/dev/null || return 0
+
+    # Initialize if missing
+    if [[ ! -f "$stats_file" ]]; then
+        printf '{"stale_locks_cleaned":0,"json_validation_rejects":0,"last_updated":"%s"}\n' "$now_iso" > "$stats_file" 2>/dev/null || return 0
+    fi
+
+    # Increment counter (best-effort, don't fail on jq errors)
+    local updated
+    updated=$(jq --arg key "$counter_name" --arg ts "$now_iso" '
+        .[$key] = ((.[$key] // 0) + 1) |
+        .last_updated = $ts
+    ' "$stats_file" 2>/dev/null) || return 0
+
+    if [[ -n "$updated" ]]; then
+        printf '%s\n' "$updated" > "$stats_file" 2>/dev/null || return 0
+    fi
+}
+
 # Atomic write: write content to file via temporary file
 # Arguments: target_file, content
 # Returns: 0 on success, 1 on failure
+# NOTE: atomic_write does NOT interact with file locks. Lock management
+# (acquire_lock/release_lock) is the CALLER's responsibility. If you need
+# exclusive access, acquire the lock before calling atomic_write, and release
+# it after (including on error paths).
 atomic_write() {
     local target_file="$1"
     local content="$2"
@@ -53,10 +90,10 @@ atomic_write() {
     mkdir -p "$target_dir"
 
     # Create unique temp file
-    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$( date +%s )_${RANDOM}.tmp"
 
     # Write content to temp file
-    if ! echo "$content" > "$temp_file"; then
+    if ! printf '%s\n' "$content" > "$temp_file"; then
         echo "Failed to write to temp file: $temp_file"
         rm -f "$temp_file"
         return 1
@@ -67,11 +104,12 @@ atomic_write() {
         create_backup "$target_file"
     fi
 
-    # Validate JSON if it's a JSON file
+    # Validate JSON if it's a JSON file (lock management is caller's responsibility)
     if [[ "$target_file" == *.json ]]; then
-        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+        if ! jq empty "$temp_file" 2>/dev/null; then
             echo "Invalid JSON in temp file: $temp_file"
             rm -f "$temp_file"
+            _safety_stats_increment "json_validation_rejects" 2>/dev/null || true
             return 1
         fi
     fi
@@ -108,7 +146,7 @@ atomic_write_from_file() {
     mkdir -p "$target_dir"
 
     # Create unique temp file
-    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$(date +%s%N).tmp"
+    local temp_file="${TEMP_DIR}/$(basename "$target_file").$$.$( date +%s )_${RANDOM}.tmp"
 
     # Copy source to temp
     if ! cp "$source_file" "$temp_file"; then
@@ -117,20 +155,21 @@ atomic_write_from_file() {
         return 1
     fi
 
-    # Validate JSON if it's a JSON file
+    # Create backup BEFORE validation (mirrors atomic_write ordering — LOCK-03)
+    if [ -f "$target_file" ]; then
+        create_backup "$target_file"
+    fi
+
+    # Validate JSON if it's a JSON file (lock management is caller's responsibility)
     if [[ "$target_file" == *.json ]]; then
-        if ! python3 -c "import json; json.load(open('$temp_file'))" 2>/dev/null; then
+        if ! jq empty "$temp_file" 2>/dev/null; then
             echo "Invalid JSON in temp file: $temp_file"
             rm -f "$temp_file"
+            _safety_stats_increment "json_validation_rejects" 2>/dev/null || true
             return 1
         fi
     fi
 
-    # Create backup if target exists
-    if [ -f "$target_file" ]; then
-        create_backup "$target_file"
-    fi
-
     # Atomic rename
     if ! mv "$temp_file" "$target_file"; then
         echo "Failed to rename temp file to target: $target_file"
@@ -166,10 +205,17 @@ create_backup() {
 # Arguments: base_name
 rotate_backups() {
     local base_name="$1"
-    local backups=$(ls -t "${BACKUP_DIR}/${base_name}".*.backup 2>/dev/null | wc -l)
 
-    if [ "$backups" -gt "$MAX_BACKUPS" ]; then
-        ls -t "${BACKUP_DIR}/${base_name}".*.backup | tail -n +$((MAX_BACKUPS + 1)) | xargs rm -f
+    # Use find with -print0 for safe handling of paths with spaces
+    local backup_count
+    backup_count=$(find "$BACKUP_DIR" -maxdepth 1 -name "${base_name}.*.backup" -type f 2>/dev/null | wc -l | tr -d ' ')
+
+    if [ "$backup_count" -gt "$MAX_BACKUPS" ]; then
+        # Delete oldest backups beyond MAX_BACKUPS using find for space-safe handling
+        find "$BACKUP_DIR" -maxdepth 1 -name "${base_name}.*.backup" -type f -print0 2>/dev/null \
+            | xargs -0 ls -t 2>/dev/null \
+            | tail -n +$((MAX_BACKUPS + 1)) \
+            | while IFS= read -r file; do rm -f "$file" 2>/dev/null || true; done
     fi
 }
 
@@ -209,9 +255,9 @@ list_backups() {
 
 # Cleanup temp files older than 1 hour
 cleanup_temp_files() {
-    find "$TEMP_DIR" -name "*.tmp" -mtime +1/24 -delete 2>/dev/null || true
+    find "$TEMP_DIR" -name "*.tmp" -mmin +60 -delete 2>/dev/null || true
 }
 
 # Export functions
 export -f atomic_write atomic_write_from_file create_backup rotate_backups
-export -f restore_backup list_backups cleanup_temp_files
+export -f restore_backup list_backups cleanup_temp_files _safety_stats_increment

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

@@ -7,13 +7,26 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 CHAMBERS_DIR="${CHAMBERS_DIR:-.aether/chambers}"
 
+# Source error-handler.sh for E_* constants and enhanced json_err
+[[ -f "$SCRIPT_DIR/error-handler.sh" ]] && source "$SCRIPT_DIR/error-handler.sh"
+
+# Fallback E_* constants (no-ops when error-handler.sh is already loaded)
+: "${E_UNKNOWN:=E_UNKNOWN}"
+: "${E_FILE_NOT_FOUND:=E_FILE_NOT_FOUND}"
+: "${E_VALIDATION_FAILED:=E_VALIDATION_FAILED}"
+
 # JSON output helpers
 json_ok() { printf '{"ok":true,"result":%s}\n' "$1"; }
-json_err() {
-  local message="${2:-$1}"
-  printf '{"ok":false,"error":"%s"}\n' "$message" >&2
-  exit 1
-}
+
+# Guard: yield to error-handler.sh's enhanced json_err when already loaded
+if ! type json_err &>/dev/null; then
+  json_err() {
+    local code="${1:-E_UNKNOWN}"
+    local message="${2:-An unknown error occurred}"
+    printf '{"ok":false,"error":{"code":"%s","message":"%s"}}\n' "$code" "$message" >&2
+    exit 1
+  }
+fi
 
 # Load chamber manifest
 load_chamber() {
@@ -21,7 +34,7 @@ load_chamber() {
   local manifest_file="$CHAMBERS_DIR/$chamber_name/manifest.json"
 
   if [[ ! -f "$manifest_file" ]]; then
-    json_err "Chamber not found: $chamber_name"
+    json_err "$E_FILE_NOT_FOUND" "Chamber not found: $chamber_name. Try: check the chamber name with /ant:tunnels."
   fi
 
   cat "$manifest_file"
@@ -41,7 +54,7 @@ EOF
   compare)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: compare <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: compare <chamber_a> <chamber_b>."
 
     # Load both manifests
     manifest_a=$(load_chamber "$chamber_a")
@@ -93,7 +106,7 @@ EOF
   diff)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: diff <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: diff <chamber_a> <chamber_b>."
 
     manifest_a=$(load_chamber "$chamber_a")
     manifest_b=$(load_chamber "$chamber_b")
@@ -138,7 +151,7 @@ EOF
   stats)
     chamber_a="${1:-}"
     chamber_b="${2:-}"
-    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "Usage: stats <chamber_a> <chamber_b>"
+    [[ -z "$chamber_a" || -z "$chamber_b" ]] && json_err "$E_VALIDATION_FAILED" "Missing arguments. Try: stats <chamber_a> <chamber_b>."
 
     manifest_a=$(load_chamber "$chamber_a")
     manifest_b=$(load_chamber "$chamber_b")
@@ -175,6 +188,6 @@ EOF
     ;;
 
   *)
-    json_err "Unknown command: $cmd. Use: compare, diff, stats"
+    json_err "$E_VALIDATION_FAILED" "Unknown command: $cmd. Try: compare, diff, or stats."
     ;;
 esac