Skip to content
Documentation
Troubleshooting
Sessions & Worktrees

Sessions & Worktrees

Common issues with agent sessions: launching, running, reviewing output, and cleaning up worktrees.

Session stuck in starting

Symptom: You launched an agent session but it never transitions to running.

Likely cause: Provider startup failed, the worktree could not be prepared, or the session is waiting on initialization work that never completed.

Fix:

  1. Open the session and check the Transcript and Metadata views for startup errors
  2. Confirm the selected provider is healthy (see Providers & Presets)
  3. Abort the session and retry if startup is clearly wedged:
pm_session { action: "abort", sessionUlid: "..." }

Worktree creation fails

Symptom: Launching a task errors with a git or worktree creation failure.

Likely cause: The repo is in a bad state for worktree creation: detached HEAD, unresolved conflicts, or a working tree that needs attention.

Fix:

# From your repo root
git status
git branch --show-current

# If detached, switch back to your normal branch
git switch <your-branch>

# Refresh local refs if needed
git fetch --all --prune

Then retry the launch.

Agent changes seem to have disappeared after the session

Symptom: The session finished, but you do not see the agent’s changes in your current branch.

Likely cause: The session ran in an isolated worktree. This is by design.

Fix:

  • Open the session’s Worktree Diff view to inspect the changes
  • Open Metadata to find the worktree path and branch name
  • Merge or cherry-pick those changes into your working branch using your normal git workflow

Useful commands once you have the worktree path:

cd <worktree-path>
git status
git branch --show-current
git log --oneline --decorate -n 5

Session worktree merge conflicts

Symptom: Bringing a completed session’s work back into your branch causes merge conflicts.

Likely cause: Your branch moved while the session was running.

Fix:

# From the session worktree path shown in Metadata
cd <worktree-path>
git fetch origin
git rebase origin/<your-target-branch>

Resolve conflicts, then continue the rebase or merge.

Session hangs on a tool call

Symptom: The session shows a tool call in progress but never completes.

Likely cause: The agent is blocked on a long-running shell command, waiting for input, or stuck in a dead subprocess.

Fix:

  • Check the Transcript and Terminal views
  • Abort the session if it is clearly stuck:
pm_session { action: "abort", sessionUlid: "..." }
  • If a subprocess is still alive afterward, stop it manually with ps and kill

Cannot find a previous session after restart

Symptom: You restarted Valdr and a previous session is no longer in the list.

Likely cause: You are looking at a different --pm-home than the one that created the session.

Fix: Check System Monitoring > Process details > PM DB Path and confirm it matches the Valdr instance you used before.

purge removed the session but left files behind

Symptom: pm_session { action: "purge" } completed, but some files remain on disk.

Likely cause: Purge removes session records and tries to clean up session-owned files, but shared worktrees or preserved transcript files can remain.

Fix:

pm_session {
  action: "purge",
  sessionUlid: "...",
  deleteFiles: true,
  dryRun: false
}

If a path still remains, use the session’s Metadata view to find it and remove it manually, for example with git worktree remove <path>.

Related

Providers & PresetsValdr Packs