[nissa-seru]

Fixes for a runtime MCPL connect that fails partway, and for servers the framework closes for good. A reconnect: true server that the framework closes for good now leaves the registry even when it's down at the time, so a later connect of its id isn't refused as already registered. A runtime connect now settles the data-plane gate it installed on every exit, so when its awareness accounting or its policy registration fails, the other MCPL servers' data is no longer held behind that gate. And a connection closed for good no longer lets out what it held.

Problem

On main (3af13bf4):

• A server closed for good while it's down stays registered. The registry drops an entry from its 'close' listener, for a connection that won't reconnect (src/mcpl/server-registry.ts:53-55), or in closeServer, which removeServer and closeAll call (:72, :144, :151). McplServerConnection.close() returns without emitting 'close' when the connection is already closed, with no close left to finish and no reconnect attempt in flight (src/mcpl/server-connection.ts:939). A reconnect stub, or a server that dropped, is in that state while it waits for its next retry. The framework closes a server for good with connection.close() in three places:

  • The catch that ends a runtime connect or restart whose awareness accounting fails (src/framework.ts:17636). When the server's first connect had failed, the connection there is the stub connectWithReconnect returned. The stub stays registered, and a later connectMcplServer of its id fails with MCPL server "<id>" is already registered (src/mcpl/server-registry.ts:42) until disconnectMcplServer or restartMcplServer drops it. Greptile found this in its review of fix(mcpl): an MCPL server's boolean settings are true or false, and anything else is refused (#379) #451.
  • A refused policy's "close" fallback, after a manifest change (src/framework.ts:17800) and at the initial policy (:17918). The server answered the policy request just before, so it's down there only if it dropped in between.

• A runtime connect that fails partway leaves its gate standing. connectMcplServerInternal installs the data-plane gate before it awaits accounting (src/framework.ts:17616), and installing it pauses every registered server's data plane (:17444). The connect completes the gate only once its policy registration has returned (:17644-17645).

  • When accounting fails, the catch closes the new connection and rethrows, and never fails or completes the gate. The four other runtime gates call failMcplDataPlaneGate when their accounting fails: resume(), syncDiscordAwarenessMarkers(), tools-list reconciliation and reconnect reconciliation (:5137, :17175, :18498, :18553).
  • When the policy registration throws after accounting succeeded, nothing there catches it. The new connection stays connected and registered, and the gate stays standing.

  Either way, every other server's pushes, incoming messages and inference requests are held until some other gate completes.

• A connection closed for good can still let out what it held. ready() and readyControlPlane() don't check whether the connection is closed (src/mcpl/server-connection.ts:346, :380), and a close that fails keeps its registry entry (src/mcpl/server-registry.ts:157-160). So the next gate's completion flushes what that connection held, with its policy already reset.

Changes

• Closes for good go through the registry. The three places call McplServerRegistry.closeServer(id, connection), which is no longer private and has a doc comment. It drops the entry once close() resolves, whatever the connection reports, if that connection is still the one registered under the id. A close that fails keeps the entry and rejects, and a close already under way is shared, as before.
• A failed accounting fails the gate. Once the close for good has settled, the catch calls failMcplDataPlaneGate, then rethrows. While the host serves, that recycles the running servers, as on the four other paths: each with reconnect: true reconnects, and its reconnect's own gate holds its data until that reconnect's accounting succeeds. While the host is stopping, it releases the gate.
• A failed policy registration closes the new connection and completes the gate. The connect closes its new connection for good through the registry, completes the gate, and rethrows.
• A connection closed for good readies nothing. McplServerConnection.ready() and readyControlPlane() now do nothing once the connection is closed with reconnect off, as after close(), whether or not its transport close succeeded, or after a drop with reconnect off. A connection between retries keeps reconnect on and readies as before.
• A close that fails is logged. Both catches close through closeFailedRuntimeConnect, which logs a close that fails instead of discarding it. Such a close keeps the entry, as closeServer does for every caller, so a later disconnect, restart or shutdown can close it again.
• Comments. Each catch says why it closes through the registry and how it settles the gate. McplServerConnection.close()'s comment now says only the registry's closeAll bounds its caller's wait.

What callers will notice

• After a runtime connectMcplServer or restartMcplServer fails its awareness accounting or its policy registration, connecting the same id again works, where it failed as already registered. If the close of the failed connection fails too, its entry stays and the failure is logged, so the id is free again once a disconnect, restart or shutdown has closed it.
• A failed accounting now recycles every running MCPL server while the host serves, with an mcpl:server-error trace for each that reads Discord awareness accounting unhealthy: …, as the four other runtime paths already do. A running server without reconnect: true is closed for good there. On main, those servers stayed connected with their data held. The connect or restart rejects once that recycle has closed the running servers' transports, as resume() and syncDiscordAwarenessMarkers() return only after theirs.
• A failed policy registration now closes the new server and leaves the running servers connected, their data no longer held behind the failed connect's gate. On main, the new server stayed connected and registered, and every server's data stayed held behind that gate.
• McplServerConnection.ready() and readyControlPlane() now do nothing once the connection is closed for good. What it held stays held. Before, any gate's completion passed the part of it that needs no grant to listeners, as for a connection whose close failed and so stayed registered. While the host stops, a connection closed for good, such as one being closed, no longer passes what it held to the stopping refusal, whose answers can't be sent on a closed connection. What every other connection held reaches it as before.
• A server that drops just before a refused policy's "close" fallback leaves the registry too.
• Nothing public changes shape: McplServerRegistry isn't exported from the package entry.

What each part is for

• Through closeServer, rather than having close() emit 'close' for a connection that's down. A connection that already reported its drop would report a second close, and every 'close' listener would run twice for one drop, the framework's mcpl:server-closed and module:removed traces among them. closeServer already drops the entry for removeServer and closeAll, and drops it only while that connection is still the registered one, which a restart could have replaced.
• All three closes for good, not only the awareness catch. The rule then holds wherever the framework closes a server for good. At the two fallbacks it covers a server that drops in between.
• Left out: removeServer(id) at those places. It closes whatever is registered under the id, which may no longer be this connection.
• failMcplDataPlaneGate when accounting fails, rather than completing the gate. Completing it would release the other servers' data while accounting is failing, which the catch exists to refuse, and it would make this the one runtime gate that fails open. Its cost is the one the four other paths already pay: a running server without reconnect: true is closed for good.
• Completing the gate when the policy registration throws, rather than failing it. Accounting succeeded, so the other servers' data is fine to release, and failing the gate would recycle them for nothing. The reconnect path completes its gate the same way when its re-registration throws.
• The close before the gate fails, so the refused connection is out of the registry and isn't recycled, unless its close fails.
• The rule at the connection, not at each completion. A connection closed for good has had its policy reset, so what it held that needs a grant would be refused, and it can send no response, so nothing it held could be answered. Readying it would only pass the rest to listeners of a server that won't be served again, from whichever completion readies it next: the failed connect's, a later gate's, or one after a close that failed in removeServer or closeAll. One check in ready() and readyControlPlane() covers them all.
• Only closed for good. A connection between retries still readies: what it held, such as a reconnect stub's connect-failed, reaches its listeners.
• One helper for both catches, so a failed connect's connection is closed, and a failed close logged, in one place.
• The tests.
  • The stub test protects what Greptile found. It also checks that a running server without reconnect: true ends closed, neither connected nor retrying.
  • The gate test protects the held data on the accounting exit, and the policy-registration test protects it on the other exit. Run again with a close that fails, that test checks that the connect still reports the registration's error, that the connection stays registered and paused through a later syncDiscordAwarenessMarkers(), and that the failed close is logged.
  • A stop-path test holds a control event and a data event on two connections and starts closing one. While that close is still under way, it checks that releasing and then failing the gate while the host stops lets out only the other one's.
  • The runtime-connect helper checks that the refused connection gets no "accounting unhealthy" trace, which pins the close before the gate's failure.
  • A registry test checks that closeServer leaves an entry that a newer connection holds under the same id, which is why the three places use it rather than removeServer(id).
  • The two fallback tests now hold their fake connection in a real registry, and the "close" fallback must leave it unregistered. The fakes' close() emits nothing, as a connection's does when it's down between retries.

Tests

At 5822b438, on Linux, Node 24.22.0. The pull request's CI runs the whole suite on Node 20 and 24.

• The four touched test files pass: shutdown-errors 29 tests, mcpl-manifest-changed 8, mcpl-config-diagnostics 12 and mcpl-awareness-barrier 34. At 8628705b, whose src/ differs from this head's only in comments, the 31 other test files whose names start with mcpl-, stop-with- or host-quiesce pass too.
• With main's src/framework.ts, src/mcpl/server-registry.ts and src/mcpl/server-connection.ts, with closeServer made public so the registry test compiles, 7 tests fail: both fallback tests, the four runtime-connect tests and the stop-path test. The registry test passes there, since main's closeServer already holds its guard.
• Each piece taken back out alone fails a test:
  • at 5822b438: the check in ready() (the failed-close test and the stop-path test); the check in readyControlPlane() (the stop-path test); and the check's reconnect condition, without which a connection between retries would count as closed for good (mcpl-reconnect-events' test of a reconnect stub);
  • at 76798228: the policy exit's gate completion, and a gate failure in its place (both policy-registration tests); and a failed close's error escaping closeFailedRuntimeConnect (the failed-close test, whose connect then rejects with the close's error);
  • at c87c6436: the failed connect's close going straight to the connection, as on main (the runtime-connect helper's trace check); the accounting exit's gate failure (the stub and gate tests); closeServer's guard (the registry test); the close and the gate's failure in swapped order (the helper's trace check); and the policy exit's close (the policy-registration test);
  • at afa80b53, this pull request's second commit: either "close" fallback's change (its fallback test).
• A probe of the gate, a framework serving one MCPL server without reconnect: true, then a runtime connect whose first connect fails and whose accounting then fails:
  • at 8202015e, this pull request's first commit, the failed connect's gate is still the current one after the rejection, and the running server is still connected with its data plane paused, the same 3 s later;
  • at 5822b438, that server is closed and unregistered by the time the connect rejects.

Not verified

• A server that drops between answering the policy request and the "close" fallback isn't staged. The fallback tests' fake connection, whose close() emits nothing, stands in for it.
• A close that fails is staged only at the policy exit, by making its transport close reject once. At the accounting exit it isn't staged. shutdown-errors.test.ts pins the registry keeping such an entry, through closeAll.
• No live MCPL server beyond the tests' own fixture.

Out of scope

• After a server is closed for good while it's down, no second mcpl:server-closed or module:removed trace follows the ones its drop emitted, as when disconnectMcplServer removes a server that's down, on main.
• A close that never settles still holds the failed connect's gate and its rejection, as on main, where this catch awaited the same close. main's StdioTransport.close() sends one SIGTERM and waits for the child's exit with no bound; feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262's, at its head c7eda6ce, escalates to SIGKILL and bounds the wait.

Related

• feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250, open, takes the awareness gate out of connectMcplServerInternal at its head 43c56c42, and with it the catch this change edits for a failed accounting. Its two "close" fallbacks still call connection.close() there.
• feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262, open, also changes connectMcplServerInternal, adding modern MCP servers. At its head c7eda6ce, the two exits this pull request changes are as on main.

Written by Effie-2756 (Claude Opus 5.5), on a design Ada-1017 (Claude Opus 5.5) approved. Naomi-2422 (Claude Opus 5.5) reviewed the change.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable regression was found.

Summary

Fixes cleanup after failed runtime MCPL connects and policy refusals.

• Runtime MCPL failures close the new server and settle its data gate.
• Closed MCPL servers leave the registry when their close succeeds.
• Closed MCPL connections no longer flush their buffered events.

Acknowledged by nissa-seru: accounting failures recycle other servers; failed closes retain their entries; permanently closed connections keep buffered events held; closing an already-down server emits no second close trace; unsettled closes remain out of scope.

Review used code and test inspection. Tests were not run.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): say what a connection closed ..." · Reviewed by Greptile}