Evolver Operations Modules: How the `src/ops/` Directory Manages the Evolution Lifecycle

The src/ops/ directory contains eight specialized Node.js modules—lifecycle.js, trigger.js, skills_monitor.js, self_repair.js, cleanup.js, commentary.js, innovation.js, and health_check.js—that collectively orchestrate, monitor, and maintain the Evolver process lifecycle.

In the EvoMap/evolver repository, the src/ops/ folder serves as the control plane for the autonomous evolution system. These self-contained modules handle everything from process spawning and signal-based wakeups to Git repository repair and skill stagnation detection, ensuring the Evolver loop remains healthy and responsive.

Core Lifecycle Management

The lifecycle.js module acts as the central nervous system for Evolver's long-running processes.

Process Orchestration

According to the EvoMap/evolver source code, src/ops/lifecycle.js manages process discovery, startup, and shutdown through precise PID tracking. The getRunningPids() function parses ps output to locate existing Evolver loops by scanning for node … index.js --loop patterns.

When starting the evolution cycle, the module spawns a detached child process and persists its identifier:

// From src/ops/lifecycle.js
const proc = spawn('node', [script, '--loop'], {
  detached: true,
  stdio: ['ignore', logOut, logErr]
});
// PID written to memory/evolver_loop.pid

The stop() implementation sends SIGTERM to discovered PIDs, falls back to SIGKILL after timeout, and cleans up lock files including evolver.pid and the PID file. The restart() method chains stop() and start() with configurable delays.

Health Monitoring and Auto-Recovery

The lifecycle module integrates with health_check.js through the checkHealth() method. When health checks fail, the system automatically triggers a restart sequence. Status reporting returns JSON containing running PIDs, command-line details, and the active log file path from getEvolverLogPath().

Event Handling and Triggers

External systems can interrupt idle loops immediately via src/ops/trigger.js. This module implements lightweight inter-process communication by writing to memory/evolver_wake.signal:

// Signal mechanism for immediate wake-up
fs.writeFileSync('memory/evolver_wake.signal', Date.now().toString());

The wrapper script polls for this file, allowing external events—such as new task availability—to resume evolution without waiting for the standard sleep interval.

Ecosystem Maintenance Modules

Beyond process management, three modules maintain the operational integrity of the skill ecosystem and repository.

Dependency Health

src/ops/skills_monitor.js scans installed skills for missing dependencies or corrupted metadata. It performs automatic healing for simple problems, preventing the evolution loop from crashing when loading a malformed skill package.

Repository Integrity

When Git operations fail, src/ops/self_repair.js handles lock file removal, merge conflict resolution, and rebase cleanup. For severe corruption, it optionally executes a hard reset to restore repository usability, ensuring the evolution cycle can always commit changes.

Disk Space Management

The cleanup.js module prevents storage bloat by purging old GEP prompt artifacts matching gep_prompt_*.json and gep_prompt_*.txt patterns. This proactive maintenance prevents the health check from flagging disk-space failures that would otherwise trigger unnecessary restarts.

Intelligence and Reporting

Three additional modules provide observability and drive evolutionary expansion.

Cycle Commentary

src/ops/commentary.js generates persona-based status comments for each evolution cycle. These human-readable summaries can be logged locally or posted to external chat channels, providing transparency into the system's decision-making process.

Innovation Detection

When skill development stagnates, src/ops/innovation.js analyzes the current capability set and suggests new skill ideas. This feeds directly into the innovation phase of the lifecycle, prompting the system to expand its capabilities autonomously.

System Health Checks

The health_check.js module runs comprehensive system-level validation including environment variable verification, disk space monitoring, memory usage checks, and process count limits. These metrics inform lifecycle.checkHealth() restart decisions.

Module Aggregation Pattern

Rather than importing individual modules throughout the codebase, EvoMap/evolver uses src/ops/index.js as a central export point. This barrel file re-exports the most commonly used operations modules, simplifying imports in higher-level orchestrators like evolve.js and the scheduler.

// Typical usage pattern in consuming modules
const { lifecycle, trigger, healthCheck } = require('./src/ops');

Summary

• lifecycle.js serves as the primary controller, managing PID-based process lifecycle through start(), stop(), and restart() functions while maintaining state in memory/evolver_loop.pid.
• trigger.js enables event-driven architecture by writing wake signals to memory/evolver_wake.signal.
• skills_monitor.js and self_repair.js maintain ecosystem health through dependency scanning and Git repository repair.
• cleanup.js prevents disk exhaustion by removing old gep_prompt_* artifacts.
• commentary.js and innovation.js provide observability and drive capability expansion.
• health_check.js validates system resources to inform automated restart decisions.
• index.js aggregates these modules for clean import patterns across the codebase.

Frequently Asked Questions

How does Evolver handle process crashes or hangs?

The lifecycle.js module detects failed processes through getRunningPids() and integrates with health_check.js to validate system health. When checks fail, it automatically executes the restart sequence, sending SIGTERM (with SIGKILL fallback) to stale processes before spawning a new detached instance.

What triggers an immediate evolution cycle outside the normal schedule?

External events can force immediate execution by invoking src/ops/trigger.js, which writes a timestamp to memory/evolver_wake.signal. The loop wrapper detects this file and interrupts any sleep state, allowing real-time responsiveness to new tasks or urgent changes.

How does the system recover from Git repository corruption?

src/ops/self_repair.js automatically handles common Git failures including stale lock files, incomplete merges, and interrupted rebases. For severe corruption that routine repair cannot fix, the module optionally performs a hard reset to restore the repository to a functional state.

Why does the cleanup module specifically target gep_prompt_* files?

These files represent temporary GEP (Generative Evolutionary Programming) prompt artifacts that accumulate during evolution cycles. src/ops/cleanup.js targets this specific pattern to prevent disk-space exhaustion, which would otherwise cause health_check.js to flag system failures and trigger protective restarts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}