@cohortapp/agent-sdk 2.3.0

package/scripts/local-triggers/templates/voice-tunnel.plist.template

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- maestro-plist-arch: cadence-bus v1 -->
+<!-- voice-tunnel plist template — exposes voice-webhook-server publicly
+     via cloudflared for Twilio webhooks + OpenAI SIP webhook delivery. -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.maestro.{{FIRSTNAME}}-voice-tunnel</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/opt/homebrew/bin/cloudflared</string>
+        <string>tunnel</string>
+        <string>--url</string>
+        <string>http://localhost:3200</string>
+        <string>--no-autoupdate</string>
+        <string>--logfile</string>
+        <string>{{AGENT_ROOT}}/logs/voice/cloudflared.log</string>
+        <string>--loglevel</string>
+        <string>info</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{AGENT_ROOT}}</string>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>ThrottleInterval</key>
+    <integer>15</integer>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>USER</key>
+        <string>{{USER}}</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/cloudflared-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/cloudflared-stderr.log</string>
+</dict>
+</plist>

package/scripts/local-triggers/templates/voice-webhook.plist.template

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- maestro-plist-arch: cadence-bus v1 -->
+<!-- voice-webhook plist template — installed by setup wizard -->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.maestro.{{FIRSTNAME}}-voice-webhook</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_BIN}}</string>
+        <string>{{AGENT_ROOT}}/scripts/daemon/voice-webhook-server.mjs</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{AGENT_ROOT}}</string>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>ThrottleInterval</key>
+    <integer>30</integer>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>USER</key>
+        <string>{{USER}}</string>
+        <key>AGENT_ROOT</key>
+        <string>{{AGENT_ROOT}}</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/voice-webhook-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{AGENT_ROOT}}/logs/voice/voice-webhook-stderr.log</string>
+</dict>
+</plist>

package/scripts/maintenance/backup-to-cloud.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# backup-to-cloud.sh — Off-machine state backup driver.
+#
+# Reads .maestro/backup-config.yaml and pushes the configured paths to GCS
+# or S3 (or rsyncs to a remote host). Designed to be invoked daily via a
+# launchd plist. Idempotent; safe to re-run.
+#
+# If .maestro/backup-config.yaml is missing or `enabled: false`, exits 0
+# silently. Errors during upload are logged to logs/maintenance/backup.log
+# and surface in `maestro doctor`.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CFG="$AGENT_DIR/.maestro/backup-config.yaml"
+LOG_DIR="$AGENT_DIR/logs/maintenance"
+LOG="$LOG_DIR/backup.log"
+mkdir -p "$LOG_DIR"
+
+log() { echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] $1" | tee -a "$LOG"; }
+
+if [ ! -f "$CFG" ]; then
+    log "backup-config.yaml not found — backup not configured. Run: maestro init backup-replication --apply"
+    exit 0
+fi
+
+# Tiny YAML reader (only the fields we need).
+get() {
+    awk -v k="$1" '
+      $1 == k":" { sub(/^[^:]+:[[:space:]]*/, "", $0); gsub(/^"|"$/, "", $0); print; exit }
+    ' "$CFG"
+}
+
+ENABLED=$(get enabled)
+if [ "$ENABLED" != "true" ]; then
+    log "Backup not enabled (.maestro/backup-config.yaml: enabled: false). Skipping."
+    exit 0
+fi
+
+PROVIDER=$(get provider)
+BUCKET=$(get bucket)
+PREFIX=$(get prefix)
+RETENTION=$(get retention_days)
+[ -z "$RETENTION" ] && RETENTION=30
+
+if [ -z "$BUCKET" ] || [ -z "$PROVIDER" ] || [ -z "$PREFIX" ]; then
+    log "ERROR: backup-config.yaml missing required fields (provider / bucket / prefix)."
+    exit 1
+fi
+
+DATE=$(date -u +"%Y-%m-%d")
+log "Starting backup → $PROVIDER://$BUCKET/$PREFIX/$DATE/"
+
+# Default include paths if the YAML doesn't override them.
+INCLUDE_DEFAULT=(state knowledge outputs config/agent.json)
+INCLUDE_PATHS=()
+in_include=0
+while IFS= read -r line; do
+    if echo "$line" | grep -qE "^include:"; then in_include=1; continue; fi
+    if [ "$in_include" = "1" ]; then
+        if echo "$line" | grep -qE "^[a-z]"; then in_include=0; continue; fi
+        path=$(echo "$line" | sed 's/^[[:space:]]*-[[:space:]]*//' | sed 's/[[:space:]]*$//')
+        [ -n "$path" ] && INCLUDE_PATHS+=("$path")
+    fi
+done < "$CFG"
+[ ${#INCLUDE_PATHS[@]} -eq 0 ] && INCLUDE_PATHS=("${INCLUDE_DEFAULT[@]}")
+
+# Build the archive
+TMP_DIR=$(mktemp -d)
+trap "rm -rf $TMP_DIR" EXIT
+TARBALL="$TMP_DIR/$PREFIX-$DATE.tar.gz"
+
+log "Packaging: ${INCLUDE_PATHS[*]}"
+tar --exclude="state/tmp" --exclude="state/rag/index" --exclude=".DS_Store" \
+    -czf "$TARBALL" -C "$AGENT_DIR" "${INCLUDE_PATHS[@]}" 2>>"$LOG" || {
+    log "ERROR: tar failed"
+    exit 1
+}
+SIZE=$(stat -f%z "$TARBALL")
+log "Packaged: $TARBALL ($SIZE bytes)"
+
+# Upload — choose provider.
+case "$PROVIDER" in
+    gcs)
+        if ! command -v gsutil >/dev/null 2>&1; then
+            log "ERROR: gsutil not found in PATH. Install gcloud SDK or change provider."
+            exit 1
+        fi
+        gsutil cp "$TARBALL" "gs://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
+        ;;
+    s3)
+        if ! command -v aws >/dev/null 2>&1; then
+            log "ERROR: aws CLI not found in PATH. Install awscli or change provider."
+            exit 1
+        fi
+        aws s3 cp "$TARBALL" "s3://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
+        ;;
+    rsync)
+        # bucket field carries the rsync target (user@host:/path)
+        rsync -avz "$TARBALL" "$BUCKET/$PREFIX/$DATE/" >>"$LOG" 2>&1
+        ;;
+    *)
+        log "ERROR: unknown provider '$PROVIDER'"
+        exit 1
+        ;;
+esac
+
+log "Upload complete: $PROVIDER://$BUCKET/$PREFIX/$DATE/"
+
+# Update .maestro/last-backup.json so doctor can verify freshness.
+mkdir -p "$AGENT_DIR/.maestro"
+cat > "$AGENT_DIR/.maestro/last-backup.json" <<JSON
+{
+  "completed_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "provider": "$PROVIDER",
+  "bucket": "$BUCKET",
+  "prefix": "$PREFIX",
+  "size_bytes": $SIZE,
+  "tarball": "$(basename "$TARBALL")"
+}
+JSON
+
+log "Backup complete."

package/scripts/maintenance/health-check.sh

@@ -0,0 +1,377 @@
+#!/bin/bash
+# health-check.sh — Daemon health alerting for all critical launchd services
+# Part of I-004: Daemon health alerting (AS-005 Phase 3 tech debt)
+#
+# Checks 5 critical launchd services for:
+#   - Service registration in launchctl
+#   - Non-zero PID (actually running)
+#   - Zero exit status (no crash)
+#   - Log freshness (recent polling activity)
+#   - Stderr log growth (error accumulation)
+#
+# Exit codes:
+#   0 = all healthy
+#   1 = one or more degraded
+#   2 = one or more down
+#
+# Usage:
+#   ./scripts/maintenance/health-check.sh            # Run full check + alert
+#   ./scripts/maintenance/health-check.sh --dry-run   # Check without Slack alert
+#   ./scripts/maintenance/health-check.sh --json       # Output JSON summary only
+
+set -e
+
+# --- Configuration ---
+BASE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+LOGS_DIR="$BASE_DIR/logs"
+SLACK_SEND="$BASE_DIR/scripts/slack-send.sh"
+
+# Derive agent identity from config/agent.json so this script is portable
+# across agent repos without per-agent edits. Both can be overridden via
+# env vars for testing.
+AGENT_FIRSTNAME="${AGENT_FIRSTNAME:-$(python3 -c "import json; print(json.load(open('$BASE_DIR/config/agent.json'))['firstName'].lower())" 2>/dev/null)}"
+AGENT_FIRSTNAME="${AGENT_FIRSTNAME:-agent}"
+PRINCIPAL_DM="${PRINCIPAL_DM:-$(python3 -c "import json; d=json.load(open('$BASE_DIR/config/agent.json')); print(d.get('slackMemberId',''))" 2>/dev/null)}"
+
+# Critical services to monitor — kept in sync with the 1.12.x architecture:
+#   - daemon                : main reactive event loop + cadence consumer
+#   - slack-events          : Slack Events API webhook server (port 3100)
+#   - slack-socket          : Slack Socket Mode WebSocket listener
+#   - slack-cloud-relay     : SSE client for Railway-hosted cloud relay
+#   - voice-webhook         : voice channel HTTP/WS server (port 3200, 1.12.5+)
+# Cadence-tick services (backlog-executor, daily-*, weekly-*) intentionally
+# excluded — they only run on schedule and have no continuous heartbeat.
+# Legacy services removed: <agent>-poller (absorbed into daemon),
+# whatsapp-handler (replaced by channel-bus + Baileys), poll-relay
+# (superseded by cloud-relay).
+# Launchd label namespace. The framework default is ai.maestro.*; agents deployed
+# before the rename still have ai.adaptic.* plists. Auto-detect from the installed
+# daemon plist so this check works across the upgrade window.
+LAUNCHD_NS="ai.maestro"
+if [ ! -f "$HOME/Library/LaunchAgents/ai.maestro.${AGENT_FIRSTNAME}-daemon.plist" ] && \
+   [ -f "$HOME/Library/LaunchAgents/ai.adaptic.${AGENT_FIRSTNAME}-daemon.plist" ]; then
+    LAUNCHD_NS="ai.adaptic"
+fi
+SERVICES="${LAUNCHD_NS}.${AGENT_FIRSTNAME}-daemon ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-events ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-socket ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-cloud-relay ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-voice-webhook"
+
+# Log freshness thresholds (seconds). The daemon uses cadence heartbeat
+# (state/cadence-bus/health.json) which updates every 15s; everything else
+# uses its named log file's mtime. Webhook-receiving services are silent
+# unless the upstream pushes events — generous thresholds reflect that.
+DAEMON_FRESHNESS=60           # cadence heartbeat — should be <30s
+SLACK_EVENTS_FRESHNESS=86400  # webhook receiver, can sit idle for hours
+SLACK_SOCKET_FRESHNESS=86400  # similar; logs only on connect/disconnect
+CLOUD_RELAY_FRESHNESS=86400   # similar
+VOICE_WEBHOOK_FRESHNESS=604800 # silent until first call (1 week)
+DEFAULT_FRESHNESS=600     # 10 minutes for any others
+
+# Stderr growth threshold (bytes) — alert if stderr exceeds this
+STDERR_THRESHOLD=102400   # 100 KB
+
+# Flags
+DRY_RUN=false
+JSON_ONLY=false
+for arg in "$@"; do
+    case "$arg" in
+        --dry-run)  DRY_RUN=true ;;
+        --json)     JSON_ONLY=true ;;
+    esac
+done
+
+# --- State tracking ---
+WORST_STATUS=0   # 0=healthy, 1=degraded, 2=down
+SUMMARY=""
+ALERT_LINES=""
+SERVICE_COUNT=0
+HEALTHY_COUNT=0
+DEGRADED_COUNT=0
+DOWN_COUNT=0
+
+timestamp() {
+    date -u "+%Y-%m-%dT%H:%M:%SZ"
+}
+
+now_epoch() {
+    date +%s
+}
+
+# Get file modification time as epoch seconds (macOS compatible)
+file_mtime_epoch() {
+    stat -f "%m" "$1" 2>/dev/null || echo "0"
+}
+
+# Get file size in bytes
+file_size() {
+    stat -f "%z" "$1" 2>/dev/null || echo "0"
+}
+
+# Get the freshness threshold for a given service
+freshness_for_service() {
+    case "$1" in
+        *daemon*)              echo "$DAEMON_FRESHNESS" ;;
+        *slack-events*)        echo "$SLACK_EVENTS_FRESHNESS" ;;
+        *slack-socket*)        echo "$SLACK_SOCKET_FRESHNESS" ;;
+        *slack-cloud-relay*)   echo "$CLOUD_RELAY_FRESHNESS" ;;
+        *voice-webhook*)       echo "$VOICE_WEBHOOK_FRESHNESS" ;;
+        *)                     echo "$DEFAULT_FRESHNESS" ;;
+    esac
+}
+
+# Find the most recent log file matching a pattern in a directory
+latest_log_in() {
+    local dir="$1"
+    local pattern="$2"
+    if [ -d "$dir" ]; then
+        # Use ls -t to find most recently modified file matching pattern
+        # shellcheck disable=SC2012
+        ls -t "$dir"/$pattern 2>/dev/null | head -1
+    fi
+}
+
+# Determine which log/state file to use as the freshness signal for a service.
+# Special case: for the main daemon we use state/cadence-bus/health.json
+# (updated every 15s by the cadence consumer) rather than a stdout log,
+# because the shared launchd-stdout.log is written by multiple processes
+# and its mtime doesn't reliably reflect daemon liveness.
+log_source_for_service() {
+    case "$1" in
+        ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-daemon)
+            # Pseudo-pattern: literal file path. The check below detects this.
+            echo "$BASE_DIR/state/cadence-bus health.json"
+            ;;
+        ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-events)
+            echo "$LOGS_DIR/polling *-slack-events.jsonl"
+            ;;
+        ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-socket)
+            echo "$LOGS_DIR/polling *-slack-socket.jsonl"
+            ;;
+        ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-cloud-relay)
+            echo "$LOGS_DIR/polling *-slack-cloud-relay.jsonl"
+            ;;
+        ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-voice-webhook)
+            echo "$LOGS_DIR/voice voice-webhook-stdout.log"
+            ;;
+        *)
+            echo ""
+            ;;
+    esac
+}
+
+# --- Main check loop ---
+NOW=$(now_epoch)
+JSON_SERVICES=""
+
+for SERVICE in $SERVICES; do
+    SERVICE_COUNT=$((SERVICE_COUNT + 1))
+    STATUS="healthy"
+    PID="-"
+    EXIT_CODE="-"
+    LAST_ACTIVITY="unknown"
+    ISSUES=""
+
+    # Step 1: Check if service is in launchctl list
+    LAUNCHCTL_LINE=$(launchctl list 2>/dev/null | grep "$SERVICE" || true)
+
+    if [ -z "$LAUNCHCTL_LINE" ]; then
+        STATUS="down"
+        ISSUES="not registered in launchctl"
+    else
+        # Parse launchctl output: PID<tab>ExitStatus<tab>Label
+        PID=$(echo "$LAUNCHCTL_LINE" | awk '{print $1}')
+        EXIT_CODE=$(echo "$LAUNCHCTL_LINE" | awk '{print $2}')
+
+        # Step 2: Check PID is non-zero (service is actually running)
+        if [ "$PID" = "-" ] || [ "$PID" = "0" ] || [ -z "$PID" ]; then
+            # PID of "-" means not running (scheduled or crashed)
+            # For KeepAlive services (daemon, poller, slack-events, whatsapp-handler), this means down
+            # For interval services (backlog-executor), "-" between runs is normal
+            case "$SERVICE" in
+                *backlog-executor*|*poller*)
+                    # Interval service — not running between intervals is OK
+                    if [ "$EXIT_CODE" != "0" ] && [ "$EXIT_CODE" != "-" ]; then
+                        STATUS="degraded"
+                        ISSUES="last run exited with status $EXIT_CODE"
+                    fi
+                    ;;
+                *)
+                    STATUS="down"
+                    ISSUES="PID is $PID (not running)"
+                    ;;
+            esac
+        fi
+
+        # Step 3: Check exit status
+        if [ "$EXIT_CODE" != "0" ] && [ "$EXIT_CODE" != "-" ]; then
+            if [ "$STATUS" = "healthy" ]; then
+                STATUS="degraded"
+            fi
+            ISSUES="${ISSUES:+$ISSUES; }exit status $EXIT_CODE"
+        fi
+    fi
+
+    # Step 4: Check log/heartbeat freshness.
+    #   - For the daemon: cadence heartbeat is the only reliable signal,
+    #     and going stale is a real degradation.
+    #   - For webhook receivers (slack-events, slack-socket, cloud-relay,
+    #     voice-webhook): once they're registered with a live PID, log
+    #     staleness is normal (they only log on inbound events). Surface
+    #     the age as informational but DO NOT degrade their status on
+    #     freshness alone.
+    LOG_SOURCE=$(log_source_for_service "$SERVICE")
+    if [ -n "$LOG_SOURCE" ]; then
+        LOG_DIR=$(echo "$LOG_SOURCE" | cut -d' ' -f1)
+        LOG_PATTERN=$(echo "$LOG_SOURCE" | cut -d' ' -f2-)
+        LOG_FILE=$(latest_log_in "$LOG_DIR" "$LOG_PATTERN")
+
+        if [ -n "$LOG_FILE" ] && [ -f "$LOG_FILE" ]; then
+            LOG_MTIME=$(file_mtime_epoch "$LOG_FILE")
+            AGE=$((NOW - LOG_MTIME))
+            THRESHOLD=$(freshness_for_service "$SERVICE")
+
+            # Apply freshness as a degradation signal only for the daemon
+            # (cadence heartbeat) and as a fallback for unknown services.
+            FRESHNESS_MATTERS=false
+            case "$SERVICE" in
+                *daemon*) FRESHNESS_MATTERS=true ;;
+                ${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-events|${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-socket|${LAUNCHD_NS}.${AGENT_FIRSTNAME}-slack-cloud-relay|${LAUNCHD_NS}.${AGENT_FIRSTNAME}-voice-webhook)
+                    FRESHNESS_MATTERS=false  # webhook receivers — silent when idle is normal
+                    ;;
+                *) FRESHNESS_MATTERS=true ;;
+            esac
+
+            if [ "$FRESHNESS_MATTERS" = true ] && [ "$AGE" -gt "$THRESHOLD" ]; then
+                AGE_MIN=$((AGE / 60))
+                if [ "$STATUS" = "healthy" ]; then
+                    STATUS="degraded"
+                fi
+                ISSUES="${ISSUES:+$ISSUES; }log stale (${AGE_MIN}m old, threshold ${THRESHOLD}s)"
+            fi
+
+            # Format last activity as relative time (informational always)
+            if [ "$AGE" -lt 60 ]; then
+                LAST_ACTIVITY="${AGE}s ago"
+            elif [ "$AGE" -lt 3600 ]; then
+                LAST_ACTIVITY="$((AGE / 60))m ago"
+            else
+                LAST_ACTIVITY="$((AGE / 3600))h ago"
+            fi
+        else
+            LAST_ACTIVITY="no log yet"
+            # Missing log isn't degradation for webhook receivers either.
+            case "$SERVICE" in
+                *daemon*)
+                    if [ "$STATUS" = "healthy" ]; then STATUS="degraded"; fi
+                    ISSUES="${ISSUES:+$ISSUES; }no cadence heartbeat"
+                    ;;
+            esac
+        fi
+    fi
+
+    # Step 5: Check daemon stderr log growth
+    if [ "$SERVICE" = "${LAUNCHD_NS}.${AGENT_FIRSTNAME}-daemon" ]; then
+        STDERR_LOG="$LOGS_DIR/daemon/launchd-stderr.log"
+        if [ -f "$STDERR_LOG" ]; then
+            STDERR_SIZE=$(file_size "$STDERR_LOG")
+            if [ "$STDERR_SIZE" -gt "$STDERR_THRESHOLD" ]; then
+                STDERR_KB=$((STDERR_SIZE / 1024))
+                if [ "$STATUS" = "healthy" ]; then
+                    STATUS="degraded"
+                fi
+                ISSUES="${ISSUES:+$ISSUES; }stderr log ${STDERR_KB}KB (threshold $((STDERR_THRESHOLD / 1024))KB)"
+            fi
+        fi
+    fi
+
+    # Track worst status
+    case "$STATUS" in
+        down)
+            if [ "$WORST_STATUS" -lt 2 ]; then WORST_STATUS=2; fi
+            DOWN_COUNT=$((DOWN_COUNT + 1))
+            ;;
+        degraded)
+            if [ "$WORST_STATUS" -lt 1 ]; then WORST_STATUS=1; fi
+            DEGRADED_COUNT=$((DEGRADED_COUNT + 1))
+            ;;
+        healthy)
+            HEALTHY_COUNT=$((HEALTHY_COUNT + 1))
+            ;;
+    esac
+
+    # Build summary line
+    STATUS_ICON="OK"
+    case "$STATUS" in
+        degraded) STATUS_ICON="WARN" ;;
+        down)     STATUS_ICON="DOWN" ;;
+    esac
+
+    SUMMARY_LINE="[$STATUS_ICON] $SERVICE  pid=$PID  exit=$EXIT_CODE  last_activity=$LAST_ACTIVITY"
+    if [ -n "$ISSUES" ]; then
+        SUMMARY_LINE="$SUMMARY_LINE  ($ISSUES)"
+    fi
+    SUMMARY="${SUMMARY}${SUMMARY:+
+}$SUMMARY_LINE"
+
+    # Track alert-worthy lines
+    if [ "$STATUS" != "healthy" ]; then
+        ALERT_LINES="${ALERT_LINES}${ALERT_LINES:+
+}$SUMMARY_LINE"
+    fi
+
+    # Build JSON entry
+    JSON_ENTRY="{\"service\":\"$SERVICE\",\"status\":\"$STATUS\",\"pid\":\"$PID\",\"exit_code\":\"$EXIT_CODE\",\"last_activity\":\"$LAST_ACTIVITY\""
+    if [ -n "$ISSUES" ]; then
+        # Escape issues for JSON
+        ESCAPED_ISSUES=$(printf '%s' "$ISSUES" | sed 's/"/\\"/g')
+        JSON_ENTRY="$JSON_ENTRY,\"issues\":\"$ESCAPED_ISSUES\""
+    fi
+    JSON_ENTRY="$JSON_ENTRY}"
+    JSON_SERVICES="${JSON_SERVICES}${JSON_SERVICES:+,}$JSON_ENTRY"
+done
+
+# --- Output ---
+OVERALL="healthy"
+case "$WORST_STATUS" in
+    1) OVERALL="degraded" ;;
+    2) OVERALL="down" ;;
+esac
+
+if [ "$JSON_ONLY" = true ]; then
+    echo "{\"timestamp\":\"$(timestamp)\",\"overall\":\"$OVERALL\",\"healthy\":$HEALTHY_COUNT,\"degraded\":$DEGRADED_COUNT,\"down\":$DOWN_COUNT,\"services\":[$JSON_SERVICES]}"
+    exit "$WORST_STATUS"
+fi
+
+# Human-readable output
+echo "=== Daemon Health Check — $(timestamp) ==="
+echo ""
+echo "$SUMMARY"
+echo ""
+echo "--- Summary: $HEALTHY_COUNT healthy, $DEGRADED_COUNT degraded, $DOWN_COUNT down (of $SERVICE_COUNT services) ---"
+echo "Overall: $OVERALL"
+
+# --- Slack alerting ---
+if [ "$WORST_STATUS" -gt 0 ] && [ "$DRY_RUN" = false ]; then
+    if [ -x "$SLACK_SEND" ]; then
+        ALERT_MSG="*Daemon Health Alert* — $DEGRADED_COUNT degraded, $DOWN_COUNT down
+
+\`\`\`
+$ALERT_LINES
+\`\`\`
+
+_Run \`scripts/maintenance/health-check.sh\` for full status._"
+
+        "$SLACK_SEND" "$PRINCIPAL_DM" "$ALERT_MSG" --no-typing 2>/dev/null || echo "WARNING: Failed to send Slack alert"
+    else
+        echo "WARNING: slack-send.sh not found or not executable at $SLACK_SEND"
+    fi
+elif [ "$WORST_STATUS" -gt 0 ] && [ "$DRY_RUN" = true ]; then
+    echo ""
+    echo "[DRY-RUN] Would send Slack alert to $PRINCIPAL_DM:"
+    echo "  $DEGRADED_COUNT degraded, $DOWN_COUNT down"
+fi
+
+# --- Log result ---
+LOG_FILE="$LOGS_DIR/maintenance/health-check.jsonl"
+mkdir -p "$(dirname "$LOG_FILE")"
+echo "{\"timestamp\":\"$(timestamp)\",\"overall\":\"$OVERALL\",\"healthy\":$HEALTHY_COUNT,\"degraded\":$DEGRADED_COUNT,\"down\":$DOWN_COUNT}" >> "$LOG_FILE"
+
+exit "$WORST_STATUS"