@hoanghainh/komagu 2.0.0 → 2.1.0

package/operate/ai/runner.py

@@ -7,7 +7,7 @@ LLM endpoint (Ollama, vLLM, private OpenAI server):
 3. Audits candidate routes for BOLA / IDOR (BOLA Auditor).
 4. Audits candidate queries for SQL/NoSQL Injection (Injection Auditor).
 5. Adversarial Skeptic Verification (Finding Verifier Council).
-6. Merges and schema-validates all findings with 0 false positives.
+6. Merges and schema-validates all findings; writes OUT/ai-run-stats.json.
 
 Standard-library only (Python 3.8+ compatible).
 """
@@ -18,30 +18,28 @@ import json
 from pathlib import Path
 import subprocess
 import sys
+import time
 from typing import Any, Callable, Dict, List, Optional
 
+from operate.ai.anchoring import Anchor, AnchorReport, anchor_findings, load_anchors
 from operate.ai.client import LLMClient
+from operate.ai.context import _included_files, _model_source, _read_snippet, _verification_context  # noqa: F401
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 LSA_PROMPTS = REPO_ROOT / "assess" / "lsa" / "prompts"
 DEFAULT_CWE = {"bola": ["CWE-284"], "bfla": ["CWE-285"], "mass_assignment": ["CWE-915"],
                "sql_injection": ["CWE-89"], "nosql_injection": ["CWE-943"]}
 LSA_SCRIPTS = REPO_ROOT / "assess" / "lsa" / "scripts"
+# Valid subtypes per category (finding.schema.json); the first one is used when a model writes an invalid value
+CATEGORY_SUBTYPES = {"bfla": ["missing_role_check", "role_from_request", "client_side_role_check"],
+                     "mass_assignment": ["whole_object_binding", "privileged_field_writable"]}
+FINDING_STATUSES = {"unverified", "confirmed", "likely", "rejected", "needs_review"}
 
 
-def _read_snippet(target_dir: Path, rel_file: str, line: int, radius: int = 15) -> str:
-    """Read a window of code around target line from the audited repository."""
-    full_path = target_dir / rel_file
-    if not full_path.is_file():
-        return f"[File not found: {rel_file}]"
-    try:
-        lines = full_path.read_text(encoding="utf-8", errors="replace").splitlines()
-        start = max(0, line - radius - 1)
-        end = min(len(lines), line + radius)
-        numbered = [f"{i + 1:4d} | {lines[i]}" for i in range(start, end)]
-        return "\n".join(numbered)
-    except Exception as e:
-        return f"[Error reading {rel_file}: {e}]"
+VERIFY_BATCH_SIZE = 5
+AUTH_MODEL_LIMIT = 6000
+RETRY_REMINDER = ("Your previous reply was empty or not valid JSON. Answer again with the JSON object only, "
+                  "exactly in the format requested above, with no other text.")
 
 
 class HeadlessAIRunner:
@@ -58,34 +56,121 @@ class HeadlessAIRunner:
         self.out_dir = Path(out_dir).resolve()
         self.client = client
         self.callback = step_callback or (lambda status, msg: None)
+        # Per-phase replies that could not be parsed as JSON; written to ai-run-stats.json
+        self.parse_failures: Dict[str, List[str]] = {}
+        # Per-phase batches whose model call failed (timeout, HTTP error); the run continues without them
+        self.call_errors: Dict[str, Dict[str, str]] = {}
+        # Per-phase batches whose first reply was empty or unparseable and were asked again
+        self.retries: Dict[str, List[str]] = {}
+        # Findings whose location was taken from the Tier 1 inventory (#319)
+        self.anchor_report = AnchorReport()
+        self._anchors: Optional[Dict[str, Anchor]] = None
+        self.phase_stats: Dict[str, Dict[str, Any]] = {}
 
     def _log(self, status: str, msg: str) -> None:
         self.callback(status, msg)
 
+    def _anchor(self, findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        if self._anchors is None:
+            self._anchors = load_anchors(self.out_dir, self.target_dir)
+        return anchor_findings(findings, self._anchors, self.target_dir, self.anchor_report)
+
+    def _chat(self, phase: str, batch_id: str, messages: List[Dict[str, str]]) -> Optional[str]:
+        """One batch call; a failed call is recorded and returns None instead of aborting the run.
+
+        An empty or unparseable reply is retried once with a reminder to answer with JSON only (#319).
+        """
+        try:
+            reply = self.client.chat(messages, temperature=0.1)
+        except Exception as e:
+            self.call_errors.setdefault(phase, {})[batch_id] = str(e)[:300]
+            self._log("warn", f"{phase}: model call failed for {batch_id} ({e}); batch left without verdicts")
+            return None
+        if self._parses(reply):
+            return reply
+        self.retries.setdefault(phase, []).append(batch_id)
+        self._log("warn", f"{phase}: reply for {batch_id} was {'empty' if not (reply or '').strip() else 'not valid JSON'}; retrying once")
+        retry_messages = messages + ([{"role": "assistant", "content": reply}] if (reply or "").strip() else []) + [
+            {"role": "user", "content": RETRY_REMINDER}]
+        try:
+            second = self.client.chat(retry_messages, temperature=0.1)
+        except Exception as e:
+            self._log("warn", f"{phase}: retry for {batch_id} failed ({e})")
+            return reply
+        return second if self._parses(second) or not (reply or "").strip() else reply
+
+    def _parses(self, reply: Optional[str]) -> bool:
+        if not (reply or "").strip():
+            return False
+        try:
+            self.client.extract_json(reply)
+            return True
+        except Exception:
+            return False
+
+    def _parse_failed(self, phase: str, batch_id: str, reply: Optional[str] = None) -> None:
+        if batch_id in self.call_errors.get(phase, {}):
+            return
+        self.parse_failures.setdefault(phase, []).append(batch_id)
+        if reply is not None:
+            raw_dir = self.out_dir / "ai-raw"
+            raw_dir.mkdir(parents=True, exist_ok=True)
+            (raw_dir / f"{phase}-{batch_id}.txt").write_text(reply, encoding="utf-8")
+        self._log("warn", f"{phase}: could not parse the model reply for {batch_id}; batch left without verdicts")
+
+    def _usage(self) -> Dict[str, Any]:
+        return dict(getattr(self.client, "usage", None) or {})
+
+    def _timed(self, phase: str, fn: Callable[[], Any]) -> None:
+        before, started = self._usage(), time.monotonic()
+        fn()
+        after = self._usage()
+        self.phase_stats[phase] = {
+            "seconds": round(time.monotonic() - started, 3),
+            **{k: after.get(k, 0) - before.get(k, 0) for k in ("calls", "prompt_tokens", "completion_tokens")},
+        }
+
+    def write_run_stats(self) -> Path:
+        """Write model, per-phase durations, token counts and parse failures to OUT/ai-run-stats.json."""
+        stats = {
+            "model": getattr(self.client, "model", None),
+            "endpoint": getattr(self.client, "endpoint", None),
+            "phases": self.phase_stats,
+            "totals": self._usage(),
+            "parse_failures": self.parse_failures,
+            "call_errors": self.call_errors,
+            "retries": self.retries,
+            "anchoring": {"moved": self.anchor_report.moved, "unanchored": self.anchor_report.unanchored},
+        }
+        path = self.out_dir / "ai-run-stats.json"
+        path.write_text(json.dumps(stats, indent=2), encoding="utf-8")
+        return path
+
     def run(self) -> Dict[str, Any]:
         """Execute all cognitive AI phases end-to-end."""
         self._log("step", "Starting Tier 2 Cognitive Multi-Agent Audit (Headless BYO-LLM)")
 
         # Phase 2: Stack & Auth Model Detector
-        self.infer_auth_model()
+        self._timed("2-stack-detector", self.infer_auth_model)
 
         # Phase 3: Route Inventory Mapping
-        self.map_routes_inventory()
+        self._timed("3-route-mapper", self.map_routes_inventory)
 
         # Phase 4a: BOLA / IDOR Cognitive Audit
-        self.audit_bola_routes()
+        self._timed("4a-bola-auditor", self.audit_bola_routes)
 
         # Phase 4b: SQL / NoSQL Injection Cognitive Audit
-        self.audit_injection_candidates()
+        self._timed("4b-injection-auditor", self.audit_injection_candidates)
 
         # Phase 4c: Privilege Audit (BFLA, mass assignment)
-        self.audit_privilege()
+        self._timed("4c-privilege-auditor", self.audit_privilege)
 
         # Phase 5: Adversarial Skeptic Verifier
-        self.verify_findings_skeptic()
+        self._timed("5-finding-verifier", self.verify_findings_skeptic)
 
         # Phase 6: Merge & Validate Outputs
         self.merge_and_validate()
+        self.write_run_stats()
 
         self._log("ok", "Tier 2 Cognitive Multi-Agent Audit completed successfully")
         return {"status": "success", "out_dir": str(self.out_dir)}
@@ -209,6 +294,20 @@ Output MUST be Markdown format adhering to Komagu auth-model.md specification.
         """Normalize finding fields to strictly comply with finding.schema.json."""
         if not isinstance(f, dict):
             return f
+        # impact must be a string; small models often return a list of consequences
+        if isinstance(f.get("impact"), list):
+            f["impact"] = "; ".join(str(i) for i in f["impact"])
+
+        # a verdict written into subtype belongs in status; fall back to the category's first subtype
+        allowed = CATEGORY_SUBTYPES.get(f.get("category"))
+        if allowed and f.get("subtype") not in allowed:
+            if f.get("subtype") in FINDING_STATUSES:
+                f["status"] = f["subtype"]
+            f["subtype"] = allowed[0]
+
+        if f.get("status") not in FINDING_STATUSES:
+            f["status"] = "unverified"
+
         # recommendation must be a string
         rec = f.get("recommendation")
         if isinstance(rec, dict):
@@ -227,8 +326,8 @@ Output MUST be Markdown format adhering to Komagu auth-model.md specification.
         else:
             for ev in evidence:
                 if isinstance(ev, dict):
-                    if "line" not in ev:
-                        ev["line"] = ev.get("start_line", default_line)
+                    if not isinstance(ev.get("line"), int):
+                        ev["line"] = ev.get("start_line") if isinstance(ev.get("start_line"), int) else default_line
                     if "file" not in ev:
                         ev["file"] = default_file
                     if "why" not in ev:
@@ -323,13 +422,14 @@ Respond STRICTLY with a valid JSON object matching:
                 {"role": "user", "content": user_prompt},
             ]
 
-            reply = self.client.chat(messages, temperature=0.1)
+            reply = self._chat("4a-bola-auditor", r_file.stem, messages)
             try:
                 parsed = self.client.extract_json(reply)
                 raw_findings = parsed.get("findings", [])
-                findings = [self._sanitize_finding(f) for f in raw_findings]
+                findings = self._anchor([self._sanitize_finding(f) for f in raw_findings])
                 route_verdicts = parsed.get("route_verdicts", [])
             except Exception:
+                self._parse_failed("4a-bola-auditor", r_file.stem, reply)
                 findings = []
                 route_verdicts = []
 
@@ -409,13 +509,14 @@ Respond STRICTLY with a valid JSON object matching:
                 {"role": "user", "content": user_prompt},
             ]
 
-            reply = self.client.chat(messages, temperature=0.1)
+            reply = self._chat("4b-injection-auditor", b_file.stem, messages)
             try:
                 parsed = self.client.extract_json(reply)
                 raw_findings = parsed.get("findings", [])
-                findings = [self._sanitize_finding(f) for f in raw_findings]
+                findings = self._anchor([self._sanitize_finding(f) for f in raw_findings])
                 candidate_verdicts = parsed.get("candidate_verdicts", [])
             except Exception:
+                self._parse_failed("4b-injection-auditor", b_file.stem, reply)
                 findings = []
                 candidate_verdicts = []
 
@@ -467,6 +568,7 @@ Respond STRICTLY with a valid JSON object matching:
                 "allowlist": c.get("allowlist"),
                 "sensitive_fields": c.get("sensitive_fields", []),
                 "code_context": _read_snippet(self.target_dir, c.get("file", ""), c.get("line") or 1),
+                "model_definition": _model_source(self.target_dir, c.get("target"), c.get("file", ""), c.get("line") or 1),
             } for c in mass]
 
             user_prompt = f"""Auth Model:
@@ -480,20 +582,51 @@ Mass Assignment Candidates:
 
 Task:
 Judge every route for BFLA and every candidate for mass assignment as described in your role.
-Respond STRICTLY with a valid JSON object with keys "batch_id" ("{b_file.stem}"),
-"privilege_route_verdicts", "candidate_verdicts" and "findings" (category "bfla" or "mass_assignment").
+Respond STRICTLY with a valid JSON object matching:
+{{
+  "batch_id": "{b_file.stem}",
+  "privilege_route_verdicts": [
+    {{"route_id": "<route_id>", "verdict": "vulnerable|safe|needs_review"}}
+  ],
+  "candidate_verdicts": [
+    {{"candidate_id": "<candidate_id>", "verdict": "vulnerable|safe|needs_review"}}
+  ],
+  "findings": [
+    {{
+      "finding_id": "BFLA-<route_id>-1 or MASS-<candidate_id>-1",
+      "category": "bfla|mass_assignment",
+      "subtype": "missing_role_check|role_from_request|client_side_role_check (bfla) or whole_object_binding|privileged_field_writable (mass_assignment)",
+      "title": "<short title>",
+      "route_id": "<route_id, bfla only>",
+      "candidate_id": "<candidate_id, mass_assignment only>",
+      "location": {{"file": "<file>", "start_line": <line>}},
+      "evidence": [{{"file": "<file>", "line": <line>, "why": "<privileged action or binding, and the missing control>"}}],
+      "impact": "<one string naming the privileged action or fields>",
+      "severity": "critical|high|medium|low",
+      "confidence": "high|medium|low",
+      "cwe": ["CWE-285"],
+      "recommendation": "<one string>",
+      "status": "unverified|needs_review"
+    }}
+  ]
+}}
+Write one finding for every "vulnerable" or "needs_review" verdict. A "needs_review" verdict goes in
+"status", never in "subtype".
+For mass assignment, judge the fields from "model_definition". If it says the definition was not found
+(or is null), you cannot know the fields: answer "needs_review", never "safe" for that reason alone.
 """
             messages = [
                 {"role": "system", "content": auditor_prompt},
                 {"role": "user", "content": user_prompt},
             ]
-            reply = self.client.chat(messages, temperature=0.1)
+            reply = self._chat("4c-privilege-auditor", b_file.stem, messages)
             try:
                 parsed = self.client.extract_json(reply)
-                findings = [self._sanitize_finding(f) for f in parsed.get("findings", [])]
+                findings = self._anchor([self._sanitize_finding(f) for f in parsed.get("findings", [])])
                 route_verdicts = parsed.get("privilege_route_verdicts", [])
                 candidate_verdicts = parsed.get("candidate_verdicts", [])
             except Exception:
+                self._parse_failed("4c-privilege-auditor", b_file.stem, reply)
                 findings, route_verdicts, candidate_verdicts = [], [], []
 
             out_doc = {
@@ -528,37 +661,46 @@ Respond STRICTLY with a valid JSON object with keys "batch_id" ("{b_file.stem}")
             return
 
         verifier_prompt = (LSA_PROMPTS / "50-finding-verifier.md").read_text(encoding="utf-8", errors="replace") if (LSA_PROMPTS / "50-finding-verifier.md").is_file() else ""
+        auth_model_path = self.out_dir / "auth-model.md"
+        auth_model = auth_model_path.read_text(encoding="utf-8", errors="replace")[:AUTH_MODEL_LIMIT] if auth_model_path.is_file() else ""
 
-        # Batch up to 10 findings per verification
-        batch_size = 10
+        batch_size = VERIFY_BATCH_SIZE
         for idx in range(0, len(all_findings), batch_size):
             chunk = all_findings[idx : idx + batch_size]
-            user_prompt = f"""Findings to Verify & Challenge:
-{json.dumps(chunk, indent=2)}
+            # The headless verifier cannot open files, so it gets the code it must judge (#286)
+            to_verify = [{"finding": f, "code_context": _verification_context(self.target_dir, f)} for f in chunk]
+            user_prompt = f"""Auth Model:
+{auth_model}
+
+Findings to Verify & Challenge (each with the code you may rely on):
+{json.dumps(to_verify, indent=2)}
 
 Task:
-You are the skeptical security verifier. For each finding:
-1. Examine whether a compensating control (global filter, integer casting, ownership check, allow-list) neutralizes the vulnerability.
-2. Confirm or refute:
-   - "confirmed" (reason_code: "traced")
-   - "rejected" (reason_code: "control_found" | "not_reachable" | "evidence_mismatch")
+You are the skeptical security verifier. You cannot open files: judge only from the code_context given
+with each finding and the Auth Model above.
+For each finding:
+1. Look for a compensating control (role or ownership check, global filter, integer cast, allow-list,
+   parameter binding) in the code_context.
+2. Only use reason_code "control_found" when the control is visible in the code_context; quote its
+   file and line in "control_found". Never assume a control in a base class, include, config or
+   middleware you were not shown.
+3. If the code you would need is not shown, answer verdict "likely" with reason_code
+   "code_not_visible" or "config_not_visible".
+Verdicts: "confirmed" | "likely" | "rejected".
+reason_code is one of: "traced", "code_not_visible", "config_not_visible", "data_ownership_unclear",
+"control_found", "evidence_mismatch", "not_executed", "not_reachable", "not_attacker_controlled".
 Respond STRICTLY with a valid JSON object matching verification.schema.json:
 {{
   "batch_id": "verified-{(idx // batch_size) + 1}",
   "verifications": [
     {{
       "finding_id": "<finding_id>",
-      "verdict": "confirmed|rejected",
-      "reason_code": "traced|control_found",
-      "confidence": "high",
-      "checked": ["Checked server-side session binding and sanitizers"],
-      "notes": "<rationale for verdict>",
-      "consensus": {{
-        "score": 0.95,
-        "agreement_level": "unanimous",
-        "voted_models": ["{self.client.model}"],
-        "rationale": "Independently audited and refuted false-alarm candidates."
-      }}
+      "verdict": "confirmed|likely|rejected",
+      "reason_code": "<one of the reason codes above>",
+      "confidence": "high|medium|low",
+      "checked": ["<what you checked in the code_context>"],
+      "control_found": {{"file": "<file>", "line": <line>, "code": "<control>"}} or null,
+      "notes": "<rationale for verdict>"
     }}
   ]
 }}
@@ -568,29 +710,15 @@ Respond STRICTLY with a valid JSON object matching verification.schema.json:
                 {"role": "user", "content": user_prompt},
             ]
 
-            reply = self.client.chat(messages, temperature=0.1)
+            reply = self._chat("5-finding-verifier", f"verified-{(idx // batch_size) + 1}", messages)
             try:
                 parsed = self.client.extract_json(reply)
                 verifs = parsed.get("verifications", [])
             except Exception:
-                # Default fallback verification for unverified items
-                verifs = [
-                    {
-                        "finding_id": f.get("finding_id", ""),
-                        "verdict": "confirmed",
-                        "reason_code": "traced",
-                        "confidence": "high",
-                        "checked": ["Audited data-flow"],
-                        "notes": "Traced via headless cognitive consensus.",
-                        "consensus": {
-                            "score": 0.90,
-                            "agreement_level": "majority",
-                            "voted_models": [self.client.model],
-                            "rationale": "Verified in headless pipeline.",
-                        },
-                    }
-                    for f in chunk
-                ]
+                # No verdicts: merge_findings.py lists these findings under
+                # coverage.findings_without_verification instead of confirming them
+                self._parse_failed("5-finding-verifier", f"verified-{(idx // batch_size) + 1}", reply)
+                verifs = []
 
             verif_doc = {
                 "batch_id": f"verified-{(idx // batch_size) + 1}",

package/operate/cli/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "2.0.0"  # x-release-please-version
+__version__ = "2.1.0"  # x-release-please-version

package/operate/cli/commands/scan.py

@@ -455,7 +455,7 @@ def execute_scan(args: argparse.Namespace) -> int:
             f"  {color('🚀 Mode: Tier 2 Cognitive Multi-Agent Engine', GREEN, BOLD)} "
             f"(Headless BYO-LLM: {args.headless_ai}, Model: {args.model})"
         )
-        print(f"  {color('✔ Skeptic Consensus Applied', GREEN)}: Verified zero-false-positive findings against compensative controls.\n")
+        print(f"  {color('✔ Skeptic Consensus Applied', GREEN)}: Findings challenged against compensating controls.\n")
     else:
         print(f"  {color('💡 Mode: Tier 1 Deterministic Engine', CYAN, BOLD)} (Regex & AST candidate extraction, no LLM required)")
         print("  To run Tier 2 Cognitive Multi-Agent Audit (BOLA semantic reasoning & Skeptic Verifier):")

package/operate/tests/test_ai_anchoring.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Finding locations anchored to Tier 1 routes / candidates, and one retry on empty replies (#319)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+from operate.ai.anchoring import AnchorReport, anchor_findings, load_anchors
+from operate.ai.runner import HeadlessAIRunner
+
+
+def _write(path: Path, data: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data) if not isinstance(data, str) else data, encoding="utf-8")
+
+
+class TestAnchoring(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="komagu_anchor_"))
+        self.target, self.out = self.tmp / "repo", self.tmp / "out"
+        _write(self.target / "node-express/routes/admin.js", "\n".join(f"// line {i}" for i in range(1, 21)) + "\n")
+        _write(self.target / "python-flask/profile.py", "\n".join(f"# line {i}" for i in range(1, 31)) + "\n")
+        _write(self.out / "routes/routes-001.json", {"routes": [
+            {"route_id": "R-1", "handler": {"file": "node-express/routes/admin.js", "line": 8}},
+            {"route_id": "R-2", "handler": {"file": "node-express/routes/admin.js", "line": 12}},
+            {"route_id": "R-3", "handler": {"file": "node-express/routes/admin.js", "line": 16}}]})
+        _write(self.out / "mass-assignment.candidates.json", {"candidates": [
+            {"candidate_id": "M-14", "file": "python-flask/profile.py", "line": 10}]})
+        self.anchors = load_anchors(self.out, self.target)
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def run_one(self, finding: dict) -> tuple:
+        report = AnchorReport()
+        return anchor_findings([finding], self.anchors, self.target, report)[0], report
+
+    def test_handler_spans_end_before_the_next_route(self) -> None:
+        self.assertEqual((self.anchors["R-1"].line, self.anchors["R-1"].end_line), (8, 11))
+        self.assertEqual((self.anchors["R-3"].line, self.anchors["R-3"].end_line), (16, 20))
+
+    def test_wrong_path_with_line_in_span_keeps_the_line(self) -> None:
+        f, report = self.run_one({"finding_id": "BFLA-R-1-1", "route_id": "R-1",
+                                  "location": {"file": "routes.js", "start_line": 9},
+                                  "evidence": [{"file": "routes.js", "line": 9, "why": "no role check"}]})
+        self.assertEqual(f["location"], {"file": "node-express/routes/admin.js", "start_line": 9})
+        self.assertEqual(f["evidence"], [{"file": "node-express/routes/admin.js", "line": 9, "why": "no role check"}])
+        self.assertEqual(report.moved, ["BFLA-R-1-1"])
+
+    def test_line_outside_span_falls_back_to_handler(self) -> None:
+        f, _ = self.run_one({"finding_id": "BFLA-R-1-1", "route_id": "R-1",
+                             "location": {"file": "node-express/routes/admin.js", "start_line": 17}})
+        self.assertEqual(f["location"]["start_line"], 8)
+
+    def test_candidate_finding_takes_candidate_site(self) -> None:
+        f, _ = self.run_one({"finding_id": "MASS-M-14-1", "candidate_id": "M-14",
+                             "location": {"file": "app.py", "start_line": 8, "end_line": 9},
+                             "evidence": [{"file": "app.py", "line": 8, "why": "binds request body"}]})
+        self.assertEqual(f["location"], {"file": "python-flask/profile.py", "start_line": 10})
+        self.assertEqual(f["evidence"][0]["file"], "python-flask/profile.py")
+
+    def test_correct_location_is_not_reported_as_moved(self) -> None:
+        f, report = self.run_one({"finding_id": "BFLA-R-2-1", "route_id": "R-2",
+                                  "location": {"file": "node-express/routes/admin.js", "start_line": 13}})
+        self.assertEqual(f["location"]["start_line"], 13)
+        self.assertEqual((report.moved, report.unanchored), ([], []))
+
+    def test_unknown_reference_is_unanchored_and_low_confidence(self) -> None:
+        f, report = self.run_one({"finding_id": "BFLA-R-9-1", "route_id": "R-9", "confidence": "high",
+                                  "location": {"file": "x.js", "start_line": 1}})
+        self.assertEqual(f["location"], {"file": "x.js", "start_line": 1})
+        self.assertEqual(f["confidence"], "low")
+        self.assertEqual(report.unanchored, ["BFLA-R-9-1"])
+
+    def test_input_is_not_mutated(self) -> None:
+        original = {"finding_id": "BFLA-R-1-1", "route_id": "R-1", "location": {"file": "routes.js", "start_line": 9}}
+        snapshot = json.dumps(original, sort_keys=True)
+        self.run_one(original)
+        self.assertEqual(json.dumps(original, sort_keys=True), snapshot)
+
+
+class TestModelSource(unittest.TestCase):
+    """The privilege auditor sees the bound model's fields, from the same app and language (#319)."""
+
+    def setUp(self) -> None:
+        from operate.ai.runner import _model_source
+        self.model_source = _model_source
+        self.tmp = Path(tempfile.mkdtemp(prefix="komagu_model_"))
+        _write(self.tmp / "java-legacy/src/model/Account.java", "public class Account {\n    private String role;\n}\n")
+        _write(self.tmp / "java-legacy/src/web/ProfileServlet.java",
+               "class ProfileServlet {\n  void post() {\n    Account account = new Account();\n    BeanUtils.populate(account, params);\n  }\n}\n")
+        _write(self.tmp / "php-laravel/app/Models/User.php", "<?php\nclass User extends Model {\n  protected $guarded = [];\n}\n")
+        _write(self.tmp / "node-express/routes/profile.js", "router.post('/p', (req, res) => User.update(req.body));\n")
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_target_class_is_found_with_its_fields(self) -> None:
+        m = self.model_source(self.tmp, "Account", "java-legacy/src/web/ProfileServlet.java", 4)
+        self.assertEqual(m["file"], "java-legacy/src/model/Account.java")
+        self.assertIn("private String role", m["code"])
+
+    def test_class_is_inferred_from_new_near_the_binding(self) -> None:
+        m = self.model_source(self.tmp, None, "java-legacy/src/web/ProfileServlet.java", 4)
+        self.assertEqual((m["class"], m["file"]), ("Account", "java-legacy/src/model/Account.java"))
+
+    def test_other_app_or_language_is_not_used(self) -> None:
+        m = self.model_source(self.tmp, "User", "node-express/routes/profile.js", 1)
+        self.assertEqual((m["class"], m["file"]), ("User", None))
+        self.assertIn("not found", m["code"])
+
+    def test_unknown_target_without_new_gives_none(self) -> None:
+        self.assertIsNone(self.model_source(self.tmp, None, "node-express/routes/profile.js", 1))
+        self.assertIsNone(self.model_source(self.tmp, "../etc", "node-express/routes/profile.js", 1))
+
+
+class _ScriptedClient:
+    """Returns the scripted replies in order; an Exception item is raised."""
+
+    model = "scripted"
+    endpoint = "test://"
+
+    def __init__(self, replies: list) -> None:
+        self.replies = list(replies)
+        self.calls: list = []
+
+    def chat(self, messages, temperature=0.1):  # noqa: ANN001
+        self.calls.append(messages)
+        item = self.replies.pop(0)
+        if isinstance(item, Exception):
+            raise item
+        return item
+
+    @staticmethod
+    def extract_json(content: str):  # noqa: ANN205
+        from operate.ai.client import LLMClient
+        return LLMClient.extract_json(content)
+
+
+class TestRetry(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp(prefix="komagu_retry_"))
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def runner(self, replies: list) -> HeadlessAIRunner:
+        return HeadlessAIRunner(self.tmp, self.tmp / "out", _ScriptedClient(replies))
+
+    def test_empty_reply_is_retried_once(self) -> None:
+        r = self.runner(["", '{"findings": []}'])
+        self.assertEqual(r._chat("4a-bola-auditor", "routes-001", [{"role": "user", "content": "audit"}]), '{"findings": []}')
+        self.assertEqual(r.retries, {"4a-bola-auditor": ["routes-001"]})
+        retry = r.client.calls[1]
+        self.assertEqual([m["role"] for m in retry], ["user", "user"])  # no empty assistant turn
+        self.assertIn("JSON object only", retry[-1]["content"])
+
+    def test_unparseable_reply_is_retried_with_its_text(self) -> None:
+        r = self.runner(["looks fine to me", '{"findings": []}'])
+        r._chat("4c-privilege-auditor", "privilege-001", [{"role": "user", "content": "audit"}])
+        self.assertEqual([m["role"] for m in r.client.calls[1]], ["user", "assistant", "user"])
+
+    def test_second_bad_reply_keeps_the_first_text(self) -> None:
+        r = self.runner(["looks fine to me", "still not json"])
+        self.assertEqual(r._chat("5-finding-verifier", "verified-1", [{"role": "user", "content": "v"}]), "looks fine to me")
+
+    def test_good_reply_is_not_retried(self) -> None:
+        r = self.runner(['{"findings": []}'])
+        r._chat("4a-bola-auditor", "routes-001", [{"role": "user", "content": "audit"}])
+        self.assertEqual((len(r.client.calls), r.retries), (1, {}))
+
+    def test_failed_call_is_not_retried(self) -> None:
+        r = self.runner([RuntimeError("timed out")])
+        self.assertIsNone(r._chat("4b-injection-auditor", "injection-001", [{"role": "user", "content": "i"}]))
+        self.assertEqual((len(r.client.calls), r.retries), (1, {}))
+        self.assertEqual(r.call_errors, {"4b-injection-auditor": {"injection-001": "timed out"}})
+
+
+if __name__ == "__main__":
+    unittest.main()