branover
diff --git a/‎docs/mcp.md‎
Lines changed: 8 additions & 4 deletions b/‎docs/mcp.md‎
Lines changed: 8 additions & 4 deletions
diff --git a/‎scripts/ci_ghidra_decompile_check.py‎
Lines changed: 24 additions & 5 deletions b/‎scripts/ci_ghidra_decompile_check.py‎
Lines changed: 24 additions & 5 deletions
diff --git a/‎src/hexgraph/agent/agent_tools.py‎
Lines changed: 50 additions & 22 deletions b/‎src/hexgraph/agent/agent_tools.py‎
Lines changed: 50 additions & 22 deletions
diff --git a/‎src/hexgraph/engine/re/analysis.py‎
Lines changed: 22 additions & 0 deletions b/‎src/hexgraph/engine/re/analysis.py‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎src/hexgraph/engine/re/emulation.py‎
Lines changed: 19 additions & 5 deletions b/‎src/hexgraph/engine/re/emulation.py‎
Lines changed: 19 additions & 5 deletions
diff --git a/‎src/hexgraph/engine/re/taint.py‎
Lines changed: 11 additions & 0 deletions b/‎src/hexgraph/engine/re/taint.py‎
Lines changed: 11 additions & 0 deletions
@@ -165,8 +165,10 @@ already state, and `meta_get_schemas` spells out in its `substrate_vs_graph` and
   reference index, the same analyze-once project the decompile verbs build, instead of re-analyzing the
   whole binary on every call. On a large target that is the difference between an instant answer and a query
   that never finishes, and an unknown symbol comes back as "not found" right away rather than after a long
-  wait. With the radare2 backend, or before a first analysis has warmed the project, the verbs fall back to
-  a fresh cross-reference pass.
+  wait. The radare2 backend works the same way: the verbs reload the warm r2 project's own index rather than
+  re-running a whole-binary pass. Either way, until a first analysis has warmed the project they point you at
+  `re_analyze` instead of quietly analyzing (see the next point) — no per-call verb ever launches a cold pass
+  of its own.
 - **Analysis is explicit — `re_analyze` first, then the per-call verbs.** The whole-program tools
   (`re_decompile_function`/`re_decompile_at`, `re_list_functions`, and the xref family
   `re_xrefs`/`re_function_xrefs`/`re_data_xrefs`/`re_call_graph`) **require a saved analysis**: on a warm
@@ -176,8 +178,10 @@ already state, and `meta_get_schemas` spells out in its `substrate_vs_graph` and
   generous, size-scaled budget, so it finishes and commits the warm project. It's **single-flight** (a second
   `re_analyze` of the same target attaches to the running one, never a duplicate) and idempotent: re-call it to
   poll (`state` walks `none → running → analyzed`), and once `analyzed` every gated verb is instant.
-  `re_disassemble` (targeted) and `re_search_decompiled` (reads the store) need no whole-program analysis and
-  are never gated. This is **backend-aware**: it covers both headless Ghidra (a warm Ghidra project) and
+  `re_recover_constant` (P-Code emulation) and the `static_analysis` taint pass gate the same way — they run
+  the deeper analysis over the warm project, so on a cold target they return the `re_analyze` lead rather than
+  analyzing themselves. `re_disassemble` (targeted) and `re_search_decompiled` (reads the store) need no
+  whole-program analysis and are never gated. This is **backend-aware**: it covers both headless Ghidra (a warm Ghidra project) and
   radare2 (a warm r2 project, reclaimable via `hexgraph prune --r2-cache-mb`), each with its own persistent
   slot. Only the Ghidra *bridge* backend — which attaches to a Ghidra you already have open — has nothing to
   build here, so it reports `unavailable` and isn't gated.
 
@@ -31,6 +31,7 @@
 from __future__ import annotations
 
 import sys
+import tempfile
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -65,13 +66,30 @@ def main() -> int:
         _fail(f"could not import hexgraph (install the package in this job): {exc}")
 
     runner = SandboxRunner(image=image)
+
+    # Analysis is WARM-ONLY now (the invariant: only re_analyze runs a full analysis). Build the warm
+    # Ghidra project ONCE via `--analyze` into a bind-mounted slot, then drive decompile + xrefs
+    # against THAT warm project — exactly the production shape (re_analyze → warm per-call verbs). A
+    # per-run temp slot; CI is ephemeral, so no cleanup needed. This ALSO exercises the `--analyze`
+    # detached-analysis path end to end under production hardening.
+    proj = tempfile.mkdtemp(prefix="ci-ghidra-slot-")
+    try:
+        warm = runner.run_json_probe("ghidra_probe.py", str(fixture),
+                                     extra_args=["--analyze"], project_mount=proj)
+    except SandboxError as exc:
+        _fail(f"ghidra --analyze (warm-project build) failed under production hardening: {exc}")
+    if isinstance(warm, dict) and warm.get("error"):
+        _fail(f"ghidra --analyze reported an error: {warm['error']}")
+
     try:
         # run_json_probe == run_probe + json.loads of stdout, the same call GhidraDecompiler
         # makes. On a non-zero probe exit it raises SandboxError; ghidra_probe.py emits its
         # diagnostic (the analyzeHeadless log tail) on STDOUT as {"error": ...}, so surface
         # that too — the previous standalone gate printed only the empty stderr, hiding the
-        # cause (the launcher's "Failed to create directory" under --read-only).
-        result = runner.run_json_probe("ghidra_probe.py", str(fixture), extra_args=[FOCUS])
+        # cause (the launcher's "Failed to create directory" under --read-only). WARM decompile
+        # against the project built above (project_mount=proj) — a cold decompile now refuses.
+        result = runner.run_json_probe("ghidra_probe.py", str(fixture),
+                                       extra_args=[FOCUS], project_mount=proj)
     except SandboxError as exc:
         # SandboxRunner raises on a non-zero probe exit and the SandboxError message carries
         # the probe's STDERR tail (runner._run: proc.stderr.strip()[:500]); it does NOT carry
@@ -115,11 +133,12 @@ def main() -> int:
     # REAL Ghidra: this is the reference-index query the re_xrefs / re_function_xrefs / re_call_graph
     # verbs serve from the warm project, and the offline tier has no Ghidra to run it. cgi_handler
     # does `strcpy(buf, token)`, so "who calls strcpy" (ReferenceManager.getReferencesTo, filtered
-    # to the containing function) MUST include cgi_handler. Drives the SAME production run_probe path
-    # (a cold throwaway project here, which still imports+analyzes then runs XREFS_SCRIPT).
+    # to the containing function) MUST include cgi_handler. Drives the SAME production run_probe path,
+    # served WARM from the project built above (project_mount=proj) — the reference index the re_xrefs
+    # family reuses, never a per-call re-analysis.
     try:
         xr = runner.run_json_probe("ghidra_probe.py", str(fixture),
-                                   extra_args=["--xrefs", "callers", "strcpy"])
+                                   extra_args=["--xrefs", "callers", "strcpy"], project_mount=proj)
     except SandboxError as exc:
         _fail(f"ghidra xrefs probe failed under production hardening: {exc}")
     if "error" in xr:
 
@@ -784,22 +784,13 @@ def _analysis_gate(ctx: ToolContext) -> str | None:
     entirely off `analysis_state` — backend-aware since C1b, so it gates BOTH headless Ghidra and
     radare2 (each with its own warm slot). `unavailable` (no persistent-slot backend — Ghidra bridge
     — / Docker down / no byte artifact) means "not gated, behave as before", so those paths are
-    unaffected. Best-effort: any error ⇒ don't gate."""
-    try:
-        from hexgraph.engine.re.analysis import analysis_state
+    unaffected. Best-effort: any error ⇒ don't gate.
 
-        st = analysis_state(ctx.project, ctx.target)
-    except Exception:  # noqa: BLE001 — a gate hiccup must never block a tool that could run
-        return None
-    state = st.get("state")
-    if state in ("analyzed", "unavailable"):
-        return None
-    lead = {"none": "No saved analysis for this target yet.",
-            "running": "A whole-binary analysis is already in progress.",
-            "failed": "The last analysis did not finish."}.get(state, "No saved analysis.")
-    return (f"{lead} Run re_analyze(target) first — it builds the warm analysis (a Ghidra or radare2 "
-            "project) ONCE with a generous budget (detached; re-call re_analyze to poll until "
-            f"state='analyzed'), then retry this tool and it'll be instant. [{st.get('detail', '')}]")
+    Delegates to `analysis.analysis_lead` — the SAME gate the tools that bypass run_tool
+    (recover_constant, the taint task) consult — so the two can never drift."""
+    from hexgraph.engine.re.analysis import analysis_lead
+
+    return analysis_lead(ctx.project, ctx.target)
 
 
 def run_tool(ctx: ToolContext, name: str, args: dict) -> str:
@@ -2056,12 +2047,40 @@ def fmt_group(group: dict) -> list[str]:
     return ctx.cache[key]
 
 
+def _r2_project_mount(ctx: ToolContext) -> str | None:
+    """The WARM r2-project slot root for this target, bind-mounted into xrefs_probe so it RELOADS the
+    analysis instead of re-running `aaa` (the invariant: only re_analyze analyzes). None when there's
+    no data dir / slot, or the active executor can't bind-mount the slot (the remote executor — the
+    slot lives on the LOCAL data dir; xrefs_probe then returns the re_analyze lead for the index modes,
+    and still scans raw for search). Best-effort; mirrors R2Decompiler._resolve_slot. Read-only reload
+    → no slot lock needed (never saves)."""
+    project = getattr(ctx, "project", None)
+    if project is None or not getattr(project, "data_dir", None):
+        return None
+    try:
+        from hexgraph.engine.re import r2_project as rp
+        from hexgraph.sandbox.executor import get_executor
+        from hexgraph.sandbox.runner import sandbox_image
+
+        ex = get_executor()
+        if not getattr(ex, "supports_project_mount", True):
+            return None  # remote executor: run_probe refuses a project_mount — degrade, don't error
+        sha = rp.content_hash(ctx.target.path)
+        version = rp.r2_version_for_image(sandbox_image(), runner=ex)
+        slot = rp.resolve(project.data_dir, sha, version)
+        slot.prepare()
+        return str(slot.root)
+    except Exception:  # noqa: BLE001 — best-effort; a resolve failure reads as "no warm slot"
+        return None
+
+
 def _run_xrefs_probe(ctx: ToolContext, subject: str | None, mode: str):
     """Run a breadth xrefs query in `mode`, returning (out, error_text). Prefers the warm persistent
     Ghidra project's reference index when headless Ghidra is active (analyze-once, fast on a large
     target where the cold r2 sweep times out); falls back to the r2 xrefs_probe (`--mode
-    function|data|callgraph`) only when Ghidra can't run. `mode="callers"` passes no --mode flag on
-    the r2 path (legacy compat)."""
+    function|data|callgraph`) only when Ghidra can't run. The r2 probe is WARM-ONLY too — it RELOADS
+    the persistent r2 project (bind-mounted) and NEVER runs `aaa`; a cold slot returns the re_analyze
+    lead. `mode="callers"` passes no --mode flag on the r2 path (legacy compat)."""
     if _ghidra_xrefs_active():
         out = _ghidra_xrefs(ctx, mode, subject)
         if out is not None:
@@ -2073,10 +2092,17 @@ def _run_xrefs_probe(ctx: ToolContext, subject: str | None, mode: str):
         return None, f"{mode} unavailable (Docker/sandbox not running)"
     extra = ([subject] if subject else []) + (["--mode", mode] if mode != "callers" else [])
     try:
-        return get_executor().run_json_probe("xrefs_probe.py", ctx.target.path,
-                                             extra_args=extra or None), None
+        out = get_executor().run_json_probe("xrefs_probe.py", ctx.target.path,
+                                            extra_args=extra or None,
+                                            project_mount=_r2_project_mount(ctx))
     except Exception as exc:  # noqa: BLE001
         return None, f"{mode} xrefs failed: {exc}"
+    # A warm-MISS payload carries the re_analyze lead (a cold index mode, e.g. reached with the
+    # run_tool gate reporting `unavailable`). Surface it as the error so EVERY caller (function/data
+    # xrefs, call graph) points at re_analyze instead of formatting an empty result.
+    if isinstance(out, dict) and out.get("needs_analysis") and out.get("error"):
+        return None, out["error"]
+    return out, None
 
 
 def _recon_function_xrefs(ctx: ToolContext, function: str) -> tuple[list[str], list[str]]:
@@ -2406,14 +2432,16 @@ def _ghidra_search(ctx: ToolContext, *, bytes_pat, immediate) -> dict | None:
 
 def _r2_search(ctx: ToolContext, *, bytes_pat, immediate):
     """The radare2 raw-scan fallback (`xrefs_probe --mode search`, `/xj`//`/vj`) for when Ghidra
-    can't answer. The probe no longer runs a whole-binary `aaa` for a search, so it's fast (function
-    mapping best-effort from the symbol table). Returns the probe dict, or a string error message."""
+    can't answer. The probe never runs a whole-binary `aaa` for a search, so it's fast; passing the
+    warm r2 project (when one exists) lets it map hits to the containing function. Returns the probe
+    dict, or a string error message."""
     from hexgraph.sandbox.executor import get_executor
 
     extra = ["--mode", "search"] + (["--bytes", str(bytes_pat)] if bytes_pat
                                     else ["--imm", str(immediate)])
     try:
-        return get_executor().run_json_probe("xrefs_probe.py", ctx.target.path, extra_args=extra)
+        return get_executor().run_json_probe("xrefs_probe.py", ctx.target.path, extra_args=extra,
+                                             project_mount=_r2_project_mount(ctx))
     except Exception as exc:  # noqa: BLE001
         return f"search_code scan failed: {exc}"
 
 
@@ -193,6 +193,28 @@ def analysis_state(project, target, *, runner=None) -> dict:
                                        "build it", "container": name}
 
 
+def analysis_lead(project, target, *, runner=None) -> str | None:
+    """A re_analyze lead when `target` has NO saved analysis for the active backend, else None
+    (proceed). `analyzed` → None; `unavailable` (Ghidra-bridge / Docker down / no byte artifact) →
+    None too, since those paths serve warm anyway or can't be gated. This is the single host-side
+    gate for the analysis-needing tools/tasks that DON'T go through agent_tools.run_tool's gate
+    (recover_constant, the taint task) — so, like every per-call tool, they point at re_analyze on a
+    cold target instead of triggering a full analysis themselves. Best-effort: any error ⇒ None."""
+    try:
+        st = analysis_state(project, target, runner=runner)
+    except Exception:  # noqa: BLE001 — a gate hiccup must never block a tool that could run
+        return None
+    state = st.get("state")
+    if state in ("analyzed", "unavailable"):
+        return None
+    lead = {"none": "No saved analysis for this target yet.",
+            "running": "A whole-binary analysis is already in progress.",
+            "failed": "The last analysis did not finish."}.get(state, "No saved analysis.")
+    return (f"{lead} Run re_analyze(target) first — it builds the warm analysis ONCE with a generous "
+            "budget (detached; re-call re_analyze to poll until state='analyzed'), then retry this — "
+            f"it's warm-only and never runs a cold analysis itself. [{st.get('detail', '')}]")
+
+
 def start_analysis(project, target, *, runner=None) -> dict:
     """Start OR attach to a detached whole-binary analysis for the ACTIVE backend. Idempotent and
     single-flight: already-warm ⇒ no-op ``analyzed``; already-running ⇒ ``running`` (attach);
 
@@ -92,18 +92,32 @@ def emulate_constant(session: Session, project: Any, target: Any, *, function: s
                 "reached_ret": False, "steps": None, "observation_id": None,
                 "error": "emulation requires the Ghidra headless decompiler (features.ghidra)"}
 
-    # PRE-CHECK: skip the doomed run for an argument-dependent routine. If a prior decompile
-    # recorded the recovered signature on the function node and it takes arguments, emulating
-    # it over uninitialized inputs won't reach a clean ret — return an informative result
-    # instead of burning a sandbox emulation. (No recorded signature ⇒ fall through and let
-    # the emulation's own in-probe arg guard decide; we never fabricate.)
+    # PRE-CHECK (first — a pure graph read, triggers NO analysis): skip the doomed run for an
+    # argument-dependent routine. If a prior decompile recorded the recovered signature on the
+    # function node and it takes arguments, emulating it over uninitialized inputs won't reach a clean
+    # ret — return an informative result (pointing at the solver) instead of burning a sandbox
+    # emulation. This is the MORE actionable answer than "needs_analysis" (re_analyze won't make an
+    # arg-dependent routine emulable), AND a recorded signature implies analysis already ran. (No
+    # recorded signature ⇒ fall through to the analysis gate; we never fabricate.)
     arg_count = _recovered_arg_count(session, project, target, function)
     if arg_count and arg_count > 0:
         return {"available": True, "function": function, "value": None, "value_hex": None,
                 "reached_ret": False, "steps": 0, "observation_id": None,
                 "skipped": "arg_dependent", "param_count": arg_count,
                 "error": _ARG_DEPENDENT_HINT}
 
+    # ANALYSIS GATE: recover_constant is invoked directly (it bypasses run_tool's gate), so gate it
+    # HERE — on a cold target with no warm project it must point at re_analyze, NEVER cold-analyze
+    # (the invariant: only re_analyze runs a full analysis). A live bridge / warm slot reads as
+    # 'analyzed'|'unavailable' → proceeds and serves it warm.
+    from hexgraph.engine.re.analysis import analysis_lead
+
+    _lead = analysis_lead(project, target)
+    if _lead:
+        return {"available": True, "function": function, "value": None, "value_hex": None,
+                "reached_ret": False, "steps": None, "observation_id": None,
+                "skipped": "needs_analysis", "error": _lead}
+
     from hexgraph.engine import observations as obs
     from hexgraph.engine.graph.nodes import get_or_create_node
     from hexgraph.sandbox.decompiler import ghidra_op_backend
 
@@ -137,6 +137,17 @@ def analyze_taint(session: Session, project: Any, target: Any, *,
         return {"available": False, "flows": [], "analyzed": 0,
                 "promoted": promoted, "observation_id": None, "cached": False, "error": None}
 
+    # ANALYSIS GATE (the invariant): the Ghidra taint pass needs the warm project — on a cold target
+    # point at re_analyze instead of cold-analyzing (the static_analysis task reaches here outside
+    # run_tool's gate). A live bridge / warm slot reads as analyzed → proceeds.
+    if isinstance(analyzer, GhidraTaintAnalyzer):
+        from hexgraph.engine.re.analysis import analysis_lead
+
+        _lead = analysis_lead(project, target)
+        if _lead:
+            return {"available": False, "flows": [], "analyzed": 0, "promoted": promoted,
+                    "observation_id": None, "cached": False, "error": _lead}
+
     result = analyzer.analyze(path, project=project)
     flows = result.get("flows") or []
     status = "error" if result.get("error") else "ok"