How the Circuit Breaker Handles Compaction Exemptions to Prevent False Positives During Auto-Compact Missions

The circuit breaker in chaitanyagiri/munder-difflin prevents false‑positive triggers during auto‑compact missions by implementing a time‑based compaction exemption that suspends token‑velocity checks while the compactingUntil timestamp remains in the future.

The circuit‑breaker module (src/main/breaker.ts) monitors agent health by detecting runaway loops and cost overruns. During auto‑compact missions, agents generate bursts of output tokens without modifying coordination files, which would normally trigger velocity‑based trip wires. To prevent these false positives, the breaker implements a compaction exemption mechanism that temporarily disables specific checks while preserving protection against genuine failures.

The Compaction Exemption Lifecycle

Initiating the Grace Period with recordCompactStart

When an auto‑compact mission begins, the PreCompact hook invokes recordCompactStart(agentId). This method establishes a grace period by setting a future timestamp in the agent's state:

// src/main/breaker.ts#L75-L81
recordCompactStart(agentId: string) {
  const s = this.get(agentId);
  const now = Date.now();
  s.compactingUntil = now + COMPACT_GRACE_MS; // 5 minutes
}

The COMPACT_GRACE_MS constant (5 minutes) provides a generous window covering the entire compaction burst.

Shortening to Trailing Grace with recordCompactEnd

When compaction completes, the PostCompact hook or session initialization calls recordCompactEnd(agentId). If the exemption is still active, it reduces the window to a shorter trailing grace:

// src/main/breaker.ts#L84-L90
recordCompactEnd(agentId: string) {
  const s = this.get(agentId);
  const now = Date.now();
  if (s.compactingUntil > now) {
    s.compactingUntil = now + POST_COMPACT_GRACE_MS; // 90 seconds
  }
}

This 90‑second (POST_COMPACT_GRACE_MS) trailing grace shields the immediate aftermath of compaction from velocity spikes.

Evaluation Logic During Exemption

During the regular heartbeat (tick → evaluate), the breaker checks compactingUntil before calculating token velocity:

// src/main/breaker.ts#L152-L165
if (input.sample && s.lastSample && nowMs >= s.compactingUntil) {
  // Token-velocity calculation only runs after exemption expires
  const dOut = input.sample.output - s.lastSample.output;
  const dMin = (input.sample.ts - s.lastSample.ts) / 60_000;
  if (dOut > 0 && dMin > 0) {
    const velocity = dOut / dMin;
    if (velocity > cfg.tokenVelocityPerMin) {
      return { 
        tripping: true, 
        reason: `token velocity ${Math.round(velocity)}/min > ${cfg.tokenVelocityPerMin}/min` 
      };
    }
  }
}

While nowMs < s.compactingUntil, the condition fails and the velocity check is bypassed entirely.

Configuration Constants and Timing

The grace periods are defined as constants at the top of src/main/breaker.ts:

const COMPACT_GRACE_MS = 5 * 60_000;      // 5 minutes
const POST_COMPACT_GRACE_MS = 90_000;     // 90 seconds

These values ensure the exemption outlives the compaction burst while minimizing the window where genuine loops might go undetected.

Hook Integration Architecture

The exemption mechanism integrates with the agent lifecycle through hooks defined in src/main/hooks.ts:

• PreCompact hook: Calls circuitBreaker.recordCompactStart(agentId) when the mission begins
• PostCompact hook: Calls circuitBreaker.recordCompactEnd(agentId) when the mission completes

The main heartbeat in src/main/index.ts invokes circuitBreaker.tick(...) each cycle, which internally calls evaluate and respects the compactingUntil timestamp.

Summary

• The compaction exemption prevents false‑positive circuit breaks during auto‑compact missions by suspending token‑velocity checks while compactingUntil is in the future.
• recordCompactStart establishes a 5‑minute grace period when compaction begins.
• recordCompactEnd reduces the exemption to 90 seconds when compaction finishes, providing a trailing safety window.
• Normal protections remain active during exemption for repeated tool calls, error storms, and cost caps.
• Implementation resides in src/main/breaker.ts with lifecycle hooks in src/main/hooks.ts.

Frequently Asked Questions

What triggers the compaction exemption in the circuit breaker?

The exemption triggers when the PreCompact hook calls recordCompactStart(agentId), which sets compactingUntil to the current time plus 5 minutes. This occurs automatically at the start of any auto‑compact mission.

Why does the circuit breaker need to exempt auto‑compact missions?

Auto‑compact missions generate bursts of output tokens without modifying coordination files. Without exemption, the breaker's token‑velocity algorithm would interpret this burst as a runaway loop and trip falsely, aborting a legitimate maintenance operation.

How long does the compaction exemption last?

The exemption lasts for 5 minutes during active compaction (COMPACT_GRACE_MS), then shortens to 90 seconds after compaction ends (POST_COMPACT_GRACE_MS) if recordCompactEnd is called. If not explicitly ended, the original 5‑minute window persists.

Does the exemption disable all circuit breaker protections?

No. The exemption only skips token‑velocity checks. Other protections including repeated tool call detection, error rate thresholds, cost caps, and genuine no‑progress loop detection remain fully active during the compaction window.

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