Our coding agent debugged phantom failures for 47 minutes because it trusted terminal history

I watched our coding agent spend 47 minutes debugging a "deployment failure" yesterday. The exit code was 0. The service was running. Users were happy.

The problem? It read this in the terminal history:

ERROR: Connection refused on port 3000
Retrying deployment...
ERROR: Database migration failed
Rolling back...
SUCCESS: Deployment completed

The agent saw "ERROR" and "failed" in the scrollback and assumed the current state was broken. It spent the next hour "fixing" a system that was already working perfectly.

Terminal history is not system state. It's archaeology.

Here's what I built to fix this:

# Add to your agent's system prompt

## State Verification Protocol

Before debugging ANY error:
1. Check current process status: `ps aux | grep [service]`
2. Verify service health: `curl -f http://localhost:3000/health`
3. Check recent logs only: `journalctl -u [service] --since="5 minutes ago"`

If all checks pass, the "error" is historical. Do not debug.

But verification commands aren't enough. You need to train your agent to distinguish between error evidence and error echoes.

I added this to our coding agent's instructions:

## Error Classification Rules

**Current errors** have:
- Active error codes from fresh commands
- Failed health checks right now
- Services that won't start when you try

**Historical errors** have:
- Error messages in scrollback
- Old log entries
- Stack traces from previous runs

Never debug historical errors. They're already solved.

The bigger issue is that most agents treat terminal output like a conversation. They read everything and assume it's all current context. But terminals accumulate garbage. A 4-hour coding session will have dozens of false starts, failed attempts, and resolved errors.

Your agent needs terminal hygiene.

I built a simple wrapper that gives our agent a clean slate:

#!/bin/bash
# fresh-session.sh

clear
echo "=== NEW AGENT SESSION $(date) ==="
echo "Previous session archived. Starting clean."
echo "Run 'show-archive' to see previous output."

# Archive previous session
history -w ~/.agent_archive/$(date +%Y%m%d_%H%M%S).log

Now when our agent starts debugging, it's looking at current state, not archaeological evidence.

Result: Our agent stopped chasing phantom failures. Debug time dropped 60%. API costs fell because it wasn't burning tokens on solved problems.

The pattern works for any long-running agent session. Web scraping agents stop "fixing" cached errors. Support agents stop reopening resolved tickets. Data agents stop reprocessing completed jobs.

Your agent doesn't need better debugging skills. It needs to know the difference between current reality and historical noise.