Relatório final — Scan do Motor

Data: 2026-10-11 · Repositório: PedroPaduelo/motor (sandbox motor, /workspace) · HEAD auditado: 69e0b28

Produção: motor-be-ws e motor-worker-ws rodam 6fc7d65. Conferido com git nesta revisão: o HEAD está só 2 commits à frente, ambos de frontend (markdown do chat). O backend auditado é idêntico ao de produção, e o fix do Parar (020aa42) já está em produção. Uma métrica de scanner fala em "4 merges à frente"; vale a conferência acima.

0. Metodologia e como ler

O scan cobriu 8 dimensões: loop do agente e SDK; tempo real; tools e system prompt; agente e subagentes; workflows; banco, cache, threads e escala; segurança; qualidade e modularidade. Cada dimensão descreveu como o Motor funciona, respondeu às perguntas do dono com evidência arquivo:linha, mediu o que dava para medir e listou perguntas abertas. Depois vieram uma pesquisa de boas práticas (Anthropic como referência, mais mercado e tempo real) e uma investigação das lacunas (SDK nativo e socket.io; capacidade e topologia de produção; modularidade de tools e subagentes; workflows frente ao mercado; webhooks, rotas e versionamento de contratos).

Revisão cética. Todos os achados que os scanners classificaram como crítica ou alta passaram por revisores adversários, que procuraram contra-evidência no código, nos docs e nos logs de produção. Os achados média, baixa e info não passaram por essa rodada.

Status usados:

• confirmado — fato e severidade mantidos pelo revisor;
• confirmado; sev. contestada (X→Y) — fato confirmado, severidade revista pelo revisor; o relatório usa Y;
• contestado — revisores de dimensões diferentes divergiram sobre o mesmo fato; as duas leituras aparecem;
• não verificado — sem rodada adversária (média, baixa, info); hipótese do scanner com evidência arquivo:linha, a confirmar antes de agir;
• refutado — derrubado por contra-evidência; listado em 3.9 e fora do roadmap.

Severidade: crítica, alta, média, baixa, info. Esforço: P (horas a 1 dia), M (dias), G (semana ou mais). Dentro de cada área, a ordem é do mais grave ao mais leve, pela severidade revisada. As linhas de código citadas referem-se ao HEAD 69e0b28.

Limites. Produção estava ociosa nas janelas de log lidas (2,66 req/min numa janela; 115 requests, todos 200, noutra). Não houve teste de carga: números de capacidade são estimativas por leitura de código e configuração. Segredos e .env de produção não foram lidos (aparecem mascarados no painel). Tudo que é estimativa ou incerto está marcado.

1. Sumário executivo — resposta direta às 9 perguntas

P1. O loop atual é o melhor? Vale trocar para o SDK nativo da Anthropic (@anthropic-ai/sdk, API Messages), sem Agent SDK nem Claude Code? Como ficaria? O loop atual é bom e cheio de cicatrizes pagas: usage somado à mão (existe mesmo em falha), parcial gravado antes de classificar o erro, aborto com nome AbortError mais guarda de 5s, reparo de tool-calls. Seria o melhor se o Motor precisasse de abstração multiprovider. Mas o Motor fala um único formato: Anthropic Messages via Load Balance, com model: "proxy-managed" sempre e até 362 tools por turno. Nesse cenário o pacote ai v5 cobra pedágio sem entregar valor: aborto por nome mágico, retry escondido, cache_creation perdido, breakpoints de cache montados por interceptor que reparseia o body a cada step, buffer acumulado manual no prepareStep, replay de thinking inoperante. Recomendação: migrar para o SDK nativo de forma incremental (tradutor de histórico, runner nativo atrás de flag por setup, shadow do wire, rollback por flag), nunca big-bang: o contrato byte a byte com o LB precisa ser preservado e o histórico persistido está em formato do AI SDK. Desenho na seção 5.1.

P2. O Motor aguenta alto volume, com muitas pessoas usando ao mesmo tempo? Não, como está. O núcleo foi desenhado para várias réplicas (lock distribuído, mailbox durável, drain atômico), mas hoje roda 1 réplica de API e 1 de worker, e há travas medidas: (1) banco: o postgresql.conf de produção mostra max_connections = 100, contra um pool pretendido de 1000 por processo (2000 com API e worker; o runbook pede ≥ 2100). Falta confirmar com SHOW max_connections, porque o container pode sobrescrever na linha de comando; (2) custo e escala: 999 steps por turno por padrão (um turno real queimou cerca de 14 milhões de tokens até overloaded_error), nenhum timeout padrão (turnTimeoutMs = 0), fan-out de subagentes sem teto por árvore; (3) gates por processo: rate limit, concorrência por org e circuit breaker multiplicam por réplica; e a 2ª réplica hoje quebraria Parar, "rodando", eventos ao vivo e fim de sessão; (4) polling: cerca de 3.000 req/min só de polling com 100 abas no pico, sem cache, e um rate limit de 30 req/min por IP que uma única aba com o modal de subagente já estoura. Estimativa sem teste de carga: ~10–30 conversas simultâneas se o banco estiver mesmo em 100 conexões; ~50–80 turnos simultâneos por réplica, com teto duro de 100 turnos por org e por processo, se o banco seguir o runbook. Recomendação: ondas 1 e 2 do roadmap (tetos, timeout, preço real, abort, isBusy e broadcast distribuídos, banco e Redis dimensionados) e um teste de carga 10→50→100 turnos antes de prometer volume.

P3. Como funciona o tempo real hoje (WebSocket, polling, SSE)? Como ficaria tudo via WebSocket com socket.io, sem polling e sem SSE? Hoje há dois canais WebSocket nativos (thread e run) em GET /ws, com handshake e replay; 9 pontos de polling REST (lista de threads 8s; árvore e graph 3–5s; modal de subagente 2s + 3s; lista de runs 5s; log 4s; passo 3s; saúde 30s); e zero SSE na camada do app — o único SSE é interno, entre o SDK e o proxy. O chat não faz streaming token a token: manda o parcial uma vez por step. Com 2 réplicas o tempo real quebra, porque broadcaster, isBusy, abort e fim de sessão vivem na memória de cada processo. Recomendação: gateway socket.io com Redis adapter (Redis Streams adapter se quiser recuperação nativa de conexão), salas por thread, run, usuário e org montadas pelo servidor a partir da identidade autenticada, seq por sala com replay pelo banco, acks do cliente para o servidor e catálogo de eventos versionado. Migração em 7 fases (F0–F6), cada uma desligando um polling, com REST como fallback. Desenho na seção 5.2. Decisão do dono: socket.io (pedido) ou evoluir o ws nativo com Redis pub/sub (seção 7).

P4. O código está modular e bem escrito? As integrações estão bem feitas? Há contradições, vazamento de informação ou problemas com as tools? Em grande parte sim, acima da média para o tamanho (backend com cerca de 57 mil linhas, frontend com cerca de 73 mil). Separação clara entre transporte (ws), execução (engine), estado (persistence) e tools; os cabeçalhos explicam o porquê; o contrato Motor↔LB é o melhor documento do repositório; MCP usa o SDK oficial v2 com pool consciente; o frontend tem zero as any (o backend tem 60). Contradições doc×código. Confirmadas pelos revisores: o aviso de colisão de tools diz "manteve o primeiro" e o código mantém o último; o abort entre réplicas é documentado ("a dona escuta e aborta") e não tem assinante. Apontadas sem revisão: cabeçalho generateText × código streamText; append da thread "soma" × "substitui"; defaults de cache do schema × contrato do LB; prompt "sem MCP externo"; "token na chave do pool"; header 16 × código 100; docs/operacao.md defasado. Vazamentos. Snapshot da config com segredos em claro gravado a cada turno no Postgres e no Redis; SSRF em 4 superfícies (webhooks, /api/mcp/test, test-connection, MCPs por thread); config da org default herdada por qualquer outra org (latente hoje, crítico com multi-org); ••• ecoado pela UI vira header real enviado ao MCP. Tools. Resultado sem teto; required decorativo para JSON válido com campo faltando; descrição de MCP entra verbatim no prompt; notificação de subagente entra com moldura de autoridade; 362 tools por turno no padrão.

P5. Como as tools são montadas, interpoladas e enviadas ao modelo, e como o system prompt é gerado? Como modularizar e ter domínio? Por turno: MCPs conectados em paralelo via pool (listTools) → filtro opcional mcps[].tools → merge com as 23 nativas em ordem alfabética (prefixo byte-idêntico para o cache) → recorte pela toolPolicy do setup. O Record inteiro vai no tools de cada step, sem limite de tamanho. O system prompt é concatenação de 3 camadas: base (system-prompt.md, 25,9 mil chars) + systemPromptAppend efetivo (org + persona do setup, ou override que substitui) + bloco de voz. Interpolação só em 3 pontos: ${VAR} no chat-config.json em disco, token de MCP virando Authorization: Bearer, e expressões ${...} de workflow; não há motor de template no prompt. Custo medido: nativas ≈ 9,4 mil tokens + system ≈ 6,5 mil = ~15,8 mil tokens por request antes de qualquer MCP; com os MCPs de produção, estimativa de 80–214 mil tokens só no bloco de tools (premissa de 150–400 tokens por tool; não medido em produção), numa janela de 230 mil. Domínio hoje: só contagens no log e a config crua. Recomendação: (1) builder de prompt por camadas versionadas (nome, hash, tamanho) com semântica explícita de soma ou substituição; (2) registro com namespace servidor__tool; (3) núcleo pequeno com carregamento sob demanda (tool search ou activeTools por step); (4) painel de inspeção por turno (hash de cada camada, tools finais com origem e tamanho, breakpoints, tokens de cache); (5) tetos de descrição, schema, resultado e steps; (6) validação de argumentos. Desenho na seção 5.3.

P6. A comunicação agente↔subagentes, que é assíncrona, é eficiente, sem overhead? Está claro para a IA como abrir subagente, escolher o setup e conduzir o processo? O desenho é bom e assíncrono de verdade: agent_spawn cria a thread filha e retorna na hora; o filho roda com lock próprio, em paralelo real; o resultado volta por push na mailbox do pai com exactly-once (notifiedParentAt); N notificações viram 1 turno; com o pai rodando, entram no meio do turno; o spawn é idempotente por toolCallId. Overhead real: o finalText do filho volta inteiro e fica no histórico do pai até a compactação; largura e profundidade são ilimitadas (D4/D6) sem orçamento por árvore; cancelar o pai não para filhos e netos; o reaper está desligado em produção, então um crash deixa o pai esperando para sempre. Clareza para a IA: descrições e seção do system prompt são boas (quando paralelizar, tarefa autocontida, setup_list antes de setupId, não esperar porque a notificação chega sozinha), mas faltam o limite de tamanho do retorno e o aviso de que filhos paralelos escrevem no mesmo workspace; e "o filho herda o setup" não traz a persona. Recomendação: contrato de delegação com retorno capado (4–8 mil chars + referência ao threadId), tetos por árvore, abort em cascata, reaper ligado em uma réplica, persona e escopo de escrita explícitos (seção 5.4).

P7. Está eficiente em banco de dados, em threads (concorrência) e em cache? Parcialmente. Banco: transações curtas, bons índices, mailbox com FOR UPDATE SKIP LOCKED; mas um turno simples custa ~20–25 statements, a autenticação faz 2 leituras por request sem cache, cada appendEvent publica o JSON num canal Redis sem consumidor, events de thread ativa cresce sem purga e o pool (1000 por processo) não casa com o max_connections = 100 lido em produção. Concorrência: lock por thread correto (Redis SET NX + heartbeat); mas rate limit, gate por org, circuit breaker, isBusy, abort e broadcaster são locais ao processo, e mapas em memória crescem sem expiração. Cache: janela quente de events bem desenhada; porém o convo no Redis é write-only (escrito a cada turno, nunca lido) — e um turno sem o convo em memória (restart seguido de um workflow que acorda a conversa, ou outra réplica) manda ao LLM só as mensagens novas, sem o histórico. Fila e cache dividem a mesma instância Redis de 512 MB (decisão registrada). Recomendação: fallback do convo (memória → Redis → banco), remover ou aproveitar o publish, cache de autenticação, retenção de events, gates em Redis, confirmar e dimensionar max_connections (ou PgBouncer) antes da 2ª réplica.

P8. O que é o workflow no Motor e como ele funciona? Uma receita JSON imutável por versão (motor.workflow/v1) com 11 tipos de passo: 5 expansores, que materializam filhos (map, verify, tournament, loop, switch), e 6 executáveis no worker (agent, transform, http, wait, human, workflow). No arranque, o run congela a versão, a base técnica da org e um snapshot por setup citado (D002). O run tem 3 tetos: usd (mole), maxSteps (1–10.000, contando filhos) e wallClockMs (pausas e esperas humanas descontadas). O reconciliador é o cérebro: único que enfileira passo, com lease no Postgres; o Postgres é a verdade e o BullMQ (5 filas de trabalho + wf-ping) é transporte; 3 barreiras impedem execução dupla. O passo agent reusa o runTurn com saída validada; pausar é gracioso em 3 estados; cancelar é cooperativo, com fechamento imediato se ninguém está vivo; tudo se propaga a sub-runs. Eventos saem em 3 trilhas (log append-only com seq, filas, runbus efêmero para a tela) e a UI mostra 1 cartão por fan-out. Fronteira deliberada: agent_spawn é quando o LLM decide paralelizar; workflow é quando a definição decide. Dentro de um passo, tools de subagente e de governança são negadas.

P9. Quais são as melhores práticas de mercado, com a Anthropic como referência, para multiagentes e runs de workflow, e onde o Motor está? O Motor cobre as 5 categorias da Anthropic — chaining, routing, paralelização (seções e votação), orchestrator-workers e evaluator-optimizer — e está à frente da média em reconciliação pelo banco, pause/cancel cooperativo com escape, custo de sub-run consolidado no pai e no modo assíncrono com notificação, que a Anthropic ainda lista como evolução futura. Falta: carregar tools sob demanda (tool search, defer_loading) — todo passo paga o catálogo inteiro, e um passo "trivial" custou US$ 0,25 e ~83 mil tokens; TTL de 1h de cache declarativo por setup; regras de cardinalidade e um "amortecedor" de delegação para a orquestradora; contrato de delegação completo (fronteiras, esforço, parada); evals reais com juiz LLM; tetos determinísticos por árvore; e observabilidade de cache e latência (TTFT, taxa de acerto). Tabela completa na seção 4.

Recomendação geral. O Motor é um runtime bem arquitetado, com dívidas de escala e segurança mapeadas e, nas mais graves, confirmadas. Ordem sugerida: (i) estancar custo e segurança (tetos, timeout, preço real, SSRF, segredos, reaper); (ii) destravar várias réplicas (abort, isBusy, broadcast e sessão distribuídos, banco e Redis dimensionados, cross-tenant antes de liberar troca de org); (iii) migrar o estrutural (SDK nativo, socket.io, tools sob demanda, painel de inspeção) com flags e shadow, sem big-bang. Nada exige reescrever o Motor: exige completar o que o desenho já prevê.

2. Como o Motor funciona hoje

2.1 O turno e o loop

Um turno é um ator por thread: cada thread tem lock próprio (uma conversa nunca espera outra), uma mailbox que agrupa tudo o que chegou num turno só e um loop de agente que chama o LLM em steps, via streaming SSE, sempre contra o proxy Load Balance em formato Anthropic Messages. O Motor nunca sabe provider, modelo real ou credencial: envia model: "proxy-managed" para POST {customUrl}/v1/messages, e o LB transpila, autentica e devolve SSE canônico (be/docs/contrato-load-balancer.md).

Passo a passo no caminho do chat:

1. Recebimento e fila. O WS recebe a mensagem e o dispatcher faz submit (be/src/engine/dispatcher.ts:265): rate limit por (org, usuário) só para submits externos (60/min por processo), push na mailbox (ilimitada por desenho, D4) e pump sem esperar. O drain é atômico: tudo o que estava pendente vira um turno (dispatcher.ts:143-151).
2. Lock e preparo. O pump pega o lock da thread no registry (memória ou Redis com TTL de 30s e heartbeat de 10s) e chama runTurn (be/src/engine/turn-runner.ts:427). O prepareTurn lê a thread e a config efetiva (global < setup < thread) e congela tudo numa linha Turn, para auditoria e replay.
3. Compactação na fronteira, antes do LLM (turn-runner.ts:524-548). O gatilho olha a ocupação medida no fim do turno anterior (thread.metadata.contextTokens). Se passou de window × compactAt (padrão 230 mil × 0,9), o compactador resume o histórico antigo, persiste um evento compaction e o LLM passa a ver [resumo] + eventos novos. Falha aqui nunca derruba o turno; após 3 falhas seguidas, escala alerta.
4. Bootstrap do agente (turn-runner.ts:650 e be/src/agent/bootstrap.ts). Monta o model (placeholder proxy-managed), o system prompt (base + apêndice do setup + voz), conecta os MCPs em paralelo (falha de um não trava os outros) e soma as tools nativas (subagentes, workflows, setups). A toolPolicy do setup recorta as tools. Um metadata.user_id estável por conversa maximiza o cache no proxy.
5. Persistência da entrada (turn-runner.ts:704-798). Primeiro as notificações de subagentes (uma mensagem sintética combinada), depois cada mensagem do usuário, cada uma como evento append-only. Pré-cheque do orçamento mensal da org (Redis, em USD e/ou tokens): estourou, aborta antes de chamar o LLM.
6. O loop (be/src/agent/loop.ts:402, runAgent). Monta messages com breakpoints de cache (system + pontos do histórico, até 4 por request; tools via interceptor), poda ou reanexa thinking antigo, reserva 1 slot no gate da org e chama streamText do pacote ai v5 com stopWhen: stepCountIs(maxSteps ?? 999), maxRetries ?? 3 e o abortSignal do turno. A cada step: o modelo gera texto e/ou tool calls, as tools executam, onStepFinish soma o usage à mão e emite onStep para a timeline ao vivo. Entre steps, o prepareStep checa o orçamento e drena notificações novas da mailbox, reenviando um buffer acumulado. O aborto tem rede dupla: reason com nome AbortError (o único que o SDK reconhece) e uma guarda de 5s que encerra à força.
7. Persistência da resposta e fechamento (turn-runner.ts:1091-1271). gravarRespostas planeja os eventos por passo (reasoning só para exibição → mensagens limpas com tool-calls reparadas → step_done), grava, registra o usage no bucket de custo da org, mede a ocupação pelo usage do último step e fecha o Turn (done, ou errored se um turno humano saiu vazio). Em falha no meio, o parcial dos steps fechados é gravado antes de classificar o erro (orçamento, cancelamento, timeout, provider 4xx/5xx, MCP, interno).

Caminho dos workflows: runAgentStep (be/src/engine/agent-step.ts:534) é uma casca sobre runTurn sem mailbox: cria ou continua uma thread headless, segura o lock durante as rodadas (original + reparos de schema, padrão 1), acumula deltas token a token, soma usage e custo e devolve saída validada ou falha tipada (inclui timeout próprio e mcp_indisponivel antes de gastar).

flowchart LR
    WS[WS: user_message] --> SUB[dispatcher.submit<br/>rate limit + mailbox.push]
    SUB --> LOCK[pump: lock da thread<br/>Redis TTL 30s + heartbeat]
    LOCK --> PREP[prepareTurn<br/>config global, setup, thread<br/>congelada no Turn]
    PREP --> COMPACT{ocupação acima de<br/>window x compactAt?}
    COMPACT -->|sim| SUM[compactador resume<br/>evento compaction]
    COMPACT -->|não| BOOT[bootstrap<br/>model + system + MCPs + nativas<br/>toolPolicy]
    SUM --> BOOT
    BOOT --> PERSIST[persiste notificações e<br/>user_messages + pré-cheque de orçamento]
    PERSIST --> LOOP[runAgent: streamText v5<br/>até 999 steps · prepareStep<br/>orçamento + drain no meio do turno]
    LOOP --> SAVE[gravarRespostas por passo<br/>usage + contextTokens]
    SAVE --> DONE[finishTurn done ou errored<br/>evento final + limpa o ao vivo]

Arquivos-chave: be/src/agent/loop.ts, be/src/engine/turn-runner.ts, be/src/engine/dispatcher.ts, be/src/engine/agent-step.ts, be/src/agent/bootstrap.ts, be/src/provider/anthropic.ts, be/src/agent/messages.ts, be/src/agent/compaction.ts, be/src/engine/response-events.ts, be/src/engine/org-concurrency.ts, be/src/engine/cost-tracker.ts, be/src/engine/registry.ts, be/src/engine/registry-redis.ts, be/docs/contrato-load-balancer.md.

2.2 Tools e system prompt

O prepareTurn (be/src/engine/turn-runner.ts:346) calcula a config efetiva com loadEffectiveConfig (be/src/setups/service.ts:763): global da org (OrgConfig no Postgres) < setup da conversa (Agent.configOverride + persona + toolPolicy) < override legado da thread (metadata.config), fundidos por resolveEffectiveConfig (be/src/config/thread-config.ts:473). O bootstrapTurn monta o que o modelo vai ver:

1. buildNativeTools: 23 tools in-process (4 de subagente, 4 de setup, 15 de workflow);
2. bootstrapAgent (be/src/agent/bootstrap.ts:51): conecta os MCPs da config em paralelo via pool (acquireMcp, be/src/tools/mcp-pool.ts:136) e filtra cada um pela allowlist mcps[].tools (filterMcpTools, be/src/tools/registry.ts:28);
3. buildMcpTools (registry.ts:67): junta tudo num Record único com as nativas, em ordem alfabética, para o prefixo ficar byte-idêntico e o cache render;
4. applyToolPolicy (registry.ts:125): recorta pela toolPolicy do setup.

O Record final vai inteiro, a cada step, no tools do streamText (be/src/agent/loop.ts:499); o SDK serializa cada tool como {name, description, input_schema} sem validar nem limitar o tamanho.

O system prompt é montado no bootstrapAgent (linhas 66-95) em camadas: base (cfg.systemPrompt inline ou o arquivo be/system-prompt.md, 25,9 mil chars, lido do disco a cada turno) + systemPromptAppend efetivo (append da org + persona do setup concatenados, ou um override da thread ou do setup que substitui tudo) + bloco de voz (só no modo voz, be/src/agent/voice-prompt.ts:88). Entra como primeira message de role system (buildMessages, be/src/agent/messages.ts:72) com cache_control; o interceptor do provider (be/src/provider/anthropic.ts:178) pode marcar a última tool com breakpoint de cache. Durante o turno, o prepareStep (turn-runner.ts:956) injeta notificações de subagentes e workflows como message sintética de role user ([NOTIFICAÇÃO DO SISTEMA], be/src/engine/mailbox.ts:232). No fim, o usage do último step mede a janela (turn-runner.ts:1180) e pode disparar a compactação no turno seguinte.

flowchart TD
    CFG[loadEffectiveConfig<br/>org, setup, thread] --> NAT[buildNativeTools: 23 nativas]
    CFG --> MCP[acquireMcp em paralelo<br/>listTools por servidor]
    MCP --> FIL[filterMcpTools<br/>allowlist mcps.tools opcional]
    FIL --> MERGE[buildMcpTools<br/>Record único em ordem alfabética]
    NAT --> MERGE
    MERGE --> POL[applyToolPolicy do setup]
    CFG --> SYS[system: base + append efetivo + voz]
    POL --> REQ[streamText a cada step<br/>system + messages + tools inteiras]
    SYS --> REQ

Interpolação existe em três lugares distintos: ${VAR} de ambiente só no chat-config.json em disco (be/src/config/load.ts:57; não vale para config no banco); token de MCP virando Authorization: Bearer no resolver (thread-config.ts:329-342); e ${...} das expressões de workflow (interpretador próprio, fora do chat).

2.3 Agente e subagentes

O pai chama agent_spawn (title, task e, opcionalmente, systemPrompt, tools e setupId). O orchestrator cria a thread filha (kind: subagent) num único INSERT (be/src/engine/orchestrator.ts:234-249), herdando metadata.config do pai — mesma sandbox, mesmos MCPs, mesma rota —, mas nunca o system prompt do pai (orchestrator.ts:175-184). Com setupId explícito, valida o setup (ativo, não arquivado, visível) e injeta a persona uma vez no systemPromptAppend do filho; sem setupId, o filho só herda o agentId e roda sem a persona (orchestrator.ts:186-223). O spawn retorna logo após dispatcher.submit com trigger spawn; a tarefa vira a primeira user_message do filho, que roda com thread e lock próprios, em paralelo real.

Quando o filho termina um turno com a mailbox vazia, onTurnEnd faz o claim exactly-once (updateMany onde notifiedParentAt é nulo, orchestrator.ts:317-321), monta o SubagentResultItem (status, finalText integral, steps, duração, tokens, irmãos ainda rodando) e empurra na mailbox do pai. Pai ocioso: abre turno com trigger subagent_notification. Pai rodando: o prepareStep drena só as notificações e injeta no meio do turno. N notificações juntas viram 1 turno (drain atômico com FOR UPDATE SKIP LOCKED, be/src/engine/mailbox-db.ts:98-146). Falha vira notificação errored; pai deletado entre claim e push dispara rollback com evento lost_notification; crash de processo depende do reaper, que é opt-in e está desligado em produção.

sequenceDiagram
    participant Pai
    participant Mail as Mailbox do pai
    participant Filha
    Pai->>Filha: agent_spawn: thread filha + primeira user_message
    Note over Pai: retorna na hora, sem esperar
    Filha->>Filha: turnos próprios, com lock próprio
    Filha->>Mail: onTurnEnd: claim exactly-once + subagent_result
    alt pai ocioso
        Mail->>Pai: turno novo, trigger subagent_notification
    else pai rodando
        Mail->>Pai: prepareStep drena e injeta no meio do turno
    end

Na UI, o filho aparece inline na timeline do pai. O desenho prevê fan-out dos eventos do filho para a sala da raiz (be/src/ws/handler.ts:234-251), mas na prática o progresso do filho não chega à sala do pai — só spawn e result, emitidos direto (achado confirmado em 3.2) —; o modal de subagente compensa com polling de 2s.

2.4 Workflows

Um workflow é uma receita JSON imutável por versão (schema: "motor.workflow/v1"; be/src/workflows/definition.ts, 1911 linhas, 11 tipos de passo). Cada versão publicada vira uma WorkflowVersion. O run congela versionId, a base técnica da org (orgConfigSnapshot), um snapshot por setup citado (setupSnapshot.__porSetup[setupId]) e o setup padrão (__padrao) quando algum passo de IA fica sem setupId (D002, be/src/workflows/runs.ts:57-179, 252-267, 404-436). O input é validado contra o schema da versão antes de qualquer cobrança, e a idempotencyKey é única por org (repetir o POST devolve o mesmo runId).

Os 11 tipos. Cinco expansores, que materializam filhos em vez de ir para a fila: map, verify, tournament, loop, switch (be/src/workflows/expanders.ts). Seis executáveis, que rodam no worker: agent, transform, http, wait, human, workflow (be/src/workflows/executors.ts). Só agent cobra dinheiro: usa a ponte runAgentStep com saída estruturada validada (1 reparo) e propaga usage e custo na mesma transação que fecha o passo. O loop roda uma iteração por vez; tournament tem bye e empate (A vence); switch decide no tick e marca os outros ramos como skipped.

Orçamento por run: usd (mole; 0 = tolerância zero), maxSteps (1–10.000 contando filhos; o expansor falha com fanout_excede_maxsteps antes de criar) e wallClockMs (espera humana e pausas descontadas por união de janelas).

Ciclo de vida. O reconciliador é o único que enfileira passo (be/src/workflows/reconcile.ts): cada tick segura o run por lease no Postgres (30s, claim atômico com a condição do run dentro do UPDATE), materializa o que desbloqueou, enfileira o que está pronto (em lote, respeitando a concorrência do fan-out, 1–200, padrão 100) e fecha o run. Quem executa é o motor-worker-ws, processo separado, com workers dedicados às filas wf-reconcile, wf-step-ai, wf-step-det, wf-notify, wf-maintenance e wf-ping. Três barreiras impedem execução dupla: jobId determinístico (step:<stepId>:<attempt>), claim condicional e @@unique([stepId, attempt]); e um passo com output gravado nunca reexecuta. A recuperação é por batimento: tentativa sem heartbeat por 45s vira lost e volta para pending; run sem progresso por 120s fecha como run_travado.

Pausar, retomar, cancelar. Pausar é gracioso: running → pausing → paused (a porta fecha antes de contar o que está em voo). Retomar restaura waiting se ainda há portão humano aberto. Cancelar é cooperativo: se há worker vivo, marca a bandeira e espera; se ninguém está vivo, fecha na hora. Tudo se propaga recursivamente a sub-runs; o custo do filho sobe ao pai uma vez só.

Eventos e tela. Três trilhas: workflow_events (log append-only, seq monotônico por UPDATE … RETURNING), filas BullMQ duráveis e runbus:* no Redis Pub/Sub (efêmero, para o WS). O canal WS do run coalesce step_partial a 2 Hz e libera até 8 passos em foco. A tela agrupa os filhos de um fan-out num cartão com histograma: "40 revisores" é uma linha só.

Fronteira com subagentes (intencional). Dentro de um passo, as tools de subagente são negadas (o filho sobreviveria ao run e furaria o orçamento; paralelismo dentro de workflow é map/fan-out orçado), e as de governança (workflow_run, pause, resume, decide, cancel) também (um passo não aprova o próprio portão).

flowchart TD
    AUT[autoria: create, draft, add_step, validate] --> PUB[publicação: versão imutável]
    PUB --> ADM[startRun: valida input<br/>congela setups e org<br/>idempotencyKey]
    ADM --> TICK[reconciliador: tick com lease de 30s<br/>materializa e enfileira]
    TICK --> AI[wf-step-ai: passo agent<br/>runAgentStep com saída validada]
    TICK --> DET[wf-step-det: transform, http, wait]
    TICK --> HUM[human: portão, run em waiting]
    AI --> BAR[barreira no banco<br/>expected e completed]
    DET --> BAR
    HUM --> BAR
    BAR --> TICK
    BAR --> AVISO[aviso para a conversa de origem]

2.5 Tempo real

Há dois canais WebSocket nativos (sem socket.io e sem SSE no app) numa rota só, GET /ws (be/src/plugins/websocket.ts:94): ?thread= vai para o canal de chat (be/src/ws/handler.ts) e ?run= para o canal de workflow (be/src/ws/run-channel.ts). A identidade nunca vem da query: o hook de auth (be/src/http/auth.ts:7-27) autentica no upgrade por bearer de máquina, cookie de sessão da Conta ou ?ticket= de uso único, e cada socket ganha um connId.

Canal de thread. O front abre 1 socket por thread ativa (fe/src/features/thread-runtime/model/use-thread-runtime.ts:90) com o cliente fe/src/api/ws.ts: backoff exponencial de 1s a 15s, sem jitter; fila de envio de 100 itens/256 KB; watchdog que fecha o socket após 60s sem frame. Ao conectar, o servidor resolve a thread, entra na sala, manda connected e reemite tudo: replay do histórico persistido mais o turno em andamento, vindo do buffer vivo no Redis. Durante o turno, o engine emite para a sala da thread e para a da raiz. O chat não faz streaming token a token: assistant_partial sai uma vez por step com o texto inteiro; deltas existem só como opção usada pelo executor de workflow. O thread_busy (início e fim de turno, e batimento de 25s enquanto ocupado) vai só para os sockets do dono, e a sidebar mantém um segundo socket por aba só para ouvi-lo.

Canal de run. O passo roda no worker e o socket está na API, então os frames atravessam processos por Redis Pub/Sub (be/src/workflows/bus.ts): o worker publica em <prefixo>:runbus:<runId> e cada réplica da API faz um psubscribe global e filtra por run. O front recebe run_connected (estado completo), run_status, step_status, step_output, run_done e step_partial.

↑ voltar ao índice

Na reconexão do chat, o front refaz o histórico por REST e poda o buffer ao vivo por turnId; turnos fechados sem conteúdo disparam um catch-up por seq.

Várias réplicas (ponto central). O broadcaster é 100% em memória (be/src/ws/broadcaster.ts:59-65); o isBusy enxerga só a réplica local (be/src/engine/registry-redis.ts:154); o abort entre réplicas publica num canal que ninguém assina (registry-redis.ts:156-167); o fechamento de sockets no fim de sessão só alcança o processo atual (be/src/auth/session.ts:104-113). Já são distribuídos: o lock de turno (Redis com TTL e heartbeat), o buffer vivo (Redis com TTL), a mailbox (Postgres com drain atômico) e o barramento de runs.

2.6 Dados e cache

Caminho do turno no banco. Mensagem → dispatcher.submit → mailbox.push (1 leitura thread.findUnique + 1 escrita mailboxItem.create, be/src/engine/mailbox-db.ts:75-96) → pump() (hasPending → tryAcquire com SET NX e TTL de 30s → drain atômico com FOR UPDATE SKIP LOCKED → runTurn → release em Lua). Dentro do runTurn: prepareTurn (getThread com cache Redis + loadEffectiveConfig + startTurn, que faz UPDATE threads.last_turn + INSERT turn numa transação) → compactação → bootstrap → registry.getConvo (conversa em memória, turn-runner.ts:705) → 1 appendEvent por mensagem (apaga o cache, transação UPDATE last_seq + INSERT event e escrita pós-commit no Redis via outbox com retry) → pré-check de orçamento (Redis HGETALL com espelho local de 1,5s) → runAgent (1 slot de concorrência da org pelo turno inteiro) → a cada step, prepareStep com checagem de orçamento e drainNotifications (1 UPDATE) → respostas (1 appendEvent por mensagem + reasoning e step_done) → finishTurn → onTurnEnd.

Cache de events. Por thread, um ZSET (score = seq) + HASH de payloads + sentinela synced, com janela quente de 200 events (trim a cada push, TTL de 1800s). Se a janela não cobre o pedido, lê do Postgres sem re-hidratar. O histórico para o LLM é reconstruído por eventsToLlmMessages (respeita o último checkpoint de compactação, be/src/agent/history.ts:102-120), mas só no connect do WS e depois de compactar; durante o turno vale o getConvo em memória.

Fila de workflows (BullMQ): transporte, com a verdade no Postgres — lease do reconciliador, claim condicional, heartbeat de tentativa a cada ~15s, varredura de órfãos a cada 30s em lote de 200, purga horária de workflow_events e retenção diária (threads na lixeira 30 dias, mailbox consumida 7, entregas de webhook 90, runs 180).

Topologia de produção medida (investigação de lacunas):

↑ voltar ao índice

Logs do motor-be-ws: 115 requests, todas com status 200, p50 de 0,8 ms, p99 de 1.250 ms, máximo de 2.188 ms; três avisos [mcp-pool] LEAK detected (browser, agentpack, mp).

3. Achados por área

Formato: os achados revisados (originalmente crítica ou alta) aparecem em blocos com evidência, impacto, recomendação, esforço e a nota do revisor. Os não verificados (média, baixa, info) aparecem em tabela, com evidência, impacto e recomendação curtos. Os refutados estão em 3.9.

3.0 Temas transversais (o mesmo fato em várias dimensões)

Vários problemas foram achados por mais de um scanner. Esta tabela junta as leituras, inclusive quando os revisores divergiram.

↑ voltar ao índice

3.1 Loop do agente e SDK

[crítica · confirmado; sev. contestada alta→crítica] loop-sdk-abort-cross-replica — Aborto entre réplicas perde as flags e vira "Erro do provider" · Esforço P

• Evidência: be/src/engine/registry-redis.ts:163-164 (publish só com {threadId, message}); be/src/engine/turn-runner.ts:1285-1319 (classifica o erro por isBudgetExceeded, isUserCancel, isTurnTimeout); turn-runner.ts:1352 (turnsFailed.inc() para tudo que não é cancelamento do usuário); be/src/engine/orchestrator.ts:457-458 e be/src/engine/server/index.ts:346-348 (cascade e shutdown usam o mesmo caminho).
• Impacto: com 2 ou mais réplicas, Parar, timeout, orçamento ou cascade que caiam fora da réplica dona não abortam nada, porque não há assinante; e, mesmo com assinante, a causa tipada se perderia: a UI mostraria "Erro do provider", a métrica de falhas inflaria e o workflow retentaria o que não devia. Hoje latente (produção roda 1 réplica).
• Recomendação: assinar <prefixo>:abort em todas as réplicas, serializar o AbortReason com as flags e reconstruir o AbortError na dona; logar quando o publish não tiver efeito; teste de integração com 2 réplicas.
• Revisão: mais grave que o descrito — o canal nem tem assinante (grep em be/src: só runbus:* e launcher-wake), e os comentários de registry-redis.ts:22-26 e be/src/engine/registry.ts:37 descrevem um desenho não implementado.

[alta · confirmado] loop-sdk-usage-cache-creation — cache_creation_input_tokens fica fora do usage, do contexto e do custo · Esforço M

• Evidência: be/src/agent/loop.ts:470-479 (soma só input, output, cached e reasoning); be/src/engine/turn-runner.ts:1180 (contextTokens = input + cached); be/src/engine/cost-tracker.ts:86-91, 141-148, 150-157 (sem campo de criação); be/src/engine/agent-step.ts:887-893; be/docs/contrato-load-balancer.md:58 (total = input + leitura + criação de cache). grep por cacheCreation|cache_creation|providerMetadata em be/src: zero ocorrências.
• Impacto: contexto submedido (a compactação dispara tarde), custo subfaturado e orçamento furado justamente nas threads que mais escrevem cache. Pela documentação de prompt caching, a escrita custa mais que o input normal (1,25x no TTL de 5 min; 2x no de 1h).
• Recomendação: ler providerMetadata.anthropic.cacheCreationInputTokens por step e somar em contextTokens, custo e orçamento; no loop nativo, ler os três contadores direto do SSE.

[alta · confirmado] loop-sdk-timeout-zero — Sem timeout padrão, um stream pendurado prende lock e slot para sempre · Esforço P

• Evidência: be/src/config/schemas.ts:386 (turnTimeoutMs padrão 0); be/chat-config.json:32 (0 no config padrão); be/src/engine/turn-runner.ts:460-485 (o relógio só existe se > 0); be/src/provider/anthropic.ts:159-197 (fetch sem timeout); be/src/engine/registry-redis.ts:103-128 (o heartbeat renova o lock); be/src/engine/reaper.ts:153 (o reaper ignora turno vivo no próprio processo).
• Impacto: provider que não fecha o stream (socket meio aberto, proxy travado) sem ninguém clicar em Parar = thread travada, lock mantido e slot vazado até reiniciar. As tools têm timeout (60s); o LLM não. A guarda de 5s só age depois que alguém aborta.
• Recomendação: padrão maior que zero no chat (ex.: 30–60 min) ou detector de stall (N minutos sem evento SSE aborta o step); timeout explícito no fetch ou no SDK.
• Revisão: o audit interno do dono já registrava o cenário (TURN-07 como alto; RATE-004 e CONFIG-13 como médios).

[alta · confirmado] loop-sdk-maxsteps-999 — Teto de 999 steps permitiu um turno real de ~14 milhões de tokens · Esforço P

• Evidência: be/src/agent/loop.ts:508; be/src/engine/dispatcher.ts:158-170 (o chat chama runTurn sem maxSteps); be/src/engine/turn-runner.ts:224-229, 940-952; be/src/engine/agent-step.ts:689 e be/src/workflows/executors.ts:340-343 (o limite de workflow depende de WF_AGENT_MAX_TOOL_STEPS, ausente do .env.example); log de produção do motor-be-ws: 81 responseMessages (~41 rodadas de tool), input 2.633.801 + output 23.622 + cached 11.340.563, terminou em overloaded_error.
• Impacto: um laço de tool queima milhões de tokens num turno só; quem parou o turno real foi o proxy sobrecarregado, não o teto. O costBudget é mensal por org e opcional, não um teto por turno.
• Recomendação: padrão menor (ex.: 50) configurável por setup, teto de tokens por turno com encerramento gracioso e alerta ao passar de N steps.

[alta · confirmado] loop-sdk-sideeffect-retry — sideEffectWrite promete 3 tentativas e executa uma · Esforço P

• Evidência: be/src/engine/turn-runner.ts:91-104 (recebe promise: Promise<unknown>, já iniciada); turn-runner.ts:105-131 (await promise sobre a mesma promise a cada tentativa); chamadores nas linhas 562, 823, 1017, 1202 e 1365; nenhum teste do helper.
• Impacto: "3 tentativas com backoff de 200 e 600 ms" vira 1 tentativa e ~800 ms parado. Um soluço de banco ou Redis que um retry real salvaria vira aviso e divergência entre cache e banco em título automático, contextTokens, compactação, notificação no meio do turno e finishTurn.
• Recomendação: receber uma função (() => Promise) e chamá-la a cada tentativa, mantendo o respeito ao abortSignal; cobrir com teste.

[alta · confirmado] loop-sdk-p07-injeta-sem-persistir — Notificação no meio do turno é injetada mesmo quando a gravação falha · Esforço M

• Evidência: be/src/engine/turn-runner.ts:1017-1030 (usa sideEffectWrite, que nunca lança); turn-runner.ts:1031-1038 (push e emit incondicionais); turn-runner.ts:1004-1011 (o comentário diz o contrário); be/src/engine/mailbox-db.ts:132-145 (o drain já marcou consumed_at); não existe reenfileiramento.
• Impacto: falha de banco no meio do turno faz o LLM reagir a uma notificação que não está no banco e já saiu da mailbox; um restart a perde para sempre.
• Recomendação: sideEffectWrite devolver sucesso ou falha; só injetar e emitir se persistiu; em falha, reenfileirar na mailbox.

[média · confirmado; sev. contestada alta→média] loop-sdk-preco-fixo — Preço fixo de Sonnet para qualquer rota deixa o teto em USD aproximado · Esforço M

• Evidência: be/src/engine/cost-tracker.ts:118-120 (3 / 15 / 0,3 USD por milhão, por env); cost-tracker.ts:64-67 (a aproximação está documentada); cost-tracker.ts:93-98, 372-377 (há também teto em tokens, independente de preço); be/docs/contrato-load-balancer.md:14 (o Motor nunca sabe o modelo).
• Impacto: se o LB rotear para um modelo mais caro ou mais barato, o teto em USD erra para cima ou para baixo, e o custo exibido mente na mesma direção. Quem cobra por uso não pode confiar no número.
• Recomendação: preço por rota ou setup, ou o LB informar modelo e custo no SSE; até lá, tratar o teto em tokens como o autoritativo.
• Revisão: rebaixado porque o teto em tokens é uma rede independente de preço e os preços são ajustáveis por env sem deploy — aproximado, não fictício.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas medidas (loop):

• Tamanho em linhas: turn-runner.ts 1583; agent-step.ts 956; loop.ts 654; compaction.ts 473; org-concurrency.ts 263; provider/anthropic.ts 227; bootstrap.ts 187; response-events.ts 175; messages.ts 107; contrato-load-balancer.md 74.
• Versões: produção instala pelo be/package-lock.json (ai 5.0.253, @ai-sdk/anthropic 2.0.101); o lock da raiz (5.0.179 e 2.0.77) atende dev e CI e é o que está no node_modules da sandbox.
• Gate por org: até 100 chamadas em voo por processo; backoff de 30s, teto de 120s; circuit abre por 90s após 3 respostas 429/503 em 60s.
• Loop: stopWhen 999; maxRetries 3 (o padrão do SDK é 2); guarda de aborto de 5s. Retry instalado: 2s inicial, fator 2, respeita retry-after; só erro marcado como retentável retenta; abort nunca retenta.
• Turno: turnTimeoutMs 0; sideEffectWrite com 0, 200 e 600 ms; compactação em 230 mil × 0,9, keepTurns 4, saída do compactador de 8 mil tokens.
• Cache padrão: TTL de 5 min em system, tools e messages; cacheTools ligado; markLastUser e markLastAssistant desligados; checkpoint acima de 20 mensagens.
• Contrato com o LB: proxy-managed, max_tokens 64000, stream sempre, thinking adaptativo resumido, effort alto.
• Lock e registry: TTL de 30s com heartbeat de 10s; convo com TTL de 3600s; buffer ao vivo com 900s; reaper de órfãos em 30 min (desligado).
• Custo: 3 / 15 / 0,3 USD por milhão; espelho local de 1,5s; bucket com TTL de 70 dias. Compactador: transcript de até 300 mil chars.
• MCP: chamada de tool 60s; conexão e listagem 30s.
• Produção (motor-be-ws): turno com 81 responseMessages e ~14 milhões de tokens até overloaded_error; dezenas de warnings "unsupported reasoning metadata" e "System messages"; 362 tools num turno (76 + 70 + 193 de MCP + 23 nativas); 3 avisos [mcp-pool] LEAK detected. motor-worker-ws: só o boot, sem erros de turno na janela.

3.2 Tempo real (backend e frontend)

[alta · confirmado] tempo-real-broadcast-local — Broadcaster 100% em memória: a 2ª réplica quebra o chat ao vivo · Esforço G

• Evidência: be/src/ws/broadcaster.ts:59-65 (clientes, salas e donos em Map/Set locais); be/src/ws/handler.ts:234-239 (o emit só alcança as salas do processo); be/src/engine/dispatcher.ts:265-303 (o turno roda na réplica que fez o pump); be/src/ws/run-channel.ts:10-12 (o código admite que o canal de thread assume turno e socket no mesmo processo).
• Impacto: com 2 réplicas, quem está conectado na outra vê o turno "congelado" até um F5 ou o polling recuperar. Escalar a API, o caminho para alto volume, quebra o tempo real de forma intermitente.
• Recomendação: salas distribuídas (socket.io + Redis adapter) ou publicar os eventos de turno no Redis e assinar em todas as réplicas, como já faz o runbus, mantendo o gate de tenant DM-17.
• Revisão: latente hoje (compose.prod.yml sem réplicas); bloqueia a escala horizontal.

[alta · confirmado; contestado entre dimensões] tempo-real-busy-local — isBusy enxerga só a réplica local, mas alimenta REST, handshake e árvore · Esforço M

• Evidência: be/src/engine/registry-redis.ts:154 (isBusy: (threadId) => local.has(threadId)); consumidores em be/src/routes/threads.ts:114, be/src/routes/agents.ts:480, 541 e be/src/ws/handler.ts:419, 467; be/src/engine/reaper.ts:23-26, 153, 181 (o reaper usa o mesmo isBusy, e o comentário admite que só vale com 1 processo).
• Impacto: com 2 ou mais réplicas, o "rodando" da sidebar, da lista e do handshake oscila ou some; o polling do subagente pode parar cedo; o reaper de uma réplica pode declarar órfão um turno vivo em outra.
• Recomendação: derivar o busy do lock distribuído (EXISTS na chave do Redis), com fallback local se o Redis falhar.
• Revisão: o revisor desta dimensão manteve alta; o da dimensão de dados rebaixou para média (o doc oficial classifica como médio) e não o tratou como bug ativo. Há mitigação parcial no front só para o rótulo da árvore.

[alta · confirmado] tempo-real-sessao-outra-replica — Sessão encerrada fecha sockets só na réplica local · Esforço P

• Evidência: be/src/auth/session.ts:104-113 (o comentário admite "só neste processo"); be/src/plugins/websocket.ts:74-92 (mapa local de sockets por sessão); be/src/ws/handler.ts:452-460, 486-559 (identidade fixada no handshake e nunca revalidada); fe/src/api/ws.ts:470.
• Impacto: logout ou revogação com 2 ou mais réplicas deixa sockets abertos nas outras, recebendo eventos da conta; com tráfego ativo, por bem mais de 1 minuto.
• Recomendação: publicar o fim de sessão no Redis para cada réplica fechar os seus sockets; revalidar a sessão periodicamente no socket.

[alta · confirmado] tempo-real-watchdog-reconecta-ocioso — Toda aba ociosa reconecta cerca de 1 vez por minuto · Esforço P

• Evidência: fe/src/api/ws.ts:469-498 (sem frame em 60s, fecha) e 527-536, 555, 575-593 (reconecta com o backoff zerado); be/src/ws/busy-heartbeat.ts:14, 25-32 (o único batimento só existe com a thread ocupada); be/src/ws/handler.ts:131-133 (o comentário admite o ciclo); o servidor não emite ping.
• Impacto: socket ocioso é derrubado e reaberto a cada ~61s, para sempre, em todas as abas, cada vez com handshake completo (events, config, replay). O servidor não distingue cliente caído de cliente ocioso.
• Recomendação: ping/pong real ou keepalive barato vindo do servidor; pausar o watchdog com a aba oculta; no socket.io, usar o heartbeat nativo.

[alta · confirmado] tempo-real-handshake-repete-historico — Cada (re)conexão relê a thread inteira e a reenvia para o cliente descartar · Esforço M

• Evidência: be/src/ws/handler.ts:396 (getEvents sem limite a cada abertura), 302-304 e 429 (replay de tudo); be/src/persistence/events.ts:247-250 ("por padrão, TUDO"); fe/src/features/thread-runtime/model/runtime.ts:139-140 (o front ignora o replay não inflight); use-thread-runtime.ts:11, 107-109 (o REST da reconexão é paginado em 100).
• Impacto: a cada reconexão — cerca de 1 por minuto por aba ociosa — o servidor relê e serializa a thread inteira para o cliente jogar fora; em threads longas (o código cita 15 mil+ events), megabytes por minuto por aba. O custo é do servidor; a UI não trava (ver o refutado em 3.9).
• Recomendação: handshake magro (connected + buffer vivo + seq); histórico 100% por REST; replay só do que vier depois do seq informado pelo cliente.

[alta · confirmado] tempo-real-dialog-estoura-ratelimit — Modal de subagente e lista estouram o teto de 30 req/min por IP com uma aba · Esforço P

• Evidência: fe/src/components/subagent-sidebar/model/use-subagent-events.ts:30 (2s = 30/min); fe/src/features/subagent/model/queries.ts:106-120 (status a cada 3s = 20/min); fe/src/features/thread/model/queries.ts:39 (lista a cada 8s = 7,5/min); be/src/routes/threads.ts:88-92, 102, 630, 783 (essas rotas têm 30 req/min por IP); be/src/server/index.ts:181-206 (chave por IP); be/src/routes/workflows.ts:198-202 (o código admite que o certo é limitar por token).
• Impacto: com uma aba e o modal aberto num subagente rodando, só as rotas com teto de 30/min recebem ~57 req/min; somando árvore e graph, ~90 req/min por aba. Parte dos polls toma 429 e o retry do cliente reinjeta a request. Atrás de NAT, poucas pessoas se derrubam umas às outras.
• Recomendação: curto prazo, espaçar o modal (2s → 4s) e/ou subir o teto dessas rotas; estrutural, push pelo WS (F3) e limite por token ou sessão em vez de IP.
• Revisão: o quadro é pior que o descrito no achado; o cliente usa retry: 1 (não 3).

[alta · confirmado] tempo-real-runs-lista-explosao — A tela de runs dispara até 11 queries a cada 5s por aba · Esforço M

• Evidência: fe/src/features/runs/components/RunsListPage.tsx:142-148 (até 11 hooks); fe/src/features/run/model/queries.ts:60-66, 87-95 (5s com run vivo; 1 status = 1 request); be/src/routes/workflows.ts:505-582 (cada listagem faz findMany + count + groupBy) e 109-123 (o backend já aceita vários status numa chamada); workflows.ts:204 (600 req/min por IP).
• Impacto: no recorte "ativos", até 132 req/min por aba, cada uma com 2–3 consultas ao Postgres; poucas abas no mesmo IP chegam ao teto; com 100 operadores, ~13 mil req/min só nessa tela. Para quando não há run vivo.
• Recomendação: unificar contadores e lista numa query só (o backend já aceita lista de status); depois, push de run.status (F4).

[alta · confirmado] tempo-real-events-canal-sem-ouvinte — Todo evento persistido é publicado num canal Redis que ninguém assina · Esforço P

• Evidência: be/src/persistence/events.ts:105-113 (publish do JSON inteiro dentro do MULTI); be/src/persistence/keys.ts:60-62; os únicos assinantes do backend são runbus:* (be/src/workflows/bus.ts:142) e launcher-wake (be/src/ws/handler.ts:259), além de um smoke de teste.
• Impacto: cada appendEvent paga serialização e publish sem consumidor, no caminho mais quente do motor.
• Recomendação: remover o publish até haver consumidor, ou usá-lo como base do broadcast distribuído (um assinante por réplica alimentando as salas).

[alta · confirmado] tempo-real-mapas-sem-teto — Mapas em memória sem expiração crescem com o uso · Esforço P

• Evidência: be/src/ws/handler.ts:212 (rootOf nunca apaga); be/src/ws/busy-owner.ts:34, 41, 46 (owners nunca apaga); be/src/engine/registry-redis.ts:72, 178-180 (convoCache sem TTL; só sai quando fecha o último socket); registry-redis.ts:216, 254, 257 (espelho do turno de outra réplica); docs/motor-agent-prod-readiness/api.html:484-488 (o doc já recomenda LRU com TTL).
• Impacto: memória cresce por thread tocada até o restart, com dados velhos (dono e conversa de horas atrás).
• Recomendação: TTL ou LRU nesses mapas e limpeza do espelho quando o lock sumir.

[alta · confirmado] tempo-real-dedupe-so-local — Dedupe de envio não vale entre réplicas; a mailbox não tem unique · Esforço M

• Evidência: be/src/ws/handler.ts:177-205 (seenClientMessageIds em memória) e 656-658 (esquecido no close); be/src/engine/mailbox-db.ts:87-95 (insert sem checagem); be/prisma/schema.prisma:329-356 (MailboxItem sem coluna nem unique de clientMessageId); docs/api-terceiros.md:595-596 (problema já conhecido).
• Impacto: envio → queda → reconexão em outra réplica (ou depois de um restart) enfileira a mesma mensagem de novo: turno duplicado e o usuário paga duas vezes; o dedupe do front só esconde a duplicata na tela.
• Recomendação: coluna clientMessageId com unique (threadId, clientMessageId) e insert tolerante a conflito, ou checagem no Redis antes do push.

[alta · confirmado] tempo-real-protocolo-sem-versao — Protocolo sem versão: deploy be/fe acoplado e eventos novos invisíveis · Esforço M

• Evidência: fe/src/api/ws.ts:242-259, 360-365 (tipo desconhecido vira null e uma métrica que ninguém lê); fe/src/features/thread-runtime/model/runtime.ts:207-215 (switch exaustivo); be/src/engine/turn-runner.ts:617, 919, 1068, 1157, 1165 (emite compaction_failed, persistence_warning e turn_empty, que o front não conhece); fe/src/features/run/model/events.ts:139-150 (o parser do run só faz cast); nenhum campo de versão no envelope.
• Impacto: backend à frente do front = eventos descartados em silêncio (3 tipos já são); deploy independente de be e fe fica arriscado; frame malformado passa no canal de run.
• Recomendação: campo v nos frames, catálogo único be/fe com regra aditiva, validação no parser do run e unknownType levado à observabilidade.

[alta · confirmado] tempo-real-metricas-cegas — O tempo real só conta sockets · Esforço P

• Evidência: be/src/observability/metrics.ts:106-121 (só o gauge ws_clients); be/src/routes/metrics.ts:19-23; be/src/routes/health.ts:115-127; nenhum contador em ws/handler.ts, ws/broadcaster.ts ou http/ws-protocol.ts.
• Impacto: não se veem salas ativas, eventos por tipo, reconexões, bytes de replay, descartes nem tipos desconhecidos — operar volume e provar a migração fica no escuro.
• Recomendação: contadores de frames por tipo e canal, conexões e reconexões, bytes de replay, descartes e tipos desconhecidos; gauges de salas, sockets por sala e listeners do runbus.

[alta · confirmado] tempo-real-busy-travado-desconexao — A badge "rodando" pode ficar acesa depois de uma queda · Esforço P

• Evidência: fe/src/components/thread-sidebar/model/use-thread-busy.ts:36, 56-61, 84-87, 123-177 (snapshot singleton que só muda com evento novo); fe/src/components/thread-sidebar/ui/ThreadList.tsx:222 (o overlay vence o valor do REST); fe/src/api/ws.ts:575-593 (o close não limpa); be/src/ws/busy-owner.ts:52 (um evento por thread, sem reenvio do estado na reconexão).
• Impacto: o turno que termina durante a queda nunca envia busy=false; a badge âmbar fica acesa até a thread rodar de novo.
• Recomendação: reconciliar o snapshot com o busy do REST a cada lista (o overlay só vence se for mais novo) e limpar no close.

[média · confirmado; sev. contestada alta→média] tempo-real-stop-abort-multi — "Parar" entre réplicas não cancela e ainda marca aborted no banco · Esforço P

• Evidência: be/src/engine/registry-redis.ts:156-167 (publica e devolve false); be/src/routes/agents.ts:575-592 e be/src/engine/orchestrator.ts:456-464 (abortChild marca aborted mesmo com ok=false); be/src/ws/handler.ts:599-612 (o stop sem efeito só gera um log); orchestrator.ts:297-321.
• Impacto: se o Parar cair em outra réplica, o turno não cancela e a API responde ok:false, mas a thread fica aborted no banco enquanto roda: a árvore mente e o gasto continua.
• Recomendação: assinar <prefixo>:abort em todas as réplicas e só marcar aborted depois que o abort confirmar; enquanto isso, documentar que o Parar exige sticky.
• Revisão: rebaixado por ser latente (1 be e 1 worker em produção); vira alta no scale-out. Ver o tema transversal em 3.0.

[média · confirmado; sev. contestada alta→média] tempo-real-fanout-filho-sem-raiz — O progresso do filho nunca chega à sala do pai · Esforço P

• Evidência: be/src/ws/handler.ts:212, 234-240 (o fan-out só acontece se rootOf conhecer a thread) e 266, 377, 565 (só a thread do próprio socket entra no cache); be/src/engine/orchestrator.ts:236-285 (o spawn não popula); fe/src/features/thread-runtime/model/timeline-live.ts:232-260 e runtime.ts:203-206.
• Impacto: o desenho D3 (o pai enxerga o filho trabalhando) não acontece: parciais e tools do filho não chegam à sala do pai; só spawn e result. O modal paga polling de 2s.
• Recomendação: popular a raiz no spawn; na migração, o pai assina a sala da família.
• Revisão: rebaixado porque o fluxo funcional está intacto e o polling de 2–3s foi aceito no doc de decisão (bn-subagent, achado 18).

[média · confirmado; sev. contestada alta→média] tempo-real-polling-sem-cache — O polling lê o Postgres direto · Esforço M

• Evidência: be/src/persistence/threads.ts:269-316 (lista e contagem direto no Prisma); be/src/routes/workflows.ts:618-626, 667-671 (passo e eventos do run direto). Mitigações achadas pelo revisor: threads.ts:165-172 (getThread com cache), events.ts:251-330 (janela quente no Redis), polls condicionais e pausados com a aba oculta, rate limits e índices.
• Impacto: picos de operadores viram picos de queries no Postgres; o custo cresce com abas × telas.
• Recomendação: push pelo WS (F2–F4); paliativo com cache curto (2–5s) por (org, usuário, rota) no Redis.

[média · confirmado; sev. contestada alta→média] tempo-real-socket-busy-duplica — O socket da sidebar recebe tudo para usar só o thread_busy · Esforço M

• Evidência: fe/src/components/thread-sidebar/model/use-thread-busy.ts:82-88 (abre socket na thread ativa) e 85-86 (só consome thread_busy e connected); be/src/ws/handler.ts:385, 429 (todo socket entra na sala e recebe o replay); be/src/ws/broadcaster.ts:129-151; fe/src/features/playground/components/PlaygroundPage.tsx:36, 193.
• Impacto: cada aba do playground mantém 2 sockets na mesma thread, com frames ao vivo e handshake em dobro. O socket do runtime já recebe o thread_busy de todas as threads do dono; o segundo é redundante.
• Recomendação: um socket por aba servindo runtime e sidebar, ou sala user: sem entrar na thread.

[média · confirmado; sev. contestada alta→média] tempo-real-runbus-psubscribe — Cada réplica recebe os frames de todos os runs · Esforço M

• Evidência: be/src/workflows/bus.ts:142 (psubscribe global), 18-26 (o comentário admite) e 124-133 (descarta antes do parse quando não há ouvinte local).
• Impacto: o tráfego Redis → API cresce com runs × réplicas; hoje, com 1 réplica, é 1x.
• Recomendação: subscribe por run com contagem de referência (o próprio comentário aponta) ou roteamento por sala no adapter do socket.io.

[média · confirmado; sev. contestada alta→média] tempo-real-sem-acks-perdas — Sem ack nem sequência: o que se perde numa queda · Esforço M

• Evidência: be/src/persistence/types.ts:97-123 (não existe tipo persistido para final e error); be/src/engine/turn-runner.ts:1232-1245 (limpa o ao vivo antes do final); be/src/ws/handler.ts:302-368, 421-425; fe/src/features/thread-runtime/model/timeline-merge.ts:90-95, 144-158; be/src/engine/registry.ts:133-144.
• Impacto: numa queda entre o último resultado e o final, o conteúdo se recupera, mas somem da timeline elapsedMs, steps, usage e historyLength do turno; a cauda do parcial do run some até o próximo frame. Não há perda de dado do usuário.
• Recomendação: seq por sala e replay de janela na reconexão; incluir final e error no buffer vivo ou persistir o resumo do final.

[média · confirmado; sev. contestada alta→média] tempo-real-backoff-sem-jitter — Reconexão sem jitter: todas as abas voltam juntas no deploy · Esforço P

• Evidência: fe/src/api/ws.ts:527-536 (1s × 2^n, teto de 15s, sem aleatoriedade); be/src/ws/handler.ts:392-443 (cada reconexão faz getEvents, config, replay e buffer vivo). Mitigações: cache quente de events; loadEffectiveConfig só vai ao banco quando há setup; rate limit global.
• Impacto: num restart, as abas reconectam nos mesmos instantes, em rajadas contra Redis e Postgres.
• Recomendação: jitter de ±50% no atraso; o handshake magro reduz o custo de cada tentativa.

Não verificados (baixa e info):

↑ voltar ao índice

Métricas medidas (tempo real):

• Produção (motor-be-ws, janela de 7,5 min): 20 requests — /healthz ×16, /api/threads?limit=50 ×2 (intervalo de 8,38s = polling de 1 aba), /tree ×1, /readyz ×1; total de 2,66 req/min. Produção estava ociosa: não há base para medir polling sob carga.
• Polling por aba visível, pior caso: lista de threads 7,5/min; árvore 20/min + graph 20/min (com filho rodando); modal de subagente 30/min + 20/min; lista de runs no recorte "ativos" 132/min; log 15/min; passo 20/min; saúde 2/min.
• Projeção: 100 abas no playground com subagentes rodando ≈ 3.000 req/min só de polling, cada uma com 1–3 queries sem cache.
• Rate limits: global de 100/min por IP; rotas de thread com 30/min por IP; leituras de run com 600/min por IP.
• WS: frame de até 8 MiB e imagem de até 2 MiB; watchdog do cliente de 60s (checagem a cada 15s); batimento de busy de 25s; backoff de 1s × 2^n com teto de 15s, sem jitter; fila de 100 itens / 256 KB.
• Sockets por aba: playground com thread ativa = 2; +1 por tela de run aberta; dashboard = 0 (só polling).
• Run: parcial de passo fora de foco até 2 Hz, com coalescência; até 8 passos em foco; handshake = 1 run + N passos + 1 groupBy.
• Buffer vivo: guarda 9 dos ~18 tipos emitidos; TTL de 900s. Eventos que o backend emite e o front descarta: compaction_failed, persistence_warning, turn_empty; subagent_progress está no buffer, mas não tem emissor.

3.3 Tools e system prompt

[alta · confirmado] tools-prompt-snapshot-com-segredos — Snapshot da config com segredos em claro vai para Postgres e Redis a cada turno · Esforço P

• Evidência: be/src/engine/turn-runner.ts:364-365 (configSnapshot = effCfg, sem redação); be/src/persistence/turns.ts:120-127 (grava em turns.config_snapshot) e 19-36, 140-143 (copia o Turn para o Redis, TTL de 1800s); be/src/config/thread-config.ts:304, 332, 388-394 (a config efetiva carrega basic.apiKey, token/Authorization de MCP e compactor.apiKey); be/src/config/redact.ts:44-73 (a redação existe, mas só nas respostas HTTP e WS).
• Impacto: cada turno espalha chaves do proxy e tokens de MCP por tabela, cache, backups e réplicas; qualquer leitura ampla do banco ou do Redis expõe credenciais.
• Recomendação: persistir redactConfig(effCfg) e calcular o configHash sobre a config completa antes de redigir; segredos ficam só em OrgConfig e Agent.
• Revisão: a única rota que hoje serializa o Turn para o cliente não devolve o snapshot — isso atenua a exposição externa, não a persistência.

[alta · confirmado] tools-prompt-ssrf-mcp-test — Teste de MCP e MCPs por thread aceitam URL arbitrária sem trava SSRF · Esforço M

• Evidência: be/src/routes/mcp.ts:11-12, 22, 35-47 (POST /api/mcp/test conecta em qualquer URL do corpo, sem checagem de papel, e devolve a mensagem de erro do destino); be/src/tools/mcp-client.ts:220-233 (connectMcp não usa o guard); be/src/config/thread-config.ts:34-49, 71-79 (ExtraMcpSchema aceita qualquer URL, inclusive http://); be/src/routes/threads.ts:139-140 (o PATCH da thread não exige admin); be/src/net/ssrf.ts:38-39 (o próprio módulo diz que MCP não passa por ele).
• Impacto: qualquer membro autenticado faz o backend conectar em hosts internos (metadata da nuvem, serviços da VPC), pelo endpoint de teste ou a cada turno via MCP da thread; e pode apontar um MCP malicioso que injeta instruções.
• Recomendação: aplicar a guarda de be/src/net/ssrf.ts no connectMcp e no /api/mcp/test; considerar exigir admin para cadastrar MCP novo.
• Revisão: o vetor fala protocolo MCP (handshake JSON-RPC), não HTTP cru; a exfiltração passa por respostas e mensagens de erro. Ver seguranca-ssrf-02 e 04 em 3.7.

[alta · confirmado] tools-prompt-descricao-mcp-verbatim — Descrição e schema de MCP entram verbatim no prompt, sem limite · Esforço M

• Evidência: be/src/tools/mcp-client.ts:280-284 (descrição e inputSchema entram sem truncar, sanitizar ou marcar a origem); be/src/tools/registry.ts:74-84 (em colisão, o último MCP vence); thread-config.ts:71-79 (qualquer thread aceita MCP por URL). Mitigações parciais: nativas vencem colisão (registry.ts:87-96); allowlist e toolPolicy opcionais.
• Impacto: qualquer MCP configurado — inclusive um que um membro adicionou à própria thread — tem um canal permanente de instrução ao modelo em todo step: exfiltração, sequestro de tools vizinhas e injeção persistente.
• Recomendação: teto de tamanho para descrição e schema; prefixo de origem ([mcp:servidor]) nas descrições; allowlist e pin de servidores por org, com revisão de tools novas.

[alta · confirmado] tools-prompt-notificacao-role-user — Resultado de subagente ou workflow entra como user, com moldura de autoridade · Esforço M

• Evidência: be/src/engine/mailbox.ts:232-239 (a notificação vira role: 'user'); mailbox.ts:245-290, 292-322 (o texto do filho ou do workflow entra dentro de [NOTIFICAÇÃO DO SISTEMA], sem marca de dado não confiável); be/src/engine/orchestrator.ts:340-343 (texto cru do filho, sem corte); be/system-prompt.md:91-126 (nenhuma instrução de que notificação é dado, não ordem).
• Impacto: texto gerado por outro agente — possivelmente envenenado por uma tool comprometida no filho — chega ao pai com autoridade de "notificação do sistema": canal clássico de injeção indireta entre agentes, num pai com tools poderosas.
• Recomendação: delimitar o conteúdo do filho como não confiável; instruir no prompt nativo que conteúdo de notificação é dado; cortar o finalText com referência para o detalhe.
• Revisão: o caminho de workflow já corta em 6 mil chars (be/src/workflows/notify-launcher.ts:57-61); o de subagente, não.

[alta · confirmado] tools-prompt-maxsteps-999 — Default de 999 steps por turno permite custo descontrolado · Esforço P

• Evidência: be/src/agent/loop.ts:508; be/src/engine/dispatcher.ts:158-170; be/src/engine/agent-step.ts:179-180, 689; be/src/config/schemas.ts:289-301, 386; be/src/engine/cost-tracker.ts:361-365 (orçamento ausente = sem teto).
• Impacto e recomendação: os mesmos de loop-sdk-maxsteps-999 (3.1). O revisor acrescenta que 999 steps também seguram fila e worker por horas.

[alta · confirmado] tools-prompt-tudo-para-o-modelo — O padrão registra todas as tools de cada MCP · Esforço G

• Evidência: be/src/config/schemas.ts:252-253 (tools opcional; ausente = todas); be/src/tools/registry.ts:32 (sem filtro, devolve tudo); be/src/persistence/agents.ts:228-243 e be/prisma/schema.prisma:100 (o setup padrão nasce sem toolPolicy); be/src/engine/turn-runner.tool-policy.test.ts:92-101 (um teste protege o "tudo" como padrão); logs de produção: 76 + 70 + 193 de MCP + 23 nativas = 362 tools por turno, sem nenhuma linha de "tools selecionadas".
• Impacto: prefixo de dezenas de milhares de tokens em todo step, mais latência, mais custo de escrita de cache e mais chance de escolher a tool errada.
• Recomendação: curadoria por setup (toolPolicy preenchida no setup padrão) e núcleo mínimo com busca de tools sob demanda, negando por padrão.
• Revisão: o número exato varia com os MCPs conectados (o briefing citava 534 antes das colisões); a ordem de grandeza — centenas por turno — está confirmada.

[média · confirmado; sev. contestada alta→média] tools-prompt-colisao-mantem-ultimo-mas-avisa-primeiro — O aviso de colisão diz o contrário do que o código faz · Esforço M

• Evidência: be/src/tools/registry.ts:76-82 (o aviso diz que manteve o primeiro e descartou o atual, mas collected[name] = t mantém o último); registry.ts:6-7 (o cabeçalho diz, corretamente, que o segundo sobrescreve); be/src/agent/bootstrap.ts:134-160 (a ordem é a de cfg.mcps).
• Impacto: com nomes repetidos entre MCPs, a tool que executa é a do último da lista e o log diz o contrário: depuração invertida, e um MCP pode tomar as tools de outro.
• Recomendação: namespace servidor__tool com alias curto; até lá, "o primeiro vence" (coerente com o aviso) ou recusar no boot quando os schemas diferirem.
• Revisão: rebaixado porque é determinístico pela ordem da config, há aviso a cada colisão (só o texto está invertido) e existe allowlist opcional.

[média · confirmado; sev. contestada alta→média] tools-prompt-sem-limite-resultado — Resultado de tool sem teto · Esforço M

• Evidência: be/src/tools/mcp-client.ts:305-310 (junta todo o texto sem cortar); be/src/engine/orchestrator.ts:340-343 (finalText sem corte). Mitigações: be/src/workflows/notify-launcher.ts:57-61 (workflow corta em 6 mil chars); be/src/agent/history.ts:102-119 e be/src/agent/compaction.ts:128-129 (a compactação limita o acúmulo entre turnos).
• Impacto: um arquivo grande, um log verboso ou um filho prolixo entram inteiros no contexto de todos os steps seguintes do turno; a compactação só age no turno seguinte (TURN-12).
• Recomendação: teto configurável por resultado (ex.: 20–50 mil chars) com marcador [TRUNCADO] e uma tool nativa para ler o resultado completo em páginas.
• Revisão: rebaixado porque o acúmulo entre turnos é limitado; o estrago fica em um turno por conversa.

[média · confirmado; sev. contestada alta→média] tools-prompt-estimativa-ignora-tools — A estimativa de contexto ignora o bloco de tools · Esforço P

• Evidência: be/src/engine/turn-runner.ts:1566-1583 (estimateContextTokens soma system e messages, sem tools) e 1180-1181 (fallback quando o proxy não devolve usage).
• Impacto: sem usage do provider, a ocupação medida erra dezenas de milhares de tokens para baixo e a compactação dispara tarde.
• Recomendação: somar o tamanho das tools (pré-calculado no bootstrap) e logar a divergência entre estimado e medido.
• Revisão: rebaixado porque o LB sempre devolve usage no caminho feliz; o fallback só roda com o proxy degradado.

[média · confirmado; sev. contestada alta→média] tools-prompt-args-sem-validacao — Argumentos de tools nativas não são validados · Esforço M

• Evidência: be/src/tools/native/subagent.ts:175-176 (String(args.title) e String(args.task) viram "undefined" e o spawn acontece); be/src/engine/orchestrator.ts:239-246 (sem validação); @ai-sdk/provider-utils (jsonSchema() sem validate aprova tudo). Contraexemplo bom: be/src/tools/native/workflow.ts:300-330 (as tools workflow_* recusam argumento ruim).
• Impacto: o required dos schemas é decorativo para JSON válido com campo faltando: agent_spawn cria filho com tarefa "undefined", gastando modelo e poluindo a árvore.
• Recomendação: validar required e tipos no início de cada execute nativo (helper zod compartilhado) e recusar com erro legível.
• Revisão: o mecanismo original estava errado (parseToolArgs só alimenta a UI e JSON quebrado o SDK já recusa — ver loop-sdk-parse-args em 3.9), mas o problema de fundo se confirmou por este caminho.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas medidas (tools e prompt):

• 23 tools nativas (4 de subagente, 4 de setup, 15 de workflow): 37.467 chars de JSON ≈ 9.367 tokens (chars/4; faixa de 7.494 a 12.489 entre chars/5 e chars/3).
• workflow_validate sozinha: 15.399 chars de JSON, com descrição de 14.665 chars (workflow.ts:603-635).
• system-prompt.md: 25.903 chars ≈ 6.476 tokens. Prefixo fixo sem MCP: ~63 mil chars ≈ 15,8 mil tokens por request.
• MCPs de produção citados no briefing: 195 + 193 + 76 + 70 = 534 tools antes das colisões; estimativa do bloco de MCP: 80–214 mil tokens (premissa de 150–400 tokens por tool), contra janela padrão de 230 mil.
• Breakpoints efetivos no seed: 2 de 4 (system e último user, ambos com TTL de 1h; tools sem breakpoint; checkpoint desligado).
• Timeouts: handshake e listagem 30s; chamada de tool 60s; pool ocioso 120s; watchdog de lease 60s.
• Compactação: transcript de 300 mil chars (40 mil de cabeça); tool result 600 chars; argumentos 400 chars; resumo de até 8 mil tokens.

3.4 Agente e subagentes

[alta · confirmado por 2 revisores; sev. contestada crítica→alta] subagentes-reaper-desligado — Reaper desligado em produção: filho órfão trava o pai para sempre · Esforço P

• Evidência: be/src/engine/reaper.ts:67-69 (só liga com REAPER_ENABLED === '1') e 302-308 (start() vira no-op); reaper.ts:275-284 (o reconciler de notificações perdidas só roda dentro do reaper); be/src/plugins/websocket.ts:64 (único start()); be/src/workflows/register.ts:63-64 (o worker não liga); docs/operacao.md:134 (DESLIGADO); a lista de variáveis dos dois serviços de produção não tem REAPER_ENABLED; be/src/engine/orchestrator.ts:297-321 (onTurnEnd é o único caminho de notificação do pai).
• Impacto: crash, OOM ou kill no meio de um turno deixa a thread do filho active e o turno running para sempre; o pai espera uma notificação que nunca chega, sem erro visível. A rede do BE-ERR-09 fica desligada junto.
• Recomendação: ligar REAPER_ENABLED=1 em exatamente uma réplica (ou padrão ligado com liderança por lock) e alertar no boot se nenhuma réplica assumiu.
• Revisão: rebaixado de crítica para alta porque o boot registra o aviso, o pai não entra em deadlock técnico (o usuário pode seguir em outra thread) e o opt-in é decisão documentada (P-20), para evitar várias réplicas varrendo sem liderança.

[alta · confirmado] subagentes-fanout-ilimitado — Largura e profundidade ilimitadas, sem orçamento por árvore · Esforço M

• Evidência: be/src/engine/orchestrator.ts:22-24 (D4: profundidade e largura ilimitadas; depth é só telemetria) e 234-235; be/src/engine/org-concurrency.ts:36-39, 50 (teto de 100 por processo, "best-effort", multiplica por réplica); be/src/tools/native/subagent.ts:38-62, 72-80 (o próprio código admite que não há teto para gasto que sobrevive ao run — por isso a tool é negada em workflow).
• Impacto: um pedido inocente ("paraleliza isso") abre N filhos que abrem netos, todos rodando turnos de LLM sem orçamento por árvore; as defesas existentes são por org e reativas, e o orçamento é mensal.
• Recomendação: teto configurável de largura por pai e de profundidade, com erro legível que oriente a consolidar; e/ou orçamento de tokens por árvore passado no spawn.

[alta · confirmado] subagentes-notificacao-sem-teto — O resultado do filho volta inteiro, sem corte nem condensação · Esforço P

• Evidência: be/src/engine/orchestrator.ts:340-343, 345-358 (finalText cru); be/src/engine/mailbox.ts:232-239, 292-323 (vai inteiro para a mensagem do pai); be/src/engine/turn-runner.ts:744-758, 994-1039 (entra no messages do pai); be/src/persistence/event-payload-schemas.ts:39-46 (também persiste inteiro). Contraste: orchestrator.ts:246 (spawnReason cortado em 500) e 410 (corte de 500 só para auditoria); be/system-prompt.md:111 (só pede concisão).
• Impacto: o pai recebe o texto final inteiro de cada filho, multiplicado por N filhos no mesmo turno, e paga isso nos turnos seguintes até a compactação (que só dispara a 90% de 230 mil); contraria o padrão da Anthropic de retorno condensado com referência externa.
• Recomendação: cortar o finalText na notificação (ex.: 4–8 mil chars, com aviso de corte) e instruir o filho a devolver resumo denso mais a referência ao threadId para o detalhe.

[alta · confirmado] subagentes-sem-cascata — Cancelar o pai não desce para filhos e netos · Esforço M

• Evidência: be/src/engine/orchestrator.ts:456-464 (abortChild aborta só o id nomeado); be/src/ws/handler.ts:599-612 (o Parar aborta só a thread conectada); be/src/engine/registry.ts:152-177 (abort por thread; cada lease nova traz controller novo); be/src/engine/dispatcher.ts:265-294 e orchestrator.ts:297-372 (a notificação do filho acorda o pai sem checar cancelamento); be/src/persistence/threads.ts:324 (listThreadTree existe, mas só é usada em leitura); flag isCascade sem uso (registry.ts:60).
• Impacto: cancelar o pai não toca a subárvore, que continua gastando; e cada neto que termina acorda o intermediário cancelado, rodando turnos que ninguém vai ler.
• Recomendação: abort recursivo pela árvore, ou marcar a raiz como cancelada para o onTurnEnd descartar notificações de subárvore morta.
• Revisão: o próprio doc de prontidão admite que o cascade "não está implementado, mas a flag existe para o futuro".

[alta · confirmado] subagentes-abort-cross-replica-morto — Abort entre réplicas publica num canal que ninguém escuta · Esforço M

• Evidência: be/src/engine/registry-redis.ts:154, 156-167; be/src/engine/reaper.ts:23-26, 48, 153, 181; docs/motor-agent-prod-readiness/engine.html:190 e arquitetura.html:631 (prometem o assinante que não existe).
• Impacto: com várias réplicas, agent_abort ou Parar na réplica errada não tem efeito e devolve false; e o reaper eleito numa réplica pode declarar órfão (e notificar erro ao pai) um turno longo vivo em outra.
• Recomendação: assinar o canal de abort em todas as réplicas; no reaper, checar se o lock existe no Redis antes de declarar órfão. Ver o tema transversal em 3.0.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas medidas (subagentes):

• Tamanho em linhas: orchestrator.ts 471; subagent.ts 281; mailbox.ts 335; mailbox-db.ts 175; dispatcher.ts 303; reaper.ts 322; reconciler.ts 120; registry-redis.ts 264; setup.ts 520; system-prompt.md 288 linhas (26.575 bytes).
• Custo por spawn: 1 findUnique (idempotência) + 1 getThread (com Redis) + 1 findFirst do setup (só com setupId) + INSERT da thread + INSERT do evento subagent_spawned + lookup da org + INSERT na mailbox.
• Custo por notificação: findFirst + updateMany (claim) + count de irmãos + push na mailbox (lookup + insert) + pump do pai (hasPending + drain).
• Tempos: reaper com stale de 30 min e varredura de 60s; reconciler de 1h; lock Redis com TTL de 30s e heartbeat de 10s; guarda de aborto de 5s; drain de shutdown de 30s.
• Tetos: rate limit externo de 60 submits/min por (org, usuário), com os internos isentos; concorrência por org de 100 em voo por processo; setup_list limitado a 50; spawnReason cortado em 500 chars; finalText sem corte.
• Contrato de prompt: seção de subagentes com ~40 linhas no system prompt e descrição do agent_spawn com ~11 linhas; só title e task são obrigatórios.
• Produção (janela lida): nenhum evento de spawn, notificação, reaper ou abort visível na amostra.

3.5 Workflows

[alta · confirmado] workflows-outputs-in-list-payload — Lista de passos e handshake do WS carregam o output inteiro de cada passo · Esforço M

• Evidência: be/src/workflows/contract.ts:132-135 (output: row.output ?? null no envelope do passo); be/src/ws/run-channel.ts:149-181 (handshake do WS: findMany sem take, com output inteiro); be/src/routes/workflows.ts:592-602 (GET /api/runs/:id/steps sem take) e 604-609 (o comentário admite que fan-out de 300 passos não pode viajar na lista — tiraram input e attempts, mas o output ficou); be/src/workflows/executors.ts:494 (corpo HTTP de até 1 MB por passo); be/src/workflows/definition.ts:118 (até 10.000 passos); fe/src/features/run/components/RunView.tsx:267-274 (o painel de foco usa o output da lista).
• Impacto: um run com 50 passos http pode gerar até 50 MB por handshake e por GET; um map de 1.000 filhos baixa megabytes só para montar a espinha. O navegador pode travar antes de renderizar (risco já registrado em docs/workflows/02-arquitetura.md:108-110).
• Recomendação: na lista, output: null com prévia curta (1–2 KB) ou indicador de truncamento; output completo só em /steps/:id e no frame step_output; ajustar o reducer do front.

[média · confirmado; sev. contestada alta→média] workflows-absence-budget-no-cap — Run sem budget não tem teto nenhum · Esforço M

• Evidência: be/src/workflows/runs.ts:270, 286-302 (resolveRunCaps: o declarado vence; ausente vira env ou "sem teto"); be/src/workflows/state.ts:378-402; be/.env.example:359-365 (WF_DEFAULT_MAX_USD, _STEPS e _WALL_MS vazios; "antes vinha escondido no default do banco: US$ 5, 200 passos, 30 min"); be/src/tools/native/workflow.ts:167-168, 738-740 (o workflow_draft só avisa); be/src/engine/agent-step.ts:174-178 (sem timeoutMs, passo de agente não tem prazo).
• Impacto: um workflow publicado sem budget (ou antes de o operador definir tetos padrão) pode gastar sem limite de USD, passos ou tempo; a única rede é o orçamento mensal da org, que é fail-open se o Redis cair.
• Recomendação: definir em produção WF_DEFAULT_MAX_USD (ex.: 5), WF_DEFAULT_MAX_STEPS (ex.: 500) e WF_DEFAULT_MAX_WALL_MS (ex.: 1.800.000); opcionalmente exigir budget com WF_REQUIRE_BUDGET=1; aviso explícito no retorno do workflow_draft quando o budget vier vazio.
• Revisão: rebaixado porque é decisão de produto explícita e documentada (docs/workflows/00-visao-geral.md:242, 284; 05-guia-operacional.md:383), com o orçamento da org conferido antes de cada chamada ao LLM (be/src/engine/turn-runner.ts:832-841). A recomendação vale como política da instalação.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas medidas (workflows):

• ~10.424 linhas de código fora de teste no diretório de workflows (definition 1911, reconcile 2456, expr 1029, runs 962, expanders 860, executors 798, runner 764, state 492, entre outros), mais 14 arquivos de teste com 302 casos; filas em be/src/queue com 1.415 linhas; workers/index.ts com 342; engine/agent-step.ts com 956; tools/native/workflow.ts com 1.581. Total da dimensão: ~14.700 linhas.
• Postgres: 6 models específicos de workflow; 9 status de run e 8 de passo.
• Filas BullMQ: 6 — wf-reconcile (10), wf-step-ai (100, lock de 120s), wf-step-det (100, lock de 60s), wf-notify (10, lock de 30s), wf-maintenance (1, lock de 60s), wf-ping (10). O lock é só atraso de recuperação; o relógio real é o heartbeat da tentativa.
• Padrões de produção: WORKER_AI_CONCURRENCY e WORKER_DET_CONCURRENCY 100; ORG_CONCURRENCY_MAX 100; DB_CONNECTION_LIMIT 1000; WF_DEFAULT_MAX_* vazios; purga ligada com eventos de 30 dias; retenção de runs de 180 dias.
• Limites do formato: 500 passos de topo; 10.000 passos no total; timeout HTTP de 1h; portão humano de até 30 dias; até 10 retries com backoff de até 600s; expressão de até 4.000 chars, profundidade 32 e 500 nós; sub-workflow com até 5 níveis; corpo HTTP de 1 MB.
• Desempenho medido (WF-PERF-L7-01): map de 1.000 transforms em 17,5s (67 passos/s, 100 filhos em voo); map de 100 com concorrência 100 em 1,5s; promoção de 50–75 ms (p50/p95).
• Observabilidade: 11 métricas Prometheus + 3 gauges de fila.

3.6 Banco, cache, threads e escala

[alta · confirmado] dados-convo-redis-writeonly — O convo no Redis é write-only e um miss zera o contexto do LLM · Esforço M

• Evidência: be/src/engine/registry-redis.ts:171 (getConvo lê só o Map local) e 172-181 (o Redis só recebe SET e DEL; nenhum GET em be/src); be/src/engine/turn-runner.ts:705-706 (getConvo(threadId) ?? [], sem fallback ao banco); be/src/ws/handler.ts:258-267, 397-399, 471, 567, 621 (o convo só é hidratado no connect ou reset; o launcher-wake acorda qualquer réplica); be/src/engine/dispatcher.ts:296-298 (kick sem hidratar); be/src/workflows/notify-launcher.ts:163-170; o próprio código admite em turn-runner.ts:869-870 que um restart "apaga da memória do LLM".
• Impacto: um turno que roda sem o convo em memória manda ao LLM só as mensagens novas, sem o histórico — e a resposta fora de contexto ainda é persistida na thread. Acontece já com 1 réplica: depois de um restart, quando um workflow acorda a conversa (kick) ou chega mensagem antes de um connect nesta instância; e em qualquer cenário com várias réplicas. O SET do convo no Redis é custo puro.
• Recomendação: getConvo com fallback: Map local → GET no Redis → getEvents + eventsToLlmMessages do banco; enquanto isso, alerta quando um turno começa com convo vazio numa thread com lastSeq > 0.

[alta · confirmado] dados-reaper-desligado — Reaper desligado: turnos órfãos ficam running e pais travam · Esforço P

• Evidência: be/src/engine/reaper.ts:67-69, 302-307; docs/operacao.md:134; be/src/plugins/websocket.ts:64; as variáveis de produção não têm REAPER_ENABLED; reconcileStuckNotifications e sweepThreadCounters só rodam dentro do reaper (reaper.ts:256, 276).
• Impacto: crash entre startTurn e finishTurn deixa o turno running para sempre; subagente órfão nunca notifica o pai; o chat fica sem rede de segurança (o sweeper só cobre workflows).
• Recomendação: a mesma de subagentes-reaper-desligado (3.4), mais isBusy distribuído para o reaper não colher turno longo de outra réplica.

[alta · confirmado] dados-broadcaster-local — Evento de turno pode ir para a réplica que não tem o socket · Esforço G

• Evidência: be/src/ws/broadcaster.ts:60-63; be/src/ws/handler.ts:234-240, 258-271 (o launcher-wake faz todas as réplicas darem kick; vence o lock quem chegar primeiro, que pode não ter o socket); be/src/workflows/register.ts:71 (o engine do worker não emite para socket algum); be/src/persistence/events.ts:65-113 (o canal :stream está pronto, sem assinante).
• Impacto: no caminho feliz (envio pelo WS), turno e socket ficam na mesma réplica. Turnos disparados por kick (workflow acordando a conversa) podem rodar na réplica errada: o usuário não vê streaming nem final até reconectar; o thread_busy tem o mesmo limite.
• Recomendação: publicar os eventos de turno no Redis (o canal :stream já existe) e cada réplica repassar só aos seus sockets; ou fixar o turno na réplica do socket.

[média · confirmado; sev. contestada alta→média] dados-events-sem-retencao — events de thread ativa cresce sem teto nem purga · Esforço G

• Evidência: be/src/queue/retention.ts:29-36 (decisão documentada: events de thread viva nunca são purgados; "particionar events no cenário grande fica para quando o volume pedir") e 113-217; be/src/queue/purge.ts:81-145 (só purga workflow_events); be/src/agent/compaction.ts:9-13 (append-only); be/prisma/schema.prisma:293-321 (5 índices, sem partição nem TTL).
• Impacto: cada turno grava ~3–8 events para sempre; threads longas e fan-out incham tabela e índices e encarecem hidratação, compactação e backup.
• Recomendação: retenção para events só de exibição (reasoning, step_done) depois de N dias, ou arquivamento de threads inativas; monitorar o tamanho da tabela e a contagem por thread.
• Revisão: rebaixado porque é decisão documentada (não corromper thread arquivada que pode voltar) e o custo de leitura é por thread.

[baixa · confirmado; contestado (alta→baixa pelo revisor; a investigação de lacunas aponta risco alto)] dados-pool-1000 — Pool de 1000 conexões por processo × max_connections do Postgres · Esforço P a M

• Evidência: be/src/persistence/prisma.ts:12, 35-40 (1000 conexões por processo, abertas sob demanda); docs/operacao.md:9-12 (API + worker = 2000; Postgres precisa de ≥ 2100; "não reduza o pool"); compose.prod.yml:20-64 (1 be + 1 worker); docs/workflows/08-matriz/l7.md:41 (teste L7-16: pico de 151 conexões, base de 42–48, zero erro de pool).
• Impacto: uma 2ª réplica de API eleva o teto a 3000, acima de 2100; sob burst, as queries estouram o pool_timeout de 10s.
• Recomendação: não subir réplica sem PgBouncer em modo transação ou max_connections dimensionado (hoje a decisão do dono proíbe reduzir o pool).
• Revisão: o revisor rebaixou para baixa assumindo o runbook (≥ 2100), 1 réplica e o pico medido de 151. A investigação de lacunas leu max_connections = 100 no postgresql.conf de produção: se SHOW max_connections confirmar, a carga do próprio teste L7-16 não caberia, e o risco volta a alto já com a topologia atual.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas medidas (dados e escala):

• Pool Prisma: 1000 conexões por processo; timeouts de conexão 10s, pool 10s e socket 30s. Conta do runbook: 1 API + 1 worker = 2000 ≤ 2100.
• Cache: thread 3600s; events 1800s; turn 1800s; config da org 60s; página de histórico 300s; janela quente de 200 events.
• Turno simples: ~20–25 statements no banco em ~12–15 idas e voltas, e ~40–50 comandos Redis em ~15–20 idas e voltas (contagem por leitura de código). Por step: 1 UPDATE (drain de notificações) + 0–1 HGETALL + 0–5 MULTIs do buffer ao vivo.
• Rate limits: dispatcher 60/min por (org, usuário); HTTP global 100/min por IP; leituras de run 600/min.
• Worker: reconcile 10, step-AI 100, step-det 100, notify 10, maintenance 1; shutdown de 30s; drain da API de 30s.
• Sweeper: a cada 30s, lote de 200, stale de 45s. Purga horária em lotes de 500. Retenção de 30, 7, 90 e 180 dias.
• Custo por turno: HGETALL de pré-check + pipeline de 8 comandos no registro; espelho local de 1,5s.
• Listas: threads até 200, setups 200, workflows e runs 200, events 100 por padrão; sem teto: árvore, turns, passos de run, webhooks.
• Schema: 20 models, ~50 índices e 11 uniques; events tem unique (thread, seq) e índice redundante (thread, seq).
• Emissões por turno: 14 chamadas emit no turn-runner + pushLive por evento ao vivo; 2–4 emissões de webhook.
• Serviços na leitura: motor-be-ws ~232–242 MB e 0,4–1,3% de CPU; motor-worker-ws ~122–129 MB e ~0,5% de CPU; Postgres 86 MB; Redis 24 MB.
• Capacidade estimada (sem teste de carga): ~50–80 turnos simultâneos confortáveis por réplica, teto duro de 100 turnos simultâneos por org e processo, ~200–300 turnos/min com turno médio de 10–20s (premissas: threads com menos de 200 events, 1–2 steps por turno, 1 org quente, proxy com latência normal) — se o banco estiver no padrão do runbook. Com max_connections = 100, a investigação de lacunas estima ~10–30 conversas simultâneas.

3.7 Segurança e vazamento de informação

[crítica ou alta · confirmado; contestado entre revisores (crítica × alta)] seguranca-cross-tenant-01 — Toda org herda a config da org default no turno · Esforço G

• Evidência: be/src/server/index.ts:290-295 (deps.chatConfig = config da org default); be/src/plugins/websocket.ts:38 (getConfig: () => deps.chatConfig); be/src/engine/index.ts:100, 153 e be/src/engine/turn-runner.ts:347-360, 432 (esse valor vira o global de todo turno, de qualquer org); be/src/setups/service.ts:763-868 (loadEffectiveConfig recebe o global e nunca lê a OrgConfig da org do turno); be/src/config/thread-config.ts:303-309 (apiKey herdada), 328-368 (MCPs com tokens), 412 (TTLs de cache), 514-516 (systemPromptAppend); be/src/routes/threads.ts:460-465 (só a org default atualiza o valor em memória) e 611-622 (a rota de config da thread também usa o da default); be/src/auth/jit.ts:170-184 (o desenho prevê uma OrgConfig por empresa e diz que "nunca copia a config da org default").
• Impacto: para qualquer org que não seja a default, o turno herda basic.apiKey (a checagem D12 não barra quando a URL é a mesma), MCPs com tokens e headers de autorização, systemPromptAppend e TTLs de cache da default; o custo vai para a chave de cobrança da default. Tudo em silêncio.
• Recomendação: loadEffectiveConfig(orgId, …) receber a OrgConfig da própria org (cache por org com TTL curto, ou um provedor (orgId) => config); o deps.chatConfig passa a ser só o template da instalação.
• Revisão: um revisor manteve crítica (o desenho é multi-tenant e o runtime o contradiz; um comentário em threads.ts:442-445 descreve o oposto do código). Outro rebaixou para alta: a UI hoje força a org default (não há troca de org) e as empresas novas nascem do template sem apiKey — latente hoje, crítico no dia em que a troca de org for liberada.

[alta · confirmado por 2 revisores; sev. contestada crítica→alta] seguranca-ssrf-01 — Entrega de webhook usa fetch cru: o guard SSRF não cobre redirect e a assinatura acompanha o salto · Esforço P

• Evidência: be/src/webhooks/dispatcher.ts:121-126 (fetch sem redirect: 'manual' nem lookup); dispatcher.ts:218 (resolveAndValidate uma vez, antes do laço de retries); dispatcher.ts:232-237 (envia X-Webhook-* e X-Motor-Signature-256, que o undici não derruba em redirect entre origens); be/src/net/ssrf.ts:27-28, 163-168, 382-396, 460-475 (o safeRequest faz tudo isso certo); be/src/workflows/executors.ts:560 (o passo http do workflow já usa o safeRequest).
• Impacto: um endpoint de webhook que responda 302 para um host interno (ex.: 169.254.169.254) faz o fetch seguir levando a assinatura e o envelope (orgId, threadId, dados do evento); e a cada retry o nome é resolvido de novo (DNS rebinding).
• Recomendação: trocar o postOnce pelo safeRequest (com os headers de assinatura no próprio safeRequest), aceitar só https: e apagar a função allowPrivateHosts morta.
• Revisão: rebaixado por 2 revisores porque quem cadastra webhook é admin da própria org; o conteúdo vazado e o vetor sustentam alta. Em produção WEBHOOK_ALLOW_PRIVATE_HOSTS está vazio (o guard vale na checagem inicial).

[alta · confirmado por 2 revisores; sev. contestada crítica→alta] seguranca-ssrf-02 — POST /api/mcp/test, aberto a qualquer membro, conecta sem guard SSRF · Esforço P

• Evidência: be/src/routes/mcp.ts:11-12, 35-47 (sem checagem de papel; connectMcp com a URL do corpo; err.message devolvido no 502); be/src/routes/index.ts:48; be/src/http/auth.ts:336 (só identidade); be/src/tools/mcp-client.ts:230-233, 376-389; be/src/net/ssrf.ts:38-39; be/public/chat.html:1646, 1707-1763 (botão "testar conexão" sem restrição de papel); problema já listado em docs/api-terceiros.md:580 (§7.3.4) e em docs/motor-agent-prod-readiness/bn-mcp.html (MCP-06).
• Impacto: qualquer membro autenticado envia uma URL interna e recebe de volta a mensagem de erro do destino — oráculo de alcançabilidade da rede interna e, se houver um MCP interno, leitura dele.
• Recomendação: exigirAdmin e rate limit próprio na rota; resolveAndValidate dentro do connectMcp (vale para todos os chamadores).
• Revisão: rebaixado porque exige sessão válida e a leitura útil depende de um MCP interno alcançável.

[alta · confirmado] seguranca-ssrf-03 — Teste de conexão do setup faz fetch cru na baseURL e ecoa a resposta · Esforço P

• Evidência: be/src/routes/agents.ts:240-364 (fetch cru para a baseURL do setup), 82 (anexa providerMessage.slice(0, 100) ao status) e 355 (ecoa err.message); be/src/config/secret-origin.ts:61-69 (sem chave quando a origem difere — mas o request sai mesmo assim); be/src/config/proxy-url.ts:41-77 (só normaliza o caminho); be/src/setups/visibility.ts:55-57 (no setup privado, o dono pode testar); be/src/config/thread-config.ts:34-49 (aceita http:// e IP privado).
• Impacto: um membro cria um setup privado com baseURL interna, chama o teste e lê os primeiros 100 chars da resposta do serviço interno, mais as mensagens de erro de transporte.
• Recomendação: usar o safeRequest e devolver só o status e uma mensagem genérica.

[alta · confirmado] seguranca-ssrf-04 — MCPs configurados na thread (por qualquer membro) alcançam a rede interna no turno seguinte · Esforço M

• Evidência: be/src/tools/mcp-client.ts:230-233 (transporte direto da URL) e 252-254, 268-270 (o erro inclui URL e motivo); be/src/tools/mcp-pool.ts:136-169; be/src/agent/bootstrap.ts:134-152; be/src/config/thread-config.ts:71-79, 328-368; be/src/routes/threads.ts:234-302 (o PATCH da thread aceita mcps sem exigir admin); docs/motor-agent-prod-readiness/bn-mcp.html:160-178 (MCP-06 registrava o furo como médio).
• Impacto: um membro grava na própria thread um MCP apontando para um IP interno; no turno seguinte o backend abre a conexão; os erros vazam a topologia e um MCP interno real pode injetar tools no prompt.
• Recomendação: resolveAndValidate no connectMcp e na camada de MCPs extras da thread, com WEBHOOK_ALLOW_PRIVATE_HOSTS como exceção explícita; idealmente também para MCPs de org e setup.
• Revisão: o MCP-06 original considerou só a config de org (admin); o override por thread, editável por membro, é o vetor mais explorável.

[alta · confirmado] seguranca-segredo-01 — No escopo da thread, o ••• ecoado pela UI vira header real enviado ao MCP · Esforço P

• Evidência: be/src/config/secret-origin.ts:178 (o bloco de headers só roda no escopo setup) e 173-177; be/src/routes/threads.ts:283-287 (o PATCH da thread usa o escopo thread); fe/src/components/thread-config/model/config-draft.ts:78-108, 122-138 (o formulário reenvia os headers inteiros, com •••); fe/src/components/thread-config/ui/McpRow.tsx:55-58, 236, 266-274; be/src/config/thread-config.ts:328-368 (os headers viram headers reais); be/src/config/redact.ts:30-37 (a redação só existe na saída); docs/setups/00-decisoes.md:222-235 (a D12 manda proteger headers também no PATCH da thread).
• Impacto: o usuário abre a config de MCP da thread, salva sem mexer, e o ••• literal é gravado e enviado como Authorization ao MCP no turno seguinte: autenticação errada e silenciosa, e a chave verdadeira se perde.
• Recomendação: tratar os headers nos dois escopos com a mesma regra do token (filtrar •••, manter se a origem não mudou, bloquear se mudou), numa função única; e o front não reenviar valores redigidos.

Não verificados (média, baixa, info):

↑ voltar ao índice

Varredura focada da investigação de lacunas (webhooks, rotas REST e versionamento; sem rodada adversária):

↑ voltar ao índice

Pontos confirmados como corretos pela mesma varredura: RBAC com exigirAdmin em webhooks, workflows e test-connection (be/src/http/rbac.ts:29-46); remoção de identidade do corpo e da query (be/src/http/auth.ts:161-169, 322-338); redação de segredos (be/src/config/redact.ts) e chave presa à origem (D12, be/src/config/secret-origin.ts); boot fail-closed fora de desenvolvimento (be/src/auth/config.ts:146-174); JWT OIDC com iss, aud, exp e nonce e recarga de JWKS; webhook de provisionamento da Conta com HMAC, janela de 5 min e idempotência; sessão com refresh_token cifrado (AES-256-GCM) e rotação com trava no Redis; passo http do workflow com safeRequest (há teste provando que o redirect entre origens derruba credenciais); pool MCP com chave por destino e watchdog de vazamento.

Métricas (segurança): be/src/net/ssrf.ts 563 linhas (guard completo: IPv4 e IPv6 normalizados, "qualquer registro interno bloqueia", conexão fixada no IP validado, redirect manual); be/src/webhooks/dispatcher.ts 334; be/src/tools/mcp-client.ts 390; be/src/auth/session.ts 374; be/src/auth/jit.ts 346; be/src/http/auth.ts 348; be/src/config/secret-origin.ts 212; be/src/setups/visibility.ts 88. Bloqueio de 28 chaves no corpo de erro do provider antes de chegar à UI (turn-runner.ts:1398-1432).

3.8 Qualidade e modularidade

[crítica · confirmado; sev. contestada alta→crítica] qualidade-abort-sem-assinante — "Parar" entre réplicas documentado e sem assinante · Esforço P

• Evidência: be/src/engine/registry-redis.ts:24 (o cabeçalho promete o canal abort:<threadId> com a dona escutando) × registry-redis.ts:164 (o único publish usa um canal único, ${p}:abort); be/src/engine/registry.ts:37 (repete a promessa); os assinantes reais são só be/src/ws/handler.ts:259 e be/src/workflows/bus.ts:142; os testes do registry Redis não cobrem o caminho entre réplicas.
• Impacto: o motivo de existir do registry distribuído (Parar em qualquer réplica) não funciona; ver o tema transversal em 3.0.
• Recomendação: implementar o assinante que o cabeçalho promete, ou corrigir os cabeçalhos; testar Parar cruzado com 2 réplicas reais.
• Revisão: elevado para crítica porque o Parar entre réplicas é a razão de existir desse componente.

Não verificados (média, baixa, info):

↑ voltar ao índice

Métricas (qualidade): backend com ~57 mil linhas em ~220 arquivos; frontend com ~73 mil linhas em 498 arquivos. Testes: 69 arquivos no backend e 142 no frontend; workflows cobertos em níveis L1 a L7. as any em produção: 60 no backend (16 em turn-runner.ts, medido nesta revisão) e 0 no frontend. Maiores arquivos do backend: reconcile.ts 2456, definition.ts 1911, turn-runner.ts 1583, tools/native/workflow.ts 1581, expr.ts 1029, runs.ts 962, agent-step.ts 956, setups/service.ts 868. Maiores do frontend: validate.ts 1902, ws.ts 668, config-draft.ts 579, blocks.tsx 535. Scripts de dev fora do build: 8 arquivos, ~1.900 linhas, sem imports em produção.

3.9 Refutados pelos revisores

Estes achados foram derrubados por contra-evidência e não entram no roadmap. A coluna da direita registra o que sobra de válido, quando sobra.

↑ voltar ao índice

4. O Motor frente às melhores práticas

Legenda da coluna "Motor hoje": coberto, parcial, não ou não avaliado (o scan não mediu). Todas as afirmações sobre o Motor vêm das seções 2 e 3.

4.1 Arquitetura de agentes e multiagentes

↑ voltar ao índice

4.2 Delegação e subagentes

↑ voltar ao índice

4.3 Contexto e prompt

↑ voltar ao índice

4.4 Tools

↑ voltar ao índice

4.5 Loop, API Messages e SDK

↑ voltar ao índice

4.6 Execução durável de workflows (mercado)

↑ voltar ao índice

4.7 Tempo real

↑ voltar ao índice

5. Arquitetura-alvo proposta

Princípio: completar o que o desenho já prevê, sem big-bang. Cada mudança estrutural entra atrás de flag, com shadow e rollback.

5.1 Loop com o SDK nativo da Anthropic (@anthropic-ai/sdk, API Messages, loop próprio)

O SDK nativo troca só o transporte e o loop. O contrato com o LB fica igual: Anthropic Messages, model: "proxy-managed", SSE, metadata.user_id estável por conversa.

flowchart TD
    A[montar request<br/>system em camadas + messages do log<br/>tools com cache_control orçado] --> B[messages.stream no proxy LB]
    B --> C[consumir SSE<br/>deltas para o sink, inputs de tool acumulados<br/>usage com cache_creation]
    C --> D{stop_reason}
    D -->|end_turn| E[persistir e fechar o turno]
    D -->|tool_use| F[validar inputs contra o schema<br/>executar em paralelo com timeout<br/>todos os tool_result numa mensagem]
    F --> G[persistir o step<br/>conferir orçamento e tetos<br/>anexar notificações já persistidas]
    G --> B
    D -->|max_tokens, refusal, pause_turn| H[ramo próprio por motivo]
    D -->|janela estourada| I[compactar + 1 retry]

1. Montagem por turno. system em blocos (as camadas do builder de 5.3); messages traduzidas do log de events (user e assistant com blocos text, tool_use e tool_result; thinking preservado byte a byte ou podado por flag); tools com input_schema, em ordem alfabética estável, com cache_control dentro do orçamento de 4 breakpoints (prioridade: system, último user, checkpoint, tools).
2. Por request. client.messages.stream({ model: 'proxy-managed', max_tokens: 64000, system, messages, tools, thinking: { type: 'adaptive', display: 'summarized' }, output_config: { effort }, metadata: { user_id } }) apontado para o proxy. Confirmar no repositório oficial os nomes exatos das opções de endpoint e autenticação (baseURL, apiKey ou authToken, headers por request) antes de codar.
3. Consumo do SSE. Deltas de texto vão para o sink (WebSocket); inputs de tool acumulados até content_block_stop; usage lido de message_start e message_delta, incluindo cache_creation_input_tokens.
4. stop_reason. end_turn persiste e fecha. tool_use valida cada input contra o schema (inválido vira tool_result com is_error, nunca {} silencioso), executa em paralelo (Promise.allSettled, timeout por tool, abort encadeado), anexa todos os resultados numa única mensagem user, persiste o step (fecha o buraco do crash), confere orçamento e tetos de steps e tokens e continua. max_tokens, refusal, pause_turn e janela excedida têm ramos próprios; o 400 de janela estourada dispara compactação e 1 retry automático.
5. Cancelamento. Parar, timeout e orçamento chamam stream.controller.abort() e abortam as tools; a guarda de 5s fica como rede; detector de stall (N minutos sem evento SSE).
6. Retries e erros. Só transitórios tipados (429, 5xx, rede), respeitando retry-after, com jitter. O SDK oficial tem maxRetries (padrão 2) e timeout por request (padrão 10 min) — configurar explicitamente; os erros tipados do SDK (limite de taxa, erro interno, timeout de conexão) viram errorKind próprios, inclusive a negação do gate de concorrência como "ocupado, tente de novo".
7. Notificações no meio do turno. Append direto em messages entre requests, só depois de persistir — o problema do P-07 desaparece por construção, junto com o buffer acumulado manual.
8. Compactação. A própria continua na fronteira, com fallback de emergência; o compactador passa pelo mesmo slot e entra no custo.

Ganhos. Controle total do array por request; cache fino (TTL de 1h, leitura de cache_creation); thinking assinado preservado; cancelamento previsível; retries e timeouts explícitos; fim do reparse do body por step e do interceptor; caminho aberto para tool search, context editing e structured outputs (que pode aposentar o scraping de JSON do agent-step) — se o LB repassar betas e server tools.

Riscos. Reescrever o runner de tools (paralelismo, validação, JSON parcial, is_error); traduzir o histórico legado (o Postgres guarda formas do AI SDK); quebrar o contrato byte a byte com o LB (o SDK oficial compõe o caminho /v1/messages a partir do baseURL, diferente do AI SDK; headers anthropic-version e betas; nomes de eventos SSE; Authorization: Bearer com x-api-key placeholder; metadata.user_id); perder a abstração multiprovider (que o Motor hoje não usa).

Migração em 4 etapas.

1. Tradutor de histórico (log ↔ Messages nativo) com suíte de paridade sobre amostra real; snapshot do wire atual validado contra o LB real, junto com o dono do LB.
2. Interface AgentTransport com duas implementações (AI SDK e nativa); runner nativo atrás de flag por setup; shadow-diff do wire.
3. Compactador no transporte novo.
4. Nativo como padrão, com rollback por flag; depois, remover ai e @ai-sdk/anthropic.

Esforço. A investigação de lacunas estima ~400 linhas alteradas, concentradas em loop.ts, e 6–8 dias úteis de um dev sênior com a rede de testes. A dimensão do loop estima semanas, contando o runner de tools, o histórico legado, o compactador e a bateria de regressão. Planejar com a estimativa maior.

5.2 Tempo real só por WebSocket, com socket.io

flowchart LR
    FE[front: 1 conexão por aba<br/>salas user, thread, run] -->|handshake autenticado<br/>ack em user_message, stop, reset| GW[gateway socket.io /v1<br/>em cada réplica da API]
    GW --- AD[(Redis Streams adapter<br/>salas globais + recuperação)]
    WK[worker: passos de workflow] -->|emite nas salas run| AD
    ENG[engine do turno] -->|eventos com seq e v<br/>persistidos antes de emitir| AD
    GW -->|replay por seq| DB[(Postgres: events e workflow_events)]

• Gateway socket.io ao lado do /ws atual (caminho próprio), com Redis Streams adapter sobre o Redis existente — suporta recuperação de conexão e retoma depois de queda do Redis; o adapter Redis clássico não suporta recuperação. Isso aposenta o broadcaster em memória.
• Salas montadas pelo servidor, a partir da identidade do handshake e da checagem de dono: org:{org}, user:{org}:{user}, thread:{id}, run:{id}. O cliente pede para entrar e o servidor valida (o gate de tenant DM-17 continua). Namespace único versionado (/v1); a investigação de lacunas também sugere namespaces /thread e /run — escolher um.
• Autenticação no handshake com o que já existe (cookie de sessão, bearer de máquina, ticket de uso único); revalidação periódica; fim de sessão publicado para todas as réplicas.
• Servidor → cliente: seq monotônico por sala e v (versão) em todo frame; eventos persistidos antes de emitir; connectionStateRecovery (ex.: até 2 min, sem pular middleware) para quedas curtas; com recovered = false, o cliente pede o que veio depois do último seq e o servidor faz replay a partir do banco. Histórico continua 100% por REST paginado; handshake magro.
• Cliente → servidor com ack e timeout: user_message (ack com enqueued e clientMessageId), stop, reset, join. O clientMessageId vira chave de idempotência persistida (unique na mailbox) e o ack passa a ser a confirmação de entrega.
• Tokens: se ligar streaming no chat, assistant_delta com seq, coalescido em janelas de 30–100 ms e volatile; marcos (fim de bloco, resultado de tool, final) persistidos e numerados.
• Worker → API: o worker emite nas salas pelo adapter (um barramento só no lugar do runbus próprio), ou mantém o runbus com subscribe por run; serverSideEmit para mensagens entre servidores (JSON, sem binário).
• Estado distribuído: busy derivado do lock no Redis e publicado na sala user:; abort por canal assinado, com AbortReason serializado; uma conexão por aba (a sidebar usa a sala user:).
• Proxy HTTP na frente do Motor (o do painel; não confundir com o Load Balance de LLM): upgrade de WebSocket e timeout de leitura acima de 45s (ping de 25s + 20s); sticky só se mantiver o transporte por polling (com transports: ['websocket'] não é necessário, perdendo o fallback); maxHttpBufferSize explícito (padrão do socket.io: 1 MB; hoje o WS aceita 8 MiB) enquanto houver imagem inline — o alvo é upload por HTTP para attachments e referência no evento.
• Catálogo de eventos versionado e único entre be e fe, regra aditiva, protocol: {min, max} no handshake; tipo desconhecido vira métrica.
• Métricas: frames por tipo e canal, conexões e reconexões, bytes de replay, descartes, tipos desconhecidos; gauges de salas e sockets por sala.

↑ voltar ao índice

Corte. socket.io não conversa com cliente WebSocket puro (nem o contrário): o corte é por cliente. Rodar os dois em caminhos separados, com shadow (comparar frames), antes de desligar o /ws. A investigação de lacunas estima ~5–7 dias úteis para a troca de transporte, além das fases F1–F6.

Alternativa (decisão do dono): manter o ws nativo e publicar os eventos de turno no Redis (o canal :stream já existe) com um assinante por réplica. Resolve as várias réplicas com menos mudança, mas sem ack, recuperação e salas prontas: seq, replay e ack teriam de ser construídos à mão.

5.3 Tools e system prompt modulares, com painel de inspeção

Builder de prompt por camadas. Cada camada tem nome, versão, hash e tamanho, em ordem fixa: (1) núcleo do Motor; (2) política da org; (3) persona do setup; (4) instruções da thread; (5) voz; (6) notificações, sempre como dado delimitado. Semântica explícita: o padrão sugerido é somar com rótulo; substituir só com flag explícita e aviso na UI. A seção "suas ferramentas" é gerada a partir das tools realmente montadas no turno (acaba o "sem MCP externo" e o warpgrep). O arquivo base fica em cache por mtime.

Registro de tools.

• Namespace servidor__tool com alias curto; colisão com schemas diferentes vira erro no boot; a toolPolicy cita servidor ou servidor__tool.
• Tetos: tamanho de descrição e schema por tool; resultado de 20–50 mil chars com [TRUNCADO] e leitura paginada; steps por turno (padrão 25–50, configurável) e tokens por turno.
• Validação de argumentos antes de executar; inválido vira erro legível.
• Origem marcada ([mcp:servidor]), allowlist e pin de servidores por org, guard SSRF no connectMcp e no refresh de credencial.
• Núcleo pequeno + carregamento sob demanda: tool search com defer_loading (se o LB repassar) ou seleção própria por request (activeTools).

Módulos (sugeridos pela investigação de lacunas): tools/transport.ts (handshake, listagem, timeouts, refresh); tools/serialize.ts (cache_control, metadata, log); agent/system-prompt.ts (o builder); engine/spawn-policy.ts (idempotência, herança, tetos).

Painel de inspeção — "o que foi enviado ao modelo".

• Persistir por turno (e por step, quando algo mudar): nome, hash e tamanho de cada camada do system; lista final de tools com origem, tamanho e se veio sob demanda; breakpoints de cache plantados; tokens de input, output, leitura e escrita de cache; compactação aplicada; notificações injetadas e em que ponto; config efetiva redigida (sem segredos) e seu hash.
• Expor num endpoint de debug do turno e numa aba "Inspecionar" na timeline e no detalhe do passo de workflow, com diff entre turnos (o que mudou no prefixo e quebrou o cache).
• Acesso: dono da thread e admin.

5.4 Protocolo agente↔subagente

sequenceDiagram
    participant O as Orquestradora
    participant M as Motor
    participant F as Filho
    O->>M: agent_spawn com contrato<br/>objetivo, fronteiras, formato, tools, orçamento, parada
    M->>M: confere tetos de profundidade, largura e orçamento da árvore
    M->>F: thread própria + tarefa
    F->>M: resultado: status, resumo de até 4–8 mil chars,<br/>referência ao threadId ou artefato, usage
    M->>O: notificação delimitada como dado não confiável
    O->>M: Parar ou agent_abort
    M->>F: abort em cascata na subárvore

• Spawn com contrato: objetivo; fronteiras (inclusive escopo de escrita — arquivos ou worktree por filho); formato de entrega; tools (allowlist aplicada também às nativas); orçamento (steps, tokens ou USD) e condição de parada; setup, com regra de persona explícita.
• Tetos determinísticos: profundidade, largura por pai, filhos simultâneos por org (distribuído), orçamento por árvore e limite de turnos por filho com resultado parcial; recusa com erro legível que oriente a consolidar.
• Retorno: status, resumo denso (até 4–8 mil chars), referência ao threadId ou artefato e usage; delimitado como dado não confiável, com marcadores de papel neutralizados.
• Ciclo de vida: cancelamento em cascata pela árvore (ou raiz marcada como cancelada, descartando notificações de subárvore morta); reaper ligado em uma réplica, com liderança; abort distribuído com causa tipada.
• Prompt da orquestradora: amortecedor de delegação e regras de cardinalidade (4.1); aviso de workspace compartilhado.
• Tempo real: o pai assina a sala da família e vê o progresso dos filhos sem polling.

5.5 Workflows

Manter o núcleo — reconciliador, barreiras, snapshot por setup, pause e cancel, custo consolidado —, que está à frente do mercado. Mudanças:

• tetos padrão da instalação em produção (WF_DEFAULT_MAX_*), aviso explícito no workflow_draft e, opcionalmente, WF_REQUIRE_BUDGET;
• lista de passos sem output (só no detalhe e no frame step_output); log do run por cursor de seq; lista de runs numa query só;
• correções de corrida (requestResume, requestPause, startRun com a mesma chave), prazo de pausa e renovação da lease em ticks longos;
• no passo agent: cache declarativo por setup (TTL de 1h e breakpoints), curadoria e defer_loading de tools por setup, alias de modelo por passo para routing, ttftMs e taxa de acerto de cache por passo, e WF_AGENT_MAX_TOOL_STEPS definido;
• agendamento (schedule): implementar ou tirar do enum e documentar;
• longo prazo: sinalizar um sub-run em andamento (hoje só há pause e cancel).

5.6 Contratos entre aplicativos

Motor ↔ Load Balance (proxy de LLM):

↑ voltar ao índice

Outros aplicativos:

• Proxy HTTP do MyPanel na frente do Motor: upgrade de WebSocket, timeout de leitura acima de 45s, sticky se houver transporte por polling.
• Conta (SSO/OIDC) e webhook de provisionamento: versão explícita no envelope; recusar versão maior desconhecida.
• MCPs do MyPanel e do AgentPack: negociar e logar a versão do protocolo; namespace e pin da lista de tools; guard SSRF; descrições compactas e respostas paginadas (aqui o Motor controla os dois lados).
• Webhooks de saída (clientes do Motor): https obrigatório, safeRequest, versão no envelope, assinatura mantida.
• Frontend: catálogo de eventos versionado e compartilhado; protocol: {min, max} no handshake.
• Worker ↔ API: um barramento só (adapter do socket.io) ou runbus com subscribe por run.

6. Roadmap priorizado em ondas

Esforço: P (horas a 1 dia), M (dias), G (semana ou mais). Risco = risco da mudança em si.

Onda 1 — Rápido (dias): estancar custo, segurança e travamentos

↑ voltar ao índice

Onda 2 — Médio (semanas): custo real e várias réplicas

↑ voltar ao índice

Onda 3 — Estrutural (meses)

↑ voltar ao índice

flowchart LR
    A16[1.6 abort entre réplicas] --> B23[2.3 estado distribuído]
    A17[1.7 reaper ligado] --> B23
    A111[1.11 max_connections] --> B26[2.6 banco e Redis]
    B23 --> R2[2ª réplica da API]
    B26 --> R2
    B29[2.9 protocolo versionado] --> C32[3.2 socket.io]
    B23 --> C32
    C32 --> R2
    B25[2.5 cross-tenant] --> ORG[troca de org na UI]
    B210[2.10 namespace de tools] --> C33[3.3 tools sob demanda]
    LB[acordo com o dono do LB] --> C31[3.1 loop nativo]
    LB --> B22[2.2 custo real]
    LB --> C33

Leitura do grafo: a 2ª réplica da API só deve subir depois de 1.6, 2.3, 2.6 e do broadcast distribuído (3.2 ou a alternativa ws + pub/sub); a troca de org na UI só depois de 2.5; tool search e o custo exato dependem do LB.

7. Perguntas de negócio e decisões do dono

Decisões necessárias:

1. Escala: quando subir a 2ª réplica da API e qual a meta de simultaneidade (usuários e turnos)? Define a urgência da onda 2.
2. Banco: confirmar max_connections em produção; manter "nunca reduzir o pool" e subir o Postgres para ≥ 2100, ou adotar PgBouncer?
3. Redis: separar fila e cache (REDIS_QUEUE_URL), hoje juntos numa instância de 512 MB sem teto de memória?
4. Política de custo: tetos padrão por turno (steps e tokens), por run (WF_DEFAULT_MAX_*) e por árvore de subagentes; orçamento fail-open (hoje) ou fail-closed quando o Redis cai?
5. Cobrança: o custo exibido precisa ser exato para cobrar clientes? Isso decide entre preço por rota no Motor e custo informado pelo LB.
6. SDK nativo: aprovar a migração incremental, abrindo mão da abstração multiprovider (hoje o Motor só fala Anthropic via LB)?
7. Tempo real: socket.io (como pedido) ou evoluir o ws nativo com pub/sub? Streaming token a token no chat é desejado? O corte por cliente é aceitável?
8. Multi-org: quando a UI terá troca de org? O conserto cross-tenant precisa vir antes.
9. Tools: "nega por padrão" com curadoria por setup? Quais MCPs ficam no núcleo? Só admin cadastra MCP? Allowlist de hosts?
10. System prompt: a camada da thread soma ou substitui a da org e a persona? O filho que herda o setup deve herdar a persona?
11. Subagentes: rever D4/D6 (largura e profundidade ilimitadas) e adotar tetos por árvore? Isolar a escrita por filho (worktree)?
12. Slot de concorrência: manter por turno (desenho RATE-003) ou passar a por request?
13. Workflows: exigir budget? Implementar o agendamento (schedule) ou retirá-lo?
14. Retenção: política para events de threads ativas (hoje mantidos para sempre, por decisão)?
15. Thinking: assumir a poda (e documentar) ou investir em preservar o thinking assinado?
16. Load Balance: quem coordena com o dono do LB as mudanças de contrato (cache_creation, modelo e custo, betas, versão)?
17. Publicação: este relatório deve ir para o AgentPack de produção atual (agentpack-v0)? Requer conexão MCP autenticada com a instalação correta (ver o fim do documento).

Perguntas abertas que dependem de dados que o scan não leu:

• .env efetivo de produção (mascarado no painel): DB_CONNECTION_LIMIT, ORG_CONCURRENCY_MAX, WF_*, CACHE_*, CHAT_TRUST_PROXY, METRICS_TOKEN; REAPER_ENABLED não aparece na lista de variáveis.
• Topologia e borda: réplicas, sticky no proxy do painel, API e WS na mesma origem no build do front.
• Tráfego real: turnos por minuto no pico, duração p50/p95 do turno, maior thread, taxa de 429/503 do proxy, taxa de acerto do cache (métricas Prometheus de tokens).
• Tamanho real das definições dos MCPs de produção; filhos por pai (p99); tamanho típico do finalText; existência de netos.
• Lado do LB: limpeza de sampling e thinking por modelo, cache_creation no usage, modelo real no SSE, repasse de betas e server tools.
• Nomes exatos das opções do SDK oficial para endpoint e autenticação customizados.
• O pool MCP é compartilhado entre orgs quando URL e headers coincidem, e é seguro no transporte SSE? (um revisor citou risco de credencial entre orgs no bn-mcp.html; não verificado)
• O runAgentStep adquire slot de concorrência da org? A ordenação alfabética das tools é estável? pruneConsumedMailbox é chamada?
• Há threads com pruneOldThinking: false e histórico legado com reasoning assinado (define a urgência do replay)?

8. Fontes

Anthropic — engenharia e pesquisa

• Building effective agents
• How we built our multi-agent research system
• Effective context engineering for AI agents
• Writing effective tools for agents
• Advanced tool use

Anthropic — Claude Code e Agent SDK

• Agent SDK — Subagents
• Claude Code — Subagents
• Claude Code — Dynamic workflows

Anthropic — plataforma e API Messages

• Prompting best practices
• Prompting Claude Opus 5
• Streaming messages
• TypeScript SDK
• SDK helpers (helpers.md)
• Handle tool calls
• Parallel tool use
• Define tools
• Fine-grained tool streaming
• Prompt caching
• Thinking
• Extended thinking
• Token counting
• Context editing
• Tool search tool
• Programmatic tool calling
• Memory tool
• MCP connector
• Handling stop reasons
• Rate limits
• Batch processing
• Features overview (GA × beta)

Mercado — multiagentes e execução durável

• Cognition — Don't build multi-agents
• OpenAI Agents SDK — Orchestrating multiple agents · Handoffs · Guardrails · Tracing
• LangGraph — Interrupts
• Inngest — Steps
• Restate — Durable steps
• DBOS — Workflow tutorial
• Temporal — Activities · Retry policies
• CrewAI — Flows
• AutoGen — Teams · Human in the loop · State
• Why do multi-agent LLM systems fail? (MAST)

Tempo real

• Socket.IO v4: Rooms · Namespaces · Delivery guarantees · Connection state recovery · Redis Streams adapter · Redis adapter · Using multiple nodes · Middlewares · Client options · Emitting events · Server options · Server API
• ws (README)
• OpenAI — Responses API WebSocket mode
• MDN — Using server-sent events

Fontes internas (repositório motor, HEAD 69e0b28)

• Código citado em cada achado (be/src/**, fe/src/**, be/prisma/schema.prisma).
• be/docs/contrato-load-balancer.md; docs/operacao.md; docs/workflows/00-visao-geral.md, 02-arquitetura.md, 04-contrato-runtime.md, 05-guia-operacional.md, 08-matriz-de-testes.md e 08-matriz/; docs/motor-agent-prod-readiness/*.html; docs/auth-sso.md; docs/api-terceiros.md; docs/setups/00-decisoes.md; docs/lockfiles.md.
• Produção (somente leitura, pelo painel): logs de motor-be-ws e motor-worker-ws; estatísticas dos serviços; postgresql.conf do <container interno (prod PG)>; configuração do <container interno (prod Redis)>; lista de variáveis (valores mascarados).

Publicação

O relatório completo está neste arquivo, no sandbox motor: /workspace/.sbcache/scan-motor-2026-10-11/RELATORIO.md.

Não foi publicado no AgentPack. O MCP agentpack-orq desta sessão aponta para a instalação antiga (<host interno (AgentPack antigo)>), não para a produção atual (<host interno (AgentPack prod)>). Por instrução, nada foi publicado na instalação antiga e nenhuma configuração ou credencial foi alterada para contornar isso. Publicar na produção atual depende de uma conexão MCP autenticada com a instalação correta; o knowledgeId fica vazio até lá. Isso não bloqueia a conclusão do scan.