dsn: debugger, play/stop, runtime

discussion/index.ndjson

@@ -1,4 +1,4 @@
-{"type":"meta","next_id":{"DSC":23,"AGD":25,"DEC":20,"PLN":41,"LSN":37,"CLSN":1}}
+{"type":"meta","next_id":{"DSC":23,"AGD":25,"DEC":23,"PLN":46,"LSN":37,"CLSN":1}}
 {"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
 {"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
@@ -7,7 +7,7 @@
 {"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
 {"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
 {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
-{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-06","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"in_progress","created_at":"2026-03-30","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0022","file":"DEC-0022-studio-debug-workspace-native-integration.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0009"}],"plans":[{"id":"PLN-0043","file":"PLN-0043-debug-workspace-first-wave-surface.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0022"]},{"id":"PLN-0044","file":"PLN-0044-runtime-handshake-selective-integration.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0021","DEC-0022"]}],"lessons":[]}
 {"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
 {"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
 {"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
@@ -20,4 +20,4 @@
 {"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
 {"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
 {"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
-{"type":"discussion","id":"DSC-0022","status":"open","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-06","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[{"id":"AGD-0023","file":"AGD-0023-studio-play-stop-shipper-phase-1.md","status":"open","created_at":"2026-04-06","updated_at":"2026-04-06"},{"id":"AGD-0024","file":"AGD-0024-studio-play-stop-runtime-run-cartridge.md","status":"open","created_at":"2026-04-06","updated_at":"2026-04-06"}],"decisions":[],"plans":[],"lessons":[]}
+{"type":"discussion","id":"DSC-0022","status":"open","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-06","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[{"id":"AGD-0023","file":"AGD-0023-studio-play-stop-shipper-phase-1.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"},{"id":"AGD-0024","file":"AGD-0024-studio-play-stop-runtime-run-cartridge.md","status":"in_progress","created_at":"2026-04-06","updated_at":"2026-04-06"}],"decisions":[{"id":"DEC-0020","file":"DEC-0020-studio-play-stop-build-pack-preparation.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0023"},{"id":"DEC-0021","file":"DEC-0021-studio-play-stop-runtime-run-from-build.md","status":"accepted","created_at":"2026-04-06","updated_at":"2026-04-06","ref_agenda":"AGD-0024"}],"plans":[{"id":"PLN-0041","file":"PLN-0041-shipper-preparation-foundation.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020"]},{"id":"PLN-0042","file":"PLN-0042-shared-execution-session-and-log-contracts.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]},{"id":"PLN-0045","file":"PLN-0045-play-stop-end-to-end-execution-flow.md","status":"review","created_at":"2026-04-06","updated_at":"2026-04-06","ref_decisions":["DEC-0020","DEC-0021","DEC-0022"]}],"lessons":[]}

discussion/workflow/agendas/AGD-0009-studio-debugger-workspace-integration.md

@@ -2,10 +2,10 @@
 id: AGD-0009
 ticket: studio-debugger-workspace-integration
 title: Integrar ../debugger ao Studio como workspace dedicado
-status: open
+status: in_progress
 created: 2026-03-30
-resolved:
+resolved: 2026-04-06
-decision:
+decision: DEC-0022
 tags:
   - studio
   - debugger
@@ -37,6 +37,11 @@ Domain owner: `studio`
 Owner surface: `docs/specs/studio`
 Cross-domain input: sibling repo `../debugger`
 
+Normative upstream dependencies:
+
+- `DEC-0020` for `Play` preparation through `build -> validate pack -> pack -> manifest`
+- `DEC-0021` for runtime execution through external `"<runtimePath>" run build` and `Play/Stop` process ownership
+
 Superficies relevantes hoje:
 
 - `docs/specs/studio/1. Studio Shell and Workspace Layout Specification.md` ja define `Debugger/Profiler` como parte do baseline workspace set;
@@ -51,16 +56,43 @@ O boundary de produto tambem ja aponta a direcao correta:
 - logs e detalhe de execucao pertencem ao workspace que os possui;
 - o debugger e uma superficie de execucao, nao um detalhe lateral do painel global de utilidades.
 
+As discussoes mais recentes de `Play/Stop` tambem reduziram o primeiro corte que interessa agora:
+
+- o `DebugWorkspace` e o destino futuro dos logs de `build`, validacao de `pack`, `pack` e runtime;
+- `Play/Stop` continua dono do fluxo operacional de `run` nesta wave;
+- o valor principal a reaproveitar do `../debugger` agora esta em filosofia, politicas de debug/remote connection, sessao, protocolo e modelos de eventos, nao em bootstrap de app standalone nem em copia literal de codigo;
+- o objetivo imediato nao e portar "o debugger inteiro", mas sim dar ao Studio uma superficie de execucao e observabilidade nativa.
+- nao precisamos comecar perfeitos: a primeira wave pode ser deliberadamente simples, desde que entregue handshake com o runtime e sink de logs suficiente para destravar `Play/Stop`.
+
+Constraint for this agenda:
+
+- esta agenda trabalha em conjunto com `AGD-0023`/`DEC-0020` e `AGD-0024`/`DEC-0021`;
+- ela NAO pode reinterpretar pipeline de preparacao, politica de execucao, ownership de `Play/Stop` ou trocar `run` por `debug` por inferencia;
+- qualquer mudanca nesses contratos exige revisao explicita das decisions upstream, nao convergencia lateral dentro desta agenda.
+
 ## Open Questions
 
-- [ ] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
+- [x] O objetivo da primeira integracao e hospedar a experiencia atual do `../debugger` quase inteira, ou abrir um primeiro wave menor sob o contrato nativo de workspace do Studio?
-- [ ] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
+- Resposta proposta: o primeiro corte deve ser menor e nativo ao contrato de workspace do Studio, focado em sink de logs de execucao/preparacao e politicas de debug/remote connection.
-- [ ] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
+- [x] Quais partes do `../debugger` sao `core` reaproveitavel dentro do Studio, e quais sao shell/bootstrap de app standalone que nao devem atravessar a fronteira?
-- [ ] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
+- Resposta proposta: o `../debugger` deve ser tratado principalmente como referencia filosofica e arquitetural; sessao, protocolo, cliente de remote connection, politicas de debug e modelos de eventos/estado podem ser reaproveitados quando isso for util, mas nao ha autorizacao para copiar codigo 1:1 por inercia. Bootstrap `Application`/`Stage`, shell standalone e UI acoplada a esse host nao devem atravessar a fronteira como unidade de integracao.
-- [ ] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
+- [x] Qual deve ser a topologia de dependencia: composite build entre repositorios siblings, extracao para modulos compartilhados, ou migracao seletiva de codigo?
-- [ ] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
+- Resposta proposta: a topologia correta desta integracao e migracao seletiva para dentro do Studio, sem link tecnico entre os dois projetos. `../debugger` nao deve virar dependencia viva do Studio porque sera removido em breve. Copia 1:1 deve ser evitada por padrao, mas pode acontecer pontualmente quando for realmente util.
+- [x] Os detalhes do handshake com o runtime ja precisam nascer totalmente redesenhados no Studio, ou podem ser tirados do `../debugger` nesta wave?
+- Resposta proposta: os detalhes do handshake podem ser tirados do `../debugger` nesta wave, desde que entrem no Studio no shape nativo do workspace e sem copiar codigo 1:1 por inercia.
+- [x] Quem passa a ser o owner do ciclo de vida da sessao de debug: o `DebugWorkspace`, a shell do Studio, ou um servico compartilhado com a run surface?
+- Resposta proposta: o owner deve ser um servico/sessao compartilhado consumido pelo `DebugWorkspace`, enquanto `Play/Stop` continua acionando connect/attach/disconnect under the hood nesta wave.
+- [x] Como eventos, telemetria, logs e estados do debugger entram no bus de workspace e no bus global sem criar um segundo sistema paralelo de notificacao?
+- Resposta proposta: `build` e `pack` permanecem owners de seus proprios logs, mas esses streams devem ser agregados, merged e sinkados para o destino de logs do `DebugWorkspace`; o workspace repassa apenas eventos resumidos relevantes para o bus global do Studio.
+- [x] O primeiro corte deve incluir `profiler` junto com `debugger`, ou o baseline inicial fecha apenas `debugger` e deixa profiling como extensao posterior?
+- Resposta proposta: o baseline inicial fecha apenas `debugger`; politicas de connect/disconnect manuais podem ficar mais relevantes quando a wave de profiling existir.
 - [ ] Como preservar tema, i18n e consistencia visual se parte da UI atual do `../debugger` ainda estiver em FXML e recursos proprios?
-- [ ] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?
+- [x] O app standalone `../debugger` continuara existindo como consumidor paralelo do mesmo core, ou a integracao no Studio passa a ser o destino primario?
+- Resposta proposta: o `../debugger` e uma tentativa anterior e sera deletado quando o Studio estiver maduro o suficiente para representa-lo; ele nao deve ser mantido como destino paralelo nem receber novas mudancas durante esta integracao.
+- [x] O sink inicial de logs precisa nascer sofisticado, ou uma console/lista simples com origem visivel ja basta nesta wave?
+- Resposta proposta: uma console/lista simples com origem visivel ja basta nesta wave; merge e apresentacao podem melhorar depois.
+- [x] O `DebugWorkspace` deve abrir ja com estado basico de conexao como `connecting`, `connected` ou `failed`, mesmo com UI ainda crua?
+- Resposta proposta: sim; o workspace deve abrir com estado basico de sessao/conexao desde a primeira wave.
 
 ## Options
 
@@ -76,11 +108,11 @@ O boundary de produto tambem ja aponta a direcao correta:
 - **Con:** Carrega para dentro do Studio um bootstrap orientado a `Application`/`Stage`, com modelo proprio de lifecycle, theming e eventos que nao casa naturalmente com o contrato de workspace atual.
 - **Maintainability:** Media para baixa. Economiza reescrita imediata, mas cristaliza um boundary torto entre app standalone e workspace embutido.
 
-### Option C - Workspace nativo do Studio apoiado em core extraido do debugger
+### Option C - Workspace nativo do Studio com migracao seletiva inspirada no debugger
-- **Approach:** Tratar o `../debugger` como fonte de servicos, protocolo, estado e controle de execucao reaproveitaveis, mas implementar o `DebugWorkspace` como composicao nativa do Studio sobre o contrato `Workspace` + bus tipado + lifecycle-managed controls.
+- **Approach:** Tratar o `../debugger` como referencia arquitetural e fonte seletiva de detalhes uteis, migrando para o Studio apenas o que fizer sentido, em shape nativo ao contrato `Workspace` + bus tipado + lifecycle-managed controls, sem criar dependencia tecnica entre os dois repositorios.
 - **Pro:** Alinha shell spec, workspace framework e boundary de produto, sem descartar o investimento ja feito no debugger.
-- **Con:** Exige separar explicitamente o que e `core` reutilizavel e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
+- **Con:** Exige separar explicitamente o que e filosofia/padrao reutilizavel, o que e core realmente util e o que e shell standalone, entao a primeira onda precisa de mais desenho tecnico.
-- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite que Studio e app standalone compartilhem nucleo sem colapsarem num acoplamento acidental.
+- **Maintainability:** Forte. Preserva a direcao arquitetural correta e permite absorver o valor estrutural do `../debugger` sem importar o host standalone como boundary errado nem copiar codigo por reflexo.
 
 ### Option D - Migracao integral do debugger para dentro do Studio
 - **Approach:** Absorver codigo e UI do `../debugger` para dentro dos modulos do Studio e tratar a aplicacao standalone como legado a ser aposentado.
@@ -96,6 +128,12 @@ O ponto principal nao e "como mostrar alguma tela de debug no Studio". O ponto p
 - o `DebugWorkspace`, que precisa ser um workspace real, com ownership claro de detalhe operacional;
 - e o `../debugger`, que hoje concentra bootstrap de app, protocolo, estado e UI numa aplicacao separada.
 
+Mas esse contrato agora tem limites claros:
+
+- `DEC-0020` ja fecha a preparacao;
+- `DEC-0021` ja fecha a execucao com `run build` e ownership de processo;
+- portanto a agenda 9 so pode definir a superficie que hospeda logs, sessao e politicas remotas compativeis com esses contratos.
+
 O fato de a rail ja ter `Debug` e a spec ja falar em `Debugger/Profiler` indica que a integracao nao e trabalho especulativo.
 Ela ja faz parte da topologia esperada do Studio.
 
@@ -109,6 +147,21 @@ O caminho mais coerente parece ser separar o problema em duas camadas:
 1. um `debugger core` reaproveitavel, com sessao, protocolo, telemetria, logs e controle de execucao;
 2. uma composicao de `DebugWorkspace` nativa do Studio, que consome esse core como mais um workspace do shell.
 
+As decisoes recentes de `Play/Stop` deixam ainda mais claro o primeiro corte util:
+
+- o `DebugWorkspace` deve receber o sink de logs de `build`, validacao de `pack`, `pack` e runtime;
+- `build` e `pack` continuam possuindo seus proprios logs, mas o usuario deve ve-los merged no destino do debugger;
+- `Play/Stop` continua fazendo attach/connect/disconnect under the hood nesta wave, sem expor ainda uma superficie rica de comandos manuais;
+- o `core` de remote connection e politicas de debug do `../debugger` pode ser reaproveitado aqui;
+- profiler fica explicitamente fora do baseline inicial.
+
+Esse recorte tambem assume pragmatismo de wave 1:
+
+- o handshake com o runtime pode nascer a partir dos detalhes ja estabilizados no `../debugger`;
+- o sink de logs pode comecar como console/lista simples com origem visivel;
+- o `DebugWorkspace` precisa mostrar estado de sessao suficiente para o usuario entender se esta conectando, conectado ou falhou;
+- refinamentos de UX, estrutura de logs e comandos mais ricos podem vir depois.
+
 Isso nao obriga uma reescrita total imediata da logica do debugger.
 Obriga apenas que a UI e o bootstrap standalone parem de ser tratados como se fossem a fronteira certa de integracao.
 
@@ -119,9 +172,15 @@ Recommended direction: seguir com **Option C**.
 A agenda deve convergir para uma decisao com os seguintes fechamentos:
 
 1. `Debug` no Studio deve virar um workspace real, nao apenas launcher de app externo;
-2. o boundary correto de reaproveitamento esta em servicos/protocolo/estado do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
+2. o `../debugger` deve ser tratado como referencia filosofica e fonte seletiva de reaproveitamento, nao como base para copia 1:1;
-3. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
+3. a topologia desta wave deve ser migracao seletiva sem link tecnico entre os dois projetos;
-4. o destino do app standalone precisa ser explicitado: consumidor paralelo do mesmo core durante migracao, ou superficie secundaria apos a integracao;
+4. o boundary correto de reaproveitamento esta em servicos/protocolo/estado/politicas de remote connection do debugger, nao no bootstrap `Application`/`Stage` como unidade de integracao;
-5. o primeiro corte deve declarar se `profiler` entra junto com `debugger` ou fica explicitamente fatiado para depois.
+5. o workspace integrado deve obedecer ao contrato do Studio para lifecycle, event bus, theming e i18n;
+6. o primeiro corte deve ser focado em sink merged de logs de execucao/preparacao e sessao de debug remota consumida pelo workspace;
+7. `Play/Stop` deve continuar controlando under the hood o fluxo de connect/attach/disconnect nesta wave;
+8. `profiler` fica explicitamente fatiado para depois;
+9. o `../debugger` nao deve receber novas mudancas e sera deletado quando o Studio estiver maduro o suficiente para representa-lo;
+10. esta agenda deve permanecer estritamente compativel com `DEC-0020` e `DEC-0021`, sem avancar sinal sobre preparacao ou execucao;
+11. a primeira wave nao precisa ser perfeita: basta entregar handshake com o runtime, estado basico de sessao e sink de logs simples com origem visivel, deixando refinamentos para depois.
 
-Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace`.
+Next step suggestion: converter esta agenda em uma `decision` que feche o modelo de integracao, o boundary de ownership entre `studio` e `../debugger`, a topologia de dependencias entre repositorios e o escopo da primeira wave de `DebugWorkspace` como superficie nativa de logs/sessao de execucao remota.

discussion/workflow/agendas/AGD-0023-studio-play-stop-shipper-phase-1.md

@@ -0,0 +1,132 @@
+---
+id: AGD-0023
+ticket: studio-play-stop-cartridge-flow
+title: Play/Stop integration agenda for build/pack freshness-gated runtime preparation
+status: in_progress
+created: 2026-04-06
+resolved: 2026-04-06
+decision: DEC-0020
+tags: [studio, play-stop, build, pack, compiler, packer, manifest]
+---
+
+## Pain
+
+O botão `Play` do Studio hoje só alterna estado visual no shell.
+Ele ainda não aciona um fluxo operacional real para preparar um conjunto executável de artefatos em `build/`.
+
+Isso deixa o shell com uma affordance de execução sem pipeline correspondente e sem um contrato claro entre:
+
+- Studio shell,
+- compiler build,
+- compiler,
+- packer,
+- e a pasta `build/` do projeto.
+
+## Context
+
+Domain owner: `studio`.
+Subdomínios referenciados: `compiler`, `packer`, `runtime`.
+
+Já existe um `ShipperWorkspace` no Studio e ele hoje chama `BuilderPipelineService.INSTANCE.build(...)`, mas esse fluxo atual é apenas um scratch inicial.
+Na prática, hoje ele está compilando bytecode e não deve ser tratado como o contrato definitivo de preparação de runtime do produto.
+
+O objetivo desta agenda não é fechar um pipeline de shipping nem materializar um `cartridge/` separado.
+O escopo desta wave é estritamente o mínimo necessário para o botão `Play` conseguir preparar artefatos rodáveis em `build/`:
+
+1. compilar o PBX necessário;
+2. executar o packer necessário;
+3. manter ou regenerar os artefatos de `build/` conforme frescor;
+4. gerar `manifest.json` em `build/`.
+
+Essa agenda trata apenas da preparação dos artefatos em `build/`.
+A execução `runtime run cartridge` ou equivalente apontando para `build/` fica em agenda separada dentro da mesma discussion.
+
+## Open Questions
+
+- [x] O `Play` deve reutilizar exatamente o mesmo pipeline já acionado pelo `ShipperWorkspace`, ou deve haver um service/application layer dedicado para o shell chamar e o workspace apenas consumir?
+- Resposta proposta: `Play` não deve reaproveitar o scratch atual do `ShipperWorkspace`; ele deve orquestrar chamadas explícitas de `build` e `pack`, cada uma com sua própria política de frescor.
+- [x] Os artefatos rodáveis desta wave devem viver em `cartridge/` separado ou no próprio `build/`?
+- Resposta proposta: nesta wave o artifact root runnable deve ser `build/`; não há necessidade de materializar um `cartridge/` separado se o runtime pode consumir o mesmo contrato diretamente de `build/`.
+- [x] Quem decide se é necessário recompilar ou repackar quando o usuário aperta `Play`?
+- Resposta proposta: nesta wave, `Play` sempre chama `build` e `pack`; a política fina de drift/freshness fica explicitamente adiada para uma segunda etapa. Quando essa segunda etapa existir, cada domínio será owner de sua própria política de frescor.
+- [x] Onde deve viver o controle fino de frescor e drift para os artefatos produzidos?
+- Resposta proposta: quando a wave de drift existir, o controle fino viverá em arquivos dedicados por domínio sob `.studio/`, começando por `asset-workspace.json` e `editor-workspace.json`, separados do snapshot principal de restauração.
+- [x] O `manifest.json` runtime-facing deve ser derivado do `prometeu.json` do projeto com normalização adicional do Studio, ou copiado quase diretamente com apenas os campos estritamente runtime-facing?
+- Resposta proposta: o `manifest.json` deve ser sempre gerado de forma determinística em `build/`, a partir do build corrente e do owner metadata do projeto, sem cópia por conveniência.
+- [x] Como o shell distinguirá falha de build, falha de pack e falha de manifest para refletir estado útil no `Play/Stop`?
+- Resposta proposta: para o `Play`, basta distinguir `success` e `failed`; logs detalhados das operações devem acompanhar o resultado. `build` falhando bloqueia `pack`, e `manifest` só roda depois do sucesso do build/pack desta wave.
+
+## Options
+
+### Option A - `Play` sempre chama `build` e `pack`, e drift fica para uma wave posterior
+- **Approach:** Fazer o shell chamar explicitamente `build` e `pack` em toda execução de `Play`; nesta wave não há reuse por drift/freshness, apenas execução determinística com logs e geração final de `manifest.json`.
+- **Pro:** Destrava a integração do `Play` com o menor contrato correto, sem antecipar um sistema de freshness ainda não normatizado.
+- **Con:** Pode refazer trabalho desnecessário em execuções sucessivas até a wave de drift existir.
+- **Maintainability:** Boa, porque mantém o `Play` simples agora e deixa a otimização para uma agenda própria depois.
+
+### Option B - `Play` inspeciona artefatos existentes e decide por conta própria se pode seguir
+- **Approach:** O shell observa presença ou timestamps de artefatos em `build/` e tenta inferir se basta reutilizar o que já existe.
+- **Pro:** Menos modelagem inicial de metadata e contratos.
+- **Con:** Move para o shell uma inteligência que pertence aos domínios de compiler e packer, além de abrir espaço para reuse incorreto sob drift parcial do workspace.
+- **Maintainability:** Fraca, porque o `Play` vira owner implícito de políticas que não são dele.
+
+## Discussion
+
+O ponto central aqui não é apenas "rodar compile + packer".
+O problema real é separar claramente:
+
+- a orquestração do `Play`,
+- a responsabilidade de `build`,
+- a responsabilidade de `pack`,
+- e a futura política de frescor de cada artefato.
+
+Se o `Play` inferir por conta própria se precisa rebuildar ou repackar, o shell passa a absorver conhecimento que pertence a outros domínios.
+Isso cria uma fronteira errada: o shell deixa de ser apenas o caller de operações e passa a ser o árbitro de drift do projeto.
+
+Ao mesmo tempo, modelar agora um sistema fino de drift adicionaria complexidade antes da própria integração básica do `Play` existir.
+Por isso, esta agenda fecha a wave 1 com execução sempre explícita e adia a otimização de freshness para uma agenda própria.
+
+O contrato mais limpo é:
+
+1. `Play` pede `build`;
+2. `build` executa e retorna `success` ou `failed`, acompanhado de logs;
+3. `Play` pede `pack`;
+4. `pack` executa e retorna `success` ou `failed`, acompanhado de logs;
+5. `manifest.json` é sempre regenerado em `build/` a partir do build corrente e dos metadados do projeto;
+6. `Play` só verifica sucesso ou falha dessas operações antes de seguir para a execução.
+
+Os constraints já visíveis no repositório reforçam esse recorte:
+
+- o compiler atual escreve `build/program.pbx`;
+- o packer atual escreve `build/assets.pa` e companions de tooling, e o spec do packer afirma explicitamente que cartridge assembly não pertence ao domínio `packer`;
+- os projetos de teste já mostram `build/` contendo `program.pbx`, `assets.pa` e companions;
+- `ProjectLocalStudioSetup` já está carregado na `StudioProjectSession`, então o shell já possui o owner correto para coordenar preparation + future run sem precisar deduzir drift por presença oportunista de arquivo.
+
+Isso torna a fronteira recomendada mais concreta:
+
+1. `build/` é o artifact root runnable desta wave;
+2. compiler e packer continuam donos de seus artefatos dentro de `build/`;
+3. `Play` não usa presença de arquivo como regra de validade;
+4. drift e freshness ficam explicitamente fora do escopo desta wave e poderão viver em arquivos dedicados por domínio sob `.studio/`;
+5. o shell avança apenas quando `build`, `pack` e `manifest` reportarem sucesso.
+
+A recomendação inicial desta agenda é:
+
+1. fazer `Play` chamar explicitamente `build` e `pack`;
+2. manter `build` e `pack` como operações domain-owned com logs e resultado binário de sucesso/falha nesta wave;
+3. adiar o controle fino de drift/freshness para uma agenda própria posterior;
+4. promover `build/` como artifact root runnable desta wave;
+5. gerar `manifest.json` em `build/` sempre a partir do build corrente;
+6. tratar o resultado de cada operação como contrato explícito para o `Play`, sem heurística oportunista baseada apenas em presença de arquivo.
+
+## Resolution
+
+Próximo passo sugerido: fechar uma decision de `studio` que trave o fluxo de preparação do `Play/Stop` com estas amarras normativas já explícitas:
+
+1. `Play` é apenas o orquestrador de `build`, `pack` e `manifest`;
+2. nesta wave, `build` sempre executa quando chamado pelo `Play`;
+3. nesta wave, `pack` sempre executa quando chamado pelo `Play`, e só é chamado se `build` tiver sucesso;
+4. o artifact root runnable desta wave é `build/`, não `cartridge/`;
+5. `manifest.json` é sempre gerado deterministicamente em `build/`, a partir do build corrente, e não copiado por conveniência;
+6. freshness e drift ficam fora do escopo desta wave e, quando tratados, usarão arquivos dedicados por domínio sob `.studio/`, como `asset-workspace.json` e `editor-workspace.json`;
+7. `Play` só segue adiante quando as operações necessárias reportarem sucesso.

discussion/workflow/agendas/AGD-0024-studio-play-stop-runtime-run-cartridge.md

@@ -0,0 +1,128 @@
+---
+id: AGD-0024
+ticket: studio-play-stop-cartridge-flow
+title: Play/Stop integration agenda for runtime execution from build using project runtime setup
+status: in_progress
+created: 2026-04-06
+resolved: 2026-04-06
+decision: DEC-0021
+tags: [studio, runtime, play-stop, build, process, project-setup]
+---
+
+## Pain
+
+Mesmo depois que o Studio conseguir preparar `build/`, o botão `Play` continuará incompleto sem um contrato claro para executar o runtime configurado no projeto contra esse artifact root.
+
+Hoje o caminho do runtime já existe em `.studio/setup.json` via `ProjectLocalStudioSetup.prometeuRuntimePath`, mas esse valor ainda não participa de nenhuma execução real no shell.
+
+Sem essa definição, o `Play/Stop` corre o risco de virar:
+
+- um botão que prepara `build/` mas não executa nada;
+- ou um launcher improvisado, sem owner claro para processo, logs, lifecycle e falhas.
+
+## Context
+
+Domain owner: `studio`.
+Subdomínios referenciados: `runtime`.
+
+O Studio já carrega `ProjectLocalStudioSetup` na `StudioProjectSession`.
+Portanto o runtime configurado por projeto já está disponível para consumo em runtime de aplicação.
+
+Após a decisão `DEC-0020`, esta agenda passa a assumir explicitamente que:
+
+- `Play` prepara `build/` como artifact root runnable;
+- `manifest.json` é gerado em `build/`;
+- não há `cartridge/` separado nesta wave.
+
+O comando desejado pelo usuário é conceitualmente:
+
+`runtime run build`
+
+usando o runtime configurado no projeto atual.
+
+Esta agenda não rediscute preparação de `build/`.
+Ela assume a saída de `DEC-0020` como pré-condição e foca no segundo passo do `Play`: iniciar, observar e interromper o processo de runtime.
+
+Também há um constraint de UX desta wave:
+
+- ao apertar `Play`, o usuário deverá ser levado para o futuro `DebuggerWorkspace`, mesmo que essa surface ainda não esteja construída;
+- até essa surface existir, os logs do runtime precisarão "ficar voando", isto é, viver provisoriamente fora do destino final pretendido;
+- a etapa de `pack` usada por `Play` deve preservar seu ciclo de validação antes da execução do runtime;
+- os logs de `build` e `pack` também devem convergir para o destino do debugger, porque é nessa surface que o usuário verá falhas de compilação, validação ou packing durante o fluxo do `Play`.
+
+Também há um constraint de escopo nesta wave:
+
+- checks adicionais de preflight antes do `build`, como arquivos do editor ainda não salvos, não entram agora;
+- quando essa wave futura existir, ela deverá bloquear o `Play` antes do `build` com erro explícito, em vez de ser tratada como detalhe implícito de runtime.
+
+## Open Questions
+
+- [x] O `Play` deve falhar imediatamente quando `prometeuRuntimePath` estiver ausente, ou o shell deve oferecer algum repair path explícito antes de abortar?
+- Resposta proposta: nesta wave, o `Play` deve falhar imediatamente com erro explícito quando `prometeuRuntimePath` estiver ausente, inválido, inexistente ou não executável; repair path guiado fica para uma wave posterior.
+- [x] O Studio deve executar o runtime diretamente pelo binário configurado, ou por um wrapper/comando fixo resolvido a partir desse path?
+- Resposta proposta: o Studio deve executar como processo externo o binário configurado em `ProjectLocalStudioSetup.prometeuRuntimePath`, apontando para `build/` e usando o subcomando `run` nesta wave; uma futura wave de debugger poderá trocar esse subcomando para `debug`.
+- [x] O `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo shell atual, ou também limpar algum estado transitório adicional no Studio?
+- Resposta proposta: `Stop` deve encerrar apenas o processo de runtime ativo iniciado pelo `Play` atual; não deve limpar estado transitório adicional além do lifecycle desse processo.
+- [x] Onde os logs de stdout/stderr do runtime devem viver nesta primeira wave: activity feed, shipper logs, uma surface dedicada, ou combinação mínima dessas superfícies?
+- Resposta proposta: o destino final dos logs deve ser o futuro `DebuggerWorkspace`, e o `Play` deve navegar para essa surface ao iniciar a execução; até ela existir, stdout/stderr e também os logs de `build`/`pack` ficam provisoriamente em uma solução transitória desacoplada, enquanto o Activity Feed recebe apenas eventos resumidos de início, sucesso de término e falha.
+- [x] Como o shell deve serializar múltiplos cliques em `Play`: ignorar enquanto já está rodando, reiniciar, ou encadear stop + rerun?
+- Resposta proposta: enquanto já houver runtime ativo iniciado pelo shell atual, cliques adicionais em `Play` devem ser ignorados até o processo sair ou o usuário apertar `Stop`.
+- [x] O `pack` usado pelo `Play` pode empacotar diretamente, ou deve preservar o ciclo de validação antes da execução do runtime?
+- Resposta proposta: o `pack` usado pelo `Play` deve preservar seu ciclo de validação antes da execução; se a validação bloquear o pack, o runtime não deve iniciar.
+- [x] Checks extras antes do `build`, como arquivos não salvos no editor, entram nesta wave?
+- Resposta proposta: não; preflight adicional de `build`, incluindo arquivos ainda não salvos, fica explicitamente para uma wave posterior e não altera o contrato desta agenda.
+- [x] A execução da agenda 24 deve validar explicitamente a existência de `build/manifest.json` antes do spawn, ou isso fica implícito pelo sucesso da preparação?
+- Resposta proposta: isso fica implícito pelo sucesso da preparação definida em `DEC-0020`; a agenda 24 não adiciona check redundante de existência de `manifest.json` antes do spawn.
+
+## Options
+
+### Option A - Play/Stop controla um processo único de runtime do projeto ativo
+- **Approach:** O shell resolve o runtime configurado no `ProjectLocalStudioSetup`, executa diretamente o binário configurado contra `build/` como processo do projeto ativo, mantém handle desse processo e usa `Stop` para encerrar exatamente esse processo.
+- **Pro:** O comportamento do botão fica simples, previsível e diretamente alinhado ao modelo visual de toggle.
+- **Con:** Exige que o Studio introduza ownership explícito de processo, logs e cleanup, em vez de só alternar estado visual.
+- **Maintainability:** Boa, porque o shell passa a ter um contrato único de execução por projeto e um lifecycle claro.
+
+### Option B - Play delega a execução ao workspace ou a um launcher externo sem handle direto no shell
+- **Approach:** O shell apenas dispara uma ação indireta e considera-se "running" sem possuir o processo como first-class state próprio.
+- **Pro:** Menor acoplamento inicial entre shell e camada de processo.
+- **Con:** O `Stop` fica semanticamente fraco ou enganoso, porque o shell não controla de verdade o processo que diz estar executando.
+- **Maintainability:** Fraca, porque o toggle visual deixa de corresponder ao lifecycle real da execução.
+
+## Discussion
+
+O ponto mais importante desta agenda é alinhar o significado de `Stop`.
+Se o shell não possui o processo de runtime como state explícito, o botão vira só uma fantasia visual.
+
+Como o runtime path já é project-local setup carregado na sessão, o Studio já tem o owner certo para resolver o binário configurado.
+O que falta é explicitar o contrato operacional:
+
+1. validar que o runtime configurado existe e é executável;
+2. executar `build`;
+3. executar a validação de `pack`;
+4. executar `pack` somente quando a validação permitir;
+5. enviar os logs de `build` e `pack` para a surface de debugger/logs da execução;
+6. rodar como processo externo o runtime configurado contra `build/` no contexto do projeto ativo, usando `run` nesta wave;
+7. capturar stdout/stderr;
+8. refletir running/stopped/failure no shell;
+9. interromper o processo correto quando o usuário apertar `Stop`.
+
+A execução do runtime nesta agenda confia no contrato de preparação anterior.
+Portanto, esta wave não introduz preflight redundante para verificar novamente a existência de `build/manifest.json` antes do spawn.
+
+A recomendação inicial desta agenda é:
+
+1. fazer o shell ser owner de um único runtime-process handle por projeto ativo;
+2. resolver o comando a partir de `ProjectLocalStudioSetup.prometeuRuntimePath`;
+3. falhar de forma explícita quando o runtime do projeto estiver ausente ou inválido;
+4. definir `Stop` como término do processo iniciado pelo `Play` atual, e não como reset genérico de UI;
+5. ignorar novo `Play` enquanto o processo atual ainda estiver rodando;
+6. preservar a validação de pack antes do pack efetivo na preparação do `Play`;
+7. tratar o futuro `DebuggerWorkspace` como destino canônico da execução e dos logs de runtime, `build` e `pack`;
+8. enquanto o `DebuggerWorkspace` não existir, manter stdout/stderr e logs de preparação em uma solução transitória, usando o Activity Feed apenas para sinais resumidos de lifecycle;
+9. deixar checks extras de preflight antes do `build`, como arquivos não salvos, fora desta wave;
+10. fixar `run` como o subcomando de execução desta wave, deixando `debug` para uma futura wave de debugger;
+11. confiar no sucesso da preparação anterior sem adicionar preflight redundante de `manifest.json` antes do spawn.
+
+## Resolution
+
+Próximo passo sugerido: fechar uma decision de `studio` que defina ownership de processo para `Play/Stop`, preserve o ciclo de validação + pack antes da execução do runtime, fixe a execução como processo externo do runtime configurado usando `run` contra `build/`, trate o `DebuggerWorkspace` como destino futuro da sessão de execução e explicite que checks extras de preflight do `build` ficam para uma wave posterior.

discussion/workflow/decisions/DEC-0020-studio-play-stop-build-pack-preparation.md

@@ -0,0 +1,147 @@
+---
+id: DEC-0020
+ticket: studio-play-stop-cartridge-flow
+title: Decision for Play/Stop build and pack preparation through build-owned artifacts
+status: accepted
+created: 2026-04-06
+accepted: 2026-04-06
+agenda: AGD-0023
+plans: [PLN-0041, PLN-0042, PLN-0045]
+tags: [studio, play-stop, build, pack, compiler, packer, manifest, shell]
+---
+
+## Decision
+
+Domain owner: `studio`.
+Referenced subdomains: `compiler`, `packer`, `runtime`.
+
+The Studio `Play` flow for this wave SHALL be implemented as an orchestration over existing domain operations, not as a separate shipping pipeline.
+
+The decision is:
+
+1. `Play` MUST call `build` first.
+2. `pack` MUST run only after `build` completes successfully.
+3. `Play` MUST treat `build/` as the runnable artifact root for this wave.
+4. `Play` MUST NOT materialize or depend on a separate `cartridge/` directory in this wave.
+5. `manifest.json` MUST be generated deterministically into `build/` from the current build result and project-owned metadata.
+6. `Play` MUST only need to evaluate whether each required operation succeeded or failed.
+7. Detailed operation logs MUST remain available alongside the operation results consumed by `Play`.
+8. The Studio shipper service MUST own preparation orchestration and preparation-log aggregation for this wave.
+9. Preparation logs MUST preserve at least the distinct channels `build`, `pack-validation`, and `pack`.
+10. Drift/freshness reuse logic is explicitly out of scope for this wave.
+11. A future drift/freshness wave MUST use domain-specific `.studio/` files rather than the main session-restoration snapshot.
+
+## Rationale
+
+This decision intentionally keeps the first executable `Play` wave narrow.
+
+The repository already shows:
+
+- compiler ownership of `build/program.pbx`,
+- packer ownership of `build/assets.pa` and companion build artifacts,
+- and no accepted requirement that a separate `cartridge/` assembly step must exist before runtime execution.
+
+Creating a new shipper/materialization layer now would add an extra boundary before the base `Play` integration exists.
+Likewise, pushing drift/freshness inference into `Play` would make the shell the owner of compiler and packer validity rules, which is the wrong boundary.
+
+This decision therefore chooses the smallest correct operational split:
+
+- `Play` orchestrates,
+- `shipper` owns preparation orchestration and preparation-log aggregation,
+- `build` produces compiler artifacts,
+- `pack` produces packer artifacts,
+- `manifest` is generated after successful preparation,
+- and runtime execution in the next wave may consume `build/` directly.
+
+## Technical Specification
+
+### 1. Orchestration Order
+
+The `Play` preparation path MUST execute in this order:
+
+1. `build`
+2. `pack` (only if `build` succeeded)
+3. `manifest` generation in `build/`
+4. handoff to the runtime-execution flow covered by a separate agenda/decision wave
+
+`Play` MUST stop immediately on the first failed required step.
+No cancellation of the preparation phase is defined in this wave.
+
+### 2. Artifact Root
+
+For this wave, `build/` is the canonical runnable artifact root.
+
+At minimum, the prepared runtime-facing output in `build/` SHALL include:
+
+- `program.pbx`
+- `assets.pa`
+- `manifest.json`
+
+Packer companion artifacts may remain in `build/` as domain-owned outputs.
+They do not redefine the minimum contract required by `Play`.
+
+### 3. Result Contract
+
+The result contract consumed by `Play` for this wave MUST be binary at the control-flow level:
+
+- `success`
+- `failed`
+
+`Play` MUST NOT need to interpret finer-grained reuse or freshness states in this wave.
+Operational logs from `build`, `pack`, and manifest generation MUST remain available so the shell can surface useful diagnostics without owning domain-specific decision logic.
+For this wave, those preparation logs are owned and aggregated by the Studio shipper service.
+
+### 4. Manifest Generation
+
+`manifest.json` MUST NOT be copied opportunistically from an older location.
+
+Instead, it MUST be generated on every successful preparation run:
+
+- in `build/`,
+- from the current build result,
+- and from project-owned metadata required by the runtime-facing manifest contract.
+
+### 5. Drift and Freshness Deferral
+
+This decision does not authorize a freshness-based skip path yet.
+
+Rules:
+
+- `Play` MUST NOT infer artifact validity from file presence alone.
+- This wave MAY always execute `build` and `pack` when `Play` is pressed.
+- If a later wave introduces drift/freshness control, that logic MUST be discussed separately before implementation.
+- That later wave MUST keep operational metadata in dedicated domain files under `.studio/`, with the agreed initial direction being `asset-workspace.json` and `editor-workspace.json`.
+- That later wave MUST NOT mix such metadata into `.studio/state.json` by convenience.
+
+### 6. Boundary With Existing Workspaces
+
+The current `ShipperWorkspace` scratch implementation does not become the normative backend for `Play` by inertia.
+
+This decision does not require:
+
+- a new shipping module,
+- a separate cartridge-materialization directory,
+- or Play-owned drift heuristics.
+
+Existing workspaces may remain useful as manual or diagnostic surfaces, but they MUST NOT redefine the `Play` preparation contract established here.
+
+### 7. Preparation Logging Boundary
+
+For this wave, preparation logging MUST follow these rules:
+
+- build and pack remain owners of their own log production;
+- the Studio shipper service aggregates preparation output for user-facing consumption;
+- the aggregated preparation stream MUST preserve distinct source channels for `build`, `pack-validation`, and `pack`;
+- downstream debugger/execution surfaces consume that aggregated preparation output rather than redefining preparation ownership.
+
+## Constraints
+
+1. This decision covers preparation only, not runtime process ownership or `Stop` behavior.
+2. This decision does not yet define the exact manifest field mapping beyond deterministic generation from current build inputs and project metadata.
+3. This decision does not yet define a drift fingerprint model.
+4. Any later attempt to skip `build` or `pack` based on freshness requires a new discussion wave or explicit revision of this decision.
+5. Any later reintroduction of `cartridge/` as a mandatory runtime root requires a new decision or explicit revision of this one.
+
+## Revision Log
+
+- 2026-04-06: Initial draft from AGD-0023.

discussion/workflow/decisions/DEC-0021-studio-play-stop-runtime-run-from-build.md

@@ -0,0 +1,174 @@
+---
+id: DEC-0021
+ticket: studio-play-stop-cartridge-flow
+title: Decision for Play/Stop runtime execution from build through external run process
+status: accepted
+created: 2026-04-06
+accepted: 2026-04-06
+agenda: AGD-0024
+plans: [PLN-0042, PLN-0044, PLN-0045]
+tags: [studio, runtime, play-stop, build, process, debugger, project-setup, logs]
+---
+
+## Decision
+
+Domain owner: `studio`.
+Referenced subdomains: `runtime`.
+
+This decision defines the runtime-execution contract that follows the preparation contract already described in `DEC-0020`.
+
+The decision is:
+
+1. `Play` MUST execute the configured runtime as an external process.
+2. The runtime executable path MUST come from `ProjectLocalStudioSetup.prometeuRuntimePath`.
+3. The external command for this wave MUST be exactly `"<runtimePath>" run build`.
+4. The process MUST run with the project root as its current working directory.
+5. `Play` MUST rely on the successful completion of the preparation pipeline and MUST NOT add a redundant manifest-existence preflight in this wave.
+6. `Play` MUST fail explicitly when the configured runtime path is missing, invalid, nonexistent, non-executable, or cannot be spawned.
+7. `Play` MUST own exactly one active runtime-process handle for the current project shell.
+8. While that process is active, additional `Play` actions MUST be ignored.
+9. `Stop` in this wave MUST kill the active runtime process directly.
+10. The future `DebuggerWorkspace` SHALL be the canonical destination of execution and logs.
+11. Until that workspace exists, runtime logs and shipper-provided preparation logs MUST flow to a temporary surface, while the Activity Feed only receives summarized lifecycle events.
+12. The shipper service remains the owner of preparation orchestration and aggregated preparation output.
+13. The `pack` step used by `Play` MUST preserve validation before packing, and runtime execution MUST NOT start if validation blocks the pack.
+14. Additional pre-build editor preflight checks, including unsaved-file detection, are explicitly deferred to a future wave.
+15. No cancellation of the preparation phase is supported in this wave.
+16. The future debugger wave MAY replace `run` with `debug`, but that is not authorized by this decision.
+
+## Rationale
+
+`Play/Stop` only becomes semantically real if the shell owns the runtime process it claims to start and stop.
+
+After `DEC-0020`, the runnable artifact root for this wave is `build/`, and the preparation flow already owns generation of `manifest.json`.
+This means the runtime-execution wave does not need another packaging boundary and does not need redundant manifest-existence checks before spawn.
+
+The narrowest correct contract is therefore:
+
+- prepare through `build -> validate pack -> pack -> manifest`,
+- treat shipper as the owner of preparation output and aggregated preparation logs,
+- spawn the configured runtime externally with `run build`,
+- keep a single process handle,
+- and surface logs in the future debugger destination.
+
+This keeps responsibility boundaries clear:
+
+- preparation remains owned by the earlier preparation decision,
+- runtime-process ownership belongs to the shell,
+- and future debugger behavior remains a later wave rather than being guessed now.
+
+## Technical Specification
+
+### 1. Runtime Command
+
+For this wave, the Studio shell MUST construct and execute the runtime command as:
+
+`"<runtimePath>" run build`
+
+Rules:
+
+- `runtimePath` MUST be read from `ProjectLocalStudioSetup.prometeuRuntimePath`;
+- the process MUST execute with `cwd` equal to the project root;
+- no wrapper command is introduced in this wave;
+- no `debug` subcommand is introduced in this wave.
+
+### 2. Execution Order
+
+`Play` preparation and execution MUST follow this order:
+
+1. `build`
+2. `pack` validation
+3. `pack` only if validation allows it
+4. runtime spawn with `run build`
+
+The shell MUST stop on first failure.
+If `build` fails, no pack validation, pack, or runtime spawn occurs.
+If pack validation blocks, no pack or runtime spawn occurs.
+If pack fails, runtime spawn does not occur.
+If preparation fails, no cancellation path is offered in this wave; the flow simply terminates in failure.
+
+### 3. Preparation Contract Reliance
+
+This decision depends on `DEC-0020`.
+
+Rules:
+
+- the shell MUST rely on the success of the earlier preparation pipeline;
+- the shell MUST NOT add a redundant check for `build/manifest.json` existence before spawn in this wave;
+- a missing manifest after successful preparation is a violation of the earlier preparation contract, not a new runtime-execution rule.
+
+### 4. Runtime Preflight
+
+Before spawning the external process, the shell MUST treat the following conditions as explicit preflight failures:
+
+- missing `prometeuRuntimePath`,
+- blank `prometeuRuntimePath`,
+- nonexistent runtime path,
+- non-executable runtime path,
+- spawn failure.
+
+This wave does not yet define a broader runtime repair flow.
+
+### 5. Process Ownership and Stop Semantics
+
+The shell MUST own exactly one active runtime-process handle per active project shell.
+
+Rules:
+
+- `Play` while the process is active MUST be ignored;
+- `Stop` MUST target only the process started by the current `Play` flow;
+- `Stop` in this wave MUST kill that process directly;
+- `Stop` has no effect during `preparing` because preparation cancellation is not defined in this wave;
+- graceful debugger-oriented stop commands are deferred to a future debugger wave.
+
+### 6. Logging and Debugger Destination
+
+The canonical destination for execution-session logs SHALL be the future `DebuggerWorkspace`.
+
+For this wave:
+
+- the shell MUST navigate toward that execution destination when `Play` starts, before runtime spawn is attempted;
+- logs from `build`, pack validation, `pack`, and runtime stdout/stderr MUST converge on that execution-log destination;
+- preparation logs arrive there through shipper-owned aggregated output;
+- until the `DebuggerWorkspace` exists, those logs MUST use a temporary/transitional surface;
+- the Activity Feed MUST remain a summary surface and MUST NOT become the primary full-log destination.
+
+### 7. Shared Session State
+
+The Studio shell and debugger destination require shared execution state that exists independently of the visual lifecycle of the workspace.
+
+For this wave, the minimum state machine SHALL distinguish at least:
+
+- `idle`
+- `preparing`
+- `prepare_failed`
+- `connecting`
+- `running`
+- `runtime_failed`
+- `stopped`
+
+This state is not owned solely by the visual workspace.
+
+### 8. Deferred Checks
+
+This decision explicitly defers:
+
+- unsaved-editor-file checks before `build`,
+- broader build preflight policy,
+- graceful runtime stop commands,
+- debugger-specific execution semantics,
+- and any redundant manifest-presence preflight beyond the contract already owned by `DEC-0020`.
+
+When introduced later, those concerns MUST be handled in a separate discussion wave or explicit revision.
+
+## Constraints
+
+1. This decision covers external runtime execution through `run`, not debugger execution through `debug`.
+2. This decision assumes the preparation contract of `DEC-0020` without reopening it.
+3. This decision does not yet define the concrete temporary UI surface that will host execution logs before the `DebuggerWorkspace` exists.
+4. This decision does not yet define richer exit-code UX beyond success/failure lifecycle handling.
+5. This decision does not yet define restart semantics beyond ignoring repeated `Play` while active.
+
+## Revision Log
+
+- 2026-04-06: Initial draft from AGD-0024.

discussion/workflow/decisions/DEC-0022-studio-debug-workspace-native-integration.md

@@ -0,0 +1,203 @@
+---
+id: DEC-0022
+ticket: studio-debugger-workspace-integration
+title: Decision for native Studio DebugWorkspace integration with selective debugger migration
+status: accepted
+created: 2026-04-06
+accepted: 2026-04-06
+agenda: AGD-0009
+plans: [PLN-0042, PLN-0043, PLN-0044, PLN-0045]
+tags: [studio, debugger, workspace, integration, logs, runtime, play-stop]
+---
+
+## Decision
+
+Domain owner: `studio`.
+Cross-domain reference: sibling repo `../debugger`.
+Normative upstream dependencies: `DEC-0020`, `DEC-0021`.
+
+This decision defines the first integration wave of `DebugWorkspace` inside Studio.
+
+The decision is:
+
+1. `Debug` in Studio MUST become a real native workspace, not an external launcher.
+2. This integration MUST remain compatible with `DEC-0020` and `DEC-0021` and MUST NOT reinterpret preparation or execution contracts by inference.
+3. The first wave of `DebugWorkspace` MUST focus on two capabilities only:
+   - runtime/debug-session handshake sufficient for the current `Play/Stop` flow,
+   - and merged execution-log sinking for preparation and runtime.
+4. The first wave does NOT need to be perfect. A simple but functional session state and log sink is sufficient.
+5. The `../debugger` repository MUST be treated as architectural reference and selective source of useful details, not as a dependency to be linked or a codebase to be copied wholesale.
+6. Studio MUST NOT create a technical linkage between the two projects for this wave.
+7. Copying code from `../debugger` MUST be avoided by default, but MAY be done selectively when concretely useful.
+8. The correct integration boundary is in useful session/protocol/remote-debug policy details, not in `Application`/`Stage` bootstrap or standalone UI hosting.
+9. `Play/Stop` MUST continue owning connect/attach/disconnect behavior under the hood in this wave.
+10. `DebugWorkspace` MUST consume shipper-provided aggregated preparation logs and runtime logs through a shared session/service boundary.
+11. `DebugWorkspace` MUST be the destination for merged logs from `build`, pack validation, `pack`, and runtime execution.
+12. Build and pack remain owners of their own logs, but the user-facing execution surface MUST show those logs merged in the debugger destination.
+13. The global Activity Feed MUST remain a summary surface rather than the primary raw-log destination.
+14. The first wave MUST exclude profiler-specific behavior.
+15. The standalone `../debugger` MUST NOT be evolved as part of this Studio integration and is expected to be removed once Studio becomes mature enough to replace it.
+
+## Rationale
+
+Recent `Play/Stop` decisions made `DebugWorkspace` no longer speculative.
+
+`DEC-0021` already establishes that:
+
+- `Play` navigates toward the future debugger destination,
+- build, pack-validation, pack, and runtime logs converge there,
+- and `Play/Stop` owns the current run-process contract.
+
+That means the immediate job of agenda 9 is not to design the final debugger product.
+Its immediate job is to provide the native Studio surface that can host:
+
+- session state,
+- handshake with the runtime,
+- and a merged sink for execution-related logs.
+
+The existing `../debugger` still matters, but mostly as a source of tested ideas and useful protocol/session details.
+Treating it as a live dependency would be the wrong topological move because:
+
+- the Studio is intended to become the durable host,
+- the sibling debugger will be removed later,
+- and hard-linking the repositories now would increase migration cost for little value.
+
+The narrowest correct answer is therefore:
+
+- native `DebugWorkspace` in Studio,
+- selective migration only,
+- no direct project linkage,
+- a shared session/service boundary outside the visual workspace,
+- no profiler in the first cut,
+- and enough runtime handshake + log sinking to support the already-decided `Play/Stop` flow.
+
+## Technical Specification
+
+### 1. Upstream Contract Boundaries
+
+This decision is downstream of `DEC-0020` and `DEC-0021`.
+
+Rules:
+
+- `DEC-0020` remains authoritative for preparation through `build -> validate pack -> pack -> manifest`;
+- `DEC-0021` remains authoritative for runtime execution through external `"<runtimePath>" run build` and current `Play/Stop` process ownership;
+- this decision MUST NOT redefine those flows;
+- any attempt to change preparation or execution semantics requires explicit revision of the upstream decisions rather than reinterpretation here.
+
+### 2. First-Wave Scope
+
+The first-wave `DebugWorkspace` MUST provide:
+
+- a native Studio workspace surface,
+- basic debug/run session state,
+- handshake behavior with the runtime sufficient for the current flow,
+- and a merged log sink for execution-related activity.
+
+The first wave MAY be visually simple.
+It does not need polished debugger UX yet.
+
+### 3. Session and Handshake
+
+The workspace MUST expose enough session state to show at least:
+
+- connecting,
+- connected,
+- failed,
+- and equivalent stopped/disconnected state as needed by the current flow.
+
+Handshake details MAY be derived from `../debugger` where useful, but MUST be integrated into Studio-native session/workspace boundaries.
+
+For this wave:
+
+- `Play/Stop` remains the owner of under-the-hood connect/attach/disconnect behavior;
+- `DebugWorkspace` is the native surface that reflects and hosts that session;
+- the underlying session state MUST exist outside the visual workspace lifecycle so the Studio shell can react to it globally.
+
+### 4. Logging
+
+The `DebugWorkspace` MUST be the merged sink destination for:
+
+- `build` logs,
+- pack-validation logs,
+- `pack` logs,
+- runtime stdout/stderr.
+
+Rules:
+
+- build and pack keep ownership of their own log production;
+- shipper owns the aggregation of preparation logs for user-facing consumption;
+- the debugger destination consumes merged preparation output plus runtime logs;
+- the initial merged sink MAY be a simple console/list with visible source/origin labels;
+- source/origin labels MUST preserve at least `build`, `pack-validation`, `pack`, and `runtime`;
+- the merged sink does not need sophisticated structure in the first wave;
+- the Activity Feed MUST only carry summarized lifecycle signals.
+
+### 5. Shared Session State
+
+The first-wave debugger integration MUST consume a shared session/service boundary that is not owned solely by the visual workspace.
+
+At minimum, that shared state MUST distinguish:
+
+- `idle`
+- `preparing`
+- `prepare_failed`
+- `connecting`
+- `running`
+- `runtime_failed`
+- `stopped`
+
+The `DebugWorkspace` consumes and reflects this state.
+
+### 6. Integration Topology
+
+The integration topology for this wave MUST be selective migration into Studio.
+
+Rules:
+
+- no composite build or equivalent live technical linkage with `../debugger`;
+- no requirement to keep the standalone debugger as a parallel supported surface;
+- no wholesale copy by inertia;
+- selective code migration is allowed when concretely useful.
+
+The intended direction is:
+
+- Studio becomes the durable host,
+- `../debugger` is not extended further for this effort,
+- and the sibling project may be removed once Studio matures enough.
+
+### 7. Native Studio Shape
+
+`DebugWorkspace` MUST obey native Studio workspace rules for:
+
+- lifecycle,
+- event-bus integration,
+- theming,
+- i18n,
+- navigation under the Studio shell.
+
+This decision does not authorize embedding the standalone debugger bootstrap as the main integration unit.
+
+### 8. Explicit Exclusions
+
+This decision does not yet define:
+
+- profiler integration,
+- polished final debugger UX,
+- a rich manual connect/disconnect control surface,
+- a final structured logging model,
+- cancellation of preparation,
+- or any change from `run` to `debug` in the runtime command path.
+
+Those concerns remain future waves.
+
+## Constraints
+
+1. This decision is subordinate to `DEC-0020` and `DEC-0021`.
+2. This decision defines the first wave of `DebugWorkspace`, not the complete debugger product.
+3. This decision assumes selective use of `../debugger` knowledge/details without creating a permanent dependency.
+4. This decision does not authorize profiler behavior.
+5. This decision does not authorize changing current `Play/Stop` ownership semantics.
+
+## Revision Log
+
+- 2026-04-06: Initial draft from AGD-0009.

discussion/workflow/plans/PLN-0041-shipper-preparation-foundation.md

@@ -0,0 +1,96 @@
+---
+id: PLN-0041
+ticket: studio-play-stop-cartridge-flow
+title: Ordered Plan 1 - Shipper preparation foundation for build, pack, and manifest
+status: review
+created: 2026-04-06
+completed:
+tags: [studio, play-stop, shipper, build, pack, manifest]
+---
+
+## Objective
+
+Implement the Studio shipper service as the owner of preparation orchestration for `build -> pack-validation -> pack -> manifest`, with deterministic output in `build/`.
+
+## Background
+
+`DEC-0020` establishes that preparation is Studio-owned, that `build/` is the runnable artifact root, and that shipper owns preparation orchestration plus aggregation of preparation logs.
+
+This is the first and foundational plan in the family. Later plans depend on its service boundary and result contracts.
+
+## Scope
+
+### Included
+- Introduce or reshape a Studio-owned shipper service boundary.
+- Execute `build`, pack validation, `pack`, and manifest generation in the required order.
+- Produce deterministic preparation results and failure boundaries.
+- Preserve preparation log channels `build`, `pack-validation`, and `pack`.
+
+### Excluded
+- External runtime spawning.
+- Debugger workspace UI.
+- Runtime handshake.
+- Drift/freshness reuse logic.
+
+## Execution Steps
+
+### Step 1 - Define the shipper service contract
+
+**What:** Add a Studio-owned service/API for preparation that exposes ordered preparation, result status, and preparation-log output.
+**How:** Introduce dedicated types for preparation request/result and channel-aware preparation log entries. Keep the service independent from UI controls and workspaces.
+**File(s):** `prometeu-studio/src/main/java/p/studio/.../shipper/*` (new package), existing `ShipperWorkspace` call sites as adapters only.
+
+### Step 2 - Implement ordered preparation
+
+**What:** Execute compiler build, pack validation, pack, and manifest generation through the shipper service.
+**How:** Reuse existing compiler and packer entrypoints. Enforce stop-on-first-failure. Do not introduce cancellation. Ensure pack validation blocks pack when needed.
+**File(s):** `prometeu-studio` service layer, packer integration call sites, manifest generation implementation.
+
+### Step 3 - Materialize the deterministic build contract
+
+**What:** Ensure successful preparation leaves `build/program.pbx`, `build/assets.pa`, and `build/manifest.json` in the expected state.
+**How:** Keep compiler and packer domain ownership of their artifacts, but make manifest generation part of shipper success. Preserve the absence of a separate `cartridge/` root.
+**File(s):** shipper implementation, manifest-generation code, any preparation DTOs/results.
+
+### Step 4 - Publish channel-preserving preparation output
+
+**What:** Aggregate preparation output for downstream consumption while preserving per-channel identity.
+**How:** Build a merged-but-structured stream that labels entries as `build`, `pack-validation`, or `pack`. Expose it as shipper-owned output rather than UI-owned state.
+**File(s):** shipper service/result/log types, adapters from compiler and packer logs.
+
+## Test Requirements
+
+### Unit Tests
+- Verify shipper enforces the exact order `build -> pack-validation -> pack -> manifest`.
+- Verify pack validation failure stops the flow before pack.
+- Verify manifest generation only happens after successful build and pack.
+- Verify aggregated preparation logs preserve the three required source channels.
+
+### Integration Tests
+- Exercise a successful preparation flow against a real project fixture and assert expected files exist in `build/`.
+- Exercise build failure and assert pack and manifest are skipped.
+- Exercise pack-validation failure and assert pack and manifest are skipped.
+
+### Manual Verification
+- Trigger shipper preparation on a real Studio project and confirm `build/` contains the expected artifacts.
+- Inspect emitted preparation logs and confirm channel labels remain visible.
+
+## Acceptance Criteria
+
+- [ ] A Studio-owned shipper service exists and is the sole owner of preparation orchestration.
+- [ ] Preparation executes in the exact decision-ordered sequence.
+- [ ] Preparation stops on first failure and does not support cancellation in this wave.
+- [ ] Successful preparation leaves the required runnable files in `build/`.
+- [ ] Preparation output preserves `build`, `pack-validation`, and `pack` channel identity.
+
+## Dependencies
+
+- Accepted `DEC-0020`.
+- Existing compiler `build` entrypoint.
+- Existing packer validation and pack entrypoints.
+
+## Risks
+
+- Hidden coupling to the current `ShipperWorkspace` scratch path may leak UI assumptions into the service boundary.
+- Manifest generation may become entangled with runtime policy if not kept narrow.
+- Log aggregation may collapse source identity if implemented as raw text concatenation.

discussion/workflow/plans/PLN-0042-shared-execution-session-and-log-contracts.md

@@ -0,0 +1,91 @@
+---
+id: PLN-0042
+ticket: studio-play-stop-cartridge-flow
+title: Ordered Plan 2 - Shared execution session and merged log contracts
+status: review
+created: 2026-04-06
+completed:
+tags: [studio, play-stop, debugger, session, logs, state]
+---
+
+## Objective
+
+Define and implement the shared execution-session boundary that exists outside visual workspace lifecycle and carries state plus merged log contracts for preparation and runtime.
+
+## Background
+
+`DEC-0021` and `DEC-0022` require a shared state machine and a merged log destination independent of the visual `DebugWorkspace`. `DEC-0020` requires shipper-owned preparation log aggregation.
+
+This plan is intentionally cross-cutting and must land before the final orchestration and workspace consumption plans.
+
+## Scope
+
+### Included
+- Shared session/service boundary outside the visual workspace.
+- Minimum shared state machine: `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, `stopped`.
+- Structured merged log-entry contract with visible source identity.
+- Adapters for shipper-owned preparation output and runtime output to feed the shared session.
+
+### Excluded
+- Final debugger workspace UI.
+- Runtime process spawning details.
+- Full handshake implementation details.
+- Profiler behavior.
+
+## Execution Steps
+
+### Step 1 - Define shared state and session contracts
+
+**What:** Introduce shared types and services for execution-session state.
+**How:** Create a Studio-owned session/service API not tied to `Workspace` lifecycle. Add explicit transitions for the minimum required states.
+**File(s):** `prometeu-studio/src/main/java/p/studio/.../debug/*` or equivalent shared execution package.
+
+### Step 2 - Define merged log-entry contracts
+
+**What:** Add a structured log-entry model for merged execution logs.
+**How:** Require at least `source`, `message`, `severity`, and ordering metadata such as timestamp/sequence. Preserve the source channels `build`, `pack-validation`, `pack`, and `runtime`.
+**File(s):** shared execution/debug model package, service interfaces, DTOs/events.
+
+### Step 3 - Connect shipper output to the shared session
+
+**What:** Feed shipper-owned preparation output into the shared session boundary.
+**How:** Adapt the shipper result/log stream into session log entries and preparation state transitions without moving ownership away from shipper.
+**File(s):** shipper adapters, shared session service, orchestration glue.
+
+### Step 4 - Connect runtime output to the shared session
+
+**What:** Reserve the runtime side of the merged stream and state transitions for later orchestration plans.
+**How:** Define append/update APIs now so later runtime plans can publish `connecting`, `running`, `runtime_failed`, and `stopped` without changing the contract shape.
+**File(s):** shared session/service types and tests.
+
+## Test Requirements
+
+### Unit Tests
+- Verify legal state transitions for the minimum state machine.
+- Verify merged log entries preserve source identity and ordering metadata.
+- Verify shipper output can be appended without collapsing channels.
+
+### Integration Tests
+- Feed a simulated preparation success/failure sequence into the shared session and assert resulting state and log stream.
+- Verify the shared session survives workspace recreation or absence.
+
+### Manual Verification
+- Inspect a development build and confirm execution state remains available even if the visual debug surface is not yet mounted.
+
+## Acceptance Criteria
+
+- [ ] A shared execution-session service exists outside the visual workspace lifecycle.
+- [ ] The minimum state machine is explicitly implemented.
+- [ ] Merged log entries preserve source identity for `build`, `pack-validation`, `pack`, and `runtime`.
+- [ ] Shipper preparation output can flow into the shared session without changing shipper ownership.
+
+## Dependencies
+
+- Accepted `DEC-0020`, `DEC-0021`, and `DEC-0022`.
+- `PLN-0041` shipper preparation foundation.
+
+## Risks
+
+- State transitions may become duplicated between shell, workspace, and service if ownership is not kept strict.
+- Log models that are too thin will force churn once the debugger surface exists.
+- Overdesign here could slow down the simple first wave the decisions explicitly allow.

discussion/workflow/plans/PLN-0043-debug-workspace-first-wave-surface.md

@@ -0,0 +1,90 @@
+---
+id: PLN-0043
+ticket: studio-debugger-workspace-integration
+title: Ordered Plan 3 - First-wave DebugWorkspace registration and temporary execution surface
+status: review
+created: 2026-04-06
+completed:
+tags: [studio, debugger, workspace, logs, shell]
+---
+
+## Objective
+
+Register a native `DebugWorkspace` in Studio and provide a first-wave temporary execution surface that consumes shared session state and merged logs.
+
+## Background
+
+`DEC-0022` requires a real native workspace, not an external launcher. `DEC-0021` requires `Play` to navigate toward the debugger destination at the start of execution.
+
+This plan intentionally keeps the UI crude and execution-focused.
+
+## Scope
+
+### Included
+- Register a concrete `DebugWorkspace` in the Studio shell.
+- Consume the shared session/service boundary from `PLN-0042`.
+- Render simple session state and a simple merged log sink with visible source labels.
+- Provide a temporary but native in-Studio execution destination.
+
+### Excluded
+- Polished final debugger UX.
+- Rich manual connect/disconnect controls.
+- Profiler behavior.
+- Standalone debugger bootstrap embedding.
+
+## Execution Steps
+
+### Step 1 - Register the workspace in the shell
+
+**What:** Make `WorkspaceId.DEBUG` point to a real workspace implementation.
+**How:** Add and register a native `DebugWorkspace` that follows Studio workspace lifecycle and event-bus rules.
+**File(s):** `prometeu-studio/src/main/java/p/studio/window/MainView.java`, `prometeu-studio/src/main/java/p/studio/workspaces/.../DebugWorkspace.java` (new).
+
+### Step 2 - Add first-wave session state presentation
+
+**What:** Surface the shared session states in the workspace.
+**How:** Render a simple status area or equivalent control showing at least `idle`, `preparing`, `prepare_failed`, `connecting`, `running`, `runtime_failed`, and `stopped`.
+**File(s):** `DebugWorkspace` controls and supporting view models/bindings.
+
+### Step 3 - Add the temporary merged log sink
+
+**What:** Show merged execution logs in a simple native Studio surface.
+**How:** Use a list/console style control with visible source labels and lightweight severity treatment. Consume the shared session log stream from `PLN-0042`.
+**File(s):** `DebugWorkspace` controls, log pane/control package.
+
+### Step 4 - Preserve native Studio shape
+
+**What:** Keep lifecycle, theming, i18n, and shell-navigation compliance.
+**How:** Avoid importing the standalone debugger host/bootstrap. Use only Studio-native workspace composition.
+**File(s):** workspace implementation, i18n keys, theme/style files as needed.
+
+## Test Requirements
+
+### Unit Tests
+- Verify the workspace can consume session state updates and reflect them.
+- Verify merged log entries render with visible source identity.
+
+### Integration Tests
+- Mount the workspace in a shell test and confirm it registers without throwing.
+- Feed synthetic session/log events and confirm the workspace updates without owning the underlying state.
+
+### Manual Verification
+- Open the `Debug` workspace from the Studio shell.
+- Confirm session states and merged logs are visible in a simple but usable surface.
+
+## Acceptance Criteria
+
+- [ ] `WorkspaceId.DEBUG` resolves to a real native workspace.
+- [ ] The workspace shows shared execution state.
+- [ ] The workspace shows merged logs with visible source identity.
+- [ ] The implementation stays within native Studio workspace boundaries.
+
+## Dependencies
+
+- Accepted `DEC-0022`.
+- `PLN-0042` shared execution session and log contracts.
+
+## Risks
+
+- The first-wave UI may accidentally hardcode temporary choices that later feel permanent.
+- Workspace ownership may drift into session ownership if bindings are not kept one-way.

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

@@ -0,0 +1,80 @@
+---
+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.

discussion/workflow/plans/PLN-0045-play-stop-end-to-end-execution-flow.md

@@ -0,0 +1,108 @@
+---
+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.