@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/__tests__/local-parse.test.js

@@ -0,0 +1,199 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { detectLanguage, entityKey, extractEntities, } from "../intelligence/ast-extractor.js";
+describe("Local Parse — TypeScript AST Extraction (P5.6-ADV-01)", () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = path.join(os.tmpdir(), `unerr-local-parse-${Date.now()}`);
+        fs.mkdirSync(tmpDir, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("extracts entities from TypeScript files matching expected output format", () => {
+        const content = [
+            "export function main(): void {",
+            "  console.log('hello')",
+            "}",
+            "",
+            "export interface Config {",
+            "  port: number",
+            "  host: string",
+            "}",
+            "",
+            "export class Server {",
+            "  start() {",
+            "    return true",
+            "  }",
+            "}",
+        ].join("\n");
+        const entities = extractEntities(content, "src/index.ts");
+        expect(entities.length).toBeGreaterThanOrEqual(3);
+        const funcEntity = entities.find((e) => e.name === "main");
+        expect(funcEntity).toBeDefined();
+        expect(funcEntity?.kind).toBe("function");
+        expect(funcEntity?.line_start).toBe(1);
+        const ifaceEntity = entities.find((e) => e.name === "Config");
+        expect(ifaceEntity).toBeDefined();
+        expect(ifaceEntity?.kind).toBe("interface");
+        const classEntity = entities.find((e) => e.name === "Server");
+        expect(classEntity).toBeDefined();
+        expect(classEntity?.kind).toBe("class");
+    });
+    it("entity keys match entityHash algorithm", () => {
+        // entityKey(repoId, filePath, kind, name, signature?)
+        // SHA-256 of null-byte-separated string, first 16 hex chars
+        const key1 = entityKey("repo-1", "src/auth.ts", "function", "login", "(user: string)");
+        const key2 = entityKey("repo-1", "src/auth.ts", "function", "login", "(user: string)");
+        // Deterministic
+        expect(key1).toBe(key2);
+        // 16 hex chars
+        expect(key1).toMatch(/^[0-9a-f]{16}$/);
+        // Different inputs → different keys
+        const key3 = entityKey("repo-1", "src/auth.ts", "function", "logout", "()");
+        expect(key3).not.toBe(key1);
+    });
+    it("extracts entities from Python files", () => {
+        const content = [
+            "class AuthService:",
+            "    def __init__(self):",
+            "        self.token = None",
+            "",
+            "    async def login(self, user: str) -> bool:",
+            "        return True",
+            "",
+            "def main():",
+            "    svc = AuthService()",
+        ].join("\n");
+        const entities = extractEntities(content, "src/auth.py");
+        const cls = entities.find((e) => e.name === "AuthService");
+        expect(cls).toBeDefined();
+        expect(cls?.kind).toBe("class");
+        const initFn = entities.find((e) => e.name === "__init__");
+        expect(initFn).toBeDefined();
+        expect(initFn?.kind).toBe("function");
+        const mainFn = entities.find((e) => e.name === "main");
+        expect(mainFn).toBeDefined();
+    });
+    it("extracts entities from Go files", () => {
+        const content = [
+            "package main",
+            "",
+            "type Server struct {",
+            "  port int",
+            "}",
+            "",
+            "func (s *Server) Start() error {",
+            "  return nil",
+            "}",
+            "",
+            "func main() {",
+            "  s := &Server{port: 8080}",
+            "  s.Start()",
+            "}",
+        ].join("\n");
+        const entities = extractEntities(content, "main.go");
+        const structEntity = entities.find((e) => e.name === "Server");
+        expect(structEntity).toBeDefined();
+        expect(structEntity?.kind).toBe("class");
+        const methodEntity = entities.find((e) => e.name === "Server.Start");
+        expect(methodEntity).toBeDefined();
+        expect(methodEntity?.kind).toBe("method");
+        expect(methodEntity?.parent_class).toBe("Server");
+        const mainFn = entities.find((e) => e.name === "main");
+        expect(mainFn).toBeDefined();
+    });
+    it("detects language from file extension", () => {
+        expect(detectLanguage("src/index.ts")).toBe("typescript");
+        expect(detectLanguage("src/app.tsx")).toBe("typescript");
+        expect(detectLanguage("src/main.py")).toBe("python");
+        expect(detectLanguage("main.go")).toBe("go");
+        expect(detectLanguage("Main.java")).toBe("java");
+        expect(detectLanguage("lib.rs")).toBe("rust");
+        expect(detectLanguage("main.c")).toBe("c");
+        expect(detectLanguage("main.cpp")).toBe("cpp");
+        expect(detectLanguage("README.md")).toBeNull();
+        expect(detectLanguage("Makefile")).toBeNull();
+    });
+    it("returns empty array for unsupported file types", () => {
+        const entities = extractEntities("# Heading\nSome markdown", "README.md");
+        expect(entities).toEqual([]);
+    });
+    it("each entity includes content_hash for dedup", () => {
+        const content = "export function hello(): string {\n  return 'world'\n}\n";
+        const entities = extractEntities(content, "src/hello.ts");
+        expect(entities.length).toBe(1);
+        expect(entities[0]?.content_hash).toMatch(/^[0-9a-f]{16}$/);
+        // Same content → same hash
+        const entities2 = extractEntities(content, "src/hello.ts");
+        expect(entities2[0]?.content_hash).toBe(entities[0]?.content_hash);
+        // Different content → different hash
+        const modified = "export function hello(): string {\n  return 'changed'\n}\n";
+        const entities3 = extractEntities(modified, "src/hello.ts");
+        expect(entities3[0]?.content_hash).not.toBe(entities[0]?.content_hash);
+    });
+    it("handles large files without hanging", () => {
+        // Generate 10K lines
+        const lines = [];
+        for (let i = 0; i < 10000; i++) {
+            if (i % 100 === 0) {
+                lines.push(`export function func_${i}(): void {`);
+                lines.push(`  console.log(${i})`);
+                lines.push("}");
+            }
+            else {
+                lines.push(`// line ${i}`);
+            }
+        }
+        const content = lines.join("\n");
+        const start = Date.now();
+        const entities = extractEntities(content, "src/big.ts");
+        const elapsed = Date.now() - start;
+        expect(entities.length).toBe(100); // 10000/100 functions
+        expect(elapsed).toBeLessThan(5000); // Should complete in <5s
+    });
+    it("builds graph-upload payload from extracted entities", () => {
+        // Simulate what push.ts --local-parse does
+        const repoId = "repo-123";
+        const filePath = "src/auth.ts";
+        const content = [
+            "export class AuthService {",
+            "  login(user: string): boolean {",
+            "    return true",
+            "  }",
+            "}",
+        ].join("\n");
+        const extracted = extractEntities(content, filePath);
+        // Build EntityDoc-compatible objects
+        const entities = extracted.map((e) => ({
+            id: entityKey(repoId, filePath, e.kind, e.name, e.signature),
+            kind: e.kind,
+            name: e.name,
+            file_path: filePath,
+            start_line: e.line_start,
+            end_line: e.line_end,
+            signature: e.signature || undefined,
+        }));
+        // Validate shapes match graph-upload requirements
+        for (const entity of entities) {
+            expect(entity.id).toMatch(/^[0-9a-f]{16}$/);
+            expect(entity.kind).toBeTruthy();
+            expect(entity.name).toBeTruthy();
+            expect(entity.file_path).toBe(filePath);
+        }
+        // Build edges
+        const fileId = entityKey(repoId, filePath, "file", filePath);
+        const edges = entities.map((e) => ({
+            _from: `files/${fileId}`,
+            _to: `${e.kind === "class" ? "classes" : "functions"}/${e.id}`,
+            kind: "contains",
+        }));
+        expect(edges.length).toBe(entities.length);
+        for (const edge of edges) {
+            expect(edge._from).toContain("files/");
+            expect(edge.kind).toBe("contains");
+        }
+    });
+});

package/dist/__tests__/log-tailer.test.js

@@ -0,0 +1,208 @@
+import { appendFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; // appendFileSync + writeFileSync still used for unerr.jsonl JSONL tests
+import os from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { closeMetricsStore, openMetricsStore, } from "../tracking/metrics-store.js";
+import { startupLog } from "../utils/startup-log.js";
+// Mock startupLog to capture output
+vi.mock("../utils/startup-log.js", () => {
+    const calls = [];
+    return {
+        startupLog: {
+            step: (...args) => calls.push({ method: "step", args }),
+            done: (...args) => calls.push({ method: "done", args }),
+            warn: (...args) => calls.push({ method: "warn", args }),
+            error: (...args) => calls.push({ method: "error", args }),
+            tokenFlow: (...args) => calls.push({ method: "tokenFlow", args }),
+            fmt: {
+                muted: (s) => s,
+                dim: (s) => s,
+                cyan: (s) => s,
+                bold: (s) => s,
+            },
+            _calls: calls,
+            _reset: () => {
+                calls.length = 0;
+            },
+        },
+    };
+});
+function getCalls() {
+    return startupLog._calls;
+}
+function resetCalls() {
+    startupLog._reset();
+}
+describe("log-tailer", () => {
+    let tmpDir;
+    let unerrDir;
+    let logsDir;
+    beforeEach(() => {
+        tmpDir = join(os.tmpdir(), `unerr-tailer-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        unerrDir = join(tmpDir, ".unerr");
+        logsDir = join(unerrDir, "logs");
+        mkdirSync(logsDir, { recursive: true });
+        resetCalls();
+    });
+    afterEach(() => {
+        closeMetricsStore(unerrDir);
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("startLogTailer returns a handle with close()", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir);
+        expect(handle).toBeDefined();
+        expect(typeof handle.close).toBe("function");
+        handle.close();
+    });
+    it("polls compression rows from metrics.db", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir, { pollIntervalMs: 50 });
+        // Insert after the tailer has captured its initial lastIds.
+        openMetricsStore(unerrDir).insertCompression({
+            ts: Date.now(),
+            ts_iso: new Date().toISOString(),
+            command: "ps aux",
+            category: "tabular",
+            confidence: 0.85,
+            raw_bytes: 1000,
+            compressed_bytes: 300,
+            saved_pct: 70,
+            omni_fallback: 0,
+            tee_file: null,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const calls = getCalls();
+        const compressionCall = calls.find((c) => c.method === "step" && String(c.args[0]).includes("ps aux"));
+        expect(compressionCall).toBeDefined();
+        handle.close();
+    });
+    it("polls token-flow rows and filters own-PID", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir, { pollIntervalMs: 50 });
+        const store = openMetricsStore(unerrDir);
+        const ts = Date.now();
+        // Own PID — should be filtered out by printTokenFlowEntry
+        store.insertTokenFlow({
+            ts,
+            ts_iso: new Date(ts).toISOString(),
+            session_id: "s1",
+            pid: process.pid,
+            turn: 1,
+            mechanism: "graph_query",
+            tool: "get_callers",
+            tokens_without: 150,
+            tokens_with: 50,
+            tokens_saved: 100,
+            detail: null,
+        });
+        // Other PID — should be relayed
+        store.insertTokenFlow({
+            ts: ts + 1,
+            ts_iso: new Date(ts + 1).toISOString(),
+            session_id: "s1",
+            pid: process.pid + 999,
+            turn: 3,
+            mechanism: "shell_compression",
+            tool: "bash",
+            tokens_without: 500,
+            tokens_with: 150,
+            tokens_saved: 350,
+            detail: null,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const calls = getCalls();
+        const tfCalls = calls.filter((c) => c.method === "tokenFlow");
+        expect(tfCalls.length).toBe(1);
+        const tfCall = tfCalls[0].args[0];
+        expect(tfCall.mechanism).toBe("shell_compression");
+        expect(tfCall.tokensSaved).toBe(350);
+        handle.close();
+    });
+    it("filters own-PID entries from unerr.jsonl", async () => {
+        const generalPath = join(logsDir, "unerr.jsonl");
+        writeFileSync(generalPath, "");
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir);
+        const ownEntry = JSON.stringify({
+            pid: process.pid,
+            level: "warn",
+            msg: "own-warning",
+        });
+        const otherEntry = JSON.stringify({
+            pid: process.pid + 1,
+            level: "warn",
+            msg: "other-warning",
+        });
+        appendFileSync(generalPath, `${ownEntry}\n${otherEntry}\n`);
+        await new Promise((resolve) => setTimeout(resolve, 3500));
+        const calls = getCalls();
+        const warnCalls = calls.filter((c) => c.method === "warn");
+        expect(warnCalls.find((c) => String(c.args[0]).includes("own-warning"))).toBeUndefined();
+        expect(warnCalls.find((c) => String(c.args[0]).includes("other-warning"))).toBeDefined();
+        handle.close();
+    });
+    it("polls file-read rows for events with savings", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir, { pollIntervalMs: 50 });
+        openMetricsStore(unerrDir).insertFileRead({
+            ts: Date.now(),
+            ts_iso: new Date().toISOString(),
+            file: "src/proxy/proxy.ts",
+            mode: "entity",
+            total_lines: 2000,
+            returned_lines: 45,
+            saved_pct: 98,
+            entity: null,
+            token_estimate: null,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const calls = getCalls();
+        const fileReadCall = calls.find((c) => c.method === "step" &&
+            String(c.args[0]).includes("proxy.ts") &&
+            String(c.args[0]).includes("entity"));
+        expect(fileReadCall).toBeDefined();
+        handle.close();
+    });
+    it("skips file-read entries with 0% savings", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir, { pollIntervalMs: 50 });
+        openMetricsStore(unerrDir).insertFileRead({
+            ts: Date.now(),
+            ts_iso: new Date().toISOString(),
+            file: "readme.md",
+            mode: "full",
+            total_lines: 20,
+            returned_lines: 20,
+            saved_pct: 0,
+            entity: null,
+            token_estimate: null,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const calls = getCalls();
+        const fileReadCall = calls.find((c) => c.method === "step" && String(c.args[0]).includes("readme.md"));
+        expect(fileReadCall).toBeUndefined();
+        handle.close();
+    });
+    it("skips compression entries with 0% savings", async () => {
+        const { startLogTailer } = await import("../proxy/log-tailer.js");
+        const handle = startLogTailer(tmpDir, { pollIntervalMs: 50 });
+        openMetricsStore(unerrDir).insertCompression({
+            ts: Date.now(),
+            ts_iso: new Date().toISOString(),
+            command: "echo hello",
+            category: "omni",
+            confidence: 1,
+            raw_bytes: 12,
+            compressed_bytes: 12,
+            saved_pct: 0,
+            omni_fallback: 0,
+            tee_file: null,
+        });
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        const calls = getCalls();
+        const echoCall = calls.find((c) => c.method === "step" && String(c.args[0]).includes("echo hello"));
+        expect(echoCall).toBeUndefined();
+        handle.close();
+    });
+});

package/dist/__tests__/loop-breaker.test.js

@@ -0,0 +1,276 @@
+/**
+ * BA-1.6: Loop Circuit Breaker tests.
+ *
+ * Verifies:
+ *   - 3 stuck patterns detected (repetitive_failure, context_poisoning, over_planning)
+ *   - Circuit breaker state transitions (closed → open → half_open → closed)
+ *   - Dollar calculation correctness
+ *   - TDD exemption (test files excluded from entity-retry count)
+ *   - $0.50 gate enforcement
+ */
+import { describe, expect, it } from "vitest";
+import { LoopCircuitBreaker } from "../behaviors/loop-breaker.js";
+function makeCtx(overrides = {}) {
+    return {
+        toolName: "edit_file",
+        args: { path: "src/payment.ts", content: "fix" },
+        sessionId: "test-session",
+        entityKey: "src/payment.ts::processPayment",
+        filePath: "src/payment.ts",
+        ...overrides,
+    };
+}
+function makeErrorResult() {
+    return {
+        error: true,
+        content: [{ type: "text", text: "TypeError: Cannot read property" }],
+    };
+}
+function makeSuccessResult() {
+    return {
+        content: [{ type: "text", text: "File updated successfully" }],
+    };
+}
+describe("Loop Circuit Breaker (BA-1.1)", () => {
+    describe("Pattern Detection", () => {
+        it("detects repetitive failure after 4 consecutive errors on same entity", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 3; i++) {
+                const ctx = makeCtx({
+                    result: { error: true, content: `TypeError on line ${45 + i}` },
+                    args: { path: "src/payment.ts", content: "retry logic v1" },
+                });
+                const output = await breaker.onPostToolUse(ctx);
+                expect(output).toBeNull();
+            }
+            const finalCtx = makeCtx({
+                result: { error: true, content: "TypeError on line 48" },
+                args: { path: "src/payment.ts", content: "retry logic v1" },
+            });
+            const output = await breaker.onPostToolUse(finalCtx);
+            expect(output).not.toBeNull();
+            expect(output?.halt).toBe(true);
+            expect(output?._context?.pattern).toBe("repetitive_failure");
+            expect(output?._context?.reason).toContain("4 consecutive failed attempts");
+        });
+        it("detects context poisoning when all results are identical", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            const identicalResult = {
+                error: true,
+                content: [{ type: "text", text: "The exact same error every time" }],
+            };
+            for (let i = 0; i < 4; i++) {
+                const ctx = makeCtx({
+                    result: identicalResult,
+                    args: {
+                        path: "src/payment.ts",
+                        content: `completely_different_approach_${i * 100}`,
+                    },
+                });
+                const output = await breaker.onPostToolUse(ctx);
+                if (i < 3) {
+                    expect(output).toBeNull();
+                }
+                else {
+                    expect(output).not.toBeNull();
+                    expect(output?._context?.pattern).toBe("context_poisoning");
+                }
+            }
+        });
+        it("detects over-planning when attempts are spaced far apart", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            const now = Date.now();
+            for (let i = 0; i < 4; i++) {
+                const ctx = makeCtx({
+                    result: makeErrorResult(),
+                    args: {
+                        path: "src/payment.ts",
+                        action: `action_${i}`,
+                        variation: `v${i * 50}`,
+                    },
+                });
+                const originalDateNow = Date.now;
+                Date.now = () => now + i * 20_000;
+                try {
+                    await breaker.onPostToolUse(ctx);
+                }
+                finally {
+                    Date.now = originalDateNow;
+                }
+            }
+            const stats = breaker.getSessionStats();
+            expect(stats.loopsPrevented).toBeGreaterThanOrEqual(1);
+        });
+    });
+    describe("Circuit Breaker States", () => {
+        it("transitions from CLOSED to OPEN on loop detection", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            expect(breaker.getCircuitState("src/payment.ts::processPayment")).toBeNull();
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            expect(breaker.getCircuitState("src/payment.ts::processPayment")).toBe("open");
+        });
+        it("blocks further attempts while circuit is OPEN", async () => {
+            const breaker = new LoopCircuitBreaker({
+                maxAttemptsPerEntity: 4,
+                cooldownMs: 60_000,
+            });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            const preResult = await breaker.onPreToolUse(makeCtx());
+            expect(preResult).not.toBeNull();
+            expect(preResult?.halt).toBe(true);
+            expect(preResult?._context?.cooldown_remaining_s).toBeGreaterThan(0);
+        });
+        it("transitions to HALF_OPEN after cooldown expires", async () => {
+            const breaker = new LoopCircuitBreaker({
+                maxAttemptsPerEntity: 4,
+                cooldownMs: 100,
+            });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            await new Promise((r) => setTimeout(r, 150));
+            const preResult = await breaker.onPreToolUse(makeCtx());
+            expect(preResult).toBeNull();
+        });
+        it("returns to CLOSED from HALF_OPEN on success", async () => {
+            const breaker = new LoopCircuitBreaker({
+                maxAttemptsPerEntity: 4,
+                cooldownMs: 100,
+            });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            await new Promise((r) => setTimeout(r, 150));
+            await breaker.onPreToolUse(makeCtx());
+            await breaker.onPostToolUse(makeCtx({ result: makeSuccessResult() }));
+            expect(breaker.getCircuitState("src/payment.ts::processPayment")).toBe("closed");
+        });
+        it("returns to OPEN from HALF_OPEN on failure", async () => {
+            const breaker = new LoopCircuitBreaker({
+                maxAttemptsPerEntity: 4,
+                cooldownMs: 100,
+            });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            await new Promise((r) => setTimeout(r, 150));
+            await breaker.onPreToolUse(makeCtx());
+            await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            expect(breaker.getCircuitState("src/payment.ts::processPayment")).toBe("open");
+        });
+    });
+    describe("TDD Exemption", () => {
+        it("does NOT flag test file modifications as loop attempts", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 6; i++) {
+                const ctx = makeCtx({
+                    filePath: "src/__tests__/payment.test.ts",
+                    entityKey: "src/__tests__/payment.test.ts::testProcessPayment",
+                    result: makeErrorResult(),
+                });
+                const output = await breaker.onPostToolUse(ctx);
+                expect(output).toBeNull();
+            }
+        });
+        it("exempts .spec.ts files", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 6; i++) {
+                const ctx = makeCtx({
+                    filePath: "src/payment.spec.ts",
+                    entityKey: "src/payment.spec.ts::specProcessPayment",
+                    result: makeErrorResult(),
+                });
+                expect(await breaker.onPostToolUse(ctx)).toBeNull();
+            }
+        });
+    });
+    describe("Dollar Calculation", () => {
+        it("includes dollar amount in guard moment output", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            let lastOutput = null;
+            for (let i = 0; i < 4; i++) {
+                lastOutput = await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            expect(lastOutput).not.toBeNull();
+            expect(lastOutput?._meta?.dollars_saved).toBeDefined();
+            expect(lastOutput?._meta?.tokens_saved).toBeGreaterThan(0);
+        });
+        it("accumulates savings across multiple loops", async () => {
+            const breaker = new LoopCircuitBreaker({
+                maxAttemptsPerEntity: 4,
+                cooldownMs: 50,
+            });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            const stats1 = breaker.getSessionStats();
+            expect(stats1.loopsPrevented).toBe(1);
+            expect(stats1.totalTokensSaved).toBeGreaterThan(0);
+            await new Promise((r) => setTimeout(r, 100));
+            await breaker.onPreToolUse(makeCtx({ entityKey: "src/checkout.ts::handleOrder" }));
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({
+                    entityKey: "src/checkout.ts::handleOrder",
+                    filePath: "src/checkout.ts",
+                    result: makeErrorResult(),
+                }));
+            }
+            const stats2 = breaker.getSessionStats();
+            expect(stats2.loopsPrevented).toBe(2);
+            expect(stats2.totalTokensSaved).toBeGreaterThan(stats1.totalTokensSaved);
+        });
+    });
+    describe("$0.50 Gate", () => {
+        it("only fires guard when estimated savings exceed $0.50", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            let guardFired = false;
+            for (let i = 0; i < 4; i++) {
+                const output = await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+                if (output?.guardMoment)
+                    guardFired = true;
+            }
+            expect(guardFired).toBe(true);
+        });
+    });
+    describe("Session Stats", () => {
+        it("tracks active and open circuits", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 4; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            const stats = breaker.getSessionStats();
+            expect(stats.activeCircuits).toBe(1);
+            expect(stats.openCircuits).toBe(1);
+            expect(stats.loopsPrevented).toBe(1);
+        });
+    });
+    describe("Edge Cases", () => {
+        it("does nothing without entityKey", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            const ctx = makeCtx({ entityKey: undefined, result: makeErrorResult() });
+            expect(await breaker.onPostToolUse(ctx)).toBeNull();
+        });
+        it("handles success results correctly (no false positive)", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 6; i++) {
+                const output = await breaker.onPostToolUse(makeCtx({ result: makeSuccessResult() }));
+                expect(output).toBeNull();
+            }
+        });
+        it("resets failure count on success between errors", async () => {
+            const breaker = new LoopCircuitBreaker({ maxAttemptsPerEntity: 4 });
+            for (let i = 0; i < 3; i++) {
+                await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+            }
+            await breaker.onPostToolUse(makeCtx({ result: makeSuccessResult() }));
+            for (let i = 0; i < 3; i++) {
+                const output = await breaker.onPostToolUse(makeCtx({ result: makeErrorResult() }));
+                expect(output).toBeNull();
+            }
+        });
+    });
+});