infraweaver 0.3.11 → 0.3.13

package/src/mcp/terraform/refactorScope.ts

@@ -12,19 +12,72 @@
  * people call (terraform-aws-vpc, say). Moving its resources into a submodule is
  * provably equivalent, and still churn for every consumer: their plans gain a
  * wall of `moved` addresses for no change in what they get. There, extraction
- * and normalisation candidates come back marked `report_only` — named in the
- * run's summary, never opened as a PR. Consolidating roots that duplicate each
- * other is unaffected: that removes real duplication, not style.
+ * and normalisation candidates in the module's own code come back marked
+ * `report_only` — named in the run's summary, never opened as a PR. A directory
+ * inside it that deploys (`envs/prod/` with its own provider or backend) is a
+ * configuration like any other, and its candidates stay actionable.
+ * Consolidating roots that duplicate each other is unaffected: that removes real
+ * duplication, not style.
  */
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { BLOCK_LABEL, parseBlocks } from "#app/mcp/terraform/hcl";
 
-/** true for a path inside an `examples/` (or `example/`) directory, at any depth. */
+/**
+ * true for a path inside an `examples/` directory at any depth, or an `example/`
+ * one at the repository root. The registry's convention is `examples/`; the
+ * singular is accepted only where that convention puts it, because a module
+ * NAMED `example` (`modules/example/`) is code someone calls.
+ */
 export function isExamplePath(path: string): boolean {
-  return /(?:^|\/)examples?\//.test(path.replace(/\\/g, "/"));
+  return /(?:^|\/)examples\/|^example\//i.test(path.replace(/\\/g, "/"));
+}
+
+const PROVIDER_OR_BACKEND = new RegExp(
+  String.raw`(?:^|\n)\s*(?:provider|backend)\s+${BLOCK_LABEL}\s*\{`,
+);
+const CLOUD_BLOCK = /(?:^|\n)\s*cloud\s*\{/;
+
+/** whether one file's text configures a provider, a backend or HCP Terraform. */
+function configuresDeployment(name: string, text: string): boolean {
+  if (name.endsWith(".tf.json")) {
+    let doc: unknown;
+    try {
+      doc = JSON.parse(text);
+    } catch {
+      return false;
+    }
+    if (typeof doc !== "object" || doc === null) return false;
+    const { provider, terraform } = doc as { provider?: unknown; terraform?: unknown };
+    if (provider !== undefined) return true;
+    // `terraform` is an object, or an array of them, in the JSON syntax
+    return [terraform]
+      .flat()
+      .some((t) => typeof t === "object" && t !== null && ("backend" in t || "cloud" in t));
+  }
+  if (PROVIDER_OR_BACKEND.test(text)) return true;
+  // `cloud` is a block name other schemas use too; only the settings block's counts
+  return parseBlocks(text, ["terraform"]).some((b) => CLOUD_BLOCK.test(b.body));
 }
 
-const PROVIDER_OR_BACKEND = /^\s*(?:provider\s+"|backend\s+")/m;
+const isTerraformFile = (name: string) => name.endsWith(".tf") || name.endsWith(".tf.json");
+
+/** whether the Terraform directly in `dir` is a root someone deploys from. */
+function deploysFrom(dir: string): boolean {
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter(isTerraformFile);
+  } catch {
+    return false;
+  }
+  return names.some((name) => {
+    try {
+      return configuresDeployment(name, readFileSync(join(dir, name), "utf8"));
+    } catch {
+      return false;
+    }
+  });
+}
 
 /** whether some directory under `dir` (to a small depth) holds a `.tf` file. */
 function holdsTerraform(dir: string, depth: number): boolean {
@@ -53,23 +106,14 @@ function holdsTerraform(dir: string, depth: number): boolean {
  * deployment, or null when it does not.
  */
 export function libraryRepoReason(cwd: string): string | null {
-  let rootFiles: string[];
+  let rootEntries: string[];
   try {
-    rootFiles = readdirSync(cwd).filter((f) => f.endsWith(".tf"));
+    rootEntries = readdirSync(cwd);
   } catch {
     return null;
   }
-  if (rootFiles.length === 0) return null;
-  for (const f of rootFiles) {
-    let text: string;
-    try {
-      text = readFileSync(join(cwd, f), "utf8");
-    } catch {
-      continue;
-    }
-    if (PROVIDER_OR_BACKEND.test(text)) return null;
-  }
-  const examples = ["examples", "example"].find((d) => existsSync(join(cwd, d)));
+  if (!rootEntries.some(isTerraformFile) || deploysFrom(cwd)) return null;
+  const examples = rootEntries.find((d) => /^examples?$/i.test(d));
   if (examples === undefined || !holdsTerraform(join(cwd, examples), 2)) return null;
   return (
     `the repository root configures no provider and no backend, and ships \`${examples}/\`: it is a ` +
@@ -77,7 +121,32 @@ export function libraryRepoReason(cwd: string): string | null {
   );
 }
 
-/** what a detector tool adds to its result when the repository is a library. */
+/**
+ * For a library repository, why a candidate in `file` (repo-relative) is
+ * reported rather than restructured — or null when the file belongs to a
+ * directory, or sits under one, that deploys on its own. Outside a library,
+ * always null.
+ */
+export function libraryScope(cwd: string): (file: string) => string | null {
+  const reason = libraryRepoReason(cwd);
+  if (reason === null) return () => null;
+  const deploys = new Map<string, boolean>();
+  return (file) => {
+    const dirs = file.replace(/\\/g, "/").split("/").slice(0, -1);
+    for (let i = dirs.length; i > 0; i--) {
+      const dir = dirs.slice(0, i).join("/");
+      let d = deploys.get(dir);
+      if (d === undefined) {
+        d = deploysFrom(join(cwd, dir));
+        deploys.set(dir, d);
+      }
+      if (d) return null;
+    }
+    return reason;
+  };
+}
+
+/** what a detector tool adds to a candidate in a library's own code. */
 export function reportOnly(reason: string | null): {
   report_only?: true;
   report_only_reason?: string;

package/src/mcp/terraform/ruleContext.ts

@@ -46,6 +46,8 @@ export interface RuleContext {
   readonly files: readonly SourceFile[];
   /** the `.tofu` half. Only the dialect rule needs it; empty on a repo with none. */
   readonly tofuFiles: readonly SourceFile[];
+  /** the `.tfvars` inputs. Only the hardcoded-secret rule reads them; empty on a repo with none. */
+  readonly tfvarsFiles: readonly SourceFile[];
   /** non-null when the walk was bounded before it finished — see [[tree]]. */
   readonly truncated: TreeTruncation;
   /** how many times a literal must repeat in one directory before it is reported. */
@@ -80,6 +82,7 @@ export interface RuleContextInput {
   cwd: string;
   files: readonly SourceFile[];
   tofuFiles?: readonly SourceFile[];
+  tfvarsFiles?: readonly SourceFile[];
   truncated?: TreeTruncation;
   repeatedLiteralThreshold: number;
 }
@@ -89,6 +92,7 @@ export function createRuleContext(input: RuleContextInput): RuleContext {
     cwd: input.cwd,
     files: input.files,
     tofuFiles: input.tofuFiles ?? [],
+    tfvarsFiles: input.tfvarsFiles ?? [],
     truncated: input.truncated ?? null,
     repeatedLiteralThreshold: input.repeatedLiteralThreshold,
   };

package/src/mcp/terraform/scanDelta.ts

@@ -275,38 +275,79 @@ export function computeScanDelta(input: ScanDeltaInput): ScanDelta {
 }
 
 /**
- * Pair an introduced finding on a NEW resource with a resolved one that broke
- * the same rule and whose resource no longer exists where it was: renamed within
- * its module, or moved under the same name to another directory (a resource
- * extracted into a module without a `moved` block). Each resolved finding pairs
- * at most once.
+ * Pair a NEW resource with a vanished one — a resource whose findings resolved
+ * because it no longer exists where it was: renamed within its module, or moved
+ * under the same name to another directory (a resource extracted into a module
+ * without a `moved` block).
+ *
+ * Resources pair one-to-one, as `moved` blocks do: Terraform rejects two blocks
+ * with the same `from` or the same `to`, so a pairing made per finding — one new
+ * bucket matched to two old ones because each shared a different rule — would
+ * advise blocks that cannot be written. Each candidate pair scores the findings
+ * the two resources share (rule by rule, instance by instance), the best pairs
+ * are taken first, and ties fall to address order so the result is stable. Only
+ * the shared findings of a pair are labelled; a rule the vanished resource never
+ * broke is new on the renamed one too.
  */
 function markPossibleRenames(
   introduced: DeltaFinding[],
   resolved: DeltaFinding[],
   headAddresses: (dir: string) => ReadonlySet<string>,
 ): void {
-  const vanished = resolved.filter((r) => {
-    if (r.address === null) return false;
-    return !headAddresses(dirOf(r.concern.location.file)).has(r.address);
-  });
-  const used = new Set<DeltaFinding>();
-  for (const finding of introduced) {
-    if (finding.address === null) continue;
-    const dir = dirOf(finding.concern.location.file);
-    const match = vanished.find(
-      (r) =>
-        !used.has(r) &&
-        ruleKey(r.concern) === ruleKey(finding.concern) &&
-        // a `moved` block cannot change a resource's type
-        typeOf(r.address as string) === typeOf(finding.address as string) &&
-        // renamed in place, or moved elsewhere under its own name
-        (dirOf(r.concern.location.file) === dir) !== (r.address === finding.address),
-    );
-    if (!match) continue;
-    used.add(match);
-    finding.possiblyPreexisting = true;
-    finding.renamedFrom = { address: match.address as string, file: match.concern.location.file };
+  const byResource = (findings: DeltaFinding[]) => {
+    const out = new Map<string, { dir: string; address: string; findings: DeltaFinding[] }>();
+    for (const f of [...findings].sort((a, b) => byLocation(a.concern, b.concern))) {
+      if (f.address === null) continue;
+      const dir = dirOf(f.concern.location.file);
+      const key = `${dir}|${f.address}`;
+      const entry = out.get(key);
+      if (entry) entry.findings.push(f);
+      else out.set(key, { dir, address: f.address, findings: [f] });
+    }
+    return [...out.values()];
+  };
+  const vanished = byResource(resolved).filter((r) => !headAddresses(r.dir).has(r.address));
+  const appeared = byResource(introduced);
+
+  // the findings of `to` that match one of `from`'s, each of `from`'s used once
+  const shared = (from: (typeof vanished)[number], to: (typeof appeared)[number]) => {
+    const left = new Map<string, number>();
+    for (const f of from.findings)
+      left.set(ruleKey(f.concern), (left.get(ruleKey(f.concern)) ?? 0) + 1);
+    return to.findings.filter((f) => {
+      const n = left.get(ruleKey(f.concern)) ?? 0;
+      if (n === 0) return false;
+      left.set(ruleKey(f.concern), n - 1);
+      return true;
+    });
+  };
+  const order = (a: { dir: string; address: string }, b: { dir: string; address: string }) =>
+    a.dir.localeCompare(b.dir) || a.address.localeCompare(b.address);
+  const candidates = vanished.flatMap((from) =>
+    appeared
+      .filter(
+        (to) =>
+          // a `moved` block cannot change a resource's type
+          typeOf(from.address) === typeOf(to.address) &&
+          // renamed in place, or moved elsewhere under its own name
+          (from.dir === to.dir) !== (from.address === to.address),
+      )
+      .map((to) => ({ from, to, findings: shared(from, to) }))
+      .filter((p) => p.findings.length > 0),
+  );
+  candidates.sort(
+    (a, b) => b.findings.length - a.findings.length || order(a.from, b.from) || order(a.to, b.to),
+  );
+  const used = new Set<object>();
+  for (const { from, to, findings } of candidates) {
+    if (used.has(from) || used.has(to)) continue;
+    used.add(from);
+    used.add(to);
+    const file = from.findings[0]?.concern.location.file as string;
+    for (const finding of findings) {
+      finding.possiblyPreexisting = true;
+      finding.renamedFrom = { address: from.address, file };
+    }
   }
 }
 

package/src/mcp/terraform/scanSession.ts

@@ -77,6 +77,12 @@ export interface ScanSession {
   // agent took from the FIRST scan (`concernKeyOf`), or it falls back to
   // matching ids exactly and calls every line-shifted finding resolved.
   concernsById?: Map<string, Concern>;
+  // the resource each reported concern sat in when it was reported (by id), and
+  // per (scanner, rule, file) key the resources the rule fired on the first time
+  // the run saw that key. terraform_verify_remediation reads both to count a fix
+  // on one resource while the rule still fires on another (see verifySites).
+  siteById?: Map<string, string | null>;
+  firstSitesByKey?: Map<string, Set<string | null>>;
   // the findings gate's concern set: scanned by the engine itself before the
   // agent starts, on the tree the run was invoked on, at the CONFIGURED
   // threshold and scope. read at end-of-run by finalizeSuccessRun for the

package/src/mcp/terraform/tools/detectPlanDrift.ts

@@ -6,6 +6,7 @@ import { PRODUCT_NAME } from "#app/brand";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { walkTfFiles } from "#app/mcp/modules";
 import { execute, tool, toolOk } from "#app/mcp/shared";
+import { listOpenRemediationPrs } from "#app/mcp/staleFix";
 import { buildConcernResult } from "#app/mcp/terraform/concernResult";
 import { indexTfResources } from "#app/mcp/terraform/cspm";
 import { docUrlsForGroup, ruleDocUrl } from "#app/mcp/terraform/decisions";
@@ -180,6 +181,7 @@ export function DetectPlanDriftTool(ctx: LocalToolContext) {
         // drift is a narrow concern source — join any prior scan baseline so a
         // later ✗→✓ verify doesn't read the whole workspace as regressions.
         baselineMode: "merge",
+        openRemediationPrs: await listOpenRemediationPrs(ctx),
       });
 
       log.info(

package/src/mcp/terraform/tools/ingestExternalFindings.ts

@@ -7,6 +7,7 @@ import { PRODUCT_NAME } from "#app/brand";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { readTextCapped, walkTfFiles } from "#app/mcp/modules";
 import { execute, tool, toolOk } from "#app/mcp/shared";
+import { listOpenRemediationPrs } from "#app/mcp/staleFix";
 import { buildConcernResult } from "#app/mcp/terraform/concernResult";
 import { cappedSummary, SeedCapParams, seedCapsFrom } from "#app/mcp/terraform/coverage";
 import {
@@ -220,6 +221,7 @@ export function IngestExternalFindingsTool(ctx: LocalToolContext) {
         // baseline so a later ✗→✓ verify doesn't read the workspace as regressions.
         baselineMode: "merge",
         seedCaps: seedCapsFrom(input),
+        openRemediationPrs: await listOpenRemediationPrs(ctx),
       });
       const cappedBlock = cappedSummary(capped);
 

package/src/mcp/terraform/tools/normalizationCandidates.ts

@@ -2,7 +2,7 @@ import { type } from "arktype";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { execute, tool, toolOk } from "#app/mcp/shared";
 import { findNormalizationCandidates } from "#app/mcp/terraform/normalization";
-import { isExamplePath, libraryRepoReason, reportOnly } from "#app/mcp/terraform/refactorScope";
+import { isExamplePath, libraryScope, reportOnly } from "#app/mcp/terraform/refactorScope";
 import { log } from "#app/utils/cli";
 
 // --- the tool ----------------------------------------------------------------
@@ -29,15 +29,15 @@ export function NormalizationCandidatesTool(ctx: LocalToolContext) {
     parameters: NormalizationCandidatesParams,
     execute: execute(async () => {
       const cwd = ctx.payload.cwd ?? process.cwd();
-      const files = findNormalizationCandidates(cwd).filter(
-        (f) => ctx.payload.refactorExamples || !isExamplePath(f.file),
-      );
+      const library = libraryScope(cwd);
+      const files = findNormalizationCandidates(cwd)
+        .filter((f) => ctx.payload.refactorExamples || !isExamplePath(f.file))
+        .map((f) => ({ ...reportOnly(library(f.file)), ...f }));
       const total = files.reduce((n, f) => n + f.count, 0);
       log.info(
         `» terraform_normalization_candidates: ${total} site(s) across ${files.length} file(s)`,
       );
       return toolOk({
-        ...reportOnly(libraryRepoReason(cwd)),
         file_count: files.length,
         total,
         files,

package/src/mcp/terraform/tools/readFindings.ts

@@ -4,6 +4,7 @@ import { type } from "arktype";
 import { PRODUCT_NAME } from "#app/brand";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { execute, tool, toolOk } from "#app/mcp/shared";
+import { listOpenRemediationPrs } from "#app/mcp/staleFix";
 import { buildConcernResult } from "#app/mcp/terraform/concernResult";
 import { cappedSummary, SeedCapParams, seedCapsFrom } from "#app/mcp/terraform/coverage";
 import { docUrlsForGroup, ruleDocUrl } from "#app/mcp/terraform/decisions";
@@ -102,6 +103,7 @@ export function ReadFindingsTool(ctx: LocalToolContext) {
         grouping,
         autonomyThreshold,
         seedCaps: seedCapsFrom(input),
+        openRemediationPrs: await listOpenRemediationPrs(ctx),
       });
       const cappedBlock = cappedSummary(capped);
 

package/src/mcp/terraform/tools/scan.ts

@@ -4,6 +4,7 @@ import { type } from "arktype";
 import type { LocalToolContext } from "#app/mcp/localContext";
 import { walkTfFiles } from "#app/mcp/modules";
 import { execute, tool, toolOk } from "#app/mcp/shared";
+import { listOpenRemediationPrs } from "#app/mcp/staleFix";
 import { loadBaseline, loadResolvedLedger } from "#app/mcp/terraform/baseline";
 import { buildConcernResult } from "#app/mcp/terraform/concernResult";
 import {
@@ -148,6 +149,8 @@ export async function runScan(
       autonomyThreshold,
       inScope,
       priority,
+      openRemediationPrs: await listOpenRemediationPrs(ctx),
+      linesMatchTree: true,
     },
   );
   const { active, suppressed, groups, batchPlan, bySeverity: by_severity } = result;

package/src/mcp/terraform/tools/verifyRemediation.ts

@@ -3,6 +3,7 @@ import type { LocalToolContext } from "#app/mcp/localContext";
 import { execute, tool, toolOk } from "#app/mcp/shared";
 import { computeConfidence } from "#app/mcp/terraform/decisions";
 import { captureProvenFix } from "#app/mcp/terraform/fixMemory";
+import { declaredAddresses } from "#app/mcp/terraform/scanDelta";
 import {
   computeRegressions,
   computeRemediationVerdict,
@@ -12,6 +13,7 @@ import {
 } from "#app/mcp/terraform/scanners";
 import { hasBaseline, scanSessionOf } from "#app/mcp/terraform/scanSession";
 import { concernKeyOf, dedupe } from "#app/mcp/terraform/types";
+import { fileReader, resolvedAtSite, siteOf } from "#app/mcp/terraform/verifySites";
 import { log } from "#app/utils/cli";
 import { resolveToolSelection } from "#app/utils/prompt/toolSelection";
 import { resolveModuleCredentialEnv } from "#app/utils/setup/registryAuth";
@@ -82,7 +84,27 @@ export async function runVerifyRemediation(
     if (key !== undefined) keyed.push({ id, key });
     else unkeyed.push(id);
   }
-  const keyedVerdict = partitionByKey(keyed, currentKeys);
+  const byKey = partitionByKey(keyed, currentKeys);
+  // a rule still firing in the file may have been fixed on THIS finding's
+  // resource; count it only under the conditions verifySites spells out
+  const read = fileReader(cwd);
+  const remainingKeyed = keyed.filter((k) => byKey.remaining.includes(k.id));
+  const atSite = new Set(
+    resolvedAtSite({
+      requested: remainingKeyed.map((k) => ({
+        ...k,
+        site: session.siteById?.get(k.id) ?? null,
+        file: reported.get(k.id)?.location.file,
+      })),
+      current: currentConcerns.map((c) => ({ key: concernKeyOf(c), site: siteOf(c, read) })),
+      firstSites: session.firstSitesByKey ?? new Map(),
+      declared: (file) => new Set(declaredAddresses(read(file) ?? "")),
+    }),
+  );
+  const keyedVerdict = {
+    resolved: [...byKey.resolved, ...byKey.remaining.filter((id) => atSite.has(id))],
+    remaining: byKey.remaining.filter((id) => !atSite.has(id)),
+  };
   const fallbackVerdict = computeRemediationVerdict(unkeyed, new Set(currentIds));
   const resolved = [...keyedVerdict.resolved, ...fallbackVerdict.resolved];
   const remaining = [...keyedVerdict.remaining, ...fallbackVerdict.remaining];

package/src/mcp/terraform/tree.ts

@@ -176,6 +176,14 @@ export function readTofuTree(cwd: string, limits?: TreeReadLimits): SourceTree {
   return readTree(cwd, ".tofu", limits);
 }
 
+/**
+ * The `.tfvars` inputs (`.auto.tfvars` included). Not configuration, so no rule
+ * reads them as blocks; the hardcoded-secret rule reads their assignments.
+ */
+export function readTfvarsTree(cwd: string, limits?: TreeReadLimits): SourceTree {
+  return readTree(cwd, ".tfvars", limits);
+}
+
 /** How many oversize paths a gap names before it stops listing them. A gap is a
  *  sentence in a report, not a manifest; past a handful the count carries the
  *  fact and the list only buries it. */

package/src/mcp/terraform/types.ts

@@ -399,7 +399,8 @@ export interface ConcernGroup {
    * the file (by-file grouping) or the rule (by-rule grouping). */
   id: string;
   /** the branch its fix is pushed to: `remediate/<id>`, plus `--<base>` when the
-   * PR targets a branch other than the repository default. */
+   * PR targets a branch other than the repository default — or the head of the
+   * remediation PR already open for this group into the same base. */
   branch?: string;
   /** the group's primary file (by-file) or a human label like "3 files"
    * (by-rule); `files` carries the full list for by-rule groups. */

package/src/mcp/terraform/verifySites.ts

@@ -0,0 +1,124 @@
+/**
+ * Which findings a fix resolved where its rule still fires elsewhere in the file.
+ *
+ * terraform_verify_remediation keys a finding on (scanner, rule, file), so a
+ * rule fixed on one resource but still firing on another in the same file read
+ * as unfixed for both: AWSGoat's open-egress fix on two of four security groups
+ * verified as 0 of 5. Counting by resource instead risks the opposite error —
+ * a fix that moves the defect onto a new resource would look resolved — so a
+ * finding counts as resolved at its own site only when ALL of these hold:
+ *
+ *   - it was placed on a resource when it was reported, by a scan of the tree
+ *     as it then stood, and no later scan placed the same id elsewhere;
+ *   - that resource is still declared in the file (a renamed or deleted one
+ *     proves nothing);
+ *   - the rule no longer fires on it;
+ *   - every place the rule still fires in the file is a resource it already
+ *     fired on before the fix (no new site, and no finding outside a resource).
+ *
+ * Anything else keeps the file-level answer, which under-claims and never
+ * over-claims.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ScanSession } from "#app/mcp/terraform/scanSession";
+import { resourceAddressAt } from "#app/mcp/terraform/suppressions";
+import { type Concern, concernKeyOf } from "#app/mcp/terraform/types";
+
+/** A reader that returns each file under `cwd` once, or null when unreadable. */
+export function fileReader(cwd: string): (file: string) => string | null {
+  const cache = new Map<string, string | null>();
+  return (file) => {
+    if (!cache.has(file)) {
+      let text: string | null;
+      try {
+        text = readFileSync(join(cwd, file), "utf8");
+      } catch {
+        text = null;
+      }
+      cache.set(file, text);
+    }
+    return cache.get(file) ?? null;
+  };
+}
+
+/** The resource a concern sits in, read from the file as it is now. */
+export function siteOf(c: Concern, read: (file: string) => string | null): string | null {
+  const text = read(c.location.file);
+  return text === null ? null : resourceAddressAt(text, c.location.line);
+}
+
+/**
+ * Remember where each reported concern sat, and the first sites per key.
+ *
+ * `linesMatchTree` says the concerns were scanned off the tree in `cwd` as it
+ * is now. Without it (a findings file or external report, which may describe
+ * another commit) their lines are not trusted to name today's resources: their
+ * ids get no site and their keys no first sites.
+ */
+export function recordConcernSites(
+  session: ScanSession,
+  concerns: Concern[],
+  cwd: string,
+  linesMatchTree: boolean,
+): void {
+  const read = fileReader(cwd);
+  session.siteById ??= new Map();
+  session.firstSitesByKey ??= new Map();
+  const first = session.firstSitesByKey;
+  const fresh = new Map<string, Set<string | null>>();
+  for (const c of concerns) {
+    const site = linesMatchTree ? siteOf(c, read) : null;
+    // an id is line-pinned, so after an edit a re-scan can report a different
+    // finding under it. It keeps the site it was first reported at; placed
+    // anywhere else later, it is ambiguous and gets none.
+    const prior = session.siteById.get(c.id);
+    session.siteById.set(c.id, prior === undefined || prior === site ? site : null);
+    if (!linesMatchTree) continue;
+    const key = concernKeyOf(c);
+    if (first.has(key)) continue;
+    const sites = fresh.get(key) ?? new Set();
+    sites.add(site);
+    fresh.set(key, sites);
+  }
+  for (const [key, sites] of fresh) first.set(key, sites);
+}
+
+export interface SiteRequest {
+  id: string;
+  /** the (scanner, rule, file) key */
+  key: string;
+  /** the resource address the finding sat in when reported, or null */
+  site: string | null;
+  file: string | undefined;
+}
+
+export function resolvedAtSite(params: {
+  requested: readonly SiteRequest[];
+  /** every finding the re-scan reports, with the resource it sits in */
+  current: readonly { key: string; site: string | null }[];
+  /** per key, the resources the rule fired on in the first scan of the run */
+  firstSites: ReadonlyMap<string, ReadonlySet<string | null>>;
+  /** the resource addresses a file declares now */
+  declared: (file: string) => ReadonlySet<string>;
+}): string[] {
+  const firingByKey = new Map<string, (string | null)[]>();
+  for (const c of params.current) {
+    const list = firingByKey.get(c.key) ?? [];
+    list.push(c.site);
+    firingByKey.set(c.key, list);
+  }
+  const out: string[] = [];
+  for (const r of params.requested) {
+    if (r.site === null || r.file === undefined) continue;
+    const firing = firingByKey.get(r.key) ?? [];
+    const known = params.firstSites.get(r.key);
+    if (known === undefined) continue;
+    if (firing.some((s) => s === null || !known.has(s))) continue;
+    if (firing.includes(r.site)) continue;
+    if (!params.declared(r.file).has(r.site)) continue;
+    out.push(r.id);
+  }
+  return out;
+}

package/src/modes/refactor.ts

@@ -18,7 +18,7 @@ This mode standardises STRUCTURE while preserving BEHAVIOUR — the equivalence
    - \`${t("terraform_normalization_candidates")}\` → in-place idiomatic cleanups that change SYNTAX, not behaviour (redundant whole-string \`"\${expr}"\` interpolation; legacy HCL0.11 map-argument block syntax like \`vars {\` on a \`template_file\`). These relocate NOTHING — zero \`moved {}\` blocks — and are proven by the same equivalence check.
    - \`${t("terraform_consolidation_candidates")}\` → the SAME resource shape declared in several root directories (\`env/dev\` + \`env/staging\` + \`env/prod\`), with the single parameterised module they could all call already derived: which attributes are identical (module content) and which differ (per-environment inputs). A member root of a group will ALSO show up as a zero-candidate cluster in \`${t("module_extraction_candidates")}\` — prefer the consolidation, which does that work once for every environment instead of once per environment. Its \`near_groups\` are the opposite case: roots recognisably the same stack that DIFFER (one carries a resource the other does not), where folding them together is a design decision this mode has no basis for. Do NOT extract a near-group root's shared resources into a module on its own either — a module one twin calls and the other does not widens exactly the drift the near-group reports. Leave those roots alone and name the near-group and its \`differences\` in your report.
 
-   **A result marked \`report_only\` is an observation, not work.** The repository is a module other configurations call (\`report_only_reason\` says why), and restructuring it is churn for every caller: name those candidates in your \`${t("report_progress")}\` summary and open no PR for them. \`examples/\` roots are left out of every candidate list unless the operator set \`refactor_examples\`.
+   **A candidate marked \`report_only\` is an observation, not work.** It sits in the code of a module other configurations call (\`report_only_reason\` says why), and restructuring that is churn for every caller: name those candidates in your \`${t("report_progress")}\` summary and open no PR for them. \`examples/\` roots are left out of every candidate list unless the operator set \`refactor_examples\`.
 
    **Before picking, check the interface.** \`${t("module_extraction_candidates")}\` reports \`unmapped_attributes\` per candidate and a top-level \`partial_interfaces\` list: arguments the raw resources SET that the target module does not. Adopting such a module DROPS them silently — and the equivalence check cannot catch it, because once the argument is gone it is absent from both sides. Two of these are unrecoverable rather than merely wrong (\`object_lock_enabled\` cannot be set after creation; \`force_destroy\` changes deletion semantics). So: **decline the candidate, or extend the module to expose the argument and say so in the PR body.** Deleting the argument to make the shapes match is never the fix. A candidate whose \`unmapped_attributes\` is \`null\` was NOT checked — the module is external and its code is not in this repo — which is not the same as clean.
 

package/src/modes/remediate-and-refactor.ts

@@ -20,7 +20,7 @@ This mode composes the **Remediate** and **Refactor** verbs into a single run. I
    - **commit the fix** (\`git add\` only the changed \`*.tf\`/\`*.tfvars\`, a \`fix(tf): …\` message). Do NOT push yet. This committed state is the refactor's equivalence BASELINE.
 
 3. **REFACTOR (phase 2) — modularise on top of the committed fix**: follow the **Refactor** mode's flow:
-   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` → pick one behaviour-preserving refactor; a result marked \`report_only\` (the repository is a module others call) is named in the summary, never proposed. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
+   - \`${t("module_extraction_candidates")}\` / \`${t("terraform_normalization_candidates")}\` → pick one behaviour-preserving refactor; a candidate marked \`report_only\` (it sits in the code of a module others call) is named in the summary, never proposed. Respect a pinned \`refactor_source\` if one was supplied (it constrains which module source you may use; the behaviour-altering b.4 path is only available when the operator pinned \`third-party\`).
    - resolve the module source, wire the \`module\` call against its real interface (\`${t("terraform_module_interface")}\` for a local module dir, \`${t("terraform_module_lookup")}\` for a registry-sourced one), and emit a \`moved {}\` block for EVERY relocated address (\`${t("terraform_generate_moved")}\`).
    - \`terraform fmt\` + \`${t("terraform_validate")}\`, then — **with the refactor edits still UNCOMMITTED** — call \`${t("terraform_equivalence_check")}\`. In this mode it diffs the working tree against the COMMITTED fix (not the run-start commit), so it measures only the refactor. It must return \`equivalent: true\` (zero uncovered moves, resource set + arguments preserved, validate + fmt clean) before you proceed; \`${t("push_branch")}\` hard-blocks an unproven one — and, once this run has added a \`moved {}\` block, it also hard-blocks a push that never ran the check at all, so abandoning the refactor means REVERTING its edits rather than leaving them in with the fix. If it can't be proven equivalent, abandon the refactor and ship the fix alone.
    - **document the module (only when the \`docs\` input is enabled)**: after the equivalence check passes, call \`${t("terraform_module_docs")}\` for the module you created/adopted (pass the relocated addresses as \`moves\`). Do not hand-write docs — the tool builds from the interface, moved blocks, and equivalence verdict.

package/src/modes/remediate.ts

@@ -34,7 +34,7 @@ export function remediateMode(t: ToolRef): Mode {
 
 4. **for the chosen group**:
    - **base branch**: this run's base branch is resolved deterministically — \`${t("create_pull_request")}\` targets the \`base_branch\` input if set, else the branch the run started on, else the repository's default branch (\`main\`, or \`master\`). You do not choose it; just **omit** the \`base\` argument when opening the PR (below) and it is filled in.
-   - **idempotency**: the remediation branch is the group's \`branch\` (\`remediate/<group-id>\`, with a \`--<base>\` suffix when the PR targets a non-default branch) — use it exactly, never a name of your own. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
+   - **idempotency**: the remediation branch is the group's \`branch\` (\`remediate/<group-id>\`, with a \`--<base>\` suffix when the PR targets a non-default branch, or the branch of the PR already open for this group) — use it exactly, never a name of your own. Before doing anything, check whether that branch or an open PR for it already exists (\`${t("git")}\` / \`${t("get_pull_request")}\`). If one exists, update it rather than opening a duplicate.
    - **branch**: create the group's \`branch\` from the **current HEAD** (the checkout that was just scanned) via \`${t("git")}\` (\`git({ command: "checkout", args: ["-b", <branch>] })\`). Do NOT switch to a different base first — branching from the scanned checkout keeps the PR diff to exactly your fix.
    - **honest refusal (decide BEFORE fixing)**: if the group's concerns appear in the scan's \`refusal_candidates\` (the fix needs a human decision — narrowing an IAM wildcard, a KMS key policy, a real ingress CIDR), do **not** guess a fix that could break the stack. Instead open a structured issue (\`${t("create_issue")}\`) describing the concern, why it isn't auto-fixed, and what a human should do, and skip the PR for that group. A proven fix or an honest refusal — never a guessed, unverifiable PR.
    - **propose, then let me steer (when there's no single right fix)**: distinct from honest refusal (which refuses a fix a human must *decide*), this is for a finding with **2–3 genuinely distinct, defensible fixes** that differ in trade-offs, not correctness (e.g. encrypt with an AWS-managed key **vs** a customer-managed KMS key; a narrow security-group rule **vs** a prefix list **vs** a VPC endpoint). When such a fork exists **and the triggering comment did not already select a strategy**, do **not** silently pick for the reviewer: via \`${t("create_issue_comment")}\` post one short comment listing the options as **A / B / C** — each a single line (what it does + its trade-off) — and ask the reviewer to reply \`${COMMENT_COMMAND} fix #<concern-id> with strategy <A|B|C>\`. Then **skip the PR for this group** this run and note it in your final report (it resumes when the reviewer replies). When the comment **did** select one (\`fix #<id> with strategy B\`, or a bare \`strategy B\` reply on the proposal thread), apply **exactly** that strategy — don't second-guess it. Reserve this for real forks in the road; a fix with one obvious correct answer just gets made.

package/src/phases/runAgentWithWatchdogs.ts

@@ -105,10 +105,11 @@ export async function runAgentWithWatchdogs(params: RunAgentParams): Promise<Age
   const costQuota = reserved ? quotas.cost : createCostQuota(quotas.costLimit.full);
   log.info(
     quotas.tokenLimit.full > 0
-      ? `» run token quota: ${quotas.tokenLimit.full.toLocaleString("en-GB")} billable tokens` +
+      ? `» run token quota: ${quotas.tokenLimit.full.toLocaleString("en-GB")} tokens` +
           (reserved
             ? ` (${tokenQuota.limit.toLocaleString("en-GB")} for the run, the rest reserved to deliver findings if it runs out)`
-            : "")
+            : "") +
+          "; a token read from the prompt cache counts as a tenth"
       : `» run token quota: disabled (${RUN_TOKEN_QUOTA_INPUT}: 0)`,
   );
   log.info(