The safety rule
An agent worked all night in a session folder. If that folder holds the only copy of what it did, nucleate will not remove it, whoever asks. This page is exactly what it checks, in what order, and what to do when a session will not go.
nucleateOn this page
- The rule
- What nucleate checks
- 1. Is anything uncommitted?
- 2. Is the branch ahead of its upstream?
- 3. With no upstream, is the commit anywhere else?
- Why it asks GitHub
- When GitHub cannot be reached
- A session is all or nothing
- What happens to the branch
- What force discards
- Never delete a session folder by hand
- When a session will not go
The rule #
nucleate never removes a worktree that holds work stored nowhere else.
That covers three things:
- uncommitted or untracked changes;
- commits that have not been pushed;
- a commit that is on no remote branch and is not the head of a merged pull request.
The rule is the same whoever asks: you at a shell, the WorktreeRemove hook when a session ends, an agent calling the remove_repo tool, or the cleanup job in nucleated. When the answer is no, nothing is deleted, the reason is printed, and the folder stays exactly as it was.
A session folder that outlives its session is therefore not clutter. It is a to-do list: something in it still needs you.
What nucleate checks #
For each worktree, in this order. Every check that fails adds a reason; nucleate status lists them under unsafe_reasons.
1. Is anything uncommitted? #
It runs git status --porcelain in the worktree. Any output, a modified file, a staged change or a file git has never seen, is a reason:
uncommitted changes
2. Is the branch ahead of its upstream? #
If the branch tracks an upstream, nucleate counts the commits the branch has that the upstream does not. Any at all is a reason, with the count:
2 unpushed commit(s)
A session branch is created from the remote's default branch, and git records that as its upstream. So until the branch is pushed with its own upstream, every commit the agent makes counts as unpushed, which is correct: those commits are nowhere else. Push with -u and the count drops to zero:
git push -u origin HEAD
3. With no upstream, is the commit anywhere else? #
A branch has no upstream when it was never given one, or when its remote branch has been deleted, which is what happens after a pull request is merged and the branch is cleaned up.
Then nucleate asks two questions about the commit the worktree is on:
- Does any remote branch contain it? If so, it is stored elsewhere and the worktree is safe.
- If not, is it the head of a merged pull request? This one is asked of GitHub.
If both answers are no:
HEAD is not on any remote branch or merged pull request
Why it asks GitHub #
A squash merge is the reason. When a pull request is squashed, GitHub writes one new commit to the default branch and the branch is usually deleted. The commits the agent made are now on no branch at all, yet the work is finished and safe. From inside the repository, that is indistinguishable from work that was never pushed.
GitHub can tell them apart. nucleate asks it for the pull requests associated with the commit, and treats the work as stored when one of them is merged and has exactly this commit as its head.
Two details follow from "exactly this commit":
- A commit added after the pull request was merged is new work. The worktree is kept.
- A pull request that was closed without merging does not count.
When GitHub cannot be reached #
If there is no answer, the answer is no. No network, a timeout (15 seconds), a rate limit, a private repository with no token, a remote that is not on GitHub: each one counts as "not merged", and the worktree is kept. nucleate never deletes on doubt.
For private repositories the question needs a token. nucleate takes it from GH_TOKEN, then GITHUB_TOKEN, then the file named by github_token_file in its configuration.
A session is all or nothing #
nucleate remove-session checks every repo in the session before it removes anything. One repo with unsaved work keeps the whole session, the clean repos included:
nucleate: refusing to remove session with unsaved work: api: 2 unpushed commit(s) | web: uncommitted changes
Half a session is worse than a whole one: an agent that comes back to it would find some of its repos gone. So a session is either complete or absent.
What happens to the branch #
When a worktree is removed, its local branch in the bare clone is deleted only if the branch's tip is on a remote branch or is the head of a merged pull request. That is the same test as above, applied to the branch.
Otherwise the branch stays. This matters most with --force.
What force discards #
nucleate remove <repo> --force removes one worktree whatever it holds. There is no force for a whole session, on purpose.
| What was in the worktree | After --force |
|---|---|
| Uncommitted and untracked files | Gone. There is no way back. |
| Commits that were pushed, or merged | Safe on the remote. The local branch is deleted. |
| Commits that were never pushed | Still on the local branch in the bare clone. |
So forced-away commits can be brought back. Start a session and add the repo on the old branch; the branch still exists, so the worktree checks it out:
nucleate create-session rescue
nucleate add web workspace/fix-login --session rescue
Never delete a session folder by hand #
rm -rf on a session folder skips every check on this page. It also leaves the bare clones believing those worktrees still exist, which blocks the branch from being checked out again.
If it has already happened, tell each clone to forget the missing worktrees:
git --git-dir="$HOME/workspace/.repos/web.git" worktree prune
Commits survive this, because they live in the bare clone and not in the folder. Uncommitted files do not.
When a session will not go #
Ask the session what it is holding:
nucleate status --session fix-login
Then act on each reason in unsafe_reasons.
| Reason | What to do |
|---|---|
uncommitted changes |
In the worktree, run git status. Commit what should be kept and delete what should not. |
2 unpushed commit(s) |
In the worktree, git push -u origin HEAD. If the branch was already pushed without -u, the same command fixes the tracking. |
HEAD is not on any remote branch or merged pull request |
The remote branch is gone and GitHub did not confirm a merge. See below. |
For the last reason, work out which case you are in:
- The pull request was merged, but GitHub could not be asked. Check the network, and for a private repository check that the token file exists and is fresh. On a box built with the recipe that is
/run/agent-tokens/github. Then run the removal again. - Commits were added after the merge. Push the branch again and open a new pull request, or decide they are not needed.
- The pull request was closed, not merged. The work exists only here. Push the branch again to keep it, or force the repo out to discard it.
When you are certain a repo's contents are not needed:
nucleate remove web --force --session fix-login
nucleate remove-session fix-login