Isolation, file ownership and cleanup: the boring half of running coding agents in parallel on Windows

Someone left a comment on my last post that was a better outline than the post was:

Parallel agents are only practical when the workspace boundaries are boring and explicit. On Windows especially, I would care less about the launch trick and more about isolation, logs, file ownership, and cleanup after failed runs.

That is Alex Shev, and he is right. Four agents in a pane grid is the screenshot. The four things he listed are what decide whether you are still using the setup in a month.

I work on NestMux, so I have a stake in this. Most of what is below is plain Windows and plain git, and the commands run the same whether or not you use it. Where I describe a decision we made, I say so, and I say where it still falls short.

Isolation is not one HOME variable

Two agents running under the same Windows account share ~/.claude, ~/.codex, ~/.gemini. Same config, and more importantly the same authenticated session. If you want two Claude accounts side by side, they need separate home directories.

On Windows, HOME is not the variable that gets you there. It is a POSIX convention that some tools honor and Windows itself does not. Set only HOME and you get a half-redirected agent: the CLI writes its config to the new location while git writes .gitconfig to the old one, and you will not notice until two panes start sharing a git identity. What you actually need per process:

HOME       = <accountDir>
USERPROFILE= <accountDir>
HOMEDRIVE  = C:
HOMEPATH   = \path\to\accountDir

Gemini CLI wants GEMINI_CLI_HOME pointing at its own subdirectory on top of that.

One trap if you are building the launcher rather than using one: Node's os.homedir() does not reliably reflect a USERPROFILE you injected at spawn time on Windows. If your app reads homedir() to decide where its own storage lives, and it also redirects USERPROFILE for child processes, those two will disagree. We ended up with a dedicated env var for storage and a separate function for "where a new shell should start", because collapsing them meant every new terminal opened inside the agent's config directory.

The config you do want shared

Full isolation is not what anyone wants. Your CLAUDE.md, your settings.json and your skills should be the same in every pane. So they get linked back to the global copy instead of duplicated.

On Windows that link is more annoying than it sounds. mklink for a file symlink needs elevation or Developer Mode. Junctions do not, so directories are fine. For files the fallback is a hardlink.

That fallback has a sting. A hardlink is not a symlink, so lstat().isSymbolicLink() returns false for it. If you later offer a "detach this account from the shared config" button and implement it as "replace symlinks with real copies", the hardlinked files are skipped, and the account goes on silently editing your global config while the UI says it is detached. Detecting them means comparing the file id:

const a = lstatSync(src,  { bigint: true })
const b = lstatSync(dest, { bigint: true })
const sameFile = a.dev === b.dev && a.ino === b.ino && a.ino !== 0n

bigint: true matters. The regular ino comes back as 0 on some Windows configurations, which makes every pair of files look identical.

File ownership on Windows means open handles

This is the one that generates support questions, and the error message actively points the wrong way.

Set up a repo with a worktree, then put a process inside it with a real working directory:

git -C C:\dev\repo worktree add C:\dev\feat -b feat
Start-Process cmd -WorkingDirectory C:\dev\feat -ArgumentList '/c','timeout /t 60'
git -C C:\dev\repo worktree remove C:\dev\feat --force

error: failed to delete 'C:/dev/feat': Permission denied

Permissions have nothing to do with it. Windows will not delete a directory that is some process's current directory, and git reports the refusal as a permissions error. On Linux the same removal succeeds, which is why this tends to reach Windows users first as a bug report nobody can reproduce.

Two things I only found by trying to write a reliable teardown:

PowerShell's Set-Location does not reproduce it. The PowerShell location is a provider concept layered on top of the process. The underlying working directory stays where the process started. So a Start-Process powershell -Command "Set-Location C:\dev\feat; ..." will let the delete go through, and you will conclude the problem is not real. Use -WorkingDirectory, or cmd, or anything that sets the actual cwd.

Killing the shell is not enough. In the run above I killed the cmd.exe and the delete still failed. The holder was timeout.exe, a child that inherited the working directory and outlived its parent. You need the process tree, not the process.

The practical consequence for anything that manages worktrees: before you touch the filesystem, you have to know which panes are sitting inside the directory. That means recording each pane's cwd at spawn time and killing by path prefix, normalized, because on Windows the same worktree shows up as both C:\dev\feat and C:/dev/feat depending on who wrote the path.

Cleanup after a failed run is where the state gets weird

Here is the part I did not expect. A failed git worktree remove is not a no-op. Continuing from the failure above:

> git -C C:\dev\repo worktree list
C:/dev/repo  39ca293 [master]

> dir C:\dev\feat
(empty)

> git -C C:\dev\repo worktree remove C:\dev\feat --force
fatal: 'C:\dev\feat' is not a working tree

> git -C C:\dev\repo worktree prune -v
(nothing)

Git deleted the worktree contents, deleted the administrative directory under .git/worktrees, and dropped the entry from git worktree list. Then it hit the locked top-level directory and stopped. What survives is an empty folder that git no longer recognizes, will not remove, and does not consider dangling. The branch is still there. prune has nothing to prune because the metadata is already gone.

So the recovery is manual and the order matters:

1. Kill whatever holds the handle, process tree included.
2. Delete the directory yourself.
3. git worktree prune afterwards, for the case where git did not get as far as clearing its own metadata.

Prune first and you can be pruning metadata that still references the directory you are about to delete.

The rule we ended up with in the app, which cost us a bug to learn: if either of those steps fails, keep the entry and report the failure. The tempting version is to drop your own record and call it removed, since the user asked for it to be gone. Then the next refresh reads git worktree list, or the leftover directory, and the worktree reappears looking healthy. Now it cannot be removed through the UI at all, because the code path for removing it assumes the state it just lost. A partial delete reported as success is worse than an error message.

Two smaller things in the same area:

Reconcile on read. People delete worktrees outside your app, with rm -rf or plain git. If your list comes from your own store, entries go stale. Compare against git worktree list on every listing, mark what git no longer knows about, and drop entries whose directory is gone from disk.

Never create a worktree inside .git. An early version of ours put some under .git/worktrees, which is git's own metadata folder. Git will create it, then refuse to treat it as a working tree, so git worktree remove fails permanently and the only exit is manual deletion. If you build paths from a repo path plus a branch name, check where you are about to land.

The setup commands that run before the agent does

Most parallel-agent setups run something after creating a worktree: npm install, a .env copy, a build. That is a place where failures get swallowed.

Three things worth having, none of them clever:

• A per-command timeout. The command that errors is fine, you see it. The one that costs you is the command that prints nothing and never exits. Waiting for a prompt on stdin will do it. Ten minutes per command and then kill it.
• Cancel on teardown. If the setup is still running when someone removes the worktree, cancel it first. Otherwise you are deleting a directory that a live npm install is writing into, which puts you right back in the previous section.
• Redaction. Setup logs catch TOKEN=... lines from an env dump or a verbose install. If you persist those logs, strip them on the way in, not on the way out.

Logs: the part I do not have an answer for

This is where the comment landed hardest and where I have the least to show.

What exists in NestMux today is a per-pane transcript you can save and export as markdown, and a setup log per worktree capped at 200 lines with secrets redacted. What does not exist is anything unified: one timeline across panes, with timestamps, exit codes, and which worktree each line belonged to.

That is exactly the artifact you need in the case the comment described. A run failed overnight, four agents were working, and the question is which one touched what, and in what order. A transcript per pane makes you reconstruct that by hand from four scrollbacks.

I do not have a shipping date for it. I am writing it down as a gap rather than a plan, because the honest state is that pane-level transcripts were easy and a cross-pane log with correct attribution is not, particularly when panes come and go.

What this adds up to

The launch trick genuinely is the easy part. Everything expensive is in teardown: who holds the handle, what state a failed delete leaves behind, and whether your own record of the world still matches the disk afterward. On Windows that is a different set of failures than on Linux, and the error messages are worse.

If you run agents in parallel and you have a teardown that survives a failed run, or a logging setup that actually answers "which agent did this", I would like to see it. Especially if it argues that the whole thing should be a script rather than an application.