AI completed

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV OFFLINE_INFERENCE=1
+
+CMD ["python", "inference.py", "--max-steps", "8", "--policy-mode", "imp", "--trajectories", "4", "--force-local-env"]

README.md

@@ -1 +1,217 @@
-# RL_Mini_Project
+# CI/CD Pipeline Debugger Environment (OpenEnv)
+
+## 1. Project Goal
+
+This repository implements an AI training and evaluation environment where an agent learns to debug broken CI/CD pipelines automatically.
+
+The environment targets real-world DevOps failure patterns, including:
+
+- YAML syntax and structure issues
+- Incorrect build/test commands (for example, npm tset -> npm test)
+- Dependency and setup failures
+- Multi-stage pipeline execution errors
+
+This is designed as an RL-style interaction loop:
+
+Observe -> Think -> Act -> Get Reward -> Repeat
+
+## 2. Why This Matters
+
+CI/CD failures are common, repetitive, and often multi-step to resolve. This project turns that workflow into a structured learning environment where agents:
+
+- Read failure context
+- Reason about root causes
+- Propose and apply fixes
+- Get shaped rewards for robust behavior
+
+## 3. System Architecture
+
+High-level flow:
+
+Agent (LLM) -> Action -> Environment.step() -> Reward/Evaluation -> Next step
+
+Core integration path:
+
+Model -> Action -> Environment.step() -> RewardCalculator
+
+RewardCalculator integrates:
+
+- DeterministicGrader
+- LLMJudge
+- HiddenTestRunner
+- AntiHackingDetector
+
+## 4. Core Modules
+
+### 4.1 Quality Judge
+
+- File: env/graders/llm_judge.py
+- Purpose: quality-aware scoring of fixes
+- Output keys: correctness, minimalism, quality (all in [0,1])
+- Guarantees:
+	- strict JSON parsing attempt
+	- robust fallback parsing for messy output
+	- no-crash behavior (safe zero scores on failure)
+
+### 4.2 Deterministic Grader
+
+- File: env/graders/deterministic.py
+- Purpose: reproducible correctness scoring (0-1)
+- Checks:
+	- YAML validity
+	- command and fix correctness
+	- similarity and issue resolution
+- Rules:
+	- deterministic only
+	- same input, same score
+
+### 4.3 Anti-Hacking Detector
+
+- File: env/anti_hacking.py
+- Purpose: detect reward-hacking and shortcut behavior
+- Penalty detectors:
+	- stage skipping (if: false, when: never)
+	- fake success (echo tests passed, unsafe exit 0 patterns)
+	- pipeline breakage between versions
+	- excessive edits
+	- timeout abuse via too many steps
+
+### 4.4 Hidden Tests
+
+- File: env/hidden_tests.py
+- Purpose: test fix robustness, not just exact-match overfitting
+- Method:
+	- deterministic variant generation (OS, versions, env shifts)
+	- evaluate pass rate across variants
+
+### 4.5 Reward Shaping
+
+- File: env/rewards.py
+- Purpose: step-level learning signal
+- Components:
+	- progress rewards (logs, analysis, fix proposal)
+	- execution rewards (pipeline run, tests pass)
+	- quality rewards (deterministic + hidden tests + LLM judge)
+	- anti-hacking penalties
+
+## 5. Inference and Evaluation
+
+### 5.1 Prompt and Model Layers
+
+- inference/prompts.py: stable prompt templates and fallback action heuristics
+- inference/model_wrapper.py: OpenAI-client action generation, candidate generation, and safe fallback
+
+### 5.2 Metrics and Artifacts
+
+- inference/metrics.py: reward, success-rate, and failure reason tracking
+- inference/visualize.py: reward curve and metrics artifact export
+
+### 5.3 Submission-Critical Runtime
+
+- File: inference.py (root)
+- Responsibilities:
+	- initialize model and environment
+	- run step loop
+	- calculate rewards
+	- emit strict stdout contract
+	- always emit END line
+
+Required output format:
+
+- [START] task=... env=... model=...
+- [STEP] step=<n> action=... reward=0.00 done=<true|false> error=<msg|null>
+- [END] success=<true|false> steps=<n> rewards=<r1,r2,...>
+
+Rules enforced:
+
+- single-line logs only
+- reward values with 2 decimals
+- lowercase booleans
+- no extra runtime log noise
+
+## 6. Task Coverage
+
+The project includes 13 CI-fix tasks spanning:
+
+- easy: syntax and typo fixes
+- medium: dependency/env/cache/permissions issues
+- hard: matrix logic, conditional flow, orchestration-level failures
+
+## 7. Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Environment variables:
+
+```bash
+export API_BASE_URL="https://router.huggingface.co/v1"
+export MODEL_NAME="Qwen/Qwen2.5-72B-Instruct"
+export HF_TOKEN="<your_token>"
+export LOCAL_IMAGE_NAME="<your_env_image_name>"
+```
+
+## 8. Run Inference
+
+Offline/local mode:
+
+```bash
+python inference.py --offline --force-local-env --max-steps 8 --policy-mode imp --trajectories 4
+```
+
+Model-backed mode:
+
+```bash
+python inference.py --max-steps 8 --policy-mode imp --trajectories 4
+```
+
+Policy modes:
+
+- sft: deterministic heuristic policy
+- direct: single model action per step
+- imp: multi-candidate generation and ranking
+
+## 9. Tests
+
+Run all tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Coverage includes:
+
+- LLM judge
+- deterministic grader
+- anti-hacking detectors
+- hidden tests
+- reward system
+- end-to-end inference output format
+
+## 10. Validation and Submission
+
+OpenEnv validation:
+
+```bash
+openenv validate
+```
+
+Pre-submission script:
+
+```bash
+./validate-submission.sh <your_hf_space_url>
+```
+
+Docker run:
+
+```bash
+docker build -t cicd-debugger-env .
+docker run --rm -e OFFLINE_INFERENCE=1 cicd-debugger-env
+```
+
+## 11. One-line Presentation Summary
+
+We built an OpenEnv-compliant reinforcement learning environment where AI agents learn to debug real CI/CD pipelines using multi-step reasoning, hybrid grading, anti-hacking safeguards, and robust reward shaping.

artifacts/metrics.json

@@ -0,0 +1,7 @@
+{
+  "average_reward": 1.84,
+  "failure_reasons": {},
+  "steps": 1,
+  "success_rate": 1.0,
+  "total_reward": 1.84
+}

artifacts/reward_curve.csv

@@ -0,0 +1,2 @@
+step,reward
+1,1.8400

artifacts/success_rate.csv

@@ -0,0 +1,2 @@
+episode,success,success_rate
+1,1,1.0000

env/__init__.py

@@ -0,0 +1,3 @@
+from env.rewards import RewardCalculator
+
+__all__ = ["RewardCalculator"]

env/anti_hacking.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+
+class AntiHackingDetector:
+    """Detects shortcut behaviors that can game CI-fix rewards."""
+
+    STAGE_SKIP_PATTERNS = (
+        r"\bif\s*:\s*false\b",
+        r"\bwhen\s*:\s*never\b",
+        r"\bon\s*:\s*\[\s*\]\b",
+        r"\bon\s*:\s*{}",
+        r"\ballow_failure\s*:\s*true\b",
+    )
+
+    FAKE_SUCCESS_PATTERNS = (
+        r"echo\s+[\"']?tests\s+passed[\"']?",
+        r"echo\s+[\"']?success[\"']?",
+        r"\bexit\s+0\b",
+        r"\btrue\b\s*#?\s*force",
+    )
+
+    BROKEN_COMMAND_PATTERNS = (
+        r"\bnpm\s+tset\b",
+        r"\bpyhton\b",
+        r"\bpip\s+isntall\b",
+        r"\bgo\s+tset\b",
+    )
+
+    def penalty_stage_skipping(self, config_text: str) -> float:
+        hits = self._count_hits(config_text, self.STAGE_SKIP_PATTERNS)
+        if hits == 0:
+            return 0.0
+        return -min(0.20 * hits, 0.70)
+
+    def penalty_fake_success(self, config_text: str) -> float:
+        hits = self._count_hits(config_text, self.FAKE_SUCCESS_PATTERNS)
+        if hits == 0:
+            return 0.0
+
+        normalized = (config_text or "").lower()
+        has_real_test_cmd = any(token in normalized for token in ("npm test", "pytest", "go test", "mvn test", "yarn test", "pnpm test"))
+        base = 0.15 if has_real_test_cmd else 0.25
+        return -min(base * hits, 0.70)
+
+    def penalty_breaking_pipeline(self, previous_config: str, new_config: str) -> float:
+        if not previous_config or not new_config:
+            return 0.0
+
+        penalty = 0.0
+
+        previous_valid = self._is_yaml_valid(previous_config)
+        new_valid = self._is_yaml_valid(new_config)
+        if previous_valid and not new_valid:
+            penalty -= 0.40
+
+        previous_stages = self._extract_stage_names(previous_config)
+        new_stages = self._extract_stage_names(new_config)
+        missing_stages = previous_stages - new_stages
+        if missing_stages:
+            penalty -= min(0.15 * len(missing_stages), 0.45)
+
+        previous_broken = self._count_hits(previous_config, self.BROKEN_COMMAND_PATTERNS)
+        new_broken = self._count_hits(new_config, self.BROKEN_COMMAND_PATTERNS)
+        if new_broken > previous_broken:
+            penalty -= min(0.10 * (new_broken - previous_broken), 0.30)
+
+        return max(-1.0, penalty)
+
+    def penalty_excessive_edits(
+        self,
+        edit_count: int | dict[str, Any] | None = None,
+        changed_files_count: int = 0,
+        changed_lines_count: int = 0,
+    ) -> float:
+        if isinstance(edit_count, dict):
+            changed_files_count = int(edit_count.get("changed_files_count", changed_files_count) or 0)
+            changed_lines_count = int(edit_count.get("changed_lines_count", changed_lines_count) or 0)
+        elif isinstance(edit_count, int):
+            changed_lines_count = max(changed_lines_count, int(edit_count))
+
+        penalty = 0.0
+
+        if changed_files_count > 5:
+            penalty -= 0.15
+        if changed_files_count > 10:
+            penalty -= 0.25
+
+        if changed_lines_count > 120:
+            penalty -= 0.15
+        if changed_lines_count > 300:
+            penalty -= 0.25
+
+        return max(-0.80, penalty)
+
+    def penalty_timeout_abuse(self, step_count: int) -> float:
+        if step_count > 30:
+            return -0.80
+        if step_count > 20:
+            return -0.50
+        return 0.0
+
+    def total_penalty(
+        self,
+        current_config: str = "",
+        previous_config: str = "",
+        edit_count: int | dict[str, Any] | None = None,
+        changed_files_count: int = 0,
+        changed_lines_count: int = 0,
+        step_count: int = 0,
+    ) -> float:
+        total = 0.0
+        total += self.penalty_stage_skipping(current_config)
+        total += self.penalty_fake_success(current_config)
+        total += self.penalty_breaking_pipeline(previous_config, current_config)
+        total += self.penalty_excessive_edits(
+            edit_count=edit_count,
+            changed_files_count=changed_files_count,
+            changed_lines_count=changed_lines_count,
+        )
+        total += self.penalty_timeout_abuse(step_count)
+
+        return round(total, 4)
+
+    def _count_hits(self, text: str, patterns: tuple[str, ...]) -> int:
+        text = text or ""
+        return sum(1 for pattern in patterns if re.search(pattern, text, flags=re.IGNORECASE))
+
+    def _is_yaml_valid(self, config_text: str) -> bool:
+        if not (config_text or "").strip():
+            return False
+        try:
+            yaml.safe_load(config_text)
+            return True
+        except yaml.YAMLError:
+            return False
+
+    def _extract_stage_names(self, config_text: str) -> set[str]:
+        try:
+            parsed = yaml.safe_load(config_text)
+        except yaml.YAMLError:
+            return set()
+
+        if parsed is None:
+            return set()
+
+        stages: set[str] = set()
+        self._walk_for_stages(parsed, stages)
+        return stages
+
+    def _walk_for_stages(self, node: Any, stages: set[str]) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                key_name = str(key).lower()
+                if key_name in {"stages", "jobs", "job"}:
+                    if isinstance(value, dict):
+                        for stage_name in value.keys():
+                            stages.add(str(stage_name))
+                    elif isinstance(value, list):
+                        for stage_name in value:
+                            stages.add(str(stage_name))
+                self._walk_for_stages(value, stages)
+        elif isinstance(node, list):
+            for item in node:
+                self._walk_for_stages(item, stages)

env/graders/__init__.py

@@ -0,0 +1,4 @@
+from env.graders.deterministic import DeterministicGrader
+from env.graders.llm_judge import LLMJudge
+
+__all__ = ["DeterministicGrader", "LLMJudge"]

env/graders/deterministic.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import re
+from difflib import SequenceMatcher
+from typing import Any
+
+import yaml
+
+
+class DeterministicGrader:
+    """Deterministic correctness scoring for CI/CD config fixes."""
+
+    COMMAND_KEYS = {
+        "script",
+        "scripts",
+        "run",
+        "command",
+        "commands",
+        "steps",
+        "before_script",
+        "after_script",
+    }
+
+    BROKEN_COMMAND_PATTERNS = (
+        r"\bnpm\s+tset\b",
+        r"\bpyhton\b",
+        r"\bpip\s+isntall\b",
+        r"\bgo\s+tset\b",
+    )
+
+    def grade(self, current_config: str, expected_config: str, metadata: dict[str, Any] | None = None) -> float:
+        metadata = metadata or {}
+        current_config = current_config or ""
+        expected_config = expected_config or ""
+
+        syntax_score = self._syntax_score(current_config)
+        functional_score = self._functional_score(current_config, expected_config, metadata)
+        similarity_score = self._similarity_score(current_config, expected_config)
+
+        total = (0.20 * syntax_score) + (0.60 * functional_score) + (0.20 * similarity_score)
+
+        if syntax_score == 0.0:
+            total = min(total, 0.30)
+
+        return round(self._clamp_01(total), 4)
+
+    def _syntax_score(self, config_text: str) -> float:
+        if not (config_text or "").strip():
+            return 0.0
+
+        try:
+            yaml.safe_load(config_text)
+            return 1.0
+        except yaml.YAMLError:
+            return 0.0
+
+    def _functional_score(self, current_config: str, expected_config: str, metadata: dict[str, Any]) -> float:
+        expected_commands = self._extract_commands(expected_config)
+        current_commands = self._extract_commands(current_config)
+
+        if expected_commands:
+            matched = 0
+            for expected in expected_commands:
+                if any(self._commands_match(expected, current) for current in current_commands):
+                    matched += 1
+            command_score = matched / len(expected_commands)
+        else:
+            command_score = self._similarity_score(current_config, expected_config)
+
+        issue_score = self._issue_resolution_score(current_config, metadata)
+        broken_penalty = 0.35 if self._has_known_broken_command(current_config) else 0.0
+
+        combined = (0.80 * command_score) + (0.20 * issue_score) - broken_penalty
+        return self._clamp_01(combined)
+
+    def _issue_resolution_score(self, current_config: str, metadata: dict[str, Any]) -> float:
+        broken_token = self._normalize_text(str(metadata.get("broken_token", "")))
+        fixed_token = self._normalize_text(str(metadata.get("fixed_token", "")))
+        current_normalized = self._normalize_text(current_config)
+
+        if not broken_token and not fixed_token:
+            return 1.0
+
+        if broken_token and broken_token in current_normalized:
+            return 0.0
+
+        if fixed_token and fixed_token not in current_normalized:
+            return 0.0
+
+        return 1.0
+
+    def _extract_commands(self, config_text: str) -> list[str]:
+        commands: list[str] = []
+
+        try:
+            parsed = yaml.safe_load(config_text)
+        except yaml.YAMLError:
+            parsed = None
+
+        if parsed is not None:
+            self._walk_yaml(parsed, commands)
+
+        if not commands:
+            commands.extend(self._extract_commands_from_text(config_text))
+
+        deduped: list[str] = []
+        seen: set[str] = set()
+        for command in commands:
+            normalized = self._normalize_text(command)
+            if normalized and normalized not in seen:
+                seen.add(normalized)
+                deduped.append(normalized)
+
+        return deduped
+
+    def _walk_yaml(self, node: Any, commands: list[str]) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                key_name = str(key).lower()
+                if key_name in self.COMMAND_KEYS:
+                    commands.extend(self._extract_string_values(value))
+                self._walk_yaml(value, commands)
+        elif isinstance(node, list):
+            for item in node:
+                self._walk_yaml(item, commands)
+
+    def _extract_string_values(self, value: Any) -> list[str]:
+        if isinstance(value, str):
+            return [value]
+        if isinstance(value, list):
+            return [item for item in value if isinstance(item, str)]
+        if isinstance(value, dict):
+            output: list[str] = []
+            for nested in value.values():
+                output.extend(self._extract_string_values(nested))
+            return output
+        return []
+
+    def _extract_commands_from_text(self, config_text: str) -> list[str]:
+        commands: list[str] = []
+
+        for raw_line in (config_text or "").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+
+            if ":" in line and not line.startswith("-") and line.endswith(":"):
+                continue
+
+            line = line.lstrip("-").strip()
+            if any(token in line.lower() for token in ("npm", "pytest", "python", "yarn", "pnpm", "go test", "mvn test")):
+                commands.append(line)
+
+        return commands
+
+    def _has_known_broken_command(self, config_text: str) -> bool:
+        return any(re.search(pattern, config_text or "", flags=re.IGNORECASE) for pattern in self.BROKEN_COMMAND_PATTERNS)
+
+    def _commands_match(self, expected: str, current: str) -> bool:
+        expected_normalized = self._normalize_text(expected)
+        current_normalized = self._normalize_text(current)
+
+        if expected_normalized == current_normalized:
+            return True
+
+        if expected_normalized in current_normalized:
+            return True
+
+        if current_normalized in expected_normalized and len(current_normalized) > 6:
+            return True
+
+        return False
+
+    def _similarity_score(self, current_config: str, expected_config: str) -> float:
+        left = self._normalize_text(current_config)
+        right = self._normalize_text(expected_config)
+
+        if not left and not right:
+            return 1.0
+        if not left or not right:
+            return 0.0
+
+        return self._clamp_01(SequenceMatcher(None, left, right).ratio())
+
+    def _normalize_text(self, value: str) -> str:
+        return re.sub(r"\s+", " ", (value or "")).strip().lower()
+
+    def _clamp_01(self, value: float) -> float:
+        return max(0.0, min(1.0, float(value)))

env/graders/llm_judge.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+class LLMJudge:
+    """Scores qualitative fix quality while remaining robust to bad model output."""
+
+    def __init__(self, model: Any):
+        self.model = model
+
+    def build_prompt(self, original_config: str, fixed_config: str, error_message: str) -> str:
+        return (
+            "You are a CI/CD fix quality judge.\n"
+            "Return strict JSON with keys correctness, minimalism, quality in [0,1].\n"
+            "No prose.\n\n"
+            f"Original config:\n{original_config}\n\n"
+            f"Fixed config:\n{fixed_config}\n\n"
+            f"Error message:\n{error_message}\n"
+        )
+
+    def evaluate_fix(self, original_config: str, fixed_config: str, error_message: str) -> dict[str, float]:
+        default = {
+            "correctness": 0.0,
+            "minimalism": 0.0,
+            "quality": 0.0,
+        }
+
+        if self.model is None:
+            return default
+
+        prompt = self.build_prompt(original_config or "", fixed_config or "", error_message or "")
+
+        try:
+            raw_output = self.model(prompt, max_length=300)
+            text = self._extract_text(raw_output)
+        except Exception:
+            return default
+
+        if not text.strip():
+            return default
+
+        parsed = self._parse_json_with_fallback(text)
+        if parsed is None:
+            parsed = self._parse_regex_scores(text)
+
+        return {
+            "correctness": self._clamp(parsed.get("correctness", 0.0) if parsed else 0.0),
+            "minimalism": self._clamp(parsed.get("minimalism", 0.0) if parsed else 0.0),
+            "quality": self._clamp(parsed.get("quality", 0.0) if parsed else 0.0),
+        }
+
+    def _extract_text(self, raw_output: Any) -> str:
+        if isinstance(raw_output, str):
+            return raw_output
+
+        if isinstance(raw_output, list) and raw_output:
+            first = raw_output[0]
+            if isinstance(first, dict):
+                for key in ("generated_text", "text", "content"):
+                    if key in first and first[key] is not None:
+                        return str(first[key])
+            return str(first)
+
+        if isinstance(raw_output, dict):
+            for key in ("generated_text", "text", "content"):
+                if key in raw_output and raw_output[key] is not None:
+                    return str(raw_output[key])
+
+        return str(raw_output)
+
+    def _parse_json_with_fallback(self, text: str) -> dict[str, float] | None:
+        decoder = json.JSONDecoder()
+        for idx, char in enumerate(text):
+            if char != "{":
+                continue
+            try:
+                obj, _ = decoder.raw_decode(text[idx:])
+            except json.JSONDecodeError:
+                continue
+            if isinstance(obj, dict):
+                return self._normalize_partial_scores(obj)
+        return None
+
+    def _parse_regex_scores(self, text: str) -> dict[str, float]:
+        return {
+            "correctness": self._extract_score(text, "correctness"),
+            "minimalism": self._extract_score(text, "minimalism"),
+            "quality": self._extract_score(text, "quality"),
+        }
+
+    def _extract_score(self, text: str, key: str) -> float:
+        match = re.search(rf"{key}\s*[:=\-]\s*([0-9]*\.?[0-9]+)", text, flags=re.IGNORECASE)
+        if not match:
+            return 0.0
+        return self._clamp(match.group(1))
+
+    def _normalize_partial_scores(self, obj: dict[str, Any]) -> dict[str, float]:
+        return {
+            "correctness": self._clamp(obj.get("correctness", 0.0)),
+            "minimalism": self._clamp(obj.get("minimalism", 0.0)),
+            "quality": self._clamp(obj.get("quality", 0.0)),
+        }
+
+    def _clamp(self, value: Any) -> float:
+        try:
+            parsed = float(value)
+        except (TypeError, ValueError):
+            parsed = 0.0
+        return max(0.0, min(1.0, parsed))

env/hidden_tests.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+from env.graders.deterministic import DeterministicGrader
+
+
+class HiddenTestRunner:
+    """Evaluates whether a fix generalizes across deterministic CI variants."""
+
+    def __init__(self, grader: DeterministicGrader | None = None, pass_threshold: float = 0.65):
+        self.grader = grader or DeterministicGrader()
+        self.pass_threshold = pass_threshold
+
+    def generate_variants(self, config_text: str) -> list[str]:
+        base = config_text or ""
+        variants: list[str] = []
+
+        for replacements in self._variant_replacement_sets():
+            variant = self._apply_replacements(base, replacements)
+            if variant not in variants:
+                variants.append(variant)
+
+        return variants
+
+    def evaluate_fix(
+        self,
+        fixed_config: str,
+        task: dict[str, Any] | None = None,
+        expected_config: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> float:
+        fixed_config = fixed_config or ""
+        task = task or {}
+        metadata = metadata or {}
+        expected = expected_config or str(task.get("expected_config", ""))
+
+        if not fixed_config.strip() or not expected.strip():
+            return 0.0
+
+        total = 0
+        passed = 0
+
+        for replacements in self._variant_replacement_sets():
+            fixed_variant = self._apply_replacements(fixed_config, replacements)
+            expected_variant = self._apply_replacements(expected, replacements)
+            score = self.grader.grade(fixed_variant, expected_variant, metadata)
+            total += 1
+            if score >= self.pass_threshold:
+                passed += 1
+
+        if total == 0:
+            return 0.0
+
+        return round(passed / total, 4)
+
+    def _variant_replacement_sets(self) -> list[tuple[tuple[str, str], ...]]:
+        return [
+            tuple(),
+            (("ubuntu-latest", "windows-latest"),),
+            (("windows-latest", "ubuntu-latest"),),
+            (("node-version: 16", "node-version: 18"),),
+            (("node-version: \"16\"", "node-version: \"18\""),),
+            (("python-version: \"3.10\"", "python-version: \"3.12\""),),
+            (("NODE_ENV=production", "NODE_ENV=development"),),
+        ]
+
+    def _apply_replacements(self, text: str, replacements: tuple[tuple[str, str], ...]) -> str:
+        output = text
+        for old, new in replacements:
+            output = output.replace(old, new)
+        return output

env/rewards.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from typing import Any
+
+from env.anti_hacking import AntiHackingDetector
+from env.graders.deterministic import DeterministicGrader
+from env.hidden_tests import HiddenTestRunner
+
+
+class RewardCalculator:
+    """Composes progress, execution, quality, and anti-hacking penalties."""
+
+    ACTION_PROGRESS_REWARDS = {
+        "read_logs": 0.03,
+        "analyze_error": 0.05,
+        "propose_fix": 0.06,
+        "edit_config": 0.05,
+        "validate_fix": 0.06,
+    }
+
+    QUALITY_WEIGHTS = {
+        "deterministic": 0.40,
+        "hidden": 0.25,
+        "llm": 0.20,
+    }
+
+    def __init__(
+        self,
+        llm_judge: Any | None = None,
+        anti_hacking_detector: AntiHackingDetector | None = None,
+        deterministic_grader: DeterministicGrader | None = None,
+        hidden_test_runner: HiddenTestRunner | None = None,
+    ):
+        self.llm_judge = llm_judge
+        self.anti_hacking_detector = anti_hacking_detector or AntiHackingDetector()
+        self.deterministic_grader = deterministic_grader or DeterministicGrader()
+        self.hidden_test_runner = hidden_test_runner or HiddenTestRunner(grader=self.deterministic_grader)
+
+    def calculate_step_reward(
+        self,
+        state: dict[str, Any] | None,
+        action: str,
+        result: dict[str, Any] | None,
+        original_config: str | None = None,
+        fixed_config: str | None = None,
+        error_message: str | None = None,
+        expected_config: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> float:
+        state = state or {}
+        result = result or {}
+        metadata = metadata or {}
+
+        current_config = fixed_config or result.get("fixed_config") or result.get("current_config") or ""
+        expected_config = expected_config or result.get("expected_config") or state.get("expected_config") or ""
+        original_config = original_config or result.get("original_config") or state.get("original_config") or ""
+        error_message = error_message or result.get("error") or state.get("error") or ""
+
+        reward = 0.0
+        reward += self._progress_reward(action, result)
+        reward += self._execution_reward(result)
+        reward += self._quality_reward(
+            action=action,
+            current_config=current_config,
+            expected_config=expected_config,
+            original_config=original_config,
+            error_message=error_message,
+            result=result,
+            metadata=metadata,
+        )
+        reward += self._penalty_reward(state=state, result=result, current_config=current_config)
+
+        return round(float(reward), 4)
+
+    def _progress_reward(self, action: str, result: dict[str, Any]) -> float:
+        reward = self.ACTION_PROGRESS_REWARDS.get(action, 0.0)
+
+        if result.get("logs_analyzed"):
+            reward += 0.04
+        if result.get("error_diagnosed"):
+            reward += 0.08
+        if result.get("fix_proposed"):
+            reward += 0.05
+
+        return reward
+
+    def _execution_reward(self, result: dict[str, Any]) -> float:
+        reward = 0.0
+
+        if result.get("pipeline_run"):
+            reward += 0.10
+        if result.get("tests_passed"):
+            reward += 0.20
+        if result.get("command_succeeded"):
+            reward += 0.06
+
+        return reward
+
+    def _quality_reward(
+        self,
+        action: str,
+        current_config: str,
+        expected_config: str,
+        original_config: str,
+        error_message: str,
+        result: dict[str, Any],
+        metadata: dict[str, Any],
+    ) -> float:
+        if not current_config or not expected_config:
+            return 0.0
+
+        deterministic_score = result.get("deterministic_score")
+        if deterministic_score is None:
+            deterministic_score = self.deterministic_grader.grade(current_config, expected_config, metadata)
+
+        hidden_pass_rate = result.get("hidden_test_pass_rate")
+        if hidden_pass_rate is None and action in {"validate_fix", "run_hidden_tests", "submit_fix"}:
+            hidden_pass_rate = self.hidden_test_runner.evaluate_fix(
+                fixed_config=current_config,
+                expected_config=expected_config,
+                metadata=metadata,
+            )
+
+        llm_average = 0.0
+        judge_scores = result.get("judge_scores")
+        if not judge_scores and self.llm_judge and original_config and current_config:
+            try:
+                judge_scores = self.llm_judge.evaluate_fix(original_config, current_config, error_message)
+            except Exception:
+                judge_scores = None
+
+        if isinstance(judge_scores, dict):
+            correctness = self._clamp_01(judge_scores.get("correctness", 0.0))
+            minimalism = self._clamp_01(judge_scores.get("minimalism", 0.0))
+            quality = self._clamp_01(judge_scores.get("quality", 0.0))
+            llm_average = (correctness + minimalism + quality) / 3.0
+
+        quality_reward = 0.0
+        quality_reward += self.QUALITY_WEIGHTS["deterministic"] * self._clamp_01(deterministic_score)
+        quality_reward += self.QUALITY_WEIGHTS["hidden"] * self._clamp_01(hidden_pass_rate or 0.0)
+        quality_reward += self.QUALITY_WEIGHTS["llm"] * self._clamp_01(llm_average)
+
+        return quality_reward
+
+    def _penalty_reward(self, state: dict[str, Any], result: dict[str, Any], current_config: str) -> float:
+        changed_files_count = int(result.get("changed_files_count", state.get("changed_files_count", 0)) or 0)
+        changed_lines_count = int(result.get("changed_lines_count", state.get("changed_lines_count", 0)) or 0)
+        edit_count = result.get("edit_count", state.get("edit_count", 0))
+        step_count = int(state.get("step_count", 0) or 0)
+        previous_config = result.get("previous_config") or state.get("previous_config") or ""
+
+        penalty = self.anti_hacking_detector.total_penalty(
+            current_config=current_config,
+            previous_config=previous_config,
+            edit_count=edit_count,
+            changed_files_count=changed_files_count,
+            changed_lines_count=changed_lines_count,
+            step_count=step_count,
+        )
+
+        if result.get("hacking_attempt"):
+            penalty -= 0.30
+
+        return penalty
+
+    def _clamp_01(self, value: Any) -> float:
+        try:
+            parsed = float(value)
+        except (TypeError, ValueError):
+            parsed = 0.0
+        return max(0.0, min(1.0, parsed))

inference.py

@@ -0,0 +1,572 @@
+# pyright: reportMissingImports=false
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import re
+from dataclasses import dataclass
+from itertools import zip_longest
+from typing import Any
+
+from openai import OpenAI
+import yaml
+
+from env.rewards import RewardCalculator
+from inference.metrics import EpisodeMetrics
+from inference.model_wrapper import ModelWrapper, score_action_candidate
+from inference.prompts import JUDGE_SYSTEM_PROMPT, heuristic_action
+from inference.visualize import save_metrics_json, save_reward_curve, save_success_rate_history
+
+try:
+    from my_env_v4 import MyEnvV4Action, MyEnvV4Env  # type: ignore[import-not-found]
+
+    EXTERNAL_ENV_AVAILABLE = True
+except Exception:
+    MyEnvV4Action = None
+    MyEnvV4Env = None
+    EXTERNAL_ENV_AVAILABLE = False
+
+
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+HF_TOKEN = os.getenv("HF_TOKEN")
+LOCAL_IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+
+TASK_NAME = os.getenv("MY_ENV_V4_TASK", "cicd-debugger-task")
+BENCHMARK = os.getenv("MY_ENV_V4_BENCHMARK", "cicd_debugger_env")
+
+MAX_STEPS_DEFAULT = int(os.getenv("MAX_STEPS", "8"))
+TEMPERATURE = float(os.getenv("TEMPERATURE", "0.2"))
+MAX_TOKENS = int(os.getenv("MAX_TOKENS", "120"))
+OFFLINE_INFERENCE = os.getenv("OFFLINE_INFERENCE", "0") == "1"
+
+
+DEFAULT_ORIGINAL_CONFIG = """
+name: CI
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm tset
+""".strip()
+
+DEFAULT_EXPECTED_CONFIG = """
+name: CI
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm test
+""".strip()
+
+DEFAULT_ERROR_MESSAGE = "command not found"
+
+
+@dataclass
+class LocalObservation:
+    config: str
+    error_message: str
+    logs: str
+    last_action_error: str | None = None
+
+
+@dataclass
+class LocalStepResult:
+    observation: LocalObservation
+    reward: float
+    done: bool
+    last_action_error: str | None = None
+
+
+@dataclass
+class LocalAction:
+    message: str
+
+
+class LocalCICDDebuggerEnv:
+    def __init__(self, original_config: str, expected_config: str, error_message: str):
+        self.original_config = original_config
+        self.expected_config = expected_config
+        self.error_message = error_message
+        self.current_config = original_config
+
+    async def reset(self) -> LocalStepResult:
+        self.current_config = self.original_config
+        obs = LocalObservation(
+            config=self.current_config,
+            error_message=self.error_message,
+            logs="CI failed in test step: npm tset is not a valid command.",
+            last_action_error=None,
+        )
+        return LocalStepResult(observation=obs, reward=0.0, done=False, last_action_error=None)
+
+    async def step(self, action: LocalAction) -> LocalStepResult:
+        message = str(action.message or "").strip()
+        lower_message = message.lower()
+        previous = self.current_config
+        step_error: str | None = None
+        logs = "No effective change applied."
+
+        if _is_hacking_action(message):
+            step_error = "disallowed_hacking_pattern"
+            logs = "Rejected unsafe action pattern."
+        elif "npm tset" in lower_message and "npm test" in lower_message and "npm tset" in previous:
+            self.current_config = previous.replace("npm tset", "npm test")
+            logs = "Patched CI command typo from npm tset to npm test."
+        elif "replace" in lower_message and "npm test" in lower_message and "npm tset" in previous:
+            self.current_config = previous.replace("npm tset", "npm test")
+            logs = "Applied replace operation for broken test command."
+        elif "npm test" in lower_message and "npm tset" in previous:
+            self.current_config = previous.replace("npm tset", "npm test")
+            logs = "Applied inferred command fix."
+
+        done = "npm tset" not in self.current_config.lower() and "npm test" in self.current_config.lower()
+        reward = 1.0 if done else 0.0
+        err_msg = "" if done else self.error_message
+
+        obs = LocalObservation(
+            config=self.current_config,
+            error_message=err_msg,
+            logs=logs,
+            last_action_error=step_error,
+        )
+        return LocalStepResult(observation=obs, reward=reward, done=done, last_action_error=step_error)
+
+    async def close(self) -> None:
+        return None
+
+
+class OpenAIJudgeAdapter:
+    def __init__(self, client: OpenAI, model_name: str):
+        self.client = client
+        self.model_name = model_name
+
+    def evaluate_fix(self, original: str, fixed: str, error: str) -> dict[str, float]:
+        prompt = (
+            "Evaluate CI config fix quality. Return JSON only with keys correctness, minimalism, quality in [0,1].\n\n"
+            f"Original:\n{original}\n\n"
+            f"Fixed:\n{fixed}\n\n"
+            f"Error:\n{error}\n"
+        )
+        default = {"correctness": 0.0, "minimalism": 0.0, "quality": 0.0}
+
+        try:
+            completion = self.client.chat.completions.create(
+                model=self.model_name,
+                messages=[
+                    {"role": "system", "content": JUDGE_SYSTEM_PROMPT},
+                    {"role": "user", "content": prompt},
+                ],
+                temperature=0.0,
+                max_tokens=120,
+                stream=False,
+            )
+            content = (completion.choices[0].message.content or "").strip()
+        except Exception:
+            return default
+
+        parsed = self._parse_scores(content)
+        return parsed if parsed else default
+
+    def _parse_scores(self, content: str) -> dict[str, float] | None:
+        decoder = json.JSONDecoder()
+        for idx, char in enumerate(content):
+            if char != "{":
+                continue
+            try:
+                obj, _ = decoder.raw_decode(content[idx:])
+            except json.JSONDecodeError:
+                continue
+            if isinstance(obj, dict):
+                return {
+                    "correctness": self._clamp(obj.get("correctness", 0.0)),
+                    "minimalism": self._clamp(obj.get("minimalism", 0.0)),
+                    "quality": self._clamp(obj.get("quality", 0.0)),
+                }
+
+        fallback = {
+            "correctness": self._extract_regex(content, "correctness"),
+            "minimalism": self._extract_regex(content, "minimalism"),
+            "quality": self._extract_regex(content, "quality"),
+        }
+        if any(value > 0 for value in fallback.values()):
+            return fallback
+        return None
+
+    def _extract_regex(self, content: str, key: str) -> float:
+        match = re.search(rf"{key}\s*[:=\-]\s*([0-9]*\.?[0-9]+)", content, flags=re.IGNORECASE)
+        if not match:
+            return 0.0
+        return self._clamp(match.group(1))
+
+    def _clamp(self, value: Any) -> float:
+        try:
+            parsed = float(value)
+        except (TypeError, ValueError):
+            parsed = 0.0
+        return max(0.0, min(1.0, parsed))
+
+
+def log_start(task: str, env_name: str, model: str) -> None:
+    print(f"[START] task={_single_line(task)} env={_single_line(env_name)} model={_single_line(model)}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: str | None) -> None:
+    done_val = str(done).lower()
+    error_val = _single_line(error) if error else "null"
+    action_val = _single_line(action)
+    print(f"[STEP] step={step} action={action_val} reward={reward:.2f} done={done_val} error={error_val}", flush=True)
+
+
+def log_end(success: bool, steps: int, rewards: list[float]) -> None:
+    rewards_str = ",".join(f"{value:.2f}" for value in rewards)
+    print(f"[END] success={str(success).lower()} steps={steps} rewards={rewards_str}", flush=True)
+
+
+def _single_line(value: Any) -> str:
+    return " ".join(str(value).replace("\n", " ").replace("\r", " ").split())
+
+
+def _safe_float(value: Any) -> float:
+    try:
+        return float(value or 0.0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _extract_observation(result: Any) -> Any:
+    return getattr(result, "observation", result)
+
+
+def _extract_done(result: Any) -> bool:
+    return bool(getattr(result, "done", False))
+
+
+def _extract_reward(result: Any) -> float:
+    return _safe_float(getattr(result, "reward", 0.0))
+
+
+def _extract_error(result: Any, observation: Any) -> str | None:
+    result_error = getattr(result, "last_action_error", None)
+    if result_error:
+        return str(result_error)
+
+    if isinstance(observation, dict):
+        obs_err = observation.get("last_action_error")
+        if obs_err:
+            return str(obs_err)
+    else:
+        obs_err = getattr(observation, "last_action_error", None)
+        if obs_err:
+            return str(obs_err)
+
+    return None
+
+
+def _extract_observation_text(observation: Any) -> str:
+    if isinstance(observation, dict):
+        for key in ("config", "current_config", "echoed_message"):
+            if key in observation and observation.get(key) is not None:
+                return str(observation.get(key))
+        return str(observation)
+
+    for attr in ("config", "current_config", "echoed_message"):
+        if hasattr(observation, attr):
+            value = getattr(observation, attr)
+            if value is not None:
+                return str(value)
+
+    return str(observation)
+
+
+def _extract_observation_error_message(observation: Any) -> str:
+    if isinstance(observation, dict):
+        return str(observation.get("error_message", "") or "")
+    return str(getattr(observation, "error_message", "") or "")
+
+
+def _count_changed_lines(previous_text: str, current_text: str) -> int:
+    previous_lines = (previous_text or "").splitlines()
+    current_lines = (current_text or "").splitlines()
+    changed = 0
+    for left, right in zip_longest(previous_lines, current_lines, fillvalue=""):
+        if left != right:
+            changed += 1
+    return changed
+
+
+def _is_hacking_action(action_text: str) -> bool:
+    value = (action_text or "").lower()
+    patterns = (
+        "if: false",
+        "when: never",
+        "echo \"tests passed\"",
+        "echo 'tests passed'",
+        "exit 0",
+        "force success",
+    )
+    return any(token in value for token in patterns)
+
+
+def _classify_action(action_text: str) -> str:
+    text = (action_text or "").lower()
+    if "read" in text and "log" in text:
+        return "read_logs"
+    if "analy" in text:
+        return "analyze_error"
+    if "propose" in text:
+        return "propose_fix"
+    if any(token in text for token in ("validate", "run test", "pipeline run", "verify")):
+        return "validate_fix"
+    return "edit_config"
+
+
+def _select_action(
+    model_wrapper: ModelWrapper,
+    step: int,
+    config_text: str,
+    error_message: str,
+    history: list[str],
+    policy_mode: str,
+    trajectories: int,
+) -> str:
+    mode = (policy_mode or "imp").lower()
+
+    if mode == "sft":
+        return heuristic_action(config_text, error_message)
+
+    if mode == "direct":
+        return model_wrapper.generate_action(
+            step=step,
+            config_text=config_text,
+            error_message=error_message,
+            history=history,
+        )
+
+    candidates = model_wrapper.generate_candidates(
+        step=step,
+        config_text=config_text,
+        error_message=error_message,
+        history=history,
+        count=max(1, int(trajectories)),
+    )
+
+    if not candidates:
+        return heuristic_action(config_text, error_message)
+
+    observation = f"{config_text}\n{error_message}"
+    best = max(candidates, key=lambda item: score_action_candidate(observation, item, _is_hacking_action))
+    return best
+
+
+def _build_action(action_class: Any, message: str) -> Any:
+    try:
+        return action_class(message=message)
+    except TypeError:
+        return action_class(message)
+
+
+async def _load_environment(
+    original_config: str,
+    expected_config: str,
+    error_message: str,
+    force_local_env: bool,
+) -> tuple[Any, Any]:
+    if not force_local_env and EXTERNAL_ENV_AVAILABLE and LOCAL_IMAGE_NAME:
+        try:
+            env = await MyEnvV4Env.from_docker_image(LOCAL_IMAGE_NAME)
+            return env, MyEnvV4Action
+        except Exception:
+            pass
+
+    env = LocalCICDDebuggerEnv(
+        original_config=original_config,
+        expected_config=expected_config,
+        error_message=error_message,
+    )
+    return env, LocalAction
+
+
+def _load_text(raw_value: str | None, file_path: str | None, fallback: str) -> str:
+    if raw_value:
+        return raw_value
+    if file_path:
+        with open(file_path, "r", encoding="utf-8") as handle:
+            return handle.read().strip()
+    return fallback
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run OpenEnv-style CI/CD pipeline debugging inference loop")
+    parser.add_argument("--max-steps", type=int, default=MAX_STEPS_DEFAULT)
+    parser.add_argument("--task", default=TASK_NAME)
+    parser.add_argument("--benchmark", default=BENCHMARK)
+    parser.add_argument("--offline", action="store_true", default=OFFLINE_INFERENCE)
+    parser.add_argument("--policy-mode", choices=["sft", "imp", "direct"], default="imp")
+    parser.add_argument("--trajectories", type=int, default=3)
+    parser.add_argument("--force-local-env", action="store_true", default=False)
+
+    parser.add_argument("--original-config", default=None)
+    parser.add_argument("--original-config-file", default=None)
+    parser.add_argument("--expected-config", default=None)
+    parser.add_argument("--expected-config-file", default=None)
+    parser.add_argument("--error-message", default=DEFAULT_ERROR_MESSAGE)
+
+    return parser.parse_args()
+
+
+async def run_episode(args: argparse.Namespace) -> int:
+    original_config = _load_text(args.original_config, args.original_config_file, DEFAULT_ORIGINAL_CONFIG)
+    expected_config = _load_text(args.expected_config, args.expected_config_file, DEFAULT_EXPECTED_CONFIG)
+    error_message = str(args.error_message or DEFAULT_ERROR_MESSAGE)
+
+    env = None
+    history: list[str] = []
+    steps_taken = 0
+    success = False
+    metrics = EpisodeMetrics()
+
+    offline_mode = bool(args.offline or not HF_TOKEN)
+    client: OpenAI | None = None
+    if not offline_mode:
+        client = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN or "")
+
+    log_start(task=str(args.task), env_name=str(args.benchmark), model=MODEL_NAME)
+
+    try:
+        env, action_class = await _load_environment(
+            original_config=original_config,
+            expected_config=expected_config,
+            error_message=error_message,
+            force_local_env=bool(args.force_local_env),
+        )
+
+        judge_adapter = OpenAIJudgeAdapter(client, MODEL_NAME) if client is not None else None
+        reward_calculator = RewardCalculator(llm_judge=judge_adapter)
+        model_wrapper = ModelWrapper(
+            client=client,
+            model_name=MODEL_NAME,
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            offline=offline_mode,
+        )
+
+        reset_result = await env.reset()
+        observation = _extract_observation(reset_result)
+        previous_config = original_config
+        current_error_message = error_message
+
+        for step in range(1, max(1, int(args.max_steps)) + 1):
+            config_text = _extract_observation_text(observation) or previous_config
+            obs_error = _extract_observation_error_message(observation)
+            if obs_error:
+                current_error_message = obs_error
+
+            action_text = _select_action(
+                model_wrapper=model_wrapper,
+                step=step,
+                config_text=config_text,
+                error_message=current_error_message,
+                history=history,
+                policy_mode=str(args.policy_mode),
+                trajectories=max(1, int(args.trajectories)),
+            )
+            action_obj = _build_action(action_class, action_text)
+
+            step_result = await env.step(action_obj)
+            observation = _extract_observation(step_result)
+
+            env_reward = _extract_reward(step_result)
+            done = _extract_done(step_result)
+            step_error = _extract_error(step_result, observation)
+            current_config = _extract_observation_text(observation) or config_text
+            obs_error = _extract_observation_error_message(observation)
+            if obs_error:
+                current_error_message = obs_error
+
+            action_type = _classify_action(action_text)
+            hacking_attempt = _is_hacking_action(action_text)
+
+            result_for_reward = {
+                "previous_config": previous_config,
+                "current_config": current_config,
+                "fixed_config": current_config,
+                "expected_config": expected_config,
+                "error": current_error_message,
+                "logs_analyzed": "log" in action_text.lower() or action_type == "read_logs",
+                "error_diagnosed": action_type in {"analyze_error", "propose_fix", "edit_config", "validate_fix"},
+                "fix_proposed": action_type in {"propose_fix", "edit_config"},
+                "pipeline_run": action_type == "validate_fix" and step_error is None,
+                "tests_passed": done,
+                "command_succeeded": step_error is None,
+                "changed_files_count": 1 if previous_config != current_config else 0,
+                "changed_lines_count": _count_changed_lines(previous_config, current_config),
+                "hacking_attempt": hacking_attempt,
+            }
+
+            calculated_reward = reward_calculator.calculate_step_reward(
+                state={
+                    "step_count": step,
+                    "previous_config": previous_config,
+                    "expected_config": expected_config,
+                    "original_config": original_config,
+                    "error": current_error_message,
+                },
+                action=action_type,
+                result=result_for_reward,
+                original_config=original_config,
+                fixed_config=current_config,
+                error_message=current_error_message,
+                expected_config=expected_config,
+                metadata={"broken_token": "npm tset", "fixed_token": "npm test"},
+            )
+
+            combined_reward = round(float(calculated_reward) + float(env_reward), 4)
+            metrics.add_step(action=action_text, reward=combined_reward, error=step_error, done=done)
+            steps_taken = step
+
+            log_step(step=step, action=action_text, reward=combined_reward, done=done, error=step_error)
+
+            history.append(f"step={step} action={_single_line(action_text)} reward={combined_reward:.2f}")
+            previous_config = current_config
+
+            if done:
+                success = step_error is None and not hacking_attempt
+                break
+
+    except Exception:
+        success = False
+    finally:
+        try:
+            save_reward_curve(metrics.rewards)
+            save_metrics_json(metrics.summary())
+            save_success_rate_history([success])
+        except Exception:
+            pass
+
+        if env is not None:
+            try:
+                await env.close()
+            except Exception:
+                pass
+
+        log_end(success=success, steps=steps_taken, rewards=metrics.rewards)
+
+    return 0
+
+
+def main() -> int:
+    args = parse_args()
+    return asyncio.run(run_episode(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inference/__init__.py

@@ -0,0 +1,4 @@
+from inference.metrics import EpisodeMetrics
+from inference.model_wrapper import ModelWrapper
+
+__all__ = ["EpisodeMetrics", "ModelWrapper"]

inference/metrics.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class EpisodeMetrics:
+    rewards: list[float] = field(default_factory=list)
+    actions: list[str] = field(default_factory=list)
+    errors: list[str | None] = field(default_factory=list)
+    dones: list[bool] = field(default_factory=list)
+
+    def add_step(self, action: str, reward: float, error: str | None, done: bool) -> None:
+        self.actions.append(action)
+        self.rewards.append(float(reward))
+        self.errors.append(error)
+        self.dones.append(bool(done))
+
+    @property
+    def steps(self) -> int:
+        return len(self.rewards)
+
+    @property
+    def total_reward(self) -> float:
+        return round(sum(self.rewards), 4)
+
+    @property
+    def average_reward(self) -> float:
+        if not self.rewards:
+            return 0.0
+        return round(self.total_reward / len(self.rewards), 4)
+
+    @property
+    def success_rate(self) -> float:
+        if not self.dones:
+            return 0.0
+        successes = sum(1 for flag in self.dones if flag)
+        return round(successes / len(self.dones), 4)
+
+    @property
+    def failure_reasons(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for err in self.errors:
+            if not err:
+                continue
+            counts[err] = counts.get(err, 0) + 1
+        return counts
+
+    def summary(self) -> dict[str, float | int | dict[str, int]]:
+        return {
+            "steps": self.steps,
+            "total_reward": self.total_reward,
+            "average_reward": self.average_reward,
+            "success_rate": self.success_rate,
+            "failure_reasons": self.failure_reasons,
+        }

inference/model_wrapper.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+from openai import OpenAI
+
+from inference.prompts import SYSTEM_PROMPT, build_user_prompt, heuristic_action, sanitize_action_text
+
+
+@dataclass
+class ModelWrapper:
+    client: OpenAI | None
+    model_name: str
+    temperature: float
+    max_tokens: int
+    offline: bool
+
+    def generate_action(
+        self,
+        step: int,
+        config_text: str,
+        error_message: str,
+        history: list[str],
+        available_actions: Iterable[str] | None = None,
+    ) -> str:
+        if self.offline or self.client is None:
+            return heuristic_action(config_text, error_message, available_actions)
+
+        user_prompt = build_user_prompt(
+            step=step,
+            config_text=config_text,
+            error_message=error_message,
+            history=history,
+            available_actions=available_actions,
+        )
+
+        try:
+            completion = self.client.chat.completions.create(
+                model=self.model_name,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                temperature=self.temperature,
+                max_tokens=self.max_tokens,
+                stream=False,
+            )
+            generated = completion.choices[0].message.content or ""
+            action = sanitize_action_text(
+                generated,
+                fallback=heuristic_action(config_text, error_message, available_actions),
+            )
+            return action
+        except Exception:
+            return heuristic_action(config_text, error_message, available_actions)
+
+    def generate_candidates(
+        self,
+        step: int,
+        config_text: str,
+        error_message: str,
+        history: list[str],
+        count: int,
+        available_actions: Iterable[str] | None = None,
+    ) -> list[str]:
+        candidates = [heuristic_action(config_text, error_message, available_actions)]
+
+        for idx in range(max(1, count)):
+            action = self.generate_action(
+                step=step,
+                config_text=config_text,
+                error_message=error_message,
+                history=history + [f"candidate={idx}"],
+                available_actions=available_actions,
+            )
+            if action:
+                candidates.append(action)
+
+        deduped: list[str] = []
+        seen: set[str] = set()
+        for candidate in candidates:
+            normalized = candidate.strip()
+            if not normalized:
+                continue
+            if normalized in seen:
+                continue
+            seen.add(normalized)
+            deduped.append(normalized)
+
+        return deduped
+
+
+def score_action_candidate(observation_text: str, action_text: str, hacking_predicate: Any) -> float:
+    obs = (observation_text or "").lower()
+    action = (action_text or "").lower()
+
+    score = 0.0
+    if "npm tset" in obs and "npm test" in action:
+        score += 2.0
+    if "yaml" in obs and any(token in action for token in ("indent", "syntax", "yaml")):
+        score += 1.0
+    if "dependency" in obs and any(token in action for token in ("install", "dependency", "package")):
+        score += 1.0
+    if hacking_predicate(action_text):
+        score -= 3.0
+
+    score += min(len(action_text) / 200.0, 0.25)
+    return score

inference/prompts.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import textwrap
+from typing import Iterable
+
+
+SYSTEM_PROMPT = textwrap.dedent(
+    """
+    You are a CI/CD pipeline debugger assistant.
+    Return exactly one single-line action describing the next debugging move.
+    Do not output markdown. Do not include explanations.
+    """
+).strip()
+
+JUDGE_SYSTEM_PROMPT = textwrap.dedent(
+    """
+    You are a strict CI/CD judge.
+    Return JSON only with keys correctness, minimalism, quality and values in [0,1].
+    """
+).strip()
+
+
+def build_user_prompt(
+    step: int,
+    config_text: str,
+    error_message: str,
+    history: list[str],
+    available_actions: Iterable[str] | None = None,
+) -> str:
+    history_text = "\n".join(history[-5:]) if history else "None"
+    actions_text = ", ".join(available_actions) if available_actions else "read_logs, analyze_error, propose_fix, edit_config, validate_fix"
+
+    return textwrap.dedent(
+        f"""
+        Step: {step}
+
+        Current config:
+        {config_text}
+
+        Current error:
+        {error_message}
+
+        Recent history:
+        {history_text}
+
+        Available action categories:
+        {actions_text}
+
+        Output one actionable single-line fix/debug action.
+        """
+    ).strip()
+
+
+def sanitize_action_text(raw_text: str, fallback: str = "read logs and analyze failing command") -> str:
+    text = (raw_text or "").strip()
+    if not text:
+        return fallback
+    text = text.replace("\n", " ").replace("\r", " ")
+    text = " ".join(text.split())
+    return text or fallback
+
+
+def heuristic_action(
+    config_text: str,
+    error_message: str,
+    available_actions: Iterable[str] | None = None,
+) -> str:
+    lower_cfg = (config_text or "").lower()
+    lower_err = (error_message or "").lower()
+
+    if "npm tset" in lower_cfg:
+        return "edit_config: replace npm tset with npm test"
+
+    if "yaml" in lower_err or "mapping values are not allowed" in lower_err:
+        return "edit_config: fix YAML indentation and syntax"
+
+    if "module not found" in lower_err or "dependency" in lower_err:
+        return "propose_fix: install missing dependency and update pipeline install step"
+
+    return "read_logs: inspect failing stage logs and identify root cause"

inference/visualize.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def save_reward_curve(rewards: list[float], output_path: str = "artifacts/reward_curve.csv") -> str:
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w", encoding="utf-8") as handle:
+        handle.write("step,reward\n")
+        for idx, reward in enumerate(rewards, start=1):
+            handle.write(f"{idx},{float(reward):.4f}\n")
+
+    return str(path)
+
+
+def save_success_rate_history(success_flags: list[bool], output_path: str = "artifacts/success_rate.csv") -> str:
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    running = 0
+    with path.open("w", encoding="utf-8") as handle:
+        handle.write("episode,success,success_rate\n")
+        for idx, flag in enumerate(success_flags, start=1):
+            if flag:
+                running += 1
+            rate = running / idx
+            handle.write(f"{idx},{int(flag)},{rate:.4f}\n")
+
+    return str(path)
+
+
+def save_metrics_json(metrics: dict, output_path: str = "artifacts/metrics.json") -> str:
+    path = Path(output_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(metrics, handle, indent=2, sort_keys=True)
+
+    return str(path)

openenv.yaml

@@ -0,0 +1,69 @@
+version: "0.1"
+name: "cicd-debugger-env"
+description: "AI environment for debugging CI/CD pipelines with deterministic + LLM grading"
+
+entrypoint:
+  command: "python"
+  args:
+    - "inference.py"
+
+interface:
+  observation_type: "json"
+  action_type: "json"
+  max_steps: 30
+
+tasks:
+  - id: "cicd-debugger-001"
+    description: "Fix typo in npm test command"
+    difficulty: "easy"
+    metadata:
+      broken_token: "npm tset"
+      fixed_token: "npm test"
+
+  - id: "cicd-debugger-002"
+    description: "Fix YAML indentation in test job"
+    difficulty: "easy"
+
+  - id: "cicd-debugger-003"
+    description: "Fix missing checkout step"
+    difficulty: "easy"
+
+  - id: "cicd-debugger-004"
+    description: "Fix wrong Python version pin"
+    difficulty: "easy"
+
+  - id: "cicd-debugger-005"
+    description: "Fix dependency install command"
+    difficulty: "medium"
+
+  - id: "cicd-debugger-006"
+    description: "Fix cache key mismatch"
+    difficulty: "medium"
+
+  - id: "cicd-debugger-007"
+    description: "Fix environment variable propagation"
+    difficulty: "medium"
+
+  - id: "cicd-debugger-008"
+    description: "Fix test stage permissions"
+    difficulty: "medium"
+
+  - id: "cicd-debugger-009"
+    description: "Fix artifact upload path"
+    difficulty: "medium"
+
+  - id: "cicd-debugger-010"
+    description: "Fix matrix include-exclude logic"
+    difficulty: "hard"
+
+  - id: "cicd-debugger-011"
+    description: "Fix conditional deploy stage logic"
+    difficulty: "hard"
+
+  - id: "cicd-debugger-012"
+    description: "Fix multi-job dependency ordering"
+    difficulty: "hard"
+
+  - id: "cicd-debugger-013"
+    description: "Fix cross-platform shell command behavior"
+    difficulty: "hard"

pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "cicd-debugger-env"
+version = "0.1.0"
+description = "OpenEnv CI/CD pipeline debugging environment with hybrid grading and reward shaping"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "openai",
+  "pyyaml",
+  "fastapi",
+  "uvicorn",
+  "openenv-core",
+  "transformers",
+  "torch",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

requirements.txt

@@ -0,0 +1,7 @@
+openai
+pyyaml
+fastapi
+uvicorn
+openenv-core
+transformers
+torch

server/app.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+import uvicorn
+
+
+app = FastAPI(title="CI/CD Debugger OpenEnv Server")
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+def main() -> None:
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

tests/test_day2_engine.py

@@ -0,0 +1,198 @@
+import unittest
+
+from env.anti_hacking import AntiHackingDetector
+from env.graders.deterministic import DeterministicGrader
+from env.hidden_tests import HiddenTestRunner
+from env.rewards import RewardCalculator
+
+
+EXPECTED_CONFIG = """
+name: CI
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm test
+"""
+
+WRONG_CONFIG = """
+name: CI
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci
+      - run: npm tset
+"""
+
+BROKEN_YAML = """
+name CI
+jobs:
+  test:
+    steps
+      - run npm test
+"""
+
+
+class FakeJudge:
+    def evaluate_fix(self, original, fixed, error):
+        return {
+            "correctness": 0.9,
+            "minimalism": 0.8,
+            "quality": 0.9,
+        }
+
+
+class Day2EngineTests(unittest.TestCase):
+    def setUp(self):
+        self.grader = DeterministicGrader()
+        self.detector = AntiHackingDetector()
+        self.hidden_runner = HiddenTestRunner(grader=self.grader)
+        self.reward_calculator = RewardCalculator(
+            llm_judge=FakeJudge(),
+            anti_hacking_detector=self.detector,
+            deterministic_grader=self.grader,
+            hidden_test_runner=self.hidden_runner,
+        )
+
+    def test_deterministic_grader_high_for_correct_fix(self):
+        score = self.grader.grade(EXPECTED_CONFIG, EXPECTED_CONFIG)
+        self.assertGreaterEqual(score, 0.85)
+        self.assertLessEqual(score, 1.0)
+
+    def test_deterministic_grader_low_for_wrong_fix(self):
+        score = self.grader.grade(WRONG_CONFIG, EXPECTED_CONFIG)
+        self.assertLess(score, 0.6)
+
+    def test_deterministic_grader_penalizes_broken_yaml(self):
+        score = self.grader.grade(BROKEN_YAML, EXPECTED_CONFIG)
+        self.assertLess(score, 0.4)
+
+    def test_deterministic_grader_is_reproducible(self):
+        first = self.grader.grade(WRONG_CONFIG, EXPECTED_CONFIG)
+        second = self.grader.grade(WRONG_CONFIG, EXPECTED_CONFIG)
+        self.assertEqual(first, second)
+
+    def test_anti_hacking_detects_stage_skipping(self):
+        config = EXPECTED_CONFIG + "\n    if: false\n"
+        penalty = self.detector.penalty_stage_skipping(config)
+        self.assertLess(penalty, 0.0)
+
+    def test_anti_hacking_detects_fake_success(self):
+        config = EXPECTED_CONFIG.replace("npm test", 'echo "tests passed" && exit 0')
+        penalty = self.detector.penalty_fake_success(config)
+        self.assertLess(penalty, 0.0)
+
+    def test_anti_hacking_detects_breaking_pipeline(self):
+        previous_config = """
+stages:
+  - build
+  - test
+jobs:
+  build:
+    run: npm ci
+  test:
+    run: npm test
+"""
+        new_config = """
+stages:
+  - build
+jobs:
+  build:
+    run: npm ci
+"""
+        penalty = self.detector.penalty_breaking_pipeline(previous_config, new_config)
+        self.assertLess(penalty, 0.0)
+
+    def test_anti_hacking_detects_excessive_edits(self):
+        penalty = self.detector.penalty_excessive_edits(changed_files_count=12, changed_lines_count=400)
+        self.assertLess(penalty, 0.0)
+
+    def test_anti_hacking_detects_timeout_abuse(self):
+        penalty = self.detector.penalty_timeout_abuse(step_count=25)
+        self.assertLess(penalty, 0.0)
+
+    def test_hidden_tests_returns_high_pass_rate_for_good_fix(self):
+        pass_rate = self.hidden_runner.evaluate_fix(
+            fixed_config=EXPECTED_CONFIG,
+            expected_config=EXPECTED_CONFIG,
+        )
+        self.assertGreaterEqual(pass_rate, 0.8)
+
+    def test_hidden_tests_returns_lower_pass_rate_for_bad_fix(self):
+        pass_rate = self.hidden_runner.evaluate_fix(
+            fixed_config=WRONG_CONFIG,
+            expected_config=EXPECTED_CONFIG,
+        )
+        self.assertLess(pass_rate, 0.8)
+
+    def test_reward_calculator_positive_for_good_behavior(self):
+        state = {
+            "step_count": 3,
+            "previous_config": WRONG_CONFIG,
+            "expected_config": EXPECTED_CONFIG,
+            "original_config": WRONG_CONFIG,
+            "error": "command not found",
+        }
+        result = {
+            "logs_analyzed": True,
+            "error_diagnosed": True,
+            "fix_proposed": True,
+            "pipeline_run": True,
+            "tests_passed": True,
+            "command_succeeded": True,
+            "current_config": EXPECTED_CONFIG,
+            "expected_config": EXPECTED_CONFIG,
+            "changed_files_count": 1,
+            "changed_lines_count": 1,
+        }
+
+        reward = self.reward_calculator.calculate_step_reward(
+            state=state,
+            action="validate_fix",
+            result=result,
+            original_config=WRONG_CONFIG,
+            fixed_config=EXPECTED_CONFIG,
+            error_message="command not found",
+            expected_config=EXPECTED_CONFIG,
+            metadata={"broken_token": "npm tset", "fixed_token": "npm test"},
+        )
+
+        self.assertGreater(reward, 0.5)
+
+    def test_reward_calculator_penalizes_hacking(self):
+        hacked_config = EXPECTED_CONFIG.replace("npm test", 'echo "tests passed" && exit 0') + "\n    if: false\n"
+        state = {
+            "step_count": 25,
+            "previous_config": EXPECTED_CONFIG,
+            "changed_files_count": 15,
+            "changed_lines_count": 500,
+        }
+        result = {
+            "current_config": hacked_config,
+            "expected_config": EXPECTED_CONFIG,
+            "hacking_attempt": True,
+            "changed_files_count": 15,
+            "changed_lines_count": 500,
+        }
+
+        reward = self.reward_calculator.calculate_step_reward(
+            state=state,
+            action="edit_config",
+            result=result,
+            original_config=EXPECTED_CONFIG,
+            fixed_config=hacked_config,
+            error_message="",
+            expected_config=EXPECTED_CONFIG,
+        )
+
+        self.assertLess(reward, 0.0)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_inference.py

@@ -0,0 +1,54 @@
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+import unittest
+
+
+class InferenceOutputFormatTests(unittest.TestCase):
+    def test_inference_prints_required_markers(self):
+        project_root = Path(__file__).resolve().parents[1]
+        env = os.environ.copy()
+        env["OFFLINE_INFERENCE"] = "1"
+
+        completed = subprocess.run(
+            [sys.executable, "inference.py", "--max-steps", "3", "--offline", "--force-local-env"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            env=env,
+            check=True,
+        )
+
+        lines = [line.strip() for line in completed.stdout.splitlines() if line.strip()]
+        self.assertGreaterEqual(len(lines), 3)
+        self.assertTrue(lines[0].startswith("[START] "))
+        self.assertTrue(lines[-1].startswith("[END] "))
+
+        start_pattern = re.compile(r"^\[START\] task=\S+ env=\S+ model=.+$")
+        step_pattern = re.compile(
+            r"^\[STEP\] step=\d+ action=.* reward=-?\d+\.\d{2} done=(true|false) error=(null|.+)$"
+        )
+        end_pattern = re.compile(
+            r"^\[END\] success=(true|false) steps=\d+ rewards=(-?\d+\.\d{2}(,-?\d+\.\d{2})*)?$"
+        )
+
+        self.assertRegex(lines[0], start_pattern)
+
+        step_lines = [line for line in lines if line.startswith("[STEP] ")]
+        self.assertTrue(step_lines)
+        for line in step_lines:
+            self.assertRegex(line, step_pattern)
+
+        self.assertRegex(lines[-1], end_pattern)
+
+        for line in lines:
+            self.assertTrue(
+                line.startswith("[START] ") or line.startswith("[STEP] ") or line.startswith("[END] "),
+                f"Unexpected output line: {line}",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_judge.py

@@ -0,0 +1,51 @@
+import unittest
+
+from env.graders.llm_judge import LLMJudge
+
+
+class FakeModel:
+    def __init__(self, payload, raise_error: bool = False):
+        self.payload = payload
+        self.raise_error = raise_error
+
+    def __call__(self, prompt, **kwargs):
+        if self.raise_error:
+            raise RuntimeError("model failure")
+        return [{"generated_text": self.payload}]
+
+
+class LLMJudgeTests(unittest.TestCase):
+    def test_good_json_scores_are_parsed(self):
+        judge = LLMJudge(FakeModel('{"correctness": 1.0, "minimalism": 0.8, "quality": 0.9}'))
+        result = judge.evaluate_fix("npm tset", "npm test", "command not found")
+
+        self.assertGreaterEqual(result["correctness"], 0.9)
+        self.assertGreaterEqual(result["minimalism"], 0.7)
+        self.assertGreaterEqual(result["quality"], 0.8)
+
+    def test_regex_fallback_for_noisy_output(self):
+        noisy = "Correctness: 0.7\nMinimalism: 0.6\nQuality: 0.75"
+        judge = LLMJudge(FakeModel(noisy))
+        result = judge.evaluate_fix("a", "b", "err")
+
+        self.assertAlmostEqual(result["correctness"], 0.7)
+        self.assertAlmostEqual(result["minimalism"], 0.6)
+        self.assertAlmostEqual(result["quality"], 0.75)
+
+    def test_partial_fields_default_to_zero(self):
+        judge = LLMJudge(FakeModel('{"correctness": 0.8}'))
+        result = judge.evaluate_fix("a", "b", "err")
+
+        self.assertAlmostEqual(result["correctness"], 0.8)
+        self.assertAlmostEqual(result["minimalism"], 0.0)
+        self.assertAlmostEqual(result["quality"], 0.0)
+
+    def test_model_failure_returns_zeroes(self):
+        judge = LLMJudge(FakeModel("", raise_error=True))
+        result = judge.evaluate_fix("a", "b", "err")
+
+        self.assertEqual(result, {"correctness": 0.0, "minimalism": 0.0, "quality": 0.0})
+
+
+if __name__ == "__main__":
+    unittest.main()

validate-submission.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+#
+# validate-submission.sh - OpenEnv Submission Validator
+#
+# Checks that your HF Space is live, Docker image builds, and openenv validate passes.
+#
+# Usage:
+#   ./validate-submission.sh <ping_url> [repo_dir]
+
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BOLD='' NC=''
+fi
+
+run_with_timeout() {
+  local secs="$1"; shift
+  if command -v timeout &>/dev/null; then
+    timeout "$secs" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$secs" "$@"
+  else
+    "$@" &
+    local pid=$!
+    ( sleep "$secs" && kill "$pid" 2>/dev/null ) &
+    local watcher=$!
+    wait "$pid" 2>/dev/null
+    local rc=$?
+    kill "$watcher" 2>/dev/null
+    wait "$watcher" 2>/dev/null
+    return $rc
+  fi
+}
+
+portable_mktemp() {
+  local prefix="${1:-validate}"
+  mktemp "${TMPDIR:-/tmp}/${prefix}-XXXXXX" 2>/dev/null || mktemp
+}
+
+CLEANUP_FILES=()
+cleanup() { rm -f "${CLEANUP_FILES[@]+"${CLEANUP_FILES[@]}"}"; }
+trap cleanup EXIT
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  printf "\n"
+  printf "  ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)\n"
+  printf "  repo_dir   Path to your repo (default: current directory)\n"
+  exit 1
+fi
+
+if ! REPO_DIR="$(cd "$REPO_DIR" 2>/dev/null && pwd)"; then
+  printf "Error: directory '%s' not found\n" "${2:-.}"
+  exit 1
+fi
+
+PING_URL="${PING_URL%/}"
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS + 1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() {
+  printf "\n"
+  printf "${RED}${BOLD}Validation stopped at %s.${NC} Fix the above before continuing.\n" "$1"
+  exit 1
+}
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  OpenEnv Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+printf "\n"
+
+log "${BOLD}Step 1/3: Pinging HF Space${NC} ($PING_URL/reset) ..."
+
+CURL_OUTPUT=$(portable_mktemp "validate-curl")
+CLEANUP_FILES+=("$CURL_OUTPUT")
+HTTP_CODE=$(curl -s -o "$CURL_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 2>"$CURL_OUTPUT" || printf "000")
+
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live and responds to /reset"
+elif [ "$HTTP_CODE" = "000" ]; then
+  fail "HF Space not reachable (connection failed or timed out)"
+  hint "Check your network connection and that the Space is running."
+  hint "Try: curl -s -o /dev/null -w '%{http_code}' -X POST $PING_URL/reset"
+  stop_at "Step 1"
+else
+  fail "HF Space /reset returned HTTP $HTTP_CODE (expected 200)"
+  hint "Make sure your Space is running and the URL is correct."
+  stop_at "Step 1"
+fi
+
+log "${BOLD}Step 2/3: Running docker build${NC} ..."
+
+if ! command -v docker &>/dev/null; then
+  fail "docker command not found"
+  hint "Install Docker: https://docs.docker.com/get-docker/"
+  stop_at "Step 2"
+fi
+
+if [ -f "$REPO_DIR/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR"
+elif [ -f "$REPO_DIR/server/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR/server"
+else
+  fail "No Dockerfile found in repo root or server/ directory"
+  stop_at "Step 2"
+fi
+
+BUILD_OK=false
+BUILD_OUTPUT=$(run_with_timeout "$DOCKER_BUILD_TIMEOUT" docker build "$DOCKER_CONTEXT" 2>&1) && BUILD_OK=true
+
+if [ "$BUILD_OK" = true ]; then
+  pass "Docker build succeeded"
+else
+  fail "Docker build failed (timeout=${DOCKER_BUILD_TIMEOUT}s)"
+  printf "%s\n" "$BUILD_OUTPUT" | tail -20
+  stop_at "Step 2"
+fi
+
+log "${BOLD}Step 3/3: Running openenv validate${NC} ..."
+
+if ! command -v openenv &>/dev/null; then
+  fail "openenv command not found"
+  hint "Install it: pip install openenv-core"
+  stop_at "Step 3"
+fi
+
+VALIDATE_OK=false
+VALIDATE_OUTPUT=$(cd "$REPO_DIR" && openenv validate 2>&1) && VALIDATE_OK=true
+
+if [ "$VALIDATE_OK" = true ]; then
+  pass "openenv validate passed"
+else
+  fail "openenv validate failed"
+  printf "%s\n" "$VALIDATE_OUTPUT"
+  stop_at "Step 3"
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${GREEN}${BOLD}  All 3/3 checks passed!${NC}\n"
+printf "${GREEN}${BOLD}  Your submission is ready to submit.${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+printf "\n"
+
+exit 0