fix(agent-manager): parallelize worktree terminal cleanup

[marius-kilocode]

What Problem This Solves

Agent Manager removes residual backend terminals one at a time before deleting a worktree. Each removal waits for process-tree termination and verification, so the waits add up when several terminals remain. Profiling reproduced a roughly 4.3-second deletion for eight idle shells, while the webview spent only a few milliseconds executing JavaScript.

Why This Change Was Made

Remove residual PTYs in batches of at most four. This overlaps independent shutdown waits without starting an unbounded number of process-tree scans.

The safety order remains unchanged: block terminal creation, close tracked terminals, await every residual PTY removal, and only then permit disk deletion. Returned SDK errors and thrown rejections are collected across all batches; any cleanup failure still rejects with an AggregateError. Termination grace periods and process-exit verification are not shortened or skipped.

User Impact

Worktrees with multiple residual terminals delete faster. Conversation histories remain available after worktree deletion, and terminals in other worktrees remain running.

This is intentionally limited to terminal cleanup. Checkpoint reclamation, Run-script shutdown, Git operations, and session relocation are unchanged. The separate checkpoint-cleanup bottleneck identified during profiling is not addressed by this PR.

Evidence

Measured the real Agent Manager delete flow on macOS arm64 with vscode-self-test, comparing the unmodified build at 9cbd9e414b against the compiled source change. All tests used a new, independent temporary Git repository, isolated VS Code profiles, and separate Kilo HOME/XDG/database paths. No model prompts or real credentials were used.

Each trial recreated the same worktree with one retained session and the stated number of idle /bin/sh backend PTYs. The Local card was selected before deletion. Timing starts at the confirming click and ends when a DOM observer sees the worktree card disappear. Startup is outside the capture. Each row has three trials per version.

Residual terminals	Before trials (s)	After trials (s)	Before mean	After mean	Change
1	0.796, 0.776, 0.815	0.795, 0.816, 0.810	0.796 s	0.807 s	+0.011 s (+1.4%)
8	4.275, 4.265, 4.289	1.415, 1.401, 1.347	4.276 s	1.388 s	-2.888 s (-67.5%)

The single-terminal ranges overlap; this small sample does not establish a single-terminal speedup. For eight terminals, all three after measurements were below all three baseline measurements. Renderer script time was at most 5.35 ms across these captures, and no trace data loss was reported.

Safety checks exercised against the actual backend and UI:

• All test shell PIDs exited and every tested session ID remained available at the fixture project root after deletion.
• A separate scenario removed eight parent processes and eight child processes. A terminal in a sibling worktree remained running and its directory remained present while the target was deleted. The sibling fixture was then cleaned up separately.
• All 14 fixture histories remained visible in the History UI after their worktrees were removed.
• All 30 pre-existing worktree paths from the initial inventory remained present. No regular-project worktree or session was a deletion target. The isolated test instance and disposable data were cleaned up.

Automated checks passed:

• 43 focused tests across pty-cleanup, agent-manager-provider-lifecycle, and script-terminal-manager.
• Extension compile, typecheck, lint, formatting, unused-export check, and Kilo change-marker guard.
• New deterministic regression coverage checks the concurrency cap, awaiting every removal, directory scoping, and continuation into later batches after both returned and thrown errors.

These are synthetic local macOS measurements, not a Windows or remote-filesystem performance guarantee. Raw profiles and screenshots were retained locally rather than committed. An unrelated VS Code startup delay occurred before the after captures; profiling began only after the UI recovered and was ready.

Manual check: In a disposable project, delete a worktree with several running terminals. Confirm its processes stop, its conversations remain in History, and a sibling worktree's terminal continues running.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (3 files)

• .changeset/fast-worktree-terminal-cleanup.md
• packages/kilo-vscode/src/agent-manager/pty-cleanup.ts
• packages/kilo-vscode/tests/unit/pty-cleanup.test.ts

---

_{Reviewed by grok-4.6 · Input: 58K · Output: 9.9K · Cached: 382.5K}

_{Review guidance: REVIEW.md from base branch main}