---
id: PLN-0066
ticket: studio-new-lsp-api-and-v1-boundary
title: Project-Scoped LSP Server Lifecycle in Studio
status: open
created: 2026-05-05
completed:
tags: [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.