aether-colony 5.1.0 → 5.2.1

package/.aether/utils/immune.sh

@@ -0,0 +1,508 @@
+#!/bin/bash
+# Immune response system — trophallaxis repair and scarification
+# Provides: _trophallaxis_diagnose, _trophallaxis_retry, _scar_add, _scar_list,
+#           _scar_check, _immune_auto_scar
+#
+# 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.
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_immune_data_dir() {
+    echo "$COLONY_DATA_DIR/immune"
+}
+
+_immune_scars_file() {
+    echo "$COLONY_DATA_DIR/immune/scars.json"
+}
+
+_immune_retry_log_file() {
+    echo "$COLONY_DATA_DIR/immune/retry-log.json"
+}
+
+_immune_ensure_dir() {
+    mkdir -p "$(_immune_data_dir)"
+}
+
+_immune_ensure_scars_file() {
+    local sf
+    sf="$(_immune_scars_file)"
+    _immune_ensure_dir
+    if [[ ! -f "$sf" ]]; then
+        printf '%s\n' '{"version":"1.0","scars":[]}' > "$sf"
+    fi
+}
+
+_immune_ensure_retry_log() {
+    local rf
+    rf="$(_immune_retry_log_file)"
+    _immune_ensure_dir
+    if [[ ! -f "$rf" ]]; then
+        printf '%s\n' '{"version":"1.0","tasks":{}}' > "$rf"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# _trophallaxis_diagnose
+# Usage: trophallaxis-diagnose --task-id <id> --failure <desc> [--phase N]
+# ---------------------------------------------------------------------------
+_trophallaxis_diagnose() {
+    local td_task_id=""
+    local td_failure=""
+    local td_phase=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --task-id) td_task_id="${2:-}"; shift 2 ;;
+            --failure)  td_failure="${2:-}";  shift 2 ;;
+            --phase)    td_phase="${2:-}";    shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$td_task_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "trophallaxis-diagnose requires --task-id"
+        return
+    fi
+
+    if [[ -z "$td_failure" ]]; then
+        json_err "$E_VALIDATION_FAILED" "trophallaxis-diagnose requires --failure"
+        return
+    fi
+
+    local td_midden_file="$COLONY_DATA_DIR/midden/midden.json"
+    local td_related=0
+    local td_related_entries="[]"
+    local td_approach=""
+
+    # Search midden for related entries using keywords from failure description
+    if [[ -f "$td_midden_file" ]]; then
+        # Extract first keyword (longest word >= 4 chars) for search
+        local td_keyword
+        td_keyword=$(echo "$td_failure" | tr '[:upper:]' '[:lower:]' | \
+            grep -oE '[a-z]{4,}' | sort -rn -k1,1 | head -1 || echo "")
+
+        if [[ -n "$td_keyword" ]]; then
+            td_related=$(jq \
+                --arg q "$td_keyword" \
+                '[.entries // [] | .[] |
+                  select(.acknowledged != true) |
+                  select(.message | ascii_downcase | contains($q))
+                ] | length' "$td_midden_file" 2>/dev/null || echo "0")
+
+            td_related_entries=$(jq \
+                --arg q "$td_keyword" \
+                '[.entries // [] | .[] |
+                  select(.acknowledged != true) |
+                  select(.message | ascii_downcase | contains($q)) |
+                  {id, timestamp, category, source, message}
+                ] | .[:5]' "$td_midden_file" 2>/dev/null || echo "[]")
+        else
+            # No usable keyword — scan all recent entries
+            td_related=$(jq '[.entries // [] | .[] | select(.acknowledged != true)] | length' \
+                "$td_midden_file" 2>/dev/null || echo "0")
+        fi
+    fi
+
+    # Build diagnosis text
+    local td_diagnosis
+    if [[ "$td_related" -gt 0 ]]; then
+        td_diagnosis="Found $td_related related failure(s) in midden matching: $td_failure"
+        td_approach="Review related midden entries for patterns. Address root cause before retrying."
+    else
+        td_diagnosis="No related failures found in midden for: $td_failure"
+        td_approach="Investigate failure from first principles. Check logs and dependencies."
+    fi
+
+    # Confidence: higher when related failures exist
+    local td_confidence
+    if [[ "$td_related" -ge 3 ]]; then
+        td_confidence="0.9"
+    elif [[ "$td_related" -ge 1 ]]; then
+        td_confidence="0.7"
+    else
+        td_confidence="0.4"
+    fi
+
+    json_ok "$(jq -n \
+        --arg task_id "$td_task_id" \
+        --arg failure "$td_failure" \
+        --arg diagnosis "$td_diagnosis" \
+        --argjson related_failures "$td_related" \
+        --arg suggested_approach "$td_approach" \
+        --argjson confidence "$td_confidence" \
+        --argjson related_entries "$td_related_entries" \
+        '{
+            task_id: $task_id,
+            failure: $failure,
+            diagnosis: $diagnosis,
+            related_failures: $related_failures,
+            suggested_approach: $suggested_approach,
+            confidence: $confidence,
+            related_entries: $related_entries
+        }')"
+}
+
+# ---------------------------------------------------------------------------
+# _trophallaxis_retry
+# Usage: trophallaxis-retry --task-id <id> --diagnosis <json>
+# ---------------------------------------------------------------------------
+_trophallaxis_retry() {
+    local tr_task_id=""
+    local tr_diagnosis=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --task-id)  tr_task_id="${2:-}";   shift 2 ;;
+            --diagnosis) tr_diagnosis="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$tr_task_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "trophallaxis-retry requires --task-id"
+        return
+    fi
+
+    _immune_ensure_retry_log
+
+    local tr_log_file
+    tr_log_file="$(_immune_retry_log_file)"
+    local tr_timestamp
+    tr_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Read current retry count for this task
+    local tr_current_count
+    tr_current_count=$(jq -r --arg tid "$tr_task_id" \
+        '.tasks[$tid].retry_count // 0' "$tr_log_file" 2>/dev/null || echo "0")
+    local tr_new_count=$(( tr_current_count + 1 ))
+
+    # Validate diagnosis JSON (graceful: use empty object if invalid)
+    local tr_diag_json
+    if echo "$tr_diagnosis" | jq empty 2>/dev/null; then
+        tr_diag_json="$tr_diagnosis"
+    else
+        tr_diag_json="{}"
+    fi
+
+    # Build the retry entry
+    local tr_entry
+    tr_entry=$(jq -n \
+        --arg ts "$tr_timestamp" \
+        --argjson retry_count "$tr_new_count" \
+        --argjson diagnosis "$tr_diag_json" \
+        '{timestamp: $ts, retry_count: $retry_count, diagnosis: $diagnosis}')
+
+    # Update log with locking
+    local tr_updated
+    if acquire_lock "$tr_log_file" 2>/dev/null; then
+        tr_updated=$(jq \
+            --arg tid "$tr_task_id" \
+            --argjson entry "$tr_entry" \
+            --argjson new_count "$tr_new_count" \
+            '.tasks[$tid] = {
+                retry_count: $new_count,
+                last_attempt: $entry.timestamp,
+                last_diagnosis: $entry.diagnosis,
+                history: ((.tasks[$tid].history // []) + [$entry])
+            }' "$tr_log_file" 2>/dev/null)
+
+        if [[ -n "$tr_updated" ]]; then
+            atomic_write "$tr_log_file" "$tr_updated"
+        fi
+        release_lock 2>/dev/null || true
+    else
+        # Lockless fallback
+        tr_updated=$(jq \
+            --arg tid "$tr_task_id" \
+            --argjson entry "$tr_entry" \
+            --argjson new_count "$tr_new_count" \
+            '.tasks[$tid] = {
+                retry_count: $new_count,
+                last_attempt: $entry.timestamp,
+                last_diagnosis: $entry.diagnosis,
+                history: ((.tasks[$tid].history // []) + [$entry])
+            }' "$tr_log_file" 2>/dev/null)
+
+        if [[ -n "$tr_updated" ]]; then
+            atomic_write "$tr_log_file" "$tr_updated"
+        fi
+    fi
+
+    json_ok "$(jq -n \
+        --arg task_id "$tr_task_id" \
+        --argjson retry_count "$tr_new_count" \
+        '{task_id: $task_id, retry_count: $retry_count, diagnosis_injected: true}')"
+}
+
+# ---------------------------------------------------------------------------
+# _scar_add
+# Usage: scar-add --pattern <desc> --severity <low|medium|high> [--phase N] [--source <src>]
+# ---------------------------------------------------------------------------
+_scar_add() {
+    local sa_pattern=""
+    local sa_severity=""
+    local sa_phase=""
+    local sa_source="unknown"
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --pattern)  sa_pattern="${2:-}";  shift 2 ;;
+            --severity) sa_severity="${2:-}"; shift 2 ;;
+            --phase)    sa_phase="${2:-}";    shift 2 ;;
+            --source)   sa_source="${2:-}";   shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$sa_pattern" ]]; then
+        json_err "$E_VALIDATION_FAILED" "scar-add requires --pattern"
+        return
+    fi
+
+    # Default severity if not provided
+    if [[ -z "$sa_severity" ]]; then
+        sa_severity="medium"
+    fi
+
+    # Validate severity
+    case "$sa_severity" in
+        low|medium|high) ;;
+        *)
+            json_err "$E_VALIDATION_FAILED" "scar-add --severity must be low, medium, or high"
+            return
+            ;;
+    esac
+
+    _immune_ensure_scars_file
+
+    local sa_scars_file
+    sa_scars_file="$(_immune_scars_file)"
+    local sa_timestamp
+    sa_timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local sa_id
+    sa_id="scar_$(date +%s)_$$"
+
+    # Build phase value for JSON
+    local sa_phase_val
+    if [[ -n "$sa_phase" ]]; then
+        sa_phase_val="$sa_phase"
+    else
+        sa_phase_val="null"
+    fi
+
+    local sa_new_scar
+    sa_new_scar=$(jq -n \
+        --arg id "$sa_id" \
+        --arg pattern "$sa_pattern" \
+        --arg severity "$sa_severity" \
+        --arg phase "$sa_phase_val" \
+        --arg source "$sa_source" \
+        --arg created_at "$sa_timestamp" \
+        '{
+            id: $id,
+            pattern: $pattern,
+            severity: $severity,
+            phase: (if $phase == "null" then null else ($phase | tonumber? // $phase) end),
+            source: $source,
+            created_at: $created_at,
+            retry_count: 0,
+            active: true
+        }')
+
+    local sa_updated
+    if acquire_lock "$sa_scars_file" 2>/dev/null; then
+        sa_updated=$(jq \
+            --argjson scar "$sa_new_scar" \
+            '.scars += [$scar]' "$sa_scars_file" 2>/dev/null)
+        if [[ -n "$sa_updated" ]]; then
+            atomic_write "$sa_scars_file" "$sa_updated"
+        fi
+        release_lock 2>/dev/null || true
+    else
+        sa_updated=$(jq \
+            --argjson scar "$sa_new_scar" \
+            '.scars += [$scar]' "$sa_scars_file" 2>/dev/null)
+        if [[ -n "$sa_updated" ]]; then
+            atomic_write "$sa_scars_file" "$sa_updated"
+        fi
+    fi
+
+    local sa_count
+    sa_count=$(jq '[.scars[]] | length' "$sa_scars_file" 2>/dev/null || echo "1")
+
+    json_ok "$(jq -n \
+        --arg id "$sa_id" \
+        --argjson scar_count "$sa_count" \
+        '{id: $id, scar_count: $scar_count}')"
+}
+
+# ---------------------------------------------------------------------------
+# _scar_list
+# Usage: scar-list [--active] [--severity <level>]
+# ---------------------------------------------------------------------------
+_scar_list() {
+    local sl_active_only=false
+    local sl_severity=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --active)   sl_active_only=true; shift ;;
+            --severity) sl_severity="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    local sl_scars_file
+    sl_scars_file="$(_immune_scars_file)"
+
+    if [[ ! -f "$sl_scars_file" ]]; then
+        json_ok '{"total":0,"active":0,"scars":[]}'
+        return 0
+    fi
+
+    local sl_result
+    sl_result=$(jq \
+        --argjson active_only "$sl_active_only" \
+        --arg severity "$sl_severity" \
+        '
+        [.scars // [] | .[] |
+            if $active_only then select(.active == true) else . end |
+            if ($severity | length) > 0 then select(.severity == $severity) else . end
+        ] |
+        . as $filtered |
+        {
+            total: ($filtered | length),
+            active: ($filtered | map(select(.active == true)) | length),
+            scars: $filtered
+        }
+        ' "$sl_scars_file" 2>/dev/null)
+
+    if [[ -z "$sl_result" ]]; then
+        json_ok '{"total":0,"active":0,"scars":[]}'
+        return 0
+    fi
+
+    json_ok "$sl_result"
+}
+
+# ---------------------------------------------------------------------------
+# _scar_check
+# Usage: scar-check --task <desc>
+# ---------------------------------------------------------------------------
+_scar_check() {
+    local sc_task=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --task) sc_task="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$sc_task" ]]; then
+        json_err "$E_VALIDATION_FAILED" "scar-check requires --task"
+        return
+    fi
+
+    local sc_scars_file
+    sc_scars_file="$(_immune_scars_file)"
+
+    if [[ ! -f "$sc_scars_file" ]]; then
+        json_ok '{"matches":0,"scars":[]}'
+        return 0
+    fi
+
+    local sc_result
+    sc_result=$(jq \
+        --arg task "$sc_task" \
+        '
+        [.scars // [] | .[] |
+            select(.active == true) |
+            # Split pattern into words, check if any word from pattern appears in task
+            select(
+                (.pattern | ascii_downcase) as $pat |
+                ($pat | split(" ") | .[] | select(length >= 3)) as $word |
+                ($task | ascii_downcase) | contains($word)
+            )
+        ] |
+        . as $matches |
+        {
+            matches: ($matches | length),
+            scars: $matches
+        }
+        ' "$sc_scars_file" 2>/dev/null)
+
+    if [[ -z "$sc_result" ]]; then
+        json_ok '{"matches":0,"scars":[]}'
+        return 0
+    fi
+
+    json_ok "$sc_result"
+}
+
+# ---------------------------------------------------------------------------
+# _immune_auto_scar
+# Usage: immune-auto-scar --task-id <id>
+# ---------------------------------------------------------------------------
+_immune_auto_scar() {
+    local ias_task_id=""
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --task-id) ias_task_id="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [[ -z "$ias_task_id" ]]; then
+        json_err "$E_VALIDATION_FAILED" "immune-auto-scar requires --task-id"
+        return
+    fi
+
+    local ias_log_file
+    ias_log_file="$(_immune_retry_log_file)"
+
+    if [[ ! -f "$ias_log_file" ]]; then
+        json_ok '{"auto_scarred":false,"retry_count":0}'
+        return 0
+    fi
+
+    local ias_retry_count
+    ias_retry_count=$(jq -r --arg tid "$ias_task_id" \
+        '.tasks[$tid].retry_count // 0' "$ias_log_file" 2>/dev/null || echo "0")
+
+    if [[ "$ias_retry_count" -lt 3 ]]; then
+        json_ok "$(jq -n \
+            --argjson retry_count "$ias_retry_count" \
+            '{auto_scarred: false, retry_count: $retry_count}')"
+        return 0
+    fi
+
+    # Auto-create a scar for this task
+    local ias_last_diagnosis
+    ias_last_diagnosis=$(jq -r --arg tid "$ias_task_id" \
+        '.tasks[$tid].last_diagnosis.failure // ""' "$ias_log_file" 2>/dev/null || echo "")
+
+    local ias_pattern
+    if [[ -n "$ias_last_diagnosis" ]]; then
+        ias_pattern="$ias_last_diagnosis"
+    else
+        ias_pattern="task $ias_task_id failed persistently (auto-scarred after $ias_retry_count retries)"
+    fi
+
+    # Determine severity based on retry count
+    local ias_severity="medium"
+    if [[ "$ias_retry_count" -ge 5 ]]; then
+        ias_severity="high"
+    fi
+
+    _scar_add --pattern "$ias_pattern" --severity "$ias_severity" --source "immune-auto-scar" >/dev/null
+
+    json_ok "$(jq -n \
+        --argjson retry_count "$ias_retry_count" \
+        '{auto_scarred: true, retry_count: $retry_count}')"
+}

package/.aether/utils/learning.sh

@@ -431,11 +431,11 @@ _learning_promote_auto() {
         # SUPPRESS:OK -- read-default: returns fallback on failure
         --evidence "Auto-promoted after $observation_count observations (confidence: $lp_confidence)" 2>/dev/null \
         || _aether_log_error "Could not create instinct from promoted learning"
-      json_ok "$(jq -n --argjson pt "$policy_threshold" --argjson oc "$observation_count" --argjson cc "$colony_count" --arg et "$event_type" '{promoted: true, mode: "auto", policy_threshold: $pt, observation_count: $oc, colony_count: $cc, event_type: $et}')"
+      json_ok "$(jq -nc --argjson pt "$policy_threshold" --argjson oc "$observation_count" --argjson cc "$colony_count" --arg et "$event_type" '{promoted: true, mode: "auto", policy_threshold: $pt, observation_count: $oc, colony_count: $cc, event_type: $et}')"
     else
       # SUPPRESS:OK -- read-default: query may return empty
       promote_msg=$(echo "$promote_result" | jq -r '.error.message // "promotion_failed"' 2>/dev/null || echo "promotion_failed")
-      result=$(jq -n \
+      result=$(jq -nc \
         --arg reason "promotion_failed" \
         --arg message "$promote_msg" \
         --argjson policy_threshold "$policy_threshold" \

package/.aether/utils/midden.sh

@@ -244,6 +244,184 @@ _midden_ingest_errors() {
     return 0
 }
 
+_midden_search() {
+    # Search midden entries by keyword match in message field
+    # Usage: midden-search <query> [--category <cat>] [--source <src>] [--limit N] [--include-acknowledged]
+    # Returns: JSON with query, match_count, and entries array
+
+    ms_query=""
+    ms_category=""
+    ms_source=""
+    ms_limit=10
+    ms_include_ack=false
+
+    # First positional arg is the query
+    if [[ $# -gt 0 && "$1" != --* ]]; then
+      ms_query="$1"
+      shift
+    fi
+
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --category)             ms_category="${2:-}"; shift 2 ;;
+        --source)               ms_source="${2:-}"; shift 2 ;;
+        --limit)                ms_limit="${2:-10}"; shift 2 ;;
+        --include-acknowledged) ms_include_ack=true; shift ;;
+        *) shift ;;
+      esac
+    done
+
+    ms_midden_file="$COLONY_DATA_DIR/midden/midden.json"
+
+    if [[ ! -f "$ms_midden_file" ]]; then
+      json_ok "{\"query\":$(printf '%s' "$ms_query" | jq -Rs .),\"match_count\":0,\"entries\":[]}"
+      return 0
+    fi
+
+    ms_result=$(jq \
+      --arg query "$ms_query" \
+      --arg category "$ms_category" \
+      --arg source "$ms_source" \
+      --argjson limit "$ms_limit" \
+      --argjson include_ack "$ms_include_ack" \
+      '
+      [.entries // [] | .[] |
+        # Filter acknowledged unless --include-acknowledged
+        if $include_ack then . else select(.acknowledged != true) end |
+        # Filter by category if specified
+        if ($category | length) > 0 then select(.category == $category) else . end |
+        # Filter by source if specified
+        if ($source | length) > 0 then select(.source == $source) else . end |
+        # Filter by keyword match in message (case-insensitive)
+        if ($query | length) > 0 then
+          select(.message | ascii_downcase | contains($query | ascii_downcase))
+        else
+          .
+        end
+      ] |
+      sort_by(.timestamp) | reverse |
+      . as $all |
+      {
+        query: $query,
+        match_count: ($all | length),
+        entries: ($all | .[:$limit])
+      }
+      ' "$ms_midden_file" 2>/dev/null)
+
+    if [[ -z "$ms_result" ]]; then
+      json_ok "{\"query\":$(printf '%s' "$ms_query" | jq -Rs .),\"match_count\":0,\"entries\":[]}"
+    else
+      json_ok "$ms_result"
+    fi
+    return 0
+}
+
+_midden_tag() {
+    # Add or remove a tag from a midden entry's tags array
+    # Usage: midden-tag --id <entry_id> --tag <tag_name>
+    #    OR: midden-tag --id <entry_id> --untag <tag_name>
+    # Returns: JSON with entry_id, tags array, and action
+
+    mt_id=""
+    mt_tag=""
+    mt_untag=""
+
+    while [[ $# -gt 0 ]]; do
+      case "$1" in
+        --id)    mt_id="${2:-}"; shift 2 ;;
+        --tag)   mt_tag="${2:-}"; shift 2 ;;
+        --untag) mt_untag="${2:-}"; shift 2 ;;
+        *) shift ;;
+      esac
+    done
+
+    # Validate: need --id
+    if [[ -z "$mt_id" ]]; then
+      json_err "$E_VALIDATION_FAILED" "midden-tag requires --id"
+    fi
+
+    # Validate: need --tag or --untag (but not both)
+    if [[ -z "$mt_tag" && -z "$mt_untag" ]]; then
+      json_err "$E_VALIDATION_FAILED" "midden-tag requires --tag or --untag"
+    fi
+
+    if [[ -n "$mt_tag" && -n "$mt_untag" ]]; then
+      json_err "$E_VALIDATION_FAILED" "midden-tag requires --tag or --untag, not both"
+    fi
+
+    mt_midden_file="$COLONY_DATA_DIR/midden/midden.json"
+
+    if [[ ! -f "$mt_midden_file" ]]; then
+      json_err "$E_FILE_NOT_FOUND" "midden.json not found"
+    fi
+
+    # Check entry exists
+    mt_exists=$(jq --arg id "$mt_id" '[.entries[]? | select(.id == $id)] | length > 0' "$mt_midden_file" 2>/dev/null || echo "false")
+    if [[ "$mt_exists" != "true" ]]; then
+      json_err "$E_RESOURCE_NOT_FOUND" "Midden entry '$mt_id' not found"
+    fi
+
+    # Acquire lock with trap-based cleanup
+    acquire_lock "$mt_midden_file" || {
+      json_err "$E_LOCK_FAILED" "Failed to acquire lock on midden.json"
+    }
+    trap 'release_lock 2>/dev/null || true' EXIT
+
+    if [[ -n "$mt_tag" ]]; then
+      # Add tag — create tags array if absent, append if tag not already present
+      mt_updated=$(jq \
+        --arg id "$mt_id" \
+        --arg tag "$mt_tag" \
+        '
+        .entries = [.entries[] |
+          if .id == $id then
+            . + {tags: ((.tags // []) | if contains([$tag]) then . else . + [$tag] end)}
+          else
+            .
+          end
+        ]
+        ' "$mt_midden_file" 2>/dev/null)
+      mt_action="added"
+    else
+      # Remove tag — remove from tags array if present
+      mt_updated=$(jq \
+        --arg id "$mt_id" \
+        --arg tag "$mt_untag" \
+        '
+        .entries = [.entries[] |
+          if .id == $id then
+            . + {tags: ((.tags // []) | map(select(. != $tag)))}
+          else
+            .
+          end
+        ]
+        ' "$mt_midden_file" 2>/dev/null)
+      mt_action="removed"
+      mt_tag="$mt_untag"
+    fi
+
+    if [[ -z "$mt_updated" ]]; then
+      trap - EXIT
+      release_lock 2>/dev/null || true
+      json_err "$E_INTERNAL" "Failed to update midden.json"
+    fi
+
+    atomic_write "$mt_midden_file" "$mt_updated"
+
+    trap - EXIT
+    release_lock 2>/dev/null || true
+
+    # Read back the updated tags for the entry
+    mt_tags=$(jq --arg id "$mt_id" '[.entries[]? | select(.id == $id) | .tags // []] | .[0] // []' "$mt_midden_file" 2>/dev/null || echo "[]")
+
+    json_ok "$(jq -n \
+      --arg entry_id "$mt_id" \
+      --argjson tags "$mt_tags" \
+      --arg action "$mt_action" \
+      '{entry_id: $entry_id, tags: $tags, action: $action}')"
+    return 0
+}
+
 _midden_acknowledge() {
     # Acknowledge midden entries by id or by category
     # Usage: midden-acknowledge --id <entry_id> [--reason <reason>]