Listeners can't be stopped, so bitcoin-node can hang after shutdown when an IPC client reconnects #385

bitcoin/bitcoin#36585 reports a v32.0rc3 node that hit a fatal error, logged "Shutdown done", and then stayed alive for 5.7 hours until systemd killed it. The threads left were the main thread (b-shutoff) and two b-capnp-loop threads, and a mining client was connected over IPC. The report has no backtrace, so the cause of that hang is not confirmed, but the code allows this sequence:

1. Shutdown() calls disconnectIncoming(), which closes the IPC connections that exist at that moment.
2. Nothing stops the listeners. ListenConnections returns void, so Bitcoin Core's CapnpProtocol::listen() has no handle to stop, and _Listen keeps an accept() pending.
3. A client that reconnects, as a mining client does when its connection drops, is accepted and served. Each Connection holds an EventLoopRef.
4. After "Shutdown done", ~CapnpProtocol releases its own reference and joins the event loop thread, which runs until no references remain. It waits for as long as the new client stays connected. SIGTERM does nothing at that point, since shutdown has already run.

Proposed change

• libmultiprocess: ListenConnections returns the Listener (or a handle to it), and a stop call, run on the event loop thread, prevents further accepts. After stopping, a pending accept() that completes is not served, and disconnect callbacks do not resume accepting at the connection limit. This was suggested in the #269 review. Closing the listening socket on stop would also make clients get "connection refused" instead of waiting in the backlog.
• Bitcoin Core: CapnpProtocol keeps the handles from listen() and stops them at the start of disconnectIncoming(), before closing the current connections.
• Tests: a listen_tests.cpp case that stops a listener and checks that a later client is not served, including at the connection limit, and a Bitcoin Core functional test that reconnects an IPC client right after shutdown disconnects it and checks that the process exits.

The stop logic has to be tested together with the accept-retry fix in #384 and the connection-limit fix in #361, which change the same accept loop.

Origin

The window was opened by bitcoin/bitcoin#32345 ("ipc: Handle unclean shutdowns better", 2025, first released in v30.0). Before it, shutdown waited for every IPC client to disconnect on its own, so a connected client could block shutdown indefinitely. bitcoin/bitcoin@7f65aac78b95 made shutdown disconnect clients instead, but did not stop new ones from connecting, because the library has no way to stop a listener. bitcoin/bitcoin#35932 lists "new connections can still be accepted during shutdown" as a known limitation. Releases from v30.0 on are affected.

The missing stop operation was also reported privately in an independent security review (2026-08-16), at the time as an API gap with no effect on Bitcoin Core.

Links

• ipcbugs pages: https://ipcbugs.ofsky.org/bugs/bitcoin-36585-shutdown-reconnect-hang/, https://ipcbugs.ofsky.org/audits/ar-21/
• bitcoin/bitcoin#36585 (report), bitcoin/bitcoin#32345, bitcoin/bitcoin#35932, #269, #361, #384