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

> Discover how Evolver operations modules in src/ops manage the evolution lifecycle. Explore Node.js modules for triggers, self repair, and more.

- Repository: [EvoMap/evolver](https://github.com/EvoMap/evolver)
- Tags: how-to-guide
- Published: 2026-04-17

---

**The `src/ops/` directory contains eight specialized Node.js modules—[`lifecycle.js`](https://github.com/EvoMap/evolver/blob/main/lifecycle.js), [`trigger.js`](https://github.com/EvoMap/evolver/blob/main/trigger.js), [`skills_monitor.js`](https://github.com/EvoMap/evolver/blob/main/skills_monitor.js), [`self_repair.js`](https://github.com/EvoMap/evolver/blob/main/self_repair.js), [`cleanup.js`](https://github.com/EvoMap/evolver/blob/main/cleanup.js), [`commentary.js`](https://github.com/EvoMap/evolver/blob/main/commentary.js), [`innovation.js`](https://github.com/EvoMap/evolver/blob/main/innovation.js), and [`health_check.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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:

```javascript
// 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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/src/ops/trigger.js). This module implements lightweight inter-process communication by writing to `memory/evolver_wake.signal`:

```javascript
// 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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/evolve.js) and the scheduler.

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

```

## Summary

- **[`lifecycle.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/trigger.js)** enables event-driven architecture by writing wake signals to `memory/evolver_wake.signal`.
- **[`skills_monitor.js`](https://github.com/EvoMap/evolver/blob/main/skills_monitor.js)** and **[`self_repair.js`](https://github.com/EvoMap/evolver/blob/main/self_repair.js)** maintain ecosystem health through dependency scanning and Git repository repair.
- **[`cleanup.js`](https://github.com/EvoMap/evolver/blob/main/cleanup.js)** prevents disk exhaustion by removing old `gep_prompt_*` artifacts.
- **[`commentary.js`](https://github.com/EvoMap/evolver/blob/main/commentary.js)** and **[`innovation.js`](https://github.com/EvoMap/evolver/blob/main/innovation.js)** provide observability and drive capability expansion.
- **[`health_check.js`](https://github.com/EvoMap/evolver/blob/main/health_check.js)** validates system resources to inform automated restart decisions.
- **[`index.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/lifecycle.js) module detects failed processes through `getRunningPids()` and integrates with [`health_check.js`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/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`](https://github.com/EvoMap/evolver/blob/main/src/ops/cleanup.js) targets this specific pattern to prevent disk-space exhaustion, which would otherwise cause [`health_check.js`](https://github.com/EvoMap/evolver/blob/main/health_check.js) to flag system failures and trigger protective restarts.