fix(server): closing a Claude session no longer leaves plugin MCP servers running

[t3dotgg]

Closing or deleting a Claude session left plugin MCP servers running. The Claude CLI stops the MCP servers it starts, but not their children. So a plugin's bun run start wrapper died and its bun server.ts kept running, writing to a pipe nobody read, and pinned a CPU core until kill -9 (#3089).

Fix

On macOS and Linux, the adapter gives the SDK a spawnClaudeCodeProcess that starts the CLI as the leader of its own process group. When the CLI exits for any reason, the adapter SIGKILLs the rest of that group. The SDK's close path is unchanged (stdin EOF, then SIGTERM, then SIGKILL on the CLI).

• Windows keeps the SDK's own spawn (no process groups).
• A spawner the caller passes in (tests) still wins.
• Commands the agent runs through its Bash tool start their own process groups, so background jobs the agent launched are not affected. I checked this with a real turn: a nohup sleep & job had its own group and survived close, both before and after this change.
• The Linux agent scope wrapper is an exec chain, so the spawned PID is still the CLI.

Tradeoff: the SDK reads stderr only from its own spawn, where it redacts credentials before it adds the tail to exit errors. This spawn sends stderr to /dev/null, so on macOS and Linux a CLI crash logs only its exit code or signal. Copying the stderr without the SDK's redaction would put tokens in server logs. This text only reached server logs, not the UI.

Proof

• New test in ClaudeAgentSdkQueryRunner.test.ts runs the real SDK against a fake CLI that leaves a child running. It fails on main (the child never dies) and passes with the fix. It passed 15 times in a row. The child holds a FIFO open, so the test waits for end-of-file, not a poll.

• Real Claude CLI 2.1.296 through layerQueryRunner, with an MCP server in the real plugin shape (bun run --cwd <plugin> --shell=bun --silent start → bun server.ts):

  	bun server.ts process group	9 s after close
  main	the server's own group	alive
  this PR	the CLI's group	gone

  Same result through the Linux agent scope wrapper, with and without systemd-run --user --scope.

• ClaudeAdapterV2.test.ts + ClaudeAgentSdkQueryRunner.test.ts: 255/255. apps/server typecheck clean.

• Not run: macOS and Windows. The macOS path uses the same POSIX calls as Linux, and the Pi adapter already uses the same detach-and-group-kill pattern.

The diagnosis is from #19045 (closed). This code is new and written from scratch. Fixes #3089.

Reviewed with sol-loop: 2 rounds with GPT-6.1-Sol on high.

Model and harness: Claude Opus 5.5 in Claude Code via T3 Code.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The PR changes the default POSIX Claude process lifecycle, including process-group termination and loss of CLI stderr diagnostics, and adds a targeted cleanup test. It also adds line-level and file-level static-analysis suppression directives, so human review is required.

No code changes detected at b027086. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	4.9 KiB	5.0 KiB	+23 B (+0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	+23 B (+1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.8 KiB	20.9 KiB	+41 B (+0.2%)	29.3 KiB	✅
Codex	Live turn messages	1	2	+1 (+100.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	−31 B (−0.6%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−31 B (−2.5%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	−41 B (−0.2%)	29.3 KiB	✅
Claude	Live turn messages	2	1	−1 (−50.0%)	8	✅

Baseline: 8d11fe1 · PR result: b027086 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 0e0bc7b2-36f4-4ec1-bcd3-c470733abb28

📥 Commits

Reviewing files that changed from the base of the PR and between a693d77 and b027086.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 37894328-e4b0-4c89-bd9d-34679cec3c8a

📥 Commits

Reviewing files that changed from the base of the PR and between 614b432 and a693d77.

📒 Files selected for processing: 2

• apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
• apps/server/src/orchestration-v2/Adapters/ClaudeAgentSdkQueryRunner.test.ts

Limit details: You’ve used all 10 included reviews currently available. Your 18 included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

📝 Walkthrough

The Claude query runner adds non-Windows process-group cleanup for CLI launches. It preserves caller-provided spawners and uses the SDK’s spawning behavior on Windows. A new process test checks child cleanup after session closure.

Changes: Claude CLI process cleanup

Layer / File(s)	Summary
Spawner selection and process-group cleanup apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts	The query runner uses a provided spawner when available. Otherwise, it uses the SDK spawner on Windows and a detached process-group spawner on other platforms. When the CLI exits, the custom spawner sends SIGKILL to the remaining process group.
Child-process cleanup test apps/server/src/orchestration-v2/Adapters/ClaudeAgentSdkQueryRunner.test.ts	A non-Windows test starts a fake CLI with a child that holds a FIFO open. After the test closes the session, it waits for the FIFO to close.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: bil0000

Merge Risk: ⚪ Minimal · up to a693d

The tested close path cleans up the CLI’s remaining child process. No concrete issue requiring a change before merge was established.

Pre-merge checks: 4

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: stopping plugin MCP servers when a Claude session closes.
Description check		The description is mostly complete. It explains the problem, implementation, platform scope, tradeoffs, issue references, test results, manual verification, untested platforms, and agent details. It u…
Linked Issues check		The directly linked active issue is #3089. spawnClaudeProcessGroup starts the non-Windows Claude CLI with detached: true, and its exit handler sends SIGKILL to the CLI process group. This cove…
Out of Scope Changes check		The changed production code is limited to Claude CLI process-group spawning and cleanup for #3089. The test changes provide direct coverage for the lingering-child failure mode. The stderr behavior co…

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}