Fix fatal crash when Bonjour connection drops mid-session

[madisonrickert]

Summary

imcp-server crashes with a Swift top-level fatal error whenever the Bonjour link to the menubar app drops mid-session. Observed 15 times in one week of Claude Desktop MCP logs on a single machine. Every recurrence produces:

critical: Connection closed, terminating...
debug: [ServiceLifecycle] Service finished unexpectedly. Cancelling group.
Swift/ErrorType.swift:254: Fatal error: Error raised at top level:
  ServiceGroupError: errorCode: A service has finished unexpectedly.

The process dies with SIGTRAP-style termination instead of exiting cleanly, which:

• Defeats Claude Desktop's supervisor-driven restart.
• Leaves zombie imcp-server processes accumulating (related to imcp-server process persists after Claude termination when iMCP is not operational #28).
• Amplifies the impact of any menubar-side connection close — including the Bonjour leaks described in [v1.4.0] iMCP crashes repeatedly when multiple services enabled — Bonjour connection leak on macOS Sequoia #165 and the vague "frequent crashing" in Very frequent crashing. #163.

Root cause

MCPService.run() handles StdioProxyError.connectionClosed and NWError codes 54/57 by return-ing. In swift-service-lifecycle 2.x, the default ServiceConfiguration.successTerminationBehavior is .cancelGroup — meaning a Service.run() that returns normally is treated as "finished unexpectedly" and the group raises ServiceGroupError. gracefulShutdownSignals: [] (the default) also means SIGINT/SIGTERM are silently ignored today.

Fix

• successTerminationBehavior: .gracefullyShutdownGroup — returning from run() shuts the group down cleanly; lifecycle.run() completes without throwing; process exits with status 0.
• failureTerminationBehavior: .gracefullyShutdownGroup — same for thrown errors, since there's nothing another layer can recover.
• gracefulShutdownSignals: [.sigint, .sigterm] — signals now trigger graceful shutdown.
• while !Task.isShuttingDownGracefully at the top of the reconnect loop — shutdown is observable between iterations so signals don't wait on the 5s retry sleep.
• Remove the dead MCPService.shutdown() method. The Service protocol in swift-service-lifecycle 2.x declares only run(), so that method was never called.

Test plan

New imcp-serverTests XCTest target with three regression tests:

• testServiceReturningNormallyExitsGroupCleanly — the primary regression guard.
• testDefaultCancelGroupThrowsWhenServiceReturns — pins the pre-fix failure mode so the library's default behavior changing is detectable.
• testTaskIsShuttingDownGracefullyObservedAfterTrigger — validates the loop's shutdown observation via ServiceLifecycleTestKit.

Run: xcodebuild -project iMCP.xcodeproj -scheme imcp-serverTests test — 3/3 pass.

Manual verification:

• SIGTERM → exit code 0, [ServiceLifecycle] Signal caught. Shutting down the group.
• Bonjour peer disappears → exit code 0, log line changed from Service finished unexpectedly. Cancelling group. to Service finished. Gracefully shutting down group.
• Full initialize → tools/list → stdin close round-trip exits cleanly.
• No orphan imcp-server processes after repeated spawns.

Related

• Likely fixes Very frequent crashing. #163 (frequent crashing — no stack trace in the report but the fatal-error signature matches what supervisors would see).
• Makes [v1.4.0] iMCP crashes repeatedly when multiple services enabled — Bonjour connection leak on macOS Sequoia #165 less user-visible: the menubar-side NWConnection leak still happens, but the CLI no longer fatal-errors when the peer goes unhealthy.
• Likely resolves imcp-server process persists after Claude termination when iMCP is not operational #28: zombie imcp-server processes after Claude Desktop termination. Those accumulate because the process exits via fatal error rather than cleanly. A process-table check after applying this change shows zero orphans.

Scope / non-goals

Deliberately out of scope — each is a candidate follow-up:

• The non-cancellable 30s Bonjour discovery (withCheckedThrowingContinuation in MCPService.run()). Worst-case signal-to-exit time when stuck in that state remains ~30s. Relevant to "Could not attach to MCP server iMCP" timeout #24.
• Why the menubar app drops the Bonjour connection after notifications/tools/list_changed in some logs. Menubar-side; unrelated to this CLI fix.
• Pre-existing per-iteration browser/proxy cleanup leaks in MCPService.run().

Independent of #162 (SDK 0.12.0 bump); either can merge first.

[LeDominik]

Hello, I've applied this one together with #162 and it's running much much better and stable now. Previously fast / parallel access to MCP could crash iMCP, this is no longer the case.