fix(mcp): shut down gracefully on stdin EOF instead of orphaning to PID 1 (#751)

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.

[fa1k3]

Summary

Fixes#751.

The SDK's StdioServerTransport subscribes to stdin data/error only and never notices end/close. When the parent MCP client dies, no teardown runs: whenever anything still references the event loop (a warm llama.cpp model's native handles being the common case), qmd mcp reparents to PID 1, leaks RAM, and keeps the SQLite index open. Multiple such orphans can pile up across client sessions.

What changed

startMcpServer() now registers registerStdioEofShutdown() after server.connect(). On stdin EOF it treats the client as disconnected and tears down gracefully:

1. server.close() — stop the transport, no further requests are dispatched
2. in-flight drain — a new InflightGate counts running tool/resource handlers; shutdown waits (bounded, 5 s default) for them to settle so their store/llm dependencies are not torn down underneath them
3. store.close() — last, and it disposes this store's own LlamaCpp instance before closing the database. (The shutdown helper takes an optional disposeLlm step for callers that own a separate instance, but the MCP path deliberately does not pass it: store.close() already owns the disposal, and defaulting to the global disposeDefaultLlamaCpp would risk tearing down an unrelated instance in an embedded process.)
4. process.exitCode = 0 (or 1 if a step failed; an earlier nonzero code is preserved, not masked) and let the loop drain

Design decisions, mirroring existing house patterns:

• No process.exit(). Setting process.exitCode keeps beforeExit alive so node-llama-cpp's auto-dispose runs before libc's static destructors — forced exits during native-addon unload have crashed before (SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59, Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129). Same rationale as finishSuccessfulCliCommand on the CLI side.
• EOF means disconnect. No response-delivery promise is made — with stdin at EOF there is nobody left to read one. Handlers that are already running get the bounded drain window above; the SDK's close semantics still signal cancellation. Because server.close() runs before the drain, the transport stops dispatching new requests first, so the gate only ever waits on already-dispatched work (its count is not a closed admission barrier, and does not need to be under this ordering).
• Idempotent shared-promise shutdown (like the HTTP transport's stop()): end, close, an already-ended stdin at registration time, and manual invocations all collapse into one run; listeners are removed on entry.
• Failure-tolerant chain: a failing step is logged (QMD Warning: … continuing shutdown.) and does not stop the remaining steps.
• stderr breadcrumbShutting down (stdin closed)..., matching the HTTP transport's SIGTERM/SIGINT messages, and giving tests an observable signal that the EOF path (not a coincidental event-loop drain) produced the exit. All logging is best-effort: the parent's death may have closed stderr too, so writes can never take the teardown down with them.
• No forced-exit watchdog. A timer that force-exits mid-cleanup would re-open exactly the SIGABRT crash on exit during Metal cleanup (macOS ARM64) #59/Bun segfaults on Windows after vsearch/query due to process.exit() during native addon unload #129 crash class. In testing (Linux, warm embedding model), disposal + natural drain exits within ~100 ms of EOF; if a reproducible post-dispose hang shows up on some platform, a watchdog armed only after the teardown chain completes would be the safe follow-up.

Related: modelcontextprotocol/typescript-sdk#2003 (open, not yet merged) proposes fixing the same gap at the transport layer. This change stays correct alongside it once it lands (the teardown is idempotent), and qmd needs its own store/llm cleanup either way.

Note: the changelog entry lands in the same [Unreleased] › Fixed block as #766 (the atomic-cleanup PR), so a trivial changelog conflict is expected if both merge — happy to rebase whichever lands second.

Verification

• New test/mcp-stdio-lifecycle.test.ts:
  • unit tests drive registerStdioEofShutdown via injected stdin (mirroring the DI style of the finishSuccessfulCliCommand tests): teardown order incl. the in-flight drain, end/close/manual idempotency, failure tolerance incl. all-steps-failing and a throwing stderr, drain-deadline miss, exit-code preservation, already-ended/destroyed stdin at registration
  • createInflightGate unit tests: immediate idle, settle-wait, missed deadline, rejecting handler releases the gate
  • end-to-end: spawns the real server with piped stdio, completes an initialize round-trip, closes stdin, and asserts a prompt code-0 exit through the EOF shutdown path (stderr breadcrumb; without it a modelless server can exit 0 by coincidence)
• Manually verified with a warm embedding model (Linux): the patched server logs the breadcrumb and exits code 0 within ~100 ms of stdin EOF. (I could not reproduce the indefinite hang itself on this Linux box — whether something keeps the loop alive after EOF is platform/timing dependent — but with this change the teardown no longer relies on the loop happening to drain.)
• bun run test:types clean, bun run build passes, suites green under vitest via Node and bun test
• Changelog entry under [Unreleased]

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #836 after rebase onto main.

[tobi]

Superseded by #837 (relanded onto current main; CHANGELOG conflict resolved). Closing in favor of the reland.