docs/error_and_solving_chat.md

Error and Solving Chat

Purpose: Log every runtime error, unexpected behavior, or blocker encountered during development. Include the error message, root cause, and exact fix applied. Never delete entries — they form a debug history.

---

How to Use This File

When you hit an error:

1. Copy the full error/traceback here
2. Write what you were trying to do when it happened
3. Investigate and write the root cause
4. Write the fix applied
5. Note if the fix was a workaround (and link to a proper fix TODO)

Entry format:

## [YYYY-MM-DD] — ERROR: <short description>
**Context:** What were you doing?
**Error output:** (paste traceback)
**Root cause:** Why did it happen?
**Fix applied:** What did you change?
**Status:** Resolved / Workaround / Open

---

[Template — Copy This for Each New Error]

## [DATE] — ERROR: <short title>
**Context:**
**Error output:**

paste error here

**Root cause:**
**Fix applied:**
**Status:** Resolved / Workaround / Open
**Linked HISTORY entry:** vX.Y

---

Common Error Categories

Category	What to Look For
Import errors	Wrong module path, missing __init__.py
AST parse errors	Residual conflict markers in file before parsing
Sandbox isolation	Two episodes sharing temp directory
Reward miscalculation	Wrong before/after state comparison
Pytest subprocess	Exit code != 0 but no tests actually failed
Git operations	Detached HEAD state in sandbox repo
Gradio / HF Space	Port conflicts, missing dependencies

---

Known Pitfalls (Pre-emptive Notes)

Pitfall 1 — AST Parsing Conflict-Marked Files

Problem: If you call ast.parse() on a file that still contains conflict markers, you get a SyntaxError that looks like a syntax issue in the agent's resolution — but it's actually just the markers still being present.

Prevention: Always strip/check for conflict markers BEFORE running ast.parse().

CONFLICT_MARKERS = ["<<<<<<<", "=======", ">>>>>>>"]

def has_conflict_markers(content: str) -> bool:
    return any(marker in content for marker in CONFLICT_MARKERS)

def validate_syntax(content: str) -> tuple[bool, str]:
    if has_conflict_markers(content):
        return False, "File still contains conflict markers"
    try:
        ast.parse(content)
        return True, ""
    except SyntaxError as e:
        return False, str(e)

---

Pitfall 2 — Sandbox Directory Not Cleaned Up

Problem: If reset() is called repeatedly without cleanup, temp directories accumulate on disk. On Windows, shutil.rmtree() can fail if files are still open.

Prevention: Use atexit to register cleanup and wrap shutil.rmtree with error handling:

import shutil, atexit

def cleanup(path):
    try:
        shutil.rmtree(path, ignore_errors=True)
    except Exception:
        pass

atexit.register(cleanup, temp_path)

---

Pitfall 3 — Pytest Subprocess Hanging

Problem: If a task's test file has an infinite loop or a blocking call, pytest subprocess will hang indefinitely, blocking the environment's step() from returning.

Prevention: Always run pytest with a timeout:

import subprocess

result = subprocess.run(
    ["pytest", task_path, "--timeout=10", "-q"],
    capture_output=True,
    text=True,
    timeout=30  # hard kill after 30s
)

Install pytest-timeout as a dependency.

---

Pitfall 4 — Conflict Block Counting Off-by-One

Problem: When scanning for conflict blocks, counting >>>>>>> lines instead of counting block starts (<<<<<<<) leads to wrong conflict_count in state. If a file has 3 blocks and one marker is malformed, counts diverge.

Prevention: Count by <<<<<<< occurrences only — each one opens exactly one block.

def count_conflict_blocks(content: str) -> int:
    return content.count("<<<<<<<")

---

Pitfall 5 — Reward Drift Between Steps

Problem: If compute_reward() uses the live file system state instead of comparing state_before to state_after, rewards can be inconsistent if files are modified between the state snapshot and reward computation.

Prevention: Always snapshot state immediately after step() applies the action, before any further operations.

---

Error Log (Active)

Add entries below as errors are encountered during development.