# Opus Review

**Model:** claude-opus-4-6
**Generated:** 2026-03-11T08:30:00Z

---

## Critical Issues

### 1. Dual Timeout — Python Bridge vs GDScript Polling
The plan has two independent timeout mechanisms. Python bridge has `TOOL_TIMEOUTS["run"] = 10.0` in protocol.py, while GDScript has its own polling timeout. If Python times out at 10s but GDScript is set to 20s, the response is lost.

**Fix required**: Python `bridge.request("run", ..., timeout=computed_timeout + buffer)` must always exceed the GDScript polling timeout. Update TOOL_TIMEOUTS or pass explicit timeout.

### 2. `_try_reload_script` — Use `get_bridge_or_none()`
Using `get_bridge()` in script_ops will attempt to CONNECT if not connected, adding a 5-second delay on every .gd write when the bridge is down. Use `get_bridge_or_none()` (already exists in session.py) for zero-latency best-effort.

Also: need lazy import to avoid circular dependency, and explicitly construct `f"res://{rel_path}"` for the path.

### 3. `open_scene_from_path` Race Condition
_handle_run is synchronous in GDScript. "Wait one process frame" requires either making it async with `await` or using a two-phase state machine (set `_pending_scene_open`, return, continue in next `_process` tick).

## Major Issues

### 4. set_main_scene Side-Effect is Dangerous
Auto-setting main_scene when empty modifies project.godot permanently. Could break export profiles. Plan should clarify this only happens when main_scene is truly empty/unset and warn about the disk modification.

### 5. verify_motion Requires Game Running
No game-running check before starting. No handling for game crash between the two state_inspect calls.

### 6. Session Access Pattern Wrong
`run.py` has no access to session. Plan says "get the session from godotiq.session" but session is only in lifespan context. Use GODOTIQ_PROJECT_ROOT env var directly with pathlib instead.

### 7. Pre-flight Script Validation Missing from New _handle_run
Current _handle_run has script validation gate (lines 264-291). The plan's Section 1 describes new handler without mentioning it. Must be preserved.

### 8. run.py Return Value Unclear
Currently run.py constructs its own response dict. New GDScript response will have {success, waited_seconds}. Plan doesn't clarify if Python passes through or constructs its own.

## Moderate Issues

### 9. Implementation Order Wrong
Section 4 (set_main_scene) must come before/with Section 1, not after. Section 1 depends on set_main_scene.

### 10. node_names Should Use _create_build_node Return Value
Use `result["name"]` from _create_build_node, not `spec["name"]`, because Godot may rename on collision.

### 11. _find_scene_by_name Ambiguity
Multiple .tscn with same base name (ui/main.tscn vs levels/main.tscn) — should error on ambiguity.

### 12. filesystem.scan() Timing After build_scene
scan() is async — client gets response before scan completes. Should acknowledge this gap.

## Minor Issues

### 13. `property` Shadows Python Builtin
Rename to `prop` or `property_name`.

### 14. `detail` Parameter Unused in verify_motion
Either apply output_limit or remove the parameter.

### 15. Prompt File Retrieval
Note that implementer needs `git show HEAD:...` to retrieve original content.
