prometeu-studio/discussion/workflow/plans/PLN-0066-project-scoped-lsp-server-lifecycle-in-studio.md

id	ticket	title	status	created	completed	tags
PLN-0066	studio-new-lsp-api-and-v1-boundary	Project-Scoped LSP Server Lifecycle in Studio	open	2026-05-05		studio lsp lifecycle projects boot shutdown

Objective

Wire the new LSP server lifecycle into the Studio project lifecycle so a server starts when a project opens and stops when that project closes, without introducing a process-global LSP service.

Background

DEC-0032 requires a project-scoped server lifecycle and explicitly rejects a global Studio-wide server. The current natural integration points are:

• StudioProjectSession
• StudioProjectSessionFactory
• StudioWindowCoordinator

These surfaces already own project startup and teardown flow and therefore are the correct place to consume lsp-api.

Scope

Included

• Add project-scoped LSP server ownership to the Studio project session lifecycle.
• Boot the server during project open.
• Shutdown the server during project close.
• Preserve existing shell, packer, play/stop, and debug flows.

Excluded

• Rich semantic responses.
• Automation channel work.
• VS Code extension transport changes.

Non-Goals

• Cross-project shared server process management.
• Multi-project pooling or server reuse.
• Changing the overall launcher/window model.

Execution Steps

Step 1 - Extend project session ownership to include the LSP lifecycle boundary

What: Make StudioProjectSession own the new project-scoped LSP service reference. How: Add the minimal lsp-api contract to StudioProjectSession, ensure it is initialized by StudioProjectSessionFactory, and guarantee shutdown on close(), including failure-safe teardown ordering. File(s): prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java, prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSessionFactory.java, related tests.

Step 2 - Trigger boot during project open flow

What: Start the LSP server as part of project initialization. How: Update the project-open sequence so the server boots after the project context is ready and before the project window is considered fully opened. Ensure failures surface as project-open failures instead of becoming silent background errors. File(s): prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java, possibly prometeu-app/src/main/java/p/studio/AppContainer.java and prometeu-studio/src/main/java/p/studio/Container.java if dependency injection changes are needed.

Step 3 - Trigger shutdown during project close flow

What: Cleanly stop the project-bound server when the project closes. How: Ensure the existing project close path tears down the LSP service through the session close path, with no leaked socket listener or hanging background resources. File(s): prometeu-studio/src/main/java/p/studio/window/StudioWindowCoordinator.java, prometeu-studio/src/main/java/p/studio/projectsessions/StudioProjectSession.java.

Step 4 - Preserve current dumb connectivity semantics

What: Keep the initial server behavior intentionally simple while validating lifecycle. How: Wire the server so the VS Code extension can still connect over TCP, even if the server behavior remains a minimal handshake or stubbed capability set for now. File(s): prometeu-lsp/prometeu-lsp-v1/src/main/java/**, tools/vscode-extension/src/extension.ts only if configuration or expectations need adjustment.

Test Requirements

Unit Tests

• Verify project session close calls LSP shutdown exactly once.
• Verify boot failures are surfaced deterministically during project open.
• Verify repeated close remains idempotent.

Integration Tests

• Run prometeu-studio tests covering project open/close lifecycle.
• Add a focused integration test proving a project-scoped server is booted and then shut down.

Manual Verification

• Open a Studio project, confirm the server starts.
• Close the project, confirm the server port is released and the process/resources terminate.
• Connect via the existing VS Code extension and confirm the dumb server remains reachable.

Acceptance Criteria

• Opening a Studio project boots an LSP server for that project.
• Closing the project shuts down that server.
• The lifecycle is owned by project session boundaries, not global app startup.
• Existing non-LSP project flows remain operational.
• The current dumb connectivity workflow remains usable as a temporary implementation phase.

Dependencies

• DEC-0032 accepted and normatively locked.
• PLN-0065 providing the new module and API boundary.

Risks

• Startup ordering mistakes can make project open flaky or hide boot errors.
• Shutdown ordering mistakes can leak ports or threads.
• Lifecycle wiring can accidentally reintroduce global process ownership if the session boundary is not kept strict.