@nathapp/nax 0.18.1

package/test/unit/cost.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import {
+  COST_RATES,
+  estimateCost,
+  estimateCostByDuration,
+  estimateCostFromOutput,
+  formatCostWithConfidence,
+  parseTokenUsage,
+} from "../../src/agents/cost";
+
+describe("parseTokenUsage", () => {
+  test("parses Claude Code token output with estimated confidence", () => {
+    const output = `
+Agent completed successfully.
+Input tokens: 12345
+Output tokens: 6789
+Total tokens: 19134
+    `;
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(12345);
+    expect(usage?.outputTokens).toBe(6789);
+    expect(usage?.confidence).toBe("estimated");
+  });
+
+  test("handles case-insensitive matches with estimated confidence", () => {
+    const output = "INPUT TOKENS: 1000\nOUTPUT TOKENS: 2000";
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(1000);
+    expect(usage?.outputTokens).toBe(2000);
+    expect(usage?.confidence).toBe("estimated");
+  });
+
+  test("returns null when tokens not found", () => {
+    const output = "Agent completed successfully.";
+    expect(parseTokenUsage(output)).toBeNull();
+  });
+
+  test("returns null when only partial token info", () => {
+    const output = "Input tokens: 1000";
+    expect(parseTokenUsage(output)).toBeNull();
+  });
+
+  test("parses JSON-structured token report with exact confidence (BUG-3)", () => {
+    const output = `{"usage": {"input_tokens": 15000, "output_tokens": 8500}}`;
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(15000);
+    expect(usage?.outputTokens).toBe(8500);
+    expect(usage?.confidence).toBe("exact");
+  });
+
+  test("parses JSON with surrounding text with exact confidence (BUG-3)", () => {
+    const output = `
+Agent completed.
+{"usage": {"input_tokens": 12000, "output_tokens": 4000}}
+Done.
+    `;
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(12000);
+    expect(usage?.outputTokens).toBe(4000);
+    expect(usage?.confidence).toBe("exact");
+  });
+
+  test("parses underscore format with estimated confidence (BUG-3)", () => {
+    const output = "input_tokens: 9000\noutput_tokens: 3000";
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(9000);
+    expect(usage?.outputTokens).toBe(3000);
+    expect(usage?.confidence).toBe("estimated");
+  });
+
+  test("rejects unreasonably large token counts (BUG-3 sanity check)", () => {
+    const output = "Input tokens: 5000000\nOutput tokens: 2000000";
+    // Should reject tokens > 1M as likely false positive
+    expect(parseTokenUsage(output)).toBeNull();
+  });
+
+  test("requires at least 2 digits to avoid false positives (BUG-3)", () => {
+    const output = "version: 1\ninput: 5\noutput: 8";
+    // Should not match single-digit numbers
+    expect(parseTokenUsage(output)).toBeNull();
+  });
+
+  test("handles mixed format with word boundaries and estimated confidence (BUG-3)", () => {
+    const output = `
+Model: claude-sonnet-4-5
+input tokens: 15432
+output tokens: 7891
+Status: success
+    `;
+    const usage = parseTokenUsage(output);
+    expect(usage).not.toBeNull();
+    expect(usage?.inputTokens).toBe(15432);
+    expect(usage?.outputTokens).toBe(7891);
+    expect(usage?.confidence).toBe("estimated");
+  });
+});
+
+describe("estimateCost", () => {
+  test("calculates cost for fast tier (Haiku)", () => {
+    const cost = estimateCost("fast", 1_000_000, 1_000_000);
+    // $0.80 input + $4.00 output = $4.80
+    expect(cost).toBeCloseTo(4.8, 2);
+  });
+
+  test("calculates cost for balanced tier (Sonnet)", () => {
+    const cost = estimateCost("balanced", 1_000_000, 1_000_000);
+    // $3.00 input + $15.00 output = $18.00
+    expect(cost).toBeCloseTo(18.0, 2);
+  });
+
+  test("calculates cost for powerful tier (Opus)", () => {
+    const cost = estimateCost("powerful", 1_000_000, 1_000_000);
+    // $15.00 input + $75.00 output = $90.00
+    expect(cost).toBeCloseTo(90.0, 2);
+  });
+
+  test("handles small token counts", () => {
+    const cost = estimateCost("fast", 10_000, 5_000);
+    // (10k/1M * 0.80) + (5k/1M * 4.00) = 0.008 + 0.020 = 0.028
+    expect(cost).toBeCloseTo(0.028, 3);
+  });
+
+  test("handles zero tokens", () => {
+    const cost = estimateCost("balanced", 0, 0);
+    expect(cost).toBe(0);
+  });
+});
+
+describe("estimateCostFromOutput", () => {
+  test("estimates cost from parsed output with confidence", () => {
+    const output = "Input tokens: 100000\nOutput tokens: 50000";
+    const estimate = estimateCostFromOutput("fast", output);
+    // (100k/1M * 0.80) + (50k/1M * 4.00) = 0.08 + 0.20 = 0.28
+    expect(estimate).not.toBeNull();
+    expect(estimate?.cost).toBeCloseTo(0.28, 2);
+    expect(estimate?.confidence).toBe("estimated");
+  });
+
+  test("returns exact confidence for JSON output", () => {
+    const output = '{"usage": {"input_tokens": 100000, "output_tokens": 50000}}';
+    const estimate = estimateCostFromOutput("fast", output);
+    expect(estimate).not.toBeNull();
+    expect(estimate?.cost).toBeCloseTo(0.28, 2);
+    expect(estimate?.confidence).toBe("exact");
+  });
+
+  test("returns null when tokens cannot be parsed", () => {
+    const output = "Agent completed successfully.";
+    const estimate = estimateCostFromOutput("balanced", output);
+    expect(estimate).toBeNull();
+  });
+});
+
+describe("estimateCostByDuration", () => {
+  test("estimates cost for 1 minute fast tier with fallback confidence", () => {
+    const estimate = estimateCostByDuration("fast", 60000);
+    expect(estimate.cost).toBeCloseTo(0.01, 2);
+    expect(estimate.confidence).toBe("fallback");
+  });
+
+  test("estimates cost for 2 minutes balanced tier with fallback confidence", () => {
+    const estimate = estimateCostByDuration("balanced", 120000);
+    expect(estimate.cost).toBeCloseTo(0.1, 2);
+    expect(estimate.confidence).toBe("fallback");
+  });
+
+  test("estimates cost for 30 seconds powerful tier with fallback confidence", () => {
+    const estimate = estimateCostByDuration("powerful", 30000);
+    expect(estimate.cost).toBeCloseTo(0.075, 3);
+    expect(estimate.confidence).toBe("fallback");
+  });
+
+  test("handles zero duration with fallback confidence", () => {
+    const estimate = estimateCostByDuration("balanced", 0);
+    expect(estimate.cost).toBe(0);
+    expect(estimate.confidence).toBe("fallback");
+  });
+});
+
+describe("formatCostWithConfidence", () => {
+  test("formats exact confidence without prefix", () => {
+    const estimate = { cost: 0.12, confidence: "exact" as const };
+    expect(formatCostWithConfidence(estimate)).toBe("$0.12");
+  });
+
+  test("formats estimated confidence with tilde prefix", () => {
+    const estimate = { cost: 0.15, confidence: "estimated" as const };
+    expect(formatCostWithConfidence(estimate)).toBe("~$0.15");
+  });
+
+  test("formats fallback confidence with tilde and label", () => {
+    const estimate = { cost: 0.05, confidence: "fallback" as const };
+    expect(formatCostWithConfidence(estimate)).toBe("~$0.05 (duration-based)");
+  });
+
+  test("formats very small costs correctly", () => {
+    const estimate = { cost: 0.001, confidence: "exact" as const };
+    expect(formatCostWithConfidence(estimate)).toBe("$0.00");
+  });
+
+  test("formats large costs correctly", () => {
+    const estimate = { cost: 12.345, confidence: "estimated" as const };
+    expect(formatCostWithConfidence(estimate)).toBe("~$12.35");
+  });
+});
+
+describe("COST_RATES", () => {
+  test("has rates for all model tiers", () => {
+    expect(COST_RATES.fast).toBeDefined();
+    expect(COST_RATES.balanced).toBeDefined();
+    expect(COST_RATES.powerful).toBeDefined();
+  });
+
+  test("rates are positive numbers", () => {
+    for (const tier of ["fast", "balanced", "powerful"] as const) {
+      expect(COST_RATES[tier].inputPer1M).toBeGreaterThan(0);
+      expect(COST_RATES[tier].outputPer1M).toBeGreaterThan(0);
+    }
+  });
+
+  test("output costs are higher than input costs", () => {
+    for (const tier of ["fast", "balanced", "powerful"] as const) {
+      expect(COST_RATES[tier].outputPer1M).toBeGreaterThan(COST_RATES[tier].inputPer1M);
+    }
+  });
+});

package/test/unit/crash-recovery.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Unit tests for crash recovery module (US-007)
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "../../src/config";
+import {
+  type CrashRecoveryContext,
+  installCrashHandlers,
+  resetCrashHandlers,
+  startHeartbeat,
+  stopHeartbeat,
+  writeExitSummary,
+} from "../../src/execution/crash-recovery";
+import { StatusWriter } from "../../src/execution/status-writer";
+
+const TEST_DIR = join(import.meta.dir, "..", ".tmp-crash-recovery");
+const TEST_JSONL = join(TEST_DIR, "test.jsonl");
+const TEST_STATUS_FILE = join(TEST_DIR, "status.json");
+
+beforeEach(() => {
+  // Create test directory
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+  mkdirSync(TEST_DIR, { recursive: true });
+
+  // Reset crash handlers before each test
+  resetCrashHandlers();
+});
+
+afterEach(() => {
+  // Reset crash handlers after each test
+  resetCrashHandlers();
+
+  // Clean up test directory
+  if (existsSync(TEST_DIR)) {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  }
+});
+
+describe("crash-recovery", () => {
+  describe("installCrashHandlers", () => {
+    test("should install handlers without throwing", () => {
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "test-run",
+        feature: "test-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      const ctx: CrashRecoveryContext = {
+        statusWriter,
+        getTotalCost: () => 0,
+        getIterations: () => 0,
+        jsonlFilePath: TEST_JSONL,
+      };
+
+      expect(() => installCrashHandlers(ctx)).not.toThrow();
+    });
+
+    test("should not throw when called multiple times", () => {
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "test-run",
+        feature: "test-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      const ctx: CrashRecoveryContext = {
+        statusWriter,
+        getTotalCost: () => 0,
+        getIterations: () => 0,
+        jsonlFilePath: TEST_JSONL,
+      };
+
+      installCrashHandlers(ctx);
+      expect(() => installCrashHandlers(ctx)).not.toThrow();
+    });
+  });
+
+  describe("heartbeat", () => {
+    test("should start and stop heartbeat without throwing", () => {
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "test-run",
+        feature: "test-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      const totalCost = 0;
+      const iterations = 0;
+
+      expect(() =>
+        startHeartbeat(
+          statusWriter,
+          () => totalCost,
+          () => iterations,
+          TEST_JSONL,
+        ),
+      ).not.toThrow();
+
+      expect(() => stopHeartbeat()).not.toThrow();
+    });
+
+    test("should write heartbeat entry after interval", async () => {
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "test-run",
+        feature: "test-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      statusWriter.setPrd({
+        version: 1,
+        feature: "test-feature",
+        userStories: [],
+      });
+
+      const totalCost = 0;
+      const iterations = 0;
+
+      startHeartbeat(
+        statusWriter,
+        () => totalCost,
+        () => iterations,
+        TEST_JSONL,
+      );
+
+      // Wait for one heartbeat cycle (60s in production, but we can't wait that long in tests)
+      // This test just verifies no crash during startup
+      await Bun.sleep(100);
+
+      stopHeartbeat();
+
+      // Verify no crash (test passes if we reach here)
+      expect(true).toBe(true);
+    });
+
+    test("should stop heartbeat idempotently", () => {
+      expect(() => stopHeartbeat()).not.toThrow();
+      expect(() => stopHeartbeat()).not.toThrow();
+    });
+  });
+
+  describe("writeExitSummary", () => {
+    test("should write exit summary to JSONL file", async () => {
+      await writeExitSummary(TEST_JSONL, 1.23, 5, 3, 60000);
+
+      const file = Bun.file(TEST_JSONL);
+      expect(await file.exists()).toBe(true);
+
+      const content = await file.text();
+      const lines = content.trim().split("\n");
+      expect(lines.length).toBe(1);
+
+      const entry = JSON.parse(lines[0]);
+      expect(entry.level).toBe("info");
+      expect(entry.stage).toBe("exit-summary");
+      expect(entry.message).toBe("Run completed");
+      expect(entry.data.totalCost).toBe(1.23);
+      expect(entry.data.iterations).toBe(5);
+      expect(entry.data.storiesCompleted).toBe(3);
+      expect(entry.data.durationMs).toBe(60000);
+      expect(entry.data.exitedCleanly).toBe(true);
+    });
+
+    test("should not throw when JSONL path is undefined", async () => {
+      await expect(writeExitSummary(undefined, 1.23, 5, 3, 60000)).resolves.toBeUndefined();
+    });
+
+    test("should include timestamp in exit summary", async () => {
+      const beforeTime = new Date().toISOString();
+      await writeExitSummary(TEST_JSONL, 1.23, 5, 3, 60000);
+      const afterTime = new Date().toISOString();
+
+      const file = Bun.file(TEST_JSONL);
+      const content = await file.text();
+      const entry = JSON.parse(content.trim());
+
+      expect(entry.timestamp).toBeDefined();
+      expect(entry.timestamp >= beforeTime).toBe(true);
+      expect(entry.timestamp <= afterTime).toBe(true);
+    });
+  });
+
+  describe("resetCrashHandlers", () => {
+    test("should reset handlers and stop heartbeat", () => {
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "test-run",
+        feature: "test-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      const ctx: CrashRecoveryContext = {
+        statusWriter,
+        getTotalCost: () => 0,
+        getIterations: () => 0,
+        jsonlFilePath: TEST_JSONL,
+      };
+
+      installCrashHandlers(ctx);
+      startHeartbeat(
+        statusWriter,
+        () => 0,
+        () => 0,
+        TEST_JSONL,
+      );
+
+      expect(() => resetCrashHandlers()).not.toThrow();
+
+      // After reset, should be able to install handlers again
+      expect(() => installCrashHandlers(ctx)).not.toThrow();
+    });
+  });
+
+  describe("SIGTERM run.complete event (BUG-017)", () => {
+    test("should emit run.complete event when SIGTERM handler is invoked directly", async () => {
+      // Mock process.exit to prevent the test process from actually exiting
+      const originalExit = process.exit;
+      let exitCalled = false;
+      let exitCode: number | undefined;
+      process.exit = ((code?: number) => {
+        exitCalled = true;
+        exitCode = code;
+      }) as typeof process.exit;
+
+      const statusWriter = new StatusWriter(TEST_STATUS_FILE, DEFAULT_CONFIG, {
+        runId: "run-sigterm-mock",
+        feature: "mock-feature",
+        startedAt: new Date().toISOString(),
+        dryRun: false,
+        startTimeMs: Date.now(),
+        pid: process.pid,
+      });
+
+      statusWriter.setPrd({
+        version: 1,
+        feature: "mock-feature",
+        userStories: [],
+      });
+
+      const startTime = Date.now() - 5000;
+      const ctx: CrashRecoveryContext = {
+        statusWriter,
+        getTotalCost: () => 2.5,
+        getIterations: () => 4,
+        jsonlFilePath: TEST_JSONL,
+        runId: "run-sigterm-mock",
+        feature: "mock-feature",
+        getStartTime: () => startTime,
+        getTotalStories: () => 10,
+        getStoriesCompleted: () => 3,
+      };
+
+      const cleanup = installCrashHandlers(ctx);
+
+      // Capture the SIGTERM listener registered by installCrashHandlers
+      const sigtermListeners = process.listeners("SIGTERM");
+      const sigtermHandler = sigtermListeners[sigtermListeners.length - 1] as () => Promise<void>;
+
+      // Invoke the handler directly — no real signal, no subprocess
+      await sigtermHandler();
+
+      // Restore process.exit before assertions
+      process.exit = originalExit;
+      cleanup();
+
+      // Assert process.exit was called with the correct SIGTERM exit code
+      expect(exitCalled).toBe(true);
+      expect(exitCode).toBe(128 + 15); // SIGTERM = signal 15
+
+      // Assert run.complete event was written to JSONL
+      const file = Bun.file(TEST_JSONL);
+      expect(await file.exists()).toBe(true);
+      const content = await file.text();
+      const lines = content.trim().split("\n").filter(Boolean);
+      const entries = lines.map((line: string) => JSON.parse(line));
+      const runCompleteEvent = entries.find((e: { stage: string }) => e.stage === "run.complete");
+
+      expect(runCompleteEvent).toBeDefined();
+      expect(runCompleteEvent.level).toBe("info");
+      expect(runCompleteEvent.message).toBe("Feature execution terminated");
+      expect(runCompleteEvent.data.runId).toBe("run-sigterm-mock");
+      expect(runCompleteEvent.data.feature).toBe("mock-feature");
+      expect(runCompleteEvent.data.success).toBe(false);
+      expect(runCompleteEvent.data.exitReason).toBe("sigterm");
+      expect(runCompleteEvent.data.totalCost).toBe(2.5);
+      expect(runCompleteEvent.data.iterations).toBe(4);
+      expect(runCompleteEvent.data.totalStories).toBe(10);
+      expect(runCompleteEvent.data.storiesCompleted).toBe(3);
+      expect(runCompleteEvent.data.durationMs).toBeGreaterThanOrEqual(0);
+    });
+  });
+});

package/test/unit/escalation.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for src/execution/escalation.ts
+ *
+ * Covers: escalateTier, getTierConfig, calculateMaxIterations
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { TierConfig } from "../../src/config";
+import { calculateMaxIterations, escalateTier, getTierConfig } from "../../src/execution/escalation";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Test fixtures
+// ─────────────────────────────────────────────────────────────────────────────
+
+const defaultTierOrder: TierConfig[] = [
+  { tier: "fast", attempts: 5 },
+  { tier: "balanced", attempts: 3 },
+  { tier: "powerful", attempts: 2 },
+];
+
+const customTierOrder: TierConfig[] = [
+  { tier: "haiku", attempts: 10 },
+  { tier: "sonnet", attempts: 5 },
+  { tier: "opus", attempts: 2 },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// escalateTier
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("escalateTier", () => {
+  it("returns next tier in order when not at max", () => {
+    expect(escalateTier("fast", defaultTierOrder)).toBe("balanced");
+    expect(escalateTier("balanced", defaultTierOrder)).toBe("powerful");
+  });
+
+  it("returns null when at max tier", () => {
+    expect(escalateTier("powerful", defaultTierOrder)).toBeNull();
+  });
+
+  it("returns null when tier not found in order", () => {
+    expect(escalateTier("unknown", defaultTierOrder)).toBeNull();
+  });
+
+  it("handles single-tier order", () => {
+    const singleTier: TierConfig[] = [{ tier: "only", attempts: 10 }];
+    expect(escalateTier("only", singleTier)).toBeNull();
+  });
+
+  it("works with custom tier names", () => {
+    expect(escalateTier("haiku", customTierOrder)).toBe("sonnet");
+    expect(escalateTier("sonnet", customTierOrder)).toBe("opus");
+    expect(escalateTier("opus", customTierOrder)).toBeNull();
+  });
+
+  it("returns null for empty tier order", () => {
+    expect(escalateTier("fast", [])).toBeNull();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// getTierConfig
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("getTierConfig", () => {
+  it("returns tier config when tier exists", () => {
+    const config = getTierConfig("balanced", defaultTierOrder);
+    expect(config).toEqual({ tier: "balanced", attempts: 3 });
+  });
+
+  it("returns undefined when tier not found", () => {
+    expect(getTierConfig("unknown", defaultTierOrder)).toBeUndefined();
+  });
+
+  it("handles first tier", () => {
+    const config = getTierConfig("fast", defaultTierOrder);
+    expect(config).toEqual({ tier: "fast", attempts: 5 });
+  });
+
+  it("handles last tier", () => {
+    const config = getTierConfig("powerful", defaultTierOrder);
+    expect(config).toEqual({ tier: "powerful", attempts: 2 });
+  });
+
+  it("returns undefined for empty tier order", () => {
+    expect(getTierConfig("fast", [])).toBeUndefined();
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// calculateMaxIterations
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("calculateMaxIterations", () => {
+  it("sums all tier attempts", () => {
+    // 5 + 3 + 2 = 10
+    expect(calculateMaxIterations(defaultTierOrder)).toBe(10);
+  });
+
+  it("handles single tier", () => {
+    const singleTier: TierConfig[] = [{ tier: "only", attempts: 7 }];
+    expect(calculateMaxIterations(singleTier)).toBe(7);
+  });
+
+  it("returns 0 for empty tier order", () => {
+    expect(calculateMaxIterations([])).toBe(0);
+  });
+
+  it("handles large attempt counts", () => {
+    const largeTiers: TierConfig[] = [
+      { tier: "a", attempts: 100 },
+      { tier: "b", attempts: 200 },
+      { tier: "c", attempts: 150 },
+    ];
+    expect(calculateMaxIterations(largeTiers)).toBe(450);
+  });
+
+  it("handles zero attempts", () => {
+    const zeroTiers: TierConfig[] = [
+      { tier: "a", attempts: 0 },
+      { tier: "b", attempts: 5 },
+      { tier: "c", attempts: 0 },
+    ];
+    expect(calculateMaxIterations(zeroTiers)).toBe(5);
+  });
+});