ttsc 0.30.3 → 0.31.0

package/internal/lspserver/lsp_proxy.go

@@ -51,6 +51,7 @@ const (
   methodCompletionResolve      = "completionItem/resolve"
   methodInitialized            = "initialized"
   methodExit                   = "exit"
+  methodShutdown               = "shutdown"
   methodPluginSelectionChanged = "ttsc/pluginSelectionChanged"
 
   // methodDidChangeWatchedFiles is the only notification an editor sends for a
@@ -86,22 +87,49 @@ const utf8BOM = "\uFEFF"
 // ProxyOptions wires the byte-level proxy together. ttscserver creates
 // the upstream pipes around `tsgo --lsp --stdio` and hands the proxy
 // editor stdio plus those pipe ends.
+//
+// Run owns one source session and invokes Close once for an io.Closer source on
+// cancellation or completion. This does not certify that custom Close joins its
+// work. Transport owners must close blocked streams on cancellation.
+//
+// @evidence contracts/common.md#principled-implementation Separate editor and upstream streams model both directions; optional source/provider values and advertisement policy preserve contribution ownership.
+// @evidence contracts/common.md#clear-and-simple-design One options value injects dependencies without global transport or provider mutation.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Command prefixing is explicit host registry policy and supported provider injection replaces no foreign methods.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs document source lifetime, transport cancellation and optional capability policy with member spacing under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation io streams abstract native transport; OS-dependent stream closability remains the transport owner's explicit responsibility.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Options choose no processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Source and proxy operations own computation sharing.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This dependency value executes no acquisition or release; Run and transport/source owners perform cleanup under their own lifetime contracts.
 type ProxyOptions struct {
-  EditorIn    io.Reader
-  EditorOut   io.Writer
-  UpstreamIn  io.Writer // we write here; the tsgo LSP process reads
-  UpstreamOut io.Reader // the tsgo LSP process writes here; we read
-  Source      PluginSource
+  // EditorIn supplies client frames; its owner must unblock native reads when
+  // cancellation requires the editor pump to return.
+  EditorIn io.Reader
+
+  // EditorOut receives serialized client-bound frames.
+  EditorOut io.Writer
+
+  // UpstreamIn receives frames consumed by the upstream LSP process.
+  UpstreamIn io.Writer
+
+  // UpstreamOut supplies frames produced by the upstream LSP process.
+  UpstreamOut io.Reader
+
+  // Source provides plugin contributions; nil selects NullPluginSource.
+  Source PluginSource
+
   // SuppressExecuteCommandProvider keeps ttsc command ids out of the
   // initialize response for clients that register wrapper commands themselves.
   SuppressExecuteCommandProvider bool
+
   // SuppressedExecuteCommandIDs filters specific ttsc command ids out of the
   // initialize response while leaving other PluginSource command ids advertised.
   SuppressedExecuteCommandIDs []string
+
   // ExecuteCommandIDPrefix is prepended to advertised command ids. Hosts that
   // run multiple proxy instances in one global command registry use this to
   // avoid collisions; incoming prefixed ids are mapped back before dispatch.
   ExecuteCommandIDPrefix string
+
   // SymbolProvider answers textDocument/documentSymbol and
   // textDocument/references from ttsc's compiler-backed code graph. tsgo
   // implements both methods, so the proxy forwards to tsgo whenever it
@@ -109,6 +137,7 @@ type ProxyOptions struct {
   // (tsgo did not advertise) or when ForceLocalSymbolProvider is set. Nil leaves
   // both methods forwarded to tsgo unconditionally.
   SymbolProvider SymbolProvider
+
   // ForceLocalSymbolProvider answers documentSymbol/references from
   // SymbolProvider even when upstream tsgo advertises the capability. It serves
   // a raw-LSP graph consumer (such as @samchon/graph) that wants graph-derived
@@ -120,7 +149,23 @@ type ProxyOptions struct {
 // Proxy bridges the editor and an upstream tsgo LSP process, intercepting
 // the message types ttsc cares about (publishDiagnostics merge, code
 // action augmentation, executeCommand for ttsc-owned commands).
+//
+// One instance serves one session. Tracked editor requests have response and
+// cancellation cleanup; proxy-originated client callbacks have separate response
+// and send-failure cleanup. A peer that never responds may leave an entry for
+// the session. Document text is discarded on close, while generation histories
+// remain to prevent late work from regaining the closed generation's validity.
+//
+// @evidence contracts/common.md#principled-implementation Pending IDs preserve string/numeric distinctions; diagnostic generations revoke even a first unpublished computation, while formatting captures live text with its document generation and permits dirty text only until that generation changes.
+// @evidence contracts/common.md#clear-and-simple-design Locks separate frame serialization, request correlation, diagnostic state and watcher reconciliation; helpers own method-specific wire handling.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts UTF-16 negotiation aligns the compiler and plugin protocols at initialization rather than applying compensating position patches per response.
+// @evidence contracts/common.md#meaningful-documentation Native prose states session scope and historical-state retention; field paragraphs identify lock ownership under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native disk and URI boundaries use shared decoding/path APIs, while protocol positions and CRLF framing do not depend on native text conventions.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Run and method handlers choose processing algorithms; this type represents protected state.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Query and refresh owners establish sharing validity rather than the state declaration.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources This type groups retained state without executing acquisition or release; Run and handlers own cleanup attempts, and unacknowledged entries and generation histories can remain for the session.
 type Proxy struct {
+  sourceCloseOnce                sync.Once
   editorIn                       io.Reader
   editorOut                      io.Writer
   upstreamIn                     io.Writer
@@ -142,11 +187,18 @@ type Proxy struct {
   // editorRequestedExit.
   editorExit atomic.Bool
 
+  // editorShutdown records that the editor sent the LSP `shutdown` request,
+  // which decides the status an `exit` ends the session with; see
+  // editorRequestedShutdown.
+  editorShutdown atomic.Bool
+
   pendingMu      sync.Mutex
   pendingActions map[string]pendingCodeActionRequest
+
   // pendingCompletions holds the plugin items computed for a forwarded
   // completion request, keyed by request id, until upstream answers it.
-  pendingCompletions       map[string]pendingCompletionRequest
+  pendingCompletions map[string]pendingCompletionRequest
+
   pendingAugmentingActions map[string]struct{}
   pendingLocalActions      map[string]struct{}
   pendingCommands          map[string]struct{}
@@ -158,19 +210,30 @@ type Proxy struct {
   upstreamCodeActionProvider     bool
   upstreamDocumentSymbolProvider bool
   upstreamReferencesProvider     bool
+
   // initializeAnswered records that the editor has received the augmented
   // capabilities, which is what makes a later trigger character "late".
   initializeAnswered bool
+
   // advertisedCompletionTriggers is the trigger set the editor was told about:
   // tsgo's own characters plus whatever the corpus contributed at that moment.
   // A refresh that produces a trigger outside this set cannot reach the editor
   // without a restart, so the proxy says so once per character.
   advertisedCompletionTriggers map[string]struct{}
-  reportedCompletionTriggers   map[string]struct{}
-  projectInputWatchDynamic     bool
-  projectInputWatchRelative    bool
 
-  diagnosticsMu               sync.Mutex
+  reportedCompletionTriggers map[string]struct{}
+  projectInputWatchDynamic   bool
+  projectInputWatchRelative  bool
+
+  // diagnosticsMu guards the diagnostics and document state below, and is
+  // never held across a frame write. A writer that decides a frame from this
+  // state holds writeMu across the decision and the write, which keeps frames
+  // in the order their decisions were made, and releases diagnosticsMu before
+  // the write blocks on an editor that is not reading yet: the editor pump
+  // takes diagnosticsMu for every document notification before it forwards
+  // the notification upstream, and must never wait on a publication.
+  diagnosticsMu sync.Mutex
+
   upstreamDiagnostics         map[string]cachedDiagnostics
   pluginDiagnostics           map[string]cachedDiagnostics
   projectDiagnostics          cachedDiagnostics
@@ -180,6 +243,7 @@ type Proxy struct {
   documentGeneration          map[string]uint64
   dirtyDocuments              map[string]struct{}
   dirtyVersions               map[string]*int
+
   // documentText caches the live editor buffer per uri so the
   // textDocument/formatting handler can format the in-memory text instead
   // of the on-disk file. didOpen / full-sync didChange seed it with the full
@@ -229,8 +293,27 @@ type cachedDiagnostics struct {
   diagnostics []json.RawMessage
 }
 
-// NewProxy returns a Proxy ready to Run. The PluginSource is required;
-// pass NullPluginSource{} for a no-contribution setup.
+type completionHintObserverSource interface {
+  SetCompletionHintsObserver(func())
+}
+
+type projectInputObserverSource interface {
+  SetProjectInputsObserver(func())
+}
+
+// NewProxy returns a Proxy ready to Run. A nil source selects NullPluginSource.
+// The instance serves one session and takes its source's Close responsibility.
+// Optional observer setters are invoked during construction; an embedding that
+// never runs the proxy must arrange their removal and source closure itself.
+//
+// @evidence contracts/common.md#principled-implementation Initialized maps represent empty correlation and diagnostic state; optional observers connect later source publications to the same proxy session.
+// @evidence contracts/common.md#clear-and-simple-design Constructor dependency capture leaves transport startup to Run and native execution to the source.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Nil source is the explicit no-plugin state; optional interfaces preserve older source capabilities without replacing methods.
+// @evidence contracts/common.md#meaningful-documentation Native prose documents nil default, one-session use and source closure ownership, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Construction captures injected streams and protocol policy without opening native paths or processes.
+// @evidence contracts/performance.md#efficient-algorithms Suppressed command IDs are scanned and hashed once, including their string bytes, into a caller-independent set; empty maps and one buffered error channel add fixed setup. Optional observer setters are synchronous delegated calls whose custom-source cost is not bounded here.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Construction captures dependencies; serving operations coordinate source and refresh reuse.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Source-held observers can retain the proxy even after the embedding drops its reference. Run teardown removes those registrations and attempts source closure once, ignoring its error; previously copied callbacks and their spawned tasks are not joined by removal. Constructing without Run leaves removal and closure with the embedding. Suppressed string bytes and later session populations have no constructor-imposed budget.
 func NewProxy(opts ProxyOptions) *Proxy {
   source := opts.Source
   if source == nil {
@@ -266,15 +349,9 @@ func NewProxy(opts ProxyOptions) *Proxy {
   // Optional-interface assertion for the same reason pluginCompletionHints uses
   // one: a source that publishes no corpus, NullPluginSource included, simply
   // never reports one changing.
-  type completionHintObserverSource interface {
-    SetCompletionHintsObserver(func())
-  }
   if observed, ok := source.(completionHintObserverSource); ok {
     observed.SetCompletionHintsObserver(proxy.completionHintsRefreshed)
   }
-  type projectInputObserverSource interface {
-    SetProjectInputsObserver(func())
-  }
   if observed, ok := source.(projectInputObserverSource); ok {
     observed.SetProjectInputsObserver(func() {
       go proxy.projectInputsRefreshed()
@@ -283,29 +360,56 @@ func NewProxy(opts ProxyOptions) *Proxy {
   return proxy
 }
 
-// Run drives both pump goroutines until they return. Pumps return when
-// their input stream closes (ErrFrameClosed), when context cancellation
-// has already been observed by the upstream/editor closers, or when a
-// pipe write fails. ErrFrameClosed and context.Canceled are folded into
-// a nil result so editor shutdown does not look like a crash.
+// Run waits for the two pump results, except that upstream completion after
+// an editor exit notification can end the session while the editor pump is
+// still blocked. ErrFrameClosed, context.Canceled and os.ErrClosed are omitted
+// from the returned first error. Context cancellation requests source shutdown;
+// interrupting blocked injected streams remains their owner's responsibility.
+//
+// Once the editor has sent `exit` and the upstream has ended, Run returns
+// without waiting for the editor's stream to close: `exit` ends the session,
+// so the return does not require closing an injected editor stream to interrupt
+// its read. This exception is not a join of that remaining pump.
+//
+// @evidence contracts/common.md#principled-implementation Two pumps dispatch complete frames; generation guards reject stale contributions and initialized position negotiation fixes UTF-16 before live buffer conversions.
+// @evidence contracts/common.md#clear-and-simple-design Method helpers separate correlation, local contributions and passthrough; one source-close boundary coordinates cancellation and completion.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Local answers require actual command/capability ownership; malformed unsupported payloads pass through rather than being repaired into expected responses. Older optional sources use explicit interface capability checks.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain stream termination and the editor-exit exception, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native disk reads and physical input matching stay behind path helpers; negotiated UTF-16 and protocol URI spelling remain distinct from native bytes and path case capability.
+// @evidence contracts/performance.md#efficient-algorithms Each pump frames and parses an envelope before routing; handlers also decode method payloads and can marshal rewritten responses. The wait loop itself has constant per-result bookkeeping, while delegated text scans, producer calls, native input probes and registration reconciliation retain their input-dependent costs. Frame caps do not bound stream duration or all session populations.
+// @evidence contracts/performance.md#reuse-equivalent-work The session retains live text, producer corpora and diagnostic publications under their document/producer guards. Owner-scoped invalidation and refresh coalescing coordinate requests; they do not independently authenticate daemon Program equivalence or a common producer capture. Actual cache validity and native execution remain with their owners.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Session correlation, document text and diagnostic state grow with traffic without a general byte/history budget. Teardown stops pending timer/scheduler admission and requests source closure once; timer callbacks already begun, copied observers and local request tasks are not joined. Stopping the context AfterFunc does not wait for an already-started shutdown callback. Custom streams can block indefinitely; the editor-exit exception can return before its pump completes, and closure errors are ignored.
 func (p *Proxy) Run(ctx context.Context) error {
+  stopSourceCancellation := context.AfterFunc(ctx, p.shutdownResidentPlugins)
+  defer stopSourceCancellation()
   defer p.stopProjectDiagnosticRefresh()
-  errCh := make(chan error, 2)
-  go func() { errCh <- p.pumpEditorToUpstream(ctx) }()
-  go func() { errCh <- p.pumpUpstreamToEditor(ctx) }()
+  defer p.shutdownResidentPlugins()
+  editorDone := make(chan error, 1)
+  upstreamDone := make(chan error, 1)
+  go func() { editorDone <- p.pumpEditorToUpstream(ctx) }()
+  go func() { upstreamDone <- p.pumpUpstreamToEditor(ctx) }()
 
   var first error
-  for completed := 0; completed < 2; {
+  editorPending, upstreamPending := true, true
+  for editorPending || upstreamPending {
     var err error
     select {
-    case err = <-errCh:
-      completed++
+    case err = <-editorDone:
+      editorPending = false
+    case err = <-upstreamDone:
+      upstreamPending = false
     case err = <-p.asyncErrCh:
     }
-    if first == nil && err != nil && !errors.Is(err, ErrFrameClosed) && !errors.Is(err, context.Canceled) {
+    // RunLSPServer closes the editor input itself when the session ends, and a
+    // read that closing ends reports os.ErrClosed: ttsc's own teardown, not a
+    // fault of the session.
+    if first == nil && err != nil && !errors.Is(err, ErrFrameClosed) && !errors.Is(err, context.Canceled) && !errors.Is(err, os.ErrClosed) {
       first = err
       p.closeAfterPumpError()
     }
+    if !upstreamPending && p.editorRequestedExit() {
+      break
+    }
   }
   return first
 }
@@ -356,6 +460,12 @@ func (p *Proxy) pumpEditorToUpstream(_ context.Context) error {
     if env.IsNotification() && env.Method == methodInitialized {
       go p.projectInputWatchInitialized()
     }
+    // Nothing follows `exit` upstream. Ending its input lets a runner that
+    // waits for its stdin to drain before returning, as exec.Cmd.Wait does,
+    // finish once tsgo has quit, instead of waiting on this pump.
+    if env.IsNotification() && env.Method == methodExit {
+      p.closeUpstreamInput()
+    }
   }
 }
 
@@ -457,6 +567,10 @@ func (p *Proxy) handleEditorEnvelope(env Envelope, body []byte) (bool, error) {
     return p.handleCompletionRequest(env)
   case methodCompletionResolve:
     return p.handleCompletionResolveRequest(env)
+  case methodShutdown:
+    if env.IsRequest() {
+      p.editorShutdown.Store(true)
+    }
   case methodExit:
     if env.IsNotification() {
       p.editorExit.Store(true)
@@ -533,9 +647,9 @@ func constrainInitializePositionEncoding(env Envelope, body []byte) []byte {
   if err != nil {
     return body
   }
-  // Re-encode only the subtree that changed: every sibling value stays the
-  // client's original bytes, so a large or unusually shaped initialize payload
-  // reaches tsgo exactly as it was sent.
+  // Preserve sibling JSON values in the rebuilt parameter subtrees. Marshaling
+  // can change their byte spelling/whitespace and serializes the parsed Envelope;
+  // only the earlier pass-through branches preserve the complete original bytes.
   general["positionEncodings"] = constrained
   encodedGeneral, err := json.Marshal(general)
   if err != nil {
@@ -586,6 +700,13 @@ func (p *Proxy) editorRequestedExit() bool {
   return p.editorExit.Load()
 }
 
+// editorRequestedShutdown reports whether the editor sent the LSP `shutdown`
+// request. The specification ends the session after `exit` with status 0
+// when `shutdown` came first and 1 when it did not.
+func (p *Proxy) editorRequestedShutdown() bool {
+  return p.editorShutdown.Load()
+}
+
 func (p *Proxy) rememberInitializeRequest(env Envelope) {
   key := env.IDKey()
   if key == "" {
@@ -614,7 +735,7 @@ func (p *Proxy) rememberInitializeRequest(env Envelope) {
   p.pendingInitialize[key] = struct{}{}
 }
 
-// forgetCancelledRequest removes any pending codeAction entry whose id
+// forgetCancelledRequest removes pending local or forwarded requests whose id
 // the editor cancelled. The notification still flows to upstream so
 // tsgo can respond with its own cancellation error. The id is keyed
 // through the shared normalizer so a cancel for `1.0` deletes an entry
@@ -857,11 +978,11 @@ func (p *Proxy) completeExecuteCommand(env Envelope, key string, command string,
     p.reportAsyncError(p.writeExecuteCommandErrorIfClean(env.ID, pending, fmt.Sprintf("ttsc command %q failed: %v", command, err)))
     return
   }
-  // Cycle 1 returns the WorkspaceEdit inside the executeCommand response
-  // instead of sending workspace/applyEdit as a server→client request.
-  // ttsc owns both ends (its VS Code extension), so the extension applies
-  // the edit on its side. Sticking to one direction avoids tracking our
-  // own outgoing request ids in the proxy.
+  // The WorkspaceEdit is returned inside the executeCommand response instead
+  // of being sent as a workspace/applyEdit server→client request. ttsc owns
+  // both ends (its VS Code extension), so the extension applies the edit on
+  // its side. Sticking to one direction avoids tracking the proxy's own
+  // outgoing request ids for this path.
   p.reportAsyncError(p.writeExecuteCommandResultIfClean(env.ID, pending, edit))
 }
 
@@ -877,9 +998,9 @@ type contentExecutor interface {
 // document formatter. Unlike the workspace/executeCommand path, this handler
 // intentionally formats the live (possibly dirty) editor buffer: it reads the
 // cached buffer text and passes it to the sidecar so formatOnSave works before
-// the file is written to disk. It therefore does NOT go through the
-// dirty-document guard that writeExecuteCommandResultIfClean applies to the
-// executeCommand path.
+// the file is written to disk. Dirty state itself does not reject formatting,
+// but a subsequent edit or close revokes the captured document generation.
+// Local request cancellation shares the executeCommand pending registry.
 //
 // When ttsc does not own ttsc.format.document the request is forwarded to
 // upstream tsgo (return false). The handler never surfaces an error to the
@@ -898,17 +1019,26 @@ func (p *Proxy) handleFormattingRequest(env Envelope) (bool, error) {
     return false, nil
   }
   uri := params.TextDocument.URI
-  go p.completeFormattingRequest(env, uri)
+  p.diagnosticsMu.Lock()
+  content, hasContent := p.documentText[uri]
+  generation := p.documentGeneration[uri]
+  p.diagnosticsMu.Unlock()
+  key := env.IDKey()
+  if key != "" {
+    p.pendingMu.Lock()
+    p.pendingCommands[key] = struct{}{}
+    p.pendingMu.Unlock()
+  }
+  go p.completeFormattingRequest(env, uri, key, generation, content, hasContent)
   return true, nil
 }
 
-func (p *Proxy) completeFormattingRequest(env Envelope, uri string) {
+func (p *Proxy) completeFormattingRequest(env Envelope, uri string, key string, generation uint64, content string, hasContent bool) {
   // hasContent distinguishes "the proxy has a buffer to format in-memory" from
   // "no buffer; let the sidecar read disk". An empty cached buffer is a valid
   // document state (the user cleared the file), so the empty string must NOT be
   // overloaded as the no-buffer sentinel: a cache hit always yields
   // hasContent=true even when the buffer is "".
-  content, hasContent := p.cachedDocumentText(uri)
   if !hasContent {
     if file, fileOK := filePathFromURI(uri); fileOK {
       if disk, err := os.ReadFile(file); err == nil {
@@ -924,12 +1054,23 @@ func (p *Proxy) completeFormattingRequest(env Envelope, uri string) {
   // logs the underlying sidecar failure to its own stderr writer, so the proxy
   // does not need a separate log sink here.
   edit, err := p.executeFormatCommand(uri, content, hasContent)
-  if err != nil {
-    p.reportAsyncError(p.writeResult(env.ID, []LSPTextEdit{}))
+  if key != "" && !p.takePendingCommand(key) {
     return
   }
-  edits := formattingTextEdits(edit, uri)
-  p.reportAsyncError(p.writeResult(env.ID, edits))
+  edits := []LSPTextEdit{}
+  if err == nil {
+    edits = formattingTextEdits(edit, uri)
+  }
+  // As with local code actions and executeCommand, serialize the generation
+  // decision with the frame write, without holding document state across I/O.
+  p.writeMu.Lock()
+  defer p.writeMu.Unlock()
+  p.diagnosticsMu.Lock()
+  if p.documentGeneration[uri] != generation {
+    edits = []LSPTextEdit{}
+  }
+  p.diagnosticsMu.Unlock()
+  p.reportAsyncError(p.writeResultLocked(env.ID, edits))
 }
 
 // executeFormatCommand runs ttsc.format.document against the supplied buffer
@@ -1358,9 +1499,9 @@ func (p *Proxy) writePublishDiagnosticsIfCurrent(uri string, version *int, diagn
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
   _, dirty := p.dirtyDocuments[uri]
   current := p.diagnosticGeneration[uri] == generation && !dirty
+  p.diagnosticsMu.Unlock()
   if !current {
     return nil
   }
@@ -1383,24 +1524,20 @@ func (p *Proxy) writeProjectDiagnosticsIfCurrent(
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
   if p.projectDiagnosticGeneration != generation ||
     len(p.dirtyDocuments) != 0 {
+    p.diagnosticsMu.Unlock()
     return projectDiagnosticsWriteResult{}, nil
   }
 
+  var frames [][]byte
   previousURI := p.projectDiagnosticsURI
   previousHadDiagnostics := len(p.projectDiagnostics.diagnostics) > 0
   changedURI := previousURI != "" && previousURI != publication.URI
   if changedURI {
     p.projectDiagnosticsURI = ""
     p.projectDiagnostics = cachedDiagnostics{}
-    if err := WriteFrame(
-      p.editorOut,
-      p.publishDiagnosticsBody(previousURI, nil, p.mergedDiagnosticsLocked(previousURI)),
-    ); err != nil {
-      return projectDiagnosticsWriteResult{}, err
-    }
+    frames = append(frames, p.publishDiagnosticsBody(previousURI, nil, p.mergedDiagnosticsLocked(previousURI)))
   }
 
   p.projectDiagnosticsURI = publication.URI
@@ -1409,13 +1546,15 @@ func (p *Proxy) writeProjectDiagnosticsIfCurrent(
     !publishEmpty &&
     !previousHadDiagnostics &&
     !changedURI {
+    p.diagnosticsMu.Unlock()
     return projectDiagnosticsWriteResult{accepted: true}, nil
   }
-  if err := WriteFrame(
-    p.editorOut,
-    p.publishDiagnosticsBody(publication.URI, nil, p.mergedDiagnosticsLocked(publication.URI)),
-  ); err != nil {
-    return projectDiagnosticsWriteResult{}, err
+  frames = append(frames, p.publishDiagnosticsBody(publication.URI, nil, p.mergedDiagnosticsLocked(publication.URI)))
+  p.diagnosticsMu.Unlock()
+  for _, frame := range frames {
+    if err := WriteFrame(p.editorOut, frame); err != nil {
+      return projectDiagnosticsWriteResult{}, err
+    }
   }
   return projectDiagnosticsWriteResult{
     accepted:     true,
@@ -1455,11 +1594,11 @@ func (p *Proxy) writeLocalCodeActionsResultIfCurrent(id json.RawMessage, actions
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
   if _, dirty := p.dirtyDocuments[pending.uri]; dirty || p.documentGeneration[pending.uri] != pending.generation {
     actions = []LSPCodeAction{}
   }
   actions = p.rewriteCodeActionCommands(actions)
+  p.diagnosticsMu.Unlock()
   return p.writeResultLocked(id, actions)
 }
 
@@ -1467,11 +1606,12 @@ func (p *Proxy) writeAugmentedCodeActionFrameIfCurrent(pending pendingCodeAction
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
+  frame := augmented
   if _, dirty := p.dirtyDocuments[pending.uri]; dirty || p.documentGeneration[pending.uri] != pending.generation {
-    return WriteFrame(p.editorOut, fallback)
+    frame = fallback
   }
-  return WriteFrame(p.editorOut, augmented)
+  p.diagnosticsMu.Unlock()
+  return WriteFrame(p.editorOut, frame)
 }
 
 func (p *Proxy) publishDiagnosticsBody(uri string, version *int, diagnostics []json.RawMessage) []byte {
@@ -1803,7 +1943,8 @@ func filePathFromURI(raw string) (string, bool) {
     return "", false
   }
   path := parsed.Path
-  if parsed.Host != "" {
+  // RFC 8089 gives localhost the same local meaning as an absent authority.
+  if parsed.Host != "" && !strings.EqualFold(parsed.Host, "localhost") {
     path = "//" + parsed.Host + path
   }
   if path == "" {
@@ -2531,19 +2672,22 @@ func (p *Proxy) invalidateForWatchedFileChanges(env Envelope) error {
 // Upstream diagnostics are left in place: the compiler owns its own answer for
 // the same document, and the editor may legitimately keep showing it while the
 // buffer is still open. Bumping the diagnostic generation discards any in-flight
-// computation started against the pre-deletion Program. A document ttsc never
-// published for is a no-op, which is the ordinary case.
+// computation started against the pre-deletion Program, including its first
+// unpublished computation. A clear frame is needed only for existing findings.
 func (p *Proxy) withdrawPluginDiagnosticsForDeletedDocument(uri string) error {
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
-  if len(p.pluginDiagnostics[uri].diagnostics) == 0 {
-    return nil
-  }
+  hadDiagnostics := len(p.pluginDiagnostics[uri].diagnostics) > 0
   delete(p.pluginDiagnostics, uri)
   p.diagnosticGeneration[uri]++
-  return WriteFrame(p.editorOut, p.publishDiagnosticsBody(uri, nil, p.mergedDiagnosticsLocked(uri)))
+  if !hadDiagnostics {
+    p.diagnosticsMu.Unlock()
+    return nil
+  }
+  body := p.publishDiagnosticsBody(uri, nil, p.mergedDiagnosticsLocked(uri))
+  p.diagnosticsMu.Unlock()
+  return WriteFrame(p.editorOut, body)
 }
 
 // watchedFileChangeIsLocalizable reports whether one watched-file entry can be
@@ -2849,6 +2993,7 @@ func (p *Proxy) stopProjectDiagnosticRefresh() {
   p.projectDiagnosticRefreshPending = false
   p.pendingProjectDiagnosticAllOwners = false
   p.pendingProjectDiagnosticOwners = nil
+  p.projectDiagnosticsRefresh.close()
 }
 
 func (p *Proxy) resumePendingProjectDiagnosticRefresh() {
@@ -2962,10 +3107,24 @@ func isProjectConfigURI(uri string) bool {
 // The children also exit on their own when the parent closes their stdin at
 // process exit, so this is the graceful path, not the only one.
 func (p *Proxy) shutdownResidentPlugins() {
-  type residentShutdown interface{ shutdownResidents() }
-  if source, ok := p.source.(residentShutdown); ok {
-    source.shutdownResidents()
-  }
+  p.sourceCloseOnce.Do(func() {
+    // Release source-held references to this completed proxy. A callback
+    // already copied by an in-flight refresh may still finish independently.
+    if observed, ok := p.source.(completionHintObserverSource); ok {
+      observed.SetCompletionHintsObserver(nil)
+    }
+    if observed, ok := p.source.(projectInputObserverSource); ok {
+      observed.SetProjectInputsObserver(nil)
+    }
+    if source, ok := p.source.(io.Closer); ok {
+      _ = source.Close()
+      return
+    }
+    type residentShutdown interface{ shutdownResidents() }
+    if source, ok := p.source.(residentShutdown); ok {
+      source.shutdownResidents()
+    }
+  })
 }
 
 // capabilityAdvertised reports whether an LSP server-capability value means the
@@ -3129,11 +3288,11 @@ func (p *Proxy) writeExecuteCommandResultIfClean(id json.RawMessage, pending pen
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
   dirty := p.documentGenerationsChangedLocked(pending.argumentGenerations) ||
     p.argumentsContainDirtyDocumentLocked(pending.args) ||
     p.workspaceEditTargetsChangedLocked(edit, pending.documentGenerations) ||
     p.workspaceEditTargetsDirtyDocumentLocked(edit)
+  p.diagnosticsMu.Unlock()
   if dirty || edit == nil {
     return p.writeResultLocked(id, nil)
   }
@@ -3144,12 +3303,12 @@ func (p *Proxy) writeExecuteCommandErrorIfClean(id json.RawMessage, pending pend
   p.writeMu.Lock()
   defer p.writeMu.Unlock()
   p.diagnosticsMu.Lock()
-  defer p.diagnosticsMu.Unlock()
   stale := p.documentGenerationsChangedLocked(pending.argumentGenerations) ||
     p.argumentsContainDirtyDocumentLocked(pending.args)
   if len(pending.argumentGenerations) == 0 {
     stale = p.documentGenerationsChangedLocked(pending.documentGenerations)
   }
+  p.diagnosticsMu.Unlock()
   if stale {
     return p.writeResultLocked(id, nil)
   }

package/internal/lspserver/lsp_refresh.go

@@ -22,6 +22,7 @@ type coalescingRefresh struct {
   generation uint64
   running    bool
   queued     bool
+  closed     bool
 }
 
 // schedule requests a run of task. It returns immediately: the run happens on
@@ -32,6 +33,10 @@ func (r *coalescingRefresh) schedule(task func(generation uint64)) {
     return
   }
   r.mu.Lock()
+  if r.closed {
+    r.mu.Unlock()
+    return
+  }
   r.task = task
   if r.running {
     r.queued = true
@@ -57,7 +62,7 @@ func (r *coalescingRefresh) run(generation uint64) {
       task(generation)
     }
     r.mu.Lock()
-    if !r.queued {
+    if r.closed || !r.queued {
       r.running = false
       r.mu.Unlock()
       return
@@ -68,3 +73,13 @@ func (r *coalescingRefresh) run(generation uint64) {
     r.mu.Unlock()
   }
 }
+
+// close prevents new runs and drops queued work. The owner must separately
+// cancel any computation already in flight before releasing its resources.
+func (r *coalescingRefresh) close() {
+  r.mu.Lock()
+  defer r.mu.Unlock()
+  r.closed = true
+  r.queued = false
+  r.task = nil
+}