Coding agents debug phantom failures because they read terminal history as current state

Our coding agent was stuck in a 2-hour loop yesterday, "fixing" a test that was already passing. It would run the test, see a failure message in the terminal history, write a fix, run the test again, see it pass, then immediately start debugging the old failure message it found scrolling up.

The problem: agents read terminal output like humans read books — sequentially, from wherever they start looking. But terminals are streams, not documents. Old output doesn't disappear when new output arrives.

Here's what was happening:

$ npm test
✗ auth.test.js - FAILED (10:23 AM)
$ git commit -m "fix auth test"
$ npm test  
✓ auth.test.js - PASSED (10:45 AM)
$ npm test
✓ auth.test.js - PASSED (10:46 AM)

The agent saw that terminal output and thought: "There's a failure in auth.test.js, I should fix it." It completely ignored the timestamps and the fact that subsequent runs were passing.

We fixed this with a simple terminal hygiene rule: clear before every command that produces output you need to trust.

function run_test() {
  clear
  npm test
}

But that wasn't enough. The agent also needed to understand that terminal output has timestamps, and only the most recent output matters for decision-making.

We added this to our coding agent's system prompt:

Terminal Hygiene Rules:
1. Clear the terminal before running tests or build commands
2. Only trust output from the command you just ran
3. If you see multiple test runs, only the most recent one matters
4. Timestamps tell you which output is current

The difference was immediate. Instead of 2-hour debugging loops, our agent now runs a test, sees the current result, and moves on if it passes.

This applies to more than just tests. We've seen agents:

• Try to fix lint errors that were already resolved
• Debug server startup failures from three restarts ago
• Reinstall packages because they saw an old "not found" error

The pattern is always the same: agents treat terminal scrollback as current state instead of historical log.

If your coding agent keeps "fixing" things that aren't broken, check its terminal hygiene. A simple clear command might save you hours of phantom debugging.