@cohortapp/agent-sdk 2.3.0

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>__AGENT_DIR__/scripts/watchdog/memory-watchdog.sh</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>30</integer>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>__AGENT_DIR__/logs/watchdog/launchd-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>__AGENT_DIR__/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,157 @@
+#!/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 <user>@<mac-mini> "~/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 <user>@<mac-mini> "sudo reboot"
+#    - Or: ssh <user>@<mac-mini> "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 (WS4 self-heal escalation)..."
+
+  # IMPORTANT (WS4 invariant): a graceful reboot is a RECOVERY action, not a
+  # halt. We deliberately do NOT write .emergency-stop — that flag is HUMAN-ONLY
+  # now. After the reboot, `pmset autorestart 1` powers the box back on and the
+  # RunAtLoad daemon plist restarts the agent automatically. Writing
+  # .emergency-stop here would brick the agent until a human cleared it —
+  # exactly the failure mode this rewrite removes.
+
+  # 1. Drain: give running sessions a moment to wrap up.
+  log "Waiting 30s for running sessions to wind down..."
+  sleep 30
+
+  # 2. SIGTERM remaining claude subprocesses so they exit cleanly (their close
+  #    handlers release locks + leave resume markers the daemon reconciles on
+  #    the next boot — no work dropped).
+  log "Sending SIGTERM to remaining claude processes..."
+  pkill -TERM -f "claude" 2>/dev/null || true
+  sleep 5
+
+  # 3. Best-effort durable state snapshot (queues live on disk regardless).
+  log "Attempting to snapshot state..."
+  (
+    cd "$MAESTRO_DIR"
+    git add -A state/ logs/ 2>/dev/null || true
+    git commit -m "chore: pre-reboot state save (watchdog-initiated, WS4)" 2>/dev/null || true
+    git push origin main 2>/dev/null || true
+  ) || true
+
+  # 4. Reboot. pmset autorestart brings the box back; the daemon restarts and
+  #    reconciles in-flight work from state/sessions/resume-pending/.
+  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"
+  # WS4: a reboot is recovery, not a halt — do NOT write .emergency-stop (that
+  # flag is human-only and would keep the agent down after the box comes back
+  # via pmset autorestart). An operator who wants the agent to STAY down should
+  # write .emergency-stop themselves, separately.
+  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,473 @@
+#!/bin/bash
+# =============================================================================
+# memory-watchdog.sh — System Resource Watchdog for Maestro Agent Deployment
+# =============================================================================
+#
+# Monitors memory pressure + Claude Code subprocess RSS and DEGRADES GRACEFULLY
+# instead of bricking the agent. The cardinal rule (WS4 invariant): every
+# automated terminal action ends in "the agent is running again." The ONLY
+# thing that permanently stops an agent is a HUMAN writing .emergency-stop —
+# this watchdog NEVER writes it.
+#
+# Runs every 30 seconds via launchd (ai.maestro.memory-watchdog.plist).
+#
+# Tiers (escalating, self-healing):
+#   SOFT     (sys 70–80% / claude ≥60%) → write state/throttle.json with an
+#            auto-expiring ceiling = liveCount-2 that the resource governor
+#            reads to admit fewer sessions. NO kills.
+#   HARD     (sys 80–90% / claude ≥75%) → SIGTERM the youngest/biggest
+#            subagents, sparing the oldest "main" session (MIN_AGE_SECONDS).
+#   CRITICAL (sys ≥90%, sustained 2 consecutive runs) → clean daemon RESTART
+#            via `launchctl kickstart -k` (the daemon re-reads state/queues +
+#            cooldowns + sweeps stale claims). NOT a halt. Only after 3 failed
+#            CRITICAL restarts within 15 min do we escalate to
+#            force-reboot.sh --graceful (pmset autorestart brings the box back).
+#
+# The legacy emergency-stop-on-OOM behaviour is GONE: it bricked agents on a
+# transient memory spike and required a human to clear the flag.
+#
+# 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 done
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MAESTRO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Auto-detect agent directory (any ~/<name>-ai or override via AGENT_DIR env).
+# The watchdog runs from maestro but protects the whole machine.
+AGENT_DIR="${AGENT_DIR:-}"
+
+# --- Ensure system paths are available ----------------------------------------
+# launchd PATH may not include /usr/sbin where sysctl lives
+export PATH="/usr/sbin:/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin:$PATH"
+
+# --- Configuration -----------------------------------------------------------
+
+# Total physical RAM in KB
+TOTAL_RAM_KB=$(sysctl -n hw.memsize | awk '{printf "%.0f", $1 / 1024}')
+
+# Claude-process RSS thresholds (percentage of total RAM).
+CLAUDE_SOFT_PERCENT="${WATCHDOG_SOFT_PERCENT:-60}"        # SOFT tier (throttle, no kills)
+CLAUDE_HARD_PERCENT="${WATCHDOG_HARD_PERCENT:-75}"        # HARD tier (kill youngest/biggest)
+
+# System-wide memory pressure thresholds (percentage used).
+SYSTEM_SOFT_PERCENT="${WATCHDOG_SYS_SOFT_PERCENT:-70}"    # SOFT tier
+SYSTEM_HARD_PERCENT="${WATCHDOG_SYS_HARD_PERCENT:-80}"    # HARD tier
+SYSTEM_CRITICAL_PERCENT="${WATCHDOG_CRITICAL_PERCENT:-90}" # CRITICAL tier (restart)
+
+# 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 (and, by sparing the oldest, the "main" session).
+MIN_AGE_SECONDS="${WATCHDOG_MIN_AGE:-60}"
+
+# Soft-throttle auto-expiry (seconds). The governor ignores an expired ceiling,
+# so even if the watchdog dies the throttle lifts on its own.
+THROTTLE_TTL_SECONDS="${WATCHDOG_THROTTLE_TTL:-300}"   # 5 min
+
+# CRITICAL must persist this many consecutive runs before we restart the daemon.
+CRITICAL_SUSTAIN_RUNS="${WATCHDOG_CRITICAL_SUSTAIN:-2}"
+
+# Failed-restart escalation: more than this many CRITICAL restarts within the
+# window → escalate to a graceful reboot.
+RESTART_FAIL_LIMIT="${WATCHDOG_RESTART_FAIL_LIMIT:-3}"
+RESTART_FAIL_WINDOW_SECONDS="${WATCHDOG_RESTART_FAIL_WINDOW:-900}"  # 15 min
+
+# Files
+LOG_DIR="$MAESTRO_DIR/logs/watchdog"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d)-watchdog.jsonl"
+STATE_FILE="$MAESTRO_DIR/state/watchdog-state.yaml"
+THROTTLE_FILE="$MAESTRO_DIR/state/throttle.json"
+# Counter/journal for CRITICAL sustain + restart-failure tracking.
+WD_COUNTER_FILE="$MAESTRO_DIR/state/watchdog-critical.json"
+
+# --- 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"
+}
+
+now_epoch() { date +%s; }
+
+# --- Memory Metrics ----------------------------------------------------------
+
+get_system_memory_pressure() {
+  # macOS memory_pressure returns a percentage of total memory free.
+  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
+    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, sorted by RSS descending.
+  /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
+      n = split(etime, parts, ":")
+      if (n == 1) { secs = parts[1] }
+      else if (n == 2) { secs = parts[1]*60 + parts[2] }
+      else if (n == 3) {
+        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 oldest claude process is treated as the "main" session and spared by
+  # HARD-tier kills. (longest-running heuristic)
+  get_claude_processes | tail -1 | awk '{print $1}'
+}
+
+# --- SOFT tier: write the auto-expiring throttle ceiling ----------------------
+
+write_throttle() {
+  local ceiling="$1" reason="$2"
+  [ "$ceiling" -lt 1 ] && ceiling=1
+  local set_at expires_at
+  set_at=$(now_epoch)
+  expires_at=$(( set_at + THROTTLE_TTL_SECONDS ))
+  # The governor reads set_at/expires_at in EPOCH MILLISECONDS (Date.now()).
+  local set_ms=$(( set_at * 1000 ))
+  local exp_ms=$(( expires_at * 1000 ))
+  mkdir -p "$(dirname "$THROTTLE_FILE")"
+  local tmp="$THROTTLE_FILE.tmp.$$"
+  printf '{"ceiling":%s,"reason":"%s","set_at":%s,"expires_at":%s}\n' \
+    "$ceiling" "$reason" "$set_ms" "$exp_ms" > "$tmp"
+  mv -f "$tmp" "$THROTTLE_FILE"
+  log_event "warn" "throttle_set" "ceiling=$ceiling reason=$reason ttl=${THROTTLE_TTL_SECONDS}s"
+}
+
+# --- HARD tier: kill youngest/biggest subagents, spare the oldest "main" ------
+
+kill_youngest_biggest_subagents() {
+  local target_count="$1"
+  local dry_run="${2:-false}"
+  local main_pid
+  main_pid=$(identify_main_session)
+  local killed=0
+
+  # get_claude_processes is sorted by RSS descending → biggest first. We skip
+  # the main session and anything younger than MIN_AGE_SECONDS.
+  while IFS=' ' read -r pid rss age comm; do
+    [ -z "$pid" ] && continue
+    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))
+      (
+        sleep 5
+        if kill -0 "$pid" 2>/dev/null; then
+          kill -9 "$pid" 2>/dev/null || true
+          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"
+}
+
+# --- CRITICAL tier: clean daemon restart, then graceful reboot if it keeps failing
+
+# Resolve the agent's daemon launchd label so we can kickstart it.
+resolve_daemon_label() {
+  local first=""
+  if [ -n "$AGENT_DIR" ] && [ -f "$AGENT_DIR/config/agent.json" ]; then
+    first=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_DIR/config/agent.json" 2>/dev/null || true)
+  fi
+  if [ -z "$first" ]; then
+    for agent_dir in "$HOME"/*-ai; do
+      [ -f "$agent_dir/config/agent.json" ] || continue
+      first=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$agent_dir/config/agent.json" 2>/dev/null || true)
+      [ -n "$first" ] && break
+    done
+  fi
+  [ -z "$first" ] && return 1
+  echo "ai.maestro.${first}-daemon"
+}
+
+# Read/append the restart-failure journal; echoes the count of restarts within
+# the rolling window AFTER recording this one.
+record_critical_restart() {
+  local ts; ts=$(now_epoch)
+  local cutoff=$(( ts - RESTART_FAIL_WINDOW_SECONDS ))
+  local existing=""
+  if [ -f "$WD_COUNTER_FILE" ]; then
+    existing=$(python3 - "$WD_COUNTER_FILE" "$cutoff" "$ts" <<'PY' 2>/dev/null || echo ""
+import sys, json
+path, cutoff, ts = sys.argv[1], int(sys.argv[2]), int(sys.argv[3])
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {}
+restarts = [t for t in d.get("restarts", []) if isinstance(t,(int,float)) and t >= cutoff]
+restarts.append(ts)
+d["restarts"] = restarts
+json.dump(d, open(path, "w"))
+print(len(restarts))
+PY
+)
+  fi
+  if [ -z "$existing" ]; then
+    # python3 missing/failed — fall back to a single-entry file (no windowing).
+    printf '{"restarts":[%s]}\n' "$ts" > "$WD_COUNTER_FILE"
+    echo 1
+  else
+    echo "$existing"
+  fi
+}
+
+critical_restart() {
+  local dry_run="${1:-false}"
+  local label
+  if ! label=$(resolve_daemon_label); then
+    log_event "error" "critical_no_daemon_label" "could not resolve daemon launchd label; skipping restart"
+    return 0
+  fi
+
+  local fails
+  fails=$(record_critical_restart)
+  if [ "$fails" -gt "$RESTART_FAIL_LIMIT" ]; then
+    log_event "critical" "critical_restart_escalation" "label=$label restarts=$fails within ${RESTART_FAIL_WINDOW_SECONDS}s > limit=$RESTART_FAIL_LIMIT — escalating to graceful reboot"
+    if [ "$dry_run" = "true" ]; then
+      echo "  [DRY RUN] Would run force-reboot.sh --graceful (restart loop)"
+      return 0
+    fi
+    "$SCRIPT_DIR/force-reboot.sh" --graceful || log_event "error" "graceful_reboot_failed" "force-reboot.sh --graceful returned non-zero"
+    return 0
+  fi
+
+  log_event "critical" "critical_daemon_restart" "label=$label kickstart -k (restart #$fails in window)"
+  if [ "$dry_run" = "true" ]; then
+    echo "  [DRY RUN] Would: launchctl kickstart -k gui/$(id -u)/$label"
+    return 0
+  fi
+  # Clean restart: re-reads state/queues + cooldowns + sweeps stale claims on
+  # boot. This is self-healing, NOT a halt.
+  local uid; uid=$(id -u)
+  if ! launchctl kickstart -k "gui/${uid}/${label}" 2>/dev/null; then
+    # Fallback for older launchd: unload+load the installed plist.
+    local plist="$HOME/Library/LaunchAgents/${label}.plist"
+    if [ -f "$plist" ]; then
+      launchctl unload "$plist" 2>/dev/null || true
+      launchctl load "$plist" 2>/dev/null || true
+    else
+      log_event "warn" "kickstart_failed_no_plist" "label=$label plist not found at $plist"
+    fi
+  fi
+}
+
+# --- CRITICAL sustain counter (in the counter JSON) ---------------------------
+
+# Increments (or resets) the consecutive-CRITICAL counter; echoes the new value.
+bump_critical_sustain() {
+  local crit="$1"  # "true" to increment, "false" to reset
+  python3 - "$WD_COUNTER_FILE" "$crit" <<'PY' 2>/dev/null || { [ "$crit" = "true" ] && echo 1 || echo 0; }
+import sys, json
+path, crit = sys.argv[1], sys.argv[2]
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {}
+if crit == "true":
+    d["sustain"] = int(d.get("sustain", 0)) + 1
+else:
+    d["sustain"] = 0
+json.dump(d, open(path, "w"))
+print(d["sustain"])
+PY
+}
+
+# --- 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 soft_threshold_mb=$(( (TOTAL_RAM_KB * CLAUDE_SOFT_PERCENT) / 100 / 1024 ))
+  local hard_threshold_mb=$(( (TOTAL_RAM_KB * CLAUDE_HARD_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 "  SOFT threshold:     ${soft_threshold_mb}MB (${CLAUDE_SOFT_PERCENT}%)"
+    echo "  HARD threshold:     ${hard_threshold_mb}MB (${CLAUDE_HARD_PERCENT}%)"
+    echo "System mem pressure:  ${system_pressure}% (SOFT ${SYSTEM_SOFT_PERCENT}% / HARD ${SYSTEM_HARD_PERCENT}% / CRITICAL ${SYSTEM_CRITICAL_PERCENT}%)"
+    if [ -f "$THROTTLE_FILE" ]; then
+      echo "Throttle:             active — $(cat "$THROTTLE_FILE")"
+    else
+      echo "Throttle:             none"
+    fi
+    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
+
+  # --- CRITICAL: system pressure ≥90% sustained 2 runs → clean daemon restart -
+  if [ "$system_pressure" -ge "$SYSTEM_CRITICAL_PERCENT" ]; then
+    local sustain
+    sustain=$(bump_critical_sustain "true")
+    log_event "critical" "system_memory_critical" "pressure=${system_pressure}% >= ${SYSTEM_CRITICAL_PERCENT}% (sustain ${sustain}/${CRITICAL_SUSTAIN_RUNS})"
+    if [ "$sustain" -ge "$CRITICAL_SUSTAIN_RUNS" ]; then
+      echo "CRITICAL: memory pressure ${system_pressure}% sustained — restarting daemon (self-heal)"
+      critical_restart "$dry_run"
+      # Reset the sustain counter after acting so we don't restart every run.
+      bump_critical_sustain "false" >/dev/null 2>&1 || true
+    else
+      echo "CRITICAL: memory pressure ${system_pressure}% (run ${sustain}/${CRITICAL_SUSTAIN_RUNS} before restart)"
+      # Also throttle hard while we wait for the second confirming run.
+      [ "$dry_run" = "false" ] && write_throttle 1 "critical-pending"
+    fi
+    return 0
+  else
+    # Pressure recovered below CRITICAL — reset the sustain counter.
+    bump_critical_sustain "false" >/dev/null 2>&1 || true
+  fi
+
+  # --- HARD: kill youngest/biggest subagents (spare the oldest main) ----------
+  if [ "$system_pressure" -ge "$SYSTEM_HARD_PERCENT" ] || [ "$claude_pct" -ge "$CLAUDE_HARD_PERCENT" ]; then
+    log_event "warn" "hard_tier" "sys=${system_pressure}% claude=${claude_pct}% (RSS ${claude_rss_mb}MB)"
+    echo "HARD: trimming subagents (sys ${system_pressure}%, claude ${claude_pct}%)"
+    # Kill enough to drop the claude RSS back toward the SOFT threshold.
+    local target_rss_kb=$(( (TOTAL_RAM_KB * CLAUDE_SOFT_PERCENT) / 100 ))
+    local excess_kb=$(( claude_rss_kb - target_rss_kb ))
+    [ "$excess_kb" -lt 0 ] && excess_kb=0
+    local procs_to_kill=$(( (excess_kb / 614400) + 1 ))   # ~600MB/proc estimate
+    [ "$procs_to_kill" -lt 1 ] && procs_to_kill=1
+    echo "  Killing $procs_to_kill subagent(s) to free ~$(( excess_kb / 1024 ))MB..."
+    kill_youngest_biggest_subagents "$procs_to_kill" "$dry_run" >/dev/null
+    # Also lower the ceiling so the governor doesn't immediately refill the slots.
+    if [ "$dry_run" = "false" ]; then
+      local remaining=$(( claude_count - procs_to_kill ))
+      [ "$remaining" -lt 1 ] && remaining=1
+      write_throttle "$remaining" "hard-tier"
+    fi
+    return 0
+  fi
+
+  # --- Too many concurrent processes (count-based HARD) -----------------------
+  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_youngest_biggest_subagents "$excess" "$dry_run" >/dev/null
+    return 0
+  fi
+
+  # --- SOFT: write the throttle ceiling (no kills) ----------------------------
+  if [ "$system_pressure" -ge "$SYSTEM_SOFT_PERCENT" ] || [ "$claude_pct" -ge "$CLAUDE_SOFT_PERCENT" ]; then
+    log_event "warn" "soft_tier" "sys=${system_pressure}% claude=${claude_pct}% (RSS ${claude_rss_mb}MB, procs ${claude_count})"
+    echo "SOFT: throttling (sys ${system_pressure}%, claude ${claude_pct}%) — no kills"
+    if [ "$dry_run" = "false" ]; then
+      # Ceiling = liveCount - 2 (let two sessions drain naturally).
+      local ceiling=$(( claude_count - 2 ))
+      [ "$ceiling" -lt 1 ] && ceiling=1
+      write_throttle "$ceiling" "soft-tier"
+    else
+      echo "  [DRY RUN] Would write throttle ceiling=$(( claude_count - 2 ))"
+    fi
+    return 0
+  fi
+
+  # --- All clear: let any stale throttle expire on its own (governor checks TTL)
+  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}"