@matt82198/aesop 0.1.0 → 0.3.1

package/bin/cli.js

@@ -11,8 +11,8 @@ const helpFlag = args.includes('--help') || args.includes('-h');
 const forceFlag = args.includes('--force');
 const yesFlag = args.includes('--yes');
 
-// Check for runtime subcommands (doctor, watch, dash, status)
-const runtimeCommands = ['doctor', 'watch', 'dash', 'status'];
+// Check for runtime subcommands (doctor, watch, dash, status, fleet, health-score, reproduce)
+const runtimeCommands = ['doctor', 'watch', 'dash', 'status', 'fleet', 'health-score', 'reproduce'];
 const isRuntimeCommand = runtimeCommands.includes(args[0]);
 
 if (isRuntimeCommand) {
@@ -20,7 +20,10 @@ if (isRuntimeCommand) {
     'doctor': '../tools/doctor.js',
     'watch': '../tools/watch.js',
     'dash': '../tools/dash.js',
-    'status': '../tools/status.js'
+    'status': '../tools/status.js',
+    'fleet': '../tools/fleet.js',
+    'health-score': '../tools/health-score.js',
+    'reproduce': '../tools/reproduce.js'
   };
   // Load and run the appropriate runtime module
   // These modules run async code that sets process.exitCode and will cause Node to exit
@@ -71,6 +74,66 @@ function validatePort(port) {
   return !isNaN(p) && p > 0 && p < 65536 ? p : null;
 }
 
+// Test if a port is available (returns Promise<boolean>)
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const net = require('net');
+    const sock = net.createConnection({ port, host: '127.0.0.1', timeout: 500 });
+    let resolved = false;
+
+    const cleanup = () => {
+      try {
+        sock.destroy();
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    };
+
+    sock.on('connect', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(false);  // Port is in use
+      }
+    });
+
+    sock.on('error', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);  // Port is free
+      }
+    });
+
+    sock.on('timeout', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);  // Assume free on timeout
+      }
+    });
+
+    // Fallback timeout
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);
+      }
+    }, 2000);
+  });
+}
+
+// Find next available port starting from basePort
+async function findAvailablePort(basePort = 8770) {
+  for (let port = basePort; port < basePort + 100; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  return basePort;  // Fallback to basePort
+}
+
 // Parse named flags
 function getFlag(flagName) {
   const idx = args.findIndex(arg => arg === flagName);
@@ -91,12 +154,16 @@ Usage:
   npx @matt82198/aesop watch
   npx @matt82198/aesop dash
   npx @matt82198/aesop status
+  npx @matt82198/aesop fleet
+  npx @matt82198/aesop reproduce
 
 Commands:
   doctor                  Preflight readiness check (Node.js, Python, git, config, dirs, hook, port)
   watch                   Launch the watchdog daemon (spawns daemons/run-watchdog.sh)
   dash                    Launch the web dashboard (spawns python3 ui/serve.py or python fallback)
   status                  One-shot fleet status snapshot (heartbeats, dashboard port, git branch)
+  fleet                   One-shot fleet snapshot (agents, heartbeats, tracker lanes, orchestrator status)
+  reproduce               Offline verification suite (repo: full test suite; installed: self-checks)
   wizard                  Interactive onboarding (prompts for project name, repos, port)
 
 Arguments:
@@ -116,6 +183,8 @@ Examples:
   npx @matt82198/aesop watch                                # Launch watchdog daemon
   npx @matt82198/aesop dash                                 # Launch web dashboard (default localhost:8770)
   npx @matt82198/aesop status                               # Show fleet status (heartbeats, port, git)
+  npx @matt82198/aesop fleet                                # Show fleet snapshot (JSON agents, heartbeats, tracker, orchestrator)
+  npx @matt82198/aesop reproduce                            # Run offline verification suite (full repo tests or installed checks)
   npx @matt82198/aesop                                      # Creates ./aesop-fleet/ with template
   npx @matt82198/aesop my-fleet                             # Creates ./my-fleet/ with template
   npx @matt82198/aesop wizard                               # Interactive onboarding (60-second setup)
@@ -314,7 +383,7 @@ function substituteTemplate(templateContent, projectName, domainsStr, reposStr)
   return result;
 }
 
-function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repoUrlsStr) {
+function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repoUrlsStr, port = 8770) {
   // Read example config
   const exampleConfigPath = path.join(templateRoot, 'aesop.config.example.json');
   let exampleConfig;
@@ -348,7 +417,8 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
       dashboard: {
         refresh_seconds: 1,
         enable_jq_parsing: true,
-        theme: 'dark'
+        theme: 'dark',
+        port: 8770
       },
       cardinal_rules: {
         subagent_model: 'haiku',
@@ -366,6 +436,8 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
   exampleConfig.scripts_root = '~/scripts';
   exampleConfig.temp_root = '~/.aesop-temp';
   exampleConfig.fleet_root = os.homedir();
+  exampleConfig.dashboard = exampleConfig.dashboard || {};
+  exampleConfig.dashboard.port = port;
   exampleConfig._generated_note = 'This config uses portable ~ paths which expand at runtime on all platforms. Config loaders in ui/config.py (Python) and monitor/collect-signals.mjs (Node.js) automatically expand ~ paths to your home directory.';
 
   // Parse repos if provided
@@ -392,14 +464,14 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
 
 // Print next steps and optionally run watchdog (returns a Promise)
 async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
-  console.log('\n🎯 Next 3 commands to get started:\n');
+  console.log('\n🎯 Next 2 commands to get started:\n');
   console.log(`  1. cd ${targetDir}`);
   console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
   console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${port})`);
-  console.log('\n📖 After that, review:');
-  console.log('  • CLAUDE.md (pre-filled with your project info)');
-  console.log('  • aesop.config.json (pre-configured for your repos)');
-  console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)\n');
+  console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+  console.log('  mkdir -p ~/.claude/memory');
+  console.log(`  cp ${targetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+  console.log(`  cp ${targetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)\n`);
 
   return new Promise((resolve) => {
     rl.question('Run watchdog --once now? (y/N): ', (answer) => {
@@ -422,6 +494,37 @@ async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
   });
 }
 
+// Initialize git repo if it doesn't exist
+function initializeGitRepo(targetDir, noGitFlag = false) {
+  if (noGitFlag) {
+    return false;  // User explicitly requested no git
+  }
+
+  const gitDir = path.join(targetDir, '.git');
+  if (fs.existsSync(gitDir)) {
+    return false;  // Git already initialized
+  }
+
+  try {
+    // Initialize git repo
+    execSync('git init -q', { cwd: targetDir, stdio: 'pipe' });
+    console.log('✓ Initialized git repository');
+
+    // Create initial commit
+    execSync('git config user.email "aesop-scaffold@local"', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git config user.name "Aesop Scaffold"', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git add -A', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git commit -q -m "Initial aesop scaffold"', { cwd: targetDir, stdio: 'pipe' });
+    console.log('✓ Created initial git commit');
+    return true;
+  } catch (e) {
+    // Git operations failed, continue anyway
+    console.warn('⚠ Warning: Failed to initialize git repo automatically');
+    console.warn('  Run manually: cd ' + targetDir + ' && git init && git add -A && git commit -m "Initial commit"');
+    return false;
+  }
+}
+
 function installPreCommitWaveguard(targetDir, templateRoot) {
   // Install the pre-commit waveguard hook to prevent commits during a wave
   // Try to locate .git directory
@@ -664,6 +767,7 @@ if (!isRuntimeCommand) {
     let finalTargetDir = targetDir;
     let configPath = path.join(targetDir, 'aesop.config.json');
     let dashboardPort = 8770;
+    const noGitFlag = args.includes('--no-git');
 
     let wizardRl = null;
 
@@ -704,7 +808,7 @@ if (!isRuntimeCommand) {
       }
       finalReposStr = selectedRepos;
 
-      // Q3: Dashboard port
+      // Q3: Dashboard port (with availability check)
       let port = '';
       while (!port) {
         port = await promptUser(wizardRl, 'Dashboard port', '8770');
@@ -713,7 +817,21 @@ if (!isRuntimeCommand) {
           console.log('  ✗ Invalid port. Must be a number between 1 and 65535.');
           port = '';
         } else {
-          dashboardPort = validPort;
+          // Check if port is available
+          const available = await isPortAvailable(validPort);
+          if (!available) {
+            console.log(`  ⚠ Port ${validPort} is in use. Trying next available port...`);
+            const nextPort = await findAvailablePort(validPort);
+            if (nextPort !== validPort) {
+              console.log(`  → Using port ${nextPort} instead`);
+              dashboardPort = nextPort;
+            } else {
+              dashboardPort = validPort;
+            }
+            port = validPort.toString();  // Exit loop
+          } else {
+            dashboardPort = validPort;
+          }
         }
       }
 
@@ -728,8 +846,15 @@ if (!isRuntimeCommand) {
       // Non-interactive defaults for wizard mode with --yes
       finalProjectName = 'my-fleet';
       finalReposStr = '';
-      dashboardPort = 8770;
+      // Find available port
+      dashboardPort = await findAvailablePort(8770);
       console.log('🪄 Running onboarding wizard with defaults (--yes)');
+    } else if (!wizardMode && finalProjectName) {
+      // Headless mode: check and find available port
+      dashboardPort = await findAvailablePort(8770);
+      if (dashboardPort !== 8770) {
+        console.log(`ℹ Port 8770 is in use, using port ${dashboardPort} instead`);
+      }
     }
 
     // Copy template files
@@ -767,8 +892,8 @@ if (!isRuntimeCommand) {
         // But if it does, warn and skip
         console.warn(`⚠ Warning: aesop.config.json already exists at ${configPath}`);
       } else {
-        // Generate aesop.config.json
-        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr, finalRepoUrlsStr);
+        // Generate aesop.config.json with the determined port
+        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr, finalRepoUrlsStr, dashboardPort);
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log('✓ Generated aesop.config.json (configured for your repos)');
       }
@@ -782,10 +907,13 @@ if (!isRuntimeCommand) {
       console.log('✓ Copied MEMORY-SEED.md (template for your facts)');
     }
 
-    // Install the pre-push hook
+    // Initialize git repo if needed (BEFORE installing hooks)
+    initializeGitRepo(finalTargetDir, noGitFlag);
+
+    // Install the pre-push hook (only works if .git exists)
     installPrePushHook(finalTargetDir, templateRoot);
 
-    // Install the pre-commit waveguard hook
+    // Install the pre-commit waveguard hook (only works if .git exists)
     installPreCommitWaveguard(finalTargetDir, templateRoot);
 
     console.log(`\n✅ Scaffolded aesop template into "${finalTargetDir}" (${copiedCount} files)`);
@@ -800,35 +928,34 @@ if (!isRuntimeCommand) {
       console.log(`  1. cd ${finalTargetDir}`);
       console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
       console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
-      console.log('\n📖 After that, review:');
-      console.log('  • CLAUDE.md (pre-filled with your project info)');
-      console.log('  • aesop.config.json (pre-configured for your repos)');
-      console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)');
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
       process.exit(0);
     } else if (finalProjectName) {
-      console.log('\nHeadless scaffolding complete! Next steps:');
+      console.log('\n✅ Headless scaffolding complete!\n');
+      console.log('🎯 Next 3 commands to get started:\n');
       console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. Review CLAUDE.md (pre-filled with your project info)');
-      console.log('  3. Review aesop.config.json (pre-configured for your repos)');
-      console.log('\nInitialize your brain (Claude Code team memory):');
-      console.log('  4. mkdir -p ~/.claude/memory');
-      console.log(`  5. cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (or review existing ~/.claude/CLAUDE.md)`);
-      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-      console.log('\nRun the daemon and dashboard:');
-      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
+      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
+      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     } else {
-      console.log('\nConfiguration steps:');
+      console.log('\n✅ Scaffold complete!\n');
+      console.log('🎯 Next 3 commands to get started:\n');
       console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. cp aesop.config.example.json aesop.config.json');
-      console.log('  3. Edit aesop.config.json with your configuration');
-      console.log('\nInitialize your brain (Claude Code team memory):');
-      console.log('  4. mkdir -p ~/.claude/memory');
-      console.log(`  5. cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
-      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-      console.log('\nRun the daemon and dashboard:');
-      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
+      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
+      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
+      console.log('\n📖 Configuration steps (optional):\n');
+      console.log('  cp aesop.config.example.json aesop.config.json  (if not generated)');
+      console.log('  Edit aesop.config.json with your configuration');
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     }
     console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
     process.exit(0);

package/daemons/run-watchdog.sh

@@ -25,8 +25,8 @@ elif command -v python >/dev/null 2>&1; then
   PYTHON_EXE="python"
 fi
 
-# Resolve conductor3 directory (sibling of AESOP_ROOT)
-CONDUCTOR_ROOT="$(dirname "$AESOP_ROOT")/conductor3"
+# Resolve conductor3 directory (sibling of AESOP_ROOT); env var override for portability
+CONDUCTOR_ROOT="${CONDUCTOR_ROOT:-$(dirname "$AESOP_ROOT")/conductor3}"
 MONITOR_HB_FILE="$CONDUCTOR_ROOT/monitor/.monitor-heartbeat"
 MONITOR_HB_STALE_THRESHOLD=600
 
@@ -59,7 +59,11 @@ acquire_lock() {
     # Check if both required files exist
     if [ -f "$lock_dir/timestamp" ] && [ -f "$lock_dir/pid" ] && [ -n "$lock_pid" ]; then
       # Both files present and pid is readable - use timestamp for stale check
-      local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
+      local lock_ts=$(cat "$lock_dir/timestamp" 2>/dev/null)
+      local lock_mtime=${lock_ts:-0}
+      if [ -z "$lock_ts" ]; then
+        echo "empty/corrupt lock timestamp — treating lock as stale" >&2
+      fi
       local now=$(date +%s)
       local lock_age=$((now - lock_mtime))
 
@@ -87,7 +91,11 @@ acquire_lock() {
 
       # Case 2: no pid file, but timestamp exists and is old (definitely abandoned)
       if [ $should_reclaim -eq 0 ] && [ -f "$lock_dir/timestamp" ]; then
-        local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
+        local lock_ts=$(cat "$lock_dir/timestamp" 2>/dev/null)
+        local lock_mtime=${lock_ts:-0}
+        if [ -z "$lock_ts" ]; then
+          echo "empty/corrupt lock timestamp — treating lock as stale" >&2
+        fi
         local now=$(date +%s)
         local lock_age=$((now - lock_mtime))
         if [ "$lock_age" -gt "$stale_threshold" ]; then
@@ -125,6 +133,7 @@ release_lock() {
 }
 
 # Check monitor heartbeat staleness; log to fleet-backup.log if missing or >600s old
+# Gracefully skips if CONDUCTOR_ROOT doesn't exist (portability for non-conductor deployments)
 check_monitor_staleness() {
   local hb_file="$1"
   local stale_threshold="$2"
@@ -132,6 +141,9 @@ check_monitor_staleness() {
   if [ -z "$hb_file" ] || [ -z "$log_file" ]; then
     return
   fi
+  if [ ! -d "$(dirname "$hb_file")" ]; then
+    return
+  fi
   if [ ! -f "$hb_file" ]; then
     echo "[$(date '+%F %T')] SIGNAL: monitor heartbeat missing ($hb_file)" >> "$log_file"
     return

package/daemons/selfheal.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# Self-healing fleet supervisor: detects stale sibling heartbeats and restarts daemons.
+# Monitors run-watchdog.sh and run-monitor.sh with safe, idempotent recovery actions.
+# Usage: selfheal.sh [--once]
+#
+# Configuration: export AESOP_ROOT=/path/to/aesop before running (defaults to script directory's parent).
+# Testing: export AESOP_SELFHEAL_SKIP_RESTART=1 to skip actual daemon restarts (test-only flag).
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AESOP_ROOT="${AESOP_ROOT:-$(dirname "$SCRIPT_DIR")}"
+CONDUCTOR_ROOT="${CONDUCTOR_ROOT:-$(dirname "$AESOP_ROOT")/conductor3}"
+MODE="${1:-daemon}"
+
+SELFHEAL_LOCK_DIR="$AESOP_ROOT/state/.selfheal-lock"
+SELFHEAL_LOG="$AESOP_ROOT/state/SELFHEAL.log"
+SELFHEAL_STALE_THRESHOLD=600
+
+WATCHDOG_HB="$AESOP_ROOT/state/.watchdog-heartbeat"
+WATCHDOG_STALE_THRESHOLD=600
+
+MONITOR_HB="$CONDUCTOR_ROOT/monitor/.monitor-heartbeat"
+MONITOR_STALE_THRESHOLD=600
+
+ts() {
+  date '+%Y-%m-%d %H:%M:%S'
+}
+
+log_heal() {
+  local msg="$1"
+  echo "[$(ts)] $msg" | tee -a "$SELFHEAL_LOG"
+}
+
+ensure_log_dir() {
+  mkdir -p "$(dirname "$SELFHEAL_LOG")" 2>/dev/null || true
+}
+
+acquire_lock() {
+  local lock_dir="$1"
+  local stale_threshold="$2"
+
+  mkdir -p "$(dirname "$lock_dir")" 2>/dev/null || true
+
+  if mkdir "$lock_dir" 2>/dev/null; then
+    if ! date +%s > "$lock_dir/timestamp" 2>/dev/null || ! echo $$ > "$lock_dir/pid" 2>/dev/null; then
+      rm -rf "$lock_dir" 2>/dev/null || true
+      return 1
+    fi
+    return 0
+  fi
+
+  if [ -d "$lock_dir" ]; then
+    local lock_pid=""
+    if [ -f "$lock_dir/pid" ]; then
+      lock_pid=$(cat "$lock_dir/pid" 2>/dev/null)
+    fi
+
+    if [ -f "$lock_dir/timestamp" ] && [ -f "$lock_dir/pid" ] && [ -n "$lock_pid" ]; then
+      local lock_ts=$(cat "$lock_dir/timestamp" 2>/dev/null)
+      local lock_mtime=${lock_ts:-0}
+      local now=$(date +%s)
+      local lock_age=$((now - lock_mtime))
+
+      if [ "$lock_age" -gt "$stale_threshold" ]; then
+        rm -rf "$lock_dir" 2>/dev/null || true
+        if mkdir "$lock_dir" 2>/dev/null; then
+          date +%s > "$lock_dir/timestamp" 2>/dev/null || true
+          echo $$ > "$lock_dir/pid" 2>/dev/null || true
+          return 2
+        fi
+      fi
+    else
+      local should_reclaim=0
+      if [ -f "$lock_dir/pid" ] && [ -n "$lock_pid" ]; then
+        if ! kill -0 "$lock_pid" 2>/dev/null; then
+          should_reclaim=1
+        fi
+      fi
+
+      if [ $should_reclaim -eq 0 ] && [ -f "$lock_dir/timestamp" ]; then
+        local lock_ts=$(cat "$lock_dir/timestamp" 2>/dev/null)
+        local lock_mtime=${lock_ts:-0}
+        local now=$(date +%s)
+        local lock_age=$((now - lock_mtime))
+
+        if [ "$lock_age" -gt "$stale_threshold" ]; then
+          should_reclaim=1
+        fi
+      fi
+
+      if [ $should_reclaim -eq 1 ]; then
+        rm -rf "$lock_dir" 2>/dev/null || true
+        if mkdir "$lock_dir" 2>/dev/null; then
+          date +%s > "$lock_dir/timestamp" 2>/dev/null || true
+          echo $$ > "$lock_dir/pid" 2>/dev/null || true
+          return 2
+        fi
+      fi
+    fi
+  fi
+
+  return 1
+}
+
+release_lock() {
+  local lock_dir="$1"
+  rm -rf "$lock_dir" 2>/dev/null || true
+  if [ -d "$lock_dir" ]; then
+    ensure_log_dir
+    log_heal "WARN: release_lock: failed to remove lock dir: $lock_dir (may be in-use on Windows)"
+  fi
+}
+
+is_heartbeat_stale() {
+  local hb_file="$1"
+  local stale_threshold="$2"
+
+  if [ ! -f "$hb_file" ]; then
+    return 0
+  fi
+
+  local hb_ts=$(cat "$hb_file" 2>/dev/null)
+  if [ -z "$hb_ts" ] || ! [[ "$hb_ts" =~ ^[0-9]+$ ]]; then
+    return 0
+  fi
+
+  local now=$(date +%s)
+  local age=$((now - hb_ts))
+
+  if [ "$age" -gt "$stale_threshold" ]; then
+    return 0
+  fi
+
+  return 1
+}
+
+restart_watchdog() {
+  ensure_log_dir
+
+  if is_heartbeat_stale "$WATCHDOG_HB" "$WATCHDOG_STALE_THRESHOLD"; then
+    if [ -z "${AESOP_SELFHEAL_SKIP_RESTART:-}" ]; then
+      log_heal "ACTION: run-watchdog heartbeat stale, restarting..."
+      if command -v bash >/dev/null 2>&1; then
+        bash "$AESOP_ROOT/daemons/run-watchdog.sh" >/dev/null 2>&1 &
+        log_heal "RESTART watchdog: spawned (PID: $!)"
+      else
+        log_heal "WARN: Cannot restart watchdog, bash not found"
+      fi
+    else
+      log_heal "DRY-RUN: watchdog heartbeat stale (would restart)"
+    fi
+    return 0
+  fi
+
+  return 1
+}
+
+restart_monitor() {
+  ensure_log_dir
+
+  if [ ! -d "$CONDUCTOR_ROOT" ]; then
+    return 1
+  fi
+
+  if is_heartbeat_stale "$MONITOR_HB" "$MONITOR_STALE_THRESHOLD"; then
+    if [ -z "${AESOP_SELFHEAL_SKIP_RESTART:-}" ]; then
+      log_heal "ACTION: run-monitor heartbeat stale, restarting..."
+      if command -v bash >/dev/null 2>&1; then
+        bash "$CONDUCTOR_ROOT/monitor/run-monitor.sh" >/dev/null 2>&1 &
+        log_heal "RESTART monitor: spawned (PID: $!)"
+      else
+        log_heal "WARN: Cannot restart monitor, bash not found"
+      fi
+    else
+      log_heal "DRY-RUN: monitor heartbeat stale (would restart)"
+    fi
+    return 0
+  fi
+
+  return 1
+}
+
+cycle_once() {
+  ensure_log_dir
+  log_heal "=== Selfheal cycle START ==="
+
+  local any_action=0
+
+  restart_watchdog
+  if [ $? -eq 0 ]; then
+    any_action=1
+  fi
+
+  restart_monitor
+  if [ $? -eq 0 ]; then
+    any_action=1
+  fi
+
+  if [ $any_action -eq 0 ]; then
+    log_heal "No stale heartbeats detected"
+  fi
+
+  log_heal "=== Selfheal cycle END ==="
+}
+
+main() {
+  lock_result=0
+  acquire_lock "$SELFHEAL_LOCK_DIR" "$SELFHEAL_STALE_THRESHOLD"
+  lock_result=$?
+
+  if [ $lock_result -eq 1 ]; then
+    exit 0
+  fi
+
+  trap "release_lock \"$SELFHEAL_LOCK_DIR\"; exit 0" INT TERM EXIT
+
+  if [ "$MODE" = "--once" ]; then
+    cycle_once
+    exit 0
+  fi
+
+  while true; do
+    cycle_once
+    sleep 60
+  done
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  main "$@"
+fi