@adaptic/maestro 1.1.3 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/maestro",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Maestro — Autonomous AI agent operating system. Deploy AI employees on dedicated Mac minis.",
   "type": "module",
   "bin": {

package/scripts/setup/configure-macos.sh

@@ -296,14 +296,63 @@ configure_app_launches() {
   # The poller uses IMAP directly, not the browser
   log "Safari: not needed as Login Item (Gmail uses IMAP polling)"
 
-  # Ensure required directories exist
-  mkdir -p "$AGENT_DIR/logs/huddle"
-  mkdir -p "$AGENT_DIR/state/huddle"
-  ok "Log and state directories verified"
+  # Ensure required directories exist (as the real user, not root)
+  local real_user="${SUDO_USER:-$CURRENT_USER}"
+  local dirs=("$AGENT_DIR/logs/huddle" "$AGENT_DIR/state/huddle" "$AGENT_DIR/logs/watchdog")
+  for d in "${dirs[@]}"; do
+    mkdir -p "$d"
+    chown "$real_user:staff" "$d" 2>/dev/null || true
+  done
+  ok "Log and state directories verified (owned by $real_user)"
 }
 
 # =============================================================================
-# 7. ORCHESTRATOR AND SUBSYSTEMS ON BOOT
+# 7. MEMORY WATCHDOG
+# =============================================================================
+
+configure_memory_watchdog() {
+  section "Memory Watchdog (OOM Protection)"
+
+  local WATCHDOG_SCRIPT="$AGENT_DIR/scripts/watchdog/memory-watchdog.sh"
+  local PLIST_SOURCE="$AGENT_DIR/scripts/watchdog/ai.maestro.memory-watchdog.plist"
+
+  if [ ! -f "$WATCHDOG_SCRIPT" ]; then
+    fail "Watchdog script not found at $WATCHDOG_SCRIPT"
+    return 0
+  fi
+
+  chmod +x "$WATCHDOG_SCRIPT"
+  ok "Watchdog script executable"
+
+  # Determine the real user's home for LaunchAgents
+  local real_user="${SUDO_USER:-$CURRENT_USER}"
+  local real_home
+  real_home=$(eval echo "~$real_user")
+  local PLIST_DEST="$real_home/Library/LaunchAgents/ai.maestro.memory-watchdog.plist"
+
+  # Install the plist (update paths for this agent directory)
+  sed "s|/Users/sophie/maestro|$AGENT_DIR|g" "$PLIST_SOURCE" > "$PLIST_DEST"
+  chown "$real_user:staff" "$PLIST_DEST" 2>/dev/null || true
+
+  # Load it (as the real user)
+  if [ "$(id -u)" -eq 0 ]; then
+    su "$real_user" -c "launchctl unload '$PLIST_DEST' 2>/dev/null; launchctl load '$PLIST_DEST'" 2>/dev/null || true
+  else
+    launchctl unload "$PLIST_DEST" 2>/dev/null || true
+    launchctl load "$PLIST_DEST" 2>/dev/null || true
+  fi
+
+  ok "Memory watchdog launchd agent installed (runs every 30s)"
+  log "Thresholds: warn=60% critical=75% emergency=85% max_procs=8"
+  log "Override via env: WATCHDOG_WARN_PERCENT, WATCHDOG_CRITICAL_PERCENT, etc."
+
+  # Create log directory with correct ownership
+  mkdir -p "$AGENT_DIR/logs/watchdog"
+  chown "$real_user:staff" "$AGENT_DIR/logs/watchdog" 2>/dev/null || true
+}
+
+# =============================================================================
+# 8. ORCHESTRATOR AND SUBSYSTEMS ON BOOT
 # =============================================================================
 
 configure_boot_services() {
@@ -331,7 +380,7 @@ configure_boot_services() {
 
     # Check which are loaded
     local loaded_count
-    loaded_count=$(launchctl list 2>/dev/null | grep -c "ai.adaptic" || echo "0")
+    loaded_count=$(launchctl list 2>/dev/null | grep -c "ai.adaptic" || true)
     if [ "$loaded_count" -gt 0 ]; then
       ok "$loaded_count agents currently loaded"
     else
@@ -364,7 +413,7 @@ configure_boot_services() {
 }
 
 # =============================================================================
-# 8. SYSTEM VERIFICATION
+# 9. SYSTEM VERIFICATION
 # =============================================================================
 
 verify_all() {
@@ -440,6 +489,30 @@ verify_all() {
     issues=$((issues + 1))
   fi
 
+  # Check memory watchdog
+  if launchctl list 2>/dev/null | grep -q "ai.maestro.memory-watchdog"; then
+    ok "Memory watchdog: running"
+  elif [ -f "$HOME/Library/LaunchAgents/ai.maestro.memory-watchdog.plist" ]; then
+    warn "Memory watchdog: installed but not loaded"
+  else
+    fail "Memory watchdog: not installed"
+    issues=$((issues + 1))
+  fi
+
+  # Check heartbeat freshness
+  local heartbeat_file="$AGENT_DIR/state/heartbeat"
+  if [ -f "$heartbeat_file" ]; then
+    local hb_age
+    hb_age=$(( $(date +%s) - $(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$(cat "$heartbeat_file")" +%s 2>/dev/null || echo 0) ))
+    if [ "$hb_age" -lt 120 ]; then
+      ok "Heartbeat: fresh (${hb_age}s ago)"
+    else
+      warn "Heartbeat: stale (${hb_age}s ago — watchdog may not be running)"
+    fi
+  else
+    warn "Heartbeat: no heartbeat file found"
+  fi
+
   # Summary
   echo ""
   if [ "$issues" -eq 0 ]; then
@@ -473,6 +546,7 @@ main() {
       configure_slack_cdp
       configure_audio
       configure_app_launches
+      configure_memory_watchdog
       configure_boot_services
       ;;
     --full|full|"")
@@ -482,6 +556,7 @@ main() {
       configure_slack_cdp
       configure_audio
       configure_app_launches
+      configure_memory_watchdog
       configure_boot_services
 
       section "Configuration Complete"

package/scripts/spawn-session.sh

@@ -28,6 +28,26 @@ if [ ! -f "$TASK_FILE" ]; then
     exit 1
 fi
 
+# --- Resource gate: refuse to spawn if machine is under pressure -------------
+MAX_CLAUDE_PROCS="${WATCHDOG_MAX_CLAUDE_PROCS:-8}"
+TOTAL_RAM_KB=$(sysctl -n hw.memsize | awk '{printf "%.0f", $1 / 1024}')
+SPAWN_BLOCK_PERCENT="${WATCHDOG_CRITICAL_PERCENT:-75}"
+
+claude_count=$(/bin/ps -eo comm | grep -ci "claude" | tr -d ' ' || true)
+claude_rss_kb=$(/bin/ps -eo rss,comm | grep -i "claude" | grep -v "Claude.app" | grep -v "Claude Helper" | awk '{sum+=$1} END {print sum+0}')
+claude_pct=$(( (claude_rss_kb * 100) / TOTAL_RAM_KB ))
+
+if [ "$claude_count" -ge "$MAX_CLAUDE_PROCS" ]; then
+    echo "[$TIMESTAMP] BLOCKED: Too many claude processes ($claude_count >= $MAX_CLAUDE_PROCS)" >&2
+    exit 1
+fi
+
+if [ "$claude_pct" -ge "$SPAWN_BLOCK_PERCENT" ]; then
+    echo "[$TIMESTAMP] BLOCKED: Claude memory usage ${claude_pct}% >= ${SPAWN_BLOCK_PERCENT}% threshold" >&2
+    exit 1
+fi
+# -----------------------------------------------------------------------------
+
 # Create session directory
 mkdir -p "$SESSION_DIR" "$(dirname "$LOG_FILE")"
 

package/scripts/watchdog/ai.maestro.memory-watchdog.plist

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!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.memory-watchdog</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/Users/sophie/maestro/scripts/watchdog/memory-watchdog.sh</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>30</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/Users/sophie/maestro/logs/watchdog/launchd-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>/Users/sophie/maestro/logs/watchdog/launchd-stderr.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+
+    <key>Nice</key>
+    <integer>10</integer>
+
+    <key>ProcessType</key>
+    <string>Background</string>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+</dict>
+</plist>

package/scripts/watchdog/force-reboot.sh

@@ -0,0 +1,148 @@
+#!/bin/bash
+# =============================================================================
+# force-reboot.sh — Remote/Automated Force Reboot for Frozen Mac Mini
+# =============================================================================
+#
+# This script provides multiple escalation levels for rebooting a frozen
+# or unresponsive Mac mini running the Maestro agent system.
+#
+# Usage:
+#   ./scripts/watchdog/force-reboot.sh --graceful   # Try graceful shutdown first
+#   ./scripts/watchdog/force-reboot.sh --force       # Immediate reboot (requires sudo)
+#   ./scripts/watchdog/force-reboot.sh --status      # Check heartbeat and uptime
+#
+# Remote usage (from another machine via SSH):
+#   ssh sophie@mac-mini.local "~/maestro/scripts/watchdog/force-reboot.sh --graceful"
+#
+# =============================================================================
+#
+# FORCE-REBOOT OPTIONS WHEN THE MACHINE IS COMPLETELY FROZEN:
+#
+# If SSH is unresponsive and the GUI is frozen, the only options are:
+#
+# 1. SMART PLUG (recommended for headless servers):
+#    - Install a WiFi smart plug (TP-Link Kasa, Shelly, etc.) on the Mac mini power
+#    - Power cycle via the smart plug's app or API
+#    - Combined with `pmset autorestart 1` (already configured), the Mac mini
+#      will boot automatically when power is restored
+#    - Example (TP-Link Kasa):
+#        kasa --host <plug-ip> --type plug off && sleep 5 && kasa --host <plug-ip> --type plug on
+#    - Example (Shelly):
+#        curl -s "http://<shelly-ip>/relay/0?turn=off" && sleep 5 && curl -s "http://<shelly-ip>/relay/0?turn=on"
+#
+# 2. PARSEC (if display is frozen but network is up):
+#    - Parsec may still be responsive even if the GUI is frozen
+#    - Connect via Parsec and use Cmd+Ctrl+Power to force restart
+#
+# 3. APPLE REMOTE MANAGEMENT (ARD):
+#    - If enabled, use "Send UNIX Command" from another Mac:
+#        sudo shutdown -r now
+#
+# 4. PHYSICAL POWER CYCLE:
+#    - Unplug and replug the Mac mini power cable
+#    - With `pmset autorestart 1`, it will boot automatically
+#
+# 5. SSH + SYSDIAGNOSE RESET (partial freeze, SSH still works):
+#    - ssh sophie@mac-mini.local "sudo reboot"
+#    - Or: ssh sophie@mac-mini.local "sudo shutdown -r now"
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAESTRO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+HEARTBEAT_FILE="$MAESTRO_DIR/state/heartbeat"
+LOG_FILE="$MAESTRO_DIR/logs/watchdog/$(date +%Y-%m-%d)-reboot.log"
+
+log() {
+  local ts
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  echo "[$ts] $1" | tee -a "$LOG_FILE"
+}
+
+check_heartbeat() {
+  if [ ! -f "$HEARTBEAT_FILE" ]; then
+    echo "No heartbeat file found — watchdog may not be running"
+    return 1
+  fi
+
+  local hb_time hb_age
+  hb_time=$(cat "$HEARTBEAT_FILE")
+  hb_age=$(( $(date +%s) - $(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$hb_time" +%s 2>/dev/null || echo 0) ))
+
+  echo "Last heartbeat: $hb_time (${hb_age}s ago)"
+  echo "System uptime:  $(uptime)"
+
+  if [ "$hb_age" -gt 120 ]; then
+    echo "WARNING: Heartbeat is stale (>2 min) — watchdog may be stuck"
+    return 1
+  fi
+  return 0
+}
+
+graceful_reboot() {
+  log "Initiating graceful reboot..."
+
+  # 1. Trigger emergency stop to prevent new work
+  echo "Memory watchdog initiated graceful reboot" > "$MAESTRO_DIR/.emergency-stop"
+  log "Emergency stop flag set"
+
+  # 2. Give running sessions 30 seconds to wrap up
+  log "Waiting 30s for running sessions to complete..."
+  sleep 30
+
+  # 3. Kill remaining claude processes gracefully
+  log "Sending SIGTERM to remaining claude processes..."
+  pkill -TERM -f "claude" 2>/dev/null || true
+  sleep 5
+
+  # 4. Commit any uncommitted state
+  log "Attempting to commit state..."
+  (
+    cd "$MAESTRO_DIR"
+    git add -A state/ logs/ 2>/dev/null || true
+    git commit -m "chore: pre-reboot state save (watchdog-initiated)" 2>/dev/null || true
+    git push origin main 2>/dev/null || true
+  ) || true
+
+  # 5. Reboot
+  log "Rebooting now..."
+  sudo shutdown -r now 2>/dev/null || {
+    log "sudo shutdown failed — trying osascript..."
+    osascript -e 'tell application "System Events" to restart' 2>/dev/null || {
+      log "All reboot methods failed — manual intervention required"
+      exit 1
+    }
+  }
+}
+
+force_reboot() {
+  log "FORCE REBOOT initiated"
+  echo "Force reboot requested" > "$MAESTRO_DIR/.emergency-stop" 2>/dev/null || true
+  sudo reboot 2>/dev/null || sudo shutdown -r now 2>/dev/null || {
+    log "sudo reboot failed — requires password or system is frozen"
+    echo "ERROR: Cannot force reboot without sudo. Options:"
+    echo "  1. Run: sudo reboot"
+    echo "  2. Power cycle via smart plug"
+    echo "  3. Physical power cycle"
+    exit 1
+  }
+}
+
+case "${1:---status}" in
+  --status)
+    check_heartbeat
+    ;;
+  --graceful)
+    graceful_reboot
+    ;;
+  --force)
+    force_reboot
+    ;;
+  *)
+    echo "Usage: $0 [--status|--graceful|--force]"
+    exit 1
+    ;;
+esac

package/scripts/watchdog/memory-watchdog.sh

@@ -0,0 +1,325 @@
+#!/bin/bash
+# =============================================================================
+# memory-watchdog.sh — System Resource Watchdog for Maestro Agent Deployment
+# =============================================================================
+#
+# Monitors memory usage and process count for Claude Code subprocesses.
+# Kills runaway subagents when thresholds are exceeded.
+# Triggers emergency stop at critical levels.
+#
+# Runs every 30 seconds via launchd (ai.maestro.memory-watchdog.plist).
+#
+# Thresholds (configurable via environment or defaults below):
+#   WARNING:   >60% RAM used by claude processes → log warning
+#   CRITICAL:  >75% RAM used by claude processes → kill oldest subagents
+#   EMERGENCY: >85% total system memory pressure  → emergency stop
+#
+# Usage:
+#   ./scripts/watchdog/memory-watchdog.sh           # Normal run
+#   ./scripts/watchdog/memory-watchdog.sh --check   # Report status only
+#   ./scripts/watchdog/memory-watchdog.sh --dry-run # Show what would be killed
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAESTRO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Auto-detect agent directory (sophie-ai, wundr, etc.)
+# The watchdog runs from maestro but protects the whole machine
+AGENT_DIR="${AGENT_DIR:-}"
+
+# --- Configuration -----------------------------------------------------------
+
+# Total physical RAM in KB
+TOTAL_RAM_KB=$(sysctl -n hw.memsize | awk '{printf "%.0f", $1 / 1024}')
+
+# Thresholds as percentage of total RAM for claude process RSS
+CLAUDE_WARN_PERCENT="${WATCHDOG_WARN_PERCENT:-60}"
+CLAUDE_CRITICAL_PERCENT="${WATCHDOG_CRITICAL_PERCENT:-75}"
+
+# System-wide memory pressure threshold (percentage)
+SYSTEM_EMERGENCY_PERCENT="${WATCHDOG_EMERGENCY_PERCENT:-85}"
+
+# Max concurrent claude CLI processes (excluding the main interactive session)
+MAX_CLAUDE_PROCS="${WATCHDOG_MAX_CLAUDE_PROCS:-8}"
+
+# Minimum age (seconds) before a claude process can be killed
+# Protects freshly-spawned sessions from being killed immediately
+MIN_AGE_SECONDS="${WATCHDOG_MIN_AGE:-60}"
+
+# Log file
+LOG_DIR="$MAESTRO_DIR/logs/watchdog"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d)-watchdog.jsonl"
+
+# State file for tracking actions across runs
+STATE_FILE="$MAESTRO_DIR/state/watchdog-state.yaml"
+
+# --- Helpers -----------------------------------------------------------------
+
+mkdir -p "$LOG_DIR" "$(dirname "$STATE_FILE")"
+
+log_event() {
+  local level="$1" event="$2" detail="${3:-}"
+  local ts
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  printf '{"ts":"%s","level":"%s","event":"%s","detail":%s}\n' \
+    "$ts" "$level" "$event" "$(echo "$detail" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read().strip()))' 2>/dev/null || echo '""')" \
+    >> "$LOG_FILE"
+}
+
+# --- Memory Metrics ----------------------------------------------------------
+
+get_system_memory_pressure() {
+  # macOS memory_pressure returns a percentage of total memory under pressure
+  # We parse the "System-wide memory free percentage" line
+  local free_pct
+  free_pct=$(memory_pressure 2>/dev/null | grep "System-wide memory free percentage:" | awk '{print $NF}' | tr -d '%')
+  if [ -z "$free_pct" ]; then
+    # Fallback: calculate from vm_stat
+    local page_size free_pages
+    page_size=$(vm_stat | head -1 | grep -o '[0-9]*')
+    free_pages=$(vm_stat | awk '/Pages free/ {print $NF}' | tr -d '.')
+    local free_kb=$(( (free_pages * page_size) / 1024 ))
+    free_pct=$(( (free_kb * 100) / TOTAL_RAM_KB ))
+  fi
+  echo $(( 100 - free_pct ))
+}
+
+get_claude_processes() {
+  # Returns: PID RSS_KB ELAPSED_SECONDS COMMAND
+  # Finds all claude CLI processes (both 'claude' and node-based claude)
+  # Excludes this watchdog script itself
+  /bin/ps -eo pid,rss,etime,comm | \
+    grep -i "claude" | \
+    grep -v "Claude.app" | \
+    grep -v "Claude Helper" | \
+    grep -v "grep" | \
+    grep -v "watchdog" | \
+    awk '{
+      pid = $1
+      rss = $2
+      etime = $3
+      comm = $4
+      # Parse etime (formats: SS, MM:SS, HH:MM:SS, D-HH:MM:SS)
+      n = split(etime, parts, ":")
+      if (n == 1) { secs = parts[1] }
+      else if (n == 2) { secs = parts[1]*60 + parts[2] }
+      else if (n == 3) {
+        # Check for D- prefix
+        if (index(parts[1], "-") > 0) {
+          split(parts[1], dp, "-")
+          secs = dp[1]*86400 + dp[2]*3600 + parts[2]*60 + parts[3]
+        } else {
+          secs = parts[1]*3600 + parts[2]*60 + parts[3]
+        }
+      }
+      printf "%s %s %s %s\n", pid, rss, secs, comm
+    }' | sort -k2 -rn
+}
+
+get_total_claude_rss_kb() {
+  get_claude_processes | awk '{sum += $2} END {print sum+0}'
+}
+
+count_claude_processes() {
+  get_claude_processes | wc -l | tr -d ' '
+}
+
+# --- Identification ----------------------------------------------------------
+
+identify_main_session() {
+  # The main interactive claude session is typically:
+  # 1. The one connected to a TTY
+  # 2. The longest-running one
+  # 3. The parent of subagent processes
+  # We use the longest-running as a heuristic
+  get_claude_processes | tail -1 | awk '{print $1}'
+}
+
+# --- Actions -----------------------------------------------------------------
+
+kill_oldest_subagents() {
+  local target_count="$1"
+  local dry_run="${2:-false}"
+  local main_pid
+  main_pid=$(identify_main_session)
+  local killed=0
+
+  # Get processes sorted by RSS descending (kill biggest first)
+  # Skip the main session
+  while IFS=' ' read -r pid rss age comm; do
+    if [ "$pid" = "$main_pid" ]; then
+      continue
+    fi
+    if [ "$age" -lt "$MIN_AGE_SECONDS" ]; then
+      log_event "info" "skip_young" "PID $pid age ${age}s < ${MIN_AGE_SECONDS}s minimum"
+      continue
+    fi
+    if [ "$killed" -ge "$target_count" ]; then
+      break
+    fi
+
+    local rss_mb=$(( rss / 1024 ))
+    if [ "$dry_run" = "true" ]; then
+      echo "  [DRY RUN] Would kill PID $pid (${rss_mb}MB, age ${age}s)"
+      log_event "info" "dry_run_kill" "PID=$pid RSS=${rss_mb}MB age=${age}s"
+    else
+      echo "  Killing PID $pid (${rss_mb}MB, age ${age}s)"
+      kill -TERM "$pid" 2>/dev/null || true
+      log_event "warn" "killed_subagent" "PID=$pid RSS=${rss_mb}MB age=${age}s signal=TERM"
+      killed=$((killed + 1))
+
+      # Give it 5 seconds to exit gracefully, then SIGKILL
+      (
+        sleep 5
+        if kill -0 "$pid" 2>/dev/null; then
+          kill -9 "$pid" 2>/dev/null || true
+          # Log to file directly since this is a subshell
+          printf '{"ts":"%s","level":"warn","event":"force_killed","detail":"PID=%s did not exit after SIGTERM"}\n' \
+            "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$pid" >> "$LOG_FILE"
+        fi
+      ) &
+    fi
+  done <<< "$(get_claude_processes)"
+
+  echo "$killed"
+}
+
+trigger_emergency_stop() {
+  local reason="$1"
+  local stop_file="$MAESTRO_DIR/.emergency-stop"
+
+  if [ -f "$stop_file" ]; then
+    log_event "warn" "emergency_already_active" "$reason"
+    return 0
+  fi
+
+  echo "$reason" > "$stop_file"
+  log_event "critical" "emergency_stop_triggered" "$reason"
+
+  # Also create in any detected agent directories
+  for agent_dir in "$HOME"/sophie-ai "$HOME"/wundr; do
+    if [ -d "$agent_dir" ]; then
+      echo "$reason" > "$agent_dir/.emergency-stop" 2>/dev/null || true
+    fi
+  done
+
+  # Kill ALL non-main claude subprocesses
+  local main_pid
+  main_pid=$(identify_main_session)
+  while IFS=' ' read -r pid rss age comm; do
+    if [ "$pid" != "$main_pid" ] && [ -n "$pid" ]; then
+      kill -TERM "$pid" 2>/dev/null || true
+    fi
+  done <<< "$(get_claude_processes)"
+
+  echo "EMERGENCY STOP: $reason"
+}
+
+# --- Main Logic --------------------------------------------------------------
+
+run_watchdog() {
+  local mode="${1:-run}"
+  local dry_run="false"
+  [ "$mode" = "--dry-run" ] && dry_run="true"
+  [ "$mode" = "--check" ] && dry_run="true"
+
+  # Collect metrics
+  local claude_rss_kb claude_count system_pressure
+  claude_rss_kb=$(get_total_claude_rss_kb)
+  claude_count=$(count_claude_processes)
+  system_pressure=$(get_system_memory_pressure)
+
+  local claude_rss_mb=$(( claude_rss_kb / 1024 ))
+  local claude_pct=$(( (claude_rss_kb * 100) / TOTAL_RAM_KB ))
+  local warn_threshold_mb=$(( (TOTAL_RAM_KB * CLAUDE_WARN_PERCENT) / 100 / 1024 ))
+  local critical_threshold_mb=$(( (TOTAL_RAM_KB * CLAUDE_CRITICAL_PERCENT) / 100 / 1024 ))
+
+  # Report
+  if [ "$mode" = "--check" ]; then
+    echo "=== Memory Watchdog Status ==="
+    echo "Total RAM:            $(( TOTAL_RAM_KB / 1024 ))MB"
+    echo "Claude processes:     $claude_count (max: $MAX_CLAUDE_PROCS)"
+    echo "Claude RSS total:     ${claude_rss_mb}MB (${claude_pct}% of RAM)"
+    echo "  Warning threshold:  ${warn_threshold_mb}MB (${CLAUDE_WARN_PERCENT}%)"
+    echo "  Critical threshold: ${critical_threshold_mb}MB (${CLAUDE_CRITICAL_PERCENT}%)"
+    echo "System mem pressure:  ${system_pressure}% (emergency at ${SYSTEM_EMERGENCY_PERCENT}%)"
+    echo ""
+    echo "Claude processes:"
+    get_claude_processes | while IFS=' ' read -r pid rss age comm; do
+      echo "  PID $pid: $(( rss / 1024 ))MB, age ${age}s — $comm"
+    done
+    echo "=============================="
+    return 0
+  fi
+
+  # --- Level 1: System emergency (memory pressure) ---------------------------
+  if [ "$system_pressure" -ge "$SYSTEM_EMERGENCY_PERCENT" ]; then
+    log_event "critical" "system_memory_emergency" "pressure=${system_pressure}% >= ${SYSTEM_EMERGENCY_PERCENT}%"
+    if [ "$dry_run" = "false" ]; then
+      trigger_emergency_stop "Memory pressure ${system_pressure}% exceeded ${SYSTEM_EMERGENCY_PERCENT}% emergency threshold"
+    else
+      echo "[DRY RUN] Would trigger EMERGENCY STOP (pressure=${system_pressure}%)"
+    fi
+    return 0
+  fi
+
+  # --- Level 2: Claude RSS critical — kill biggest subagents -----------------
+  if [ "$claude_pct" -ge "$CLAUDE_CRITICAL_PERCENT" ]; then
+    log_event "warn" "claude_memory_critical" "RSS=${claude_rss_mb}MB (${claude_pct}%) >= ${CLAUDE_CRITICAL_PERCENT}%"
+    echo "CRITICAL: Claude processes using ${claude_rss_mb}MB (${claude_pct}% of RAM)"
+
+    # Kill enough to get below warning threshold
+    local target_rss_kb=$(( (TOTAL_RAM_KB * CLAUDE_WARN_PERCENT) / 100 ))
+    local excess_kb=$(( claude_rss_kb - target_rss_kb ))
+    # Estimate ~600MB per process
+    local procs_to_kill=$(( (excess_kb / 614400) + 1 ))
+    [ "$procs_to_kill" -lt 1 ] && procs_to_kill=1
+
+    echo "  Killing $procs_to_kill subagent(s) to free ~$(( excess_kb / 1024 ))MB..."
+    kill_oldest_subagents "$procs_to_kill" "$dry_run"
+    return 0
+  fi
+
+  # --- Level 3: Too many concurrent processes --------------------------------
+  if [ "$claude_count" -gt "$MAX_CLAUDE_PROCS" ]; then
+    local excess=$(( claude_count - MAX_CLAUDE_PROCS ))
+    log_event "warn" "too_many_claude_procs" "count=${claude_count} > max=${MAX_CLAUDE_PROCS}"
+    echo "WARNING: $claude_count claude processes running (max: $MAX_CLAUDE_PROCS)"
+    echo "  Killing $excess oldest subagent(s)..."
+    kill_oldest_subagents "$excess" "$dry_run"
+    return 0
+  fi
+
+  # --- Level 4: Claude RSS warning — log only --------------------------------
+  if [ "$claude_pct" -ge "$CLAUDE_WARN_PERCENT" ]; then
+    log_event "warn" "claude_memory_warning" "RSS=${claude_rss_mb}MB (${claude_pct}%) >= ${CLAUDE_WARN_PERCENT}%"
+    return 0
+  fi
+
+  # --- All clear -------------------------------------------------------------
+  # Only log periodically (every 5 minutes = every 10th run at 30s interval)
+  local run_count_file="$MAESTRO_DIR/state/watchdog-run-count"
+  local run_count=0
+  [ -f "$run_count_file" ] && run_count=$(cat "$run_count_file")
+  run_count=$(( (run_count + 1) % 10 ))
+  echo "$run_count" > "$run_count_file"
+
+  if [ "$run_count" -eq 0 ]; then
+    log_event "info" "healthy" "claude_procs=${claude_count} rss=${claude_rss_mb}MB (${claude_pct}%) pressure=${system_pressure}%"
+  fi
+}
+
+# --- Write heartbeat ---------------------------------------------------------
+
+write_heartbeat() {
+  local heartbeat_file="$MAESTRO_DIR/state/heartbeat"
+  date -u +"%Y-%m-%dT%H:%M:%SZ" > "$heartbeat_file"
+}
+
+# --- Entry point -------------------------------------------------------------
+
+write_heartbeat
+run_watchdog "${1:-run}"