Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(compact-protocol): implement COMPACT PROTOCOL + REFRESH PROTOCOL behind flag (default off)

Chaitanya Giri2a6ad847f140
diff --git a/src/main/compact-gate.cjs b/src/main/compact-gate.cjs
new file mode 100644
index 00000000..5d381989
--- /dev/null
+++ b/src/main/compact-gate.cjs
@@ -0,0 +1,107 @@
+'use strict';
+
+// CompactGate — core logic for the COMPACT PROTOCOL (see hive/protocols/COMPACT-PROTOCOL.md).
+//
+// Plain CommonJS so tests can require() this without transpilation and so it
+// can be imported from compact.ts with no bundler special-casing.
+//
+// Responsibilities:
+// - Single-flight: at most one compaction per agent in flight
+// - Cooldown: after a compaction completes, suppresses all compact requests
+// (from any service) for the cooldown window — no compact-on-top-of-compact
+// - 50% threshold: trigger at 50% context utilisation (was 80% in old watchdog)
+// - Fire counter: after every N fires, emit 'refresh' instead of 'compact' so
+// the agent receives the REFRESH PROTOCOL message instead of a silent /compact
+// - Counter reset: when context drops well below threshold the counter resets,
+// indicating a genuine workload drop / context reclaim
+
+const DEFAULT_THRESHOLD = 0.50;
+const DEFAULT_COOLDOWN_MS = 90_000; // 90 s — long enough to cover most /compact ops
+const DEFAULT_REFRESH_AFTER_FIRES = 3;
+
+class CompactGate {
+ constructor({
+ enabled = false,
+ threshold = DEFAULT_THRESHOLD,
+ cooldownMs = DEFAULT_COOLDOWN_MS,
+ refreshAfterFires = DEFAULT_REFRESH_AFTER_FIRES,
+ } = {}) {
+ this.enabled = enabled;
+ this.threshold = threshold;
+ this.cooldownMs = cooldownMs;
+ this.refreshAfterFires = refreshAfterFires;
+
+ /** agentId → true while a compaction request is in flight (not yet completed). */
+ this.pending = new Set();
+ /** agentId → timestamp (ms) after which the cooldown expires. */
+ this.cooldownUntil = new Map();
+ /** agentId → consecutive compaction fire count (resets on workload drop). */
+ this.fireCount = new Map();
+ }
+
+ /**
+ * Called by the Status hook handler with each context-window reading.
+ *
+ * Returns:
+ * 'skip' — below threshold or gate disabled; do nothing
+ * 'blocked' — above threshold but single-flight or cooldown active; do nothing
+ * 'compact' — threshold crossed; issue /compact for this agent
+ * 'refresh' — every Nth fire; emit REFRESH PROTOCOL message instead
+ */
+ check(agentId, contextPct) {
+ if (!this.enabled) return 'skip';
+
+ if (contextPct < this.threshold) {
+ // Well below threshold (< threshold/2) → workload dropped; reset the fire
+ // counter so the next crossing starts fresh rather than escalating to REFRESH
+ // prematurely after a genuine context reclaim.
+ if (contextPct < this.threshold / 2) {
+ this.fireCount.delete(agentId);
+ this.pending.delete(agentId);
+ }
+ return 'skip';
+ }
+
+ // Single-flight guard
+ if (this.pending.has(agentId)) return 'blocked';
+
+ // Cooldown guard (dedup across any service that might trigger a compact)
+ const cd = this.cooldownUntil.get(agentId);
+ if (cd !== undefined && Date.now() < cd) return 'blocked';
+
+ // Increment consecutive fire count
+ const fires = (this.fireCount.get(agentId) ?? 0) + 1;
+ this.fireCount.set(agentId, fires);
+ this.pending.add(agentId);
+
+ return fires % this.refreshAfterFires === 0 ? 'refresh' : 'compact';
+ }
+
+ /**
+ * Call when a compaction has completed (e.g., the post-compact Stop hook fires).
+ * Clears the in-flight flag and starts the cooldown window.
+ */
+ onCompacted(agentId) {
+ this.pending.delete(agentId);
+ this.cooldownUntil.set(agentId, Date.now() + this.cooldownMs);
+ }
+
+ /**
+ * Returns true when this gate would suppress a compact request for agentId.
+ * Use this to let the scheduler standup or janitor defer to the gate.
+ */
+ isBlocked(agentId) {
+ if (this.pending.has(agentId)) return true;
+ const cd = this.cooldownUntil.get(agentId);
+ return cd !== undefined && Date.now() < cd;
+ }
+
+ /** Remove all per-agent state (agent removed / disconnected). */
+ remove(agentId) {
+ this.pending.delete(agentId);
+ this.cooldownUntil.delete(agentId);
+ this.fireCount.delete(agentId);
+ }
+}
+
+module.exports = { CompactGate, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES };
diff --git a/src/main/compact.ts b/src/main/compact.ts
new file mode 100644
index 00000000..0d8f547c
--- /dev/null
+++ b/src/main/compact.ts
@@ -0,0 +1,60 @@
+/**
+ * TypeScript wrapper around compact-gate.cjs so the main process and hooks.ts
+ * can import with full types. The plain-JS core lives in compact-gate.cjs so
+ * tests can require() it directly without a TypeScript compile step.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { CompactGate: _CG, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES } =
+ require('./compact-gate.cjs') as {
+ CompactGate: new (opts?: CompactGateConfig) => _GateInstance;
+ DEFAULT_THRESHOLD: number;
+ DEFAULT_COOLDOWN_MS: number;
+ DEFAULT_REFRESH_AFTER_FIRES: number;
+ };
+
+export { DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES };
+
+export type CompactAction = 'compact' | 'refresh' | 'blocked' | 'skip';
+
+export interface CompactGateConfig {
+ /** Feature flag — default false. Zero behavior change when off. */
+ enabled?: boolean;
+ /** Context-window utilisation threshold (0–1). Default 0.50 (50%). */
+ threshold?: number;
+ /** Milliseconds to suppress all compact requests after one completes. Default 90 000. */
+ cooldownMs?: number;
+ /** Issue REFRESH PROTOCOL after every N fires. Default 3. */
+ refreshAfterFires?: number;
+}
+
+interface _GateInstance {
+ enabled: boolean;
+ threshold: number;
+ pending: Set<string>;
+ fireCount: Map<string, number>;
+ check(agentId: string, contextPct: number): string;
+ onCompacted(agentId: string): void;
+ isBlocked(agentId: string): boolean;
+ remove(agentId: string): void;
+}
+
+export class CompactGate {
+ readonly enabled: boolean;
+ readonly threshold: number;
+ private _g: _GateInstance;
+
+ constructor(config: CompactGateConfig = {}) {
+ this._g = new _CG(config);
+ this.enabled = this._g.enabled;
+ this.threshold = this._g.threshold;
+ }
+
+ check(agentId: string, contextPct: number): CompactAction {
+ return this._g.check(agentId, contextPct) as CompactAction;
+ }
+
+ onCompacted(agentId: string): void { this._g.onCompacted(agentId); }
+ isBlocked(agentId: string): boolean { return this._g.isBlocked(agentId); }
+ remove(agentId: string): void { this._g.remove(agentId); }
+}
diff --git a/src/main/config.ts b/src/main/config.ts
index 8b11c83e..ec2df1ac 100644
--- a/src/main/config.ts
+++ b/src/main/config.ts
@@ -72,6 +72,21 @@ export const HEARTBEAT_MISSION: ScheduledMission = {
quietThresholdMs: 300_000
};
+/** COMPACT PROTOCOL config (see hive/protocols/COMPACT-PROTOCOL.md).
+ * Default off — zero behavior change until explicitly enabled. Shared floor
+ * infra; requires god + human sign-off before activation (flag flip). */
+export interface CompactProtocolConfig {
+ /** Master feature flag. Default false = old 80%-watchdog + standup path unchanged. */
+ enabled?: boolean;
+ /** Context utilisation threshold (0–1) to trigger compaction. Default 0.50. */
+ threshold?: number;
+ /** Cooldown (ms) after a compaction completes — any service is suppressed for
+ * this window (dedup gate). Default 90 000 (90 s). */
+ cooldownMs?: number;
+ /** After every N fires, emit REFRESH PROTOCOL instead of /compact. Default 3. */
+ refreshAfterFires?: number;
+}
+
/** Circuit-breaker thresholds (Lane A #6.6b). The breaker runs inside the
* heartbeat beat, so it only ticks when the heartbeat is enabled. Trip
* conditions are behavioral by default; `costCapUsd` is the only $-based one and
@@ -136,6 +151,9 @@ export interface HarnessConfig {
maxTurns?: number;
/** Circuit-breaker thresholds (Lane A #6.6b). Unset = conservative defaults. */
circuitBreaker?: CircuitBreakerConfig;
+ /** COMPACT PROTOCOL (see hive/protocols/COMPACT-PROTOCOL.md). Default off —
+ * requires god + human sign-off before enabling. */
+ compactProtocol?: CompactProtocolConfig;
/** Fire native desktop notifications on agent lifecycle events (idle finish / waiting for input). */
notifications?: boolean;
/** Terminal theme — mirrored into each agent's per-session Claude settings
diff --git a/src/main/hooks.ts b/src/main/hooks.ts
index 4ed79aed..bb4f747d 100644
--- a/src/main/hooks.ts
+++ b/src/main/hooks.ts
@@ -18,6 +18,7 @@ import type { HiveManager } from './hive';
import type { HarnessConfig } from './config';
import type { ControlRegistry } from './control';
import type { CircuitBreaker } from './breaker';
+import { CompactGate, type CompactGateConfig } from './compact';
interface HookPayload {
hook_event_name?: string;
@@ -44,6 +45,9 @@ export class HookServer {
* Lets the harness read per-agent telemetry (e.g. current context size)
* even when several agents share one cwd. */
private transcriptPaths = new Map<string, string>();
+ /** COMPACT PROTOCOL gate — lazily initialised from config when the flag is on.
+ * null when the feature flag is off (zero behavior change). */
+ private compactGate: CompactGate | null = null;
constructor(
private hive: HiveManager,
@@ -118,6 +122,13 @@ export class HookServer {
tokens: cw.total_input_tokens,
limit: cw.context_window_size
});
+ // COMPACT PROTOCOL gate (flag-gated — zero effect when disabled).
+ // Check on every Status tick; the gate deduplicates via pending+cooldown.
+ const pct = cw.total_input_tokens / cw.context_window_size;
+ const action = this.getGate()?.check(agentId, pct);
+ if (action === 'compact' || action === 'refresh') {
+ this.getWebContents()?.send('hive:compactAgent', { agentId, action });
+ }
}
return {};
}
@@ -141,6 +152,9 @@ export class HookServer {
}
if ((event === 'Stop' || event === 'SubagentStop') && agentId) {
+ // Notify the compact gate that the agent has stopped (compact completed or
+ // genuinely idle) — starts the cooldown window so no service double-compacts.
+ this.getGate()?.onCompacted(agentId);
// Loop guard: a previous Stop hook already blocked this turn → let it stop.
if (p.stop_hook_active) { this.emit(agentId, event, p); return {}; }
const drain = this.hive.drainForStop(agentId);
@@ -204,6 +218,16 @@ export class HookServer {
return {};
}
+ /** Return the active CompactGate if the feature flag is on, else null.
+ * Lazily creates the gate on first use; nulls it when the flag turns off.
+ * Reading config per-call is cheap (in-memory read from disk-backed JSON). */
+ private getGate(): CompactGate | null {
+ const cp = this.getConfig().compactProtocol as CompactGateConfig | undefined;
+ if (!cp?.enabled) { this.compactGate = null; return null; }
+ if (!this.compactGate) this.compactGate = new CompactGate(cp);
+ return this.compactGate;
+ }
+
/** Fire a native desktop notification — gated on the user's `notifications`
* setting. Only the OS toast is gated; the hive:hookEvent emit is always sent
* so avatars/UI stay live regardless. Best-effort: never throw into the hook. */
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 4430eda1..94f0d5a2 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -572,6 +572,16 @@ const api = {
ipcRenderer.on('mission:autoCompact', listener);
return () => ipcRenderer.removeListener('mission:autoCompact', listener);
},
+ /** COMPACT PROTOCOL (flag-gated): the main-process gate detected a threshold
+ * crossing for a specific agent. Action is 'compact' (issue /compact) or
+ * 'refresh' (emit REFRESH PROTOCOL message). Only fires when the flag is on. */
+ onCompactAgent: (
+ cb: (e: { agentId: string; action: 'compact' | 'refresh' }) => void
+ ): (() => void) => {
+ const listener = (_e: IpcRendererEvent, payload: { agentId: string; action: 'compact' | 'refresh' }) => cb(payload);
+ ipcRenderer.on('hive:compactAgent', listener);
+ return () => ipcRenderer.removeListener('hive:compactAgent', listener);
+ },
// ─── Full-text search across hive files (board, tasks, memory) ─────────────
textSearch: (q: string): Promise<{ ok: boolean; results: Array<{ source: string; excerpt: string }> }> =>
diff --git a/src/renderer/src/hooks/useHive.ts b/src/renderer/src/hooks/useHive.ts
index cd23f879..90dffbeb 100644
--- a/src/renderer/src/hooks/useHive.ts
+++ b/src/renderer/src/hooks/useHive.ts
@@ -42,6 +42,17 @@ const COMPACT_CMD =
'/compact Summarise exactly what you are currently working on and the next step, ' +
'so you can resume from the same point — then continue that work after compacting.';
+// REFRESH PROTOCOL message — sent after every 3rd COMPACT PROTOCOL fire when
+// compaction is no longer reclaiming enough headroom. Instructs the agent to
+// flush state, checkpoint the task, and start a fresh context session.
+const REFRESH_MSG =
+ 'Context window has grown. Repeated compaction is no longer reclaiming enough headroom ' +
+ 'and performance degradation is likely if you continue. Follow the REFRESH PROTOCOL:\n' +
+ '1. Flush all working state to memory.md (let the miner push it to MemPalace).\n' +
+ '2. Checkpoint the in-flight task in tasks.json + board so nothing is lost.\n' +
+ '3. Start a fresh context (/clear or a new session), then run `mempalace wake-up` ' +
+ 'to rehydrate the durable digest. Resume on a clean slate backed by the palace.';
+
// Per-pty submission chain. Every submitToPty for a given pty is appended here so
// two callers (e.g. the boot sequence's /remote-control and the inbox-wake nudge)
// can NEVER interleave their text + Enter — which jammed them onto one line and
@@ -584,9 +595,13 @@ export function useHive(config: HarnessConfig | null): void {
// /compact for each live agent so the drain (#4) delivers it only when the
// agent is idle — never jamming a working terminal. Deduped: if a /compact
// is already queued for an agent, skip it (no second one piles up).
+ // When the COMPACT PROTOCOL gate is enabled, the gate drives per-agent
+ // compaction via effect #7 below — skip the blanket standup queue to avoid
+ // compact-on-top-of-compact (the gate already deduplicates via cooldown).
useEffect(() => {
if (!config?.onboardingComplete) return;
return window.cth.onAutoCompact(() => {
+ if (config?.compactProtocol?.enabled) return; // gate-driven path handles it
const { agents, messageQueues, enqueueMessage } = useStore.getState();
for (const a of agents) {
if (!a.ptyId) continue;
@@ -598,5 +613,30 @@ export function useHive(config: HarnessConfig | null): void {
enqueueMessage(a.id, COMPACT_CMD);
}
});
+ }, [config?.onboardingComplete, config?.compactProtocol?.enabled]);
+
+ // 7) COMPACT PROTOCOL gate (flag-gated). Main process detected a 50% threshold
+ // crossing for a specific agent and requests either a /compact or a REFRESH.
+ // Only fires when compactProtocol.enabled is true — deduped at the gate level.
+ useEffect(() => {
+ if (!config?.onboardingComplete) return;
+ return window.cth.onCompactAgent?.((e) => {
+ const { agents, messageQueues, enqueueMessage } = useStore.getState();
+ const a = agents.find((x) => x.id === e.agentId);
+ if (!a?.ptyId) return;
+ if (!isClaudeProvider(inferAgentProvider(a.command, a.provider))) return;
+ if (e.action === 'refresh') {
+ // REFRESH PROTOCOL: send the full refresh instructions (not a /compact).
+ // Dedup: skip if a refresh message is already queued.
+ const queued = messageQueues[a.id] ?? [];
+ if (queued.some((m) => m.text.startsWith('Context window has grown'))) return;
+ enqueueMessage(a.id, REFRESH_MSG);
+ } else {
+ // 'compact': enqueue /compact, deduped.
+ const queued = messageQueues[a.id] ?? [];
+ if (queued.some((m) => m.text.trimStart().startsWith('/compact'))) return;
+ enqueueMessage(a.id, COMPACT_CMD);
+ }
+ });
}, [config?.onboardingComplete]);
}
diff --git a/test/compact.test.cjs b/test/compact.test.cjs
new file mode 100644
index 00000000..1acc2782
--- /dev/null
+++ b/test/compact.test.cjs
@@ -0,0 +1,162 @@
+'use strict';
+
+const assert = require('assert');
+const { CompactGate, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES } =
+ require('../src/main/compact-gate.cjs');
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+let failures = 0;
+async function test(name, fn) {
+ try {
+ await fn();
+ console.log(` ✓ ${name}`);
+ } catch (err) {
+ failures++;
+ console.log(` ✗ ${name}\n ${err.message}`);
+ }
+}
+
+(async () => {
+ console.log('compact gate tests (COMPACT PROTOCOL)');
+
+ // ─── Defaults ──────────────────────────────────────────────────────────────
+
+ await test('exported defaults match spec', async () => {
+ assert.strictEqual(DEFAULT_THRESHOLD, 0.50);
+ assert.strictEqual(DEFAULT_COOLDOWN_MS, 90_000);
+ assert.strictEqual(DEFAULT_REFRESH_AFTER_FIRES, 3);
+ });
+
+ // ─── Feature flag ──────────────────────────────────────────────────────────
+
+ await test('disabled gate → always skip regardless of context %', async () => {
+ const g = new CompactGate({ enabled: false });
+ assert.strictEqual(g.check('a', 1.0), 'skip');
+ assert.strictEqual(g.check('a', 0.99), 'skip');
+ });
+
+ // ─── 50% threshold ─────────────────────────────────────────────────────────
+
+ await test('below threshold → skip', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.strictEqual(g.check('a', 0.49), 'skip');
+ });
+
+ await test('exactly at threshold → compact', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.strictEqual(g.check('a', 0.50), 'compact');
+ });
+
+ await test('above threshold → compact', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.strictEqual(g.check('a', 0.80), 'compact');
+ });
+
+ // ─── Single-flight ─────────────────────────────────────────────────────────
+
+ await test('second check while pending → blocked (single-flight)', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.strictEqual(g.check('a', 0.75), 'compact');
+ assert.strictEqual(g.check('a', 0.80), 'blocked');
+ assert.strictEqual(g.check('a', 0.99), 'blocked');
+ });
+
+ await test('different agents are independent (single-flight is per-agent)', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.strictEqual(g.check('a', 0.75), 'compact');
+ assert.strictEqual(g.check('b', 0.75), 'compact'); // 'b' not blocked by 'a'
+ assert.strictEqual(g.check('a', 0.80), 'blocked'); // 'a' still blocked
+ });
+
+ // ─── Dedup cooldown across services ────────────────────────────────────────
+
+ await test('cooldown blocks all services after compacted', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 300 });
+ g.check('a', 0.75); // puts in pending
+ g.onCompacted('a'); // clears pending, starts 300ms cooldown
+ assert.ok(g.isBlocked('a'), 'blocked immediately after compacted');
+ assert.strictEqual(g.check('a', 0.75), 'blocked', 'check returns blocked during cooldown');
+ });
+
+ await test('cooldown expires → not blocked', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 100 });
+ g.check('a', 0.75);
+ g.onCompacted('a');
+ await sleep(150);
+ assert.ok(!g.isBlocked('a'), 'not blocked after cooldown expires');
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'can compact again after cooldown');
+ });
+
+ await test('isBlocked returns false when not pending and no cooldown', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50 });
+ assert.ok(!g.isBlocked('a'));
+ });
+
+ // ─── 3-fire → REFRESH escalation ───────────────────────────────────────────
+
+ await test('fires 1 and 2 produce compact, fire 3 produces refresh', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 2');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 → REFRESH');
+ });
+
+ await test('counter continues after refresh: fires 4,5 compact, fire 6 refresh', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });
+ // fires 1–3
+ g.check('a', 0.75); g.onCompacted('a');
+ g.check('a', 0.75); g.onCompacted('a');
+ g.check('a', 0.75); g.onCompacted('a'); // fire 3 = refresh
+ // fires 4–6
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 4');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 5');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 6 → REFRESH');
+ });
+
+ // ─── Counter reset on context drop ─────────────────────────────────────────
+
+ await test('context drops to threshold/2 → fire counter resets', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });
+ // Two fires (fires 1 and 2 — next would be refresh on 3)
+ g.check('a', 0.75); g.onCompacted('a');
+ g.check('a', 0.75); g.onCompacted('a');
+ // Context drops well below threshold (< 0.25)
+ g.check('a', 0.20); // should reset counter and return 'skip'
+ // Now the counter is reset — next three fires should be 1,2,compact then 3=refresh
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1 after reset');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 2 after reset');
+ g.onCompacted('a');
+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 after reset → REFRESH');
+ });
+
+ await test('context between threshold/2 and threshold → no counter reset', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });
+ g.check('a', 0.75); g.onCompacted('a'); // fire 1
+ g.check('a', 0.75); g.onCompacted('a'); // fire 2
+ // Context drops to 30% — above threshold/2 (25%) so no reset
+ g.check('a', 0.30); // skip, but no reset
+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 without reset → REFRESH');
+ });
+
+ // ─── remove() cleans up all state ──────────────────────────────────────────
+
+ await test('remove clears pending, cooldown, and fire count', async () => {
+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 10_000, refreshAfterFires: 3 });
+ g.check('a', 0.75); // pending + fire 1
+ g.onCompacted('a'); // cooldown active
+ g.remove('a');
+ assert.ok(!g.isBlocked('a'), 'not blocked after remove');
+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1 again (counter reset by remove)');
+ });
+
+ // ─── Summary ───────────────────────────────────────────────────────────────
+
+ console.log(failures === 0 ? '\nall passed' : `\n${failures} failure(s)`);
+ process.exit(failures === 0 ? 0 : 1);
+})();