ttsc 0.30.4 → 0.31.0

package/internal/lspserver/lsp_native_plugin_source.go

@@ -11,6 +11,9 @@ import (
   "strings"
   "sync"
   "sync/atomic"
+  "time"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/e2etrace"
 )
 
 const nativePluginCommandStdoutLimit = 4 * 1024 * 1024
@@ -19,44 +22,141 @@ const nativePluginCommandStderrLimit = 1024 * 1024
 // NativePluginManifest is the JSON shape the JavaScript ttscserver launcher
 // writes to its private manifest file after running normal project plugin
 // discovery and source-plugin builds.
+//
+// @evidence contracts/common.md#principled-implementation Descriptor entries, executable entries and initial declarations remain distinct. Raw project context carries the declared launcher identity without authenticating it; the source separately normalizes accepted startup inputs.
+// @evidence contracts/common.md#clear-and-simple-design One manifest separates supplied startup fields from later host refresh state. Its maps, slices and raw JSON are mutable values, not an immutable capture.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Shared snapshot keys select supplied manifest entries rather than embedded expected selections; required-key lookup and host normalization own admission, not this wire shape.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the launcher producer and selection-change effect, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Binary locations and project context carry native paths separately from diagnostic URIs; the source performs native interpretation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The manifest carries startup values; construction selects discovery and validation algorithms.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The value does not coordinate producer reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Resource acquisition belongs to the constructed source rather than this transport value.
 type NativePluginManifest struct {
+  // InitialProjectInputs holds shared startup declarations selected by entry key.
   InitialProjectInputs map[string]LSPProjectInputSnapshot `json:"initialProjectInputs,omitempty"`
-  Plugins              []NativePluginConfigEntry          `json:"plugins"`
-  LSPPlugins           []NativeLSPPluginEntry             `json:"lspPlugins"`
-  ProjectContext       json.RawMessage                    `json:"projectContext,omitempty"`
+
+  // Plugins contains the compact descriptor configuration passed to sidecars.
+  Plugins []NativePluginConfigEntry `json:"plugins"`
+
+  // LSPPlugins contains executable entries whose declared flags admit queries.
+  LSPPlugins []NativeLSPPluginEntry `json:"lspPlugins"`
+
+  // ProjectContext carries opaque launcher JSON; the source reads supplied
+  // physical project/config locations and separately gates forwarding it.
+  ProjectContext json.RawMessage `json:"projectContext,omitempty"`
+
+  // SelectionInputs are what the plugin selection itself was loaded from. A
+  // reported change is compared by the host's restart-selection policy. The
+  // value itself does not register a watcher or certify that a change arrived.
+  SelectionInputs *NativePluginSelectionInputs `json:"selectionInputs,omitempty"`
 }
 
 // NativePluginConfigEntry mirrors the compact sidecar protocol used by
 // --plugins-json. It intentionally excludes host-only fields such as binary.
+//
+// @evidence contracts/common.md#principled-implementation Name, stage and JSON configuration preserve the compact descriptor protocol independently of executable metadata.
+// @evidence contracts/common.md#clear-and-simple-design Sidecar configuration excludes host-only binary fields.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Configuration comes from project discovery rather than known rule fixtures.
+// @evidence contracts/common.md#meaningful-documentation Native prose explains why binary metadata is absent, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation These JSON descriptor values define no filesystem or process boundary.
+// @evidenceExclude contracts/performance.md#efficient-algorithms The value chooses no processing strategy.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work It does not coordinate configuration reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It carries data without a native resource lifecycle.
 type NativePluginConfigEntry struct {
+  // Config is decoded JSON configuration, separate from executable metadata.
+  // Numeric values follow encoding/json's ordinary interface-value decoding.
   Config map[string]any `json:"config"`
-  Name   string         `json:"name"`
-  Stage  string         `json:"stage"`
+
+  // Name identifies the descriptor passed through the compact plugin protocol.
+  Name string `json:"name"`
+
+  // Stage selects the descriptor's configured plugin lane.
+  Stage string `json:"stage"`
 }
 
 // NativeLSPPluginEntry names one built sidecar that opted into the LSP
 // protocol through its JavaScript descriptor capabilities.
+//
+// @evidence contracts/common.md#principled-implementation Executable path, initial snapshots and declared capability flags distinguish query admission without assuming every descriptor advertises every verb. The path/flags are supplied metadata, not artifact identity or runtime capability authentication.
+// @evidence contracts/common.md#clear-and-simple-design Executable capabilities remain separate from generic plugin configuration.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Capability flags come from the descriptor contract rather than probing known package names.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies the opt-in boundary, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Binary is a native executable path passed as exec's executable argument, not a shell command; project context is separately capability-gated.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Source operations own transport selection and processing.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The entry describes identity inputs without coordinating execution reuse.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The source owns processes started from this descriptor.
 type NativeLSPPluginEntry struct {
-  Binary                 string                   `json:"binary"`
-  InitialProjectInputKey string                   `json:"initialProjectInputKey,omitempty"`
-  InitialProjectInputs   *LSPProjectInputSnapshot `json:"initialProjectInputs,omitempty"`
-  Name                   string                   `json:"name,omitempty"`
-  ProjectDiagnostics     bool                     `json:"projectDiagnostics,omitempty"`
-  ProjectInputs          bool                     `json:"projectInputs,omitempty"`
-  ProjectContextArgs     bool                     `json:"projectContextArgs,omitempty"`
-  Stage                  string                   `json:"stage,omitempty"`
+  // Binary selects exec's native executable; it is not an artifact fingerprint.
+  Binary string `json:"binary"`
+
+  // InitialProjectInputKey refers to the manifest's shared startup snapshot.
+  // A nonempty key takes precedence over InitialProjectInputs.
+  InitialProjectInputKey string `json:"initialProjectInputKey,omitempty"`
+
+  // InitialProjectInputs optionally supplies an inline startup declaration.
+  InitialProjectInputs *LSPProjectInputSnapshot `json:"initialProjectInputs,omitempty"`
+
+  // Name is optional descriptor labeling used in source diagnostics.
+  Name string `json:"name,omitempty"`
+
+  // ProjectDiagnostics admits dedicated project-diagnostic queries.
+  ProjectDiagnostics bool `json:"projectDiagnostics,omitempty"`
+
+  // ProjectInputs admits input declaration discovery and startup snapshots.
+  ProjectInputs bool `json:"projectInputs,omitempty"`
+
+  // ProjectContextArgs permits the separate project-context JSON argument when
+  // one is available; it also distinguishes the selected transport key.
+  ProjectContextArgs bool `json:"projectContextArgs,omitempty"`
+
+  // Stage carries descriptor stage metadata independently of these query flags.
+  Stage string `json:"stage,omitempty"`
 }
 
 // NativePluginSourceOptions configures a sidecar-backed PluginSource.
+//
+// ManifestJSON is the launcher manifest, Cwd and Tsconfig name the client's
+// selected project, and Err receives discovery and transport logs without
+// transferring ownership of the writer's closure.
+//
+// @evidence contracts/common.md#principled-implementation Client identity and manifest data permit the source to distinguish logical publication from physical sidecar execution context.
+// @evidence contracts/common.md#clear-and-simple-design The value groups explicit construction inputs; command execution still obtains the process environment from its owning transport.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A caller-supplied log sink avoids global stderr mutation.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies project inputs and log closure ownership, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Cwd and Tsconfig are native project locations; manifest parsing handles separate physical context rather than inferring identity from OS names.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Options select no processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Construction owns producer coordination.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The constructed source acquires resources; these options do not.
 type NativePluginSourceOptions struct {
-  Cwd          string
-  Err          io.Writer
+  // Cwd is the client's selected working directory before manifest context
+  // supplies a separate physical execution root.
+  Cwd string
+
+  // Err is an optional log destination; the source does not close it.
+  Err io.Writer
+
+  // ManifestJSON is supplied startup metadata decoded by the constructor.
   ManifestJSON string
-  Tsconfig     string
+
+  // Tsconfig preserves the client's selected config spelling independently of
+  // any physical config path supplied by the manifest context.
+  Tsconfig string
 }
 
 // NativePluginSource implements PluginSource by delegating to native sidecars
 // that explicitly support ttsc's LSP subcommands.
+//
+// Close requests child termination and rejects later process starts. Refresh
+// failures preserve last-good producer publications until a successful update.
+//
+// @evidence contracts/common.md#principled-implementation Per-producer records distinguish last-good state from current generations; transport identity includes the executable and negotiated project-context arguments.
+// @evidence contracts/common.md#clear-and-simple-design Independent locks protect corpus, input, diagnostic and resident state; shared transport helpers own command execution.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Older serve support has an explicit direct-command fallback; owner selection uses descriptor capabilities rather than package-specific patches.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain lifecycle, retained publications and lock responsibilities with separated members under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation exec receives executable and argument vectors; Windows helpers query owning-directory flags separately from file URIs. An unknown flag preserves identity distinctions and broadens glob invalidation matching instead of authorizing a false merge or losing an event.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Source operations choose algorithms; this type groups their protected state.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The type represents cache identity and generations; operation acknowledgments justify sharing and invalidation.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Close and refresh/serve operations control acquisitions and release; the representation itself does not execute them.
 type NativePluginSource struct {
   cwd                string
   err                io.Writer
@@ -67,12 +167,13 @@ type NativePluginSource struct {
   clientTsconfig     string
   clientCwd          string
 
-  // The client's project resolves once. Both halves are fixed for the
-  // session, while the answer costs a symlink walk per ancestor, and the
-  // question is asked again for every producer on every publication.
+  // The client's physical project path and key resolve once for this source.
+  // Later publication URI comparisons resolve each candidate against that
+  // cached key; they do not revalidate the client's physical target.
   clientProjectOnce sync.Once
-  clientProject     string
-  clientProjectKey  string
+
+  clientProject    string
+  clientProjectKey string
 
   commandIDs      []string
   codeActionKinds []string
@@ -82,27 +183,38 @@ type NativePluginSource struct {
   // discovery may still be writing it. It is the flattened publication-order
   // view of pluginHints, materialized on every store so the completion path
   // copies a ready slice instead of rebuilding one per keystroke.
-  hintsMu         sync.RWMutex
+  hintsMu sync.RWMutex
+
   completionHints []LSPCompletionHint
+
   // pluginHints keeps each producer's corpus separately, keyed by plugin
   // identity, so one plugin's refresh cannot disturb another's. A producer's
   // entry changes only when that producer answers successfully: a refresh that
   // failed to run leaves the last known-good corpus in place rather than
   // blanking a working corpus over a transient spawn failure.
   pluginHints map[string]completionHintRecord
+
   // hintsObserver is told after every completed refresh cycle so the proxy can
   // react to a corpus that changed mid-session. Nil for any host that did not
   // register one.
   hintsObserver func()
-  // hintsRefresh serializes and coalesces corpus refreshes. A refresh loads a
-  // Program per plugin, so scheduling one per editor event without coalescing
-  // would stack process spawns behind each other.
+
+  // hintsRefresh serializes and coalesces corpus refreshes. Producers may use
+  // resident transports or direct commands; this state does not certify how
+  // many Programs they construct or when an editor event reaches them.
   hintsRefresh coalescingRefresh
-  owners       map[string]NativeLSPPluginEntry
-  logMu        sync.Mutex
 
-  projectInputsMu       sync.RWMutex
-  projectInputs         LSPProjectInputSnapshot
+  owners map[string]NativeLSPPluginEntry
+  logMu  sync.Mutex
+
+  projectInputsMu sync.RWMutex
+  projectInputs   LSPProjectInputSnapshot
+
+  // selection is fixed for the session: its directories are watched in every
+  // flattened snapshot, whatever the plugins later rediscover, and checked
+  // beside its reload inputs.
+  selection pluginSelectionInputs
+
   pluginProjectInputs   map[string]projectInputRecord
   projectInputsObserver func()
   projectInputsRefresh  coalescingRefresh
@@ -111,13 +223,18 @@ type NativePluginSource struct {
   pluginProjectDiagnostics   map[string]projectDiagnosticRecord
   projectDiagnosticsSequence atomic.Uint64
 
-  // residentMu guards the resident-daemon table below. A resident sidecar keeps
-  // a warm Program across verbs, so lsp-diagnostics / lsp-code-actions reuse it
-  // instead of respawning per verb; serveUnsupported remembers a sidecar that
-  // predates lsp-serve so the source stops retrying it and stays on exec.
-  residentMu       sync.Mutex
+  // residentMu guards the resident-daemon table below. Supported serve calls
+  // reuse a transport across verbs; the sidecar owns its Program lifecycle.
+  // serveUnsupported records failed initial serve admission so later calls
+  // use direct commands rather than retrying that transport.
+  residentMu sync.Mutex
+
   residents        map[string]*residentSidecar
   serveUnsupported map[string]bool
+
+  processContext  context.Context
+  cancelProcesses context.CancelFunc
+  closed          bool
 }
 
 type limitedBuffer struct {
@@ -126,6 +243,39 @@ type limitedBuffer struct {
   truncated bool
 }
 
+// commandContext resolves the source lifetime even for a zero-value source.
+// residentMu also orders lazy initialization against Close.
+func (s *NativePluginSource) commandContext() context.Context {
+  s.residentMu.Lock()
+  defer s.residentMu.Unlock()
+  if s.processContext == nil {
+    s.processContext, s.cancelProcesses = context.WithCancel(context.Background())
+    if s.closed {
+      s.cancelProcesses()
+    }
+  }
+  return s.processContext
+}
+
+// Close marks the session closed, cancels its command context and attempts
+// resident pipe closure, kill and Wait. It always returns nil rather than
+// reporting cleanup errors and does not join one-shot calls or refresh tasks.
+// Calls after Close cannot start another child through that cancelled context.
+// A running rule has no computation deadline while the source remains open.
+//
+// @evidence contracts/common.md#principled-implementation Closed state and shared cancellation precede resident-lock acquisition, allowing the cancellation callback to close owned reply pipes. Resident cleanup attempts Wait, but ignored pipe/kill/wait errors and the nil return do not certify successful termination of every running task.
+// @evidence contracts/common.md#clear-and-simple-design One idempotent boundary revokes future starts, cancels one-shot/resident command contexts, closes refresh scheduling and serially cleans detached residents. One-shot calls and refresh computations own their own completion.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Cancellation corrects process ownership rather than adding a timeout to conceal a blocked shutdown.
+// @evidence contracts/common.md#meaningful-documentation Native prose states post-close behavior and the absence of a computation deadline, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation CommandContext cancellation and pipe closure use Go abstractions across native platforms; inherited descendant processes are not themselves owned or recursively terminated.
+// @evidence contracts/performance.md#efficient-algorithms Teardown detaches the resident map and traverses its entries once, acquiring each resident lock and attempting serial cleanup. Lock and process/pipe waits can dominate elapsed time; Command.WaitDelay is not an overall Close deadline, and opt-in observation adds trace serialization and writes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Closing source ownership is not reusable computation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Shared cancellation requests child termination before resident Wait; pipe/kill/wait errors are ignored while resident handles are cleared. Closed schedulers discard queued reruns, but Close does not join one-shot calls, refresh tasks, cancellation callbacks or caller-owned writers, recursively terminate descendants, or impose an overall timeout. Corpus and other cache fields are not cleared by this transition and remain retained while the source is reachable.
+func (s *NativePluginSource) Close() error {
+  s.shutdownResidents()
+  return nil
+}
+
 func (b *limitedBuffer) Write(p []byte) (int, error) {
   remaining := b.limit - b.Len()
   if remaining <= 0 {
@@ -153,8 +303,19 @@ func (b *limitedBuffer) Bytes() []byte {
   return b.buf.Bytes()
 }
 
-// NewNativePluginSource parses a launcher-produced manifest and discovers the
-// command ids owned by every LSP-capable sidecar.
+// NewNativePluginSource parses a launcher-produced manifest, discovers command
+// ownership, and initializes retained project inputs. Discovery failures are
+// logged and skipped; successful construction does not certify that every
+// sidecar answered or that sequential input observations share one capture.
+//
+// @evidence contracts/common.md#principled-implementation Parsed startup snapshots are normalized and their selected reload fingerprints compared before storage. Supplied digest syntax and sequential equality are not producer-capture authentication; native failure markers can compare equal. Logical client spelling remains separate from the supplied sidecar context.
+// @evidence contracts/common.md#clear-and-simple-design Static command discovery precedes snapshot initialization; optional corpus work starts through the ordinary refresh scheduler.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Missing snapshots use supported discovery; its failed producers are skipped rather than guessed. JSON decoding and snapshot/selection validation reject their stated malformed inputs, without authenticating the manifest's claimed physical context or producer completeness.
+// @evidence contracts/common.md#meaningful-documentation Native prose distinguishes accepted startup state from complete discovery; lifecycle prose explains scheduled corpus acquisition under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Direct command arguments preserve executable/argument separation and sidecar cwd. Snapshot normalization uses native identity attempts with lexical or unknown-case fallbacks; client protocol spelling remains separate, and supplied physical context is not independently authenticated here.
+// @evidence contracts/performance.md#efficient-algorithms Manifest JSON bytes and descriptor/key text are processed before deduplicated command queries. Startup normalization, file-byte hashing, directory listings and native case/path probes delegate real I/O; each accepted producer store can rebuild and sort the aggregate. Selection validation and scheduled corpus work add their own input-dependent costs; no startup deadline is imposed.
+// @evidence contracts/performance.md#reuse-equivalent-work Command ownership is retained for session descriptors after one discovery attempt per deduplicated transport, including skipped failures. Shared snapshot keys reuse supplied data after normalization and selected current comparisons, not an authenticated launcher graph; missing inputs invoke discovery and can coexist with retained successful startup records.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Failure requests shutdown of the partially initialized source; success transfers that responsibility to Close or Proxy.Run. Shutdown cancels context and attempts resident cleanup but does not join all direct calls or refresh callbacks or clear retained records. Manifest, command-owner and aggregate bytes have no independent session budget; per-command output caps do not bound total retained bytes or native execution time.
 func NewNativePluginSource(opts NativePluginSourceOptions) (*NativePluginSource, error) {
   var manifest NativePluginManifest
   if strings.TrimSpace(opts.ManifestJSON) != "" {
@@ -168,22 +329,9 @@ func NewNativePluginSource(opts NativePluginSourceOptions) (*NativePluginSource,
   if err != nil {
     return nil, fmt.Errorf("ttscserver: encode plugin manifest: %w", err)
   }
-  sidecarCwd := opts.Cwd
-  sidecarTsconfig := opts.Tsconfig
-  if len(manifest.ProjectContext) > 0 {
-    var identity struct {
-      PhysicalConfigPath  string `json:"physicalConfigPath"`
-      PhysicalProjectRoot string `json:"physicalProjectRoot"`
-    }
-    if err := json.Unmarshal(manifest.ProjectContext, &identity); err != nil {
-      return nil, fmt.Errorf("ttscserver: decode project context: %w", err)
-    }
-    if strings.TrimSpace(identity.PhysicalProjectRoot) != "" {
-      sidecarCwd = identity.PhysicalProjectRoot
-    }
-    if strings.TrimSpace(identity.PhysicalConfigPath) != "" {
-      sidecarTsconfig = identity.PhysicalConfigPath
-    }
+  sidecarCwd, sidecarTsconfig, err := nativeSidecarContext(opts.Cwd, opts.Tsconfig, manifest.ProjectContext)
+  if err != nil {
+    return nil, err
   }
   source := &NativePluginSource{
     cwd:                sidecarCwd,
@@ -196,6 +344,12 @@ func NewNativePluginSource(opts NativePluginSourceOptions) (*NativePluginSource,
     clientCwd:          opts.Cwd,
     owners:             map[string]NativeLSPPluginEntry{},
   }
+  accepted := false
+  defer func() {
+    if !accepted {
+      source.shutdownResidents()
+    }
+  }()
   source.discoverCommandIDs()
   missingInitialProjectInputs := false
   for _, plugin := range selectPluginTransports(
@@ -243,20 +397,49 @@ func NewNativePluginSource(opts NativePluginSourceOptions) (*NativePluginSource,
   if missingInitialProjectInputs {
     source.discoverProjectInputs(1)
   }
-  // The corpus fetch loads a Program, so it runs off the construction path.
-  // Blocking here would delay initialize — and therefore the editor's first
-  // response — for a feature most projects do not use. Until it lands,
-  // CompletionHints answers nil and the editor sees exactly what it sees today.
+  if manifest.SelectionInputs != nil {
+    selection, err := newPluginSelectionInputs(*manifest.SelectionInputs)
+    if err != nil {
+      return nil, fmt.Errorf(
+        "ttscserver: plugin selection inputs are invalid: %w",
+        err,
+      )
+    }
+    if !selection.current() {
+      return nil, fmt.Errorf(
+        "ttscserver: plugin selection inputs changed during startup",
+      )
+    }
+    source.projectInputsMu.Lock()
+    source.selection = selection
+    source.projectInputs = source.flattenProjectInputsLocked()
+    source.projectInputsMu.Unlock()
+  }
+  // Optional corpus queries run off the construction path so their native
+  // execution does not block initialize. CompletionHints may remain nil until
+  // an accepted corpus lands; nil does not certify successful absence.
   //
   // The first fetch goes through the same scheduler every later refresh uses,
   // so startup and mid-session rediscovery share one generation counter and one
   // coalescing rule rather than racing as two independent writers.
   source.RefreshCompletionHints()
+  accepted = true
   return source, nil
 }
 
-// Diagnostics asks every LSP-capable sidecar for document diagnostics and its
-// separate project publication.
+// Diagnostics queries each selected native transport for document diagnostics
+// and any embedded project publication. Failed queries/decodes are logged and
+// skipped; an empty document result does not certify that all producers succeeded.
+// Project output can aggregate last-good records from different request generations.
+//
+// @evidence contracts/common.md#principled-implementation Legacy arrays and structured results use separate decoding paths. A nonempty project URI enters that producer's generation-guarded store, while the response marker records receipt even if an older store is rejected. Aggregation can therefore report current retained records rather than one common request capture; skipped failures do not certify successful absence.
+// @evidence contracts/common.md#clear-and-simple-design Transport deduplication and result decoding are shared helpers; document and project outputs remain distinct.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Legacy wire decoding is a supported protocol difference, while failed producers retain explicitly last-good project state rather than claiming fresh output.
+// @evidence contracts/common.md#meaningful-documentation Native prose states document and project contribution scope, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Native executable/argv and logical document URI values are separated. Project URI restatement uses native realpath/ancestor fallback and, on Windows, owning-directory case queries; failed observation preserves distinctions or lexical spelling rather than certifying physical producer/artifact identity.
+// @evidence contracts/performance.md#efficient-algorithms One query iteration per selected transport can involve a resident attempt and one-shot fallback. Work includes transport/key-byte hashing, native IO, structured/legacy decoding, diagnostic appends and per-publication copies. Manifest-ordered aggregation additionally resolves each project URI through native path/case queries while holding its read lock; logging can also block and observation adds trace IO.
+// @evidence contracts/performance.md#reuse-equivalent-work Resident requests share sidecar state and carry queued invalidations; actual freshness still depends on caller notifications and producer behavior. Last-good project records have per-producer generation guards, not a common filesystem capture, and document replies are not cached solely by URI.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Per-command output caps do not bound aggregate document/project values or concurrent callers. Last-good project records and their nested payloads have no aggregate age/byte budget and survive Close while the source is reachable; shallow diagnostic copies can share nested data with returned values. Native commands have source cancellation and post-exit/cancellation WaitDelay but no open-session computation deadline; Close does not certify all task or descendant termination.
 func (s *NativePluginSource) Diagnostics(doc LSPDocumentVersion) LSPDiagnosticsResult {
   if s == nil || doc.URI == "" {
     return LSPDiagnosticsResult{}
@@ -304,7 +487,19 @@ func decodeNativeDiagnostics(body []byte) (LSPDiagnosticsResult, error) {
   return LSPDiagnosticsResult{Document: legacy}, nil
 }
 
-// CodeActions asks every LSP-capable sidecar for actions matching the request.
+// CodeActions asks each selected native transport for command-backed actions.
+// Failed queries or invalid replies are logged and skipped; the returned slice
+// does not report whether all producers succeeded. Range/context marshal errors
+// are ignored, so malformed raw context data can leave an empty argument.
+//
+// @evidence contracts/common.md#principled-implementation Range/context values are JSON-encoded for the selected transport, with marshal errors currently ignored rather than certified as unchanged payloads. Direct edits, commandless actions and commands owned by another advertised transport are rejected; skipped producer failures do not certify a complete or successfully empty result.
+// @evidence contracts/common.md#clear-and-simple-design Producer queries and ownership validation share the existing transport and command map.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Edit rejection is a native ownership boundary, not a success-shaped substitute for implementing an advertised command.
+// @evidence contracts/common.md#meaningful-documentation Native prose states matching inputs; nearby validation comments explain command-only ownership under the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation URI remains protocol data while native exec receives separate argv entries; no shell quoting or OS-name-based path folding occurs.
+// @evidence contracts/performance.md#efficient-algorithms Transport selection hashes binary/context-mode key bytes before serial producer queries. Costs include range/context encoding, native work and blocking, reply decoding, raw-edit trimming, command/key hashing and log formatting, not just action counts or constant-time ownership lookup. Fallback can add a one-shot spawn after a resident transport failure; opt-in observation adds serialization and IO.
+// @evidence contracts/performance.md#reuse-equivalent-work Resident requests serialize their pipe and carry queued invalidations, while actual freshness requires caller change notifications and sidecar behavior. Actions remain URI/range/context-specific; this method has no response-shape cache and failed transports can fall back to a fresh command.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Each native reply has a byte cap, but aggregate decoded actions across producers, request encoding and concurrently waiting callers are uncapped here. Returned values can retain decoded strings/raw data. Close requests cancellation and attempts resident cleanup without certifying every task's termination; rule computation has no open-session deadline, and caller-owned logging can block.
 func (s *NativePluginSource) CodeActions(uri string, rng LSPRange, ctx LSPCodeActionContext) []LSPCodeAction {
   if s == nil || uri == "" {
     return nil
@@ -334,16 +529,8 @@ func (s *NativePluginSource) CodeActions(uri string, rng LSPRange, ctx LSPCodeAc
       continue
     }
     for _, action := range actions {
-      if hasDirectCodeActionEdit(action.Edit) {
-        s.log("ttscserver: %s returned direct LSP edit for action %q; command-backed actions are required", pluginLabel(plugin), action.Title)
-        continue
-      }
-      if action.Command == nil {
-        s.log("ttscserver: %s returned commandless LSP action %q; command-backed actions are required", pluginLabel(plugin), action.Title)
-        continue
-      }
-      if !s.pluginOwnsCommand(plugin, action.Command.Command) {
-        s.log("ttscserver: %s returned unowned LSP command %q", pluginLabel(plugin), action.Command.Command)
+      if rejection := nativeCodeActionRejection(plugin, action, func(command string) bool { return s.pluginOwnsCommand(plugin, command) }); rejection != "" {
+        s.log("%s", rejection)
         continue
       }
       out = append(out, action)
@@ -354,6 +541,15 @@ func (s *NativePluginSource) CodeActions(uri string, rng LSPRange, ctx LSPCodeAc
 
 // ExecuteCommand routes a ttsc-owned workspace command to the sidecar that
 // advertised it through lsp-command-ids.
+//
+// @evidence contracts/common.md#principled-implementation Delegation retains command ownership and argument meaning while explicitly selecting the disk-backed path.
+// @evidence contracts/common.md#clear-and-simple-design The content-aware operation owns execution and edit decoding for both entries.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts This forwarding entry does not maintain a separate command interpretation.
+// @evidence contracts/common.md#meaningful-documentation Native prose names the advertised owner boundary, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation The delegated operation owns executable argv and native working-directory interpretation.
+// @evidence contracts/performance.md#efficient-algorithms Delegation performs the content-aware executor's command-key hashing, raw-argument encoding, native command work and reply decoding. This wrapper adds no duplicate interpretation but does not remove those payload-dependent and blocking costs.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work The delegated operation owns the effectful command policy.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Native child ownership belongs to the delegated executor and source lifetime.
 func (s *NativePluginSource) ExecuteCommand(command string, args []json.RawMessage) (*LSPWorkspaceEdit, error) {
   return s.ExecuteCommandWithContent(command, args, "", false)
 }
@@ -364,9 +560,18 @@ func (s *NativePluginSource) ExecuteCommand(command string, args []json.RawMessa
 // adding the --content-stdin flag and piping content to the sidecar's stdin, so
 // the proxy can format dirty editor buffers (formatOnSave) without first writing
 // them to disk. hasContent — not content != "" — gates the in-memory path: an
-// empty buffer the user cleared is a valid document state and must still format
-// in-memory (to a no-op) rather than falling through to stale disk content.
+// empty buffer the user cleared still travels through stdin rather than falling
+// through to stale disk content. The sidecar determines the returned edits.
 // Decoding of the returned WorkspaceEdit is identical to ExecuteCommand.
+//
+// @evidence contracts/common.md#principled-implementation Advertised ownership selects the producer; hasContent distinguishes an empty live buffer from absent buffer input. Invalid raw argument JSON is rejected before a process starts.
+// @evidence contracts/common.md#clear-and-simple-design One executor handles disk and stdin modes, accepts null or decodes the changes-only WorkspaceEdit shape, and rejects non-null documentChanges. Decoding does not certify edit coordinates, URI ownership or semantic correctness.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Empty content does not trigger a stale-disk fallback; unknown commands return the ownership sentinel.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain empty-buffer semantics and shared decoding, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation exec receives binary and separate flags; live buffer text travels through stdin without shell interpolation or newline rewriting.
+// @evidence contracts/performance.md#efficient-algorithms Costs include command-string hashing, raw argument validation/encoding and copies, native execution and IO, then two JSON passes for non-null edit replies. strings.Reader shares existing content rather than concatenating it into argv, but transport still consumes its bytes; opt-in observation adds serialization and trace writes.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Executing a workspace command may cause external effects, so matching inputs do not authorize shared execution.
+// @evidence contracts/performance.md#bound-retention-and-release-resources Cmd.Run waits a successfully started direct child and uses the source cancellation context; output buffers have per-child byte caps and WaitDelay applies after cancellation or process exit rather than imposing a computation deadline. Argument/content inputs, concurrent calls and aggregate decoded edit ownership are not independently capped here. Source.Close does not join these calls or certify descendant termination; returned edits remain caller-owned.
 func (s *NativePluginSource) ExecuteCommandWithContent(command string, args []json.RawMessage, content string, hasContent bool) (*LSPWorkspaceEdit, error) {
   if s == nil {
     return nil, ErrCommandNotHandled
@@ -375,15 +580,9 @@ func (s *NativePluginSource) ExecuteCommandWithContent(command string, args []js
   if !ok {
     return nil, ErrCommandNotHandled
   }
-  argsJSON, _ := json.Marshal(args)
-  cmdArgs := []string{
-    "--command=" + command,
-    "--arguments-json=" + string(argsJSON),
-  }
-  var stdin io.Reader
-  if hasContent {
-    cmdArgs = append(cmdArgs, "--content-stdin")
-    stdin = strings.NewReader(content)
+  cmdArgs, stdin, encodeErr := nativeExecuteCommandInput(command, args, content, hasContent)
+  if encodeErr != nil {
+    return nil, encodeErr
   }
   body, err := s.runWithStdin(plugin, "lsp-execute-command", stdin, cmdArgs...)
   if err != nil {
@@ -418,6 +617,15 @@ func decodeNativeLSPWorkspaceEdit(plugin NativeLSPPluginEntry, body []byte) (*LS
 }
 
 // CommandIDs returns the command ids discovered at source construction time.
+//
+// @evidence contracts/common.md#principled-implementation Copying the immutable discovered IDs prevents callers from rewriting source command ownership.
+// @evidence contracts/common.md#clear-and-simple-design Discovery owns identity selection; this accessor only exposes its result.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Identities come from actual producer advertisement rather than a fixed command list.
+// @evidence contracts/common.md#meaningful-documentation Native prose states construction-time discovery, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation This accessor copies protocol strings without interpreting native paths or processes.
+// @evidence contracts/performance.md#efficient-algorithms Copying N IDs takes O(N) time and output space without rediscovery.
+// @evidence contracts/performance.md#reuse-equivalent-work Immutable session descriptors authorize sharing the construction-time command list among all callers.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned copy transfers to the caller; source lifetime owns the original list.
 func (s *NativePluginSource) CommandIDs() []string {
   if s == nil || len(s.commandIDs) == 0 {
     return nil
@@ -430,19 +638,27 @@ func (s *NativePluginSource) CommandIDs() []string {
 // CompletionHints returns the corpus plugins published, or nil until it has
 // been fetched.
 //
-// Nil while loading is deliberate and is the whole reason the fetch is
-// asynchronous. Unlike lsp-command-ids and lsp-code-action-kinds — which ignore
-// their arguments and never build a Program — lsp-hints must load one, because
-// a corpus is a projection of what a project rule's Check found. Paying that on
-// the initialize path would delay every editor session for a feature most
-// projects do not use, and paying it on the first completion would freeze the
-// popup. Answering "no hints yet" degrades honestly: the editor still gets
-// tsgo's completion, and ours appear once they exist.
+// Nil while loading permits asynchronous acquisition. A project-rule hint
+// producer can load a Program to project its Check results; the producer owns
+// that work, and this accessor does not certify its internals. Acquisition is
+// scheduled outside initialization and completion reads. Nil does not distinguish
+// a pending fetch, successful empty publication or failed acquisition, and the
+// accessor supplies no producer-success status.
 //
 // The same reasoning carries to refresh. It answers the last known-good corpus
 // while a rediscovery scheduled by RefreshCompletionHints is running, so
-// completion never blocks on a producer and never observes a half-cleared
-// corpus.
+// completion does not wait for the producer request itself or observe a
+// half-cleared corpus. It can still wait for publication-lock ownership and pay
+// the ready-view copy cost.
+//
+// @evidence contracts/common.md#principled-implementation Locked publication reads return independent hint and item slices, preventing consumers from mutating producer state; failed refreshes retain last-good state explicitly.
+// @evidence contracts/common.md#clear-and-simple-design Writers materialize the ordered corpus, leaving completion reads to copy a ready view.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts A retained corpus is described as last-good rather than falsely current after a failed producer call.
+// @evidence contracts/common.md#meaningful-documentation Native paragraphs explain asynchronous availability and refresh behavior, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation The accessor handles protocol data only; producer execution owns the native boundary.
+// @evidence contracts/performance.md#efficient-algorithms Copying H group headers and I item records is O(H+I) processing and returned slice storage without rebuilding producer order or copying string bytes. The read lock can wait for a writer's corpus flattening; returning hints is not a zero-latency guarantee.
+// @evidence contracts/performance.md#reuse-equivalent-work Callers share a flattened view of per-producer last-good records. Successful stores publish individually, so a response can mix refresh generations; retained data does not certify current inputs after failures or missing notifications.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returned slices transfer to the caller and share immutable string bytes with stored records. Corpus publication owns retained data; Close revokes scheduling but does not clear these fields while the source remains reachable.
 func (s *NativePluginSource) CompletionHints() []LSPCompletionHint {
   if s == nil {
     return nil
@@ -454,6 +670,9 @@ func (s *NativePluginSource) CompletionHints() []LSPCompletionHint {
   }
   out := make([]LSPCompletionHint, len(s.completionHints))
   copy(out, s.completionHints)
+  for index := range out {
+    out[index].Items = append([]LSPCompletionItem(nil), out[index].Items...)
+  }
   return out
 }
 
@@ -462,14 +681,24 @@ func (s *NativePluginSource) CompletionHints() []LSPCompletionHint {
 // The corpus is a projection of what a project rule's Check found, so it goes
 // stale the moment the rule's inputs change: a saved contributor-indexed
 // document, a rule enabled in `lint.config.*`, a watched file rewritten outside
-// the editor. Without this the corpus stayed a session snapshot and only a
+// the editor. Without this the corpus would stay a session snapshot and only a
 // language-server restart could replace it.
 //
 // Asynchronous for the same reason the first fetch is (see CompletionHints):
 // the editor event that schedules a refresh must not wait for a Program load.
-// Concurrent requests coalesce into at most one queued rerun, so a save storm
-// costs one extra refresh rather than one per notification, and the previous
-// corpus keeps answering completion until the new one lands.
+// Requests arriving during one active cycle coalesce into one queued rerun.
+// Continued notifications across later cycles can schedule further reruns; there
+// is no fixed total refresh count for an entire save storm. Previous producer
+// records remain visible until their successful replacements arrive.
+//
+// @evidence contracts/common.md#principled-implementation Serial refresh generations publish producer records individually after successful decoding. A queued rerun requests later discovery rather than certifying that all reported input changes were captured or that all producers succeeded.
+// @evidence contracts/common.md#clear-and-simple-design One coalescing scheduler serves startup and later notifications.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Last-good retention follows explicit failed-refresh policy rather than masking a failure as a successful empty result.
+// @evidence contracts/common.md#meaningful-documentation Separate native paragraphs explain invalidation, nonblocking scheduling and coalescing, following the documentation skill.
+// @evidence contracts/portability.md#os-neutral-implementation Shared native command execution owns executable/argv differences; scheduling does not derive filesystem capabilities from OS labels.
+// @evidence contracts/performance.md#efficient-algorithms A cycle hashes transport/context key bytes and serially queries distinct producers, including native work, reply decoding/grouping, possible fallback and logging/observer costs. Every successful store reselects manifest transports and flattens all currently retained groups under the publication lock, so this full view can be rebuilt once per successful producer rather than once per cycle.
+// @evidence contracts/performance.md#reuse-equivalent-work Concurrent notifications share one active cycle and at most one rerun, while successful stores expose the latest producer generation.
+// @evidence contracts/performance.md#bound-retention-and-release-resources One worker and one pending rerun bound simultaneous scheduler state, not total cycles or producer runtime. Close rejects schedules and requests native cancellation without joining the running task or observer. Replies have per-producer caps, but retained last-good corpora/string bytes have no aggregate age/byte budget and are not cleared by Close; callback completion also has no deadline here.
 func (s *NativePluginSource) RefreshCompletionHints() {
   if s == nil || len(s.plugins) == 0 {
     return
@@ -480,6 +709,15 @@ func (s *NativePluginSource) RefreshCompletionHints() {
 // SetCompletionHintsObserver registers fn to run after each completed refresh
 // cycle. The proxy uses it to notice a trigger character that appeared after
 // the initialize response was already sent. A nil fn clears the observer.
+//
+// @evidence contracts/common.md#principled-implementation The locked observer slot atomically replaces callback ownership; nil removes future notifications, though a callback already copied by a refresh may finish.
+// @evidence contracts/common.md#clear-and-simple-design One callback boundary lets the proxy react without exposing corpus storage.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Supported observation avoids patching producer refresh methods.
+// @evidence contracts/common.md#meaningful-documentation Native prose states notification timing and nil removal, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Callback registration performs no native interpretation.
+// @evidenceExclude contracts/performance.md#efficient-algorithms Assigning an observer chooses no processing algorithm.
+// @evidenceExclude contracts/performance.md#reuse-equivalent-work Refresh scheduling owns coalesced work rather than this callback setter.
+// @evidence contracts/performance.md#bound-retention-and-release-resources One function reference is retained, replaced or cleared under hintsMu, but its captured reachable data has no byte budget imposed here. Previously copied callbacks can still begin or finish after replacement; the setter does not join their execution or cancel their effects.
 func (s *NativePluginSource) SetCompletionHintsObserver(fn func()) {
   if s == nil {
     return
@@ -490,9 +728,9 @@ func (s *NativePluginSource) SetCompletionHintsObserver(fn func()) {
 }
 
 // completionHintRecord is one producer's corpus and the refresh generation that
-// produced it. The generation is what keeps a slow refresh from overwriting a
-// newer one: plugin fetches run sequentially inside a cycle, but two cycles can
-// still be in flight when a scheduled refresh outlives its successor's start.
+// produced it. Normal scheduled cycles are serial; the generation comparison
+// additionally refuses an older producer record if supplied to the store. It
+// does not certify that different producers share one filesystem capture.
 type completionHintRecord struct {
   hints      []LSPCompletionHint
   generation uint64
@@ -529,6 +767,7 @@ func (s *NativePluginSource) discoverCompletionHints(generation uint64) {
       // and the alternative is punishing every well-behaved old plugin to catch
       // a rare new one. Refresh strengthens that trade rather than weakening it:
       // a logged failure would now print per save instead of per session.
+      e2etrace.CompletionHintsPublication(s.cwd, pluginLabel(plugin), generation, "run-failed", 0, err)
       continue
     }
     published, err := decodeNativeCompletionHints(body)
@@ -537,9 +776,14 @@ func (s *NativePluginSource) discoverCompletionHints(generation uint64) {
       // verb and got it wrong, which is worth saying — unlike one that never
       // implemented it at all.
       s.log("ttscserver: %s lsp-hints returned invalid JSON: %v", pluginLabel(plugin), err)
+      e2etrace.CompletionHintsPublication(s.cwd, pluginLabel(plugin), generation, "decode-failed", 0, err)
       continue
     }
-    s.storeCompletionHints(plugin, generation, published)
+    outcome := "published"
+    if !s.storeCompletionHints(plugin, generation, published) {
+      outcome = "superseded"
+    }
+    e2etrace.CompletionHintsPublication(s.cwd, pluginLabel(plugin), generation, outcome, len(published), nil)
   }
   s.notifyCompletionHintsObserver()
 }
@@ -551,18 +795,21 @@ func (s *NativePluginSource) discoverCompletionHints(generation uint64) {
 // empty successful answer clears it — that is how a disabled rule's items stop
 // being offered. An older generation is dropped: refresh cycles are scheduled by
 // editor events, and the last event's answer is the one the user is waiting for.
-func (s *NativePluginSource) storeCompletionHints(plugin NativeLSPPluginEntry, generation uint64, hints []LSPCompletionHint) {
+// The return value reports whether this store actually published, including an
+// empty corpus, so private observation cannot label a rejected result as live.
+func (s *NativePluginSource) storeCompletionHints(plugin NativeLSPPluginEntry, generation uint64, hints []LSPCompletionHint) bool {
   key := pluginKey(plugin, s.projectContextJSON)
   s.hintsMu.Lock()
   defer s.hintsMu.Unlock()
   if existing, ok := s.pluginHints[key]; ok && generation < existing.generation {
-    return
+    return false
   }
   if s.pluginHints == nil {
     s.pluginHints = map[string]completionHintRecord{}
   }
   s.pluginHints[key] = completionHintRecord{hints: hints, generation: generation}
   s.completionHints = s.flattenCompletionHintsLocked()
+  return true
 }
 
 // flattenCompletionHintsLocked concatenates every producer's corpus in manifest
@@ -713,6 +960,15 @@ func usableNativeCompletionItems(items []LSPCompletionItem) []LSPCompletionItem
 }
 
 // CodeActionKinds returns the action kinds discovered from LSP-capable sidecars.
+//
+// @evidence contracts/common.md#principled-implementation Copying discovered kinds prevents callers from mutating source advertisement state.
+// @evidence contracts/common.md#clear-and-simple-design Capability discovery owns selection; the accessor exposes a ready list.
+// @evidence contracts/common.md#prohibited-implementation-shortcuts Kinds come from producer capabilities rather than package-specific substitutions.
+// @evidence contracts/common.md#meaningful-documentation Native prose identifies discovered action kinds, following the documentation skill.
+// @evidenceExclude contracts/portability.md#os-neutral-implementation Action-kind strings are protocol values with no native boundary.
+// @evidence contracts/performance.md#efficient-algorithms The N-kind copy is O(N) time and returned space.
+// @evidence contracts/performance.md#reuse-equivalent-work Immutable session descriptors permit reuse of construction-time capabilities.
+// @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned copy transfers ownership; the source owns its original list.
 func (s *NativePluginSource) CodeActionKinds() []string {
   if s == nil || len(s.codeActionKinds) == 0 {
     return nil
@@ -723,56 +979,13 @@ func (s *NativePluginSource) CodeActionKinds() []string {
 }
 
 func (s *NativePluginSource) discoverCommandIDs() {
-  seen := map[string]struct{}{}
-  kindSeen := map[string]struct{}{}
-  for _, plugin := range selectPluginTransports(
+  discoverNativeCommandRegistry(selectPluginTransports(
     s.plugins,
     nil,
     s.projectContextJSON,
-  ) {
-    body, err := s.run(plugin, "lsp-command-ids")
-    if err != nil {
-      s.log("%v", err)
-      continue
-    }
-    var ids []string
-    if err := json.Unmarshal(body, &ids); err != nil {
-      s.log("ttscserver: %s lsp-command-ids returned invalid JSON: %v", pluginLabel(plugin), err)
-      continue
-    }
-    for _, id := range ids {
-      if id == "" {
-        continue
-      }
-      if _, ok := seen[id]; ok {
-        s.log("ttscserver: duplicate LSP command id %q from %s ignored", id, pluginLabel(plugin))
-        continue
-      }
-      seen[id] = struct{}{}
-      s.commandIDs = append(s.commandIDs, id)
-      s.owners[id] = plugin
-    }
-    kindBody, kindErr := s.run(plugin, "lsp-code-action-kinds")
-    if kindErr != nil {
-      s.log("%v", kindErr)
-      continue
-    }
-    var kinds []string
-    if err := json.Unmarshal(kindBody, &kinds); err != nil {
-      s.log("ttscserver: %s lsp-code-action-kinds returned invalid JSON: %v", pluginLabel(plugin), err)
-      continue
-    }
-    for _, kind := range kinds {
-      if kind == "" {
-        continue
-      }
-      if _, ok := kindSeen[kind]; ok {
-        continue
-      }
-      kindSeen[kind] = struct{}{}
-      s.codeActionKinds = append(s.codeActionKinds, kind)
-    }
-  }
+  ), func(plugin NativeLSPPluginEntry, command string) ([]byte, error) {
+    return s.run(plugin, command)
+  }, func(message string) { s.log("%s", message) }, &s.commandIDs, &s.codeActionKinds, s.owners)
 }
 
 func (s *NativePluginSource) pluginOwnsCommand(plugin NativeLSPPluginEntry, command string) bool {
@@ -788,58 +1001,33 @@ func (s *NativePluginSource) pluginOwnsCommand(plugin NativeLSPPluginEntry, comm
 }
 
 func (s *NativePluginSource) run(plugin NativeLSPPluginEntry, command string, args ...string) ([]byte, error) {
-  // Route the Program-loading read verbs through the plugin's resident daemon so
-  // a warm Program is reused across verbs. serveRun returns served=false for a
-  // sidecar that predates lsp-serve or a transport failure, falling back to the
-  // spawn-per-verb path below with no behavior change. The static discovery
-  // verbs (lsp-command-ids / lsp-code-action-kinds) and lsp-execute-command stay
-  // on exec by design.
-  if command == serveVerbDiagnostics ||
-    command == serveVerbCodeActions {
-    if body, served, err := s.serveRun(plugin, command, args); served {
-      return body, err
-    }
-  }
-  if command == serveVerbProjectDiagnostics ||
-    command == serveVerbHints {
-    // These newer optional verbs join the daemon on a weaker condition than the
-    // original document reads. A staged sidecar may implement the direct verb
-    // while its older resident loop rejects it. A nonzero resident reply is
-    // indistinguishable from the verb itself failing, so retry once through the
-    // advertised direct command. A genuine failure pays one extra spawn and is
-    // then handled exactly as it was before lsp-serve.
-    if body, served, err := s.serveRun(plugin, command, args); served && err == nil {
-      return body, nil
-    }
-  }
-  return s.runWithStdin(plugin, command, nil, args...)
+  return runNativePluginRead(command, args,
+    func(verb string, arguments []string) ([]byte, bool, error) {
+      return s.serveRun(plugin, verb, arguments)
+    },
+    func(verb string, arguments []string) ([]byte, error) {
+      return s.runWithStdin(plugin, verb, nil, arguments...)
+    },
+  )
 }
 
 // runWithStdin runs a sidecar subcommand like run, additionally wiring stdin to
 // the supplied reader when it is non-nil. Callers that do not pass buffer text
 // (Diagnostics, CodeActions, discovery) reach this through run with a nil
-// reader, leaving the sidecar's stdin unset exactly as before.
+// reader, leaving the sidecar's stdin unset exactly as before. The opt-in
+// observer retains these already captured limited buffers and truncation flags
+// under the same invocation; original parsing and result ownership are unchanged.
 func (s *NativePluginSource) runWithStdin(plugin NativeLSPPluginEntry, command string, stdin io.Reader, args ...string) ([]byte, error) {
   if strings.TrimSpace(plugin.Binary) == "" {
     return nil, fmt.Errorf("ttscserver: %s has no binary", pluginLabel(plugin))
   }
-  // No deadline: the command is running the user's own rules, and how long
-  // that takes is not this process's call. The context stays so that a future
-  // early return cannot leave the child running — cancelling it kills the
-  // process rather than abandoning it.
-  ctx, cancel := context.WithCancel(context.Background())
-  defer cancel()
-  allArgs := []string{
-    command,
-    "--cwd=" + s.cwd,
-    "--tsconfig=" + s.tsconfig,
-    "--plugins-json=" + s.pluginsJSON,
-  }
-  if plugin.ProjectContextArgs && strings.TrimSpace(s.projectContextJSON) != "" {
-    allArgs = append(allArgs, "--project-context-json="+s.projectContextJSON)
-  }
-  allArgs = append(allArgs, args...)
+  // Rules have no computation deadline, but session teardown cancels their
+  // processes. WaitDelay bounds pipe draining after exit or cancellation when
+  // a descendant inherited the child's output handles.
+  ctx := s.commandContext()
+  allArgs := nativePluginCommandArgs(plugin, command, s.cwd, s.tsconfig, s.pluginsJSON, s.projectContextJSON, args)
   cmd := exec.CommandContext(ctx, plugin.Binary, allArgs...)
+  cmd.WaitDelay = time.Second
   cmd.Dir = s.cwd
   cmd.Env = os.Environ()
   if stdin != nil {
@@ -849,20 +1037,11 @@ func (s *NativePluginSource) runWithStdin(plugin NativeLSPPluginEntry, command s
   stderr := limitedBuffer{limit: nativePluginCommandStderrLimit}
   cmd.Stdout = &stdout
   cmd.Stderr = &stderr
+  observation := e2etrace.BeginCommand(cmd, "Run")
   err := cmd.Run()
-  if err != nil {
-    msg := strings.TrimSpace(stderr.String())
-    if msg == "" {
-      msg = err.Error()
-    } else if stderr.truncated || stderr.Len() >= nativePluginCommandStderrLimit {
-      msg += " (stderr truncated)"
-    }
-    return nil, fmt.Errorf("ttscserver: %s %s failed: %s", pluginLabel(plugin), command, msg)
-  }
-  if stdout.truncated {
-    return nil, fmt.Errorf("ttscserver: %s %s produced more than %d bytes on stdout", pluginLabel(plugin), command, nativePluginCommandStdoutLimit)
-  }
-  return bytes.TrimSpace(stdout.Bytes()), nil
+  observation.Result(err)
+  observation.Output(stdout.Bytes(), stderr.Bytes(), stdout.truncated, stderr.truncated)
+  return nativePluginCommandResult(plugin, command, err, &stdout, &stderr)
 }
 
 func hasDirectCodeActionEdit(edit json.RawMessage) bool {