feat(runtime): add workspace-aware run foundations

PENDING_LOG.md

@@ -1,5 +1,21 @@
 # PENDING_LOG
 
+## Triagem atual — evolução arquitetural incremental
+
+- Em 2026-03-20, a análise comparativa entre SynapseOS, Superset, Mastra e coding-agent foi consolidada como direção de produto e arquitetura para a próxima onda de evolução local.
+- A conclusão prática é que o SynapseOS não deve tentar reproduzir o produto Superset nem migrar o runtime central para TypeScript neste momento; o ganho líquido imediato está em absorver boundaries, contratos internos e padrões de extensibilidade de forma incremental sobre o core Python atual.
+- Em 2026-03-20, a onda local `F51` → `F53` foi executada sequencialmente:
+- `F51-runtime-boundaries-foundation` abriu contratos explícitos de `ToolSpec`/capabilities, `WorkspaceProvider`, `RunContext` e lifecycle hooks no Synapse-Flow.
+- `F52-workspace-isolation-foundation` tornou o workspace efetivo da run auditável com `workspace_path` persistido e provider `run-scoped` opcional.
+- `F53-observability-runtime-events` enriqueceu a timeline local com `run_context_initialized`, `step_started` e `state_transitioned`, além de refletir `workspace_path` em `runs show` e `RUN_REPORT.md`.
+- Com isso, a frente ativa imediata deixa de ser `F51` e passa a ser nenhuma: a próxima decisão de produto volta a ser escolher um novo bucket pequeno sobre baseline já ampliada.
+- A fila seguinte recomendada, em ordem, fica restrita por enquanto a quatro buckets pequenos e verificáveis:
+- `multi-agent-session-orchestration`: formalizar registry/capabilities e coordenação entre adapters sem abrir UI desktop.
+- `local-control-plane-foundation`: expor API local mínima para TUI/integrações futuras, mantendo CLI-first e shell desktop como hipótese posterior.
+- `baseline-handoff-sync`: alinhar `PENDING_LOG.md`, `ERROR_LOG.md`, README e artefatos de feature ao estado real pós-`F53`.
+- O bucket `desktop-shell` fica explicitamente fora da fila principal neste momento; ele só volta à mesa depois que `runtime boundaries`, `workspace isolation`, `observability` e `control plane` estiverem estabilizados.
+- O bucket `TypeScript-first runtime migration` fica explicitamente descartado por ora; qualquer uso futuro de TypeScript deve ficar limitado a shell/UI opcional consumindo um core Python autoritativo.
+
 ## Decisões incorporadas recentemente
 
 - Em 2026-03-13, `origin/main` absorveu a merge de `F42-tui-filters` pela PR `#86`, adicionando filtros visuais locais no dashboard TUI para falhas (`f`), atividade (`r`) e restauracao da lista completa (`x`).
@@ -174,8 +190,9 @@
 
 - Fixtures de testes aspiracionais marcadas como 🔜 no TDD.md: `tests/fixtures/worker/` (ainda ausente).
 - Property-based testing com `hypothesis` ainda não implementado (mencionado como evolução futura em TDD.md).
-- Fechar a `chore-post-f40-f42-baseline-sync` atualizando `PENDING_LOG.md`, `memory.md`, `ERROR_LOG.md`, `README.md` e `CHANGELOG.md` ao estado pos-`F42`/`F40`.
-- Rodar nova `technical-triage` depois da `chore-post-f40-f42-baseline-sync` para escolher a proxima frente fora de `remote_multi_host_auth`.
+- Fechar o bucket `baseline-handoff-sync` alinhando `ERROR_LOG.md`, `README.md` e eventuais docs publicas ao baseline local pos-`F53`.
+- Rodar nova `technical-triage` depois do `baseline-handoff-sync` para escolher uma unica frente entre `multi-agent-session-orchestration` e `local-control-plane-foundation`.
+- Manter `desktop-shell` e `TypeScript-first runtime migration` explicitamente fora da fila principal ate o core Python atual estabilizar boundaries, isolamento e observabilidade.
 - Manter `remote_multi_host_auth` explicitamente adiado ate existir demanda concreta, recorte proprio e validavel.
 
 ## Pontos de atenção futuros

features/F51-runtime-boundaries-foundation/REPORT.md

@@ -0,0 +1,50 @@
+# F51 Report
+
+## Resumo executivo
+
+- A `F51-runtime-boundaries-foundation` introduz boundaries internos explícitos para `ToolSpec`, `WorkspaceProvider`, `RunContext` e lifecycle hooks no Synapse-Flow.
+- O recorte foi implementado de forma incremental sobre o core Python atual, sem migrar stack, sem abrir desktop shell e sem quebrar a pipeline linear do MVP.
+- A feature prepara o terreno para isolamento operacional de workspace, observabilidade mais rica e futuras frentes de multi-agent orchestration.
+
+## Escopo alterado
+
+- novo módulo [runtime_contracts.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/runtime_contracts.py) com contratos de `ToolSpec`, `WorkspaceContext`, `RunContext`, `WorkspaceProvider`, `LocalWorkspaceProvider` e `RunLifecycleHooks`
+- [contracts.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/contracts.py) passa a exportar `ToolSpec`
+- [adapters.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/adapters.py) passa a expor `tool_spec`, `capabilities` e `command_prefix` por adapter
+- [pipeline.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/pipeline.py) passa a carregar `run_context` explícito e a aceitar `workspace_provider`
+- [persistence.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/persistence.py) passa a propagar `initiated_by` e `workspace_provider` ao runtime persistido
+- [runtime/dispatch.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/runtime/dispatch.py) passa a validar e resolver SPEC por `WorkspaceProvider`
+
+## Validacoes executadas
+
+- `validate_spec_file(Path("features/F51-runtime-boundaries-foundation/SPEC.md"))`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m pytest tests/unit/test_contracts.py tests/unit/test_cli_adapter.py tests/unit/test_pipeline_engine.py tests/unit/test_runtime_dispatch.py -q`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m ruff check src/synapse_os/contracts.py src/synapse_os/runtime_contracts.py src/synapse_os/adapters.py src/synapse_os/pipeline.py src/synapse_os/persistence.py src/synapse_os/runtime/dispatch.py tests/unit/test_contracts.py tests/unit/test_cli_adapter.py tests/unit/test_pipeline_engine.py tests/unit/test_runtime_dispatch.py`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m ruff format --check src/synapse_os/contracts.py src/synapse_os/runtime_contracts.py src/synapse_os/adapters.py src/synapse_os/pipeline.py src/synapse_os/persistence.py src/synapse_os/runtime/dispatch.py tests/unit/test_contracts.py tests/unit/test_cli_adapter.py tests/unit/test_pipeline_engine.py tests/unit/test_runtime_dispatch.py`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m mypy src/synapse_os/contracts.py src/synapse_os/runtime_contracts.py src/synapse_os/adapters.py src/synapse_os/pipeline.py src/synapse_os/persistence.py src/synapse_os/runtime/dispatch.py`
+
+## Review de seguranca
+
+- Parecer final: aprovado.
+- Riscos revisados:
+  - ampliar a superfície de execução do runtime ao introduzir abstrações novas
+  - enfraquecer o boundary de `workspace_root` no dispatch
+  - acoplar a feature a uma migração prematura de stack
+- Mitigações aplicadas:
+  - nenhum subprocesso ou transporte novo foi introduzido
+  - o dispatch continua ancorado em `resolve_path_within_root`, agora encapsulado por provider explícito
+  - o recorte permaneceu local, CLI-first e Python-first
+
+## Riscos residuais
+
+- O fallback do `PipelineEngine` sem `workspace_provider` explícito ainda resolve o workspace de forma local simples via diretório da SPEC.
+- A feature introduz boundaries, mas ainda não materializa isolamento operacional por run nem worktree real.
+
+## Proximos passos
+
+- Usar `WorkspaceProvider` como base para isolamento operacional de workspace por run.
+- Reaproveitar `RunContext` e hooks de lifecycle para enriquecer timeline, status e observabilidade local.
+
+## Status final da frente
+
+- `READY_FOR_COMMIT`

features/F51-runtime-boundaries-foundation/SPEC.md

@@ -0,0 +1,46 @@
+---
+id: F51-runtime-boundaries-foundation
+type: refactor
+summary: "Introduzir boundaries internos para tools, workspace, run context e lifecycle do Synapse-Flow"
+inputs:
+  - Arquitetura atual do SynapseOS
+  - Padrões arquiteturais extraídos de Superset, Mastra e coding-agent
+outputs:
+  - Contratos internos explícitos para tools, workspace, run context e lifecycle
+  - Integração do runtime atual com os novos contratos sem regressão funcional
+  - Base estável para worktrees, multi-agent orchestration e control plane local em fases futuras
+acceptance_criteria:
+  - O core deve expor um contrato explícito para tool/capability sem depender da implementação concreta de adapter
+  - O core deve expor um contrato explícito para workspace provider sem introduzir multi-workspace por run no MVP
+  - O core deve expor um run context/lifecycle hook utilizável por pipeline, runtime e persistência
+  - O comportamento atual do Synapse-Flow deve permanecer compatível com a pipeline linear state-driven existente
+  - Deve existir cobertura de teste para os novos contratos internos e para a compatibilidade do fluxo atual com esses contratos
+non_goals:
+  - Implementar shell desktop
+  - Migrar runtime central para TypeScript, Node ou Bun
+  - Introduzir worktree por tarefa nesta fase
+  - Introduzir memória semântica ativa ou roteamento automático por memória
+  - Reestruturar o monorepo para o modelo do Superset
+---
+
+# Contexto
+O SynapseOS já possui um núcleo coerente e auditável para o Synapse-Flow, a engine própria de pipeline do projeto, com pipeline linear state-driven, runtime dual simples, persistência local e adapters CLI. Esse núcleo está visível principalmente em `src/synapse_os/pipeline.py`, `src/synapse_os/state_machine.py`, `src/synapse_os/runtime/` e `src/synapse_os/adapters.py`.
+
+A análise comparativa com Superset, Mastra e coding-agent mostrou que o maior ganho imediato não está em copiar stack, Electron ou o produto completo deles, mas em absorver boundaries mais fortes para:
+
+1. tool/capability registry
+2. workspace abstraction
+3. run context e lifecycle hooks
+4. observability e extensibilidade por contrato
+
+Hoje esses pontos existem de forma parcial ou implícita. Isso dificulta evoluções incrementais como worktree por run, multi-agent orchestration, control plane local e uma UX mais rica sem aumentar acoplamento.
+
+# Objetivo
+Criar a primeira camada de fundação arquitetural inspirada em Superset e Mastra, mas implementada de forma nativa e incremental no SynapseOS.
+
+O recorte desta feature deve:
+
+1. introduzir contratos internos mínimos para `ToolSpec`/capabilities, `WorkspaceProvider`, `RunContext` e lifecycle hooks;
+2. integrar esses contratos ao Synapse-Flow atual sem quebrar a pipeline linear do MVP;
+3. preparar o terreno para features futuras de worktree isolation, observability mais rica, multi-agent orchestration e eventual control plane local;
+4. preservar os princípios atuais de CLI-first, spec-first, local-first e auditabilidade.

features/F52-workspace-isolation-foundation/REPORT.md

@@ -0,0 +1,49 @@
+# F52 Report
+
+## Resumo executivo
+
+- A `F52-workspace-isolation-foundation` introduz a fundação de isolamento operacional de workspace por run sobre os contratos abertos na `F51`.
+- O recorte ficou restrito a `workspace_path` auditável e a um provider `run-scoped`, sem abrir `git worktree` obrigatório nem alterar a CLI pública.
+- A feature preserva o modo legado de workspace único quando o isolamento adicional não é solicitado.
+
+## Escopo alterado
+
+- [runtime_contracts.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/runtime_contracts.py) ganha `RunScopedWorkspaceProvider`
+- [persistence.py](/home/g0dsssp33d/work/projects/SynapseOS/src/synapse_os/persistence.py) passa a persistir `workspace_path` na tabela `runs`
+- `RunRepository` passa a aceitar `workspace_path` explícito e a atualizar schema legado com coluna nova
+- `PersistedPipelineRunner` passa a resolver workspace por `run_id` quando `run_workspace_root` é fornecido
+- o evento `run_started` passa a carregar `workspace` no texto para melhorar rastreabilidade local
+
+## Validacoes executadas
+
+- `validate_spec_file(Path("features/F52-workspace-isolation-foundation/SPEC.md"))`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m pytest tests/unit/test_persistence.py tests/integration/test_pipeline_persistence.py tests/unit/test_runtime_dispatch.py -q`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m ruff check src/synapse_os/runtime_contracts.py src/synapse_os/persistence.py tests/unit/test_persistence.py tests/integration/test_pipeline_persistence.py tests/unit/test_runtime_dispatch.py`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m ruff format --check src/synapse_os/runtime_contracts.py src/synapse_os/persistence.py tests/unit/test_persistence.py tests/integration/test_pipeline_persistence.py tests/unit/test_runtime_dispatch.py`
+- `env PYTHONPATH=src ./.venv-codex-runtime/bin/python -m mypy src/synapse_os/runtime_contracts.py src/synapse_os/persistence.py`
+
+## Review de seguranca
+
+- Parecer final: aprovado.
+- Riscos revisados:
+  - materializar diretórios fora da raiz confiável
+  - quebrar compatibilidade de runs existentes por mudança de schema
+  - introduzir isolamento mais ambicioso do que o MVP comporta
+- Mitigações aplicadas:
+  - o provider novo só cria diretórios previsíveis sob `run_workspace_root / <run_id>`
+  - a coluna `workspace_path` entra com upgrade compatível para schema legado
+  - o modo atual continua funcionando com fallback seguro para o diretório da SPEC
+
+## Riscos residuais
+
+- O isolamento entregue ainda não cria `git worktree`, cópia de árvore nem múltiplos workspaces por run.
+- A materialização do workspace é operacional e auditável, mas ainda não altera a política de artifacts ou diff por run.
+
+## Proximos passos
+
+- Reaproveitar `workspace_path` e `RunContext` para enriquecer a timeline de eventos e o diagnóstico da run.
+- Decidir depois, em frente própria, se `git worktree` realmente compensa como próximo grau de isolamento.
+
+## Status final da frente
+
+- `READY_FOR_COMMIT`

features/F52-workspace-isolation-foundation/SPEC.md

@@ -0,0 +1,45 @@
+---
+id: F52-workspace-isolation-foundation
+type: feature
+summary: "Introduzir isolamento operacional de workspace por run sobre o WorkspaceProvider do Synapse-Flow"
+inputs:
+  - WorkspaceProvider introduzido pela F51
+  - Boundary de workspace já endurecido em F24, F38 e F39
+outputs:
+  - Provider capaz de materializar um workspace operacional por run
+  - Metadados persistidos para rastrear o workspace resolvido da run
+  - Compatibilidade com o modo atual de workspace único quando o isolamento não for solicitado
+acceptance_criteria:
+  - O runtime deve conseguir resolver um workspace operacional por run sem quebrar o MVP de um único workspace local por execução
+  - O caminho efetivo do workspace usado pela run deve ficar auditável para pipeline, persistência e observabilidade local
+  - O sistema deve continuar rejeitando escapes fora da raiz confiável de workspace
+  - O modo atual deve permanecer compatível quando nenhum isolamento adicional for solicitado
+  - Deve existir cobertura de teste para resolução do workspace da run e para persistência do contexto correspondente
+non_goals:
+  - Criar múltiplos workspaces por uma mesma run
+  - Implementar git worktree obrigatório nesta fase
+  - Alterar a CLI pública para um modelo desktop-first
+  - Introduzir scheduling distribuído ou coordenação multi-host
+---
+
+# Contexto
+Com a `F51-runtime-boundaries-foundation`, o SynapseOS passou a expor contratos explícitos para `WorkspaceProvider`, `RunContext` e lifecycle hooks. Isso resolve o primeiro problema estrutural: o core agora tem boundary para runtime, workspace e extensibilidade.
+
+O próximo gap prático é que o Synapse-Flow, a engine própria de pipeline do SynapseOS, ainda opera sobre um root local único, sem materializar um workspace operacional por run. Hoje já existe endurecimento de boundary em `workspace_root`, persistência e runtime state, especialmente nas frentes `F24`, `F38` e `F39`, mas isso ainda protege a raiz; não isola a execução.
+
+Esse isolamento operacional é o pré-requisito mais útil para evoluções futuras como:
+
+1. worktree por tarefa quando isso realmente compensar;
+2. artifacts e diff por run com menos ambiguidade;
+3. multi-agent orchestration com contexto de filesystem previsível;
+4. control plane local com status de workspace explícito.
+
+# Objetivo
+Criar a fundação de isolamento operacional de workspace por run sem abrir ainda a ambição completa de `git worktree per task`.
+
+O recorte desta feature deve:
+
+1. permitir que o `WorkspaceProvider` resolva um workspace efetivo por run, ainda dentro de uma raiz confiável local;
+2. tornar esse workspace auditável em persistência e observabilidade local;
+3. preservar compatibilidade com o modelo atual quando o isolamento adicional não estiver habilitado;
+4. preparar o terreno para uma futura frente específica de `git worktree` sem assumir esse custo agora.