Recovering from a runaway agent: rollback patterns

A runaway agent is the AI workflow equivalent of a runaway intern with sudo. The good news: if your workflow uses worktrees and commits, recovery is straightforward. If it doesn't, recovery is stressful.

This post is the rollback playbook for both cases.

What "runaway" looks like

Three common patterns:

1. Scope explosion

You asked for one thing; the agent did 50 things. The diff has 200 changed files when 10 were expected.

2. Wrong-tree refactor

The agent decided to refactor an adjacent module that "looked similar." Now your auth rewrite has changed the user-management UI.

3. Aggressive removal

The agent removed code it judged "unused." Some of it was actually used. Tests fail; production won't build.

In all three cases, the immediate need is the same: revert to a known-good state, then decide what to do with the agent's work.

Recovery, in order of safety

Best case: working in a worktree on a feature branch (recommended)

Setup that prevents stress:

git worktree add ~/dev/sessions/2026-04-22-auth-rewrite/repo feat/auth-jwt

When the agent goes runaway:

cd ~/dev/sessions/2026-04-22-auth-rewrite/repo

# Option A: revert to the worktree's branch HEAD before the runaway
git reset --hard HEAD@{1}    # one HEAD position back
# or specific commit:
git reset --hard <known-good-commit>

# Option B: if no commits yet in this session, reset to main
git reset --hard origin/main

Your main worktree is untouched. The "damage" is contained to the session worktree, which you can throw away entirely:

cd ~/dev/repos/main-app
git worktree remove ~/dev/sessions/2026-04-22-auth-rewrite/repo --force
git branch -D feat/auth-jwt

Five minutes, no stress. Spawn a new worktree, re-prompt with sharper scope.

Second-best case: working on a feature branch in main worktree

Slightly more risk but still manageable:

cd ~/dev/repos/main-app

# You're on feat/auth-jwt with runaway changes
git checkout main             # leave the bad branch
git branch -D feat/auth-jwt   # delete (force; you've left it)

The bad branch is gone. Your main worktree is back on main. Zero damage to main.

If you wanted to salvage parts:

# Before deleting, cherry-pick the good commits
git checkout -b feat/auth-jwt-salvaged
git cherry-pick <good-commit-1>
git cherry-pick <good-commit-2>
git checkout main
git branch -D feat/auth-jwt   # delete the bad branch

Worst case: the agent committed directly to main (don't do this)

If the agent committed to main and pushed:

git revert <bad-commit-sha>   # creates a new commit that undoes
git push                      # push the revert

Don't git reset --hard on main if it's been pushed — colleagues will fight you.

If the bad commits are pushed, revert is the safe path. It leaves history clean and shipped.

Recovering uncommitted changes

If the agent ran for hours and didn't commit, options narrow:

Option 1: stash and inspect

git stash                # save current state to stash
git stash list           # see what's there
git stash show -p stash@{0}  # see the diff
git stash drop stash@{0}     # discard if you don't want it
# or:
git stash pop                # restore (and remove from stash)

Option 2: reflog for recent HEAD positions

git reflog
# Shows recent HEAD positions; find the one before the runaway
git reset --hard HEAD@{N}   # N is the position number

Option 3: lost objects

If git operations went wild:

git fsck --lost-found
# Lists dangling objects you might recover
git show <sha>

This is the "sift through the trash" option. Use only when the others fail.

Option 4: editor local history

VS Code, Cursor, JetBrains all have local file history independent of git. Right-click a file → "Local History" → restore from a recent version.

This is the safety net when git can't help.

After the rollback

Three follow-up steps:

1. Diagnose what went wrong

Was it:

• Vague prompt: agent had no scope, wandered.
• Vague CLAUDE.md: scope wasn't enforced.
• Agent error: agent misunderstood a clear scope.
• Ambiguous codebase: pattern was unclear, agent guessed wrong.

The diagnosis informs the fix.

2. Update CLAUDE.md

Add a counter-example:

## Pitfalls
- Don't refactor the user-management module when working on auth.
  Past failure: agent saw `users-controller.ts` and "improved" it
  while doing auth work. Reverted on 2026-04-22.

The counter-example prevents the next instance.

3. Re-spawn with sharper scope

Don't just retry the same prompt. Tighten:

# Session: rewrite-auth-main — 2026-04-22 (retry)

## Goal
Replace CookieAuth with JwtAuth in src/auth/ ONLY.

## Files in scope (read + edit)
- src/auth/CookieAuth.ts
- src/auth/JwtAuth.ts
- src/auth/middleware.ts
- src/auth/auth-repo.ts
- tests/auth/*

## Files NOT in scope (do not read or modify)
- src/users/* — separate session
- migrations/* — handled by infra team
- Any file outside src/auth/ except tests/auth/

The explicit "files not in scope" is what prevents the runaway.

Salvage workflow (when partial work is good)

Sometimes 60% of the agent's work is correct; you don't want to throw it away.

Approach 1: cherry-pick

Before reverting, identify the good commits:

git log --oneline                         # list commits
git log --stat <commit>                   # see what each changed

For each good commit:

git cherry-pick <sha>

Apply each one to a fresh branch. Skip the bad ones.

Approach 2: hunk-level salvage

If commits mix good and bad changes:

git checkout main
git checkout -b salvage
git checkout <bad-branch> -- <specific-good-files>
git add -p   # interactively stage only the good hunks
git commit -m "salvage: good parts from <session>"

This is fiddly but works for messy cases.

Approach 3: copy + paste

For small good parts, just open the runaway worktree, copy the relevant code, paste into a fresh branch. Less elegant but fast.

Prevention

Recovery is annoying. Prevention is better.

Tight CLAUDE.md scope

Most runaways trace to vague scope. Be explicit about what's in vs. out:

## Files in scope
- src/auth/* (read + edit)

## Files NOT in scope
- everything else

## When in doubt
- Ask before touching a file outside scope.
- Don't "helpfully" refactor adjacent code.

Worktree per session

Always. Worktrees contain damage to a directory you can throw away.

Commit early, commit often

If you're letting an agent run long-running, instruct it (in CLAUDE.md):

## Commit cadence
- After every logical step, commit with descriptive message.
- Don't accumulate >50 lines without a commit.

Frequent commits = better reflog = easier rollback.

Snapshot before risky tasks

Before kicking off a task you suspect might go wrong:

git tag pre-experiment

If things go bad: git reset --hard pre-experiment. Easy.

Read CLAUDE.md scope back to the agent

> Before starting, restate the scope from CLAUDE.md and confirm you understand
> what's NOT in scope.

If the agent's restatement is wrong, fix the CLAUDE.md before letting it work.

File-manager setup for recovery

When recovering, mq-dir's quad-pane is useful:

• Pane 1: the session's worktree (the runaway).
• Pane 2: main worktree of the same repo.
• Pane 3: a fresh worktree where you'll salvage to.
• Pane 4: cmux pane for git commands.

You see the bad state, the good state, the salvage destination, and the commands all at once. No alt-tabbing during stressful recovery.

Verdict

Runaway agents are inevitable; recovery doesn't have to be stressful. The setup that minimizes pain:

1. Worktree per session (damage contained).
2. Commit early and often (reflog is rich).
3. Tight CLAUDE.md scope (prevents most runaways).

When recovery is needed:

1. Identify the worktree/branch.
2. Reset to a known-good state.
3. Optionally salvage good parts via cherry-pick.
4. Update CLAUDE.md to prevent the next instance.

Five minutes to recover from a contained runaway. Hours to recover from one that touched main directly.

The setup investment (worktrees, commits, CLAUDE.md) pays back the first time you have a runaway. Worth doing before you need it.

mq-dir's quad-pane is well-suited for both running parallel sessions safely and recovering when things go wrong. Free, MIT.