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

> Learn how the circuit breaker in chaitanyagiri/munder-difflin prevents false positives during auto compact missions using time-based exemptions and suspended token-velocity checks.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-29

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts):

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts) with lifecycle hooks in [`src/main/hooks.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.