terramend 0.2.0

package/src/mcp/staleFix.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ToolContext } from "#app/mcp/server";
+import {
+  assessStaleFix,
+  ClosePullRequestTool,
+  groupIdFromBranch,
+  isBotActor,
+  isRemediationBranch,
+  ListRemediationPrsTool,
+} from "#app/mcp/staleFix";
+
+describe("isRemediationBranch / groupIdFromBranch", () => {
+  it("recognises remediate and generate branches, rejects others", () => {
+    expect(isRemediationBranch("remediate/abc123")).toBe(true);
+    expect(isRemediationBranch("remediate/batch-deadbeef")).toBe(true);
+    expect(isRemediationBranch("terramend/generate-s3-site")).toBe(true);
+    expect(isRemediationBranch("feature/foo")).toBe(false);
+    expect(isRemediationBranch("main")).toBe(false);
+  });
+
+  it("extracts the group id from a remediate branch only", () => {
+    expect(groupIdFromBranch("remediate/abc123")).toBe("abc123");
+    expect(groupIdFromBranch("remediate/batch-deadbeef")).toBe("batch-deadbeef");
+    expect(groupIdFromBranch("terramend/generate-s3")).toBeNull();
+    expect(groupIdFromBranch("main")).toBeNull();
+  });
+});
+
+describe("isBotActor", () => {
+  it("treats terramend logins and any [bot] as bot; a null login as non-human", () => {
+    expect(isBotActor("terramend[bot]")).toBe(true);
+    expect(isBotActor("terramenddev")).toBe(true);
+    expect(isBotActor("dependabot[bot]")).toBe(true);
+    expect(isBotActor(null)).toBe(true); // unmapped author → not provably human
+    expect(isBotActor(undefined)).toBe(true);
+  });
+
+  it("treats a real user login as non-bot", () => {
+    expect(isBotActor("alice")).toBe(false);
+    expect(isBotActor("octocat")).toBe(false);
+  });
+});
+
+describe("assessStaleFix", () => {
+  it("escalates a human-touched branch regardless of base movement", () => {
+    const a = assessStaleFix({ baseBehindBy: 5, hasNonBotCommits: true });
+    expect(a.status).toBe("human_touched");
+    expect(a.action).toBe("escalate");
+  });
+
+  it("skips a PR whose base has not advanced", () => {
+    const a = assessStaleFix({ baseBehindBy: 0, hasNonBotCommits: false });
+    expect(a.status).toBe("current");
+    expect(a.action).toBe("skip");
+  });
+
+  it("flags a stale PR for refresh when the base advanced", () => {
+    const a = assessStaleFix({ baseBehindBy: 3, hasNonBotCommits: false });
+    expect(a.status).toBe("stale");
+    expect(a.action).toBe("refresh");
+    expect(a.reason).toContain("3 commit");
+  });
+});
+
+// --- tool tests ------------------------------------------------------------
+
+function execText(t: ReturnType<typeof ListRemediationPrsTool>) {
+  return t.execute as (
+    p: unknown,
+    c: unknown,
+  ) => Promise<{ content: [{ type: "text"; text: string }]; isError?: boolean }>;
+}
+
+describe("ListRemediationPrsTool", () => {
+  function makeCtx(
+    openPrs: unknown[],
+    compares: Record<string, { ahead_by: number; behind_by: number; commits: unknown[] }>,
+  ): ToolContext {
+    return {
+      repo: { owner: "o", name: "r" },
+      payload: {},
+      octokit: {
+        // paginate is mocked to return the list directly; the first arg (the
+        // `pulls.list` route) just needs to exist to be referenced.
+        paginate: vi.fn(async () => openPrs),
+        rest: {
+          pulls: { list: vi.fn() },
+          repos: {
+            compareCommits: vi.fn(async ({ head }: { head: string }) => ({
+              data: compares[head] ?? { ahead_by: 1, behind_by: 0, commits: [] },
+            })),
+          },
+        },
+      },
+    } as unknown as ToolContext;
+  }
+
+  it("filters to remediation branches and assesses each", async () => {
+    const openPrs = [
+      {
+        number: 1,
+        html_url: "u1",
+        title: "fix a",
+        head: { ref: "remediate/aaa" },
+        base: { ref: "main" },
+        labels: [{ name: "terramend" }],
+      },
+      {
+        number: 2,
+        html_url: "u2",
+        title: "human PR",
+        head: { ref: "feature/x" },
+        base: { ref: "main" },
+        labels: [],
+      },
+      {
+        number: 3,
+        html_url: "u3",
+        title: "fix b (stale)",
+        head: { ref: "remediate/bbb" },
+        base: { ref: "main" },
+        labels: [],
+      },
+    ];
+    const compares = {
+      "remediate/aaa": {
+        ahead_by: 1,
+        behind_by: 0,
+        commits: [{ author: { login: "terramend[bot]" } }],
+      },
+      "remediate/bbb": {
+        ahead_by: 1,
+        behind_by: 4,
+        commits: [{ author: { login: "terramend[bot]" } }],
+      },
+    };
+    const ctx = makeCtx(openPrs, compares);
+    const text = await execText(ListRemediationPrsTool(ctx))({}, {});
+    const out = text.content[0].text;
+    expect(out).toContain("ok: true");
+    // only the two remediation PRs appear (feature/x filtered out)
+    expect(out).toContain("remediate/aaa");
+    expect(out).toContain("remediate/bbb");
+    expect(out).not.toContain("feature/x");
+    // #1 current (behind 0) → skip; #3 stale (behind 4) → refresh
+    expect(out).toContain("skip");
+    expect(out).toContain("refresh");
+  });
+
+  it("marks a branch with a human commit as escalate", async () => {
+    const openPrs = [
+      {
+        number: 5,
+        html_url: "u5",
+        title: "fix c",
+        head: { ref: "remediate/ccc" },
+        base: { ref: "main" },
+        labels: [],
+      },
+    ];
+    const compares = {
+      "remediate/ccc": {
+        ahead_by: 2,
+        behind_by: 3,
+        commits: [{ author: { login: "terramend[bot]" } }, { author: { login: "alice" } }],
+      },
+    };
+    const ctx = makeCtx(openPrs, compares);
+    const text = await execText(ListRemediationPrsTool(ctx))({}, {});
+    const out = text.content[0].text;
+    expect(out).toContain("escalate");
+    expect(out).toContain("human_touched");
+    expect(out).toContain("alice");
+  });
+});
+
+describe("ClosePullRequestTool", () => {
+  function makeCtx(opts: {
+    push?: "disabled" | "restricted" | "enabled";
+    issueNumber?: number;
+  }): ToolContext & {
+    _update: ReturnType<typeof vi.fn>;
+    _comment: ReturnType<typeof vi.fn>;
+  } {
+    const update = vi.fn(async ({ pull_number }: { pull_number: number }) => ({
+      data: { number: pull_number, state: "closed", html_url: `u${pull_number}` },
+    }));
+    const comment = vi.fn(async () => ({ data: { id: 1 } }));
+    const ctx = {
+      repo: { owner: "o", name: "r" },
+      payload: {
+        push: opts.push ?? "restricted",
+        event:
+          opts.issueNumber !== undefined
+            ? { trigger: "issue", issue_number: opts.issueNumber, is_pr: true }
+            : { trigger: "unknown" },
+      },
+      toolState: { model: undefined, createdTargets: new Set<number>() },
+      octokit: {
+        rest: {
+          issues: { createComment: comment },
+          pulls: { update },
+        },
+      },
+    } as unknown as ToolContext;
+    return Object.assign(ctx, { _update: update, _comment: comment });
+  }
+
+  it("closes a PR (standalone run = in scope) and posts the comment first", async () => {
+    const ctx = makeCtx({});
+    const text = await execText(ClosePullRequestTool(ctx) as never)(
+      { pull_number: 7, comment: "already resolved on base" },
+      {},
+    );
+    expect(text.content[0].text).toContain("state: closed");
+    expect(ctx._comment).toHaveBeenCalledOnce();
+    expect(ctx._update).toHaveBeenCalledWith(
+      expect.objectContaining({ pull_number: 7, state: "closed" }),
+    );
+  });
+
+  it("is blocked under push: disabled", async () => {
+    const ctx = makeCtx({ push: "disabled" });
+    const text = await execText(ClosePullRequestTool(ctx) as never)({ pull_number: 7 }, {});
+    expect(text.isError).toBe(true);
+    expect(text.content[0].text).toContain("read-only");
+    expect(ctx._update).not.toHaveBeenCalled();
+  });
+
+  it("refuses to close a PR outside the run's scope", async () => {
+    const ctx = makeCtx({ issueNumber: 42 });
+    const text = await execText(ClosePullRequestTool(ctx) as never)({ pull_number: 7 }, {});
+    expect(text.isError).toBe(true);
+    expect(text.content[0].text).toContain("scoped to #42");
+    expect(ctx._update).not.toHaveBeenCalled();
+  });
+});

package/src/mcp/staleFix.ts

@@ -0,0 +1,277 @@
+import { type } from "arktype";
+import { addFooter } from "#app/mcp/comment";
+import { assertTargetInScope } from "#app/mcp/scope";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+/**
+ * §27 Stale-fix self-healing. A Terramend remediation PR is "base + a minimal,
+ * proven fix". When the base branch advances after the PR is opened, the PR goes
+ * stale: its diff is computed against an old base, the concern may already be
+ * resolved upstream (a human fixed it, or the base changed the file), or the
+ * branch simply needs re-deriving on the new base. A scheduled `RefreshRemediation`
+ * run sweeps the open remediation PRs and, per PR, either re-derives the fix on
+ * the current base and force-updates it, closes it as already-resolved, or leaves
+ * it for a human when someone has added their own commits.
+ *
+ * This file is the GitHub-orchestration seam: a pure classifier (`assessStaleFix`)
+ * that decides what to do from git facts, the read tool that surfaces the open
+ * remediation PRs with their staleness, and the focused write tool that closes a
+ * now-redundant PR. The actual re-derive/validate/verify loop is driven by the
+ * mode prompt using the existing scan/validate/verify/push tools — no git merge
+ * is performed (re-deriving on the fresh base avoids conflict resolution entirely
+ * and keeps the PR diff to exactly the fix).
+ */
+
+// the branch-name conventions Terramend opens PRs under: `remediate/<group-id>`
+// (incl. `remediate/batch-<hash>`) for a fix and `terramend/generate-<slug>` for
+// a generation. The naming is the primary "this is Terramend's PR" signal.
+const REMEDIATION_BRANCH = /^(?:remediate\/|terramend\/generate-)/;
+
+/** true when `branch` is a Terramend remediation/generation branch. */
+export function isRemediationBranch(branch: string): boolean {
+  return REMEDIATION_BRANCH.test(branch);
+}
+
+/** the `<group-id>` of a `remediate/<group-id>` branch (the scan group id that
+ * keys the fix), or null for a generation branch / non-remediation branch. */
+export function groupIdFromBranch(branch: string): string | null {
+  return branch.match(/^remediate\/(.+)$/)?.[1] ?? null;
+}
+
+/** true when a commit-author login is Terramend's bot (so a commit by it is NOT
+ * a human edit). A null/absent login is treated as non-human: Terramend pushes
+ * with a git identity that often doesn't map to a GitHub user, so requiring a
+ * positive bot match would make every PR look human-touched and never refresh. */
+export function isBotActor(login: string | null | undefined): boolean {
+  if (!login) return true;
+  const normalized = login.replace(/\[bot\]$/i, "").toLowerCase();
+  return normalized === "terramend" || normalized === "terramenddev" || /\[bot\]$/i.test(login);
+}
+
+export type StaleFixStatus = "current" | "stale" | "human_touched";
+export type StaleFixAction = "skip" | "refresh" | "escalate";
+
+export interface StaleFixAssessment {
+  status: StaleFixStatus;
+  action: StaleFixAction;
+  reason: string;
+}
+
+/**
+ * Decide what a refresh sweep should do with one open remediation PR, from git
+ * facts alone. Pure.
+ *  - a branch carrying NON-bot commits is `human_touched` → `escalate` (never
+ *    force-overwrite a human's work; leave it for review).
+ *  - a branch whose base has NOT advanced is `current` → `skip` (the fix is still
+ *    derived against the live base).
+ *  - otherwise the base moved → `stale` → `refresh`: re-derive the fix on the
+ *    current base, then close it if the concern is already resolved or update it.
+ */
+export function assessStaleFix(input: {
+  baseBehindBy: number;
+  hasNonBotCommits: boolean;
+}): StaleFixAssessment {
+  if (input.hasNonBotCommits) {
+    return {
+      status: "human_touched",
+      action: "escalate",
+      reason:
+        "the PR branch has commit(s) not authored by terramend — auto-refresh would overwrite a human's work; label it needs-human and leave it for review",
+    };
+  }
+  if (input.baseBehindBy <= 0) {
+    return {
+      status: "current",
+      action: "skip",
+      reason: "the base has not advanced since the PR was opened — the fix is still current",
+    };
+  }
+  return {
+    status: "stale",
+    action: "refresh",
+    reason:
+      `the base advanced ${input.baseBehindBy} commit(s) since the PR was opened — re-scan on the current base, ` +
+      "then close the PR if the concern is already resolved or re-derive + force-update the fix otherwise",
+  };
+}
+
+interface AssessedRemediationPr {
+  number: number;
+  url: string;
+  title: string;
+  branch: string;
+  base: string;
+  group_id: string | null;
+  base_behind_by: number;
+  head_ahead_by: number;
+  has_non_bot_commits: boolean;
+  commit_authors: string[];
+  labels: string[];
+  status: StaleFixStatus;
+  recommended_action: StaleFixAction;
+  reason: string;
+}
+
+export const ListRemediationPrsParams = type({
+  "limit?": type.number.describe(
+    "max open remediation PRs to assess (default 30). Each is one compare-commits API call.",
+  ),
+});
+
+export function ListRemediationPrsTool(ctx: ToolContext) {
+  return tool({
+    name: "list_remediation_prs",
+    description:
+      "§27 — list the repo's OPEN Terramend remediation/generation PRs (branches `remediate/<id>` or " +
+      "`terramend/generate-<slug>`) with their staleness, so a refresh sweep knows which to act on. For each " +
+      "PR it compares the head branch against its base and returns `base_behind_by` (how many commits the " +
+      "base advanced since the PR was opened), `head_ahead_by`, `has_non_bot_commits` (a human pushed to the " +
+      "branch), the `group_id`, labels, and a `recommended_action`: `skip` (still current), `refresh` (base " +
+      "moved — re-derive the fix on the current base, then close-if-resolved or force-update), or `escalate` " +
+      "(human-touched — label needs-human, don't overwrite). Read-only. Use it as the first step of " +
+      "RefreshRemediation.",
+    parameters: ListRemediationPrsParams,
+    execute: execute(async ({ limit }) => {
+      const cap = limit ?? 30;
+      const owner = ctx.repo.owner;
+      const repo = ctx.repo.name;
+
+      const open = await ctx.octokit.paginate(ctx.octokit.rest.pulls.list, {
+        owner,
+        repo,
+        state: "open",
+        per_page: 100,
+      });
+      const remediation = open.filter((pr) => isRemediationBranch(pr.head.ref)).slice(0, cap);
+
+      const prs: AssessedRemediationPr[] = [];
+      const errors: { number: number; error: string }[] = [];
+      for (const pr of remediation) {
+        try {
+          // base..head: ahead_by = the PR's own commits, behind_by = commits on
+          // the base the PR lacks (how far the base moved since the fork point).
+          const cmp = await ctx.octokit.rest.repos.compareCommits({
+            owner,
+            repo,
+            base: pr.base.ref,
+            head: pr.head.ref,
+          });
+          const commitAuthors = [
+            ...new Set(
+              (cmp.data.commits ?? [])
+                .map((c) => c.author?.login ?? c.commit.author?.name ?? null)
+                .filter((a): a is string => a !== null),
+            ),
+          ];
+          const hasNonBotCommits = (cmp.data.commits ?? []).some(
+            (c) => !isBotActor(c.author?.login),
+          );
+          const assessment = assessStaleFix({
+            baseBehindBy: cmp.data.behind_by,
+            hasNonBotCommits,
+          });
+          prs.push({
+            number: pr.number,
+            url: pr.html_url,
+            title: pr.title,
+            branch: pr.head.ref,
+            base: pr.base.ref,
+            group_id: groupIdFromBranch(pr.head.ref),
+            base_behind_by: cmp.data.behind_by,
+            head_ahead_by: cmp.data.ahead_by,
+            has_non_bot_commits: hasNonBotCommits,
+            commit_authors: commitAuthors,
+            labels: pr.labels.map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean),
+            status: assessment.status,
+            recommended_action: assessment.action,
+            reason: assessment.reason,
+          });
+        } catch (e) {
+          errors.push({ number: pr.number, error: e instanceof Error ? e.message : String(e) });
+        }
+      }
+
+      const counts = {
+        refresh: prs.filter((p) => p.recommended_action === "refresh").length,
+        skip: prs.filter((p) => p.recommended_action === "skip").length,
+        escalate: prs.filter((p) => p.recommended_action === "escalate").length,
+      };
+      log.info(
+        `» list_remediation_prs: ${prs.length} open remediation PR(s) — ` +
+          `${counts.refresh} refresh, ${counts.skip} skip, ${counts.escalate} escalate` +
+          (errors.length ? ` (${errors.length} errored)` : ""),
+      );
+      return toolOk({
+        count: prs.length,
+        action_counts: counts,
+        pull_requests: prs,
+        ...(errors.length ? { errors } : {}),
+        note:
+          prs.length === 0
+            ? "No open Terramend remediation PRs to refresh."
+            : "Act on the `refresh` PRs (re-derive on the current base, then close-if-resolved or force-update); `escalate` PRs get a needs-human label and are left for a human; `skip` PRs are already current.",
+      });
+    }),
+  });
+}
+
+export const ClosePullRequest = type({
+  pull_number: type.number.describe("the pull request number to close (not merge)."),
+  "comment?": type.string.describe(
+    "an optional comment explaining why it's being closed — posted before closing (e.g. 'concern already resolved on the base; this fix is now redundant').",
+  ),
+});
+
+export function ClosePullRequestTool(ctx: ToolContext) {
+  return tool({
+    name: "close_pull_request",
+    description:
+      "Close (NOT merge) a pull request. §27 use: a Terramend remediation PR whose concern is already " +
+      "resolved on the current base — the fix is redundant, so close it (optionally with an explanatory " +
+      "comment) instead of leaving a stale PR open. Blocked under `push: disabled`, and bound to the run's " +
+      "scope (a comment-triggered run can only close the PR it was triggered on or one it opened; a " +
+      "standalone scheduled sweep may close any). Never merges — closing is reversible.",
+    parameters: ClosePullRequest,
+    execute: execute(async ({ pull_number, comment }) => {
+      // permission gate: closing a PR is a repo write — block it under read-only.
+      if (ctx.payload.push === "disabled") {
+        throw new Error(
+          "Closing a pull request is disabled. This repository is configured for read-only access (push: disabled).",
+        );
+      }
+      // scope gate: same binding as comment/label/PR-body writes (mcp/scope.ts).
+      assertTargetInScope(ctx, pull_number, "close");
+
+      const owner = ctx.repo.owner;
+      const repo = ctx.repo.name;
+
+      if (comment) {
+        await ctx.octokit.rest.issues.createComment({
+          owner,
+          repo,
+          issue_number: pull_number,
+          body: addFooter(ctx, comment),
+        });
+        log.info(`» commented before closing PR #${pull_number}`);
+      }
+
+      const result = await ctx.octokit.rest.pulls.update({
+        owner,
+        repo,
+        pull_number,
+        state: "closed",
+      });
+      ctx.toolState.wasUpdated = true;
+      log.info(`» closed pull request #${result.data.number}`);
+
+      return {
+        success: true,
+        number: result.data.number,
+        state: result.data.state,
+        url: result.data.html_url,
+      };
+    }),
+  });
+}

package/src/mcp/terraform/cost.ts

@@ -0,0 +1,163 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { type RunResult, resolveBaseRef, run } from "#app/mcp/terraform/types";
+
+// --- infracost (cost lens) ------------------------------------------------
+
+export interface CostBreakdown {
+  /** total estimated monthly cost, or null when no resources are priced. */
+  totalMonthlyCost: number | null;
+  currency: string;
+}
+
+/**
+ * Parse `infracost breakdown --format json`. The top-level `totalMonthlyCost`
+ * is a decimal string (absent / null when a project has no priced resources);
+ * `currency` defaults to USD. A missing/unparseable cost becomes null so the
+ * caller reports "unpriced" rather than a misleading $0.00.
+ */
+export function parseInfracostBreakdown(stdout: string): CostBreakdown {
+  const parsed = JSON.parse(stdout || "{}") as {
+    totalMonthlyCost?: string | number | null;
+    currency?: string;
+  };
+  const raw = parsed.totalMonthlyCost;
+  const num = typeof raw === "number" ? raw : raw != null ? Number.parseFloat(raw) : Number.NaN;
+  return {
+    totalMonthlyCost: Number.isFinite(num) ? num : null,
+    currency: parsed.currency || "USD",
+  };
+}
+
+export interface ResourceCost {
+  name: string;
+  monthlyCost: number;
+}
+
+/**
+ * Parse the per-resource monthly costs from `infracost breakdown --format json`
+ * (`projects[].breakdown.resources[]`), so a cost increase can be attributed to
+ * the specific resources that drove it instead of just a total. Skips unpriced
+ * (null/zero) resources; returns them sorted most-expensive first. Pure.
+ */
+export function parseInfracostResources(stdout: string): ResourceCost[] {
+  let parsed: {
+    projects?: {
+      breakdown?: { resources?: { name?: string; monthlyCost?: string | number | null }[] };
+    }[];
+  };
+  try {
+    parsed = JSON.parse(stdout || "{}");
+  } catch {
+    return [];
+  }
+  const out: ResourceCost[] = [];
+  for (const project of parsed.projects ?? []) {
+    for (const r of project.breakdown?.resources ?? []) {
+      const raw = r.monthlyCost;
+      const cost =
+        typeof raw === "number" ? raw : raw != null ? Number.parseFloat(raw) : Number.NaN;
+      if (Number.isFinite(cost) && cost > 0 && r.name) {
+        out.push({ name: r.name, monthlyCost: Math.round(cost * 100) / 100 });
+      }
+    }
+  }
+  return out.sort((a, b) => b.monthlyCost - a.monthlyCost);
+}
+
+export interface CostDelta {
+  currency: string;
+  baselineMonthly: number | null;
+  currentMonthly: number | null;
+  /** current − baseline, rounded to cents; null when either side is unknown. */
+  deltaMonthly: number | null;
+  direction: "increase" | "decrease" | "no-change" | "unknown";
+}
+
+/** Pure cost-delta computation: current (post-fix) vs the base-branch baseline. */
+export function computeCostDelta(
+  baseline: CostBreakdown | null,
+  current: CostBreakdown,
+): CostDelta {
+  const currency = current.currency || baseline?.currency || "USD";
+  const baselineMonthly = baseline?.totalMonthlyCost ?? null;
+  const currentMonthly = current.totalMonthlyCost;
+  if (baselineMonthly === null || currentMonthly === null) {
+    return { currency, baselineMonthly, currentMonthly, deltaMonthly: null, direction: "unknown" };
+  }
+  const deltaMonthly = Math.round((currentMonthly - baselineMonthly) * 100) / 100;
+  const direction = deltaMonthly > 0 ? "increase" : deltaMonthly < 0 ? "decrease" : "no-change";
+  return { currency, baselineMonthly, currentMonthly, deltaMonthly, direction };
+}
+
+export interface CostEscalation {
+  /** true when the monthly increase meets/exceeds the operator's threshold. */
+  escalate: boolean;
+  reason?: string;
+}
+
+/**
+ * §4.16-next — decide whether a cost increase is large enough to escalate the PR
+ * to human review (`needs-human`). Compares the monthly delta against the
+ * operator's `cost_increase_block_usd` threshold. No threshold set, an unknown
+ * delta, or a decrease/no-change ⇒ no escalation. Pure + deterministic so the
+ * decision is auditable, not a model judgement.
+ */
+export function classifyCostEscalation(
+  deltaMonthly: number | null,
+  thresholdUsd: number | undefined,
+): CostEscalation {
+  if (thresholdUsd === undefined || deltaMonthly === null || deltaMonthly <= 0) {
+    return { escalate: false };
+  }
+  if (deltaMonthly >= thresholdUsd) {
+    return {
+      escalate: true,
+      reason: `the fix raises monthly cost by ${deltaMonthly}, at or above the ${thresholdUsd} escalation threshold`,
+    };
+  }
+  return { escalate: false };
+}
+
+export function runInfracostBreakdown(scanCwd: string, key: string): RunResult {
+  return run("infracost", ["breakdown", "--path", ".", "--format", "json", "--no-color"], scanCwd, {
+    INFRACOST_API_KEY: key,
+  });
+}
+
+/**
+ * Cost of the base-branch version of the same Terraform, computed in a detached
+ * git worktree so the current (fixed) checkout is never disturbed. Best-effort:
+ * any failure (no base ref, worktree add fails, infracost errors) returns null
+ * and the caller falls back to reporting current cost only.
+ */
+export function infracostBaseline(cwd: string, key: string, tmpdir: string): CostBreakdown | null {
+  const baseRef = resolveBaseRef(cwd);
+  if (!baseRef) return null;
+  const prefixResult = run("git", ["rev-parse", "--show-prefix"], cwd);
+  const prefix = prefixResult.status === 0 ? prefixResult.stdout.trim() : "";
+  // unique, unpredictable worktree path. the old `infracost-base-<pid>` name was
+  // predictable (a local actor could pre-create/symlink it) and collided when
+  // two baselines ran in the same process. mkdtemp gives a fresh PARENT dir;
+  // the worktree itself goes in a not-yet-existing child (git worktree add
+  // refuses a path that already exists). the finally removes both the git
+  // worktree registration and the parent dir.
+  const baseDir = mkdtempSync(join(tmpdir, "infracost-base-"));
+  const worktree = join(baseDir, "wt");
+  const add = run("git", ["worktree", "add", "--detach", worktree, baseRef], cwd);
+  if (add.status !== 0) {
+    rmSync(baseDir, { recursive: true, force: true });
+    return null;
+  }
+  try {
+    const scanCwd = prefix ? join(worktree, prefix) : worktree;
+    const r = runInfracostBreakdown(scanCwd, key);
+    if (r.missing || r.status !== 0) return null;
+    return parseInfracostBreakdown(r.stdout);
+  } catch {
+    return null;
+  } finally {
+    run("git", ["worktree", "remove", "--force", worktree], cwd);
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+}