Document lifecycle notifications parked across a crash-restart are delivered to the new server after the didOpen replay #1859

vscode-languageclient (observed in 10.1.1) can deliver stale textDocument/didChange, textDocument/didClose, and textDocument/didOpen notifications to a freshly restarted server, out of order with the document-open replay the client performs on (re)connect. A server that validates document versions or open/closed state strictly will see an apparent protocol violation and, if it treats that as fatal, enter a crash loop.

Mechanism

1. The server process crashes. The default CloseAction.Restart path runs handleConnectionClosed → cleanUp(ShutdownMode.Restart), which clears _syncedDocuments, and then start() on the same client instance (client.ts, handleConnectionClosed / cleanUp).
2. During the (multi-second) restart window, editor events keep firing. DidChangeTextDocumentFeature.callback captures document.version at event time and calls client.sendNotification(...). Because the client state is not Stopped/Stopping, sendNotification is not rejected — it parks at await this.$start() and is later delivered over the next connection (client.ts, sendNotification: const connection = await this.$start();). The same applies to didClose/didOpen/didSave fired in that window.
3. On the new connection, doInitialize sets the state to Running and initializeFeatures runs DidOpenTextDocumentFeature.register, which replays didOpen for every currently-open matching document with its current (post-window) version (textSynchronization.ts).
4. The parked stragglers from step 2 then flush against the new server:
   • a didChange captured at version N arrives after the replayed didOpen at version M ≥ N → the document version goes backwards;
   • a parked didClose for a document that was closed during the window → a close for a document the new server never saw opened (the replay only covers documents still open at replay time);
   • a parked didOpen → a second open for a document the replay already opened.

Impact

The LSP spec says didChange versions increase after each change, so a server is entitled to treat a version going backwards (or a close/open for a document in the wrong state) as a protocol violation. In the Julia language server we assert on exactly that to catch real desyncs — and with this race, each straggler kills the freshly restarted server, so a single primary crash cascades into repeated crashes until the client's crash-loop breaker ("crashed 5 times in the last 3 minutes") gives up.

We observed this in the wild through the Julia VS Code extension's crash telemetry: right after a crash-restart, the new server received a replayed didOpen with version 3 followed by a parked didChange with version 2 ("LS version is 3, request version is 2"), and separately a didClose for a document that was never opened on the new connection. The reproduction rate tracks how often the server has a primary crash, which is what makes the window observable.

Reproduction sketch

1. Server for some document type, restart-on-crash via the default error handler.
2. Open a document, type (version reaches N).
3. Kill the server process.
4. While the client is restarting (state not Running), keep typing (versions N+1, N+2 are captured and parked) and/or close the document.
5. When the restart completes, the server receives didOpen at the current version followed by the parked notifications from step 4 captured at their older versions / for the now-closed document.

Proposed direction

Tag document-lifecycle notifications with the connection generation at the time they are created, and discard them at flush time (after await this.$start() resolves) if the connection has been swapped since. This is safe by construction: the restart replay re-establishes authoritative state for every open document — the replayed didOpen carries the document's complete current text — so a straggler from a previous connection is provably stale.

Related (all fixed) precedent for this class of ordering bug, none of which covers the crash-restart parking path: #1133 / #1176 (didChange/didOpen out of order with full sync during search-and-replace), #1228 (async param conversion breaking notification/request order), #1695 (delayOpenNotifications sending the wrong didOpen version).

We currently work around this in the Julia extension with middleware that defers lifecycle notifications fired while the client is not Running and drops the ones the replay has superseded (julia-vscode/julia-vscode#4205), but the durable fix belongs in the library.