prometeu-studio/discussion/workflow/plans/PLN-0044-runtime-handshake-selective-integration.md

id	ticket	title	status	created	completed	tags
PLN-0044	studio-debugger-workspace-integration	Ordered Plan 4 - Runtime handshake integration from selective debugger knowledge	review	2026-04-06		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.