# Troubleshooting & Tips

> Reference material for the replayer skill. Load this when encountering issues.

## Troubleshooting

### Auto-chat hangs (status="running" but no progress)

**Symptom**: `diagnostics/status` returns `"status": "running"` indefinitely, telemetry log stops growing, but opencode process may still be alive (idle).

**Root cause**: The opencode ACP session can hang during an agent tool call or LLM API request. `ask_and_wait` may not trigger its idle timeout correctly, leaving the status stuck at "running". Calling `auto-chat/stop` only updates the DB status — it does NOT kill the opencode process or clear the in-memory session cache.

**Recovery steps**:

1. Stop auto-chat:
   ```bash
   curl -s -X POST "$BASE_URL/api/workspaces/$WS_ID/auto-chat/stop" \
     -H "Authorization: Bearer $TOKEN"
   ```

2. Kill the stuck opencode process:
   ```bash
   pkill -9 -f "opencode acp"
   ```

3. Restart the backend (clears in-memory session cache):
   ```bash
   make kill && make api
   ```

4. **Create a new workspace** and retry. Do NOT reuse the old workspace — `get_or_create_session` will attempt to resume the stale opencode session via `resume_session_id`, which can hang again.

**Prevention**: When running Mode F, monitor telemetry log activity (`grep "Recorded:" telemetry.log | tail`). If no new tool calls appear for >3 minutes and the agent isn't streaming text, the session is likely stuck.

### "Agent is busy with a previous request"

**Symptom**: SSE stream returns `{"type": "error", "error": "Agent is busy with a previous request."}`.

**Root cause**: A previous auto-chat or SSE stream is still holding the ACP session lock for this workspace. This happens when a previous request was interrupted (e.g., curl timeout) but the backend session wasn't cleaned up.

**Recovery**: Same as above — stop auto-chat, kill opencode, restart backend, use a new workspace.

## Tips

- **Re-running a case**: Delete messages first (`DELETE /api/workspace/{id}/messages`), then send the prompt again. The workspace directory and source data are preserved.
- **Parallel runs**: Each workspace has its own agent session. You can run multiple replays in parallel on different workspaces.
- **Long-running queries**: TopSQL/SlowQuery queries via Data Proxy can take 30-60 seconds. The SSE stream sends keepalive comments to prevent timeout. Use `--max-time 600` for curl.
- **Token expiry**: JWT tokens expire after 30 days by default. API keys (`ib_...`) don't expire.
- **Remote environment access**: Use `investibook` CLI with `--profile <name>` to query any remote API directly. No AWS SSO, kubectl, or local backend needed.
- **Interactive mode**: Mode F is preferred for automated evaluation. It typically completes in 0-2 follow-ups for well-tuned skills, and surfaces skill regressions when it needs 3+.