# 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](../providers/))
3. Abort the session and retry if startup is clearly wedged:

```text
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:**

```bash
# 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:

```bash
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:**

```bash
# 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:

```text
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](/valdr/docs/ui/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:**

```text
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

- [Agent Sessions UI](/valdr/docs/ui/agent-sessions/)
- [pm_session MCP reference](/valdr/docs/valdr-mcp/sessions/)
- [Launching Agents](/valdr/docs/ui/tasks/agent-launch/)