fix(process): safely clean up lingering worktree processes

[kunchenguid]

Summary

• Terminate lingering processes tied to a worktree before it is returned or reused so pooled worktrees do not carry background editors or agents that can block cleanup.
• Protect the current process chain more conservatively during cleanup, including fallback handling for parent lookup failures, to avoid killing the invoking treehouse session.
• Add cross-platform termination coverage, tests, and documentation updates so get and return reflect the new process-cleanup behavior.

Risk Assessment

⚠️ Medium: The change is well-scoped, but it adds destructive process cleanup on the return path and still has silent-failure and Windows race conditions that could leave pooled worktrees in an inconsistent state.

Testing

• ✅ Test - passed

Pipeline

Updates from git push no-mistakes

✅ **Rebase** - passed

Round 1 - passed ✅

⚠️ **Review** - 2 warnings

Round 1 - found 2 issues (1 error, 1 warning)

• 🚨 cmd/return_cmd.go:58 - treehouse return now calls killLingeringProcesses before cleanup, so invoking it from inside the target worktree will match the current treehouse process and the caller's shell by cwd and send them SIGTERM/SIGKILL. That can kill the command before pool.Release runs and abruptly terminate the user's session.
• ⚠️ cmd/return_cmd.go:58 - Returning a worktree by path now unconditionally terminates every process with that worktree as cwd, even without --force or any in-use confirmation. This is a significant behavior change from a cleanup command and can silently kill another active agent/editor session unless that UX is explicitly intended.

Round 2 (auto-fix) - found 1 warning

• ⚠️ internal/process/terminate.go:45 - If parentPID lookup fails while protecting the current process chain, the loop stops and leaves ancestor processes unprotected. In that fallback case treehouse return can still terminate the invoking shell or wrapper process from inside the worktree, which is the exact failure mode this patch is trying to prevent. Make the failure path conservative by skipping termination entirely, or by treating unknown ancestors as protected instead of continuing with a partial filter.

Round 3 (auto-fix) - found 2 warnings

• ⚠️ internal/process/terminate.go:45 - If walking the current process's parent chain fails, filterProtectedProcesses returns nil, and callers treat that as 'no lingering processes' and proceed to reset/reuse the worktree. A transient gopsutil failure here can leave background processes running against a pooled worktree with no warning.
• ⚠️ internal/process/terminate_windows.go:11 - The Windows termination path fires TerminateProcess and returns immediately, but return/get reset the worktree right after this call. Because process teardown and handle release are asynchronous on Windows, this can race into flaky checkout/clean failures when a just-killed process still has files open.

✅ **Test** - passed

Round 1 - found 0 issues

🔧 **Document** - 2 issues found → auto-fixed (2)

Round 1 - found 2 warnings

• ⚠️ README.md:37 - The Quick Start and lifecycle docs do not mention that leaving a worktree via treehouse/treehouse get now terminates lingering processes whose cwd is inside that worktree before returning it to the pool. This is a new user-visible behavior and should be documented where the exit flow is described.
• ⚠️ README.md:139 - The CLI reference for treehouse return [path] is now incomplete: return also kills lingering worktree-scoped processes before cleaning and pooling the worktree. The command description or flag/usage docs should mention this side effect so users know detached tools will be stopped.

Round 2 (auto-fix) - found 2 issues (1 warning, 1 info)

• ⚠️ cmd/return_cmd.go:20 - The Cobra short help still says Return a worktree to the pool, but this change now terminates lingering worktree processes before release. Update the command help text so treehouse help return matches the new behavior documented in the README.
• ℹ️ AGENTS.md:14 - internal/process/ is documented as only providing in-use detection via cwd scanning, but this change adds cross-platform termination of lingering worktree processes as well. Update the project structure note so internal docs reflect the package’s expanded responsibility.

Round 3 (auto-fix) - found 0 issues

✅ **Lint** - passed

Round 1 - found 0 issues

✅ **Push** - passed

Round 1 - passed ✅