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()`.

```python
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:

```python
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:

```python
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.

```python
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.

<!-- Entries will be added here as development proceeds -->