From 02a1548512e3eb27e1a76a467d12b71751373828 Mon Sep 17 00:00:00 2001
From: ghangz <152254226+ghangz@users.noreply.github.com>
Date: Wed, 1 Jul 2026 11:41:56 +0800
Subject: [PATCH 1/2] Add FlashMLA runtime path audit

---
 tools/runtime_path_audit.py | 56 +++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 tools/runtime_path_audit.py

diff --git a/tools/runtime_path_audit.py b/tools/runtime_path_audit.py
new file mode 100644
index 00000000..7ccb8f6b
--- /dev/null
+++ b/tools/runtime_path_audit.py
@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Audit MACA-related path variables for missing, duplicate, and stale entries."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+ENV_VARS = ['MACA_HOME', 'LD_LIBRARY_PATH', 'PYTHONPATH']
+
+
+def split_paths(value: str) -> list[str]:
+    parts: list[str] = []
+    for chunk in value.replace(";", os.pathsep).split(os.pathsep):
+        chunk = chunk.strip()
+        if chunk:
+            parts.append(chunk)
+    return parts
+
+
+def audit(env: dict[str, str]) -> dict[str, object]:
+    findings: list[dict[str, str]] = []
+    for name in ENV_VARS:
+        seen: set[str] = set()
+        for raw in split_paths(env.get(name, "")):
+            normalized = str(Path(raw))
+            if normalized in seen:
+                findings.append({"env": name, "path": raw, "severity": "warning", "message": "duplicate path entry"})
+            seen.add(normalized)
+            if not Path(raw).exists():
+                findings.append({"env": name, "path": raw, "severity": "info", "message": "path does not exist in this container"})
+    return {"finding_count": len(findings), "findings": findings}
+
+
+def self_test() -> None:
+    missing = os.pathsep.join(["/definitely_missing", "/definitely_missing"])
+    data = audit({"LD_LIBRARY_PATH": missing})
+    assert data["finding_count"] >= 2
+    print(json.dumps({"ok": True, "finding_count": data["finding_count"]}, ensure_ascii=False))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--self-test", action="store_true")
+    args = parser.parse_args()
+    if args.self_test:
+        self_test()
+        return 0
+    print(json.dumps(audit(dict(os.environ)), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 8a306a314bebc1990603ce1b8c6fb9fb042ff3fc Mon Sep 17 00:00:00 2001
From: ghangz <152254226+ghangz@users.noreply.github.com>
Date: Wed, 1 Jul 2026 15:36:52 +0800
Subject: [PATCH 2/2] Address PR review feedback

- Add FlashMLA runtime path audit
- Normalize runtime path audit entries
---
 tools/runtime_path_audit.py | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/tools/runtime_path_audit.py b/tools/runtime_path_audit.py
index 7ccb8f6b..60443555 100644
--- a/tools/runtime_path_audit.py
+++ b/tools/runtime_path_audit.py
@@ -8,7 +8,7 @@
 import os
 from pathlib import Path
 
-ENV_VARS = ['MACA_HOME', 'LD_LIBRARY_PATH', 'PYTHONPATH']
+ENV_VARS = ["MACA_HOME", "LD_LIBRARY_PATH", "PYTHONPATH"]
 
 
 def split_paths(value: str) -> list[str]:
@@ -20,25 +20,48 @@ def split_paths(value: str) -> list[str]:
     return parts
 
 
+def normalize_path(raw: str) -> str:
+    return os.path.normpath(os.path.abspath(os.path.expanduser(raw)))
+
+
 def audit(env: dict[str, str]) -> dict[str, object]:
     findings: list[dict[str, str]] = []
     for name in ENV_VARS:
         seen: set[str] = set()
         for raw in split_paths(env.get(name, "")):
-            normalized = str(Path(raw))
+            normalized = normalize_path(raw)
             if normalized in seen:
-                findings.append({"env": name, "path": raw, "severity": "warning", "message": "duplicate path entry"})
+                findings.append(
+                    {
+                        "env": name,
+                        "path": raw,
+                        "severity": "warning",
+                        "message": "duplicate path entry",
+                    }
+                )
             seen.add(normalized)
-            if not Path(raw).exists():
-                findings.append({"env": name, "path": raw, "severity": "info", "message": "path does not exist in this container"})
+            if not Path(normalized).exists():
+                findings.append(
+                    {
+                        "env": name,
+                        "path": raw,
+                        "severity": "info",
+                        "message": "path does not exist in this container",
+                    }
+                )
     return {"finding_count": len(findings), "findings": findings}
 
 
 def self_test() -> None:
     missing = os.pathsep.join(["/definitely_missing", "/definitely_missing"])
     data = audit({"LD_LIBRARY_PATH": missing})
-    assert data["finding_count"] >= 2
-    print(json.dumps({"ok": True, "finding_count": data["finding_count"]}, ensure_ascii=False))
+    if data["finding_count"] < 2:
+        raise RuntimeError(f"self-test failed: {data}")
+    print(
+        json.dumps(
+            {"ok": True, "finding_count": data["finding_count"]}, ensure_ascii=False
+        )
+    )
 
 
 def main() -> int: