constellai 0.3.0

package/docs/pt/TELEGRAM.md

@@ -0,0 +1,294 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/TELEGRAM.md) · [✦ Constella](../../README.pt-BR.md)
+
+# 🛰️ Telegram — a ponte de bolso para a sua constelação
+
+![](../assets/divider-orbit.svg)
+
+Um único chat privado do Telegram vira uma ponte remota para a sua empresa de agentes: você conversa com a CEO (Ada), aprova planos, liga ou pausa a execução 24/7, dispara novos trabalhos e consulta a Base de Conhecimento — tudo pelo celular, enquanto a nave de controle continua rodando sem interface.
+
+> Fonte da verdade: `src/server/telegram.ts` (ingest + comandos + callbacks), `src/lib/telegram.ts` (cliente da Bot API + formato do token), `bin/worker.mjs` (loop de long-poll), `src/app/api/telegram/poll/route.ts` (entrada exclusiva do worker), `src/server/actions/profile-actions.ts` (`connectTelegram`), `src/lib/scrub.ts` (limpeza de segredos).
+
+---
+
+## 2. O que é
+
+Um bot do Telegram bidirecional, restrito a **um** chat privado por workspace (allowlist). Mensagens recebidas chegam à agente CEO por um canal **isolado** (`telegram`), e um conjunto de comandos de barra + botões inline funcionam como um controle remoto real sobre o ciclo de trabalho. Saída: respostas da agente digitadas na aba Telegram dentro do app são espelhadas de volta para o celular, mantendo a conversa em uma única thread independentemente de onde você digitou.
+
+## 3. Quando usar 🌠
+
+- Você está longe da nave de controle mas quer **ver o status**, **aprovar um plano pendente** ou **ligar/desligar a execução 24/7**.
+- Você quer **iniciar um novo trabalho** a partir de um briefing de uma linha (`/new …`) e deixar a CEO transformá-lo em specs · issues · TODOs.
+- Você quer **perguntar à Base de Conhecimento** (`/kb …`) sem abrir o app.
+- Você quer **conversar com a CEO** (Ada) como em qualquer DM, mas pelo celular.
+
+O Telegram é opcional. É um plugin nativo e o toggle de integração (`settings.integrations.telegram`) vem **LIGADO** por padrão, mas nada acontece até você conectar um token de bot + chat id pela tela de Perfil. Se não estiver configurado, todo caminho do Telegram é um no-op honesto.
+
+## 4. Como funciona 🌌
+
+### Os dois processos
+
+A Constella roda um processo **web** (Next.js) e um **worker** separado (`bin/worker.mjs`). O polling do Telegram vive no worker:
+
+- O worker roda `telegramLoop()` — um loop infinito que faz POST em `BASE/api/telegram/poll` com o header privilegiado `x-worker-secret`.
+- Essa rota (`src/app/api/telegram/poll/route.ts`) é **fail-closed**: exige `CONSTELLA_WORKER_SECRET` e retorna `401` se o header faltar/estiver errado. Em `401`, o worker recua por 30s (tratado como "não configurado / segredo divergente").
+- A rota chama `pollTelegram()` (em `src/server/telegram.ts`), que faz o trabalho real, e devolve `{ ok, updates }`.
+
+### Long-polling, por workspace
+
+`pollTelegram()` itera por **todos** os workspaces. Para cada um, ela:
+
+1. Pula o workspace se a integração estiver desligada (`integrationOn(settings.integrations, "telegram")` — veja `src/lib/integrations.ts`).
+2. Carrega a config do cofre via `getTelegramConfig(ws.id)`; pula se ausente ou se o token estiver malformado.
+3. Registra o menu de comandos `/` do bot **uma vez por bot por processo** (`tgSetMyCommands`, protegido por um set em memória `commandsRegistered`).
+4. Chama `tgGetUpdates(token, offset)` — o `getUpdates` do Telegram com `timeout=25` (um **long-poll do lado do servidor** de ~25s) e `allowed_updates=["message","callback_query"]`.
+5. Faz o ingest de cada update, avança o cursor (`maxId = update_id + 1`) e persiste de volta em `settings.telegram.offset`.
+
+O worker deixa um intervalo breve de 1s entre os long-polls; em erro, recua por 5s.
+
+### A allowlist 🕳️
+
+Somente o **único chat privado registrado** pode comandar o bot. Em `ingest()`:
+
+- O `chat.id` da mensagem deve ser igual a `cfg.chatId`, **e**
+- se `m.from` existir, o `from.id` do remetente também deve ser igual a `cfg.chatId` (em um chat privado eles são o mesmo número).
+
+Qualquer outra coisa é **ignorada silenciosamente**. A mesma checagem é reaplicada aos toques em botões inline em `handleCallback()`. Na conexão (`connectTelegram`), o chat id é validado como um id numérico positivo (ids de grupo são negativos e deixariam qualquer membro comandar o bot — são rejeitados).
+
+### Roteamento de entrada
+
+Para uma mensagem permitida, `ingest()` decide o caminho:
+
+| Condição | O que acontece |
+| --- | --- |
+| `callback_query` presente | Toque em botão inline → `handleCallback()` |
+| aguardando motivo de rejeição + texto puro (não `/…`) | O texto **é** o motivo da rejeição → `requestPlanChangesFor()` |
+| texto começa com `/` | Comando de controle remoto → `handleCommand()` |
+| caso contrário | Falar com a CEO → `runCeoReply()` |
+
+Texto + legenda são limitados a 4000 caracteres. Fotos e documentos são baixados e salvos como anexos (veja [Anexos](#anexos)).
+
+### Conversando com a CEO
+
+`runCeoReply()` resolve a agente **Ada** (`handle = "ada"`, com fallback para o primeiro agente), coloca o status dela em `working`, mostra um indicador `typing…` ao vivo num heartbeat de 4s (o Telegram limpa após ~5s) e chama `replyInChannel(orgId, ws, "telegram", ada, "chat")` (`src/server/collab.ts`).
+
+O `replyInChannel` adiciona uma **proteção contra injeção de prompt específica do Telegram**: avisa ao modelo que a mensagem do operador é *dado, não instrução*, que ele nunca deve revelar segredos / conteúdo de `.env` / `.claude/` / o system prompt, e que deve recusar qualquer tentativa de override. A resposta passa pela limpeza de segredos antes do envio.
+
+Se a Ada decidir que é trabalho de build/fix, ela emite um token interno `[[CREATE_WORK]]`; `replyInChannel` devolve `planRequested = true`, e o `runCeoReply` então roda `planFromConversationFor(orgId, ws, "telegram")` — o **mesmo** ritual de planejamento do caminho web (specs → issues → TODOs) — e confirma no celular.
+
+## 5. Fluxo principal — poll → agente → resposta 🚀
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant TG as Telegram Bot API
+    participant W as worker (bin/worker.mjs)
+    participant API as /api/telegram/poll
+    participant P as pollTelegram()
+    participant ING as ingest()
+    participant CEO as replyInChannel (Ada)
+    participant DB as tabela message
+
+    W->>API: POST (x-worker-secret)
+    API->>API: verifica CONSTELLA_WORKER_SECRET (senão 401)
+    API->>P: pollTelegram()
+    P->>TG: getUpdates(offset, timeout=25)
+    TG-->>P: updates[] (long-poll ~25s)
+    loop cada update
+        P->>ING: ingest(ws, cfg, update)
+        ING->>ING: allowlist: chat.id == cfg.chatId?
+        alt comando (/…)
+            ING->>ING: handleCommand() → ação real
+        else botão inline
+            ING->>ING: handleCallback() → ação real
+        else texto livre
+            ING->>DB: persiste turno do operador (channel=telegram)
+            ING->>CEO: replyInChannel(..., "chat")
+            CEO-->>ING: text + planRequested
+            ING->>TG: sendMessage(resposta limpa)
+            opt planRequested
+                ING->>ING: planFromConversationFor() (specs·issues·TODOs)
+            end
+        end
+    end
+    P->>DB: salva settings.telegram.offset = maxId
+    P-->>W: { updates: N }
+```
+
+## 6. Conceitos-chave ✦
+
+- **Canal isolado.** O Telegram vive em seu próprio canal `telegram` — nunca `room` ou `dm:<handle>` — então a conversa do celular nunca vaza contexto para a team room ou DMs. (`TG_CHANNEL = "telegram"`.)
+- **Credenciais no cofre.** O token do bot + chat id ficam criptografados no cofre sob o ref `telegram_bot` como JSON `{botToken, chatId, allowedName}`. Nunca são persistidos em settings em texto puro.
+- **Cursor de offset.** `settings.telegram.offset` é o cursor de updates do Telegram; avançá-lo confirma os updates processados para que nunca sejam reentregues.
+- **Espera pelo motivo da rejeição.** Um set em memória `awaitingReason` lembra que você tocou no botão **↩️ Reject**; sua próxima mensagem de texto puro vira o motivo. Em memória basta — um restart do servidor simplesmente descarta a espera pendente (toque de novo para repetir).
+- **Registro do menu de comandos.** `commandsRegistered` garante que `setMyCommands` rode uma vez por bot por processo — até bots conectados antes desse recurso existir recebem o menu no próximo poll.
+- **Limpeza de segredos.** Toda string de saída passa por `scrubSecrets(text, [cfg.botToken])` (`src/lib/scrub.ts`) — redigindo o token do bot, os segredos de ambiente padrão e formatos de credenciais de alta confiança (OpenAI/Anthropic `sk-…`, tokens do GitHub, chaves AWS, JWTs, chaves PEM, PATs `cn_…` da Constella e até outros tokens do Telegram).
+
+## 7. Tabelas
+
+### Comandos de barra do Telegram (`handleCommand`)
+
+| Comando | Aliases | Ação |
+| --- | --- | --- |
+| `/help` | — | Mostra o texto de ajuda do controle remoto |
+| `/status` | — | `planStatusFor(ws)` — status rápido |
+| `/review` | — | `reviewSummaryFor(ws)` — resumo de plano / issues / tasks |
+| `/tasks` | — | `tasksListFor(ws)` — o que está em andamento agora |
+| `/approve` | — | `approvePlanFor()` — aprova o plano pendente, enfileira tasks |
+| `/start_execution` | `/start`, `/run` | `approvePlanFor()` + `setAuto247For(true)` — aprova e roda 24/7 |
+| `/pause` | `/stop` | `setAuto247For(false)` — pausa o 24/7 |
+| `/resume` | — | `setAuto247For(true)` — retoma o 24/7 |
+| `/reject <motivo>` | — | `requestPlanChangesFor()` — devolve o plano à CEO |
+| `/new <briefing>` | `/new-work`, `/new-goal` | Injeta um turno do operador + roda a CEO → goal · specs · issues |
+| `/cancel` | — | `cancelGoalFor()` no goal ativo mais recente — para a execução |
+| `/archive` | — | `archiveGoalFor()` no goal ativo mais recente — zipa + arquiva |
+| `/kb <pergunta>` | `/ask-kb` | `kbAnswer(orgId, q)` — pergunta à Base de Conhecimento |
+| *(desconhecido)* | — | Responde "Unknown command" + ajuda |
+
+> O menu `/` que o Telegram mostra é registrado a partir de `TG_BOT_COMMANDS` em `src/lib/telegram.ts` e deve espelhar `handleCommand`. O menu exibido omite os aliases.
+
+### Callbacks de botão inline (`handleCallback`)
+
+| `callback_data` | Ação | Toast | One-shot? |
+| --- | --- | --- | --- |
+| `approve_plan` | `approvePlanFor()` | ✅ Approved | sim (teclado removido) |
+| `start_exec` | `approvePlanFor()` + `setAuto247For(true)` | ▶️ Executing | sim |
+| `reject_plan` | `requestPlanChangesFor()` + arma a espera do motivo | ↩️ Sent back | sim |
+| `review` | `reviewSummaryFor(ws)` | 📝 Review | não |
+| `status` | `planStatusFor(ws)` | 📊 Status | não |
+| `pause` | `setAuto247For(false)` | ⏸ Paused | não |
+| `resume` | `setAuto247For(true)` | ▶️ Resumed | não |
+| *(desconhecido)* | — | Unknown action | — |
+
+Ações one-shot (`approve_plan` / `start_exec` / `reject_plan`) têm seu teclado inline removido via `tgClearButtons`, para que um segundo toque não as dispare de novo.
+
+### Config do cofre & settings
+
+| Onde | Chave / coluna | Significado |
+| --- | --- | --- |
+| cofre | ref `telegram_bot` | JSON criptografado `{botToken, chatId, allowedName}` |
+| `workspace.settings` | `integrations.telegram` | toggle de integração (padrão `true`) |
+| `workspace.settings` | `telegram.offset` | cursor do `getUpdates` do Telegram |
+
+### Linhas em `message` escritas pelo Telegram
+
+| Coluna | Valor no caminho do Telegram |
+| --- | --- |
+| `channel` | `"telegram"` (constante `TG_CHANNEL`) |
+| `fromKind` | `"operator"` (entrada) / `"agent"` (respostas) |
+| `fromHandle` | `"system"` para respostas de controle; handle da Ada para respostas da CEO |
+| `text` | texto da mensagem ou `"(attachment)"`, limitado a 4000 |
+| `attachments` | descritores de arquivos salvos, ou `null` |
+
+## 8. Superfície da Bot API 🪐
+
+Todas as chamadas HTTP passam por `src/lib/telegram.ts` contra `https://api.telegram.org`. Cada helper primeiro checa `isTelegramToken()` — formato do token `^\d{6,}:[A-Za-z0-9_-]{30,}$` — para que um valor malformado nunca consiga repontar a URL da requisição.
+
+| Helper | Método da Bot API | Propósito |
+| --- | --- | --- |
+| `tgGetMe` | `getMe` | verifica o token → `@username` (na conexão) |
+| `tgSetMyCommands` | `setMyCommands` | registra o menu de comandos `/` |
+| `tgGetUpdates` | `getUpdates` | long-poll (`timeout=25`, `message` + `callback_query`) |
+| `tgGetFile` | `getFile` + `/file/bot…` | baixa uma foto/documento → bytes |
+| `tgSendChatAction` | `sendChatAction` | indicador `typing…` |
+| `sendTelegramTo` | `sendMessage` | resposta em texto puro (sem Markdown) |
+| `sendTelegram` | `sendMessage` | envio de notificação (Markdown) |
+| `sendTelegramButtons` | `sendMessage` + `inline_keyboard` | mensagem com botões de controle remoto |
+| `tgAnswerCallback` | `answerCallbackQuery` | confirma um toque de botão + toast opcional |
+| `tgClearButtons` | `editMessageReplyMarkup` | remove um teclado one-shot |
+
+Respostas da agente usam `sendTelegramTo` (texto puro, sem `parse_mode`) de propósito — conteúdo arbitrário (títulos de issues, código, nomes de workspace) nunca deve quebrar o envio nem ser interpretado como Markdown.
+
+## 9. Anexos
+
+Fotos e documentos em uma mensagem recebida são baixados e armazenados no workspace:
+
+- Um id curto de download por mensagem é gerado (`uid().slice(0,8)`).
+- Cada arquivo é buscado via `tgGetFile`, tem o nome sanitizado (`[^\w.\-]` → `_`, últimos 60 caracteres) e é gravado em `uploads/tg-<dlId>/<nome-seguro>` sob a **raiz da org** (`orgRoot(ws.orgId)`).
+- Um descritor de anexo `{name, type, size, path}` é adicionado ao `message.attachments` persistido.
+- Fotos usam o maior tamanho disponível; documentos mantêm seu `file_name` e `mime_type` originais.
+
+Uma mensagem sem texto e sem nenhum anexo salvo é descartada.
+
+## 10. Passo a passo — conectar & comandar 🛰️
+
+### Conectar o bot (`connectTelegram`)
+
+1. Crie um bot com o **@BotFather** do Telegram e copie o token.
+2. Descubra seu **chat id numérico pessoal** (um chat privado — não um grupo).
+3. Na tela de **Perfil** da Constella, informe o token + chat id (e um nome de exibição opcional).
+4. `connectTelegram()` valida o formato do token, rejeita ids não-positivos/de grupo, chama `tgGetMe` para verificar que o token realmente funciona, então armazena `{botToken, chatId, allowedName}` no cofre e registra o menu `/` (`tgSetMyCommands`).
+5. O worker pega isso no próximo poll — mande uma mensagem ao bot para confirmar.
+
+> `telegramStatus()` alimenta o card no app e mascara o chat id (`12•••89`). `disconnectTelegram()` apaga o ref `telegram_bot` do cofre.
+
+### Comandar pelo celular
+
+```text
+/status                      → status rápido
+/review                      → resumo completo de plano / issues / tasks
+/new uma página de cobrança com checkout
+                             → a CEO rascunha goal · specs · issues · TODOs
+/approve                     → enfileira as tasks
+/start_execution             → aprova + 24/7 LIGADO
+/pause   /resume             → liga/desliga o 24/7
+/reject use Stripe e não PayPal→ devolve o plano com um motivo
+/cancel  /archive            → para / arquiva o goal ativo
+/kb como funciona a auth?    → pergunta à Base de Conhecimento
+só conversar normalmente     → fala com a CEO (Ada)
+```
+
+### Espelhamento (app → celular)
+
+Quando você responde pela **aba Telegram dentro do app**, `src/server/chat.ts` chama `mirrorToTelegram(workspace.id, reply)`. Ele carrega a config do cofre e envia a resposta já limpa para o chat real — mantendo a conversa do bot numa única thread independentemente de onde você digitou.
+
+## 11. Estados possíveis
+
+| Estado | Sintoma | Causa |
+| --- | --- | --- |
+| **Não configurado** | Bot nunca responde; rota de poll retorna `401` e depois recua 30s | sem segredo `telegram_bot` no cofre |
+| **Integração desligada** | Configurado mas ignorado | `settings.integrations.telegram = false` |
+| **Conectado** | Respostas, comandos e botões funcionam | token válido + chat id correspondente |
+| **Chat estranho** | Silêncio | id de remetente / chat ≠ `cfg.chatId` (ignorado silenciosamente) |
+| **Aguardando motivo** | Próxima mensagem de texto registrada como motivo da rejeição | você tocou em **↩️ Reject** |
+| **Typing…** | Indicador ao vivo enquanto a resposta é gerada | heartbeat de 4s em `runCeoReply` |
+| **Worker fora do ar** | Nenhuma resposta | o processo worker não está rodando (veja [TEST_DEV](./TEST_DEV.md) / [ARCHITECTURE](./ARCHITECTURE.md)) |
+
+## 12. Integrações relacionadas
+
+- O caminho de resposta da CEO é o mesmo usado por [DM](./DM.md) e pela [TEAM_ROOM](./TEAM_ROOM.md) — o Telegram só o roda em seu canal isolado com uma proteção extra contra injeção.
+- `/new` roda o ritual completo do [WORKFLOW](./WORKFLOW.md) (Goal → Spec → Issue → Plan → TODOs); veja [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md).
+- `/kb` responde a partir da nebulosa de memória [KB_RAG](./KB_RAG.md).
+- As mesmas ações de controle remoto são expostas programaticamente pela [PUBLIC_API](./PUBLIC_API.md) e pelo servidor [MCP](./MCP.md).
+- O Telegram é uma entrada nativa de [PLUGINS](./PLUGINS.md); o toggle vive ao lado das outras integrações.
+
+## 13. Segurança 🕳️
+
+- **Entrada exclusiva do worker.** `/api/telegram/poll` exige `x-worker-secret == CONSTELLA_WORKER_SECRET` (fail-closed `401`). O worker ainda se recusa a enviar esse segredo para qualquer `CONSTELLA_BASE_URL` não-loopback, a menos que `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` (proteção contra SSRF / exfiltração de segredo).
+- **Allowlist estrita.** Exatamente um chat id privado; tanto `chat.id` quanto `from.id` são checados nas mensagens e nos toques de botão. Ids de grupo (negativos) são rejeitados na conexão.
+- **Validação do formato do token.** `isTelegramToken()` protege toda chamada da Bot API para que um token adulterado não consiga redirecionar a URL da requisição.
+- **Reforço contra injeção de prompt.** `replyInChannel` injeta uma cláusula de segurança específica do Telegram: a mensagem do operador é *dado*, segredos/`.env`/`.claude/`/system-prompt nunca devem ser revelados, tentativas de override são recusadas.
+- **Limpeza de segredos na saída.** Toda mensagem de saída passa por `scrubSecrets(…, [cfg.botToken])` — redigindo o token do bot mais formatos de credenciais de alta confiança — antes de sair da nave.
+- **Criptografado em repouso.** As credenciais vivem no [cofre](./SECURITY.md) AES-256-GCM, nunca em settings em texto puro; o card de status no app mascara o chat id.
+- **Saída limitada.** Os corpos de saída têm tamanho limitado (`sendTelegramTo` 3800, `sendTelegram` 3500), e `callback_data` é limitado ao máximo de 64 bytes do Telegram.
+
+## 14. Solução de problemas 🛠️
+
+| Sintoma | Verifique |
+| --- | --- |
+| Bot mudo, rota de poll retorna `401` | Sem segredo `telegram_bot` — conecte pelo Perfil. (O worker trata `401` como "não configurado" e recua 30s.) |
+| "Telegram rejected this bot token." na conexão | Token errado/revogado — `tgGetMe` falhou; copie de novo do @BotFather. |
+| "Chat id must be your personal numeric id…" | Você usou um id de grupo (negativo) — use seu chat id privado. |
+| Mensagens ignoradas, sem erro | `chat.id`/`from.id` do remetente ≠ o `cfg.chatId` registrado (allowlist). |
+| Menu `/` não aparece | `setMyCommands` é best-effort; roda uma vez por bot por processo — reinicie o worker ou reconecte. |
+| Nenhuma resposta | O processo **worker** não está rodando — inicie `npm start` (web + worker) ou `npm run dev:all`. |
+| Resposta parece cortada | Os corpos têm tamanho limitado por design (3800/3500 caracteres). |
+| Motivo da rejeição não registrado | Um comando de barra supera a espera pendente do motivo; envie o motivo como texto puro logo após tocar em ↩️ Reject. |
+
+## 15. Links relacionados
+
+- [DM](./DM.md) · [TEAM_ROOM](./TEAM_ROOM.md) · [CHAT_COMMANDS](./CHAT_COMMANDS.md)
+- [WORKFLOW](./WORKFLOW.md) · [GOALS_SPECS_ISSUES](./GOALS_SPECS_ISSUES.md)
+- [KB_RAG](./KB_RAG.md) · [KB_AGENT](./KB_AGENT.md)
+- [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) · [PLUGINS](./PLUGINS.md)
+- [ARCHITECTURE](./ARCHITECTURE.md) · [AI_ARCHITECTURE](./AI_ARCHITECTURE.md) · [SECURITY](./SECURITY.md)
+- [CONFIGURATION](./CONFIGURATION.md) · [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)

package/docs/pt/TEST_DEV.md

@@ -0,0 +1,324 @@
+[← Índice](./README.md) · [🇬🇧 English](../en/TEST_DEV.md) · [✦ Constella](../../README.pt-BR.md)
+
+# Test Dev 🛰️ — pilotando o produto antes do lançamento
+
+![](../assets/divider-orbit.svg)
+
+O Test Dev sobe o **produto que os agentes estão construindo** (não a nave Constella em si), o dirige com um navegador headless e relata o que viu: erros de console, crashes de página, requisições que falharam, segredos vazados e um punhado de sondagens de segurança. Ele é ao mesmo tempo um **console do operador** (a tela `/test-dev`) e um **portão autônomo** que o loop de trabalho atravessa antes de uma tarefa ser marcada como `done`.
+
+> Mapa estelar: o produto é uma pequena sonda em órbita. O Test Dev é a passagem de telemetria — pilotamos, observamos os instrumentos e só liberamos para a próxima etapa se nada crítico acender. Um boot que nunca alcança a órbita é `inconclusive`, nunca um falso `fail`.
+
+---
+
+## Quando usar 🌌
+
+- **Operador, sob demanda** — abra o módulo **Test Dev** (rota `/test-dev`) ou digite `/test-dev` na Team Room / em uma DM para rodar a validação contra o app em execução.
+- **Autonomamente, como portão** — quando um agente termina uma tarefa de *código*, o loop de trabalho sobe o projeto (portão de boot) e, se houver servidor no ar, roda o Test Dev como um segundo portão antes da tarefa poder pousar em `done`.
+- **Como parte da preparação de deploy** — `runDeployPipeline` chama `ensureBootable` em sua etapa `validateBuild`, reutilizando a mesma maquinaria do dev server (veja [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md)).
+
+Use sempre que quiser um sinal *real* de que o app ainda inicia e renderiza — não um teste unitário, e sim um navegador de verdade batendo em rotas de verdade.
+
+---
+
+## Como funciona 🪐
+
+Dois módulos do servidor cooperam:
+
+| Módulo | Arquivo | Responsabilidade |
+| --- | --- | --- |
+| **Gerenciador do dev server** | `src/server/devserver.ts` | Detectar um projeto executável, instalar dependências uma vez, escolher uma porta livre, subir + supervisionar o dev server do próprio projeto, observar seu console. |
+| **Harness de teste** | `src/server/test-harness.ts` | Dirigir o servidor em execução com Chromium headless (Playwright), coletar findings, rodar sondagens de segurança, capturar screenshot, calcular o veredito, persistir a execução, capturar para a KB. |
+
+O dev server do projeto é um **processo filho de vida longa**, um por workspace, rastreado em memória num mapa `SERVERS` (`Map<workspaceId, DevServer>`). Ele *não* é o processo web/worker da Constella — é o app em construção. No reconcile de boot da Constella, `stopAllProjectServers()` mata todo servidor rastreado para que um restart não deixe nenhum órfão.
+
+---
+
+## Fluxo principal 🌠
+
+```mermaid
+flowchart TD
+  A["runTestDev(workspaceId, orgId, opts)"] --> B["insere test_run (status: running)"]
+  B --> C{"serverUrl() no ar?"}
+  C -- "não, opts.noBoot" --> Z1["inconclusive — suba o dev server"]
+  C -- "não" --> D["startProjectServer()"]
+  D --> E{"running + url?"}
+  E -- "não" --> Z2["inconclusive — não subiu"]
+  E -- "sim" --> F
+  C -- "sim" --> F["deriva rotas (caller ou '/'), máx 8"]
+  F --> G{"import @playwright/test"}
+  G -- "ausente" --> Z3["inconclusive — Playwright indisponível"]
+  G -- "ok" --> H["chromium.launch headless"]
+  H -- "binário ausente" --> H2["ensureChromium() instala · tenta de novo"]
+  H2 -- "ainda falha" --> Z4["inconclusive — não conseguiu subir o chromium"]
+  H --> I["novo context 1280x800 · liga listeners console/pageerror/requestfailed"]
+  I --> J["para cada rota: goto · clica 1º botão · varre HTML por segredos · screenshot"]
+  J --> K["sondagens de segurança: /.env /.env.local /.git/config /config.json /admin /api"]
+  K --> L{"algum finding high-severity?"}
+  L -- "sim" --> M["veredito: fail"]
+  L -- "não" --> N["veredito: pass"]
+  M --> O["atualiza test_run · ingestKnowledge(type: test)"]
+  N --> O
+```
+
+### Lista de passos (o que `runTestDev` realmente faz)
+
+1. **Abrir a execução** — insere uma linha `test_run` com `status: "running"`, `by` = `operator` (padrão) ou `agent`.
+2. **Garantir um dev server** —
+   - Se já houver uma URL no ar, usa.
+   - Se não houver e `opts.noBoot` estiver setado (caminho do portão autônomo), retorna `inconclusive` imediatamente — o portão nunca auto-instala/sobe um projeto no meio de uma tarefa.
+   - Caso contrário, chama `startProjectServer()`; se não subir, retorna `inconclusive`.
+   - Se o servidor iniciou mas `serverStatus().status !== "running"` ainda, retorna `inconclusive` ("ainda subindo — tente de novo em instantes").
+3. **Derivar rotas** — `opts.routes` fornecidas pelo chamador, senão `["/"]`, limitadas a **8** rotas.
+4. **Subir o navegador** — `import("@playwright/test")` dinâmico. Se o import falhar → `inconclusive`. Se `chromium.launch()` lançar porque o binário do navegador não está instalado → `ensureChromium()` roda `npx playwright install chromium` (uma vez por processo, limite de 300s) e tenta de novo; se ainda falhar → `inconclusive`.
+5. **Dirigir cada rota** — abre um context em **1280×800**, liga os listeners e, para cada rota: `page.goto(...)` (`domcontentloaded`, timeout 20s), registra um finding `high` em HTTP ≥ 500, espera 800ms, clica no primeiro `button` visível e habilitado para exercitar um fluxo, varre o HTML servido por segredos, captura screenshot em `.testdev/`.
+6. **Sondagens de segurança** — `fetch` em cada caminho sensível (`redirect: "manual"`, timeout 4s); um `200` com conteúdo (qualquer caminho exceto `/api`) ou um match de segredo é um finding de segurança `high`.
+7. **Veredito** — qualquer finding de severidade `high` ⇒ `fail`; caso contrário `pass`. Warnings / findings low nunca reprovam uma execução.
+8. **Persistir + capturar** — atualiza a linha `test_run` (`status`, `summary`, `findings`, `finishedAt`) e `ingestKnowledge(type: "test")` para que o veredito vire KB durável.
+
+---
+
+## Conceitos-chave ✦
+
+### Detecção de stack (`detectProject`)
+
+`detectProject(orgId)` varre a raiz do workspace **e** subdiretórios comuns (`packages`, `apps`, `app`, `web`, `client`, `frontend`, `backend`, `server`, `api`). Ele roda duas passagens:
+
+- **Passagem 1 — Node sempre vence.** `detectNode(dir)` procura `package.json` com um script `dev`, `start` ou `serve` (nessa prioridade). O gerenciador de pacotes é inferido pelo lockfile: `pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, senão `npm`. A instalação só é sinalizada quando `node_modules` está ausente.
+- **Passagem 2 — outros ecossistemas**, em ordem: Django (`manage.py`), FastAPI (`main.py` contendo `FastAPI(`) → `uvicorn`, `main.py` simples → `python main.py`, Go (`go.mod`) → `go run .`, Rust (`Cargo.toml`) → `cargo run`, estático (`server.js`) → `node server.js`.
+
+| `ProjectKind` | Gatilho | Label | Etapa de install |
+| --- | --- | --- | --- |
+| `node` | `package.json` + dev/start/serve | `npm/pnpm/yarn <script>` | `<pm> install` se `node_modules` ausente |
+| `python` (django) | `manage.py` | `django runserver` | `pip install -r requirements.txt` (uma vez, marker) |
+| `python` (fastapi) | `main.py` com `FastAPI(` | `uvicorn` | idem |
+| `python` (script) | `main.py` | `python main.py` | idem |
+| `go` | `go.mod` | `go run` | — |
+| `rust` | `Cargo.toml` | `cargo run` | — |
+| `static` | `server.js` | `node server.js` | — |
+
+### Faixa de portas 🛰️
+
+`freePort(start = 4173, end = 4999)` percorre a faixa e retorna a primeira porta que faz bind em `127.0.0.1`. A faixa deliberadamente **evita a própria `:3000` da Constella**. A porta escolhida é exportada para o filho como `PORT`, e qualquer sentinela literal `$PORT` em `runArgs` é substituída antes do spawn. Env passado ao filho: `PORT`, `BROWSER=none`, `NODE_ENV=development`.
+
+### Pré-checagem de toolchain
+
+Para kinds não-Node e não-estáticos (`python`/`go`/`rust`), `toolAvailable(cmd)` roda `<cmd> --version` (cache de 60s) antes de subir. Um toolchain ausente falha **rápido e com clareza** em vez de uma espera morta de 30s. No portão de boot isso é tratado como "não dá para validar, não punir" — veja Estados possíveis.
+
+### Detecção de "ready" + deadlines de boot
+
+`push()` observa o stdout/stderr do filho; a primeira linha que casa com `/(ready|listening|localhost:|started server|compiled)/i` vira `status: "starting" → "running"`. Em paralelo, `waitReachable(url, deadline)` faz polling na porta. Os deadlines escalam por kind:
+
+| Kind | Deadline de boot |
+| --- | --- |
+| `go`, `rust` (compilação) | 120 000 ms |
+| `python` | 60 000 ms |
+| `node` / `static` | 30 000 ms |
+
+### Findings — tipos & severidades 🕳️
+
+Um `Finding` é `{ severity, kind, route, message }`.
+
+| `kind` | Origem | `severity` típica |
+| --- | --- | --- |
+| `console` | `page.on("console")` — `error` → high, `warning` → low | high / low |
+| `pageerror` | `page.on("pageerror")` — exceção JS não capturada | high |
+| `request` | `page.on("requestfailed")` (não-`ERR_ABORTED`), HTTP ≥ 500 no `goto`, ou navegação que falhou | med / high |
+| `security` | match do regex de segredo no HTML servido, ou caminho sensível retornando `200` com conteúdo | high |
+| `boot` | dev server / chromium não conseguiu iniciar | low |
+| `fidelity` | **diff visual vs o design aprovado** — a rota rodando é pixel-diffada (no navegador, 1280×800) contra um baseline renderizado da tela promovida. Drift pequeno → `med`; estruturalmente errado (>50% diferente) → `high` | med / high |
+
+**Fidelidade visual (quando um design static foi promovido).** Se o projeto tem um [design promovido](DESIGN.md) servido de `public/`, o harness captura um **baseline** único de cada tela aprovada e faz pixel-diff do app rodando contra ele. Enforça "o app rodando bate com o design": drift de dado real é nota, uma tela que não bate (>50%) **falha o gate**. A checagem é best-effort — nunca trava um projeto sem design promovido e nunca quebra um run.
+
+O detector de segredos `SECRET_RE` casa chaves `sk-…`, IDs AWS `AKIA…`, cabeçalhos de chave privada PEM e literais `password: "…"` / `password='…'`. Ele é aplicado tanto ao HTML servido quanto aos corpos de resposta das sondagens.
+
+### Sondagens de segurança
+
+`SECURITY_PATHS = ["/.env", "/.env.local", "/.git/config", "/config.json", "/admin", "/api"]`. Cada um é buscado **apenas contra o dev server local do projeto** — nunca um host externo. Um `200` que retorna conteúdo (todo caminho exceto `/api`, que pode legitimamente ser um `200` roteável) é marcado como finding de segurança high-severity, assim como qualquer corpo de resposta que case com `SECRET_RE`.
+
+### Lógica do veredito
+
+```text
+high = findings onde severity === "high"
+status = high.length ? "fail" : "pass"
+```
+
+Somente findings **hard (high-severity)** bloqueiam. Warnings e notas de baixa severidade são registrados mas não reprovam a execução. Se o app não conseguir subir, o Playwright estiver ausente, ou o chromium não subir, o veredito é **`inconclusive`** — uma escolha de design deliberada para que o harness nunca produza um falso `fail` e nunca bloqueie uma tarefa por engano.
+
+---
+
+## A tabela `test_run` 🗄️
+
+Definida em `src/db/schema.ts` (`sqliteTable("test_run", …)`):
+
+| Coluna | Tipo | Notas |
+| --- | --- | --- |
+| `id` | text PK | UUID da execução |
+| `workspaceId` | text → `workspace.id` | cascade delete; indexada (`test_run_ws_idx`) |
+| `goalId` | text, nullable | link opcional ao goal sob teste |
+| `issueId` | text, nullable | link opcional à issue sob teste |
+| `status` | enum `running` \| `pass` \| `fail` \| `inconclusive` | padrão `running` |
+| `summary` | text | padrão `""`; fatia persistida de ≤ 600 chars |
+| `findings` | text (JSON) | `Finding[]` serializado; fatia persistida de ≤ 20 000 chars |
+| `by` | enum `operator` \| `agent` | quem disparou a execução |
+| `startedAt` | integer timestamp | padrão agora |
+| `finishedAt` | integer timestamp, nullable | setado em `finish()` |
+
+A página `/test-dev` (`src/app/(app)/test-dev/page.tsx`) lista as **20 execuções mais recentes** do workspace mais o `serverStatus(workspace.id)` ao vivo.
+
+---
+
+## Estados possíveis 🌌
+
+### Status do dev server (`DevServerStatus.status`)
+
+| Estado | Significado |
+| --- | --- |
+| `none` | nenhum servidor rastreado para este workspace |
+| `starting` | spawnado, ainda não alcançável / nenhuma linha de "ready" vista |
+| `running` | alcançável / imprimiu uma linha de "ready" |
+| `stopped` | saiu de forma limpa ou foi parado pelo operador |
+| `error` | spawn falhou, exit ≠ 0, toolchain ausente, ou nenhuma porta livre |
+
+### Veredito de teste (`TestVerdict`)
+
+| Veredito | Quando |
+| --- | --- |
+| `pass` | nenhum finding high-severity |
+| `fail` | ≥ 1 finding high-severity |
+| `inconclusive` | não subiu / nenhum projeto executável / Playwright ou chromium indisponível / servidor ainda inalcançável / `noBoot` e nada no ar |
+
+---
+
+## Passo a passo 🚀
+
+### Rodar como operador
+
+1. Abra o módulo **Test Dev**, ou digite `/test-dev` na Team Room ou em uma DM.
+2. Se nenhum dev server estiver no ar, suba a partir do módulo (isso chama `startDevServerAction` → `startProjectServer`, instalando dependências na primeira vez).
+3. Rode a validação. O Edsger posta o resultado de volta no thread:
+   `Test Dev — **pass** … Navigated N route(s).`
+4. Inspecione os findings + screenshots (salvos em `<org-root>/.testdev/<runId>-<route>.png`).
+
+### Rodar para uma issue específica
+
+`runTestDevAction({ issueId })` resolve rotas com `routesForIssue(workspaceId, issueId)`, que minera o título/key da issue por substrings parecidas com `/path` (até 4) e sempre inclui `/`.
+
+---
+
+## Exemplos 🛰️
+
+**Comando slash do operador (`/test-dev`)** — tratado em `src/server/commands.ts`:
+
+```text
+operator: /test-dev
+edsger:   🧪 Running the Test Dev validation gate…
+edsger:   Test Dev — pass. Passed — 2 note(s), no blocking issues. Navigated 1 route(s).
+```
+
+**Portão autônomo (runner)** — após uma tarefa de código, em `src/server/runner.ts`:
+
+```ts
+// portão de boot — o projeto AINDA precisa subir
+const boot = await ensureBootable(ws.id, ws.orgId);
+if (!boot.ok) {
+  next = "review";
+  await pushInbox(ws.id, { kind: "block", refType: "task", refId: t.id, /* … */
+    title: `${t.key} broke the dev server`, detail: `${t.title}\n\n${boot.detail}` });
+}
+
+// portão Test Dev — só se um servidor já estiver no ar (noBoot: true)
+if (next === "done" && serverUrl(ws.id)) {
+  const gate = await runTestDev(ws.id, ws.orgId, { goalId: t.goalId, issueId: t.issueId ?? undefined,
+    by: "agent", noBoot: true, routes: /* routesForIssue */ });
+  if (gate.status === "fail") {
+    next = "review";
+    await pushInbox(ws.id, { kind: "validation", refType: "validation", refId: gate.id, /* … */
+      title: `${t.key} failed Test Dev`, detail: gate.summary });
+  }
+}
+```
+
+---
+
+## Gating do Edsger + o modelo de dois portões 🪐
+
+O loop de trabalho autônomo aplica **dois** portões antes de uma tarefa de código poder ser marcada como `done`:
+
+1. **Portão de boot (`ensureBootable`)** — aplica-se quando `next === "done"` e a tarefa tocou ao menos um caminho de *código* (`isCodePath`: qualquer coisa que não esteja sob `.claude/`, `DOCS/`, `PO/`, `Reports/`, `specs/`, `issues/`, `mock/`, e que não seja um `*.md` de topo). Se o projeto não sobe mais, a tarefa volta para `review`, um `block` é enfileirado no Inbox (`"<key> broke the dev server"`) e o operador é notificado. Um *toolchain ausente* retorna `ok: true` (pula, "não dá para validar"), nunca um bloqueio falso.
+2. **Portão Test Dev (`runTestDev`, `noBoot: true`)** — aplica-se quando `next === "done"` **e um dev server já está no ar** (`serverUrl(ws.id)`). Por causa de `noBoot`, esse portão nunca instala/sobe um projeto no meio da tarefa — ele só valida o que já está no ar. Um veredito `fail` manda a tarefa de volta para `review` com um item `validation` no Inbox (`"<key> failed Test Dev"`).
+
+O **Edsger** é o agente de QA/teste (handle `edsger`, reporta a `linus`). Quando o Test Dev roda como portão autônomo (`by: "agent"`), a captura na KB é atribuída ao `edsger`; quando rodado via `/test-dev`, o Edsger é a persona que posta o veredito na conversa. Ambos os portões são projetados para **degradar para `inconclusive`/pular** em vez de segurar uma tarefa por engano.
+
+```mermaid
+flowchart LR
+  T["tarefa concluída pelo agente"] --> C1{"tocou caminho de código?"}
+  C1 -- "não (docs/PO)" --> DONE["done"]
+  C1 -- "sim" --> BG["portão de boot: ensureBootable"]
+  BG -- "ok:false" --> REV1["review + Inbox block"]
+  BG -- "ok:true" --> C2{"dev server no ar?"}
+  C2 -- "não" --> RG["portão de review (reviewer)"]
+  C2 -- "sim" --> TD["runTestDev noBoot:true"]
+  TD -- "fail" --> REV2["review + Inbox validation"]
+  TD -- "pass / inconclusive" --> RG
+  RG --> DONE
+```
+
+---
+
+## Screenshots & artefatos 🌠
+
+- Screenshots são gravados em `<org-root>/.testdev/<runId>-<route>.png` (rota convertida em slug `[a-z0-9_]`, `root` para `/`). O diretório é criado em best-effort com `mkdirSync(..., { recursive: true })`.
+- A captura na KB (`ingestKnowledge`) escreve uma entrada do tipo `test` intitulada `Test Dev — <status>` com o summary, ligada ao goal/issue, atribuída ao `edsger` (execuções de agente) ou `operator`.
+- O diretório `.testdev/` é um artefato de controle da Constella — ele é removido da árvore de fonte limpa pela preparação de deploy (`buildCleanTree`) e não faz parte do produto que é enviado.
+
+---
+
+## Integrações relacionadas 🛰️
+
+- **Loop de trabalho / runner** — `src/server/runner.ts` conecta ambos os portões (veja [WORKFLOW.md](./WORKFLOW.md), [AGENTS.md](./AGENTS.md)).
+- **Inbox** — portões reprovados enfileiram itens `block` / `validation` (veja [INBOX.md](./INBOX.md)).
+- **KB / RAG** — todo veredito é ingerido como conhecimento `test` durável (veja [KB_RAG.md](./KB_RAG.md), [KB_AGENT.md](./KB_AGENT.md)).
+- **Prepare Deploy** — reutiliza `ensureBootable` + `detectProject` na etapa `validateBuild` (veja [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md)).
+- **Comandos de chat** — `/test-dev` e `/review` (veja [CHAT_COMMANDS.md](./CHAT_COMMANDS.md)).
+- **Stacks de projeto** — a detecção de stack espelha os ecossistemas do starter executável (veja [PROJECT_STACKS.md](./PROJECT_STACKS.md)).
+
+---
+
+## Segurança 🕳️
+
+- **Sondagens são apenas locais.** As sondagens de segurança e a checagem de frameability do iframe (`previewFrameableAction`) só miram `127.0.0.1` / `localhost`. O harness nunca aponta um navegador ou `fetch` para um host externo.
+- **Varredura de segredos** roda no HTML servido e nos corpos de resposta das sondagens via `SECRET_RE`; um match é um finding de segurança high-severity (e, se aparecer na saída do produto, algo que os agentes precisam corrigir antes do deploy).
+- **Sondagem de caminhos sensíveis** confirma que `/.env`, `/.git/config`, `/admin` etc. não são servidos sem autenticação pelo app sob teste.
+- **Sem falso fail.** A incapacidade de subir ou de instalar o Chromium gera `inconclusive`, nunca `fail` — o portão não pode ser transformado numa negação de progresso por um toolchain instável.
+- O dev server do projeto roda com `NODE_ENV=development`, `BROWSER=none`, dentro do workspace da org; no restart da Constella, `stopAllProjectServers()` o recolhe.
+
+Veja [SECURITY.md](./SECURITY.md) para o modelo de confiança geral.
+
+---
+
+## Solução de problemas 🌌
+
+| Sintoma | Causa | Correção |
+| --- | --- | --- |
+| `inconclusive — No runnable project` | nenhum script dev/start/serve no `package.json` e nenhum entrypoint Python/Go/Rust/`server.js` | adicione um script `dev`/`start` ou um ponto de entrada reconhecido no workspace |
+| `inconclusive — Playwright not available` | `@playwright/test` não instalado | instale o Playwright no diretório de instalação |
+| `Couldn't install/launch chromium` | binário do navegador ausente, install estourou o timeout (300s) | rode `npx playwright install chromium` no diretório de instalação e tente de novo |
+| `inconclusive — Dev server is still starting` | porta ainda inalcançável dentro do deadline | espere e rode de novo; para a primeira compilação go/rust isso pode levar até 120s |
+| `error — Toolchain not found: '<cmd>'` | python/go/cargo fora do `PATH` | instale o toolchain, ou escolha uma stack Node (o portão de boot o pula como "não dá para validar") |
+| `error — No free port available` | nada livre em `4173–4999` | libere uma porta na faixa ou pare dev servers obsoletos |
+| Portão de boot segurou a tarefa (`"<key> broke the dev server"`) | a mudança deixou o projeto sem conseguir subir | corrija o erro de build/import; a tarefa fica em `review` com o log de boot no Inbox |
+| Iframe de preview mostra erro do navegador | app envia `X-Frame-Options` / CSP `frame-ancestors` restritivo | esperado — `previewFrameableAction` detecta; abra o app numa nova aba |
+
+---
+
+## Links relacionados ✦
+
+- [WORKFLOW.md](./WORKFLOW.md) — o ciclo de vida do trabalho e onde os portões se encaixam
+- [AGENTS.md](./AGENTS.md) — Edsger (QA) e o roster
+- [PREPARE_DEPLOY.md](./PREPARE_DEPLOY.md) — reuso de `ensureBootable` na preparação de deploy
+- [DEPLOY.md](./DEPLOY.md) — lançando o produto
+- [INBOX.md](./INBOX.md) — onde portões reprovados pousam
+- [KB_RAG.md](./KB_RAG.md) · [KB_AGENT.md](./KB_AGENT.md) — conhecimento de teste durável
+- [CHAT_COMMANDS.md](./CHAT_COMMANDS.md) — `/test-dev`, `/review`
+- [PROJECT_STACKS.md](./PROJECT_STACKS.md) — stacks que o dev server consegue subir
+- [SECURITY.md](./SECURITY.md) · [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)