---
id: PLN-0045
ticket: studio-play-stop-cartridge-flow
title: Ordered Plan 5 - End-to-end Play/Stop execution flow through shipper and DebugWorkspace
status: review
created: 2026-04-06
completed:
tags: [studio, play-stop, runtime, debugger, shipper, shell]
---

## Objective

Wire the full first-wave `Play/Stop` flow end-to-end through shipper preparation, shared execution session state, native debugger destination, external runtime execution, and direct-stop behavior.

## Background

`DEC-0020`, `DEC-0021`, and `DEC-0022` together now define the intended first-wave behavior. This plan is intentionally last because it integrates the service, session, workspace, and handshake pieces established in the earlier plans.

## Scope

### Included
- `Play` navigation to the debugger destination at flow start.
- Invocation of shipper preparation.
- Propagation of preparation failure into the shared session and debugger destination.
- External runtime spawn `"<runtimePath>" run build` in project root.
- Runtime output publication into shared session and debugger destination.
- Direct runtime kill on `Stop`.

### Excluded
- Preparation cancellation.
- Drift/freshness reuse.
- `debug` command path.
- Profiler behavior.

## Execution Steps

### Step 1 - Wire `Play` into the shared execution destination

**What:** Make pressing `Play` move the user into the debugger destination immediately.
**How:** Navigate to `DebugWorkspace` at the beginning of the flow, before runtime spawn, so preparation failures also appear there.
**File(s):** shell/play controls, workspace selection/navigation logic, `MainView` or equivalent shell coordinator code.

### Step 2 - Invoke shipper preparation and reflect preparation state

**What:** Start the shipper service and reflect `preparing` / `prepare_failed`.
**How:** Transition the shared execution session into `preparing`, consume shipper aggregated preparation output, and stop on first preparation failure.
**File(s):** play orchestration layer, shared session service adapters, shell controls.

### Step 3 - Spawn the external runtime process

**What:** Execute the exact current-wave runtime command.
**How:** Use `ProjectLocalStudioSetup.prometeuRuntimePath` and spawn `"<runtimePath>" run build` with `cwd = project root`. Transition through `connecting`, then `running`, or `runtime_failed` on failure.
**File(s):** runtime orchestration service, shell controls, process-management code.

### Step 4 - Wire `Stop` semantics

**What:** Kill the active runtime process directly.
**How:** Keep one active process handle. Ignore repeated `Play` while active. During `preparing`, `Stop` remains a no-op because cancellation is out of scope.
**File(s):** play/stop controls, runtime orchestration service, shared session service.

### Step 5 - Close the end-to-end loop

**What:** Ensure all logs and state transitions reach the debugger destination consistently.
**How:** Route shipper preparation output plus runtime output into the shared session/log sink. Keep the Activity Feed summary-only.
**File(s):** orchestration layer, shared session adapters, workspace bindings.

## Test Requirements

### Unit Tests
- Verify `Play` transitions the session to `preparing` before runtime spawn.
- Verify repeated `Play` is ignored while runtime is active.
- Verify `Stop` kills the active runtime process and does nothing during `preparing`.
- Verify spawn failures become runtime preflight failures.

### Integration Tests
- End-to-end success path: `Play` opens debugger destination, prepares successfully, spawns runtime, and exposes logs/state.
- Build failure path: debugger destination opens and shows preparation failure without runtime spawn.
- Pack-validation failure path: debugger destination opens and shows preparation failure without runtime spawn.
- Runtime spawn failure path: debugger destination opens and shows runtime failure after successful preparation.

### Manual Verification
- Press `Play` in Studio and confirm the shell navigates to `Debug`.
- Confirm preparation logs appear before runtime output.
- Confirm `Stop` kills a running runtime process.
- Confirm repeated `Play` while running is ignored.

## Acceptance Criteria

- [ ] `Play` opens the debugger destination immediately.
- [ ] The flow executes shipper preparation before runtime spawn.
- [ ] Preparation failures remain visible in the debugger destination.
- [ ] Runtime spawn uses the exact command and working-directory contract from `DEC-0021`.
- [ ] `Stop` kills only the active runtime process and does not cancel preparation.
- [ ] The debugger destination shows merged preparation and runtime logs end-to-end.

## Dependencies

- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
- `PLN-0041` shipper preparation foundation.
- `PLN-0042` shared execution session and log contracts.
- `PLN-0043` first-wave `DebugWorkspace` surface.
- `PLN-0044` runtime handshake selective integration.

## Risks

- End-to-end orchestration may reintroduce ownership confusion if shell, shipper, and debugger boundaries are not kept strict.
- UI timing issues may surface when navigating to the debugger before preparation output begins.
- Process-lifecycle bugs can leave the shell believing a runtime is still active after failure.