aether-colony 5.0.0 → 5.2.1

package/.aether/utils/council.sh

@@ -0,0 +1,425 @@
+#!/bin/bash
+# Council deliberation module — Advocate/Challenger/Sage model with spawn budget guards
+# Provides: _council_deliberate, _council_advocate, _council_challenger, _council_sage,
+#           _council_history, _council_budget_check
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, acquire_lock,
+# release_lock, LOCK_DIR, COLONY_DATA_DIR, error constants) is available.
+# _spawn_can_spawn is available from spawn.sh (sourced before this module).
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_council_data_dir() {
+    echo "$COLONY_DATA_DIR/council"
+}
+
+_council_deliberations_file() {
+    echo "$COLONY_DATA_DIR/council/deliberations.json"
+}
+
+_council_ensure_file() {
+    local cf
+    cf="$(_council_deliberations_file)"
+    mkdir -p "$(_council_data_dir)"
+    if [[ ! -f "$cf" ]]; then
+        printf '%s\n' '{"version":"1.0","deliberations":[]}' > "$cf"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# _council_deliberate
+# Usage: council-deliberate --proposal <text> [--budget N] [--depth light|standard|deep]
+# ---------------------------------------------------------------------------
+_council_deliberate() {
+    local cd_proposal=""
+    local cd_budget="3"
+    local cd_depth="standard"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --proposal) cd_proposal="${2:-}"; shift 2 ;;
+            --budget)   cd_budget="${2:-3}";  shift 2 ;;
+            --depth)    cd_depth="${2:-standard}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$cd_proposal" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-deliberate requires --proposal"
+        return
+    fi
+
+    if ! [[ "$cd_budget" =~ ^[0-9]+$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-deliberate --budget must be a positive integer"
+        return
+    fi
+
+    local cd_ts
+    cd_ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local cd_unix
+    cd_unix=$(date -u +%s)
+    local cd_id="delib_${cd_unix}"
+
+    _council_ensure_file
+
+    local cd_file
+    cd_file="$(_council_deliberations_file)"
+
+    acquire_lock "$cd_file" 2>/dev/null || true
+    # shellcheck disable=SC2064
+    trap "release_lock '$cd_file' 2>/dev/null || true" EXIT
+
+    local cd_updated
+    cd_updated=$(jq \
+        --arg id "$cd_id" \
+        --arg proposal "$cd_proposal" \
+        --arg ts "$cd_ts" \
+        --argjson budget "$cd_budget" \
+        --arg depth "$cd_depth" \
+        '.deliberations += [{
+            "id": $id,
+            "proposal": $proposal,
+            "advocate": null,
+            "challenger": null,
+            "sage": null,
+            "budget": $budget,
+            "depth": $depth,
+            "created_at": $ts,
+            "status": "pending"
+        }]' "$cd_file") || {
+        release_lock "$cd_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to write deliberation"
+        return
+    }
+
+    atomic_write "$cd_file" "$cd_updated" || {
+        release_lock "$cd_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to persist deliberation"
+        return
+    }
+
+    release_lock "$cd_file" 2>/dev/null || true
+    trap - EXIT
+
+    json_ok "$(jq -n \
+        --arg id "$cd_id" \
+        --arg proposal "$cd_proposal" \
+        --argjson budget "$cd_budget" \
+        '{"id":$id,"proposal":$proposal,"status":"pending","budget":$budget}')"
+}
+
+# ---------------------------------------------------------------------------
+# _council_advocate
+# Usage: council-advocate --deliberation-id <id> --argument <text>
+# ---------------------------------------------------------------------------
+_council_advocate() {
+    local ca_id=""
+    local ca_argument=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --deliberation-id) ca_id="${2:-}"; shift 2 ;;
+            --argument)        ca_argument="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$ca_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-advocate requires --deliberation-id"
+        return
+    fi
+
+    if [[ -z "$ca_argument" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-advocate requires --argument"
+        return
+    fi
+
+    local ca_file
+    ca_file="$(_council_deliberations_file)"
+
+    if [[ ! -f "$ca_file" ]]; then
+        json_err "$E_VALIDATION_FAILED" "No deliberations found; run council-deliberate first"
+        return
+    fi
+
+    local ca_exists
+    ca_exists=$(jq -r --arg id "$ca_id" '.deliberations[] | select(.id == $id) | .id' "$ca_file" 2>/dev/null || echo "")
+    if [[ -z "$ca_exists" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Deliberation not found: $ca_id"
+        return
+    fi
+
+    acquire_lock "$ca_file" 2>/dev/null || true
+    # shellcheck disable=SC2064
+    trap "release_lock '$ca_file' 2>/dev/null || true" EXIT
+
+    local ca_updated
+    ca_updated=$(jq \
+        --arg id "$ca_id" \
+        --arg arg "$ca_argument" \
+        '(.deliberations[] | select(.id == $id)).advocate = $arg
+         | (.deliberations[] | select(.id == $id)).status = "in_progress"' \
+        "$ca_file") || {
+        release_lock "$ca_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to record advocate argument"
+        return
+    }
+
+    atomic_write "$ca_file" "$ca_updated" || {
+        release_lock "$ca_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to persist advocate argument"
+        return
+    }
+
+    release_lock "$ca_file" 2>/dev/null || true
+    trap - EXIT
+
+    json_ok '{"role":"advocate","recorded":true}'
+}
+
+# ---------------------------------------------------------------------------
+# _council_challenger
+# Usage: council-challenger --deliberation-id <id> --argument <text>
+# ---------------------------------------------------------------------------
+_council_challenger() {
+    local cc_id=""
+    local cc_argument=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --deliberation-id) cc_id="${2:-}"; shift 2 ;;
+            --argument)        cc_argument="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$cc_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-challenger requires --deliberation-id"
+        return
+    fi
+
+    if [[ -z "$cc_argument" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-challenger requires --argument"
+        return
+    fi
+
+    local cc_file
+    cc_file="$(_council_deliberations_file)"
+
+    if [[ ! -f "$cc_file" ]]; then
+        json_err "$E_VALIDATION_FAILED" "No deliberations found; run council-deliberate first"
+        return
+    fi
+
+    local cc_exists
+    cc_exists=$(jq -r --arg id "$cc_id" '.deliberations[] | select(.id == $id) | .id' "$cc_file" 2>/dev/null || echo "")
+    if [[ -z "$cc_exists" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Deliberation not found: $cc_id"
+        return
+    fi
+
+    acquire_lock "$cc_file" 2>/dev/null || true
+    # shellcheck disable=SC2064
+    trap "release_lock '$cc_file' 2>/dev/null || true" EXIT
+
+    local cc_updated
+    cc_updated=$(jq \
+        --arg id "$cc_id" \
+        --arg arg "$cc_argument" \
+        '(.deliberations[] | select(.id == $id)).challenger = $arg
+         | (.deliberations[] | select(.id == $id)).status = "in_progress"' \
+        "$cc_file") || {
+        release_lock "$cc_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to record challenger argument"
+        return
+    }
+
+    atomic_write "$cc_file" "$cc_updated" || {
+        release_lock "$cc_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to persist challenger argument"
+        return
+    }
+
+    release_lock "$cc_file" 2>/dev/null || true
+    trap - EXIT
+
+    json_ok '{"role":"challenger","recorded":true}'
+}
+
+# ---------------------------------------------------------------------------
+# _council_sage
+# Usage: council-sage --deliberation-id <id> --synthesis <text> --recommendation <text>
+# ---------------------------------------------------------------------------
+_council_sage() {
+    local cs_id=""
+    local cs_synthesis=""
+    local cs_recommendation=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --deliberation-id) cs_id="${2:-}";             shift 2 ;;
+            --synthesis)       cs_synthesis="${2:-}";       shift 2 ;;
+            --recommendation)  cs_recommendation="${2:-}";  shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$cs_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-sage requires --deliberation-id"
+        return
+    fi
+
+    if [[ -z "$cs_synthesis" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-sage requires --synthesis"
+        return
+    fi
+
+    if [[ -z "$cs_recommendation" ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-sage requires --recommendation"
+        return
+    fi
+
+    local cs_file
+    cs_file="$(_council_deliberations_file)"
+
+    if [[ ! -f "$cs_file" ]]; then
+        json_err "$E_VALIDATION_FAILED" "No deliberations found; run council-deliberate first"
+        return
+    fi
+
+    local cs_exists
+    cs_exists=$(jq -r --arg id "$cs_id" '.deliberations[] | select(.id == $id) | .id' "$cs_file" 2>/dev/null || echo "")
+    if [[ -z "$cs_exists" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Deliberation not found: $cs_id"
+        return
+    fi
+
+    acquire_lock "$cs_file" 2>/dev/null || true
+    # shellcheck disable=SC2064
+    trap "release_lock '$cs_file' 2>/dev/null || true" EXIT
+
+    local cs_updated
+    cs_updated=$(jq \
+        --arg id "$cs_id" \
+        --arg synthesis "$cs_synthesis" \
+        --arg rec "$cs_recommendation" \
+        '(.deliberations[] | select(.id == $id)).sage = {"synthesis": $synthesis, "recommendation": $rec}
+         | (.deliberations[] | select(.id == $id)).status = "complete"' \
+        "$cs_file") || {
+        release_lock "$cs_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to record sage synthesis"
+        return
+    }
+
+    atomic_write "$cs_file" "$cs_updated" || {
+        release_lock "$cs_file" 2>/dev/null || true
+        trap - EXIT
+        json_err "$E_UNKNOWN" "Failed to persist sage synthesis"
+        return
+    }
+
+    release_lock "$cs_file" 2>/dev/null || true
+    trap - EXIT
+
+    json_ok "$(jq -n \
+        --arg rec "$cs_recommendation" \
+        '{"role":"sage","recommendation":$rec,"deliberation_complete":true}')"
+}
+
+# ---------------------------------------------------------------------------
+# _council_history
+# Usage: council-history [--limit N]
+# ---------------------------------------------------------------------------
+_council_history() {
+    local ch_limit=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --limit) ch_limit="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    local ch_file
+    ch_file="$(_council_deliberations_file)"
+
+    if [[ ! -f "$ch_file" ]]; then
+        json_ok '{"total":0,"deliberations":[]}'
+        return
+    fi
+
+    local ch_total
+    ch_total=$(jq '.deliberations | length' "$ch_file" 2>/dev/null || echo 0)
+
+    if [[ -n "$ch_limit" ]] && [[ "$ch_limit" =~ ^[0-9]+$ ]]; then
+        local ch_result
+        ch_result=$(jq \
+            --argjson limit "$ch_limit" \
+            --argjson total "$ch_total" \
+            '{"total":$total,"deliberations":(.deliberations | .[-($limit):])}' \
+            "$ch_file" 2>/dev/null) || ch_result='{"total":0,"deliberations":[]}'
+        json_ok "$ch_result"
+    else
+        local ch_result
+        ch_result=$(jq \
+            --argjson total "$ch_total" \
+            '{"total":$total,"deliberations":.deliberations}' \
+            "$ch_file" 2>/dev/null) || ch_result='{"total":0,"deliberations":[]}'
+        json_ok "$ch_result"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# _council_budget_check
+# Usage: council-budget-check [--budget N]
+# ---------------------------------------------------------------------------
+_council_budget_check() {
+    local cb_budget="3"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --budget) cb_budget="${2:-3}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if ! [[ "$cb_budget" =~ ^[0-9]+$ ]]; then
+        json_err "$E_VALIDATION_FAILED" "council-budget-check --budget must be a positive integer"
+        return
+    fi
+
+    # Delegate to spawn-can-spawn at depth 1
+    local cb_spawn_result
+    cb_spawn_result=$(_spawn_can_spawn 1 2>/dev/null || echo '{"can_spawn":false,"current_total":0,"global_cap":10}')
+
+    local cb_can
+    cb_can=$(echo "$cb_spawn_result" | jq -r '.result.can_spawn // .can_spawn // false' 2>/dev/null || echo "false")
+    local cb_current
+    cb_current=$(echo "$cb_spawn_result" | jq -r '.result.current_total // .current_total // 0' 2>/dev/null || echo 0)
+    local cb_cap
+    cb_cap=$(echo "$cb_spawn_result" | jq -r '.result.global_cap // .global_cap // 10' 2>/dev/null || echo 10)
+    local cb_remaining=$(( cb_cap - cb_current ))
+    [[ $cb_remaining -lt 0 ]] && cb_remaining=0
+
+    # allowed is true only if spawn is allowed AND remaining >= requested budget
+    local cb_allowed="false"
+    if [[ "$cb_can" == "true" ]] && [[ $cb_remaining -ge $cb_budget ]]; then
+        cb_allowed="true"
+    fi
+
+    json_ok "$(jq -n \
+        --argjson allowed "$cb_allowed" \
+        --argjson remaining "$cb_remaining" \
+        --argjson budget "$cb_budget" \
+        '{"allowed":$allowed,"remaining":$remaining,"budget":$budget}')"
+}

package/.aether/utils/emoji-audit.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# emoji-audit.sh — Audit emoji usage across Aether command files
+# Checks command files against the canonical emoji reference map defined in
+# .aether/skills/colony/colony-visuals/SKILL.md
+#
+# Usage: bash emoji-audit.sh [repo_root]
+#
+# Output: JSON compatible with aether-utils.sh subcommand pattern:
+#   {"ok": true, "result": {"files_scanned": N, "total_emojis": N,
+#     "unmapped": [...], "unused": [...], "usage": {...}}}
+#
+# Compatible with bash 3.x (macOS system bash).
+# Can be sourced by aether-utils.sh or run standalone.
+
+# ---------------------------------------------------------------------------
+# _emoji_audit_main — perform the audit and print JSON result
+# Uses Python3 for emoji extraction and map logic (handles multi-codepoint sequences)
+# ---------------------------------------------------------------------------
+_emoji_audit_main() {
+    local repo_root="${1:-.}"
+
+    if ! command -v python3 >/dev/null 2>&1; then
+        printf '{"ok":false,"error":"python3 is required but not found"}\n'
+        return 1
+    fi
+
+    python3 - "$repo_root" <<'PYEOF'
+import sys
+import os
+import re
+import json
+import glob
+
+repo_root = sys.argv[1] if len(sys.argv) > 1 else "."
+
+# ---------------------------------------------------------------------------
+# Canonical emoji reference map — must match colony-visuals SKILL.md
+# ---------------------------------------------------------------------------
+EMOJI_REF_MAP = {
+    "\U0001f528":        "Builder ant",           # 🔨
+    "\U0001f441\ufe0f": "Watcher ant",            # 👁️
+    "\U0001f3b2":        "Chaos ant",             # 🎲
+    "\U0001f50d":        "Scout ant",             # 🔍
+    "\U0001f3fa":        "Archaeologist / Seal",  # 🏺
+    "\U0001f52e":        "Oracle ant",            # 🔮
+    "\U0001f3db\ufe0f": "Architect ant",          # 🏛️
+    "\U0001f50c":        "Ambassador ant",        # 🔌
+    "\U0001f4ca":        "Measurer ant / Status", # 📊
+    "\U0001f9ea":        "Probe / Tests",         # 🧪
+    "\U0001f504":        "Weaver / Refresh",      # 🔄
+    "\U0001f4e6":        "Gatekeeper / Package",  # 📦
+    "\U0001f465":        "Auditor",               # 👥
+    "\U0001f6a9":        "Flag / Blocker",        # 🚩
+    "\U0001f4ad":        "Dream",                 # 💭
+    "\U0001f95a":        "Queen / Init",          # 🥚
+    "\U0001f4cb":        "Plan / List",           # 📋
+    "\u2705":            "Pass / Success",        # ✅
+    "\u274c":            "Fail / Error",          # ❌
+    "\u26a0\ufe0f":     "Warning",               # ⚠️
+    "\u26d4":            "Hard block",            # ⛔
+    "\U0001f4be":        "Save / Persist",        # 💾
+    "\U0001f3af":        "Focus signal",          # 🎯
+    "\U0001f6ab":        "Redirect signal",       # 🚫
+    "\U0001f4ac":        "Feedback signal",       # 💬
+}
+
+# ---------------------------------------------------------------------------
+# Scan command files
+# ---------------------------------------------------------------------------
+scan_dirs = [
+    os.path.join(repo_root, ".claude", "commands", "ant"),
+    os.path.join(repo_root, ".opencode", "commands", "ant"),
+]
+
+scan_files = []
+for d in scan_dirs:
+    if os.path.isdir(d):
+        scan_files.extend(glob.glob(os.path.join(d, "*.md")))
+
+files_scanned = len(scan_files)
+
+# ---------------------------------------------------------------------------
+# Extract emoji sequences from combined content
+# Matches base emoji + optional variation selectors, ZWJ sequences
+# ---------------------------------------------------------------------------
+EMOJI_PATTERN = re.compile(
+    r'[\U0001F300-\U0001F9FF\U00002600-\U000027BF\U00002702-\U000027B0'
+    r'\U0001FA00-\U0001FA9F\U0001FAA0-\U0001FAFF\U00002300-\U000023FF'
+    r'\U00002B00-\U00002BFF\U00003000-\U0000303F'
+    r'\U0001F600-\U0001F64F\U0001F680-\U0001F6FF'
+    r'\u2300-\u27BF\u2B00-\u2BFF\u2600-\u27FF'
+    r'\u2702-\u27B0\u2194-\u21AA\u231A-\u231B\u23E9-\u23F3\u23F8-\u23FA'
+    r'\u25AA-\u25FE\u2614-\u2615\u2648-\u2653\u267F\u2693\u26A0-\u26A1'
+    r'\u26AA-\u26AB\u26BD-\u26BE\u26C4-\u26C5\u26CE\u26D4\u26EA'
+    r'\u26F2-\u26F3\u26F5\u26FA\u26FD\u2702\u2705\u2708-\u270D'
+    r'\u270F\u2712\u2714\u2716\u271D\u2721\u2728\u2733-\u2734\u2744'
+    r'\u2747\u274C\u274E\u2753-\u2755\u2757\u2763-\u2764\u2795-\u2797'
+    r'\u27A1\u27B0\u27BF\u2934-\u2935\u2B05-\u2B07\u2B1B-\u2B1C\u2B50'
+    r'\u2B55\u3030\u303D\u3297\u3299]'
+    r'[\uFE0E\uFE0F\u20D0-\u20FF\u200D\U0001F3FB-\U0001F3FF]*'
+    r'(?:\u200D[\U0001F300-\U0001FFFF\u2600-\u27BF][\uFE0E\uFE0F\u20D0-\u20FF]*)*',
+    re.UNICODE
+)
+
+found_emojis = set()
+for filepath in scan_files:
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="replace") as fh:
+            content = fh.read()
+        for m in EMOJI_PATTERN.finditer(content):
+            e = m.group(0)
+            if e.strip():
+                found_emojis.add(e)
+    except OSError:
+        pass
+
+total_emojis = len(found_emojis)
+
+# ---------------------------------------------------------------------------
+# Compute results
+# ---------------------------------------------------------------------------
+# Normalize ref map keys for lookup (strip variation selectors for comparison)
+def normalize(s):
+    return s.replace("\ufe0f", "").replace("\ufe0e", "")
+
+ref_normalized = {normalize(k): (k, v) for k, v in EMOJI_REF_MAP.items()}
+found_normalized = {normalize(e): e for e in found_emojis}
+
+# unmapped: found in files but not in reference map (by normalized form)
+unmapped = sorted([
+    raw for norm, raw in found_normalized.items()
+    if norm not in ref_normalized
+])
+
+# unused: in reference map but not found in files (by normalized form)
+unused = sorted([
+    canonical for norm, (canonical, concept) in ref_normalized.items()
+    if norm not in found_normalized
+])
+
+# usage: reference map entries found in files -> concept
+usage = {}
+for norm, (canonical, concept) in ref_normalized.items():
+    if norm in found_normalized:
+        usage[canonical] = concept
+
+output = {
+    "ok": True,
+    "result": {
+        "files_scanned": files_scanned,
+        "total_emojis": total_emojis,
+        "unmapped": unmapped,
+        "unused": unused,
+        "usage": usage,
+    }
+}
+print(json.dumps(output))
+PYEOF
+}
+
+# ---------------------------------------------------------------------------
+# Entry point when run as a standalone script
+# ---------------------------------------------------------------------------
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    _emoji_audit_main "${1:-$(pwd)}"
+fi

package/.aether/utils/error-handler.sh

@@ -87,8 +87,8 @@ json_err() {
     "$code" "$escaped_message" "$details_json" "$recovery" "$timestamp" >&2
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] ERROR $code: $escaped_message" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]] && [[ "${AETHER_TESTING:-}" != "1" ]]; then
+    echo "[$timestamp] ERROR $code: $escaped_message" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
   fi
 
   exit 1
@@ -111,8 +111,22 @@ json_warn() {
     "$code" "$escaped_message" "$timestamp"
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] WARN $code: $escaped_message" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]] && [[ "${AETHER_TESTING:-}" != "1" ]]; then
+    echo "[$timestamp] WARN $code: $escaped_message" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
+  fi
+}
+
+# --- _aether_log_error function for surfaced errors ---
+# Dual output: [error] prefix to stderr (screen) + timestamped entry to errors.log (file)
+# Distinct from: json_err (structured JSON), json_warn (non-fatal JSON), ⚠ (recovery), [trimmed] (budget)
+_aether_log_error() {
+  local message="$1"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  echo "[error] $message" >&2
+  if [[ -n "${COLONY_DATA_DIR:-}" ]]; then
+    mkdir -p "$DATA_DIR" 2>/dev/null  # SUPPRESS:OK -- idempotent: ensure dir exists
+    echo "[$timestamp] $message" >> "$COLONY_DATA_DIR/errors.log" 2>/dev/null  # SUPPRESS:OK -- cleanup: log write is best-effort
   fi
 }
 
@@ -139,8 +153,8 @@ error_handler() {
     "$E_BASH_ERROR" "$details" "$(_recovery_default)" "$timestamp" >&2
 
   # Log to activity.log (best effort)
-  if [[ -n "${DATA_DIR:-}" ]]; then
-    echo "[$timestamp] ERROR $E_BASH_ERROR: Command failed at line $line_num (exit $exit_code)" >> "$DATA_DIR/activity.log" 2>/dev/null || true
+  if [[ -n "${COLONY_DATA_DIR:-}" ]] && [[ "${AETHER_TESTING:-}" != "1" ]]; then
+    echo "[$timestamp] ERROR $E_BASH_ERROR: Command failed at line $line_num (exit $exit_code)" >> "$COLONY_DATA_DIR/activity.log" 2>/dev/null || true
   fi
 
   exit 1
@@ -198,7 +212,7 @@ feature_log_degradation() {
 }
 
 # --- Export all functions and variables ---
-export -f json_err json_warn error_handler
+export -f json_err json_warn _aether_log_error error_handler
 export -f feature_enable feature_disable feature_enabled feature_log_degradation
 export -f _get_recovery _recovery_hub_not_found _recovery_repo_not_init
 export -f _recovery_file_not_found _recovery_json_invalid _recovery_lock_failed