Feature request: reap processes started in a worktree on `wt remove`?

[max-sixty]

Removing a worktree leaves behind any long-running processes that were started inside it — dev servers, watchers, language servers, tmux panes spawned by a post-start hook. wt remove deletes the directory (or trashes it) but the processes keep running, holding ports and file handles and, on the trash path, referencing files that no longer exist at their old path.

Would it be feasible for wt to reap those processes, perhaps as an option on wt remove?

The interesting part is identifying which processes "belong to" the worktree, since that's where I'd expect the feasibility to be decided:

• By working directory — processes whose cwd is under the worktree path (lsof -a -d cwd +D <path> on macOS, /proc/*/cwd on Linux). Catches most dev servers, but misses a process that started in the worktree and then chdir'd away, and a daemon that forked and re-parented to init.
• By process group / session — if wt recorded the pgid of hook-spawned processes at post-start, it could signal that group at remove. More reliable for things wt itself launched, but nothing for processes the user started by hand in the worktree.
• By tmux/zellij session — for the common case where a post-start hook opens a multiplexer session named after the worktree, "reaping" might just mean killing that session.

Open questions:

• Is cwd-based detection reliable enough to reap by default, or would it need to be opt-in given the risk of killing something unrelated?
• Should this build on the existing pre-remove hook (letting the user supply the kill logic) rather than wt implementing process discovery itself? A pre-remove hook already has the worktree path and can run whatever the user wants — so this might be a docs/example question rather than a code one.
• How should it interact with the trash-vs-delete path and the --force flag?

Mostly asking whether this is in scope for wt at all, versus something better left to a user-supplied pre-remove hook.

This was written by Claude Code on behalf of max

[worktrunk-bot]

Thanks for the thoughtful writeup — your instinct that this leans toward a hooks/docs question rather than a code one matches how worktrunk already handles it. Two of the three approaches you sketched are already shipped:

Process group / session → wt step tether (experimental). You wrap the long-lived command with it — typically inside a post-start hook — and worktrunk ties the command's lifetime to the worktree, killing the whole process group (SIGTERM, then SIGKILL) once the worktree is gone. Crucially it addresses the reparent/rm -rf gap you flagged: teardown watches the worktree root, not wt remove specifically, so a plain git worktree remove, an rm -rf, or a crashed hook still trips it — the exact leak that a pre-remove hook alone misses. This was built for the leak you're describing (on macOS the accumulation eventually saturates fseventsd).

# .config/wt.toml
[post-start]
server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}"

tmux/zellij session, or anything wt didn't launch → pre-remove hook. The hook runs in the worktree being removed with {{ worktree_path }}, {{ branch }}, and the same hash_port/sanitize filters your post-start used, so port- and session-based teardown line up deterministically across the two hooks. The tips & patterns page has worked recipes — tmux (tmux kill-session -t {{ branch | sanitize }}), a Docker container per worktree, and a dev-server-behind-Caddy setup that stops the container on remove:

[pre-remove]
tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"

The one approach that's deliberately not built is cwd-based auto-discovery (lsof +D / walking /proc/*/cwd). Your own open question answers why: it can't reap by default without risking killing something unrelated (the reparented daemon it misses vs. the innocent shell sitting in the directory it'd catch), and it's the least reliable of the three for exactly the cases you listed. worktrunk deliberately keeps flag/config surface small and routes niche workflow needs through hooks and wt step tether rather than native process discovery — the tether route gets you the reliable subset (things worktrunk launched) without the false-positive risk, and pre-remove covers the rest with logic you control.

So for the interaction questions: it's orthogonal to trash-vs-delete and --force, because reaping happens before the directory is touched (pre-remove runs with the worktree still present) or is tied to the directory's disappearance (tether), not to how the removal is performed.

If there's a gap left — e.g. tether doesn't fit a workflow of yours, or a recipe is missing from the docs — happy to dig into that specific case.

[max-sixty]

How likely are there to be processes we would want to keep? I'm thinking of a wt remove --kill-processes or similar, which looks for processes under that path and kills them; as an alternative to starting everything with wt step tether and maybe missing things...

[worktrunk-bot]

Good question — the honest answer is that the false-positive set is small but sharp, so it decides the design.

What lives under a worktree cwd, split by whether you'd want to kill it:

• Reap-me: dev servers, watchers, LSPs spawned by post-start, ad-hoc npm run dev — the ones you filed this about. These are the bulk.
• Keep-me: an editor opened in the worktree (VS Code, nvim) and an interactive shell the user cd'd in. Not many, but killing either is hostile — and an editor with unsaved buffers is exactly the "silent loss of work" the Data Safety rules tell us to refuse without explicit consent. So this can't be default-on; it's --kill-processes at most, and arguably it should list-then-confirm (or --dry-run) before signalling, the same posture as trash-vs-delete.

The part worth flagging before building it: cwd matching is wrong in both directions, so --kill-processes and wt step tether aren't substitutes — neither is a superset of the other.

• cwd is over-inclusive: catches the editor/shell above.
• cwd is under-inclusive: misses the two cases from the issue body — a daemon that forked and chdir'd away, and one that reparented to PID 1. Those hold the port you're trying to free but no longer report a cwd under the path. Precisely what tether is built to reap (it kills the whole process group, so a reparented child and the esbuild sidecar that never held the cwd still die).

So the "start everything with tether and maybe miss things" worry is real, but --kill-processes closes a different gap (hand-started processes wt never launched) while opening the reparent gap that tether closes. The reliable design is both, not one instead of the other: tether for what wt launches, --kill-processes --dry-run/confirm for the long tail wt didn't.

Feasibility/portability: cwd discovery is /proc/*/cwd on Linux and lsof -a -d cwd +D <path> on macOS; Windows has no cheap per-process cwd, which is the same wall tether already documents (taskkill /T reaches a live tree but not a post-exit detach). There's a small precedent for wt reaping processes it recognizes — run_internal_sweep already reaps orphaned git fsmonitor--daemon on remove — but that's wt's own known daemon, not arbitrary user processes, so it doesn't carry the false-positive question; --kill-processes would be the first place we signal processes we didn't spawn.

My read: worth it as opt-in, with a preview/confirm step and a filter that excludes TTY-attached processes (the interactive shell) to shrink the keep-me set. Happy to prototype the Linux /proc path behind --kill-processes (list-only first, so it prints what it would signal without killing anything) if you want to see the false-positive rate on a real session before committing to the semantics.

[max-sixty]

OK, let's add it as a flag on wt remove and mark as experimental. Come up with a good name, please

[worktrunk-bot]

Went with --reap — it's the term this thread and the issue title already use, it's concise, and the messages read naturally (◎ Reaping 2 processes under feature worktree). Opened #3396.

It's experimental and opt-in, discovers by cwd (lsof -d cwd), and keeps the conservative posture we landed on: processes holding a controlling terminal (interactive shells, terminal editors with unsaved buffers) are spared, only detached servers/watchers are candidates, and the list is printed before signalling. Reaping runs before the directory is staged, so it's orthogonal to background/trash/--force. cwd discovery stays under-inclusive by design — reparented/chdir'd daemons still need wt step tether — and the docs say so. Unix only.

One open call for you on the PR: I print-then-signal rather than adding an interactive confirm / --dry-run in this first cut. Happy to add a confirm step if you'd prefer that as the default for an experimental kill.