[ian-pascoe]

Summary

Each Pi session built its own LspServerManager, so every Minimal Subagents child (and Advisor session) that touched code cold-started its own tsc --lsp (about 8–10 CPU-s, 650–900 MB RSS) and oxlint for the same workspace root as its parent. Now the sessions in one Pi process share Server Instances through a pi-lsp-private pool, and each session holds a Server Instance Lease on the instances it uses.

globalThis[Symbol.for("@ian-pascoe/pi-lsp/server-instance-pool.v1")]   # pi-lsp only; no other package imports it
  key = [pi-lsp version, serverId, root, command, args, env, initializationOptions,
         settings, lsp.timeouts, maxConcurrentDiagnostics]
  entry: client | shared startup, leases, failure state, stderr (tmp, 0700/0600), #464 limiter

session A ──lease──┐
session B ──lease──┼──▶ one process per key
child C   (no lease until first use)

 LspServerManager (per session: routing, enablement, known routes, previews, session files)
-  ensureClient → LspServerClient.start(…session callbacks…)
+  ensureClient → pool.acquire(key, holder, start)    # lazy lease; joins a running or starting instance
-  stopServer / restartServer → client.shutdown()
+  stopServer / restartServer → pool.stop(key)        # stops for every leaseholder; each restarts lazily
-  shutdown → stop every client
+  shutdown → release every lease                     # the last release stops the process
+  disable  → release this session's leases only
 workspace/applyEdit (always unsolicited)
+  one leaseholder → held preview in that session; two or more → applied:false (cannot attribute)
 lsp_status / /lsp
+  "… shared with N other sessions" + shared_with_sessions (omitted when N = 0)

Decisions: ADR-0005. Glossary: Server Instance redefined, Server Instance Lease added, and the behavior boundary updated. A session that holds no lease shows an instance as stopped, even while other sessions run it.

Closes #465

Evidence

• Before: two pi-lsp sessions in one process with the same cwd and settings → 2 launches of the fake server for each Server Definition and root.
  After: test/lsp-shared-server-instances.test.ts (two extension instances, fake server logging launches):

  same cwd + settings                         → 1 launch
  different settings value / project override → separate launches
  concurrent cold routes; trigger session shuts down mid-start → 1 launch, other session gets running client
  child shutdown → parent keeps instance; last shutdown → process exits; unused session takes no lease
  /lsp stop in A → process dead for both; next use relaunches
  crash → unavailable in both; lsp_restart from either → recovered for both
  lsp_restart while initialize is delayed → fresh running instance, no failure state
  disable in A → B keeps using the process
  unsolicited applyEdit: 1 leaseholder → preview; 2 → server logs {applied:false, failureReason:"…cannot attribute…"}
  stderr survives starter shutdown, removed on stop; dir 0700, file 0600
  lsp_status → "shared with 1 other session"; single-session text byte-identical
  maxConcurrentDiagnostics: 1 across two sessions → peak 1 in flight
  stop with a missing definition → lease released, no orphan
  

• Independent two-axis review (standards and spec): the possible bugs, test gaps and cleanups it found are fixed in 54f353b.

• pnpm --filter @ian-pascoe/pi-lsp test: 523 passed. pnpm test:root: 15 passed. pnpm verify passes.

Merge Danger

Door: two-way

The pool lives in process memory and no persisted format changes. Reverting restores one manager per session.

Blast Radius: lsp-lifecycle

• /lsp stop and lsp_restart now affect every session using the instance, and a crash in one session's request makes the instance unavailable in all of them.
• Server-initiated edits are declined while two or more sessions share an instance.
• Server stderr files move from the session directory to a temp directory for each Server Instance.
• Two copies of pi-lsp at the same version but with different code, such as a linked dev checkout and a published copy, share instances. This limitation is accepted and recorded in ADR-0005.