---
id: PLN-0044
ticket: studio-debugger-workspace-integration
title: Ordered Plan 4 - Runtime handshake integration from selective debugger knowledge
status: review
created: 2026-04-06
completed:
tags: [studio, debugger, runtime, handshake, remote-connection]
---

## Objective

Integrate the minimum runtime/debug-session handshake needed for the current flow, using selective knowledge from `../debugger` without creating a project linkage.

## Background

`DEC-0022` allows handshake details to be derived from `../debugger` while keeping Studio-native boundaries. `DEC-0021` reserves `debug` for the future but requires enough session behavior to support the current `run` flow and debugger destination.

## Scope

### Included
- Study and selectively port the useful runtime-handshake behavior from `../debugger`.
- Implement Studio-native handshake/session integration code.
- Publish handshake state into the shared execution session boundary.

### Excluded
- Composite build or live dependency on `../debugger`.
- Full debugger feature parity.
- Profiler behavior.
- Manual rich connection-control UI.

## Execution Steps

### Step 1 - Identify the useful handshake slice

**What:** Isolate the exact handshake/protocol/session behavior needed from `../debugger`.
**How:** Read the sibling repo and extract only the minimum details necessary for the current run/debug-session handshake. Do not mirror the standalone app structure.
**File(s):** Study `../debugger`; implement only Studio-native targets under `prometeu-studio`.

### Step 2 - Implement a Studio-native handshake service

**What:** Add handshake/session integration code in Studio-native shape.
**How:** Create a dedicated service or adapter layer that can publish `connecting`, `connected`, and failure information into the shared execution session.
**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent service package.

### Step 3 - Connect the handshake to the shared session

**What:** Make handshake outcomes visible to shell and workspace consumers.
**How:** Feed successful and failed handshake events into the session state machine and merged logs without requiring the visual workspace to own the protocol.
**File(s):** shared session service, handshake adapter/service, tests.

## Test Requirements

### Unit Tests
- Verify handshake success updates the shared session to the expected connected/running path.
- Verify handshake failure updates the shared session to a failure state and emits visible log output.

### Integration Tests
- Simulate the runtime handshake sequence and confirm session consumers receive the expected state transitions.

### Manual Verification
- Run a development build and confirm the session reflects connecting/connected/failed without needing the standalone debugger app.

## Acceptance Criteria

- [ ] Studio contains a native handshake/service implementation shaped for the current flow.
- [ ] No technical linkage to `../debugger` is introduced.
- [ ] Shared session state reflects handshake success and failure.
- [ ] The implementation selectively reuses useful debugger knowledge without wholesale copying.

## Dependencies

- Accepted `DEC-0021` and `DEC-0022`.
- `PLN-0042` shared execution session and log contracts.
- `PLN-0043` first-wave debug workspace surface.

## Risks

- Porting too much from `../debugger` could drag standalone assumptions into Studio.
- Porting too little may leave the current flow without a stable enough handshake.