API

Sessão

O Brabo executa trabalho de engenharia por agentes de IA. Duas forças moldam praticamente toda regra daqui:

O agente não é confiável por construção. É um modelo de linguagem: pode alucinar, entrar em loop ou pedir algo destrutivo. As regras existem para que o dano possível seja limitado pela estrutura, não pela qualidade do prompt.

O gasto é real e contínuo. Todo turno consome token pago. Orçamento, teto e medição não são conveniências administrativas — são o que impede um loop de agente de virar prejuízo.

Atores

O vocabulário está no glossário.

Contexto de negócio

RN-001 — A sessão tem cinco estados e transições fechadas

created → active → closing → closed, com closed_abnormally alcançável de qualquer estado não terminal. De closing nunca há volta para active, e os estados terminais não têm saída.

stateDiagram-v2
  [*] --> created
  created --> active
  created --> closed_abnormally: falha no provisionamento
  active --> closing
  active --> closed_abnormally
  closing --> closed
  closing --> closed_abnormally
  closed --> [*]
  closed_abnormally --> [*]

• Onde: src/domain/sessions/session-state-machine.ts:29
• Teste: test/domain/sessions/session-state-machine.spec.ts
• Caso de borda: closing é um estado transitório. Uma sessão presa nele significa que o dreno começou e não terminou — há alerta para isso, ver o runbook.

RN-002 — Todo evento de sessão é imutável e o seq é denso

Nunca há UPDATE em session_events. O seq é único por sessão (unique(session_id, seq)) e não tem buracos: começa em 1 e é contíguo.

• Onde: src/db/schema/sessions.ts (tabela session_events)
• Teste: conferido no restore — docker/backup/restore.sh falha se count(*) ≠ max(seq) − min(seq) + 1 ou min(seq) ≠ 1
• Por quê: é o que torna rastreável a evidência do Psicólogo e verificável o backup. Estado que precisa mudar mora em tabela própria, ao lado.

Aprovação de ações

O coração do sistema. Toda ação com efeito externo nasce como proposed_action.

RN-003 — A ação tem seis estados, e negada é terminal

stateDiagram-v2
  [*] --> pending
  [*] --> auto_approved: a política permitiu
  pending --> approved: usuário aprova
  pending --> denied: usuário nega
  approved --> executed
  approved --> failed
  auto_approved --> executed
  auto_approved --> failed
  denied --> [*]
  executed --> [*]
  failed --> [*]

• Onde: src/domain/actions/action-state-machine.ts:36
• Teste: test/domain/actions/action-state-machine.spec.ts
• Caso de borda: uma ação aprovada que executou vira executed, não continua approved. Contar aprovações por status = 'approved' dá o número errado — o critério correto é decided_by IS NOT NULL.

RN-004 — A decisão é avaliada em três estágios, e deny vence na hora

Ordem: (a) IAM → (b) agent_autonomy → (c) permissions.json. Cada estágio só pode subir a permissividade; um estágio calado nunca rebaixa o anterior. deny em qualquer estágio retorna na hora.

• Onde: src/domain/actions/decide.ts:120
• Teste: test/domain/actions/decide.spec.ts (10 KB — o maior do domínio)

RN-005 — Papel mínimo por tipo de ação

Antes de qualquer política, o IAM: cada ActionType exige um papel efetivo mínimo. Sem ele, deny com motivo explícito.

• Onde: src/domain/actions/decide.ts:117 (MIN_ROLE_FOR_ACTION_TYPE)
• Teste: test/domain/actions/decide.spec.ts

RN-006 — Teto: merge em branch protegida nunca é auto-aprovável

dev, qa, rc e main são protegidas. Um git_merge que mira uma delas é rebaixado de auto_approve para require_approval depois que toda a política rodou. Nem agent_autonomy nem permissions.json conseguem promovê-lo.

rc continua na lista mesmo depois que a etapa saiu da política (ADR 0030) e o bootstrap deixou de criá-la (RN-029). Esta lista decide o que a trava recusa, e repositórios criados por versões anteriores ainda têm a branch: proteger uma que não existe não custa nada; desproteger uma que existe custa caro.

• Onde: src/domain/actions/decide.ts:523 (isProtectedBranch, o teto da trava de merge) + protected-branches.ts:4
• Teste: test/domain/actions/decide.spec.ts
• Origem: ADR 0011 §1
• Nota: a proteção equivalente na plataforma (GitHub/GitLab) diverge entre os providers e não é o portão — ver ADR 0028.

RN-007 — Teto: patch de instrução nunca é auto-aprovável

Mudar a instrução de um agente sempre exige decisão humana. O valor da funcionalidade está no humano ver o diff; auto-aprovar seria o agente se reescrevendo.

• Onde: src/domain/actions/decide.ts:170
• Teste: test/domain/actions/decide.spec.ts
• Origem: ADR 0016 §8

RN-008 — O casamento de comando é por padrão, não por substring

O permissions.json casa um comando de terminal por padrão estruturado, com o comando devidamente tokenizado — não por includes().

• Onde: src/domain/actions/command-matcher.ts
• Teste: test/domain/actions/command-matcher.spec.ts

Backlog

RN-009 — A história tem quatro estados, e done é terminal

draft → ready → in_progress → done. Retrabalho é permitido: ready → draft e in_progress → ready.

stateDiagram-v2
  [*] --> draft
  draft --> ready: passa na checagem de prontidão (RN-010)
  ready --> in_progress
  ready --> draft: retrabalho
  in_progress --> done
  in_progress --> ready: devolvida
  done --> [*]

• Onde: src/domain/backlog/story-state-machine.ts:27
• Teste: test/domain/backlog/story-state-machine.spec.ts

RN-010 — draft → ready exige quatro coisas, validadas no domínio

Para uma história virar ready ela precisa, de todas:

1. dod não vazio — Definition of Done
2. dor não vazio — Definition of Ready
3. pelo menos 1 requisito funcional (rf)
4. pelo menos 1 regra de negócio ligada (businessRuleIds)

O erro nomeia exatamente o que falta, não um "inválido" genérico.

• Onde: src/domain/backlog/story-readiness.ts:39
• Teste: test/domain/backlog/story-readiness.spec.ts
• Origem: ADR 0009 §3
• Por quê: é o que impede o PO de despejar uma história vaga na fila do dev.

RN-011 — Regra de negócio sem história é achado, não erro

A cobertura regra→história é calculada, e o que não tem história aparece como pendente — informação, não falha.

• Onde: src/domain/backlog/coverage.ts
• Teste: test/domain/backlog/coverage.spec.ts

RN-013 — O grafo de módulos não pode ter ciclo

• Onde: src/domain/architecture/module-graph.ts
• Teste: test/domain/architecture/module-graph.spec.ts

Gates de PR

RN-014 — A ordem dos gates é imutável e awaiting_user é terminal

awaiting_qa → awaiting_secops → awaiting_user. Aprovar o QA nunca pula direto para o usuário. changes_requested devolve ao dev na mesma branch, sem PR nova.

stateDiagram-v2
  [*] --> awaiting_qa
  awaiting_qa --> awaiting_secops: QA aprova
  awaiting_qa --> awaiting_qa: changes_requested (volta ao dev)
  awaiting_secops --> awaiting_user: SecOps aprova
  awaiting_secops --> awaiting_secops: changes_requested
  awaiting_user --> [*]: o merge é do humano

• Onde: src/domain/execution/pr-gate-state-machine.ts:24
• Teste: test/domain/execution/pr-gate-state-machine.spec.ts
• Origem: ADR 0013 §1
• Caso de borda: awaiting_user é terminal por desenho — o sistema nunca faz merge (RN-006).

RN-015 — Ciclo K: o teto de correção é finito e herdado

Toda volta de gate consome uma rodada. Esgotado o teto, a tarefa fica bloqueada com motivo, em vez de girar para sempre. Um subagente criado pela paralelização herda o teto do agente-base.

Desde a Fase 8b o teto vale também para a ÁREA de QA, sem mudança de código: o QaLeadServer é o único chamador de record_gate_verdict, então uma rodada de gate — não importa quantas especializações ela consultou por baixo — continua consumindo exatamente UMA rodada. Ver RN-036.

• Onde: DEFAULT_MAX_GATE_CORRECTIONS = 3 em src/application/use-cases/execution/record-gate-verdict.use-case.ts:21; aplicado em activate-execution.use-case.ts:89 e, no engine, em qa_lead_server.ex:268 e secops_agent_server.ex:142
• Teste: apps/engine/test/engine/gates/qa_automacao_agent_test.exs (a especialização devolve {:blocked, ...} sem chamar a api) e qa_lead_server_test.exs (o Lead NUNCA chama record_gate_verdict nesse caso — é isso que impede a correção de ser queimada)
• Origem: ADR 0017 §4

RN-017 — Orçamento tem escopo exclusivo: projeto ou sessão

Um budget referencia um projeto ou uma sessão, nunca os dois — garantido por um check no banco de dados, não só no código.

• Onde: src/db/schema/llm.ts (budgets_scope_check)
• Teste: a constraint é a garantia

RN-018 — Notificação de orçamento em 70%, 90% e 100%, sem repetir

Cada limiar dispara uma vez; o último notificado fica persistido em budgets.last_threshold_notified.

• Onde: src/domain/llm/budget-threshold.ts:1
• Teste: test/domain/llm/budget-threshold.spec.ts

RN-019 — policy = 'block' recusa a chamada; 'allow' só registra

• Onde: src/domain/llm/budget-threshold.ts:4
• Caso de borda: um projeto em allow não se detém no teto. É a causa mais comum de "o orçamento não segurou" — veja o runbook.

RN-020 — O modelo é resolvido em cascata, do mais específico ao mais geral

session > agent > area > project > workspace. Vence o primeiro que existir. area entrou na FASE 23 — veja a RN-102 para a posição dela e o que muda para quem já leu esta cascata.

• Onde: src/domain/llm/binding-resolver.ts
• Teste: test/domain/llm/binding-resolver.spec.ts

Psicólogo e Anamnese

RN-021 — Hipótese sem evidência válida não é gravada

Os evidenceEventIds precisam apontar para eventos que existem e pertencem à sessão analisada. A validação é atômica por lote: um id inválido reprova o lote inteiro.

• Onde: src/domain/psychologist/hypothesis-evidence.ts
• Teste: test/domain/psychologist/hypothesis-evidence.spec.ts
• Origem: ADR 0015 §3

RN-022 — O ciclo de vida da hipótese é compare-and-swap

proposed → accepted | dismissed. Duas decisões concorrentes sobre a mesma hipótese: uma vence, a outra recebe conflito — não 500, não silêncio.

• Onde: src/domain/psychologist/hypothesis-lifecycle.ts
• Teste: test/domain/psychologist/hypothesis-lifecycle.spec.ts
• Origem: ADR 0022 §7

RN-024 — A Anamnese só perfila competência do catálogo — guarda-corpo estrutural

Competências de processo são seis, fechadas: git, agile, arquitetura, testes, seguranca, infra. Mais as stacks técnicas derivadas do module_map. Qualquer outra coisa — "ansiedade", "saúde mental" — não tem caminho de escrita: é erro no domínio, não instrução de prompt.

• Onde: src/domain/anamnese/competency-catalog.ts:16
• Teste: test/domain/anamnese/competency-catalog.spec.ts
• Origem: ADR 0016 §1
• Por quê: a Anamnese perfila competência técnica, não pessoa. O limite é estrutural porque uma instrução de prompt não é garantia.

RN-025 — Apagar o perfil apaga de verdade, e o opt-out impede a re-derivação

• Onde: src/domain/anamnese/proficiency-profile.entity.ts + tabela anamnese_opt_outs
• Origem: ADR 0016 §2

RN-026 — Patch de instrução negado não é reproposto

A comparação é sobre o conteúdo normalizado, não sobre o texto literal: reindentar o mesmo patch não o transforma em proposta nova. Não há tabela de dedup — a fonte é o próprio histórico de proposed_action com actionType = instruction_patch e status = denied.

• Onde: src/domain/instructions/patch-dedup.ts:22
• Teste: test/domain/instructions/patch-dedup.spec.ts

RN-027 — Rollback de instrução é operação para frente

Reverter cria uma versão nova com o conteúdo antigo; não apaga histórico. A tabela de versões é append-only.

• Onde: src/domain/instructions/
• Origem: ADR 0016 §4

Git

RN-029 — O bootstrap de Gitflow é idempotente e retomável

Cinco passos; cada um verifica antes de agir e pode ser retomado do ponto que falhou. skip é sucesso, não erro.

Eram seis. O sexto criava a branch rc, degrau que o ADR 0030 removeu da política — o bootstrap continuou criando, protegendo e documentando no repositório do usuário uma escada que o produto já tinha abandonado (achado #3 do primeiro dogfooding). O valor create_rc_branch continua no enum bootstrap_step: linhas antigas o referenciam, e passo que aconteceu de verdade não se apaga do histórico.

• Onde: src/application/use-cases/git/bootstrap-steps.ts + domain/git/repo-bootstrap.entity.ts (RETIRED_BOOTSTRAP_STEPS)
• Teste: test/domain/git/repo-bootstrap-status.spec.ts
• Origem: ADR 0005

RN-030 — Reapresentar um refresh já usado revoga a família inteira

Cada refresh consome o token apresentado e emite um filho com o mesmo family_id e o mesmo family_started_at. Apresentar um token que já foi consumido é a assinatura de um roubo — alguém está usando uma cópia — e a resposta é revogar todos os tokens vivos daquela família, com evento de segurança.

O usuário legítimo é deslogado junto. Isso é o comportamento correto, não um defeito: do lado do servidor, um duplo-submit do cliente e um replay de ladrão são idênticos.

• Onde: src/domain/auth/refresh-token.ts:50 + application/use-cases/auth/refresh.use-case.ts:98
• Teste: test/application/use-cases/auth/rotacao-e-reuso.spec.ts
• Borda: quem apresenta um token de família já revogada é vítima a jusante, não novo roubo: registra refresh_revoked e não dispara segunda cascata. Sem essa distinção, cada aba do usuário legítimo geraria um alarme falso durante o incidente.
• Origem: ADR 0031

RN-031 — Falha de login é contada por e-mail e por IP, e o bloqueio escala

Janela deslizante de 15 minutos no Postgres, sem Redis. Dois baldes por tentativa e o mais restritivo vence: e-mail (5 falhas → 30s, 8 → 5min, 12 → 15min) e IP (20 → 30s, 30 → 2min). Um login bem-sucedido limpa o balde do e-mail; o de IP drena só por tempo.

A chave do balde é o e-mail normalizado, nunca o id do usuário. Com id, o balde só existiria depois de encontrar a conta, e o próprio lockout viraria oráculo de existência.

• Onde: src/domain/auth/lockout-policy.ts:97 + infrastructure/persistence/drizzle/drizzle-login-throttle.ts:74
• Teste: test/application/use-cases/auth/lockout.spec.ts
• Borda: enquanto bloqueado, a tentativa não é registrada. Se fosse, um atacante manteria a conta da vítima travada para sempre só continuando a tentar — o lockout viraria negação de serviço contra quem ele protege.
• Por quê: o balde de IP não pode ser limpo no sucesso; quem tem uma conta válida zeraria a janela à vontade e pulverizaria palpites sem limite.
• Origem: ADR 0031

RN-032 — Nenhuma resposta distingue conta existente de inexistente

Qualquer resposta diferente da falha uniforme só é alcançável depois de uma verificação de senha bem-sucedida. No login, e-mail inexistente, senha errada e conta bloqueada devolvem o mesmo 401 e gastam o mesmo tempo — o ramo sem conta verifica contra um hash dummy gerado com os mesmos parâmetros do real. No registro e no pedido de reset, endereço conhecido e desconhecido devolvem 202.

• Onde: src/application/use-cases/auth/login.use-case.ts:79 + register.use-case.ts:74
• Teste: test/application/use-cases/auth/enumeracao.spec.ts
• Borda: a checagem de bloqueio por e-mail roda depois do argon2, não antes. Sair mais cedo é a otimização que qualquer revisor sugeriria, e é exatamente o vazamento — o teste fica vermelho se alguém a introduzir.
• Borda: o usuário MIGRADO do Keycloak (existe em users, sem linha em auth_credentials) também recebe o 401 uniforme — e o link de "definir senha" é disparado em silêncio. Responder password_pending confirmaria que o endereço existe e que é conta legada. Por isso findByEmail é um LEFT JOIN numa consulta só: duas consultas encadeadas fariam esse ramo pagar uma ida a mais ao banco, e o relógio revelaria o que o corpo esconde.
• Por quê: o que se afirma é "nenhum ramo pula o trabalho caro e nenhum produz resposta distinguível", não tempo constante. Ver as consequências no ADR.
• Origem: ADR 0031, borda do migrado em ADR 0032

RN-033 — Token de verificação e de reset vale uma vez só

Consumo por UPDATE condicional com returning: o próprio UPDATE é a guarda. Zero linhas cobre inexistente, de outro propósito, já consumido, invalidado e expirado — todos com a mesma resposta. Pedir um link novo invalida o anterior. Concluir um reset revoga todas as sessões do usuário e não emite tokens.

• Onde: src/infrastructure/persistence/drizzle/account-token.repository.ts:76
• Teste: test/application/use-cases/auth/tokens-de-conta.spec.ts
• Borda: dois envios simultâneos não passam os dois. A corrida é o caso normal, não a exceção: scanner de e-mail corporativo abre todo link de toda mensagem, então o robô costuma consumir o token antes do humano clicar.
• Por quê: o reset não emite sessão de propósito — logar direto a partir de um link recebido por e-mail faria comprometer o e-mail equivaler a tomar a conta, sem segundo passo.
• Origem: ADR 0031

RN-034 — A sessão da web vive em cookie httpOnly, com CSRF

O refresh token vai num cookie brabo_refresh (httpOnly, SameSite=Strict, Path=/auth, Secure em produção) e não aparece no corpo de nenhuma resposta. O access token, de 15 minutos, fica em memória no cliente e viaja no Authorization: Bearer.

/auth/refresh e /auth/logout exigem X-CSRF-Token igual ao cookie brabo_csrf, comparado em tempo constante.

• Onde: src/interfaces/http/auth/session-cookies.ts:53 + interfaces/http/auth/auth.controller.ts
• Teste: test/interfaces/session-cookies.spec.ts
• Borda: falha de CSRF é 403, não 401. Com 401 o cliente tentaria renovar a sessão e entraria em laço — a credencial está boa, quem está errada é a requisição.
• Por quê: devolver o refresh também no corpo anularia o httpOnly — bastaria um XSS ler a resposta do login, e levaria a sessão longa em vez dos 15 minutos do access.
• Origem: ADR 0032

RN-035 — O tráfego interno engine ↔ api exige o segredo de serviço

As 32 rotas /internal/* são @ServiceRoute(): ficam fora do JWT de usuário e fora do rate limit. Quem autentica é o EngineServiceGuard, comparando X-Brabo-Service-Token com BRABO_SERVICE_TOKEN em tempo constante. O mesmo segredo vale nos dois sentidos, e BRABO_SERVICE_TOKEN_PREVIOUS é aceito só na verificação, para a rotação não ter janela de indisponibilidade.

• Onde: src/interfaces/http/auth/engine-service.guard.ts:44 + infrastructure/security/service-token.ts + apps/engine/lib/engine_web/plugs/verify_service_token.ex
• Teste: apps/engine/test/engine_web/plugs/verify_service_token_test.exs, test/interfaces/route-surface.spec.ts e, para a rotação do lado da api (anterior aceito só na verificação, quem chama manda o atual, removido o anterior o velho cai), test/infrastructure/security/service-token.spec.ts (describe "rotação do BRABO_SERVICE_TOKEN") e test/interfaces/engine-service.guard.spec.ts (RN-597)
• Borda: a isenção de rate limit vem do METADADO da rota, não do guard. O RateLimitGuard é APP_GUARD e roda antes de qualquer guard de controller — quando ele decide, o EngineServiceGuard ainda não rodou.
• Origem: ADR 0032

RN-038 — Agente contado no resumo do workspace = gastou tokens este mês

O resumo do dashboard de projetos ("N projetos ativos · M agentes · gasto este mês") conta como "agente" quem tem pelo menos uma linha em token_usage com actor_kind = 'agent' no mês corrente, somando todos os projetos do workspace. Sem o filtro de actor_kind, um user mandando chat ou um system registrando uso inflaria a contagem — token_usage grava para qualquer tipo de ator, não só agente. O corte por mês usa created_at >= date_trunc('month', now()); um agente que trabalhou só no mês anterior não conta, mesmo que ainda apareça no roster de alguma sessão. A contagem naturalmente inclui as subespecialidades de área da Fase 8 (qa-automacao, qa-performance-seguranca, infra-workflows): cada uma tem seu próprio actor_id quando gasta tokens.

• Onde: src/infrastructure/persistence/drizzle/token-usage.repository.ts (summarizeForWorkspaceThisMonth)
• Teste: test/application/use-cases/iam/get-workspace-summary.use-case.spec.ts

RN-040 — Binding de agente exige tool calling nativo

Vincular um modelo a um agente (scope = 'agent') só é permitido se o modelo tiver supports_tool_calling. Um agente só existe dentro do ToolLoop, e o ToolLoop só funciona se o modelo souber pedir ferramentas; sem isso, a falha apareceria adiante como "o agente parou sem terminar", que é exatamente o diagnóstico por eliminação que o ADR 0020 proibiu. A recusa é um 422 e a mensagem aponta para o filtro "aptos para agentes" — sem esse apontamento a regra vira um beco sem saída.

O ToolCallRecovery do engine recupera chamadas que o modelo escreveu em prosa, mas é um resgate, não uma licença: depende de o modelo acertar o formato por acaso.

Só agent valida. workspace e project são o fallback do chat humano e session é conversa — nenhum deles roda um ToolLoop, e travá-los proibiria modelos só de chat no produto. O agente context-manager está coberto por construção: é um slug dentro do escopo agent, não um escopo próprio.

Nota aditiva — o filtro passou a vir MARCADO, e quem o liga é o ESCOPO. O parágrafo acima diz que a recusa aponta para o filtro "aptos para agentes", "senão a regra vira beco sem saída" — e por muito tempo ela foi um: o prop que abre o seletor com o filtro marcado existia desde a Fase 9c e nenhuma tela de produção o passava. O seletor de um agente abria oferecendo modelo chat-only cujo clique só existia para ser recusado. As duas telas que gravam num escopo validado passam a abrir filtradas — ModelsSection (agente e a caixa da área na linha do lead, RN-912) —, e a régua de quem liga não é a tela e sim assertModelFitsBindingScope: onde a api RECUSA, o filtro vem marcado; onde ela não recusa, quem escolhe é a pessoa. Por isso o seletor de SESSÃO continua sem filtro — marcar ali esconderia modelo que a api aceita. Isto não elimina o 422: o filtro cobre uma das três causas, e as outras duas (RN-043 — desativado no workspace, sumido do provider) seguem alcançáveis, com o indisponível ainda LISTADO e marcado; o desfecho de recusa da RN-470 continua sendo o que conta o que houve. E é estado INICIAL de um checkbox, não trava: desmarcar volta a listar tudo.

A consequência: o vigente que o filtro esconde é DITO. workspace e project nunca exigiram tool calling, e as rotas que resolvem o binding de um agente ou de uma área chamam ResolveModelBindingUseCase sem exigeToolCalling — então um padrão chat-only desses níveis é resolvido normalmente e vira o vigente da linha. Com o filtro marcado, o gatilho mostrava um nome que a lista aberta não continha, sem nenhuma opção marcada. O picker agora nomeia o modelo e a causa; ele PODE nomear a causa porque só há um filtro ali. Quando a lista inteira fica vazia, quem fala continua sendo o texto de lista vazia, que já manda desmarcar — dois avisos sobre o mesmo checkbox seriam ruído.

Correção de fato, não do texto acima: "Only agent validates" descreve a Fase 9a. Desde o ADR 0064 area entra na MESMA validação — ela não é fallback genérico, o único consumidor do modelo de uma área é um agente dela (RN-102) —, e é por isso que são DUAS as telas que ligam o filtro.

• Onde: src/domain/llm/model-capabilities.ts:38; apps/web/src/components/ModelPicker.tsx (o filtro e o aviso de vigente escondido), apps/web/src/routes/settings/ModelsSection.tsx (quem o liga, no seletor do agente e no do lead que segue a área)
• Teste: test/domain/llm/model-capabilities.spec.ts, test/application/use-cases/llm/set-model-binding.use-case.spec.ts; apps/web/src/routes/settings/filtro-de-aptos.test.tsx e apps/web/src/routes/SessionPage.filtro-de-aptos.test.tsx (as duas telas que ligam, e a que não liga)
• Origem: ADR 0041

RN-041 — Contagem de tokens que o provider não deu é marcada como estimada

Quando a resposta do provider não traz usage, a base compatível com OpenAI conta localmente com o tokenizer e emite o chunk com estimated: true. O número ainda serve para cobrança, mas a marca preserva a diferença entre "o provider disse zero" e "o provider não disse nada" — e é o que permite à UI qualificar o custo em vez de mostrar um valor sem procedência.

Os outros dois providers divergem, e a divergência é normalizada, não escondida: o Ollama simplesmente não emite usage sem a linha done; o Anthropic não pode omitir a contagem, porque usage é obrigatório no message_start do protocolo dele. As três respostas estão em docs/reference/llm-providers.md.

• Onde: src/infrastructure/llm/openai-compatible-provider.ts:167
• Teste: test/contract/llm-provider.contract.ts (cenário sem_usage, rodado contra os três providers)
• Origem: ADR 0041

RN-042 — O metering registra quem ATENDEU a chamada, não só por onde ela entrou

Quando a chamada passa por um hub que informa o provider real, token_usage registra esse provider em upstream_provider, além do provider de entrada. Sem hub — ou com um hub que não informou — o campo é null, nunca string vazia: a consulta de custo por provider precisa distinguir "não passou por hub" de "passou por um e o hub não disse".

Nas métricas, o rótulo upstream_provider repete o próprio provider quando não há hub, de modo que sum by (upstream_provider) continua somando o custo inteiro.

• Onde: src/application/use-cases/llm/record-llm-usage.use-case.ts:73
• Teste: test/application/use-cases/llm/record-llm-usage.use-case.spec.ts
• Origem: ADR 0041

RN-043 — Um modelo descoberto entra desabilitado; um modelo que desaparece é marcado, nunca apagado

A sincronização do catálogo tem três desfechos, e nenhum é destrutivo:

1. Um modelo novo entra sem linha de curadoria em nenhum workspace, e a ausência de linha É o estado desabilitado. O catálogo de um provider tem centenas de linhas — despejá-las como ativas tornaria a escolha impossível e ligaria um modelo caro sem que ninguém decidisse. Ativar é a curadoria do owner, e vale só no workspace dele (RN-052).
2. Um modelo que sumiu do catálogo remoto recebe availability = 'unavailable' e permanece na tabela: model_bindings e token_usage apontam para a linha, e apagá-la levaria junto o histórico de custo.
3. Um modelo que voltou retorna a available com a curadoria intacta — a escolha do owner sobrevive a uma ausência temporária do provider.

Os dois eixos são deliberadamente independentes: a curadoria é decisão de uma pessoa, availability é uma observação do provider. Nenhum escreve no outro — e desde o ADR 0049 eles nem moram na mesma tabela, então a sincronização não tem campo de curadoria para atropelar, mesmo que quisesse.

Três consequências no resto do sistema:

• um binding NOVO para um modelo inativo ou indisponível é recusado no domínio (ModelNotBindableError, 422). Os bindings que já existem permanecem;

• a cascata do resolveBinding pula o candidato indisponível, registra o que pulou em skipped e — quando o turno leva ferramentas — revalida supports_tool_calling em TODOS os níveis. Sem isso, o fallback pousaria um agente num modelo só de chat e violaria a RN-040 em silêncio;

• um provider que falhou não torna nada indisponível: um 401 é "não sei o que há ali", não "não há nada ali". O provider é pulado, com a ORIGEM da falha (infra | modelo) no relatório — nunca diagnóstico por eliminação.

• Onde: src/application/use-cases/llm/sync-model-catalog.use-case.ts:160, src/domain/llm/binding-resolver.ts:63, src/domain/llm/model-capabilities.ts:49

• Teste: test/application/use-cases/llm/sync-model-catalog.use-case.spec.ts, test/domain/llm/binding-resolver.spec.ts, test/application/use-cases/llm/set-model-binding.use-case.spec.ts

• Origem: ADR 0042

RN-044 — O preço vale daqui para a frente, e o custo antigo continua conferindo

Toda linha de token_usage registra o preço que produziu o seu cost_micros. Mudar o preço de um modelo não reprecifica o consumo passado — e mais que isso: o custo antigo continua reproduzível, porque tokens × preço registrado bate com o custo registrado mesmo depois de três correções na tabela models.

Toda mudança de preço grava uma linha em model_price_changes, append-only, com o par antes/depois e a origem (manual | sync). O par é gravado junto de propósito: reconstruir o "antes" a partir da linha anterior dependeria de nenhuma escrita ter escapado do caminho auditado, que é exatamente o que a auditoria existe para provar. Um preço igual ao atual é no-op — uma linha dizendo "mudou de 10 para 10" transformaria o log em ruído.

A regra vale para todo caminho que muda preço, não só o da tela. Duas escritas costumavam escapar dela: a sincronização do catálogo (que mudava o preço via upsert, nunca produzindo a origem sync que o domínio declarava desde a Fase 9c) e o seed.ts (que roda num banco já semeado — BRABO_FORCE_SEED=1 no bootstrap.sh do k8s — e portanto corrigia o preço em silêncio). Ambos agora auditam, com o seed reaproveitando o próprio UpdateModelPricingUseCase.

• Onde: src/application/use-cases/llm/update-model-pricing.use-case.ts:44, src/application/use-cases/llm/sync-model-catalog.use-case.ts:213, src/db/seed.ts:376
• Teste: test/application/use-cases/llm/update-model-pricing.use-case.spec.ts, test/application/use-cases/llm/sync-model-catalog.use-case.spec.ts
• Origem: ADR 0042

RN-045 — Um repositório adotado só é alterado por um plano aprovado

Adotar um repositório existente diagnostica sem agir. A adoção valida o acesso (getRepo), grava as linhas do projeto e produz um plano: a lista serializada do que o bootstrap faria, obtida chamando o check() de cada passo — o mesmo que dá idempotência desde a RN-029 — sem nunca executar a mutação correspondente.

Enquanto repo_bootstraps.plan_decision é nulo, nenhuma mutação roda. O portão fica antes do executor, não dentro dele: o runner do bootstrap é o mesmo da Fase 2, sem filtro, e simplesmente não é chamado. Somado à guarda que já pulava branches protegidas, não há caminho de código que toque uma branch fora de um plano aprovado.

Os dois desfechos:

• aprovar é tudo ou nada (aprovar passos soltos quebraria a cascata dev←main, qa←dev). O que executa é o plano rederivado no momento da execução: igual ou menor que o mostrado, nunca maior — uma branch que virou protegida nesse meio-tempo é pulada;
• adotar como está dispensa o bootstrap, registra a decisão e não mexe no cursor para fingir convergência. O plano é guardado como evidência do que foi deliberadamente não aplicado.

Decidir sobre um plano regenerado é recusado (409): a decisão carrega o planGeneratedAt que o usuário viu, e um "sim" dado sobre outra coisa não vale.

O provisionamento normal recusa (409) rodar num repositório adotado — sem essa guarda, o caminho de retomada rodaria o bootstrap no repositório de terceiros sem plano nenhum.

Limite conhecido: "proteção divergente" aqui é presença × ausência, porque é só isso que o contrato expõe (GitBranch.protected é um booleano, e o ADR 0028 adiou uma ProtectionPolicy normalizada). Uma branch com proteção PARCIAL conta como "desprotegida" e pode ser sobrescrita — mas só dentro de um plano aprovado.

• Onde: src/application/use-cases/git/decide-bootstrap-plan.use-case.ts, src/application/use-cases/git/bootstrap-plan.ts, src/application/use-cases/git/bootstrap-steps.ts:74
• Teste: test/application/use-cases/git/decide-bootstrap-plan.use-case.spec.ts, test/application/use-cases/git/bootstrap-plan.spec.ts
• Origem: ADR 0044

RN-046 — Todo repositório de projeto declara a sua origem

project_repositories.origin e repo_bootstraps.origin dizem se o Brabo criou o repositório (created) ou adotou um que já existia (adopted). A origem é escrita explicitamente por quem grava a linha — não pelo default da coluna — e não muda depois.

Não é decoração: é o que faz o produto tratar como caso legítimo o que a Fase 10 precisou fazer à mão (inserir linhas em project_repositories e repo_bootstraps para apontar um projeto para um fork). Um repositório adopted tem política de branches própria, não passa pelo provisionamento e só é alterado conforme a RN-045.

O backfill da migration 0031 marca tudo que já existia como created, e pode ser cego quanto a isso: a adoção não existia antes dela, então não há linha adotada para classificar errado.

• Onde: src/db/schema/git.ts, src/db/migrations/0031_special_winter_soldier.sql, src/domain/git/repo-bootstrap.entity.ts
• Teste: test/application/use-cases/git/adopt-repository.use-case.spec.ts
• Origem: ADR 0044

RN-048 — A promoção de story é do usuário por padrão; o modo muda quem dispara, nunca o que se valida

projects.story_promotion escolhe QUEM promove uma story de draft para ready:

• manual: o PO deixa a story completa e ela fica draft com stories.proposed_ready = true. Nenhuma de suas tarefas é pegável — o claimNext exige story.status = 'ready' — e é o usuário quem a promove, individualmente ou em lote, a partir do Backlog.
• auto (default de projeto novo desde a RN-659): o PO promove por conta própria ao terminar uma story completa. Esse era o comportamento anterior à Fase 12c; manual foi o default da 12c até a RN-659 (migration 0065), que mudou só o default da coluna — projetos criados no meio do caminho continuam manual.

O modo muda o gatilho, não o critério. Os dois caminhos passam por assertPromotable — prontidão (RF/DoD/DoR/regra) e módulos resolvidos contra o module_map vigente — e é isso que o teste de simetria em story-promotion.spec.ts trava: para toda story, isPromotable concorda com o que assertPromotable levanta. Antes da fase, a validação era duplicada e assimétrica (a criação chamava canBecomeReady, a transição chamava assertReady + assertModulesResolved): duas portas para o mesmo estado, com fechaduras diferentes. Tornar o gatilho configurável exigiu unificá-las primeiro, senão "promover pela UI" e "promover na criação" seriam regras distintas com o mesmo nome.

Uma story incompleta nunca é proposta. proposed_ready só liga quando a story já passaria na validação — propor o que o domínio recusaria empurraria o trabalho do PO para o usuário disfarçado de decisão.

A recusa devolve a story ao PO: grava returned_reason/returned_at, desliga proposed_ready, emite backlog.story_promotion_returned e injeta o motivo como mensagem FIXADA na sessão do PO, com a mesma redação de precedência de um gate devolvido ao dev (lição do ADR 0020). A recusa é gravada antes de falar com o engine, e o engine falhar não a desfaz — é o inverso da ordem do rearme na RN-047, e por um motivo: lá o evento afirma algo SOBRE o engine, aqui ele afirma algo sobre o usuário, o que é verdade haja ou não um PO de plantão para ouvir.

A promoção em lote não é tudo ou nada: cada story é a sua própria transação, e uma que perdeu a prontidão entre a proposta e a decisão volta failed com o motivo, sem derrubar as outras que o usuário acabou de revisar.

O evento backlog.story_transitioned registra o ator real — user na promoção manual, agent/po na automática. O event log é imutável e é o que a auditoria lê: registrar o PO numa decisão do usuário apagaria exatamente a etapa humana que a regra existe para devolver.

A migration 0033 faz um backfill dirigido, não cego: a coluna nasce manual e todo projeto que já existia é movido para auto. O novo default vale para quem vier depois; um projeto em andamento não pode parar de produzir por causa de um deploy.

• Onde: src/domain/backlog/story-promotion.ts, src/db/migrations/0033_absurd_domino.sql, src/application/use-cases/backlog/promote-stories.use-case.ts, src/application/use-cases/backlog/return-story.use-case.ts, apps/engine/lib/engine/agents/po_server.ex (revision_message/1)
• Teste: test/domain/backlog/story-promotion.spec.ts (simetria), test/db/story-promotion-migration.spec.ts (backfill dirigido), test/application/use-cases/backlog/promote-stories.use-case.spec.ts, test/application/use-cases/backlog/return-story.use-case.spec.ts, apps/engine/test/engine/agents/po_server_test.exs (describe revise/2)
• Origem: ADR 0046

RN-049 — Toda decisão sobre uma ação proposta fica no event log, com quem decidiu

proposed_action.created, .approved e .denied são eventos de domínio em session_events, além das linhas do outbox que os levam ao engine. O outbox não é memória: ele é drenado, marcado com processed_at e podado.

actor é quem realmente decidiu — o usuário em .approved/.denied, o agente que propôs em .created. E created.payload.status diz como a ação nasceu (pending, auto_approved, denied).

Isso rende a distinção que dá a métrica: decisão humana = evento proposed_action.approved; a política decidindo sozinha aparece apenas em .created com status: auto_approved e ator agente, e nunca se confunde com um clique. Essa contagem — "cliques de aprovação" — era exatamente o que a Fase 10 queria medir e não conseguiu, porque a decisão não existia em lugar consultável (achado #17). approve_always conta como aprovação porque delega ao mesmo caso de uso, e emite permission.granted por cima.

Ficou de fora, por decisão: o proposed_action.created que o bootstrap do repositório emite direto para o outbox. Essas mutações já são narradas por bootstrap.step_* na mesma sessão, e duplicá-las contaria o mesmo fato duas vezes numa métrica de aprovação.

• Onde: src/application/use-cases/actions/propose-action.use-case.ts, .../approve-action.use-case.ts, .../deny-action.use-case.ts
• Teste: test/application/use-cases/actions/approve-deny-action.use-case.spec.ts (describe the decision in the event log)
• Origem: ADR 0048

RN-051 — Um preço digitado à mão vence o catálogo do provider

Uma linha de models com manual_pricing = true tem um número que alguém digitou depois de ler a documentação do provider. A sincronização do catálogo não toca nele — nem quando o catálogo remoto traz um preço próprio. Era isso que o schema sempre dizia ("quem sincroniza preço NÃO PODE sobrescrever uma linha marcada aqui sem decisão explícita") e o que o código não fazia: o remoto sempre vencia quando trazia um preço, e a sincronização seguinte desfazia a correção de quem tinha acertado um número errado.

A regra existe porque, para vários providers, o número digitado é o único que existe: NVIDIA NIM e Bitdeer não publicam preço por token em documentação nenhuma (referência de providers), e o valor semeado é uma aproximação de mercado. Deixar o catálogo remoto sobrescrevê-lo trocaria uma aproximação conhecida por outra, sem ninguém decidir.

Um modelo NOVO nasce com a flag vinda do catálogo, não de um default fixo: descoberto com preço, manual_pricing = false (a fonte é a sincronização, e é ela quem mantém a linha em dia); descoberto sem preço, true — a linha está esperando alguém digitar um, e marcá-la já protege esse número do primeiro catálogo que resolver informar um preço.

• Onde: src/application/use-cases/llm/sync-model-catalog.use-case.ts (resolverPreco), src/db/schema/llm.ts:137
• Teste: test/application/use-cases/llm/sync-model-catalog.use-case.spec.ts (manually typed price beats a catalog that REPORTS a price)
• Origem: ADR 0042

RN-052 — A curadoria de modelos vale só no workspace que a decidiu

Ligar ou desligar um modelo no seletor é uma decisão daquele workspace, e não alcança o vizinho. O catálogo em si continua global — nome, preço, janela e capabilities são fatos do provider, iguais para todos, e duplicá-los por workspace criaria N verdades sobre o mesmo modelo, além de partir token_usage.model_id ao meio.

Antes disso, models.is_active era uma coluna para a instalação inteira: quem clicava em "ativar" decidia por todos os workspaces, e a tela não dava sinal nenhum disso. O efeito prático era um workspace ligando um modelo caro no seletor de outro — e o gasto aparecendo no orçamento de quem não decidiu nada.

Três regras derivadas:

1. A ausência de linha é o estado desabilitado. Não há um estado separado de "nunca decidido"; um modelo que a sincronização descobriu não tem linha e não aparece no seletor (RN-043).
2. Desabilitar é UPDATE, não DELETE. Apagar a linha apagaria também quem decidiu e quando. As leituras tratam os dois casos como inativos; o registro existe para quem audita.
3. Os escopos agent e session não conferem a curadoria. Nenhum dos dois tem âncora de workspace — o binding de agente é por slug global. A checagem recebe null e confere só a disponibilidade, deixando a lacuna explícita em vez de adivinhar um workspace.

• Onde: src/db/schema/llm.ts (workspace_models), src/application/use-cases/llm/set-models-active.use-case.ts, src/application/use-cases/llm/set-model-binding.use-case.ts (workspaceDoEscopo)
• Teste: test/application/use-cases/llm/set-models-active.use-case.spec.ts (activating in one workspace does NOT turn on the model in its neighbor)
• Origem: ADR 0049

RN-053 — Reativar a execução acorda quem está parado, dentro da sessão que já existe

Ativar a execução de um projeto que já está executando é reativação, não um começo do zero: ela cai na sessão de execução atual e acorda os agentes que estavam parados. Duas partes, uma de cada lado do sistema.

A sessão é reaproveitada. A ativação usa a sessão active do projeto que já carrega um execution.activated; só cria uma quando não há nenhuma. Não existe coluna dizendo "esta sessão é de execução" — o que distingue uma é o evento que ela guarda, e é isso que se consulta. Fechar a sessão continua sendo o jeito de recomeçar: uma fechada não é candidata, e a próxima ativação abre uma nova.

Antes, o create era incondicional, e o engine descarta o novo session_id quando o agente já está vivo. Cada clique em "ativar" deixava para trás uma sessão ativa que recebia o execution.activated e mais nada — os eventos dos agentes continuavam indo para a sessão da ativação anterior.

O agente é acordado por wake, não por work. Um começo do zero dispara o ciclo (:work — emite dev.started e pega tarefa). Um agente que já estava vivo recebe {:wake, :became_claimable}, e quem decide é a guarda de estado do servidor:

Disparar :work para todos seria pior que o defeito: ele pega tarefa incondicionalmente, e para um agente em awaiting_gate significaria largar o worktree que o gate está varrendo — além de contornar o circuit breaker com um clique.

• Onde: src/application/use-cases/execution/activate-execution.use-case.ts, src/infrastructure/persistence/drizzle/session.repository.ts (findActiveExecutionSession), apps/engine/lib/engine_web/controllers/execution_command_controller.ex (acordar/4)
• Teste: test/application/use-cases/execution/activate-execution.use-case.spec.ts (describe reactivation doesn't open an orphan session), test/infrastructure/persistence/session-execution.repository.spec.ts, apps/engine/test/engine_web/controllers/execution_command_controller_test.exs (describe reactivation)
• Origem: achado #11 do primeiro dogfooding

Gates de PR

RN-054 — O handoff externo se dirige ao lead da área ou a um agente sem área — nunca a um subagente

Quem fala com uma área de fora fala com o lead. Um handoff dirigido a um subagente (qa-automacao, qa-performance-seguranca, infra-workflows) é recusado com um erro tipado que nomeia o lead a quem o chamador deveria ter se dirigido — recusar sem dizer o caminho certo só trocaria uma quebra de hierarquia por um agente travado.

A recusa acontece antes do INSERT. Recusar depois deixaria um handoff fantasma na tabela e um handoff.offered — evento imutável — afirmando uma oferta que a política não permite.

A delegação interna (lead → subagente) não passa por aqui: ela é privada da área, tem tabela própria (delegations) e caminho próprio (RecordDelegationUseCase). A regra é sobre a fronteira externa da área, não sobre o que acontece dentro dela.

O ADR 0038 pedia esta validação, nomeando o lugar — CreateHandoffUseCase é o único do sistema que grava toAgent — e ela nunca tinha sido implementada (achado #12 do primeiro dogfooding). O offer_handoff do engine repassava to_agent como string livre, então até agora nada impedia um agente de quebrar a hierarquia.

Área, lead e membros têm UMA fonte desde a FASE 18: src/domain/agents/agent-areas.ts. A lista era escrita à mão em três lugares (api, web, engine) e o teste só comparava api com web — o engine divergia em silêncio. Agora apps/web/src/lib/agent-areas.generated.ts e apps/engine/lib/engine/agents/areas.ex são produzidos por pnpm --filter api gerar:areas, e o teste reprova o que estiver velho no disco. Desde a AT-046 o mesmo gerador também escreve SOLO_CONVERSATIONAL_AGENTS (RN-440) no arquivo da web — e só lá, porque o engine não tem leitor para ele. A lista continua sendo o CATÁLOGO; agent_areas é o ESTADO por projeto (RN-094), e os dois respondem perguntas diferentes.

• Onde: src/domain/agents/agent-areas.ts (assertHandoffTargetAllowed, HandoffToSubagentError), src/application/use-cases/agents/create-handoff.use-case.ts
• Teste: test/domain/agents/agent-areas.spec.ts (a regra + a checagem de que as cópias derivadas não divergem da fonte), test/application/use-cases/agents/create-handoff.use-case.spec.ts (recusa sem linha e sem evento)
• Origem: ADR 0038, fechado a partir do achado #12 do primeiro dogfooding

Credenciais

Chave de LLM e token de git do usuário vivem na mesma tabela (user_credentials), sob o mesmo envelope encryption. Esta seção vale para as duas.

RN-055 — Credencial é sempre cifrada e gravada; verificar é ação à parte, com três respostas

O cadastro não julga a credencial: cifra e grava, mesmo que o provider fosse recusá-la. Verificar é uma ação explícita sobre a credencial já gravada — a api decifra, chama o provider e devolve só o veredito. O texto plano nunca volta em resposta nenhuma, nem em pedaço, nem no motivo da recusa.

Era o contrário: o cadastro testava antes de persistir e recusava a gravação (ADR 0004, estendido às chaves de LLM na Fase 11a). O modo de falha real foi o oposto do previsto — como o campo é write-only e a tela nunca reexibe o que foi digitado, uma recusa deixava o usuário sem credencial e sem o texto para corrigir.

O veredito tem três valores, e o terceiro é obrigatório:

Sem nao_suportado, um provider cujo tester é NO-OP voltaria ok e a tela afirmaria uma verificação que nunca aconteceu. É a regra de capability do ADR 0041 aplicada aqui: só se declara o que foi provado. Por isso o port declara supports() — o silêncio de test() sozinho é ambíguo.

Chave ruim não é exceção HTTP: o caso de uso captura LLMCredentialConnectionTestFailedError/GitCredentialConnectionTestFailedError e devolve resultado, com 200. A única exceção é não existir credencial para (usuário, provider) — 404, porque aí não há o que testar.

• Onde: src/application/use-cases/credentials/test-stored-credential.use-case.ts, src/application/use-cases/llm/upsert-user-credential.use-case.ts, src/application/use-cases/git/register-git-credential.use-case.ts, src/application/ports/llm-credential-connection-tester.port.ts (supports)
• Teste: test/application/use-cases/credentials/test-stored-credential.use-case.spec.ts (os três resultados, o despacho git×LLM, o 404 e a ausência do segredo na resposta); test/application/use-cases/llm/upsert-user-credential.use-case.spec.ts e test/application/use-cases/git/register-git-credential.use-case.spec.ts (a gravação incondicional, que é a inversão)
• Origem: ADR 0050

RN-056 — Faceta de capability vem do provider; silêncio preserva o que estava

supports_vision, supports_reasoning e generates_image são fato do provider, não opinião: saem do catálogo remoto no sync, com o mesmo fallback de supports_tool_calling — remoto, depois local, depois false.

No OpenRouter (o único que publica isso hoje) as três saem de: architecture.input_modalities contém image, supported_parameters contém reasoning, e architecture.output_modalities contém image. Aceitar imagem e produzir imagem são eixos distintos: fundi-los mandaria o usuário para o modelo errado.

Antes, o sync lia supportsVision do que já estava GRAVADO e nunca consultava o remoto — a coluna nascia false e não havia caminho para virar verdadeira. Os 338 modelos do primeiro sync real ficaram todos false, incluindo 181 que o provider declara como multimodais.

Ausência de declaração não é declaração de ausência (ADR 0041): o parser OMITE o campo quando o provider se cala, e undefined preserva o valor local. Por isso a tela usa as facetas só como filtro POSITIVO e nunca escreve "não lê imagem" — false aqui quer dizer "o provider não declarou".

• Onde: src/infrastructure/llm/openrouter-provider.ts (temModalidade, parseCatalogoOpenRouter), src/application/use-cases/llm/sync-model-catalog.use-case.ts, src/db/schema/llm.ts (models)
• Teste: test/infrastructure/llm/openrouter-provider.contract.spec.ts (modalidade não declarada OMITE o campo em vez de afirmar false); test/application/use-cases/llm/sync-model-catalog.use-case.spec.ts (catálogo que se cala sobre modalidade preserva a faceta gravada)
• Origem: ADR 0051

RN-057 — "Para que serve" é curadoria do workspace, e marcar uso não liga o modelo

Nenhum catálogo de provider publica "bom para código". Isso é opinião de quem opera, descoberta usando — então mora em workspace_models.uses, ao lado da outra decisão do workspace (RN-052), e não em models.

Vocabulário FECHADO — codigo, documentacao, analise, imagem, conversa —, com prova de exaustividade em tempo de compilação nos dois lados. Texto livre daria code, coding e código no mesmo filtro em uma semana.

Duas regras que mantêm os eixos separados:

1. Marcar uso não liga o modelo. workspace_models.is_active tem DEFAULT true, então a linha criada por uma marcação de uso é inserida com is_active = false explícito. Sem isso, opinar sobre um modelo o autorizaria a gastar, contra a RN-043.
2. Trocar o uso não desliga o que estava ligado. is_active fica fora do SET do ON CONFLICT.

A lista de usos substitui a anterior, não soma: lista vazia é como se desmarca tudo, e é um estado legítimo — "ninguém opinou" não é "não serve".

• Onde: src/domain/llm/model-uses.ts, src/db/schema/llm.ts (workspace_models.uses), src/infrastructure/persistence/drizzle/workspace-model.repository.ts (setUses), src/application/use-cases/llm/set-model-uses.use-case.ts
• Teste: test/application/use-cases/llm/set-model-uses.use-case.spec.ts (marcar uso NÃO liga o modelo — a linha nova nasce inativa, trocar o uso não desliga o que já estava ligado, o uso vale só neste workspace)
• Origem: ADR 0051

RN-058 — A chave que o AGENTE gasta é a do owner do workspace

Credencial de LLM pertence a uma pessoa (user_credentials.user_id), e agente não é pessoa. O turno de agente resolve a chave pelo owner do workspace (workspaces.created_by), não por quem abriu a sessão nem por quem criou o projeto: quem banca a conta banca os agentes, e isso não muda quando outra pessoa da equipe começa a sessão.

created_by e não workspace_members.role = 'owner': pode haver vários owners, e "qualquer um deles" faria a chave usada variar sem ninguém decidir.

Antes disto o turno passava o slug do agente (agentId ?? sessionId) na coluna de usuário. A consulta ia ao banco com user_id = 'criativo', o Postgres recusava o UUID inválido, e o erro virava resposta vazia no fio — sem métrica, sem evento de falha, sem nada na tela. O efeito prático, que só uma execução real revelou: nenhum agente jamais usou um provider com credencial. Só ollama funcionava, porque para ele a busca é pulada — e foi com modelo local que a Fase 4, o dogfooding da Fase 10 e todas as demos rodaram.

O chat humano nunca teve o defeito: ele usa actor.id, que é o usuário de verdade.

• Onde: src/application/use-cases/llm/resolve-credential-owner.use-case.ts, src/application/use-cases/llm/stream-llm-turn.use-case.ts, src/application/use-cases/llm/run-llm-turn.use-case.ts
• Teste: test/application/use-cases/llm/resolve-credential-owner.use-case.spec.ts (o owner vence quem criou o projeto; a chave encontrada é a dele; projeto inexistente é 404 e não erro de banco)
• Origem: execução real da FASE 13b

RN-060 — O gasto das chaves é do owner, e só ele vê

O relatório de consumo por credencial (GET /workspaces/:id/credential-spend) exige owner no workspace. Não é maintainer: desde a RN-058 os agentes de todos os projetos gastam a credencial do dono, e a fatura dele não é assunto de quem só opera um projeto.

O relatório agrupa por provider, porque é essa a unidade da credencial — uma chave por provider, por pessoa. Um total único não bateria com fatura nenhuma.

E separa agente de pessoa: as duas coisas saem da mesma chave desde a RN-058, e "meus agentes estão caros?" é uma pergunta diferente de "eu uso muito o chat?". Por isso este é o único agregado de custo do produto sem o filtro actor_kind = 'agent' da RN-038 — aqui a pergunta é quanto saiu da chave, e o chat do próprio owner sai dela.

Gasto de credencial já removida continua no relatório, marcado: o consumo aconteceu, e escondê-lo daria um total que não fecha com o extrato do provider.

Nenhum segredo atravessa: a resposta tem provider, tokens e custo — nunca a chave, nem cifrada (ADR 0050).

• Onde: src/application/use-cases/llm/get-credential-spend.use-case.ts, src/interfaces/http/llm/budgets.controller.ts, apps/web/src/components/CredentialSpendSection.tsx
• Teste: test/application/use-cases/llm/get-credential-spend.use-case.spec.ts (agrupa por provider; separa agente de pessoa; chave removida fica marcada); apps/web/src/components/CredentialSpendSection.test.tsx
• Origem: decisão do usuário junto com a RN-058

RN-065 — Um module_map por SESSÃO; revisar é outra sessão

create_module_map recusa uma segunda emissão dentro da mesma sessão, com uma mensagem que diz o próximo passo. Entre sessões o mapa continua versionando (version + 1, findCurrent devolve o mais alto) — revisar a arquitetura é comportamento desejado.

A distinção é o ponto: entre sessões, uma nova emissão é uma revisão; dentro da mesma, é o modelo redecidindo do zero. Numa execução real o Arquiteto emitiu quatro mapas seguidos, com nomes e recortes diferentes a cada vez — greeting, hello_core, greeting, hello-api-core — e o laço só terminou porque a rede caiu (%Req.TransportError{reason: :timeout}).

A recusa volta ao modelo pelo tool-result (RN-061): ele lê que já existe um e segue para assign_story_modules, que é o passo 2 do kickoff dele. É por isso que o turno não termina quando o mapa é emitido — o Arquiteto ainda tem três passos pela frente (vincular histórias, propor um ADR, registrar tensões), e terminar ali mataria os três.

• Onde: src/application/use-cases/architecture/create-module-map.use-case.ts
• Teste: test/application/use-cases/architecture/create-module-map.use-case.spec.ts (refuses the SECOND map of the same session; e o versionamento entre sessões continua provado ao lado)
• Origem: execução real da FASE 13b

RN-066 — Toda resposta sobre módulos traz os nomes canônicos

O Arquiteto não tem ferramenta para ler o module_map vigente. É por isso que as três respostas que ele recebe sobre módulos precisam dizer os nomes:

1. Um create_module_map bem-sucedido devolve os módulos como a api os gravou — não apenas a versão.
2. Um assign_story_modules recusado lista os módulos válidos, além dos inexistentes.
3. Um create_module_map recusado pela RN-065 diz quais módulos a sessão já definiu, não quantos.

Sem mapa nenhum não há nomes a oferecer, e uma lista vazia lê-se como "chute de novo": esse caminho nomeia o problema real — falta o passo 1 do kickoff.

O motivo é concreto. Numa execução real o Arquiteto emitiu o mapa (saudacao, api_http), não conseguiu relê-lo e recorreu à força bruta: 18 chutes seguidos — api, core, http, greeting, domain, web, hello-api, hello, greeting-api, saudacao, app, server, publico, public-api, api-publica — até acertar um por sorte. Nas palavras dele no event log: "vou descobrir os nomes válidos testando candidatos plausíveis".

O dano não foi o desperdício, foi o resultado: as quatro histórias acabaram no mesmo módulo (saudacao), inclusive a do endpoint, api_http ficou sem história nenhuma, e o desfecho afirmou "Todas as 4 histórias foram vinculadas a módulos com sucesso". Como a execução sobe um dev agent por módulo, a arquitetura desenhada não seria a construída.

O laço da RN-065 era um sintoma disso: o Arquiteto reemitia o mapa justamente para tentar fixar nomes que não conseguia ler.

• Onde: src/application/use-cases/architecture/assign-story-modules.use-case.ts, src/application/use-cases/architecture/create-module-map.use-case.ts, apps/engine/lib/engine/harness/tools/create_module_map.ex
• Teste: test/application/use-cases/architecture/assign-story-modules.use-case.spec.ts (the refusal lists the VALID modules; with no module_map, it directs creating the map) e create-module-map.use-case.spec.ts (the refusal says WHICH modules there are)
• Origem: execução real da FASE 13b

RN-067 — Toda sessão nasce emitindo session.created

CreateSessionUseCase é o único lugar que cria uma sessão. Ele emite session.created para o outbox na mesma transação do insert, e é esse evento que faz o engine subir o SessionServer da sessão.

Quem chamou sessions.create(...) diretamente produziu uma sessão que o engine nunca conheceu. O efeito é uma cascata silenciosa:

• o canal Phoenix responde REFUSED JOIN para sempre — a UI só reclama no console e continua tentando a cada 10 segundos;
• sem canal não há atualização ao vivo: o fio fica preso no indicador de digitação, mesmo com o agente já idle;
• ninguém bate o heartbeat, e como é o heartbeat que fecha a sessão (RN-064), ela fica active para sempre.

Três caminhos faziam isso: provision-repository (duas chamadas), adopt-repository e activate-execution — este último cria a sessão onde rodam os dev agents.

A prova por contraste, de uma execução real: a sessão do assistente não tinha session.created, tinha engine.session_states vazio e REFUSED JOIN; a sessão aberta pela rota normal tinha o evento, a linha de estado e JOINED.

O teste é sobre a FONTE de propósito: um teste de comportamento provaria um caminho por vez, e o defeito aqui é o caminho em que ninguém pensou.

• Onde: src/application/use-cases/sessions/create-session.use-case.ts (o dono), git/provision-repository.use-case.ts, git/adopt-repository.use-case.ts, execution/activate-execution.use-case.ts (os chamadores)
• Teste: test/application/use-cases/sessions/toda-sessao-emite-created.spec.ts (only CreateSessionUseCase calls sessions.create)
• Origem: execução real da FASE 13b

RN-068 — O dev agent lê o worktree sem pedir permissão

Ativar a execução semeia duas famílias de comandos no allow do projeto: ler o próprio worktree (ls, pwd, find, cat, head, tail, grep, wc, echo, git status, git diff, git log) e build e teste.

A segunda já existia: ReportDone só deixa uma PR abrir depois de um terminal com exit 0. A primeira foi acrescentada porque o agente olha antes de construir, e sem ela não conseguia nem começar.

O motivo é concreto. Uma ferramenta :pipeline pendente devolve proposed_action <id> status pending como RESULTADO — não a saída do comando — e o ToolLoop segue em frente. Num repositório recém-provisionado, cada ls -la do agente caía em aprovação, não lhe ensinava nada e queimava uma iteração. Numa execução real o desfecho foi toolloop.limit_reached {iteration: 8, max_iterations: 8}, tarefa bloqueada por "limite de iterações atingido", sem uma linha escrita — e as aprovações que o usuário deu chegaram depois de o laço esgotado.

Liberar leituras não afrouxa o pipeline, e é isso que o teste afirma: deny vence allow, os BUILTIN_DENY_PATTERNS continuam ativos, o casamento é por prefixo de TOKEN (um ls permitido não permite lsof), e um comando composto exige que TODO segmento case — ls && rm -rf / não passa por causa do ls.

A allowlist é mitigação, não solução: é uma lista de comandos previstos e o modelo inventa comandos. A correção estrutural — o agente ESPERAR a decisão em vez de queimar iterações — está no ADR 0052.

• Onde: src/domain/actions/dev-terminal-patterns.ts, semeado por application/use-cases/execution/activate-execution.use-case.ts
• Teste: test/domain/actions/dev-terminal-patterns.spec.ts (allows ls -la; a composite command doesn't hitch a ride on the allowed segment)
• Origem: execução real da FASE 13b

RN-070 — Todo gate declarado aponta para a evidência que o prova

Nenhuma entrada de config/gates.yml existe sem evidencia, e o registro não pode afirmar mais do que verifica: um gate block exige verificacao: script, e um gate planned não carrega evidência de algo que ainda não aconteceu.

Evidência é um localizador, não prosa: event_log traz os tipos de evento e o filtro de payload que os distingue dos vizinhos; teste e ci trazem o caminho, e um alvo que sumiu REPROVA. É o mesmo modo de falha que o docmap chama de glob morto — uma regra que nunca dispara e finge cobertura.

Essa última afirmação é sobre o REPOSITÓRIO, e nunca é avaliada em runtime. O registro é validado em duas camadas: validarRegistro (o conteúdo — block precisa de script, os quatro gates humanos continuam humanos, active precisa de evidência, nenhum id duplicado, nenhuma entrada órfã) vale onde quer que o arquivo seja lido e é o que o loader da api chama; validarLocalizadores (o arquivo alvo está em disco) só faz sentido dentro de um checkout, e é cobrada pelo teste do arquivo real e pela fase 2 do validacao-gates.ts.

As duas costumavam ser uma função só, e isso custou um defeito de produção, medido na v6.1.0 instalada: GET /gates devolvia 500 com RegistroDeGatesInvalido listando os onze alvos como ausentes — doze 5xx em cerca de 55 minutos, em toda instalação. A imagem de produção leva /app/config/gates.yml e mais nada; test/, scripts/ci/ e .github/ nunca entram nela. A regra não foi afrouxada — foi movida para onde a pergunta existe. Não a ponha de volta no loader: arquivoExiste num processo que não tem repositório responde sobre outra árvore.

A tela escondeu isso: a RN-084 faz o PrGateTimeline cair no pipeline completo quando a rota falha, então o 500 só aparecia nos logs da api.

Três tipos porque nem todo gate vive no event log: merge-protegida é um teto numa regra pura que não emite evento próprio (o que a garante é um teste) e backmerge é CI com estado em .release/gate.json. Rebaixá-los a warn por isso mentiria sobre as travas mais duras do produto.

O filtro importa tanto quanto o tipo: qa-verificada e secops-segura gravam o MESMO pr.gate_changed, e o mesmo tipo dispara na ABERTURA do gate, sem veredito — sem o filtro, abrir contaria como passar. O mesmo vale para os dois gates de PR de infra. É por isso que nenhum par (event_types + filtro) pode se repetir.

O filtro só alcança o PAYLOAD, de propósito: aceitar uma coluna arbitrária abriria a consulta inteira. Quem promoveu uma story (humano ou o PO) mora na coluna actor_kind e fica fora do vocabulário declarativo.

• Onde: src/domain/gates/gate-registry.ts (validarRegistro e validarLocalizadores), registrado em config/gates.yml, medido em scripts/validacao-gates.ts; o loader que deliberadamente chama só a primeira é src/infrastructure/gates/gate-registry.loader.ts
• Teste: test/domain/gates/gate-registry.spec.ts (é válido: nenhum problema acumulado; todo alvo de prova citado existe no repositório; validarRegistro ignora o disco: alvo ausente não é problema DELE; nenhum par (event_types + filtro) se repete entre gates) e test/infrastructure/gates/gate-registry.loader.spec.ts (carrega o registro real sem exigir os alvos que a imagem não leva, contra uma raiz reconstruída como a árvore da imagem de produção)
• Origem: FASE 15a (ADR 0054); a divisão em duas camadas veio do 500 de GET /gates medido na v6.1.0 instalada (AT-086)

RN-071 — Os quatro gates de autoridade do usuário não podem ser declarados automáticos

acao-aprovada, story-promovida, plano-de-adocao e merge-protegida têm aprovacao_humana: true por construção. A lista mora no DOMÍNIO (GATES_HUMANOS_IMUTAVEIS), não no teste: mexer nela tem de ser um ato deliberado, revisado como código.

aprovacao_humana: true significa que a decisão é do usuário — diretamente por um clique, ou delegada por uma política que ele mesmo escreveu no permissions.json. É isso que permite a acao-aprovada coexistir com status: auto_approved: a política decidindo sozinha é o usuário tendo decidido de antemão. merge-protegida é o caso em que nem a delegação existe — o teto rebaixa auto_approve para require_approval mesmo com a autonomia ligada.

O contrário também reprova: um id na lista sem gate correspondente é uma regra morta, apontando para nada.

• Onde: src/domain/gates/gate-registry.ts (GATES_HUMANOS_IMUTAVEIS); o teto em src/domain/actions/decide.ts
• Teste: test/domain/gates/gate-registry.spec.ts (%s cannot have aprovacao_humana false); o teto em test/domain/actions/decide.spec.ts
• Origem: FASE 15a (ADR 0054)

RN-072 — Sem escolha explícita, o modelo é o do agente Criativo

Quando a cascata de bindings pousa no default do workspace — isto é, ninguém decidiu nada para este projeto — o modelo herdado é o do agente Criativo, não o default global.

O agente Criativo é sempre a porta de entrada de um projeto: é com ele que a primeira conversa acontece, e o binding dele representa "o modelo que este projeto usa para pensar".

A herança preenche a lacuna, nunca sobrescreve: bindings de sessão, de agente ou de projeto são escolhas explícitas de alguém e continuam vencendo. É por isso que é um passo DEPOIS da cascata e não um novo escopo dentro dela — não disputa precedência. E o modelo herdado passa pelos mesmos filtros: sumido do catálogo ou sem tool calling significa que não é herdado, pelo mesmo motivo que a cascata os pula (RN-043).

O que isto conserta: o default do workspace é global e tende a ser um modelo local pequeno. Uma sessão nova e um dev agent — que não têm binding próprio — nasciam nele, e o ADR 0020 proíbe um modelo local pequeno no passo semântico. Numa execução real foi preciso trocar o modelo à mão em cada sessão aberta, e os três dev agents subiram em llama3.2:1b sem que ninguém tivesse pedido.

• Onde: src/domain/llm/binding-resolver.ts (herdarModeloDeStart), aplicado em application/use-cases/llm/resolve-model-binding.use-case.ts
• Teste: test/domain/llm/binding-resolver.spec.ts (fills the gap; does NOT override %s's explicit choice)
• Origem: achados B e O da execução real (FASE 13c, fase A)

RN-075 — Comando de terminal é avaliado por onde toca, não só pelo verbo

A pasta do projeto (<PROJECT_WORKSPACES_ROOT>/<workspace_dir_name> — o UUID puro num projeto de antes do RN-109, <slug>-<8 chars do id> num projeto novo) é o escopo. Um comando de terminal que toca qualquer caminho fora dela nunca é auto-aprovado, por mais que o verbo esteja em allow. Dentro dela, cd deixa de exigir permissão — ele é a declaração de escopo, não um verbo.

Quatro propriedades que os testes fixam:

• Aperta: Terminal(cat) liberado deixa de auto-executar cat /workspace/apps/engine/.../git_executor.ex. Era o achado U: o casamento é por VERBO, então o agente lia o código da plataforma que o executava, e alcançava o worktree de outros projetos.
• Afrouxa: cd <dentro> && cat README.md vira auto_approve. Era o defeito mais caro da escada — o dev agent emite sempre cd <caminho> && <verbo>, cd não estava em allow nenhum, e comando composto exige que TODOS os segmentos casem.
• Permite sem isentar: dentro do escopo, verbo fora do allow continua pedindo. Estar na pasta do projeto não torna curl … | sh seguro.
• Fora do escopo é require_approval, nunca deny: o agente pode ter razão legítima para olhar fora, e a decisão continua sendo do usuário.

deny continua vencendo primeiro, e os dois tetos (RN-006, RN-007) seguem intocados. Sem raiz informada ao decide(), o veredito é o de antes desta regra — nenhum chamador tem comportamento alterado por omissão.

A normalização é léxica, não realpath: <raiz>/../.. é resolvido e reprovado, mas link simbólico de dentro apontando para fora não é detectado. decide() é puro por contrato e resolver symlink exigiria IO no domínio. Escopo é política; isolamento é outro problema, declarado em aberto no ADR.

Sem regex sobre a entrada, de propósito. Tirar as barras finais da raiz era .replace(/\/+$/, ''), e o CodeQL apontou ReDoS polinomial (js/polynomial-redos, HIGH): o padrão obriga o motor a tentar cada posição inicial e varrer até o fim, degradando em O(n²). Hoje é varredura O(n), equivalente inclusive no caso degenerado — a raiz / vira string vazia nos dois, e é isso que faz startsWith('/') valer para todo caminho absoluto. Quem for "simplificar" de volta para regex reabre o alerta.

• Onde: src/domain/actions/path-scope.ts, domain/actions/decide.ts (teto do escopo e o cd no escopo), raiz derivada em infrastructure/filesystem/project-workspaces-root.ts
• Teste: test/domain/actions/path-scope.spec.ts e test/domain/actions/decide.spec.ts (describe decide — escopo de caminho)
• Origem: ADR 0055, achado U, Fase F do backlog

O escopo só vale enquanto ele próprio estiver dentro da raiz — quem garante isso é a RN-092.

RN-078 — Falha em proteger branches pode ser reconhecida, e só ela

protect_branches falha em repositório privado no plano gratuito do GitHub — e o wizard avisa isso antes de começar. O usuário pode reconhecer a falha e seguir; o bootstrap fecha e o projeto passa a ser alcançável.

O que isso destrava é maior do que parece. O único botão oferecido depois da falha era "Tentar novamente", que falha sempre pelo mesmo motivo. E provision_failed faz o dashboard redirecionar o clique do projeto de volta para a página de provisionamento — o projeto ficava inalcançável para sempre, preso num passo que não tem como suceder.

Só a proteção pode ser reconhecida. Ela é o ÚLTIMO passo e a única cuja falha deixa um repositório utilizável: o repo existe, os arquivos foram commitados, as branches foram criadas. Falhar em criar o repositório ou em commitar é outra coisa — ali "seguir" produziria um projeto sem onde trabalhar, e o botão seria uma segunda mentira em cima da primeira. A recusa diz isso, em vez de só negar.

A garantia do produto não muda. A trava de merge (RN-006) é aplicada em decide.ts, não pela proteção do provider. Seguir sem ela remove a segunda camada, a do GitHub — não a do Brabo. É o que torna esta saída honesta em vez de um atalho.

A decisão vai para o event log com o usuário como ator e o erro original no payload: seguir sem proteção é escolha dele, e quem ler depois precisa saber o que exatamente foi dispensado.

• Onde: src/application/use-cases/git/acknowledge-protection-failure.use-case.ts, rota em interfaces/http/git/git.controller.ts, botão em apps/web/src/routes/ProvisioningPage.tsx
• Teste: test/application/use-cases/git/acknowledge-protection-failure.use-case.spec.ts (destrava; a decisão no log com o ator; e a recusa para falha anterior)
• Origem: achado D, Fase D do backlog

RN-081 — História repetida: título igual recusa, justificativa igual avisa

Duas respostas diferentes para dois problemas diferentes:

• título idêntico no projeto é erro, não escolha: a história é recusada e nada é criado;
• mesma justificativa — todas as regras de negócio que a história cita já estavam cobertas por outra — é suspeita, não erro. A história é criada e sai um backlog.story_overlap_warned. Um segundo recorte da mesma regra pode ser legítimo, então quem julga é o usuário; o produto só se recusa a deixar passar despercebido.

Contido, não intersecção. Duas histórias compartilharem uma regra é normal, e avisar disso viraria ruído que ninguém lê. O sinal só existe quando a nova não acrescenta cobertura nenhuma. História que não cita regra alguma não gera aviso: tratar o conjunto vazio como subconjunto de tudo acusaria todas.

O limite é o mesmo da RN-080, e o par do achado o atravessa: "Endpoint público de saudação determinística" e "Endpoint público GET /hello que responde saudação imediata" cobrem o mesmo endpoint com títulos e justificativas diferentes — nada mecânico os liga, e eles continuam passando. Há teste afirmando isso, para o limite ficar visível em vez de implícito. Desde a RN-681 o par é AVISADO por embedding — continua passando, e o teste que afirma o limite DESTE mecanismo segue valendo.

• Onde: src/domain/backlog/story-overlap.ts, src/application/use-cases/backlog/create-story.use-case.ts
• Teste: test/domain/backlog/story-overlap.spec.ts, test/application/use-cases/backlog/create-story.use-case.spec.ts
• Origem: achado R, Fase E do backlog

RN-082 — A credencial de git de uma ação é a do OWNER do workspace

Quando a api executa uma ação de git contra provider remoto (pr_open, git_merge), o token vem do owner do workspace — o mesmo resolvedor da RN-058, não de quem decidiu a ação.

Resolver por quem decidiu só funcionava com clique humano. Ação auto-aprovada por política não tem decisor: decided_by fica NULL, o token fica undefined, e o GitHub responde Requires authentication. Na prática, com autonomia ligada — que é o modo que o ADR 0055 existe para viabilizar — nenhum dev agent conseguia abrir PR em provider remoto.

O contraste que expôs o defeito aconteceu dentro de uma execução só: no mesmo run, git_push passou e pr_open falhou. O push é executado pelo ENGINE, que já injetava a credencial do owner (RN-076); a PR é aberta pela API, que estava fora de simetria.

Não apareceu antes porque toda validação anterior usou o LocalGitProvider, onde o token nem é consultado.

O princípio é o mesmo da RN-058, e vale repetir porque é o que impede as duas regras de divergirem com o tempo: quem banca a conta banca os agentes, e isso não muda conforme quem clica. Por isso o resolvedor é REUSADO em vez de reimplementado.

• Onde: src/application/use-cases/actions/execute-git-action.use-case.ts, reusando application/use-cases/llm/resolve-credential-owner.use-case.ts
• Teste: test/application/use-cases/actions/execute-git-action.use-case.spec.ts (pr_open auto-aprovado, com decidedBy: null, pede a credencial do owner)
• Origem: achado AA, validação real da 13b

RN-083 — O lead decide o paralelismo; acima do teto, você autoriza

Quantos agentes sobem deixa de ser um número no código: quem avalia é o lead da área. Mas a decisão dele não é soberana sobre GASTO — até agent_areas.max_parallel (nasce com 5 no dev, RN-910) ele sobe e segue; acima disso vira proposed_action do tipo parallelize, pelo mesmo pipeline de toda ação com efeito externo.

O teto é da SESSÃO, não do módulo. É a única parte da regra que não é óbvia, e a que um refactor desatento desfaz: contar por módulo permitiria N módulos × 2 agentes sem autorização nenhuma — o buraco anterior com outro nome. Há teste afirmando exatamente isso.

Teto zero ou negativo é configuração inválida, não "sem limite". Tratá-lo como ilimitado transformaria um erro de digitação em gasto irrestrito, que é o oposto do que o pipeline existe para fazer.

Quem PEDE é o lead; quem DECIDE é você. A proposed_action nasce com o lead como ator, e a decisão fica no event log com o seu nome — é essa distinção que faz a história ser reconstituível depois (ADR 0048).

O motivo viaja no payload IMUTÁVEL, com os três números (quantos há, quantos pede, qual o teto): quem ler daqui a seis meses precisa entender o que foi autorizado sem reconstruir o estado da sessão.

AcceptParallelizationUseCase não muda: ele continua sendo quem EXECUTA, tanto no caminho direto quanto quando a ação é aprovada. Absorvê-lo por dentro, em vez de reescrevê-lo, é o que mantém a suite da Fase 4 verde sem modificação — que é a prova de que a troca não vazou para o contrato externo.

O teto é configurável por área, e só por você. PATCH /projects/:projectId/agent-areas/:key/max-parallel exige maintainer — o mesmo papel de ativar a execução, e pelo mesmo motivo: mudar o teto é decidir quanto o produto pode gastar sem perguntar. Não existe caminho automático de subi-lo. A Anamnese pode PROPOR, quando notar que a autorização virou rotina, e a proposta continua passando por esta rota depois que você aceita — um produto que eleva o próprio teto de gasto é exatamente o que o pipeline de aprovação existe para impedir.

Mudar o teto vale para os PRÓXIMOS pedidos. O que já está aguardando decisão continua aguardando: a ação carrega no payload o teto vigente quando foi criada, e reinterpretá-la sob o teto novo mudaria o que você está prestes a decidir depois de ler.

• Onde: src/domain/execution/paralelismo.ts (a regra pura), application/use-cases/execution/request-parallelization.use-case.ts, application/use-cases/execution/set-area-max-parallel.use-case.ts, exposto em interfaces/http/execution/execution.controller.ts e configurado em apps/web/src/routes/settings/ParallelismSection.tsx
• Teste: test/domain/execution/paralelismo.spec.ts, test/application/use-cases/execution/request-parallelization.use-case.spec.ts, test/application/use-cases/execution/set-area-max-parallel.use-case.spec.ts e apps/web/src/routes/ProjectSettingsTab.test.tsx (ParallelismSection)
• Gate: config/gates.yml (paralelismo-autorizado) — status: active desde a auditoria fluxo.yml × código (achado A1/B5); o mecanismo em si não mudou, só o registro que ficou planned por engano desde a FASE 14d, ver gates.md
• Origem: ADR 0053, FASE 14d

RN-084 — A esteira exibida deriva do registro de gates

O painel do time mostra a etapa em que uma PR está derivando-a de config/gates.yml, não de uma lista escrita na tela. Gate que sai do registro some da esteira; gate planned nunca aparece.

A regra existe por uma forma específica de envelhecimento. Antes da FASE 15b a tela tinha as etapas fixas no componente, e o registro (FASE 15a) descrevia os gates em outro lugar. Nada ligava os dois: acrescentar um gate ao YAML não mudava a tela, e remover um deixava a tela mostrando uma etapa que já não existia — sem nenhum teste falhar, porque as duas fontes estavam certas cada uma por si. É o mesmo apodrecimento que o docs/.docmap.yml existe para impedir, e a resposta é a mesma: uma fonte só, com o consumo cobrado.

Três decisões de borda, todas para a tela degradar em vez de sumir:

• gate de PR que a tela ainda não sabe desenhar é ignorado, não quebra o render — o registro pode ganhar um gate antes de a tela ganhar o rótulo;

• os rótulos são de tela, não do registro: o YAML descreve engenharia, e a tela fala com quem espera uma PR;

• sem registro (a rota falhou), mostra a esteira completa em vez de vazia — uma esteira genérica informa mais que nada.

• Onde: apps/web/src/components/PrGateTimeline.tsx (etapasDaEsteira), lendo GET /gates (src/interfaces/http/gates/gates.controller.ts)

• Teste: apps/web/src/components/PrGateTimeline.test.ts (gate que SAI do registro some da tela, gate de PR que a tela ainda não sabe desenhar é IGNORADO, sem registro, mostra a esteira completa)

• Origem: ADR 0054, FASE 15b

RN-086 — Gastar com mais agentes nunca se auto-aprova

As duas ações que mexem em quanto o produto pode gastar sozinho — parallelize (ultrapassar o teto agora) e raise_max_parallel (mudar o teto) — nunca são auto-aprováveis. Nem por agent_autonomy, nem por permissions.json. É a mesma classe de garantia da trava de merge e do teto do patch de instrução.

Sem isto o teto da RN-083 seria decorativo. Um permissions.json com Parallelize() no allow faria toda ultrapassagem se aprovar sozinha — a regra que existe para EXIGIR a decisão do usuário passaria a dispensá-la. E raise_max_parallel é o caso mais grave: seria o produto elevando o próprio limite de gasto, exatamente o que o pipeline de aprovação existe para impedir.

A Anamnese pode PROPOR, e é isso que ela faz. Quando autorizar mais um agente vira rotina, o teto está errado, e quem percebe primeiro é quem lê o histórico. O sinal já chegava a ela: as decisões do usuário na janela vêm de proposed_actions, com actionType e status.

O limiar é três aprovações e nenhuma negação, e as duas metades importam:

• duas não são rotina — são duas. Três é o que separa "aconteceu" de "está acontecendo sempre";
• uma negação derruba o sinal inteiro, por mais aprovações que haja. Se o usuário recusou alguma vez, o teto está fazendo o trabalho dele, e propor subi-lo seria ler o sinal ao contrário.

Propor um teto igual ou menor que o vigente é recusado pela api: a Anamnese roda periodicamente e reproporia a mesma coisa a cada rodada, enchendo de ruído uma fila que o usuário precisa ler.

Aprovar aplica o valor do payload, não um recalculado na hora — é o número que você leu ao decidir.

• Onde: src/domain/actions/decide.ts (o teto), application/use-cases/execution/propose-max-parallel.use-case.ts, execute-max-parallel-raise.use-case.ts, apps/engine/lib/engine/anamnese/tools/propose_max_parallel.ex e o limiar em apps/engine/lib/engine/workers/anamnese_worker.ex (nota_de_paralelismo/1)
• Teste: test/domain/actions/decide.spec.ts (decide — teto do paralelismo), test/application/use-cases/execution/propose-max-parallel.use-case.spec.ts, execute-max-parallel-raise.use-case.spec.ts, apps/engine/test/engine/anamnese/tools_test.exs e test/engine/workers/anamnese_worker_test.exs (duas aprovacoes NAO sao rotina, uma NEGACAO derruba o sinal)
• Origem: ADR 0053, FASE 14d

Painel de projetos

RN-090 — O dashboard lê o workspace, não um projeto de cada vez

A grade de cards e os dots da barra lateral se alimentam de uma requisição por ciclo — GET /workspaces/:workspaceId/projects-summary —, e o número de requisições não cresce com a quantidade de projetos.

O card mostra provedor de git, status de provisionamento, orçamento, chips de agentes e última atividade; a sidebar mostra o dot de status e o contador de não lidos. Tudo isso vinha de sete consultas em POLL por projeto, o que fazia 23 projetos custarem 3.824 requisições por minuto contra um limite de 300 (RateLimitGuard) — a tela derrubava a si mesma em 429 antes de terminar de carregar. A RN-088 fez a app parar de insistir quando isso acontece; esta reduz o pedido.

Duas fronteiras que a regra fixa, e que não são detalhe de implementação:

• A api responde fatos, não roster. roster traz o que aconteceu no event log (execução ativada, módulos, gate já aberto, subagentes delegados, infra aceita). Quem é lead de área, que ícone cada agente tem e como os membros viram um chip continua sendo do web — e a regra de PRESENÇA é uma só (rosterFromFacts), compartilhada com o painel do time, para que um agente novo não apareça num lugar e falte no outro.
• A gaveta do sino só busca quando aberta. Ela era, até a RN-091, a única leitura que continuava sendo uma requisição por projeto — o corte de "onde parei de ler" é seq guardado no navegador (read-state), que o servidor não conhece. Hoje o navegador manda esse corte, e a gaveta também é uma requisição só.

Efeito colateral aceito e desejado: gatesEverOpened e delegatedSubagents passam a cobrir a sessão INTEIRA. O cliente derivava dos últimos 200 eventos e perdia chips em sessão longa (ver ADR 0021) — o texto de deriveAgentRoster sempre disse "já abriu alguma vez".

• Onde: src/application/ports/projects-summary-repository.port.ts, src/infrastructure/persistence/drizzle/projects-summary.repository.ts, src/interfaces/http/iam/workspaces.controller.ts (getProjectsSummary), apps/web/src/lib/hooks.ts (useProjectsSummary), apps/web/src/lib/agent-status.ts (rosterFromFacts), apps/web/src/routes/Dashboard.tsx, apps/web/src/routes/Shell.tsx
• Teste: apps/web/src/routes/Dashboard.fanout.test.tsx (30 projetos custam o mesmo que 3; nenhum endpoint por projeto é chamado); test/infrastructure/persistence/drizzle/projects-summary.repository.spec.ts (o número de consultas ao banco não cresce com N); apps/web/src/lib/agent-status.test.ts (os fatos da api produzem os mesmos chips que o event log)
• Origem: dashboard de 23 projetos medido no navegador — 3.824 req/min antes, 12 depois

RN-091 — O navegador manda onde parou de ler; o sino é uma requisição

Com a gaveta de notificações aberta, o conteúdo dela sai de uma requisição por ciclo — POST /workspaces/:workspaceId/unread-events — e o número de requisições não cresce com a quantidade de projetos.

É a metade que faltava da RN-090. Aquela derrubou o dashboard de 3.824 para 12 req/min, mas o sino continuou buscando um projeto de cada vez: 23 projetos com a gaveta aberta mediam 286 req/min contra o limite de 300 (RateLimitGuard). Passava, e sumia com um projeto a mais.

O obstáculo, e por que a saída é esta. Não existe "marcar como lido" no servidor, de propósito: o corte é um seq por projeto guardado no localStorage de cada navegador (read-state). Havia duas saídas, e a diferença entre elas é de PRODUTO:

• parar de repolar enquanto a gaveta está aberta muda a atualidade do que o usuário vê — recusada, ninguém pediu essa troca;
• o navegador mandar o mapa projeto → afterSeq devolve exatamente os mesmos dados na mesma cadência. É batelamento puro: nada muda para quem olha a tela, nem a frescura nem o conteúdo.

É POST sem mutar nada, e a api responde 200 (nunca 201) para dizer isso. O verbo foi escolhido por ser o único com CORPO: são dezenas de pares, e em query string isso vira URL longa — que proxy trunca — além de pôr id de projeto do usuário em log de acesso, contra a regra de não passar dado pessoal por query string.

Três garantias de semântica que a rota fixa, porque batelar leituras com cortes diferentes é onde o erro fácil mora:

• mapa vazio devolve vazio, e sem tocar no banco. "Não perguntei nada" não é "me dê tudo";
• cada projeto respeita o SEU corte — seq estritamente maior que o dele;
• o teto de 50 eventos é por projeto, o mesmo que GET .../events aplica sem limit. Um limite na resposta inteira deixaria o projeto barulhento comer a cota dos calados.

Cursor apontando para projeto de outro workspace é ignorado, não recusado: ele vem do armazenamento local de quem chama e pode ser sobra de um workspace antigo.

• Onde: src/application/ports/projects-summary-repository.port.ts (unreadEventsForWorkspace), src/infrastructure/persistence/drizzle/projects-summary.repository.ts, src/interfaces/http/iam/workspaces.controller.ts (getUnreadEvents), src/interfaces/http/iam/dto/unread-events.dto.ts, apps/web/src/lib/notifications.ts (useNotificationGroups), apps/web/src/lib/api-client.ts (getUnreadEvents)
• Teste: apps/web/src/routes/Dashboard.fanout.test.tsx (com a gaveta ABERTA: uma requisição, e 30 projetos custam o mesmo que 3); test/infrastructure/persistence/drizzle/projects-summary.repository.spec.ts (o número de consultas ao banco não cresce com N; mapa vazio, corte por projeto, teto por projeto e isolamento de workspace)
• Origem: residual medido da RN-090 — 286 req/min com a gaveta aberta num workspace de 23 projetos

RN-092 — O projectId é segmento de caminho, e o escopo nunca sai da raiz

projectScopeRoot() recusa um projectId que não seja segmento de caminho simples (^[A-Za-z0-9_-]{1,64}$), lançando em vez de montar o caminho.

O motivo é que o id chega de @Param('projectId') sem pipe de validação, e o Express decodifica o percent-encoding do segmento antes de entregá-lo: um ..%2F..%2Fetc chega como ../../etc, e o join resolveria para fora da raiz sem reclamar. Os dois consumidores da função sofrem, e o segundo é o grave:

• o permissions.json seria lido e escrito em caminho arbitrário;
• o escopo da RN-075 autoriza comando de terminal sob essa pasta. Um escopo que escapa da raiz é a política de aprovação apontando para o lugar errado — falha de SEGURANÇA, não de arquivo não encontrado.

A checagem é deliberadamente mais larga que UUID (aceita letra, dígito, hífen e sublinhado) para não amarrar o formato do id, e estreita o bastante para que o resultado nunca escape. E fica onde a raiz é derivada, não em cada chamador, pela mesma razão que fez a função existir: as duas derivações têm que concordar, e checagem duplicada é checagem que um dia diverge.

O caminho feliz não muda — todo id real é UUID vindo do banco.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts (projectScopeRoot)
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts
• Origem: ADR 0058, alertas js/path-injection do CodeQL

RN-093 — Em produção, a api não sobe com a chave de exemplo do state de OAuth

resolveOauthStateSecret() derruba o boot quando NODE_ENV === 'production' e GIT_OAUTH_STATE_SECRET está ausente, é igual ao literal de exemplo do repositório, ou tem menos de 16 caracteres. Fora de produção o default de desenvolvimento continua valendo.

Essa chave assina o state do OAuth de git, e o state é o único que impede o callback GET /git/oauth/:provider/callback — rota pública, por necessidade — de ser forjado. Com a chave conhecida, qualquer um assina um state para {projectId, userId, provider} à escolha e faz o callback gravar, no projeto apontado por esse payload, o token de git obtido do provider.

Por que rejeitar o literal, e não só o vazio. O default estava no .env.example de um repositório open source — é segredo publicado, não segredo fraco. E o docker-compose.prod.yml o supria como fallback, então no caminho real de erro a variável estava definida: uma verificação de "não vazia" passaria por cima do defeito inteiro.

A resolução fica em função única, e não em cada chamador, pela mesma razão da RN-092 — eram duas cópias do mesmo literal, e cópias divergem. Divergindo aqui, o callback recusaria todo state legítimo.

• Onde: src/infrastructure/security/oauth-state-secret.ts (resolveOauthStateSecret), chamada no boot em src/main.ts
• Teste: test/infrastructure/security/oauth-state-secret.spec.ts
• Origem: ADR 0059

RN-094 — A área de agentes nasce com o projeto

Criar um projeto grava as três áreas (dev, qa, infra) em agent_areas, com o lead de cada uma e os membros enumeráveis em agent_area_members — na MESMA transação da criação. Se o seeding falha, o projeto não nasce: projeto sem área é projeto onde a RN-083 lê tabela vazia e cai no default sem que ninguém tenha decidido nada.

Isto é a correção de um defeito, não uma capacidade nova. agent_areas existe desde a FASE 14d e nunca foi gravada — AgentAreaRepository.upsert tinha teste e não tinha NENHUM chamador. Em produção a tabela estava vazia, GET /projects/:projectId/agent-areas devolvia [], e os quatro casos de uso que a leem operavam sobre o nada. É a mesma falha da própria FASE 14d, escrita no CLAUDE.md: testar a peça não é testar o caminho até ela. Por isso o teste desta regra entra pelo caso de uso que a rota chama, com repositório real: um fake aqui provaria exatamente o que já estava provado e quebrado.

Semeia em DOIS lugares, e cada um responde uma pergunta diferente. A criação do projeto faz a área EXISTIR — a tela de Configurações lê num projeto que nunca executou. A ativação da execução diz quem são os MEMBROS da área de dev: um dev-<modulo> por módulo do module_map, que não existia quando o projeto nasceu. Enquanto não há membros gravados, quem sustenta a regra de endereçamento (RN-087) é o predicado ehDevDeModulo, que não consulta o banco.

O seeding manda o teto de NASCENÇA, e só no INSERT. Desde a RN-910 a área nasce com o valor do catálogo (dev 5, qa 4, infra 2), mas o upsert o grava só quando a linha ainda não existe: a ativação é repetível, e um teto que você subiu não volta ao valor de nascença em silêncio — o produto desfazendo a sua decisão. A migração de backfill 0038 faz a área existir e para aí; quem alinha os projetos existentes é a 0073 (RN-910).

Projetos criados antes disto são cobertos pela migração 0038, com ON CONFLICT DO NOTHING nas duas tabelas. Sem ela, o defeito ficaria corrigido só para quem começasse do zero.

• Onde: src/application/use-cases/agents/seed-agent-areas.use-case.ts, chamado por application/use-cases/iam/create-project.use-case.ts e application/use-cases/execution/activate-execution.use-case.ts; lista canônica em src/domain/agents/agent-areas.ts; backfill em src/db/migrations/0038_wandering_lila_cheney.sql
• Teste: test/application/use-cases/iam/create-project-semeia-areas.spec.ts (o caminho, contra o banco, incluindo a falha que derruba a criação), test/db/agent-areas-backfill.spec.ts (a migração rodada de verdade, duas vezes) e test/application/use-cases/execution/activate-execution.use-case.spec.ts (os membros de dev, e o teto nunca enviado)
• Origem: FASE 18, defeito achado na investigação do programa 16–26; a tabela vem do ADR 0053

RN-095 — A leitura de repositório é contida ao projeto e limitada

A superfície de leitura de código (GET /projects/:projectId/code/{tree,file,search} e o diff de PR) tem duas garantias, e as duas são do mesmo tipo: o produto recusando fazer o que o cliente pediu.

Contenção. Todo caminho de arquivo vindo do cliente passa por caminhoDeRepositorioContido(), que ancora o pedido na pasta do projeto e recusa o que sair dela — ../, absoluto, ou byte NUL. Ela é uma função só, no mesmo arquivo do projectScopeRoot da RN-092, reusando as primitivas do escopo de terminal (normalizarCaminho/dentroDoEscopo). Nenhuma rota valida caminho por conta própria, e é isso que a regra afirma: quatro implementações da mesma contenção seriam quatro chances de divergir, e o CLAUDE.md já registra que a decisão foi manter a checagem central e pagar o preço no painel do CodeQL (barreira em outra função ele não enxerga).

Ela devolve o caminho normalizado, e o chamador usa o que voltou. Devolver o original permitiria conferir b e mandar a/../b ao provider — a forma mais comum de a contenção existir e não valer.

O vetor não é "ler o arquivo errado". Em github/gitlab o caminho vira segmento de URL da API do provider, então um ../ troca de endpoint com a credencial do owner do workspace na mão (RN-058/RN-082). Em local ele vira o lado direito de git show <ref>:<path>. A ref é conferida no mesmo lugar, pelo mesmo motivo, e .. nela é recusado porque para o git dev..main é intervalo de commits, não revisão.

Limite. Árvore e diff já vêm cortados pelo contrato (GIT_TREE_ENTRY_LIMIT, GIT_DIFF_FILE_LIMIT, FASE 26a). A busca não: ela não é operação do contrato — é composta sobre listTree e getFileContent, e é a única leitura cujo custo cresce com o TAMANHO do repositório em vez do tamanho do pedido. Três orçamentos a param (diretórios percorridos, arquivos abertos, casamentos devolvidos), um cache de TTL curto evita repetir as mesmas chamadas, e truncated diz que o corte aconteceu. Sem eles, um viewer gastaria a credencial e o rate limit do owner à vontade — a mesma família de defeito dos 3.824 req/min do dashboard (RN-090).

A indexação de docs tem teto próprio. O GIT_BLOB_MAX_BYTES (512 KiB) vale para a aba Code e para a busca; a indexação de docs/adr lê cada .md até RAG_INDEX_FILE_MAX_BYTES (4 MiB), pelo parâmetro maxBytes de ReadProjectCodeUseCase.file (o default continua o da aba) — RN-1036.

Cortar é sempre visível: toda resposta que pode ter sido cortada diz isso num campo. filesScanned vai junto na busca porque o custo que ninguém vê é o que ninguém corrige.

Ler não vira proposed_action. Leitura não é efeito externo, e transformá-la em ação de aprovação encheria a fila de ruído até ninguém mais ler as de verdade. O congelamento da fase é o outro lado disso: a aba é só leitura, e escrita — quando vier — nasce proposed_action.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts (caminhoDeRepositorioContido), src/application/use-cases/git/read-project-code.use-case.ts, src/domain/git/git-read-limits.ts, src/domain/git/git-read-cache.ts, src/interfaces/http/git/code.controller.ts
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (a contenção isolada), test/application/use-cases/git/read-project-code.use-case.spec.ts (o caminho malicioso recusado nas três rotas antes de o provider ser chamado, e cada um dos três orçamentos parando a busca), test/domain/git/git-read-cache.spec.ts
• Origem: FASE 26b, item 34 do programa 16–26; a contenção estende a RN-092 (ADR 0058)

Sessão

RN-097 — O tipo da sessão é intenção de criação; a execução continua sendo evento

A sessão nasce consultiva ou criativa, escolhida por quem a abre e gravada em sessions.kind. A consultiva é só conversa; a criativa é a que produz — abre a ideação com o agente Criativo e é a única que entra em execução. O tipo nunca muda: não há rota que o troque.

O risco desta regra não é o campo, é a segunda fonte de verdade. O produto já sabia dizer se uma sessão está executando, e sabia por outro caminho: findActiveExecutionSession procura a sessão active que carrega o evento execution.activated (é o que faz a reativação cair na sessão onde os dev agents já estão, achado #11 do primeiro dogfooding). As duas convivem sob uma regra que as impede de brigar:

• O kind classifica a INTENÇÃO de criação. Uma sessão criativa que nunca ativou a execução não é a sessão de execução corrente, e a derivação por evento continua sem olhar o kind — se passasse a olhar, toda sessão criativa aberta viraria candidata a receber os dev agents.
• O evento classifica o ESTADO de execução, como sempre.
• execution.activated numa sessão consultiva é ERRO (409), nunca conversão silenciosa. Este é o ponto que decide qual das duas fontes vence: deixar o evento promover o tipo seria justamente fazê-las escreverem uma por cima da outra.

A guarda mora no funil — AppendSessionEventUseCase — e não no ActivateExecutionUseCase, porque os dois caminhos que gravam evento (a rota do usuário e o /internal/* do engine) passam por ele. A leitura extra da sessão só é paga quando o evento é o de execução. A recusa acontece antes do incrementSeq: uma tentativa recusada não pode consumir seq, ou a RN-002 quebraria.

O DEFAULT da coluna é consultiva — o tipo que pode menos: uma linha que chega por um caminho que não passa pela rota (migration, SQL de manutenção) não ganha o direito de executar. O backfill da migration faz o contrário, e de propósito, pelo raciocínio da 0033: no momento em que roda, toda sessão é anterior à distinção, e algumas são sessões onde há dev agents trabalhando — acordá-las como consultiva faria a reativação de um projeto em andamento falhar sem ninguém ter decidido nada.

• Onde: src/domain/sessions/session-kind.ts:50 (podeAtivarExecucao), src/db/schema/sessions.ts:68 (a coluna), src/application/use-cases/sessions/append-session-event.use-case.ts:54 (a guarda)
• Teste: test/application/use-cases/sessions/session-kind-e-nome.spec.ts
• Origem: ADR 0061

Painel de projetos

RN-100 — A ordem do sino é do SQL, não do front

A gaveta de notificações mostra os eventos do mais recente para o mais antigo, e quando um projeto tem mais não lidos que o teto de 50 os que aparecem são os mais NOVOS.

A ordenação é do banco por necessidade, não por gosto. A consulta corta em 50 por projeto com uma função de janela (row_number() OVER (PARTITION BY session_id ORDER BY seq DESC)), e é ela que decide quais 50 eventos sobrevivem — não só em que ordem eles saem. Com ASC sobreviviam os 50 mais antigos, e um .sort() no cliente ordenaria por recência justamente a janela que a consulta já tinha escolhido errado: num projeto com 300 não lidos, o 251º evento apareceria como "o mais recente". É por isso que não há ordenação nenhuma no caminho do front, e o comentário no componente diz que não pode haver.

A consequência, e por que o corte de leitura não mudou. O corte é um seq por projeto no localStorage, e não existe endpoint de marcar lido, por decisão registrada na RN-091. Um corte por seq marca um prefixo; a gaveta agora mostra um sufixo. Marcar como lidas "as 50 exibidas" é inexprimível sem um conjunto de lidos por evento — tabela nova, fora de escopo. Os dois únicos cortes expressáveis continuam sendo "nada" e "tudo até agora".

A saída não foi mudar a semântica (ela continua avançando para o último seq, exatamente como antes), foi parar de esconder o que esse avanço engole:

• cada projeto mostra o total de não lidos, não o tamanho da janela, e declara quantos ficaram de fora (+ N mais antigos);
• o botão passa a dizer o que faz — marcar as N como lidas — quando há algo fora da janela;
• o número que falta sai de subtração, não de requisição: latestSeq menos o corte já vem no resumo do workspace (RN-090).

Como a semântica do corte não mudou, não há ADR nesta regra: o que mudou foi qual janela a consulta escolhe e o que a gaveta declara sobre ela.

• Onde: src/infrastructure/persistence/drizzle/projects-summary.repository.ts (unreadEventsForWorkspace), src/application/ports/projects-summary-repository.port.ts, src/interfaces/http/iam/dto/iam.response.dto.ts (ProjectUnreadEventsResponseDto), apps/web/src/lib/notifications.ts (useNotificationGroups), apps/web/src/components/NotificationBell.tsx
• Teste: test/infrastructure/persistence/drizzle/projects-summary.repository.spec.ts ("com mais não lidos que o teto, voltam os MAIS RECENTES, do novo para o velho" — afirma o CONJUNTO antes da ordem); apps/web/src/components/NotificationBell.test.tsx (renderiza na ordem recebida, sem reordenar; o contador é o total; o botão diz quantas marca); apps/web/src/lib/notifications.test.tsx (o que ficou fora da janela sai por subtração, sem segunda requisição); apps/web/src/routes/Dashboard.fanout.test.tsx (a gaveta continua sendo UMA requisição)
• Origem: pedido do usuário na primeira navegação real — "Sino e notificações devem sempre ordenar para última data modificada em descendente para a mais antiga"

RN-101 — O mesmo gasto, duas audiências: a fatura é do owner, o consumo é de quem gastou

O produto responde duas perguntas diferentes sobre token_usage, e nenhuma é recorte da outra.

A do owner é por CREDENCIAL. GET /workspaces/:id/credential-spend continua como a RN-060 o deixou — por provider, exigindo owner, respondendo "quanto saiu da minha chave". Junto dele, GET /workspaces/:id/spend-report (também owner) quebra o workspace por modelo, provider, projeto, ator e dia — o eixo de provider entrou pela RN-186. O owner vê os dois porque é a única pessoa que pode ver os dois.

A do membro é por ATOR. GET /projects/:id/spend/me (papel viewer) devolve, em tokens e custo estimado, o que quem chamou consumiu naquele projeto, por sessão e por dia. Ela não quebra por provider nem por credencial — a chave que rodou é a do owner (RN-058), e uma fatia da fatura dele não é o que o membro está perguntando.

O ator não é parâmetro: sai do usuário autenticado, e não existe onde escrever o id de outra pessoa. "Membro não vê linha de outro ator" é propriedade da assinatura do caso de uso, não uma checagem que alguém pode esquecer de chamar.

Agente não entra na conta do membro. token_usage registra quem GASTOU, não quem mandou gastar; atribuir o agente a quem o iniciou seria inventar um dado que a tabela não tem. Gasto de agente aparece no relatório do owner, de quem é a chave.

O eixo de provider existe, e o membro não o alcança. Até o ADR 0076 ele simplesmente não existia na agregação, e era a ausência que continha a visão do membro. Hoje sumGroupedBy tem seis dimensões (model, provider, project, actor, session, day) e a contenção mudou de forma, não de força: quem contém é o TIPO — ver RN-186 e RN-187. O que não mudou é que dois providers servindo o mesmo nome de modelo continuam caindo numa linha só na dimensão model.

• Onde: src/application/use-cases/llm/get-my-spend.use-case.ts, src/application/use-cases/llm/get-workspace-spend-report.use-case.ts, src/application/ports/token-usage-repository.port.ts, src/interfaces/http/llm/spend.controller.ts, apps/web/src/routes/ProjectSpendTab.tsx
• Teste: test/application/use-cases/llm/spend-audiencias.use-case.spec.ts (o membro não enxerga linha de outro ator, nem de agente, nem do owner; o filtro é pelo par (kind, id); a resposta não carrega provider); apps/web/src/routes/ProjectSpendTab.test.tsx
• Origem: ADR 0063 (FASE 22), revisto pelo ADR 0076

RN-102 — O modelo da área é padrão herdável; divergir é decisão do agente, e voltar a herdar apaga a decisão

A cascata de binding ganhou um nível: sessão > agente > **área** > projeto > workspace. area fica ENTRE agente e projeto — é o PADRÃO que o lead e os subagentes de uma área compartilham (qa/qa-automacao/ qa-performance-seguranca, infra/infra-workflows, dev/dev-<módulo>), e o binding do próprio agente é a DIVERGÊNCIA que o sobrepõe. Se a área viesse ACIMA do agente ela venceria sempre, e "padrão herdável" seria, na prática, "padrão imposto" — nenhum agente conseguiria escolher outro modelo.

O nível novo entra na MESMA revalidação de capability da RN-041/RN-043: modelo da área que sumiu do provider ou que não faz tool calling é PULADO e registrado em skipped, exatamente como agent já era. assertModelFitsBindingScope (RN-040) passou a exigir supports_tool_calling também no escopo area — ela nunca é lida por chat humano, só por agente, então deixá-la passar adiaria a mesma falha silenciosa em um nível.

"Voltar a herdar" apaga o binding, nunca copia o modelo do nível de baixo para o de cima. Gravar no agente o modelo que a área decidiu pareceria igual na tela e não é: viraria uma CÓPIA, e a próxima mudança da área deixaria esse agente para trás sem ninguém notar. Herdar é a AUSÊNCIA de decisão própria, e desfazer uma divergência é remover a linha — DELETE /projects/:id/agent-bindings/:slug e DELETE /projects/:id/area-bindings/:key, ambos 204, ambos 404 quando o escopo já herda (idempotência que MENTIRIA se fosse 204 silencioso: apagar o que não existia e apagar de verdade são respostas diferentes para a mesma tela).

Mudar o modelo da ÁREA exige maintainer, e não developer como o do agente individual — pelo mesmo motivo do teto de paralelismo (RN-083): o binding da área alcança o lead e TODOS os subagentes de uma vez, e escolher modelo é decidir quanto o produto gasta sem perguntar.

A TELA passou a honrar os DOIS mínimos, e são dois. Até aqui ModelsSection — a tabela de modelo por agente — não checava papel nenhum: o ModelPicker da coluna MODELO VIGENTE e o "voltar a herdar" da coluna ORIGEM apareciam clicáveis para todo mundo, viewer incluído, e a api recusava com 403. A saída NÃO foi copiar o gate da seção irmã (owner || maintainer): isso trocaria o defeito pelo INVERSO, trancando um developer fora de uma ação que PUT/DELETE .../agent-bindings/:slug aceita — e o inverso é pior, porque oferecer o que será recusado ao menos termina num toast, enquanto perder capacidade é invisível para quem a perdeu. O mínimo é do ENDPOINT, não da seção, e as duas seções são vizinhas na MESMA tela com mínimos diferentes. A comparação saiu das telas e virou roleAtLeast (apps/web/src/lib/roles.ts), sobre o ROLE_ORDER que já existia — mesmo nome da função do backend, porque é a mesma regra dos dois lados do fio; escrever a hierarquia à mão (role === 'owner' || role === 'maintainer') acerta por acidente enquanto o mínimo é alto e erra calada quando é baixo. Papel AUSENTE (consulta em voo, ou que falhou) não alcança nada: errar para o lado de desabilitar se conserta recarregando.

Some o CONTROLE, nunca a INFORMAÇÃO (ADR 0064). Quem não pode editar continua vendo o modelo vigente no gatilho e a cadeia de origem inteira (RN-470), e o "voltar a herdar" continua na linha, inerte — ele é o que DIZ que aquele agente divergiu, e escondê-lo apagaria um estado que dá para ler sem poder mudar. O motivo de estarem apagados é dito UMA vez, em texto, na legenda da seção, e não por title em cada linha: tooltip em elemento disabled não abre no Chromium (o navegador não despacha evento de mouse em controle desabilitado), e uma explicação que não aparece é a mesma ausência com mais código.

Nada disso é fronteira de segurança, e o limite é declarado. Quem recusa continua sendo o RolesGuard. O papel que a tela lê é o do WORKSPACE (useCurrentWorkspaceWithRole) e quem autoriza do outro lado é o papel EFETIVO do PROJETO (ResolveEffectiveRoleUseCase.forProject), que uma linha de project_members SOBREPÕE nos dois sentidos — então quem tem papel próprio no projeto pode ver aqui um controle desabilitado que a api aceitaria. Fechar isso exigiria uma consulta de papel POR PROJETO que o web ainda não tem, e é a mesma lacuna que a caixa da área (RN-912) também carrega; inventar uma segunda fonte de papel só numa seção seria pior que a lacuna.

Nota aditiva (RN-471): a lacuna do parágrafo acima é UMA, não uma por seção, e onde a tela JÁ faz a consulta de papel por projeto ela se fecha em vez de se declarar. A seção de Membros busca listProjectMembers, que é findMemberRole para todo mundo de uma vez, e compõe projectRole ?? workspaceRole — exatamente o que forProject faz. Isso não é a segunda fonte de papel que este parágrafo recusa: é a MESMA composição, a partir de dados que aquela seção já tem em mãos. As duas seções de modelo continuam com a aproximação por não terem esses dados. Cuidado ao ler "SOBREPÕE nos dois sentidos" acima: é literal, e três descrições de OpenAPI afirmam o contrário — ver a RN-471.

• Onde: src/domain/llm/binding-resolver.ts (precedência), src/domain/llm/model-capabilities.ts (capability de area), src/application/use-cases/llm/resolve-model-binding.use-case.ts (a área do agente sai do catálogo agent-areas.ts, sem round-trip ao banco), src/application/use-cases/llm/clear-model-binding.use-case.ts, src/interfaces/http/llm/model-bindings.controller.ts (area-bindings, DELETE em agent-bindings e area-bindings), apps/web/src/routes/settings/ModelsSection.tsx (coluna Origem com "voltar a herdar"; desde a RN-912 o apagar da área é desmarcar a caixa do lead, e o gate de maintainer segue sobre roleAtLeast sem mudar de mínimo), src/interfaces/http/llm/model-bindings.controller.ts:273 e :301 (developer nos dois endpoints de agente — estas linhas NÃO mudaram), apps/web/src/lib/roles.ts:49 (roleAtLeast — a comparação que faltava), apps/web/src/routes/settings/ModelsSection.tsx:93 (podeEditar, e por que developer e não maintainer), :379 (o picker desabilitado), :446 (o botão desabilitado, e por que o motivo não vai em title), :546 (a legenda que diz o motivo)
• Teste: test/domain/llm/binding-resolver.spec.ts, test/domain/llm/model-capabilities.spec.ts, test/application/use-cases/llm/resolve-model-binding.use-case.spec.ts, test/application/use-cases/llm/clear-model-binding.use-case.spec.ts, apps/web/src/routes/ProjectSettingsTab.test.tsx, apps/web/src/routes/settings/papel-na-tabela-de-agentes.test.tsx (viewer não edita e o clique não chega na api; developer edita e o PUT/DELETE chega; papel ausente é inerte; a informação da linha sobrevive ao controle apagado; e o caso que impede "uniformizar" as duas seções — o mesmo developer vê a tabela de agentes habilitada e a de áreas desabilitada, ao mesmo tempo)
• Origem: ADR 0064 (FASE 23)

RN-103 — O binding de agente é POR PROJETO, não mais global

Até a FASE 23, scope = 'agent' guardava um SLUG global (scope_id = 'qa'), e PUT /projects/:id/agent-bindings/:slug recebia :projectId na rota e o DESCARTAVA de propósito — escolher o modelo do Arquiteto na tela de um projeto mudava o modelo dele em TODOS os projetos. Isso deixou de se sustentar quando a área virou padrão herdável (RN-102): a área é por projeto, e um binding de agente global ACIMA de um padrão por projeto faria o mesmo agente resolver modelos diferentes só onde existisse área — e faria "voltar a herdar" apagar uma decisão que alcançava projetos que ninguém está olhando.

A saída foi tornar agent por projeto também, e não rebaixar a área para abaixo do agente: scope_id de agent e de area virou COMPOSTO — <projectId>:<slug do agente|chave da área> — em vez de inventar uma tabela nova só para guardar um projeto por binding. UUID de projeto e slug de agente nunca contêm :, o que torna o primeiro : um separador não ambíguo; a leitura corta nele, e não em todos, para um slug com : (nenhum existe hoje, mas nada impede) não virar três pedaços.

scope_id sem o projeto (o formato antigo) é RECUSADO na escrita, não aceito e ignorado: gravá-lo criaria um binding que a cascata nunca mais encontraria — invisível, e não um erro. A migração 0040 espalha cada binding de agente global existente para uma linha por projeto (preservando o que cada projeto resolvia antes da mudança) e apaga o formato antigo; é ESPALHAR e não apagar porque a linha global nunca guardou informação de a quem "pertencia" — inventar um projeto dono seria inventar dado que não existia.

• Onde: src/domain/llm/binding-scope-id.ts (formato e validação), src/application/use-cases/llm/set-model-binding.use-case.ts (workspaceDoEscopo passou a derivar o workspace de agent/area também — a curadoria da RN-043 não era verificável neles antes), src/db/migrations/0040_tearful_night_nurse.sql
• Teste: test/domain/llm/binding-scope-id.spec.ts, test/application/use-cases/llm/set-model-binding.use-case.spec.ts, test/application/use-cases/llm/resolve-model-binding.use-case.spec.ts ("o binding de agente é POR PROJETO: o vizinho não o enxerga")
• Origem: ADR 0064 (FASE 23)

RN-105 — Sem imagem decidida pelo Arquiteto, o container não sobe e o Code não abre

A aba Code (GET /projects/:id/code/*, ADR 0060) responde 409 enquanto o projeto estiver em sem_decisao — o estado inicial de todo projeto. sem_decisao vira decidido só quando o Arquiteto emite artifact.project_image pela ferramenta choose_project_image, com imagem OCI de tag explícita (latest recusado), rationale e postura de rede.

A checagem mora no MESMO funil que a contenção de caminho da RN-095 (ReadProjectCodeUseCase.alvo), e não em cada uma das sete rotas (árvore, arquivo, busca, diff de PR, blame, lista de PRs e branches detalhadas, FASE 26b) — checagem duplicada em sete chamadores é checagem que um dia diverge em um deles (ADR 0058). Contagem corrigida aqui: este registro dizia "quatro rotas" desde a FASE 26, e ficou desatualizado quando a FASE 26b acrescentou as três últimas ao mesmo funil sem que ninguém revisasse este número.

O artefato não tem tabela: é o próprio evento no event log, versionado (version cresce a cada emissão, o vigente é o de maior version), do mesmo jeito que artifact.module_map. Revisar a imagem é emitir uma versão nova, nunca sobrescrever a anterior.

• Onde: src/domain/containers/project-container.ts, src/application/use-cases/containers/decidir-imagem-do-projeto.use-case.ts, src/application/use-cases/containers/obter-container-do-projeto.use-case.ts, src/application/use-cases/git/read-project-code.use-case.ts (método portaoDoContainer), apps/engine/lib/engine/harness/tools/choose_project_image.ex
• Teste: test/domain/containers/project-container.spec.ts, test/application/use-cases/containers/container-do-projeto.use-case.spec.ts, test/application/use-cases/git/read-project-code.use-case.spec.ts (bloco "o portão do container")
• Borda: 409 e não 403 — nada está errado com quem pediu nem com a permissão dele; o recurso ainda não existe NESTE ESTADO. E não é 404: a aba existe, só não está liberada. A mensagem diz o que falta, para a tela mostrar o motivo em vez de um erro mudo (RN-088).
• Origem: ADR 0065

RN-106 — git push, PR e deploy não saem pelo terminal — mesmo dentro do escopo do projeto

REVISADA pela RN-418 (ADR 0102, decisão GLOBAL do dono do produto): o deny que este registro descreve virou TETO ABSOLUTO (require_approval incondicional) — o resto desta entrada é histórico, fiel ao que valia até a revisão.

Dentro do container do projeto o agente é livre (ADR 0065): o allowlist de verbos do ADR 0055 não converge (achados Z e AD — verbo, forma e invocação são espaços distintos), e a saída é a parede, não uma lista mais longa. Mas três efeitos atravessam a parede e chegam no mundo, e a decisão do usuário foi textual: "agente livre para o que quiser desde que não seja comandos de git ligado ao deploy e ao PR — estas ações ainda devem ser humanas".

decide() reconhece git push, git remote add/set-url, git merge, os CLIs de provider (gh pr create, gh pr merge, glab mr create/merge, releases e workflow dispatch) e os comandos de deploy comuns (kubectl apply, helm upgrade, terraform apply, docker push, npm publish, ...) por PREFIXO de tokens, ignorando flags globais no meio (git -C /tmp push casa). Qualquer segmento do comando composto que case é deny — não require_approval: "sempre permitir" grava o padrão em allow, e um clique bastaria para a segunda porta ficar aberta para sempre. deny vence allow em qualquer estágio, e é aplicado ANTES de qualquer estágio permissivo em decide().

Negar não tira poder do agente: a mensagem redireciona para a ação TIPADA (git_push, git_merge, pr_open) — que nasce proposed_action, tem papel mínimo próprio e registra no event log o que foi empurrado e para onde. É o caminho que o dev agent já usa (agent_io.ex propõe git_push); o que muda é que agora está garantido por deny, não só combinado por convenção.

• Onde: src/domain/actions/external-effect.ts, src/domain/actions/decide.ts (bloco "FRONTEIRA DO CONTAINER")
• Teste: test/domain/actions/external-effect.spec.ts, test/domain/actions/decide.spec.ts (describe "a fronteira do container")
• Borda: a fronteira NÃO se sobrepõe à trava de merge em branch protegida (RN-014, sempre manual) nem ao escopo de caminho (RN-095/ADR 0055) — as três regras coexistem, cada uma vetando por um motivo diferente.
• Origem: ADR 0065

RN-109 — O nome de pasta do workspace é congelado na criação, e projeto antigo mantém o UUID

A pasta física de um projeto em PROJECT_WORKSPACES_ROOT era o UUID puro — ilegível ao abrir no disco. projects.workspace_dir_name (NOT NULL, UNIQUE) passou a guardar o nome de verdade: <slug>-<8 chars do id> para projeto NOVO (workspaceDirNameFor em src/infrastructure/filesystem/project-workspaces-root.ts), gerado em código — o id nasce de crypto.randomUUID() no CreateProjectUseCase, não do defaultRandom() do Postgres, porque o nome da pasta precisa do id ANTES do insert. Os 8 caracteres seguem a mesma convenção do rótulo de sessão (apps/web/src/lib/session-label.ts).

O nome é CONGELADO no momento da criação e nunca recalculado: UpdateProjectUseCase permite editar o slug depois, e isso NÃO toca workspace_dir_name — reservar a pasta física, com working tree e worktrees de agente possivelmente abertos, é risco real que a decisão evita por construção, não por disciplina de quem chama.

Projeto criado ANTES desta migração (0042) manteve a pasta física que já tinha: o backfill grava workspace_dir_name = id para toda linha existente — o mesmo valor que já era verdade no disco — e NUNCA renomeia diretório nenhum. Um trigger BEFORE INSERT (projects_workspace_dir_name_default_trg) aplica o MESMO fallback (id::text) para qualquer insert que chegue sem o campo — rede de segurança para quem esquecer de gravá-lo (nunca o caminho principal, que sempre grava explícito), e o que mantém as dezenas de fixtures de teste existentes, que não conhecem este conceito, funcionando sem precisar reescrever cada uma.

A derivação de caminho a partir do nome (projectScopeRoot, RN-092/RN-075) passou a receber workspace_dir_name em vez do projectId cru — mesma validação de charset, mesma pureza. O engine lê a MESMA coluna (Engine.Projects.Project.workspace_dir_name/1) para resolver Engine.Actions.Workspace.workspace_dir/1, nunca recomputando o nome a partir do id: as duas derivações (api e engine) são, na prática, a mesma leitura contra o mesmo banco — é o que garante que RN-075 (escopo de terminal) e RN-092 (leitura de código) continuam apontando para a MESMA pasta que o engine realmente usa.

• Onde: src/db/schema/iam.ts (projects.workspaceDirName), src/db/migrations/0042_tough_captain_midlands.sql, src/infrastructure/filesystem/project-workspaces-root.ts (workspaceDirNameFor, projectScopeRoot), src/application/use-cases/iam/create-project.use-case.ts, apps/engine/lib/engine/projects/project.ex (workspace_dir_name/1, all_workspace_dirs/0), apps/engine/lib/engine/actions/workspace.ex (workspace_dir/1,2), apps/engine/lib/engine/dev/worktree_cleanup.ex
• Teste: test/db/workspace-dir-name-migration.spec.ts (trigger, backfill equivalente, unicidade), test/application/use-cases/iam/create-project-semeia-areas.spec.ts (workspaceDirName nasce <slug>-<8 chars>, dois projetos com o mesmo slug em workspaces diferentes não colidem de pasta), test/infrastructure/filesystem/project-workspaces-root.spec.ts
• Borda: o teto de paralelismo e o gate de merge não mudam — RN-109 é só NOME de pasta, nunca política. Renomear o slug depois da criação não renomeia a pasta; a pasta só se lê pelo workspace_dir_name gravado.
• Origem: ADR 0066 (revisa o ADR 0055).

RN-114 — Os quatro segredos irmãos do GIT_OAUTH_STATE_SECRET também não sobem em produção com o valor de exemplo

O ADR 0059 fechou o padrão para GIT_OAUTH_STATE_SECRET e deixou declaradamente aberto que o mesmo modo de falha valia para quatro segredos irmãos, todos com default de desenvolvimento no docker-compose.prod.yml: AUTH_JWT_SECRET, BRABO_SERVICE_TOKEN, CREDENTIALS_MASTER_KEY e SECRET_KEY_BASE. Esta RN fecha os quatro, replicando exatamente a mesma regra — não é decisão nova, é a mesma decisão aplicada aos irmãos.

Em produção (NODE_ENV === 'production'), cada resolutor derruba o boot quando a variável está ausente/só com espaços, é igual ao literal de exemplo do repositório (que é público — está no .env.example), ou tem menos de 16 caracteres. Fora de produção o default de desenvolvimento continua valendo, porque docker compose up sem .env tem que funcionar.

• AUTH_JWT_SECRET — deriva o par Ed25519 que assina o access token. Com o default público, qualquer um forja um access token válido.
• BRABO_SERVICE_TOKEN — autentica o tráfego interno api ↔ engine. Com o default público, qualquer um chama as rotas /internal/* sem passar pelo EngineServiceGuard.
• CREDENTIALS_MASTER_KEY — embrulha os DEKs que cifram as credenciais do usuário (chaves de LLM, tokens de git). Com o default público, qualquer um decripta o acervo. Fora de escopo aqui: qualquer mecanismo de rotação — esse já existe (CREDENTIALS_MASTER_KEY_PREVIOUS + src/scripts/rewrap-deks.ts) e não muda; esta é só a checagem de BOOT.
• SECRET_KEY_BASE (engine) — já derrubava o boot sem a variável (runtime.exs, bloco :prod, boilerplate padrão do Phoenix). O defeito real não era falta de checagem no Elixir: era o docker-compose.prod.yml suprir o literal público como fallback, o que fazia a variável chegar sempre DEFINIDA e mascarava o raise que já existia. A correção aqui foi só remover o fallback do compose — nenhuma linha de Elixir mudou.

Vale a mesma razão do ADR 0059 para rejeitar o literal, e não só o vazio: o docker-compose.prod.yml supria os quatro literais como fallback, então no caminho real de erro as variáveis estavam definidas — uma verificação de "não vazia" passaria por cima do defeito inteiro.

• Onde: src/infrastructure/security/auth-key-material.ts (passphraseAtual), src/infrastructure/security/service-token.ts (tokenDeServicoAtual) e src/infrastructure/security/envelope-encryption.service.ts (EnvelopeEncryptionService, checagem no construtor) — os dois primeiros chamados no boot em src/main.ts, o terceiro exercitado quando o NestFactory.create monta o grafo de providers. SECRET_KEY_BASE em apps/engine/config/runtime.exs (inalterado) com o fallback removido de docker/docker-compose.prod.yml
• Teste: test/infrastructure/security/auth-key-material.spec.ts, test/infrastructure/security/service-token.spec.ts e o describe validação de produção em test/infrastructure/security/envelope-encryption.service.spec.ts
• Origem: ADR 0059

RN-127 — ref/path da aba Code recusam chegar como ARRAY, não só como caminho fora do escopo

@Query('ref') ref?: string e @Query('path') path?: string (code.controller.ts) extraem o valor cru sem DTO/class-validator no meio, e o ValidationPipe global (main.ts) não ajuda: ele pula tipo primitivo nativo (String) por desenho do Nest, então nada intercepta ref/path antes de chegarem como argumento de método. O Express entrega ?ref=a&ref=b como array, não string — a anotação string do TypeScript só existe em compile-time.

Um array escapava das DUAS checagens que a RN-095 já fazia tratando o valor como string: ref.includes('..') tem semântica de ELEMENTO EXATO (não substring) em array, e REF_VALIDO.test(ref) chama .toString() no array antes de casar — um valor como ['x/../y'] continha .. e ainda assim passaria pelas duas.

garantirQueryEscalar(valor, criarErro) recusa o array ANTES de qualquer outra checagem, num lugar só, reusado pelos DOIS pontos que tratavam query como string: caminhoDeRepositorioContido (mesmo arquivo da RN-092/095) e ReadProjectCodeUseCase.alvo (ref). O erro concreto (CaminhoForaDoEscopoError ou BadRequestException) é decidido por quem chama, passado como fábrica — a função central não decide o tipo de erro, só a forma da checagem.

O caminho feliz não muda: todo ref/path legítimo já era string.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts (garantirQueryEscalar, usada em caminhoDeRepositorioContido), src/application/use-cases/git/read-project-code.use-case.ts (alvo, ref)
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (garantirQueryEscalar isolada e caminhoDeRepositorioContido recusando array), test/application/use-cases/git/read-project-code.use-case.spec.ts (ref/path como array são 400 em tree, que todas as outras rotas reusam via alvo)
• Origem: alerta CRÍTICO do CodeQL (confusão de tipo em query param HTTP) bloqueando a promoção qa→main, achado durante a PR #256; estende a RN-095

RN-128 — sessionId/projectId/agent/agentId são validados ANTES de virar segmento de URL da requisição interna ao engine

HttpApiToEngineClient interpola estes valores em template string pra montar a URL de /internal/* — sem DTO/class-validator no meio, igual à RN-127: eles chegam de @Param/lookup de sessão sem pipe de validação em algum ponto da cadeia, e nada garante a forma deles antes da interpolação. Um valor malicioso poderia injetar segmento de path extra ou caracteres que quebram a URL montada — o EngineServiceGuard autentica o CHAMADOR (RN-035), não CONFERE o que o chamador manda na URL.

garantirSegmentoDeUrlInterna reusa a mesma largura de NOME_DE_PASTA_VALIDO (RN-092/109) — hex, hífen e sublinhado, 1 a 64 chars — e é chamada em DOIS lugares, cobrindo TODOS os métodos que interpolam id em URL, não só os que o CodeQL reportou:

• dentro de postCommand, que a maioria dos métodos já usa (startAgent, sendAgentMessage, confirmReadiness, cancelAgentTurn, offerInfraHandoff, invalidateInstructions, startExecution, acceptParallelization, rearmDevAgent, reviseStory) — o chamador lista as tuplas (nome, valor) que já interpolou no path, e postCommand valida TODAS antes de montar a requisição;
• direto em reanalyzeSession/runAnamnese, que não passam por postCommand (precisam distinguir 503 de falha de transporte) e por isso eram os dois únicos pontos que o CodeQL alcançou.

O caminho feliz não muda: sessionId/projectId são sempre UUID vindo do banco, e agent/agentId são sempre slug curto.

• Onde: src/infrastructure/http-clients/api-to-engine-client.ts (garantirSegmentoDeUrlInterna, postCommand)
• Teste: test/infrastructure/http-clients/api-to-engine-client.spec.ts (id malformado é recusado ANTES de tocar a rede — provado apontando ENGINE_URL pra uma porta que nada escuta — e o caminho feliz chega a fazer a requisição)
• Origem: alerta CRÍTICO do CodeQL (URL de requisição interna montada com valor não validado) bloqueando a promoção qa→main, achado durante a PR #256; mesmo padrão do RN-092

RN-135 — Ativar a execução fecha a sessão de CHAT que originou o pedido

ActivateExecutionUseCase sempre resolvia a sessão de EXECUÇÃO (findActiveExecutionSession, ou criava uma criativa nova), mas nunca transicionava a sessão de CHAT de onde veio o clique em "ativar execução" — a conversa com o Dev Lead/PO, numa sessão separada. Ela ficava active para sempre, mesmo com a execução já rodando sozinha em outra sessão, e continuava aparecendo como conversa aberta na lista.

execute() ganhou originSessionId, opcional e por último — um chamador antigo (hoje só a ativação pela Visão Geral, sem contexto de sessão) continua funcionando de forma IDÊNTICA, sem fechar nada. Quando passado, no FIM do método (depois de tudo o mais ter acontecido: module_map, áreas, autonomia, startExecution, execution.activated):

• nunca fecha a própria sessão de execução — se originSessionId for igual à sessão que acabou de receber execution.activated, o fechamento é pulado, porque fechá-la destruiria o processo que os dev agents acabaram de ganhar;
• só fecha o que está active — a mesma cautela de decide-bootstrap-plan.use-case.ts#fecharSessao, nada a fazer se a sessão não existe mais ou já não está aberta;
• reaproveita o GetSessionPendingWorkUseCase (RN-073) — a MESMA guarda que segura o fechamento por heartbeat de inatividade: um handoff oferecido, uma proposed_action pendente ou um agente working sem idle posterior impedem o fechamento;
• passa por closing antes de closed — a máquina de estados (active -> closing -> closed) não permite o salto direto.

Uma falha ou estado pendente aqui NUNCA se propaga a quem chamou execute(): a ativação da execução já aconteceu e é o efeito principal; fechar o chat de origem é um efeito colateral best-effort.

• Onde: src/application/use-cases/execution/activate-execution.use-case.ts (closeOriginSession), src/interfaces/http/execution/dto/activate-execution.dto.ts (originSessionId), src/interfaces/http/execution/execution.controller.ts
• Teste: test/application/use-cases/execution/activate-execution.use-case.spec.ts, describe fecha a sessão de origem (RN-135) — fecha sem pendência, NÃO fecha com pendência, NÃO fecha sessão já não-active, chamador antigo sem o parâmetro não fecha nada, e nunca fecha a própria sessão de execução mesmo se originSessionId coincidir com ela
• Origem: achado de investigação de código — sessão criativa com execução ativada continuava active na lista mesmo com 35 eventos de dev agents dentro dela

RN-139 — A aba Executores lê a sessão de execução VIGENTE, nunca a mais recente do projeto

ProjectExecutorsTab buscava os eventos de dev agent/QA pela sessão que useLatestSession devolvia — a de createdAt mais recente do projeto, sem filtrar por kind nem exigir execution.activated. Funcionava só por coincidência: a sessão de execução costuma ser a mais nova. Assim que qualquer sessão nasce depois dela — uma ideação nova, um chat consultivo — a aba passa a olhar essa sessão nova, vazia de eventos de execução, em silêncio: nenhuma pista na tela dizia qual sessão estava sendo exibida.

A leitura correta já existia no backend: findActiveExecutionSession (SessionRepository) — a sessão active mais recente que carrega execution.activated — mas só era usada internamente por ActivateExecutionUseCase para decidir se reativa ou cria. A correção expõe o MESMO critério por HTTP, em vez de duplicá-lo no front:

• GET /projects/:projectId/execution/session (role:viewer) devolve a sessão vigente ou null — nunca infere pela mais recente;

• ProjectExecutorsTab troca useLatestSession por useActiveExecutionSession (novo hook sobre a rota acima) como fonte da sessão que a aba inteira lê;

• o cabeçalho da aba sempre mostra QUAL sessão está sendo exibida — o rótulo dela (hashtag + nome) linkando para SessionPage, ou "Nenhuma execução ativa" quando null — nunca mais implícito. Os três estados da RN-088 se aplicam à própria busca da sessão: carregando, erro (com trace_id) e vazio (null) são três renders distintos, nunca um if (!sessão) return null que os colapsa.

• Onde: src/application/use-cases/execution/get-active-execution-session.use-case.ts, src/interfaces/http/execution/execution.controller.ts (getSession), apps/web/src/lib/hooks.ts (useActiveExecutionSession), apps/web/src/routes/ProjectExecutorsTab.tsx

• Teste: apps/web/src/routes/ProjectExecutorsTab.test.tsx — mostra a sessão de execução mesmo com sessão mais recente existindo no projeto, estado "nenhuma execução ativa" explícito, e erro de rede tratado (não em branco)

• Origem: achado de investigação de código + teste ao vivo — a mesma classe de defeito que a RN-088 fechou para 429, agora para "qual sessão a tela está olhando"

RN-143 — Um subcomando de git somente leitura só é permitido ancorado pela flag que torna a leitura inequívoca, nunca pelo verbo solto

Consultando o banco de uma execução real, os dev agents queimaram dezenas de aprovações manuais em subcomandos de exploração — git branch -a, git remote -v, git worktree list, git show origin/dev --stat, git log --all --oneline --graph, git for-each-ref, git ls-tree -r origin/dev --name-only, git config user.name — nenhum coberto pela RN-068, que só permitia git status/diff/log (sem flags extras). Como o casamento por prefixo de token exige que TODO segmento de um comando composto esteja em allow, uma longa cadeia de exploração caía inteira em require_approval no instante em que UM desses subcomandos aparecia no meio.

DEV_TERMINAL_ALLOW_PATTERNS ganhou git branch -a/-r/-v/--list/--show-current, git remote -v/git remote show, git worktree list, git show, git for-each-ref, git ls-tree, git rev-parse e git config --get. O git log não precisou de padrão novo: o casamento já é por PREFIXO de token (tokens finais extras são permitidos), então Terminal(git log) já cobria git log --all --graph --oneline --decorate.

A cautela aqui é a mesma que a RN-068 já mostra para ls/lsof, aplicada a verbos com um irmão MUTANTE que aceita a mesma forma truncada do padrão. Terminal(git branch) casaria git branch -D nome (apaga) tanto quanto git branch nome-nova (cria) ou git branch sozinho — o padrão não vê o que vem DEPOIS do prefixo que conferiu. É por isso que nenhum dos quatro verbos com forma mutante (branch, remote, worktree, config) foi admitido pelo verbo solto; cada um foi ANCORADO pela flag que torna a leitura inequívoca independentemente do que vem depois:

• git branch — ancorado em -a/-r/-v/--list/--show-current, nunca no verbo sozinho; -D/-d/-m/-M (apagar/renomear) e um nome de branch solto (criar) ficam de fora.

• git remote — ancorado em -v e show (que só aceita um nome de remoto depois, sempre uma leitura); add/remove/set-url ficam de fora.

• git worktree — ancorado em list; add/remove/prune ficam de fora.

• git config — só --get foi admitido, porque é a única flag que o próprio git garante ser leitura independentemente do que vem depois (uma chave, ou uma chave + padrão de valor). git config user.name/git config user.email SEM --get foram deixados de fora deliberadamente: um segundo token depois da chave (git config user.name "novo valor") é uma ESCRITA, e o casamento por prefixo não distingue "nenhum token a mais" de "um token a mais" sem inventar um novo parser de contagem de argumentos — a mesma limitação que já bloqueia um git branch solto. --global/--system nunca foram ancorados.

• Onde: src/domain/actions/dev-terminal-patterns.ts

• Teste: test/domain/actions/dev-terminal-patterns.spec.ts (describe read-only git subcommands (found live) — cobre a cadeia composta observada ao vivo sendo auto-aprovada, e cada variante mutante com a MESMA palavra de comando — git branch -D, git remote add, git worktree add, git config --global user.name — permanecendo em require_approval)

• Origem: consulta ao banco de uma sessão real, achada durante o uso

RN-145 — O Arquiteto também tem um botão de prontidão, e a MESMA confirmação oferece Infra e Dev Lead

OfferInfraHandoffUseCase (POST .../agents/arquiteto/handoff-infra) já existia desde a Fase 4a — grava architecture.readiness_confirmed e chama o engine, que oferece o handoff ao Infra e, na MESMA confirmação, ao Dev Lead (FASE 14d/ADR 0053). O que faltava era o jeito de chegar até ele: nenhum lugar do frontend chamava o endpoint. O botão "Confirmar arquitetura pronta" existe pro Criativo desde sempre ("Estou pronto para produzir", RN-131/RN-142) — o Arquiteto não tinha equivalente nenhum, e sem o clique o handoff nunca nascia: a correção de prioridade do card no fio (RN-125) ficava sem efeito prático, porque não havia o que mostrar.

arquitetoActive espelha criativoActive (existe um agent.activated pro Arquiteto nesta sessão) e arquiteturaJaDeclarada espelha prontidaoJaDeclarada (existe QUALQUER handoff saindo do Arquiteto — a prova de que a confirmação já aconteceu, já que OfferInfraHandoffUseCase cria pelo menos o de Infra na mesma chamada). O botão aparece no composer só quando o primeiro é verdadeiro e o segundo não é — some depois do clique pelo mesmo motivo que o do Criativo some depois da prontidão.

Ao contrário do Criativo, o Arquiteto NÃO tem guardrail de servidor bloqueando a confirmação sem module_map — ArquitetoServer.offer_infra_handoff não recusa nada, diferente de CriativoServer.confirm_readiness (RN-142). O botão só desabilita durante streaming; não replicar aqui o disabled={!hasModuleMap} da Visão Geral é decisão deliberada, pelo mesmo raciocínio que já vale para "Ativar execução" no card do Dev Lead (RN-137) — quando este card existe, o Arquiteto já decidiu a arquitetura.

• Onde: src/interfaces/http/agents/agents.controller.ts (handoffInfra, rota preexistente), apps/web/src/lib/api-client.ts (confirmArchitectureReadiness), apps/web/src/routes/SessionPage.tsx (arquitetoActive, arquiteturaJaDeclarada, handleArchitectureReadiness, botão "Confirmar arquitetura pronta")
• Teste: apps/web/src/routes/SessionPage.arquiteto-modelo-icone.test.tsx, describe "problema 1" — botão ausente sem o Arquiteto ativo, caminho feliz chama o endpoint dedicado, falha mostra toast de erro, e o botão some com a arquitetura já declarada
• Origem: investigação de código — o endpoint e a lógica do engine existiam desde a Fase 4a/14d sem NENHUM caminho de UI até eles

RN-146 — agent.response carrega o nome do modelo que gerou a resposta

O nome do modelo só existia em token_usage, sem vínculo com o evento agent.response específico que ele produziu — SessionPage.tsx mostrava a string FIXA "modelo" ao lado do nome do agente, nunca o nome real.

A mudança atravessa as três camadas, todas com o MESMO nome de campo (modelName), para que não seja preciso traduzir entre elas:

1. api — StreamLlmTurnUseCase/RunLlmTurnUseCase já resolviam o modelo (resolveModelBinding → models.findById) para chamar o provider; o frame final/RunLlmTurnResult ganham modelName: string | null. null só quando o turno falhou ANTES de resolver um modelo (sem binding, ou binding para modelo inexistente) — nos demais casos, inclusive orçamento excedido, o binding já tinha resolvido e o nome viaja mesmo no frame de erro.
2. engine — os quatro agentes conversacionais (criativo_server.ex, po_server.ex, arquiteto_server.ex, dev_lead_server.ex) extraem Map.get(frame, "modelName") do frame final e o incluem no payload de emit_response/agent.response (%{content: content, modelName: model_name}).
3. web — SessionPage.tsx lê event.payload.modelName. Evento GRAVADO antes desta mudança não tem a chave (undefined), e um turno cuja api não resolveu modelo nenhum grava null — os dois degradam para o rótulo genérico "modelo", nunca para undefined/null na tela; o mesmo padrão que text === '' já usa para resposta anterior à RN-059.

• Onde: src/application/use-cases/llm/stream-llm-turn.use-case.ts (LlmTurnStreamEvent), src/application/use-cases/llm/run-llm-turn.use-case.ts (RunLlmTurnResult), src/interfaces/http/internal/dto/internal.response.dto.ts (LlmTurnResponseDto/LlmTurnStreamEventResponseDto), apps/engine/lib/engine/agents/{criativo,po,arquiteto,dev_lead}_server.ex (emit_response/3), apps/web/src/routes/SessionPage.tsx (bloco agent.response da timeline)
• Teste: test/application/use-cases/llm/run-llm-turn.use-case.spec.ts, test/application/use-cases/llm/stream-llm-turn.use-case.spec.ts (modelName no caminho feliz, no erro do provider e sem binding), apps/engine/test/engine/agents/{criativo,po,arquiteto,dev_lead}_server_test.exs (agent.response carrega o nome do modelo; borda do frame sem a chave), apps/web/src/routes/SessionPage.arquiteto-modelo-icone.test.tsx, describe "problema 2" — nome real, evento antigo sem a chave, modelName: null
• Origem: investigação de código — confirmado que o dado já existia em token_usage, mas nunca chegava ao payload do evento

RN-149 — O Container level do diagrama C4 é derivado do module_map, nunca redigitado pelo modelo

create_c4_diagram (ferramenta nova do Arquiteto) gera as duas sintaxes Mermaid do diagrama C4 (Context + Container, modelo de Simon Brown). O tool call carrega só system_name/system_description/actors — os módulos e as dependências do nível Container NÃO fazem parte da entrada: o caso de uso busca o module_map VIGENTE do projeto (ModuleMapRepository.findCurrent, mesma leitura de GetArchitectureUseCase) e deriva o Container level dele, com os MESMOS nomes e dependências que create_module_map já validou sem ciclo.

A alternativa óbvia — deixar o modelo descrever os módulos de novo no tool call do diagrama, como ele já faz para create_module_map — foi descartada de propósito: um segundo lugar onde o modelo escreve "os módulos são X, Y, Z" é um segundo lugar onde essa lista pode divergir da primeira, e a divergência seria SILENCIOSA — nada recusaria um diagrama com um módulo que não existe mais no mapa real. Derivar do repositório fecha essa divergência por construção: o diagrama pode ficar DESATUALIZADO se o module_map mudar depois (reemitir é gerar de novo, sem trava — ver ADR 0068), mas nunca MENTE sobre o que existia no momento em que foi gerado.

Sem module_map vigente, create_c4_diagram é recusado com 400 — não há Container level sem módulos para desenhar, e a mensagem de erro instrui o Arquiteto a chamar create_module_map primeiro (RN-061: a recusa volta pelo tool-result, com o motivo inteiro).

O artefato artifact.c4_diagram é versionado no event log sem tabela própria — mesmo desenho de artifact.project_image (ADR 0065): o vigente é o de maior version, e revisar é gerar de novo, nunca sobrescrever.

• Onde: src/domain/architecture/c4-diagram.ts (gerarDiagramaContexto/gerarDiagramaContainer, puras), src/application/use-cases/architecture/create-c4-diagram.use-case.ts, src/application/use-cases/architecture/get-c4-diagram.use-case.ts, apps/engine/lib/engine/harness/tools/create_c4_diagram.ex, apps/web/src/components/C4DiagramView.tsx (renderização, três estados — RN-088), apps/web/src/lib/mermaid-render.ts (o mermaid fica isolado aqui, import() dinâmico)
• Teste: test/domain/architecture/c4-diagram.spec.ts (sintaxe Mermaid válida a partir de um module_map de exemplo, aresta pendurada ignorada, ids deduplicados), test/application/use-cases/architecture/create-c4-diagram.use-case.spec.ts (sem module_map recusa com 400 e não grava nada; Container reflete os módulos/dependências reais; versiona ao reemitir), apps/engine/test/engine/harness/tools/create_c4_diagram_test.exs, apps/web/src/components/C4DiagramView.test.tsx (sucesso vira SVG, erro de sintaxe vira Alert legível sem quebrar a tela, diagrama vazio não tenta renderizar)
• Origem: pedido do usuário — diagrama C4 do Arquiteto na Visão Geral do projeto (ADR 0068)

RN-151 — O badge de projeto na sidebar é aprovações pendentes, não atividade não lida

O número ao lado do nome de cada projeto em Shell.tsx vinha de useProjectsUnread — latestSeq (o seq mais recente já gravado na sessão) menos o cursor de "última vez visto" que o navegador guarda em read-state.ts. Isso conta QUALQUER evento novo — tool.call, agent.response, chat — não só decisão pendente. Um projeto de teste mostrava "392" na sidebar (atividade acumulada de uma execução real) enquanto a aba Aprovações do MESMO projeto mostrava "8" (a contagem de verdade). Um número que não corresponde a nada acionável ao clicar é pior que nenhum.

O read model do dashboard (ProjectsSummaryRepository.summarizeForWorkspace, RN-090) ganhou pendingApprovalsCount: COUNT(*) de proposed_actions com status = 'pending', agregado por project_id numa consulta a mais no Promise.all já existente — mesmo formato de storiesAwaitingPromotion (RN-048), sem crescer o número de idas ao banco por projeto. A soma é do projeto INTEIRO, todas as sessões — de propósito diferente da aba Aprovações (ProjectApprovalsTab.tsx), que mostra só as pendências da sessão MAIS RECENTE: o badge é por PROJETO, não por sessão, e uma pendência numa sessão antiga continua sendo uma pendência.

Shell.tsx parou de importar useProjectsUnread — o único consumidor dele ali era este badge. Dashboard.tsx/ProjectCard.tsx ganharam o mesmo fio: o prop unreadCount de ProjectCard nunca tinha chamador (ProjectCardContainer não o passava), e virou pendingApprovalsCount com o mesmo valor da sidebar — duas telas, um número, uma fonte.

• Onde: src/application/ports/projects-summary-repository.port.ts (ProjectCardSummary.pendingApprovalsCount), src/infrastructure/persistence/drizzle/projects-summary.repository.ts (summarizeForWorkspace, consulta agregada sobre proposed_actions), apps/web/src/routes/Shell.tsx, apps/web/src/routes/Dashboard.tsx, apps/web/src/components/ProjectCard.tsx
• Teste: test/infrastructure/persistence/drizzle/projects-summary.repository.spec.ts (pendingApprovalsCount soma o projeto INTEIRO..., só pending conta, não vaza entre projetos, número de consultas continua constante), apps/web/src/routes/Shell.test.tsx (badge de aprovações pendentes)
• Origem: achado do usuário navegando a app — badge da sidebar mostrando "392" contra "8" de verdade na aba Aprovações do mesmo projeto

RN-153 — "Auto mode": o ApprovalCard liga autonomia pra QUALQUER ação futura de um agente

Revista pela RN-603 (ADR 0167): decide() passou a receber também a ORIGEM da autonomia, e o modo automático (a curinga em auto_approve) não passa mais pelo teto de escopo de caminho. O que segue abaixo sobre decide() "não mudar" descreve o desenho original.

Antes deste RN, agent_autonomy só sabia conceder autonomia por (projeto, agente, TIPO de ação) — uma linha por tipo, upsert de UMA regra por vez (SetAgentAutonomyUseCase, src/application/use-cases/actions/set-agent-autonomy.use-case.ts). Confiar amplamente num agente exigia uma linha por tipo — terminal, write_file, pr_open… — e tipo novo nascia sem regra, de volta a require_approval.

"Auto mode" é o valor especial actionType: "*" na MESMA tabela e no MESMO endpoint (PUT /projects/:projectId/agent-autonomy) — não é mecanismo novo, é a coluna existente (agent_autonomy.action_type, text livre, sem enum nem FK — src/db/schema/agents.ts) aceitando um valor a mais. A curinga significa "autonomia pra qualquer tipo de ação DESTE agente" e é resolvida em DrizzleAgentAutonomyRepository.findMode (src/infrastructure/persistence/drizzle/agent-autonomy.repository.ts): busca a regra ESPECÍFICA e a curinga na mesma consulta, e a específica sempre vence — gravar terminal: deny com "*": auto_approve já ligado continua negando terminal desse agente, e liberando o resto. decide() (src/domain/actions/decide.ts) não muda: ele recebe o PermissionPolicy já resolvido em ctx.autonomyMode, exatamente como antes da curinga existir — é por isso que os tetos absolutos valem sem precisar saber que "auto mode" existe (ver RN-154).

O ApprovalCard (apps/web/src/components/ApprovalCard.tsx) ganha o botão "Modo automático" ao lado de "Sempre permitir", visível só quando: (a) a ação está pending, (b) quem propôs é um AGENTE (actor.kind === 'agent' — não há autonomia de agente para conceder a um usuário) e (c) quem chama (ProjectApprovalsTab.tsx/SessionPage.tsx) já confirmou papel maintainer/owner no workspace — mesma exigência do endpoint (@RequireRole('maintainer'), inalterado). O prop onActivateAutoMode é undefined para quem não tem o papel — o card ESCONDE o botão em vez de mostrá-lo desabilitado, e a checagem mora em quem chama, não no card (componente presentational, sem query própria).

Desligar reusa o toggle manual/auto que o card do agente já tinha (Fase 8d) — nenhuma tela nova. AgentTeamGrid.tsx passa a procurar a regra curinga do agente ANTES da representativa (autonomyActionTypeFor): se existir, o toggle do card reflete e edita a CURINGA, não mais o tipo representativo — desligar é gravar a mesma curinga como require_approval, e o toggle no card do agente é exatamente esse "desligar".

• Onde: src/domain/actions/decide.ts (AGENT_AUTONOMY_ALL_ACTIONS, AgentAutonomyActionType), src/infrastructure/persistence/drizzle/agent-autonomy.repository.ts (findMode com precedência específica > curinga), src/interfaces/http/actions/dto/set-agent-autonomy.dto.ts (aceita "*"), apps/web/src/components/ApprovalCard.tsx (botão "Modo automático"), apps/web/src/components/AgentTeamGrid.tsx (toggle passa a priorizar a curinga), apps/web/src/routes/ProjectApprovalsTab.tsx e apps/web/src/routes/SessionPage.tsx (handleActivateAutoMode, gate de papel via useCurrentWorkspaceWithRole)
• Teste: test/infrastructure/persistence/drizzle/agent-autonomy.repository.spec.ts (precedência específica > curinga; curinga é por agente; desligar é regravar a curinga como require_approval), test/application/use-cases/actions/propose-action.use-case.spec.ts (auto mode auto-aprova ação comum SEM bater em permissions.json; regra específica em deny vence a curinga), test/interfaces/http/actions/agent-autonomy.controller.spec.ts (PUT/GET continuam exigindo maintainer; DTO aceita "*" e recusa string fora da lista), apps/web/src/components/ApprovalCard.test.tsx (botão some sem onActivateAutoMode; clique chama o callback; nota explica os tetos que continuam pedindo decisão)
• Origem: pedido do usuário — "Sempre permitir" só grava um padrão de comando específico, e agent_autonomy só cobria um tipo de ação por vez; faltava confiar amplamente num agente com um clique só

RN-154 — Os três tetos absolutos continuam bloqueando MESMO com "auto mode" ligado

Revista pela RN-603 (ADR 0167): os tetos listados aqui seguem valendo em modo automático; o que deixou de valer para ele foi o teto de ESCOPO DE CAMINHO (ADR 0055), que nunca esteve nesta lista.

O desenho do "auto mode" (RN-153) é deliberadamente incapaz de furar os três tetos que já existiam em decide() — eles são aplicados por ÚLTIMO, sobre current.policy, sem olhar de onde veio a permissividade (agent_autonomy com tipo específico, curinga, ou permissions.json — a função nunca soube distinguir as origens, e continua sem saber):

1. Merge em branch protegida (git_merge com destino em dev/qa/rc/main, RN-006) — a trava de merge (isProtectedBranch) rebaixa auto_approve para require_approval sempre, mesmo com "*": auto_approve ligado pro agente.
2. instruction_patch (RN-007) — mudar a instrução de outro agente exige o humano ver o diff; auto mode não muda isso.
3. parallelize/raise_max_parallel (RN-086) — subir o teto de paralelismo, ou pedir mais agente acima dele, continua decisão do usuário; um agente com auto mode ligado não consegue se auto-conceder mais poder de gasto.

A prova é por CONSTRUÇÃO, não por caso a caso: como os três tetos verificam só current.policy === 'auto_approve' — nunca a origem —, e "auto mode" só consegue chegar em current.policy === 'auto_approve' pelo MESMO caminho que uma regra específica de agent_autonomy já usava (ctx.autonomyMode), os tetos que já continham agent_autonomy continuam contendo a curinga sem precisar de código novo. O risco real não era o teto — era alguém, ao generalizar agent_autonomy pra aceitar "*", inserir a checagem da curinga ANTES dos tetos e reabrir a porta; por isso AGENT_AUTONOMY_ALL_ACTIONS foi resolvido inteiramente no REPOSITÓRIO (antes de decide() rodar), e decide() em si não ganhou nenhuma linha nova — só o suficiente pra não ter onde a curinga furar.

• Onde: src/domain/actions/decide.ts (os três blocos de teto, linhas ~207–258, inalterados por esta feature)
• Teste: test/application/use-cases/actions/propose-action.use-case.spec.ts ("auto mode NÃO auto-aprova merge em branch protegida", "... instruction_patch", "... parallelize/raise_max_parallel" — os três com agent_autonomy "*" gravado como auto_approve e o veredito continuando require_approval)
• Origem: restrição de design confirmada pelo usuário ao pedir o "auto mode" — os três tetos são a garantia que não pode regredir

RN-155 — ordenação da timeline usa o vínculo proposed_action.created, nunca action.seq cru

A timeline de SessionPage.tsx ordena eventos e ações propostas por um único eixo numérico comparável. Para eventos, é event.seq (gapless, por sessão). Para ações, é o seq do evento proposed_action.created correlato (achado por payload.actionId === action.id, gravado por ProposeActionUseCase na MESMA transação que cria a ação) — nunca action.seq, que é bigserial único e global de toda a tabela proposed_actions, compartilhado por todas as sessões e projetos do sistema, e portanto incomparável com event.seq (contraste deliberado, ver src/db/schema/actions.ts). Comparar os dois direto produzia ordem imprevisível toda vez que um ApprovalCard entrava na mistura com eventos normais. Ações sem esse vínculo (só o bootstrap de Gitflow — git_repo_create/git_branch_create, que gravam apenas outbox) degradam para uma posição interpolada por createdAt, ancorada no último evento anterior.

• Onde: apps/web/src/routes/SessionPage.tsx (ordemDaAcaoNaTimeline)
• Teste: apps/web/src/routes/SessionPage.ordenacao-e-avisos.test.tsx
• Origem: achado de PR #286 — cards de aprovação apareciam fora de ordem na timeline, misturados com eventos normais

RN-169 — O projeto escolhe onde o código mora: Local ou Container

REVISADA pela RN-421 (ADR 0104): workspace_mode/local viraram execution_mode de TRÊS valores (container/mounted/runner, migração 0048) — o resto desta entrada é histórico, fiel ao que valia até a revisão.

Um projeto nasce com um modo de workspace (projects.workspace_mode, migração 0043), e é ele que decide de onde a raiz de escopo é derivada:

• container (DEFAULT, e o comportamento que sempre existiu): a pasta GERENCIADA pelo produto, join(PROJECT_WORKSPACES_ROOT, workspace_dir_name) (RN-109);
• local: uma pasta DO USUÁRIO, no caminho absoluto de projects.workspace_path.

O par é amarrado por CHECK no banco ((workspace_mode = 'local') = (workspace_path IS NOT NULL)), e não só pelo caso de uso: a coluna é lida por DOIS processos (api e engine) e escrita por scripts de seed/backfill que não passam por ele. local sem caminho seria escopo de terminal apontando para lugar nenhum; container com caminho seria uma segunda fonte de verdade esperando divergir da primeira.

A derivação continua única — projectScopeRoot passou a receber a localização ({workspaceDirName, workspaceMode, workspacePath}) e escolhe o ramo; nenhum dos quatro consumidores (RN-092) ganhou validação própria. O engine resolve o mesmo localizador na CONSULTA (nome de pasta no container, caminho absoluto no local) e distingue os dois pela barra inicial, que é inequívoca porque o nome de pasta é validado contra ^[A-Za-z0-9_-]{1,64}$.

Duas consequências explícitas do modo local:

1. O portão da imagem do Arquiteto (RN-105) NÃO vale. REVOGADO pela RN-494 (ADR 0135): a dispensa terminou — os três modos passam a exigir a decisão de imagem antes de abrir a aba Code. O resto deste item é histórico. Projeto Local não sobe container, então a aba Code liberava sem esperar decisão que nunca ia acontecer. A dispensa morava no mesmo funil do portão na api, e a tela concordava: ProjectCodeTab nem chegava a perguntar o estado do container (RN-107) quando o projeto era Local — se só a api dispensasse, a aba continuaria bloqueada na tela por uma decisão inexistente.
2. O permissions.json mora na pasta do usuário, junto com o código — porque a política tem que ser lida da MESMA raiz que o escopo de terminal autoriza.

workspace_mode não confunde com o GitProviderName 'local': um diz onde o CÓDIGO mora em disco, o outro onde o REPOSITÓRIO git vive, e as duas escolhas são ortogonais.

• Onde: src/db/schema/iam.ts (projects), src/infrastructure/filesystem/project-workspaces-root.ts (projectScopeRoot), src/domain/iam/project.entity.ts, src/application/use-cases/git/read-project-code.use-case.ts (portaoDoContainer), apps/web/src/routes/ProjectCodeTab.tsx, apps/engine/lib/engine/projects/project.ex, apps/engine/lib/engine/actions/workspace.ex (workspace_dir/2), apps/engine/lib/engine/dev/worktree_cleanup.ex (que era a segunda derivação escrita à mão, e passou a usar a única), apps/web/src/routes/NewProjectWizard.tsx
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (describe "projectScopeRoot no modo local"), test/infrastructure/filesystem/fs-permissions-file-store.spec.ts (o permissions.json na pasta do usuário), test/application/use-cases/iam/create-project-modo-de-workspace.spec.ts, test/application/use-cases/git/read-project-code.use-case.spec.ts (projeto Local não passa pelo portão), test/interfaces/http/iam/project-dto-modo-de-workspace.spec.ts (o modo é congelado: PATCH não o muda), apps/web/src/routes/ProjectCodeTab.test.tsx (a tela também dispensa o gate), apps/engine/test/engine/actions/workspace_test.exs (describe "workspace_dir/2 com o localizador já resolvido"), apps/web/src/routes/NewProjectWizard.test.tsx
• Decisão arquitetural: ADR 0072
• Origem: pedido do usuário (decisão dele, com a variante de caminho livre escolhida explicitamente)

RN-170 — Caminho Local é validado na CRIAÇÃO, e a recusa ensina

REVISADA pela RN-422 (ADR 0104): a validação de criação passou a DIVERGIR por modo — mounted (o local renomeado) continua tocando disco como descrito aqui, runner valida só o LÉXICO, sem I/O — o resto desta entrada é histórico, fiel ao que valia até a revisão.

Criar um projeto no modo local com um caminho que a api não alcança produz um projeto que trava depois — na primeira ferramenta do primeiro agente, longe da tela onde a decisão foi tomada. Por isso a criação recusa com 400, e a mensagem diz o que falta fazer.

O caminho precisa ser:

1. absoluto, sem .. nem . em nenhum segmento (o caminho gravado é o caminho que se lê; /srv/app/../../etc é /etc e não parece);
2. existente e uma pasta dentro do container da api;
3. gravável pelo processo (access(W_OK|X_OK)) — as imagens rodam non-root (ADR 0024), e pasta do host com outro dono chega montada como somente leitura na prática;
4. fora da raiz e das pastas de sistema (/, /etc, /usr, /var, /data… e tudo abaixo delas): a raiz do projeto é o escopo que AUTORIZA o terminal do agente (ADR 0055), e um projeto com raiz em /etc transforma "o agente escreve no projeto dele" em "o agente reescreve o container";
5. sem sobreposição com o checkout do Brabo, nos DOIS sentidos — a pasta que CONTÉM o monorepo e a pasta DENTRO dele. O segundo caso é o problema que o ADR 0055 relata acontecendo de verdade.

O caminho gravado é o normalizado, não a string crua: validar uma string e gravar outra é como a validação deixa de valer no dia seguinte. workspacePath enviado junto com workspace_mode: container é RECUSADO, não ignorado — campo descartado em silêncio vira "mas eu configurei".

A parte LÉXICA (itens 1, 4 e 5) roda também na leitura, a cada derivação de projectScopeRoot: o único jeito de burlar a criação é escrever direto no banco, e o que se ganha ali é escopo de terminal em /. A parte de DISCO (itens 2 e 3) roda só na criação, onde o usuário ainda pode corrigir.

A recusa por pasta ausente traz a instrução de montagem — o arquivo, os dois serviços e a linha (- <caminho>:<caminho>), com o ponteiro para o runbook. Montar só na api produz um projeto que a api aceita e o engine não enxerga: ela valida o que ela vê, e não tem como saber o que está montado no outro container.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts (validarCaminhoDeWorkspaceLocal, CaminhoLocalInvalidoError), src/application/use-cases/iam/create-project.use-case.ts (caminhoValidado), src/interfaces/http/iam/dto/create-project.dto.ts, apps/web/src/lib/wizard.ts (caminhoLocalParecePlausivel)
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (describe "validarCaminhoDeWorkspaceLocal"), test/application/use-cases/iam/create-project-modo-de-workspace.spec.ts (describe "a criação RECUSA o caminho que travaria depois"), apps/web/src/lib/wizard.test.ts, apps/web/src/routes/NewProjectWizard.test.tsx
• Decisão arquitetural: ADR 0072
• Origem: guarda exigida pela variante de caminho livre (ADR 0072)

RN-186 — provider é dimensão do relatório do owner, e só dele

sumGroupedBy aceita provider como dimensão, e GET /workspaces/:id/spend-report devolve a lista porProvider ao lado de modelo, projeto, ator e dia. O ADR 0063 tinha deixado o eixo de fora; o ADR 0076 o devolveu sem revogar o argumento: quebrar gasto por provider continua sendo quebrar por CREDENCIAL, e por isso o eixo mora numa rota que já exige owner (RN-060) — a mesma régua de credential-spend, que segue respondendo a pergunta da FATURA (por mês, com o vínculo à chave que existe hoje).

GET /projects/:id/spend/me não ganhou nada. A assimetria é o desenho: as duas respostas continuam não sendo recorte uma da outra (RN-101).

A dimensão model não mudou: dois providers servindo o mesmo nome de modelo continuam numa linha só. Quem quer a quebra por credencial tem a lista própria, e cruzar as duas dimensões multiplicaria as linhas do ranking sem responder pergunta que as duas listas separadas já não respondam.

• Onde: src/application/ports/token-usage-repository.port.ts:150 (SpendDimension), src/infrastructure/persistence/drizzle/token-usage.repository.ts:255 (o GROUP BY), src/application/use-cases/llm/get-workspace-spend-report.use-case.ts:112, src/interfaces/http/llm/spend.controller.ts:56
• Teste: test/application/use-cases/llm/spend-audiencias.use-case.spec.ts ("quebra por PROVIDER, e o mesmo nome de modelo em dois providers segue UMA linha")
• Origem: ADR 0076

RN-187 — A visão do membro não alcança provider, e quem garante é o TIPO

Enquanto o eixo não existia, o que continha a visão do membro era a ausência de argumento a passar. Com o eixo de volta, a contenção passou a ser da assinatura: sumGroupedBy tem duas sobrecargas, e a que aceita um escopo com actor — o da audiência do membro, e o único que ele tem — só recebe SpendDimensionDoAtor, que é Exclude<SpendDimension, 'provider'>. sumGroupedBy('provider', escopoComAtor) não compila.

Nem o repositório nem o caso de uso têm if sobre essa combinação, de propósito: uma checagem em tempo de execução daria a impressão de que a garantia é dinâmica, quando quem a sustenta é o compilador — e um if é o tipo de coisa que a próxima refatoração remove sem que nenhum teste fique vermelho.

A barreira é dupla e as duas metades são independentes: a rota do membro também não tem parâmetro de dimensão (só projectId e dias), então uma query inventada como ?dimensao=provider é descartada pelo Nest antes de chegar ao handler.

Exclude em vez de uma segunda lista escrita à mão é deliberado: dimensão nova nasce alcançável pelas duas audiências, e tirá-la do alcance do membro vira ato explícito neste ponto — nunca um esquecimento em outro arquivo.

• Onde: src/application/ports/token-usage-repository.port.ts:121 (as duas sobrecargas), :147 (SpendDimensionDoAtor), :163/:173 (os dois escopos), src/application/use-cases/llm/get-my-spend.use-case.ts:73, src/interfaces/http/llm/spend.controller.ts:98
• Teste: test/application/use-cases/llm/spend-audiencias.use-case.spec.ts ("não compila pedir provider com escopo de ator" — um @ts-expect-error que o tsc reprova como diretiva NÃO USADA se a barreira cair; e "só pede as dimensões session e day"), test/interfaces/spend.controller.spec.ts (a rota do membro aceita dias e mais nada)
• Origem: ADR 0076

RN-188 — Pessoa e agente são partição da lista por ator, sem consulta a mais

O relatório do owner traz porOwner (linhas de actor_kind = 'user') e porAgente (actor_kind = 'agent') além de porAtor, que continua inteira. Os dois blocos são derivados de porAtor no caso de uso — actorKind já vem na linha desde a FASE 22 —, e não duas consultas com where actor_kind. O motivo é medido: o ADR 0063 mostrou que o custo destas consultas cresce com o tamanho de token_usage e não com o do pedido, então varrer a janela duas vezes a mais para separar o que já está separado em memória seria caro pelo motivo errado.

actor_kind que não seja pessoa nem agente (hoje, system) não entra em nenhum dos dois blocos e continua visível em porAtor e no total. Abrir um terceiro bloco para ele diria que o produto tem uma audiência que ele não tem.

O rótulo "Por owner" é do handoff de design e vale pela RN-058 — é a chave do owner que todas essas linhas gastam. Quem é o dono do workspace continua sendo o campo ownerId, não o actorKind de cada linha.

• Onde: src/application/use-cases/llm/get-workspace-spend-report.use-case.ts:120
• Teste: test/application/use-cases/llm/spend-audiencias.use-case.spec.ts ("separa PESSOA de AGENTE em dois blocos, sem perder a lista por ator")
• Origem: ADR 0076

RN-189 — O embedding devolve um vetor por entrada, ou um erro

embed é uma operação em LOTE: recebe N textos e devolve N vetores, na mesma ordem. A ordem é o único vínculo entre entrada e vetor, e é por isso que uma resposta mais curta não serve — o i-ésimo vetor acabaria pertencendo a outra frase, e o índice erraria em silêncio, com o sintoma aparecendo na BUSCA, semanas depois e longe da causa.

Assim, o contrato recusa, em vez de degradar, três coisas: um lote incompleto, um vetor vazio e dimensões diferentes na mesma resposta. Uma lista de entradas vazia também é recusada antes de sair pela rede — responder [] a ela faria o chamador gravar um índice vazio achando que indexou algo.

O resultado traz quatro campos, e cada um responde a uma pergunta que já custou caro em outro lugar do produto: dimensions é conferido contra o que VOLTOU (nunca copiado do catálogo); model é o que o provider disse ter usado, porque um alias resolve para uma versão datada e é esse nome que vai para o metering, pela mesma razão do preço congelado (RN-044); e inputTokens vem com estimated, preservando a distinção "o provider disse zero" × "o provider não disse nada" da RN-041.

O erro é lançado, normalizado por code, em vez de virar um chunk como no chat. A razão do chunk é preservar o gasto de um turno em andamento; aqui não há nada a preservar — ou o provider devolveu os vetores e cobrou, ou não devolveu e não cobrou. É a mesma escolha do listModels, e a taxonomia é a mesma: nenhum LLMErrorCode novo.

• Onde: src/application/ports/llm-provider.port.ts:61, src/infrastructure/llm/embedding-result.ts:26
• Teste: test/contract/llm-provider.contract.ts (cinco casos, rodados contra todo provider que declara a capability)
• Origem: ADR 0075

RN-190 — O embedding tem uma capability em duas camadas, e a do modelo é exclusão

Como no tool calling (RN-040), a capability tem duas camadas: o PROVIDER (capabilities.embeddings, o teto) e o MODELO (supportsEmbeddings na linha do catálogo). A diferença entre os dois casos é exatamente o que a regra existe para afirmar:

• tool calling é um gradiente — um modelo que não pede ferramentas ainda conversa, e por isso só o binding de agente é recusado;
• embedding é exclusão — o nomic-embed-text não responde a uma pergunta e o llama3.2 não devolve um vetor. São conjuntos disjuntos, e o daemon do Ollama prova isso respondendo 501 ("This server does not support embeddings") a um pedido de embedding com um modelo de chat.

assertCanEmbed confere os dois na ordem que falha melhor: primeiro o provider, porque trocar de modelo não conserta um provider que não faz embedding. Um modelo sem declaração também é recusado, com mensagem diferente — ausência significa "o provider não disse" (ADR 0041), nunca permissão, e a ação certa para quem lê é sincronizar o catálogo em vez de trocar de modelo. Deduzir a capability pelo NOME do modelo é proibido: seria um palpite vestido de dado.

• Onde: src/domain/llm/embedding-capability.ts:64, src/infrastructure/llm/ollama-provider.ts:319
• Teste: test/domain/llm/embedding-capability.spec.ts, test/infrastructure/llm/ollama-provider.spec.ts
• Origem: ADR 0075

RN-191 — embeddings: true exige execução, não documentação

A regra da casa (ADR 0041/ADR 0043) aplicada à nova capability: só o ollama declara true, e a prova é o POST /api/embed rodado contra o daemon real 0.32.1 com nomic-embed-text — duas entradas, dois vetores de 768 dimensões, prompt_eval_count: 10.

Os outros oito declaram false, por dois motivos distintos:

• falta de prova (sete): não há chave para eles no ambiente, e o único smoke test pago que já rodou (aceite) foi de CHAT — num hub, o embedding roteia para providers diferentes dos do chat, e a prova de um endpoint não é prova do outro;
• operação ausente (Anthropic): não há endpoint dedicado de embedding, e a documentação dele aponta para um terceiro, que é outro provider, com outra chave e outro dialeto.

O DIALETO da base OpenAI-compatível é provado à parte, com a suíte de contrato rodando uma segunda vez sobre ela com a capability ligada. É isso que torna barato virar um provider para true no dia em que a chave dele existir: muda uma linha do literal, e o parsing já está exercitado. Um provider que declara false e ainda expõe o método recusa a chamada antes de tocar a rede.

• Onde: src/infrastructure/llm/ollama-provider.ts:73, src/infrastructure/llm/openai-compatible-provider.ts:325
• Teste: test/contract/llm-provider.contract.ts, test/infrastructure/llm/openai-compatible-provider.contract.spec.ts, test/infrastructure/llm/ollama-provider.embeddings.smoke.spec.ts (manual, contra o daemon real)
• Origem: ADR 0075

RN-198 — Atividades agrupa por agente-base/instância REAL, nunca por contador inventado

A seção Atividades da sidebar é a mesma lógica de agrupamento de AgentTimelineTree.tsx/timeline-tree.ts (já usada na Visão geral do projeto), movida para um lugar novo — não reescrita. montarArvore já agrupa por evento.actor.id; a novidade é agruparPorInstancia (apps/web/src/lib/timeline-tree.ts), que decide quais ramos formam um grupo visual de dois níveis.

A "instância" não é um contador renumerado (-01/-02) — é o agent_id REAL que o produto já escreve: devAgentId/extraDevAgentId (src/application/use-cases/execution/activate-execution.use-case.ts:27-38) produzem dev-<modulo> e dev-<modulo>-2 (sufixo sempre exatamente -2, porque o teto é DOIS por módulo, RN-154). Um ramo só vira "instância extra" de outro se o agente-base (sem o sufixo) TAMBÉM tiver um ramo na mesma lista — senão ele é o próprio agente. Agente com uma instância abre direto nos eventos; com duas, revela um segundo nível, uma linha por instância, cada uma com sua própria contagem — reaproveitando getAgentLastSeenSeq/setAgentLastSeenSeq (read-state.ts) que já existia para o contador de novidade da árvore.

Escopo: só o projeto da ROTA ATUAL (pathname), não todos os projetos do workspace — agregar todos exigiria uma consulta de eventos POR projeto, a mesma classe de N+1 que a RN-090/091 fechou no dashboard. Reusa o MESMO par de hooks que AgentTimelineTree/SessionPage já usam (useActiveExecutionSession + useSessionEvents, mesma queryKey) — zero requisição nova quando as duas telas estão montadas juntas.

O que abre/fecha é persistido em brabo.sidebar.agents, com o formato do handoff adaptado aos ids reais: agenteBase (grupo aberto, ex.: dev-backend) ou ${agenteBase}/${instancia} (uma instância específica aberta, ex.: dev-backend/dev-backend-2).

• Onde: apps/web/src/lib/timeline-tree.ts (agruparPorInstancia, GrupoDeAgente), apps/web/src/routes/Shell.tsx:237-311 (GrupoDeAtividade, InstanciaDeAgente), apps/web/src/routes/Shell.tsx:376-399 (escopo e persistência)
• Teste: apps/web/src/lib/timeline-tree.test.ts (describe "agruparPorInstancia"), apps/web/src/lib/sidebar-state.test.ts
• Origem: PROGRAMA 28, Onda 1/frente B0 (achado, sem código) e Onda 2/frente B (implementação)

RN-213 — Alerta de custo é leitura de lastThresholdNotified, nunca recálculo

alertaDeOrcamento não reimplementa crossedThresholds (src/domain/llm/budget-threshold.ts): lê o campo que o backend já grava no momento em que uma chamada real cruza 70/90/100%, e só decide a cor (warning abaixo de 90, danger a partir de 90) e se o texto deve avisar bloqueio ativo (policy === 'block' && spentMicros >= limitMicros). Nenhuma regra de negócio nova — puramente apresentação de um dado que já existe.

• Onde: apps/web/src/lib/spend.ts (alertaDeOrcamento)
• Teste: apps/web/src/lib/spend.test.ts (describe "alertaDeOrcamento (RN-213)"); apps/web/src/routes/ProjectSpendTab.test.tsx (describe "o orçamento do projeto")

RN-219 — Os três escopos do índice de chunks são honestos, e mutuamente exclusivos por CHECK

O índice do Chat RAG cobre só três fontes de texto que o produto já sabe de onde vieram: docs, adr e session. Código-fonte e Pull Requests ficam de fora de propósito — indexá-los sem um watcher de reindexação a cada push faria o índice mentir sobre cobertura, a mesma classe de erro que o ADR 0042 já recusa para capability de modelo. session_id/source_path são mutuamente exclusivos por CHECK, não por convenção de aplicação, mesmo padrão de projects.workspace_mode/workspace_path (ADR 0072): scope = 'session' exige session_id e recusa source_path; docs/adr exigem source_path e recusam session_id. A trava fica no banco porque quem vai escrever esta tabela é um pipeline (Onda 4) que não necessariamente passa pelo mesmo caso de uso toda vez.

• Onde: src/db/schema/rag.ts (chunkScopeEnum e os dois CHECK da tabela chunks)
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts ("recusa chunk de docs sem source_path — o CHECK da migração 0045, não validação de aplicação")
• ADR: 0079

RN-220 — Vetor e busca léxica vivem na mesma linha, nunca em tabelas separadas

chunks.embedding (pgvector) e chunks.search_vector (tsvector) são colunas irmãs da MESMA tabela, não duas tabelas ligadas por chunk_id. Separar exigiria um JOIN em toda busca híbrida (Onda 4) e abriria espaço para as duas divergirem — um trecho com vetor mas sem entrada léxica, ou vice-versa — sem nenhum mecanismo do banco impedindo. Uma linha, uma fonte de verdade para as duas metades da busca.

• Onde: src/db/schema/rag.ts (tabela chunks)
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts (as três specs escrevem e leem as duas colunas na mesma linha)
• ADR: 0079

RN-221 — search_vector nunca é escrita pela aplicação — é coluna GENERATED

search_vector é GENERATED ALWAYS AS (to_tsvector('portuguese', content)) STORED. Nenhum caso de uso, repositório ou script escreve nela — o Postgres a mantém coerente com content por construção, pronta na mesma transação do INSERT, sem depender de nenhum provider de LLM responder (diferente de embedding, que só chega quando um pipeline de indexação existir).

• Onde: src/db/schema/rag.ts (coluna search_vector)
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts ("grava um chunk de docs com vetor e devolve o search_vector gerado pela GENERATED ALWAYS AS")
• ADR: 0079

RN-222 — A dimensão do vetor é documentada, não adivinhada, e embedding chega depois do chunk

chunks.embedding é vector(768) — a dimensão real do nomic-embed-text do Ollama, o único provider que hoje declara capabilities.embeddings: true (RN-191, ADR 0075). Um índice vetorial tem dimensão FIXA: trocar de modelo de embedding no futuro é migração nova, nunca parâmetro de runtime. A coluna é NULLABLE: esta tabela guarda o CHUNK (texto recortado), e o VETOR pode chegar depois via um pipeline de indexação assíncrono que ainda não existe (Onda 4) — sem isso, chunking teria que esperar embedding, misturando duas falhas de natureza diferente (parsing de documento contra chamada de rede a um provider) numa escrita atômica só.

• Onde: src/db/schema/rag.ts (coluna embedding)
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts ("grava um chunk de docs com vetor..." grava com embedding preenchido; as outras duas specs gravam sem ele, confirmando a nulabilidade)
• ADR: 0079; RN-191

RN-223 — O índice vetorial é HNSW, não IVFFlat, porque a tabela nasce vazia

IVFFlat precisa de linhas já carregadas para treinar as listas (lists) e fica ruim se construído sobre tabela vazia — que é exatamente o estado desta tabela ao nascer, sem pipeline de indexação ainda (Onda 4). HNSW constrói o grafo incrementalmente, inserção por inserção, sem etapa de treino — bom desde a primeira linha. vector_cosine_ops porque é a métrica que embeddings de texto geralmente esperam (o ranking de similaridade não deveria mudar com a magnitude do vetor).

• Onde: src/db/migrations/0045_shallow_randall.sql (chunks_embedding_idx)
• ADR: 0079

RN-225 — Migração que pode exigir privilégio de operador nasce em breaking/

Criar uma extensão exige que o role da aplicação tenha CREATEDB (ou que a extensão esteja marcada "trusted" pelo DBA). Localmente o role é superusuário, mas nada garante isso em produção — gerenciadores de Postgres administrado frequentemente não dão superusuário à aplicação. Se a migration falhar aí, é ação do OPERADOR antes do deploy (rodar CREATE EXTENSION vector; uma vez, como superusuário), não bug do produto — o critério do CLAUDE.md para nascer em breaking/ em vez de feature//bugfix/.

• Onde: branch breaking/tabela-de-chunks, src/db/migrations/0045_shallow_randall.sql (comentário que documenta a decisão dentro da própria migration)
• ADR: 0079

RN-226 — ChunkRepository cobre só escrita/leitura básica; createMany é operação de lote

O port só tem create, createMany, findById e listByProject — busca híbrida (vetor + léxico, pesos, limiar) é da Onda 4 (G2) e deliberadamente NÃO entra aqui: o port guarda dado, o caso de uso decide o que fazer com ele. createMany existe porque uma indexação recorta N trechos de um documento/sessão de uma vez, evitando N round-trips por documento indexado.

• Onde: src/application/ports/chunk-repository.port.ts, src/infrastructure/persistence/drizzle/chunk.repository.ts
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts ("createMany grava um lote e listByProject filtra por escopo, sem misturar docs e session")
• ADR: 0079

PROGRAMA 28 — Onda 4, frente G2: pipeline de indexação e busca híbrida do Chat RAG (RN-231..238, ADR 0080)

As RNs do auth first-party moram em Regras de negócio — Autenticação.

Saíram daqui por TAMANHO, não por assunto: junto com Custo elas eram metade de uma página de 640 KB. O conteúdo não mudou, e as âncoras #rn-NNN são as mesmas — o que mudou foi o arquivo que as hospeda.

Autenticação

RN-231 — ChunkRepository ganha DELETE e as duas metades da busca híbrida

O port da Onda 3 (RN-226) só cobria escrita/leitura básica. A Onda 4 acrescentou deleteByScope/deleteBySession (para reindexação idempotente por full rebuild — apagar e recriar, nunca UPDATE) e searchByVector/searchByLexicalQuery (as duas metades da busca híbrida, cada uma uma consulta independente, aproveitando o índice feito para ela — HNSW ou GIN). deleteByScope é tipado Exclude<ChunkScope, 'session'>: apagar session por projeto inteiro apagaria sessões que não estão sendo reindexadas agora, então sessão só apaga por deleteBySession.

• Onde: src/application/ports/chunk-repository.port.ts (linhas 105-146), src/infrastructure/persistence/drizzle/chunk.repository.ts
• Teste: test/infrastructure/persistence/chunk.repository.spec.ts — describes "Onda 4 (G2)" (delete por escopo/sessão, busca por vetor/léxico, caso feliz e vazio de cada um)
• ADR: 0080

RN-232 — Origem do texto indexado: docs/adr do repositório do PRÓPRIO projeto, session só de chat.message/agent.response

docs/adr são indexados via ReadProjectCodeUseCase — a mesma superfície da aba Code, com a mesma credencial do owner, o mesmo portão de container (RN-105) e a mesma checagem de caminho (RN-095) — nunca a documentação do Brabo enquanto produto. session indexa só dois tipos de evento (chat.message, agent.response); o resto do event log (tool.call, agent.status, agent.error...) é mecanismo/falha, não conhecimento citável.

• Onde: src/application/use-cases/rag/index-project-docs.use-case.ts (linhas 16-17, 64), src/application/use-cases/rag/index-session.use-case.ts (linha 29, 45). Desde a AT-764, a leitura de cada .md usa o teto próprio da indexação, não o da aba Code (RN-1036)
• Teste: test/application/use-cases/rag/index-project-docs.use-case.spec.ts, test/application/use-cases/rag/index-session.use-case.spec.ts (casos felizes + "projeto sem docs/" + "evento sem payload.text é ignorado")
• ADR: 0080

RN-233 — Provider de embedding indisponível: grava sem vetor e declara a lacuna, nunca finge indexação completa

Quando ollama/nomic-embed-text não responde, RagEmbeddingService.embedMany não lança — devolve available: false e null por entrada pedida. O pipeline grava os chunks mesmo assim (embedding: null; search_vector é GENERATED ALWAYS AS e não depende de provider nenhum), e o relatório de indexação declara a lacuna (embedding: { available, embedded, skipped, reason }). A mesma degradação vale na busca: HybridSearchUseCase roda só com o sinal léxico e vectorAvailable: false avisa.

• Onde: src/application/use-cases/rag/rag-embedding.service.ts (linhas 53-58)
• Teste: test/application/use-cases/rag/rag-embedding.service.spec.ts — "CASO DE FALHA: provider sem a capability..." e "CASO DE FALHA: provider que lança no meio do lote..."; index-project-docs.use-case.spec.ts/ index-session.use-case.spec.ts — "CASO DE FALHA: provider de embedding indisponível grava os chunks SEM vetor..."; hybrid-search.use-case.spec.ts — "quando o embedding está indisponível, degrada para busca só léxica"
• ADR: 0080

RN-234 — Busca híbrida: duas consultas independentes, fusão por peso (0.6/0.4), limiar 0.2, e o contrato de citação

searchByVector/searchByLexicalQuery são consultas SEPARADAS (nunca um JOIN), fundidas em HybridSearchUseCase por soma ponderada (RAG_SEARCH_WEIGHT_VECTOR = 0.6, RAG_SEARCH_WEIGHT_LEXICAL = 0.4 — as escalas de cosseno e ts_rank normalizado não são comparáveis por natureza) e cortadas em RAG_SEARCH_SCORE_THRESHOLD = 0.2. Nenhum dos quatro números vem de calibração com dado real — são ponto de partida documentado. A citação (HybridSearchHit) expõe chunkId/content/scores separados (null, não zero, quando o sinal não achou o chunk)/origin como união discriminada por kind (file com sourcePath/headingPath, session com sessionId/eventId).

• Onde: src/application/use-cases/rag/hybrid-search.use-case.ts (linhas 44-113), src/domain/rag/rag-search-limits.ts (linhas 60-93), src/domain/rag/rag-citation.ts (linhas 12-71)
• Teste: test/application/use-cases/rag/hybrid-search.use-case.spec.ts (fusão/ordenação/limiar, query fora da faixa, degradação léxico-only, origin de sessão) e test/infrastructure/persistence/chunk.repository.spec.ts (as consultas SQL de fato, contra pgvector/tsvector real)
• ADR: 0080

RN-1046 — A busca híbrida devolve no máximo N trechos do mesmo arquivo

Depois da fusão e do limiar (RN-234) e antes do corte em limit, a busca mantém só os maxPerFile melhores trechos de cada arquivo (RAG_SEARCH_MAX_CHUNKS_PER_FILE, hoje 2), na ordem do score. Assim um documento grande e repetitivo (o business-rules.md agregado) não ocupa todas as citações e abafa o documento específico (um ADR). O melhor trecho de cada arquivo nunca é descartado, então o filtro só pode subir a posição do primeiro trecho de um arquivo, nunca baixá-la. Trecho sem arquivo (sessão) não entra na conta. O maxPerFile vigente vai congelado em rag_searches.pesos (RN-479), para a calibração não comparar rodadas com regras diferentes; linhas antigas não o têm. O seed do golden set aceita GOLDEN_SET_RAG_MAX_PER_FILE e, em caso perdido, imprime a posição do arquivo esperado entre os candidatos antes do corte.

• Onde: src/application/use-cases/rag/hybrid-search.use-case.ts (limitarPorArquivo), src/domain/rag/rag-search-limits.ts, src/domain/rag/rag-telemetry.ts, scripts/seed-golden-set-rag.ts
• Teste: test/application/use-cases/rag/hybrid-search.use-case.spec.ts
• ADR: 0080 (a decisão sobre diversidade fica no ADR 0272)

RN-235 — Chunking: 1200 caracteres, 150 de sobreposição, por parágrafo/heading

CHUNK_TARGET_CHARS = 1200 (~300 tokens em português), CHUNK_OVERLAP_CHARS = 150 (12,5%), com corte preferindo quebra de parágrafo, depois de palavra, dentro de uma janela de 200 caracteres. Markdown (docs/adr) é dividido por HEADING antes de ser recortado por tamanho, preservando headingPath. Números documentados como ponto de partida ajustável, não calibrados contra dado real de qualidade de recuperação (não existe, ainda, um corpo de perguntas reais rodado contra este índice).

• Onde: src/domain/rag/chunking.ts (linhas 30-31, 53 em diante)
• Teste: test/domain/rag/chunking.spec.ts (texto que cabe/não cabe, texto vazio, sobreposição real, texto patológico sem espaço, headings aninhados, markdown sem heading)
• ADR: 0080

RN-236 — Reindexação é sempre MANUAL, full rebuild idempotente

Não há watcher por push nem por fechamento de sessão. ReindexProjectUseCase roda docs/adr uma vez e uma IndexSessionUseCase por sessão do projeto, cada indexação apagando o escopo/sessão antes de recriar — rodar duas vezes seguidas não duplica. Disparado por POST /projects/:projectId/rag/reindex, role:maintainer.

• Onde: src/application/use-cases/rag/reindex-project.use-case.ts (linha 36)
• Teste: test/application/use-cases/rag/reindex-project.use-case.spec.ts (agrega docs+sessões, embeddingAvailable falso quando qualquer rodada falha, projeto inexistente)
• ADR: 0080

RN-237 — Cobertura do índice é contagem REAL, nunca "há N minutos" inventado

GetRagCoverageUseCase conta arquivos .md reais no repositório do projeto contra quantos têm chunk, e sessões do projeto contra quantas têm chunk. Não existe coluna de timestamp de indexação por escopo, e a resposta não inclui nenhum "reindexado há Xmin" — um número chutado mentiria (mesma régua do ADR 0042 para nota de modelo).

Desde a AT-764 (RN-1036), cada escopo docs/adr também traz filesCut: quantos desses arquivos têm chunk marcado metadata.sourceCut, isto é, foram lidos só até o teto de indexação. Um arquivo "indexado" que filesCut conta tem parte do texto FORA do índice, e a cobertura não o apresenta mais como inteiro.

• Onde: src/application/use-cases/rag/get-rag-coverage.use-case.ts (linha 47)
• Teste: test/application/use-cases/rag/get-rag-coverage.use-case.spec.ts
• ADR: 0080

RN-1036 — A indexação de docs nunca descarta em silêncio o conteúdo de um arquivo

A indexação de docs lê cada .md até o teto próprio de indexação (RAG_INDEX_FILE_MAX_BYTES, 4 MiB), separado do teto da aba Code (GIT_BLOB_MAX_BYTES, 512 KiB, RN-095), que não muda. Um arquivo cortado por esse teto, ou pulado por ser binário (\0 no conteúdo), aparece:

• em cutFiles no relatório de indexação (POST .../rag/reindex), com { path, bytes, reason }: bytes é o tamanho do arquivo no repositório e reason é too_large (lido só até o teto) ou binary (pulado, sem chunk);
• no Logger.warn da api, com o caminho e os bytes;
• no metadado dos chunks de um arquivo cortado (metadata.sourceCut: true);
• na cobertura (RN-237), em filesCut de cada escopo.

O que passa do teto é cortado no teto, nunca descartado em silêncio. O insert dos chunks é fatiado (RAG_INSERT_BATCH_SIZE, 1000 por comando) porque o Postgres aceita 65 535 parâmetros por comando e um arquivo de 4 MiB já gera ~5 400 chunks. O provider do GitHub lê o conteúdo em formato raw: no formato JSON a API devolve content vazio para arquivo de 1 a 100 MB, e o arquivo sumiria sem aviso.

• Onde: src/application/use-cases/rag/index-project-docs.use-case.ts, src/application/use-cases/git/read-project-code.use-case.ts (file(..., maxBytes)), src/application/use-cases/rag/get-rag-coverage.use-case.ts, src/domain/rag/rag-search-limits.ts, src/infrastructure/persistence/drizzle/chunk.repository.ts, src/infrastructure/git/github-provider.ts, src/interfaces/http/rag/dto/rag.response.dto.ts.
• Teste: test/application/use-cases/rag/index-project-docs.use-case.spec.ts (600 KiB indexado até o fim; acima de 4 MiB em cutFiles com sourceCut; .md com \0 pulado e declarado), test/application/use-cases/git/read-project-code.use-case.spec.ts (default de 512 KiB intacto), test/application/use-cases/rag/get-rag-coverage.use-case.spec.ts (filesCut), test/infrastructure/persistence/chunk.repository.spec.ts (9 500 chunks em createMany), test/infrastructure/git/github-provider.contract.spec.ts (arquivo acima de 1 MB em raw).
• ADR: 0269.
• Origem: AT-764 (EP-033), decisão do dono de 06/11/2026 (teto de 4 MiB); rodada 223, lane A.

RN-238 — As três rotas HTTP do RAG dividem papel por quem MUDA o que o produto gasta

POST .../rag/search e GET .../rag/coverage são role:viewer (leitura pura); POST .../rag/reindex é role:maintainer, porque dispara N chamadas ao repositório do projeto e ao provider de embedding — mesma régua "muda o que o produto gasta sem perguntar" do teto de paralelismo de área (RN-083).

• Onde: src/interfaces/http/rag/rag.controller.ts (linhas 50, 57, 81, 98), docs/security-surface.md
• Teste: test/interfaces/route-surface.spec.ts (classificação de papel, tags fechadas, metadados OpenAPI das três rotas)
• ADR: 0080

PROGRAMA 28 — Onda 4, frente E2: virtualização de linha e minimapa na aba Code (RN-239..242)

RN-243 — O ciclo de vida do container é TABELA, e nenhuma linha dela chama Docker

project_containers (migração 0046) grava o ESTADO mutável do container de um projeto — distinto de artifact.project_image no event log (ADR 0065), que é a DECISÃO imutável do Arquiteto. Nem RegistrarTransicaoDeContainerUseCase nem ObterCicloDeVidaDoContainerUseCase chamam um daemon Docker: nenhum serviço do produto monta /var/run/docker.sock nem roda privileged hoje, e conceder isso é decisão de segurança fora do escopo desta regra. Um orquestrador real, quando existir, CONSOME esta tabela depois de agir de verdade — nunca o contrário.

• Onde: src/domain/containers/container-lifecycle.ts, src/application/use-cases/containers/registrar-transicao-de-container.use-case.ts
• Teste: test/application/use-cases/containers/ciclo-de-vida-do-container.use-case.spec.ts
• ADR: 0081

RN-244 — A máquina de estados do container: só removed sai reprovisionando

provisioning → running ⇄ stopped, com failed alcançável de provisioning/running/stopped, e removed → provisioning como a ÚNICA saída de removed — nenhum estado é terminal de verdade, porque um projeto pode reprovisionar com uma imagem revisada pelo Arquiteto. Transição fora da tabela lança InvalidContainerTransitionError, que o caso de uso traduz para 409 — mesmo formato de session-state-machine.ts e pr-gate-state-machine.ts.

• Onde: src/domain/containers/container-lifecycle.ts (ALLOWED_TRANSITIONS)
• Teste: test/domain/containers/container-lifecycle.spec.ts
• ADR: 0081

RN-245 — A primeira transição exige a imagem já decidida, e CONGELA versão e recursos

Não existe linha até a primeira chamada com to: 'provisioning', e ela só é aceita se o Arquiteto já tiver decidido a imagem do projeto (RN-105) — o mesmo portão que já protege a aba Code, aplicado na origem em vez de duplicado. A versão de artifact.project_image e os recursos declarados naquele instante são CONGELADOS na linha nova (image_version, cpus, memory_mb, pids_limit): uma revisão posterior do artefato não muda retroativamente o que uma instância já provisionada promete.

• Onde: src/application/use-cases/containers/registrar-transicao-de-container.use-case.ts
• Teste: test/application/use-cases/containers/ciclo-de-vida-do-container.use-case.spec.ts — "a primeira transição (provisioning) cria a linha…" e "sem decisão de imagem do Arquiteto, não há o que provisionar"
• ADR: 0081

RN-246 — Projeto em modo local não tem ciclo de vida de container

Um projeto com workspace_mode: 'local' (ADR 0072, RN-169) roda no container do AGENTE de sempre — não sobe container próprio. Pedir qualquer transição para um projeto local é recusado com 400 ANTES de tocar a tabela, na origem, não filtrado depois na UI.

• Onde: src/application/use-cases/containers/registrar-transicao-de-container.use-case.ts
• Teste: test/application/use-cases/containers/ciclo-de-vida-do-container.use-case.spec.ts — "projeto em modo local não tem ciclo de vida de container (ADR 0072)"
• ADR: 0081

RN-247 — Uma linha por projeto: project_id é único

Só existe UM container vigente por projeto de cada vez — o mesmo desenho de dev_agent_states no engine (ADR 0045). A constraint única mora no BANCO (project_containers_project_id_unique), não só no caso de uso: create chamado duas vezes para o mesmo projeto falha na escrita, nunca produz uma segunda linha silenciosa.

• Onde: src/db/migrations/0046_chilly_forgotten_one.sql
• Teste: test/infrastructure/persistence/drizzle/container.repository.spec.ts — "só uma linha por projeto — create duplicado viola a constraint única"
• ADR: 0081

RN-248 — Teto de recursos DECLARADO, não aplicado — o campo existe para quando houver orquestrador

cpus/memory_mb/pids_limit gravam o que o artefato do Arquiteto prometia no momento do provisionamento, mas nenhum processo hoje faz o kernel respeitar esse teto — não há orquestrador chamando docker run --cpus … --memory … --pids-limit …. O campo nasce mesmo assim porque adiar a coluna para quando o orquestrador existir obrigaria uma migration de correção no dia em que ele chegasse; declarar sem aplicar é honesto enquanto a tabela não mentir sobre APLICAR (nenhuma tela ou resposta de API hoje afirma "o container está limitado a X" — só "a intenção registrada era X").

• Onde: src/db/schema/containers.ts (projectContainers)
• Teste: test/infrastructure/persistence/drizzle/container.repository.spec.ts — "create nasce em provisioning, com a versão e os recursos passados"
• ADR: 0081

PROGRAMA 28 — Onda 5, frente G3: a tela do Chat RAG (RN-252..254, ADR 0082)

RN-267 — GET /projects/:projectId/container/lifecycle é a primeira exposição HTTP do ciclo de vida do container

O ADR 0081 criou ObterCicloDeVidaDoContainerUseCase sem rota, de propósito ("expor uma seria adivinhar contrato" antes de existir um consumidor real). A Onda 5/F2 é esse consumidor (RN-268), e a rota nasce como espelho fiel do caso de uso: null quando o projeto nunca foi provisionado — o resultado esperado hoje, porque nenhum orquestrador real transiciona project_containers em produção (RegistrarTransicaoDeContainerUseCase não tem chamador nenhum fora de teste) — ou o estado registrado (status/imageVersion/resources/failureReason/statusChangedAt), NUNCA confirmado contra um daemon Docker, porque não existe cliente Docker no produto (RN-243). Mesma permissão da rota irmã (GET /projects/:projectId/container): viewer, GET, sem @Post — quem transicionaria o ciclo de vida é um orquestrador que ainda não existe.

• Onde: src/interfaces/http/containers/containers.controller.ts (cicloDeVida), src/interfaces/http/containers/dto/containers.response.dto.ts (CicloDeVidaDoContainerResponseDto)
• Teste: test/interfaces/http/containers/containers.controller.spec.ts
• Borda: id/projectId/containerId da linha interna NÃO vazam na resposta — o contrato HTTP não é a mesma forma que a linha do banco.
• ADR: 0083 (revisa o 0081)

RN-272 — O callback do login social decide em ORDEM: identidade conhecida, depois vínculo por e-mail, depois conta nova

SocialLoginCallbackUseCase resolve a identidade do provider em três passos, nesta ordem, e nunca fora dela: (provider, providerUserId) já vinculada → login direto; sem vínculo mas o e-mail bate com uma conta existente → decide por RN-274/RN-275; nenhuma das duas → provisiona conta nova (RN-278). A chave de busca do primeiro passo é sempre providerUserId, nunca e-mail — evita que trocar o e-mail no provider "perca" o vínculo.

• Onde: src/application/use-cases/auth/social-login-callback.use-case.ts
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — os sete casos de SocialLoginCallbackUseCase
• ADR: 0084

RN-273 — O state do login social tem propósito PRÓPRIO, mesmo assinado pela mesma chave do fluxo de conexão de git

domain/auth/social-oauth-state.ts assina com GIT_OAUTH_STATE_SECRET — a MESMA chave HMAC do state de "conectar git ao projeto X" (domain/git/oauth-state.ts) — mas o payload carrega purpose: 'social_login', checado ANTES de qualquer outro campo. Um state do fluxo de conexão de git, mesmo com assinatura válida, é recusado aqui: sem o discriminante, aceitá-lo equivaleria a logar como o userId de quem iniciou aquela conexão — escalação de privilégio.

• Onde: src/domain/auth/social-oauth-state.ts
• Teste: test/domain/auth/social-oauth-state.spec.ts — "RN-273: rejeita um state do fluxo de CONEXÃO de git, mesma chave"
• ADR: 0084

RN-274 — Vincular identidade social a conta existente exige e-mail VERIFICADO pelo provider

Quando o e-mail devolvido pelo provider bate com uma conta já cadastrada, o vínculo só acontece se o provider marca aquele e-mail como verificado (emailVerified: true) — GitHub via GET /user/emails, GitLab via confirmed_at. Um e-mail digitado mas não verificado não é prova de identidade: qualquer um pode registrar um e-mail alheio num provider OAuth. Aceitar o vínculo sem essa checagem abriria account takeover — quem já tem alguem@empresa.com na Brabo não pediu para um GitHub alheio, com aquele endereço só DIGITADO, herdar a conta. A recusa é 403, e nenhum vínculo é gravado.

• Onde: src/application/use-cases/auth/social-login-callback.use-case.ts (vincularAContaExistente)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "RECUSA vincular quando o e-mail bate mas NÃO está verificado pelo provider"
• ADR: 0084

RN-275 — Provisionar conta NOVA não exige e-mail verificado — só vincular a uma existente exige

A verificação de e-mail da RN-274 protege uma conta que já existe; quando não há conta correspondente, não há nada a proteger, só uma conta nova a nascer. Exigir e-mail verificado nesse caso encareceria o caminho comum (a maioria dos usuários de GitHub tem e-mail verificado, mas nem todos, e recusar o login por isso seria atrito sem ganho de segurança correspondente) sem reduzir risco nenhum — o pior caso é uma conta nova com um e-mail não comprovado, o mesmo risco que o registro por senha já aceita implicitamente até o clique no link de verificação.

• Onde: src/application/use-cases/auth/social-login-callback.use-case.ts (provisionarContaNova)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "provisiona conta nova mesmo com e-mail NÃO verificado"
• ADR: 0084

RN-276 — providerUserId, nunca e-mail ou login, é a chave de identidade social

social_identities tem índice único em (provider, provider_user_id) — o id NUMÉRICO e estável do provider. E-mail e login (username) podem mudar de dono ou de valor no provider sem aviso; usá-los como chave faria uma troca de e-mail no GitHub "perder" o vínculo de quem já tinha conta, ou pior, herdar silenciosamente o vínculo de outra pessoa que reusou aquele endereço depois.

• Onde: src/db/migrations/0047_complete_hannibal_king.sql, src/application/ports/social-identity-repository.port.ts
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "identidade já conhecida: login direto, sem criar segunda linha"
• ADR: 0084

RN-277 — Login social pede escopo MÍNIMO, nunca o de conexão de repositório

buildLoginAuthorizeUrl pede read:user user:email (GitHub) e read_user (GitLab) — nunca o repo/api que o fluxo de CONEXÃO de git pede. Entrar na conta não deveria conceder acesso a repositório nenhum; os dois fluxos reusam o MESMO app OAuth (RN-281) mas pedem autorizações diferentes, decididas na hora da autorização, não na configuração do app.

• Onde: src/infrastructure/git/github-oauth-client.ts, src/infrastructure/git/gitlab-oauth-client.ts (buildLoginAuthorizeUrl)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "StartSocialLoginUseCase › caminho feliz"
• ADR: 0084

RN-278 — Conta provisionada por login social nasce SEM senha — mesmo estado "pendente" da migração do Keycloak

Provisionar por login social grava uma linha em users e NENHUMA em auth_credentials — o mesmo par que a migração do Keycloak já deixava para "conta sem senha ainda" (ver RN-032 e migracao-keycloak.spec.ts). LoginUseCase e ResetPasswordUseCase já tratam esse estado; não foi necessário um segundo mecanismo de "senha pendente" para o login social.

• Onde: src/application/ports/auth-credential-repository.port.ts (criarUsuarioSemCredencial), src/infrastructure/persistence/drizzle/auth-credential.repository.ts
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "caminho feliz: provisiona um usuário NOVO, sem senha (RN-278)"
• ADR: 0084

RN-279 — Vincular por e-mail verificado também verifica o e-mail da conta existente

Quando uma conta registrada por senha (e nunca verificada) é vinculada a uma identidade social cujo e-mail o provider marca como verificado, a conta ganha emailVerifiedAt preenchido como efeito colateral. O provider acabou de provar, por um caminho independente, exatamente o que o clique no link de verificação provaria — não faz sentido a conta continuar bloqueada do login por senha (RN-032) depois de provar posse do e-mail por outro caminho igualmente forte.

• Onde: src/application/use-cases/auth/social-login-callback.use-case.ts (vincularAContaExistente)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "vincula a conta existente (…) e marca o e-mail dela como verificado (RN-274/279)"
• ADR: 0084

RN-280 — Login social recusa conta DESABILITADA, mesma régua do login por senha

Identidade social vinculada a uma conta com auth_credentials.disabled_at preenchido é recusada com 403, tanto no login direto (identidade já conhecida) quanto na tentativa de vincular. Desabilitar uma conta não pode ser contornado trocando de método de entrada.

• Onde: src/application/use-cases/auth/social-login-callback.use-case.ts (entrarComIdentidadeConhecida, vincularAContaExistente)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — "recusa login de identidade vinculada a conta DESABILITADA"
• ADR: 0084

RN-281 — O login social reusa o MESMO app OAuth da conexão de git — sem variável de ambiente nova

GITHUB_OAUTH_CLIENT_ID/_SECRET e GITLAB_OAUTH_CLIENT_ID/_SECRET continuam sendo os únicos client id/secret cadastrados. O que muda por fluxo é o redirect_uri (/auth/oauth/<provider>/callback contra /git/oauth/<provider>/callback) e o scope (RN-277) — os dois decididos em tempo de requisição. Ação do OPERADOR continua necessária (cadastrar o segundo callback URL no app de cada provider), documentada em .env.example — é essa exigência, não uma env var nova, que justifica o branch nascer breaking/.

• Onde: .env.example, src/application/use-cases/auth/start-social-login.use-case.ts
• Teste: manual (cadastro no app OAuth) — não há como testar automaticamente uma configuração externa ao produto
• ADR: 0084

RN-282 — O access token do login social nunca viaja na URL nem no corpo do callback

GET /auth/oauth/:provider/callback grava os cookies de sessão (definirCookiesDeSessao, a MESMA função do login por senha) e redireciona para WEB_ORIGIN/. O boot da web (restaurarSessao(), chamado em toda carga de página) troca o refresh recém-gravado por um access token — nenhum código novo do lado do cliente além dos botões e o alias de rota de erro.

• Onde: src/interfaces/http/auth/auth.controller.ts (oauthCallback)
• Teste: test/interfaces/route-surface.spec.ts — cobre a classificação pública e os metadados OpenAPI da rota; o fluxo completo de cookie→boot é E2E, fora do escopo de teste de unidade
• ADR: 0084

RN-283 — Falha do callback de login social não vaza o motivo na URL

Qualquer falha (state inválido, code rejeitado pelo provider, conta desabilitada, e-mail não verificado) redireciona para WEB_ORIGIN/login?oauth_error=1 — um único sinal genérico, nunca o motivo real. Mesmo padrão do callback de conexão de git (WEB_ORIGIN/git-error).

• Onde: src/interfaces/http/auth/auth.controller.ts (oauthCallback, bloco catch)
• Teste: test/application/use-cases/auth/social-login-callback.use-case.spec.ts — cobre os desfechos de falha que o controller mapeia para o mesmo redirect genérico
• ADR: 0084

Analytics e delivery-metricas: os dois papéis viram RELATÓRIO (RN-320..322, ADR 0089)

Decisão consciente do dono do produto de ANTECIPAR a construção dos papéis analytics e delivery-metricas (packages/contracts/fluxo.yml, status: proposto) sem esperar o gatilho orgânico que cada um já declarava. Os dois viram um SCRIPT só — scripts/analise-funil.ts — no mesmo formato de medir-execucao.ts (Fase 13b): NestFactory.createApplicationContext, --projeto <uuid> obrigatório, leitura pura via Drizzle, sem escrita nenhuma. A forma é a que o próprio fluxo já prescrevia: analytics é "absorvido por medicao" e delivery-metricas "nunca vira agente" — nenhum GenServer, nenhum agente de LLM.

RN-320 — analise-funil.ts é script, nunca agente — mesmo esqueleto de medir-execucao.ts

O comando é pnpm --filter api analise:funil -- --projeto <uuid> [--json]. Só lê proposed_actions (filtrado por actionType IN (git_commit, pr_open, git_merge)) e projects, nunca escreve. A guarda if (process.argv[1]?.endsWith('analise-funil.ts')) void main(); no fim do arquivo é a mesma de medir-execucao.ts: sem ela, importar o módulo no teste subiria o Nest inteiro e derrubaria o processo no process.exit do parser de argumentos.

• Onde: scripts/analise-funil.ts:64-73 (lerOpcoes), :256-319 (main), :390 (guarda de execução)
• Teste: test/scripts/analise-funil.spec.ts (só as funções puras — a parte que fala com o banco é exercitada por execução real, mesmo padrão de medir-execucao.spec.ts)
• ADR: 0089

RN-321 — O funil conta SESSÃO por etapa, só ação executed, e o lead time usa updated_at da execução

calcularFunil conta quantas sessões produziram pelo menos um git_commit, pr_open e git_merge com status: 'executed' — uma sessão com três commits entra uma vez só em cada etapa que alcançou, nunca três. A taxa de conversão de uma etapa é sessões-da-etapa / sessões-da-etapa-anterior, e é null (não 0, não Infinity) quando o denominador é zero — não há "conversão de" nada para medir. calcularLeadTimes usa updated_at da linha de proposed_actions, não created_at: é o instante em que ExecuteGitActionUseCase#record gravou o execution_result de verdade (updateExecutionResult bumba updatedAt), não quando a ação foi PROPOSTA — a mesma distinção que token_usage/preço congelado já fazem em outro contexto (RN-042). Merge cujo updated_at precede o do commit (duas levas na mesma sessão, ou dado incoerente) é descartado, nunca vira lead time negativo.

• Onde: scripts/analise-funil.ts:115-160 (calcularFunil), :170-193 (calcularLeadTimes)
• Teste: test/scripts/analise-funil.spec.ts (describe "calcularFunil", "calcularLeadTimes")
• ADR: 0089

RN-322 — Deployment frequency real filtra merge em branch PROTEGIDA; três métricas ficam DECLARADAS ausentes, nunca aproximadas

deploymentFrequencyPorDia só conta git_merge executed cujo executionResult.targetBranch está em PROTECTED_BRANCHES (src/domain/actions/protected-branches.ts) — merge numa branch de feature não é deploy. Cruza por REFERÊNCIA com o gate backmerge (config/gates.yml): a evidência dele é CI, em .release/gate.json, fora do alcance de um script que só lê o banco, então não há junção de dado, só o mesmo recorte de branch que o gate observa.

Três métricas saem do relatório com uma seção "Não medido, de propósito" em vez de um número aproximado:

1. Funil de produto completo (ideação → commit). sessions não tem storyId — RN-230 já declara a lacuna na aba Criativo. Fechá-la exige schema novo, fora do escopo desta frente (nenhuma migration).
2. Evidência de adoção por feature. Não é dado que falta coletar: o Brabo não instrumenta os projetos que ele CONSTRÓI, e não há caminho nenhum para essa telemetria existir hoje.
3. MTTR e change failure rate. Exigem sinal de INCIDENTE de produção real — a mesma dependência que packages/contracts/fluxo.yml já registra para secops-runtime/platform (status: proposto/planned, ativação sincronizada com DEPLOY_ENABLED).

• Onde: scripts/analise-funil.ts:220-247 (deploymentFrequencyPorDia), :372-386 (seção "Não medido" impressa)
• Teste: test/scripts/analise-funil.spec.ts (describe "deploymentFrequencyPorDia")
• ADR: 0089

O gate implementavel ativa — QA-estratégia como segundo momento do qa-lead (RN-340/341, ADR 0090)

RN-340 — O gate implementavel decide a story ANTES do dev agent escrever código

config/gates.yml declarava o gate implementavel (dono dev-lead) desde a FASE 14d com status: planned — nunca ativado. O ADR 0090 ativa: a ferramenta assess_implementability do Dev Lead propõe o parecer de implementabilidade de uma story (implementavel/inviavel + justificativa) como proposed_action, MESMO padrão de propose_execution_plan (RN-284) — três desfechos ({:ok, texto} | {:pending, action_id} | {:error, texto}), papel mínimo maintainer em decide.ts, e DELIBERADAMENTE fora do bloco de tetos absolutos (é decisão inicial, não ultrapassagem de teto).

O parecer depende do plano de teste, que é um PRÉ-REQUISITO, não um argumento. run_assessment/2 lê o artifact.plano_de_teste mais recente da story no HISTÓRICO da própria sessão do Dev Lead (emitido pela QA-estratégia, RN-341):

1. Sem plano ainda — dispara Engine.Gates.Dispatcher.run_qa_estrategia/3 (mesma indireção trocável em teste que run_qa/2/run_secops/2 já usam) e devolve {:error, texto} pedindo para tentar de novo em instantes. Erro de ferramenta é ENTRADA do laço, não fim de linha (RN-163): o Dev Lead tem teto de 14 iterações para tentar de novo. A janela de espera é aceita e declarada — a QA-estratégia roda em processo separado (qa-lead), e um run/2 síncrono não pode bloquear esperando o resultado sem acoplar os dois processos.
2. Com plano — monta o parecer com o plano de teste EMBUTIDO no payload (síntese e critérios executáveis), para o usuário decidir sem precisar abrir dois eventos, e propõe a ação.

Desde a RN-674 (ADR 0192) os dois passos acima NÃO valem mais. O plano de teste nasce DEPOIS da entrega do dev e alimenta o qa-verificada; run_assessment/2 não lê nem dispara plano, propõe o parecer na PRIMEIRA chamada, sobre a história e o module_map que o Dev Lead já tem no contexto, e o payload perdeu planoDeTeste/criteriosExecutaveis. Dispatcher.run_qa_estrategia/3 saiu. O resto desta regra (proposta, três desfechos, papel mínimo, fora dos tetos absolutos) segue igual.

• Onde: apps/engine/lib/engine/agents/dev_lead_tools.ex (run_assessment/2, spec_assess_implementability/0), dev_lead_server.ex (run_tool/3); src/domain/actions/decide.ts (assess_implementability); config/gates.yml (implementavel, status: active)
• Teste: apps/engine/test/engine/agents/dev_lead_tools_test.exs (describe "assess_implementability"), dev_lead_server_test.exs (describe "suspensão em aprovação" — os dois testes novos), test/domain/actions/decide.spec.ts (describe "parecer de implementabilidade do Dev Lead")
• Origem: ADR 0090

secops-runtime — relatório de abuso sobre rate_limit_hits (RN-375..377, ADR 0091)

Decisão consciente do dono do produto de antecipar o papel secops-runtime (packages/contracts/fluxo.yml, camada_seguranca), que nasceu proposto com o critério de separação "produção com tráfego real (pós DEPLOY_ENABLED + platform ativo)". Esse gatilho não disparou — não há tráfego de produção. O que existe hoje é rate_limit_hits (RateLimitGuard, ADR 0027): uma linha por request contado, gravada mesmo sob tráfego de dev/CI. secops-runtime entra como SCRIPT (pnpm --filter api relatorio:seguranca-runtime), não agente LLM nem GenServer — não há decisão a tomar, só dado a agregar.

RN-375 — O relatório declara a janela, nunca finge um histórico maior

DomainGaugesCollector.pruneRateLimit (src/infrastructure/observability/domain-gauges.collector.ts:177-186) apaga hits mais velhos que 2 × RATE_LIMIT_WINDOW_MS (240s com o default de 60s), a cada METRICS_GAUGE_INTERVAL_MS (15s por padrão) — a tabela nunca guarda mais que uns poucos minutos. relatorio-seguranca-runtime.ts imprime DUAS janelas, nunca uma só: a CONFIGURADA (o teto teórico da poda) e a OBSERVADA (o que os dados efetivamente cobrem, do primeiro ao último occurred_at lido). Quando as duas coincidem, o relatório diz explicitamente que é sinal de poda — hits mais antigos podem ter existido e já foram apagados — nunca "não houve mais hits que isso".

RN-376 — O ranking trabalha só com o que bucket_key guarda: balde e quando

RateLimitGuard.registrarEContar (src/interfaces/http/shared/rate-limit.guard.ts:150-170) grava só bucket_key (user:<uuid> ou ip:<endereço>) e occurred_at — NÃO há rota, método HTTP nem motivo do bloqueio. rankingDeBaldes e interpretarBalde (scripts/relatorio-seguranca-runtime.ts) classificam por esses dois campos e só eles; um bucket_key fora do formato user:/ip: cai em desconhecido em vez de estourar, para o script não quebrar se um RateLimitGuard futuro gravar outro formato. Pedir "ranking de IP por rota" seria inventar dimensão que a tabela nunca guardou.

O papel dbre vira dois scripts mecânicos (RN-400..403, ADR 0093)

RN-400 — O parecer de migração é análise ESTÁTICA de SQL, e ignora o padrão de risco quando ele só aparece em comentário

lintarConteudo (o núcleo puro de lint-migracao.ts) varre cada .sql de src/db/migrations/ linha a linha, sem depender de --projeto nem de banco — o risco que ele acha é de SCHEMA, não de carga, e por isso não depende de volume real de dados nenhum (o critério de separação que packages/contracts/fluxo.yml já declarava para o papel). Cinco padrões, cada um com a razão anexada ao achado: DROP TABLE/TRUNCATE (perda total, irreversível), DROP COLUMN (perda da coluna, irreversível), ALTER COLUMN ... TYPE/SET DATA TYPE (pode reescrever a tabela inteira) e ADD COLUMN ... NOT NULL sem DEFAULT (falha contra tabela não-vazia — o padrão que 0042_tough_captain_midlands.sql evitou conscientemente, com nullable-primeiro-depois-backfill-depois-SET NOT NULL).

Linha que começa com -- (comentário) é ignorada de propósito: este repositório explica em prosa, no próprio SQL, por que um padrão foi EVITADO — analisar o texto do comentário acharia o padrão exatamente na frase que descreve por que ele não foi usado.

• Onde: scripts/lint-migracao.ts (REGRAS, linha 75; lintarConteudo, linha 126)
• Teste: test/scripts/lint-migracao.spec.ts — cada padrão individualmente, combinação de vários na mesma migration, e "ignora o padrão de risco quando ele aparece só em COMENTÁRIO"
• ADR: 0093

Auditoria fluxo.yml × código — Onda 2: RN-160 no backend e delegação Dev Lead → dev (RN-404/405, ADR 0094)

Fecha os dois últimos achados da auditoria (seção D, docs/explanation/auditoria-fluxo-vs-codigo.md): B6 (RN-160 garantida só no cliente) e B1 (a delegação Dev Lead → dev-<modulo> declarada pelo ADR 0053 item 5 e nunca implementada).

RN-404 — "Confirmar arquitetura pronta" (RN-160) é revalidada no BACKEND, não só desabilitada na UI

RN-160 garantia a regra ("pelo menos 1 história promovida antes do handoff duplo Arquiteto→Dev Lead/Infra") só desabilitando o botão em SessionPage.tsx — uma chamada HTTP direta a POST /agents/arquiteto/handoff-infra, sem passar pela UI, ignorava a regra por completo. OfferInfraHandoffUseCase.execute agora consulta StoryRepository.findByProject(projectId) e recusa com BadRequestException quando NENHUMA história do projeto tem status !== 'draft' — a checagem vem ANTES de gravar architecture.readiness_confirmed e ANTES de qualquer chamada ao engine (offerInfraHandoff; o offerDevHandoff saiu na RN-672): uma recusa não pode deixar rastro de handoff meio-ofertado no event log, que é imutável. StoryRepository foi escolhido (e não ListBacklogUseCase) por ser mais leve — não precisa montar a árvore épico→história→tarefa para responder "existe alguma não-draft?".

• Onde: src/application/use-cases/agents/offer-infra-handoff.use-case.ts (linhas 27-34, a checagem; injeção de StoryRepository no construtor)
• Teste: test/application/use-cases/agents/offer-infra-handoff.use-case.spec.ts — zero história promovida recusa com ZERO chamada ao engine e ZERO evento gravado; com ao menos uma ready/in_progress/done, segue o fluxo normal
• ADR: 0094

Auditoria fluxo.yml × código — Onda 6 (última): o gate necessidade-validada (RN-406, ADR 0095)

RN-408 — MAIL_TRANSPORT=smtp deriva o boot pelo padrão da RN-114, sem o default público

Fecha o item de backlog "SMTP real no MailSender" (ADR 0096). resolverConfigSmtp() valida SMTP_HOST/SMTP_USER/SMTP_PASSWORD/ SMTP_FROM no MESMO formato da RN-114 — em produção (NODE_ENV === 'production'), cada um derruba o boot se estiver ausente, só com espaços, ou (no caso de SMTP_HOST) igual ao literal de exemplo publicado (comentado) em .env.example. SMTP_FROM tem uma checagem a mais: precisa casar "Nome <email@dominio>" ou só email@dominio. SMTP_PORT inválida (não numérica ou fora de 1–65535) também derruba o boot em produção.

A diferença para a RN-114 original é estrutural, não de rigor: os quatro segredos da RN-114 (AUTH_JWT_SECRET e companhia) TÊM um default de desenvolvimento público, e é a existência desse default que torna "não vazia" uma checagem insuficiente. Aqui não há default nenhum — SMTP_HOST fica em branco se ninguém setar —, então a régua inteira só é aplicada quando NODE_ENV=production E MAIL_TRANSPORT=smtp. Fora de produção, ou com o transporte em log (o default, inclusive em produção), nenhuma das cinco variáveis é exigida: enviar e-mail de verdade é opt-in do operador, e sem esse opt-in explícito o comportamento continua sendo o log-only de sempre — inclusive em produção, para quem já roda o produto hoje não quebrar ao atualizar.

A validação roda dentro do construtor de SmtpMailSender, exercitado pelo useFactory de AuthUseCasesModule na montagem do grafo de providers do Nest (NestFactory.create()) — não por uma chamada eager em main.ts, como os quatro segredos da RN-114 original. A diferença é deliberada: aqueles quatro protegem caminho que QUALQUER requisição pode exercitar a qualquer momento, então falhar antes de subir importa. SmtpMailSender só é instanciado quando o operador optou por smtp, e AuthUseCasesModule é importado incondicionalmente (via AuthHttpModule), então a validação ainda acontece no boot — mesmo desenho que CREDENTIALS_MASTER_KEY já usa (validada no construtor de EnvelopeEncryptionService, exercitado pela mesma montagem de grafo).

• Onde: src/infrastructure/mail/smtp-config.ts (resolverConfigSmtp, resolverModoDeTransporte), src/infrastructure/mail/smtp-mail-sender.ts (SmtpMailSender, chama resolverConfigSmtp() no construtor), src/application/use-cases/auth/auth-use-cases.module.ts (useFactory do MailSender)
• Teste: test/infrastructure/mail/smtp-config.spec.ts (mesmo padrão de auth-key-material.spec.ts/service-token.spec.ts), test/infrastructure/mail/smtp-mail-sender.spec.ts
• Origem: ADR 0096, estendendo o padrão da RN-114 (que por sua vez estende o ADR 0059)

Workspace pessoal automático no cadastro (RN-410)

Achado navegando o produto depois de um reset de banco: o botão "Novo projeto"/"+" do dashboard não fazia NADA, sem erro nenhum. A causa raiz estava em duas camadas. A visível: Dashboard.tsx só abre o NewProjectWizard quando useCurrentWorkspace() acha um workspace (list[0]?.workspace de GET /workspaces); sem nenhum, o clique não tem onde ir. A funda: RegisterUseCase criava usuário e credencial mas NUNCA um workspace, e o mesmo valia para SocialLoginCallbackUseCase no ramo que provisiona conta nova — TODO cadastro novo, por senha ou por login social, caía nessa parede. Só não tinha aparecido antes porque db/seed.ts sempre cria um workspace junto dos dados de demonstração, e nenhuma tela do produto chama createWorkspace (a rota, o caso de uso e o client HTTP existem — só não têm chamador nenhum na UI).

RN-410 — Toda conta NOVA nasce com um workspace pessoal, na MESMA transação da conta

RegisterUseCase (registro por e-mail/senha) e SocialLoginCallbackUseCase (provisionamento de conta nova via login social) criam o workspace e adicionam o usuário como owner — mesmo par create/addMember que CreateWorkspaceUseCase já usa — dentro da MESMA transação que já cria usuário e credencial. Não é uma segunda chamada ao use case: ele abre a PRÓPRIA transação, e o ponto é nunca existir usuário sem workspace se algo falhar no meio.

Nome e slug saem de UMA função pura, nomeESlugDoWorkspacePessoal(nome, email, userId) (src/domain/auth/personal-workspace.ts), reusada pelos dois pontos de criação — para a regra não divergir em dois arquivos, o mesmo motivo por trás de normalizarEmail/exigirSenhaValida morarem no domínio. O nome usa o nome informado (login social usa o login do provider), com o local-part do e-mail como fallback quando não há nome — nunca inventa nenhum dos dois. O slug é kebab-case do mesmo texto, SEMPRE sufixado com userId.slice(0, 8) (mesmo padrão de extraDevAgentId/workspaceDirName/rótulo de sessão): workspaces.slug é UNIQUE no banco e nada no produto faz retry-on-conflict, então dois cadastros com nome ou local-part iguais colidiriam sem o sufixo. Nome ou e-mail sem NENHUM caractere alfanumérico degradam para o literal workspace-<8 chars>, nunca para uma string vazia.

• Onde: src/domain/auth/personal-workspace.ts (nomeESlugDoWorkspacePessoal), src/application/use-cases/auth/register.use-case.ts, src/application/use-cases/auth/social-login-callback.use-case.ts (método provisionarContaNova)
• Teste: test/domain/auth/personal-workspace.spec.ts (nome com/sem nome, fallback para o local-part do e-mail, acento/maiúscula virando kebab-case ASCII, fallback workspace-<id> sem caractere alfanumérico nenhum, slug sempre único por conta do sufixo); test/application/use-cases/auth/register.use-case.spec.ts (conta nova ganha workspace com o usuário como owner, e-mail duplicado não cria um segundo); test/application/use-cases/auth/ social-login-callback.use-case.spec.ts (mesma prova no ramo que provisiona conta nova via login social)
• ADR: nenhum — correção de um caminho que devia ter feito isso desde o início, não decisão estrutural nova
• Origem: achado por uso real, navegando o produto — não item de backlog planejado

"N agentes online" no dashboard — status AO VIVO, nunca presença histórica (RN-409, ADR 0097)

RN-412 — dev.awaiting_gate/dev.awaiting_approval seguram a sessão; a janela efetiva de compactação é coerente com o transporte

Achado por USO real ("nas PRs sempre está estourando entity too large"), com dois defeitos que se encadeiam. O gate de QA/SecOps morria com 413 request entity too large → o dev agent que esperava o veredito ficava preso em dev.awaiting_gate indefinidamente → esse estado NÃO era um dos três que a RN-411 segurava → o heartbeat de 30s fechava a sessão por baixo → a aba Executores exigia sessão ativa (findActiveExecutionSession) e apagava o roster inteiro, mesmo com trabalho real pendurado.

A causa do 413 era da própria api do Brabo, nunca do provider de LLM — ver ADR 0098. Duas correções, as duas necessárias (uma sem a outra só adia o estouro):

1. src/main.ts nunca configurou limite de body do Express — valia o default de 100 KB, o gargalo mais estreito no sentido engine→api (o Phoenix aceita até 8 MB). POST /internal/sessions/:sessionId/llm-turn reenvia o histórico INTEIRO da conversa a cada iteração do ToolLoop, e 3-4 tool results de 32 KiB (teto individual da RN-150) já somavam mais que 100 KB. API_JSON_BODY_LIMIT (default 10mb) fecha essa ponta.
2. Engine.Harness.ContextManager.Default tinha dois defeitos que deixavam a compactação inalcançável antes do corpo estourar: estimate/1 contava só content, então mensagens de assistant com toolCalls pesados custavam ~zero tokens na estimativa; e a janela de compactação usava só context_window (128.000 tokens nos agentes de gate — qa_automacao_agent.ex, qa_performance_seguranca_agent.ex, qa_estrategia_agent.ex, appsec_agent.ex, dev_agent_server.ex), dando ~350 KB antes de compactar (threshold 0.7 × janela). A janela EFETIVA agora é min(context_window, teto_de_transporte) (transport_max_body_bytes, config única, default 8 MiB), e o corte sempre acontece em FRONTEIRA DE ITERAÇÃO do ToolLoop (group_by_iteration/1) — nunca separando uma mensagem assistant com toolCalls dos role: "tool" que a respondem, que quebraria o protocolo de tool-use do provider.

A régua de trabalho pendente (DEV_PENDING_TYPES, get-session-pending-work.use-case.ts) ganhou dois tipos: dev.awaiting_gate (o argumento original — o gate agora não deveria mais morrer, mas travar a sessão por causa dele nunca foi correto, é defesa em profundidade) e dev.awaiting_approval, por um argumento DIFERENTE do que a RN-411 tinha descartado: a decisão de aprovação/negação grava proposed_actions.status de forma SÍNCRONA na transação do ApproveActionUseCase (o segundo sinal já não vê mais pending ali), mas a retomada do dev agent é ASSÍNCRONA — só depois de avisarQuemEsperava() gravar task.action_settled/task.pr_settled na outbox é que Engine.Outbox.Drain enfileira o job do Oban que acorda DevAgentServer. Nessa janela, nada segurava a sessão: o mesmo defeito da RN-411, um nível mais fundo.

A aba Executores/Visão Geral tinham o defeito irmão do lado web: executionActivated era derivado de events.some((e) => e.type === 'execution.activated') sobre a janela de só 200 eventos de useSessionEvents ({ limit: 200, latest: true }) — execution.activated é dos PRIMEIROS eventos de uma sessão de execução e saía da janela em qualquer sessão real. O valor correto já existia, agregado sobre TODOS os eventos (bool_or(...), RN-090), no resumo do workspace (ProjectCardSummary.roster.executionActivated) — ProjectExecutorsTab.tsx e ProjectOverviewTab.tsx passaram a consumi-lo em vez de derivar da janela. gatesEverOpened sofre da MESMA classe de defeito e ficou DECLARADO como limitação conhecida, não corrigido aqui — corrigi-lo exigiria mudar a assinatura de deriveAgentRoster/rosterFactsFromEvents, fora do escopo desta correção.

• Onde: src/main.ts, apps/engine/lib/engine/harness/context_manager.ex, apps/engine/lib/engine/harness/tokenizer.ex, src/application/use-cases/sessions/get-session-pending-work.use-case.ts, apps/web/src/routes/ProjectExecutorsTab.tsx, apps/web/src/routes/ProjectOverviewTab.tsx
• Teste: test/main.spec.ts (body de 1 MB aceito; acima do limite → 413); apps/engine/test/engine/harness/context_manager_test.exs (toolCalls pesados disparam compactação; :pinned sobrevive; teto de transporte força compactação mesmo com janela de modelo grande); get-session-pending-work.use-case.spec.ts (último evento dev.awaiting_gate/dev.awaiting_approval → pending: true); ProjectExecutorsTab.test.tsx/ProjectOverviewTab.test.tsx (sessão com >200 eventos ainda mostra o roster via resumo agregado)
• Origem: achado por uso real — "nas PRs sempre está estourando entity too large", investigado em conjunto com o dono do produto

RN-416 — O grafo é memória DERIVADA, reconstruível por projeção da outbox

A alternativa de o engine escrever no Neo4j direto foi RECUSADA — abriria um segundo caminho de escrita além do event log, quebrando a garantia de fonte única de verdade. GraphProjector (api) drena uma SEGUNDA linha de outbox, mesma transação de sempre, aggregateType: 'graph_projection' — valor que o Engine.Outbox.Drain do lado engine nunca casa (o filtro dele é aggregate_type IN ('session', 'task')), evitando a corrida que existiria se reusasse 'session' (o engine já drena e marca esse tipo em ~2s). Mesmo padrão de deny-action.use-case.ts, que já grava em dois aggregateType na mesma transação.

Instrumentado em dois pontos: AppendSessionEventUseCase (para handoff.offered, psychologist.hypothesis_proposed, anamnese.profile_updated — payload só {eventId}, o projector RELÊ o envelope completo do event log na hora de projetar, nunca confia numa cópia potencialmente velha) e TransitionSessionUseCase (para session.closed/session.closed_abnormally, que não passam por session_events). GraphProjector é um poller (~2s, mesmo formato do DomainGaugesCollector) que chama os casos de uso de gravação já existentes da fundação anterior — a idempotência mora NELES (chave natural por tipo: Hipotese.id, Handoff(sessionId,seq), PerfilAnamnese(userId,dimensao), Interacao.sessionId com extensão de faixa). GraphUnavailableError no meio de um lote PARA o ciclo inteiro (o resto falharia pelo mesmo motivo) — a linha fica não-processada e tenta de novo sozinha no próximo ciclo, sem intervenção.

• Onde: src/application/graph-projection/graph-projector.ts; src/domain/graph/graph-projection-events.ts; src/application/use-cases/sessions/append-session-event.use-case.ts, transition-session.use-case.ts
• Teste: graph-projector.spec.ts (caminho feliz dos quatro tipos; resolução evidência→seq de hipótese; GraphUnavailableError deixa a linha sem marcar e para o ciclo; ciclo seguinte reprocessa com sucesso; reprocessar a MESMA linha duas vezes não duplica no grafo); testes novos em append-session-event.use-case.spec.ts/ transition-session.use-case.spec.ts (tipo projetável grava a segunda linha; tipo não-projetável não grava nada extra)
• Origem: ver ADR 0101

RN-418 — Efeito externo git e comando privilegiado (sudo/doas) viram teto absoluto, nunca deny

Revisada pela RN-713 (AT-385, 02/10): com o modo automático (a curinga em auto_approve), push e PR são auto-aprovados.

Revisada pela RN-689 (AT-347, decisão do dono de 01/10): o teto abaixo vale também para as ações TIPADAS git_push e pr_open, que até ali só tinham o papel mínimo e nasciam auto_approved pelo curinga, por regra específica ou por permissions.json. O resto desta entrada continua valendo.

Revisa a RN-106 por decisão GLOBAL e explícita do dono do produto: git push, abertura de PR, deploy (a mesma detecção por prefixo que a RN-106 já tinha) e sudo/doas (novo — casados por VERBO em comandoPrivilegiadoNoComando, varrendo todos os segmentos do comando) deixam de ser deny incondicional e viram TETO ABSOLUTO — require_approval incondicional, no MESMO bloco final e MESMO padrão de código dos outros tetos (merge protegida, instruction_patch, parallelize/raise_max_parallel, escopo de caminho): current.policy === 'auto_approve' → sobrescrito. Nunca auto-aprovável por agent_autonomy (inclusive o curinga "*" do modo automático) nem por permissions.json.

A condição que torna isto seguro — sem a qual o teto seria decorativo — é a metade que fecha "sempre permitir" NA FONTE: ApproveAlwaysActionUseCase/patternsForAction recusam gravar padrão em allow pra ação de terminal com efeito externo git ou comando privilegiado. A instância específica ainda pode ser aprovada pelo fluxo normal (ApproveActionUseCase); só o clique que gravaria um padrão pra sempre é recusado, com mensagem clara. É o mesmo argumento que a RN-106 original usava pra justificar deny — resolvido na origem, não mais bloqueando o sintoma.

Um aviso automático de segurança sinalizou esta mudança durante a implementação (reescrever uma regra que o produto documentava como deny absoluto merece escrutínio) — o dono do produto confirmou explicitamente, depois de revisar, que a decisão era essa.

• Onde: src/domain/actions/decide.ts (bloco de tetos absolutos), src/domain/actions/external-effect.ts (comandoPrivilegiadoNoComando, mensagemDeComandoPrivilegiado), src/application/use-cases/actions/approve-always-action.use-case.ts
• Teste: decide.spec.ts (git push com auto mode "*" E com allow casando no permissions.json resolvem pra require_approval; sudo idem; os tetos anteriores continuam intactos — regressão completa); approve-always-action.use-case.spec.ts ("sempre permitir" sobre git com efeito externo/sudo não grava padrão; comando comum continua gravando normalmente — regressão); external-effect.spec.ts
• Origem: ver ADR 0102

Onda 1 do ADR 0104 — execution_mode em três valores, workspace verificado pelo runner

O ADR 0072 (RN-169/RN-170) e o ADR 0103 (RN-419/RN-420) nunca se falaram: o runner reusava a mesma flag workspace_mode == 'local' sem bind-mount nenhum, então usar o runner de verdade continuava exigindo passar pela validação de PASTA MONTADA. O ADR 0104 reconcilia os dois. Migração 0048 recria o enum (project_workspace_mode → project_execution_mode, local → mounted) numa transação só — ALTER TYPE ... ADD VALUE não pode ser referenciado na mesma transação em que foi adicionado — e soma workspace_verified_at (nullable).

RN-421 — execution_mode tem TRÊS valores: container/mounted/runner

projects.workspace_mode (dois valores) virou projects.execution_mode (três): container (DEFAULT, inalterado), mounted (o antigo local, RENOMEADO — mesmo comportamento, mesma validação de disco na criação) e runner (NOVO: uma pasta do usuário sem bind-mount, confirmada pelo CLI brabo-runner). O CHECK do banco passou a ser (execution_mode <> 'container') = (workspace_path IS NOT NULL) — cobre os dois modos não- container com a MESMA condição, sem OR explícito por valor.

projectScopeRoot/Project.workspace_dir_name (api e engine) derivam a raiz pela MESMA regra nos dois modos não-container: o caminho do usuário é a raiz, distinguido do nome de pasta gerenciada pela barra inicial. O que muda entre mounted e runner não é ONDE a raiz fica — é QUANDO/QUEM confirma que ela existe de verdade (RN-422/RN-423).

• Onde: src/db/migrations/0048_quiet_iron_fist.sql, src/db/schema/iam.ts (projectExecutionModeEnum), src/domain/iam/project.entity.ts (PROJECT_EXECUTION_MODES), src/infrastructure/filesystem/project-workspaces-root.ts (projectScopeRoot), apps/engine/lib/engine/projects/project.ex
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (describe "projectScopeRoot nos modos mounted/runner"), apps/engine/test/engine/projects/project_test.exs
• Decisão arquitetural: ADR 0104
• Origem: reconciliação pedida pelo dono do produto, entre os ADRs 0072 e 0103

RN-422 — A validação de criação DIVERGE por modo: mounted toca disco, runner só o léxico

CreateProjectUseCase.caminhoValidado ganhou um terceiro ramo. mounted continua exatamente como local era (RN-170, histórico): recusa com 400 o caminho que não existe, não é pasta ou não é gravável dentro do container, com a instrução de montagem. runner valida só o LÉXICO — mesma lista de proibições (absoluto, sem .., fora de raiz/pasta de sistema, sem sobreposição com o checkout do Brabo) — sem tocar disco: só o runner, rodando no HOST de verdade, tem autoridade para confirmar que a pasta existe. O projeto nasce com workspace_verified_at: null.

caminhoDeWorkspaceLocalValido (o predicado léxico) foi EXPORTADO de project-workspaces-root.ts para ser reusado nos dois lados que precisam dele sem tocar disco: a criação de projeto runner e a confirmação do runner (RN-423) — a mesma função, nunca duas cópias que um dia divergem.

• Onde: src/application/use-cases/iam/create-project.use-case.ts (caminhoValidado), src/infrastructure/filesystem/project-workspaces-root.ts (caminhoDeWorkspaceLocalValido, exportada), src/interfaces/http/iam/dto/create-project.dto.ts
• Teste: test/application/use-cases/iam/create-project-modo-de-workspace.spec.ts (bloco runner), test/interfaces/http/iam/project-dto-modo-de-workspace.spec.ts, apps/web/src/lib/wizard.test.ts (canAdvanceFromWorkspace para runner)
• Decisão arquitetural: ADR 0104
• Origem: reconciliação do ADR 0104

RN-424 — PAT autentica SÓ runner-ticket, por construção — nunca dual-auth com JWT nessa rota

Um Personal Access Token (brb_…) nunca autoriza nenhuma rota além de POST /projects/:projectId/runner-ticket. A garantia não é um if que uma rota nova poderia esquecer de checar: é estrutural. @RequirePatAuth() marca o handler com IS_PAT_ROUTE_KEY; JwtAuthGuard (o APP_GUARD global) checa esse metadado ANTES de tentar verify() de JWT e devolve true sem validar nada — o mesmo formato de bypass que IS_PUBLIC_KEY e IS_SERVICE_ROUTE_KEY já usam. PatAuthGuard, aplicado só nesse handler via @UseGuards(), é quem de fato autentica: extrai o bearer, recusa (401) qualquer valor que não comece com brb_ sem consultar o repositório — nunca tenta validar como JWT nessa rota, e nenhuma outra rota aceita brb_… como bearer.

Depois que o PatAuthGuard popula request.user, RolesGuard/ ResolveEffectiveRoleUseCase continuam rodando, inalterados — cinto e suspensório: se o dono do PAT perder papel suficiente no projeto pela via normal (ProjectMember/workspace), o token para de autorizar mesmo sem ter sido revogado explicitamente.

A alternativa considerada e recusada: o JwtAuthGuard global reconhecer o prefixo brb_ e popular request.user direto, pra QUALQUER rota. Isso autorizaria o PAT a tudo que o papel do usuário permite no resto da api — o escopo "só pede ticket de runner" viraria decorativo.

• Onde: src/interfaces/http/auth/pat-route.decorator.ts (IS_PAT_ROUTE_KEY/@RequirePatAuth()), src/interfaces/http/auth/jwt-auth.guard.ts (o terceiro early-out), src/interfaces/http/auth/pat-auth.guard.ts (PatAuthGuard), src/interfaces/http/runner/runner-tickets.controller.ts (runnerTicket, o único handler marcado)
• Teste: test/interfaces/pat-auth.guard.spec.ts, test/interfaces/jwt-auth.guard.spec.ts (@RequirePatAuth() passa sem tentar verify()), test/interfaces/http/runner/runner-tickets.controller.spec.ts (runnerTicket tem o decorator, terminalTicket não)
• Decisão arquitetural: ADR 0105

RN-425 — Validação de PAT colapsa inexistente/revogado/expirado numa resposta só; escopo errado é 403; last_used_at nunca throttla

PersonalAccessTokenRepository.validarEUsar(hash) é UMA query: UPDATE personal_access_tokens SET last_used_at = now() WHERE token_hash = $1 AND revoked_at IS NULL AND (expires_at IS NULL OR expires_at > now()) RETURNING id, user_id, project_id. Zero linhas devolve null, e o guard responde 401 pra "não existe", "revogado" e "expirado" com a MESMA mensagem — quem apresenta um token roubado ou expirado não descobre qual dos três é o motivo (mesmo padrão de AccountTokenRepository.consumir()).

Escopo de projeto incorreto é uma categoria DIFERENTE: se project_id devolvido pela query não bate com :projectId da rota, é 403, não 401 — o token autenticou de verdade, só não tem direito a ESTE projeto.

last_used_at é atualizado de forma INCONDICIONAL, na MESMA query de validação — nunca com um throttle (ex.: "só se last_used_at for NULL ou tiver mais de 5 minutos") no mesmo WHERE. Um throttle ali é um bug real: um PAT reapresentado duas vezes em menos de 5 minutos cairia fora do WHERE na segunda vez (porque last_used_at estaria "fresco demais"), e a query devolveria zero linhas pra um token válido — rejeitando com 401 uma reconexão legítima. O laço de retry do runner reconecta em segundos, não minutos. O custo de não throttlar é um UPDATE de uma linha por índice único a cada chamada — irrelevante no pior caso real (até 10 tentativas seguidas, teto do runner).

• Onde: src/infrastructure/persistence/drizzle/personal-access-token.repository.ts (validarEUsar), src/interfaces/http/auth/pat-auth.guard.ts
• Teste: test/infrastructure/persistence/personal-access-token.repository.spec.ts (inexistente/revogado/expirado → null; "toca last_used_at sempre que válido, sem throttle" — regressão do bug acima), test/interfaces/pat-auth.guard.spec.ts (escopo errado → 403, não 401)
• Decisão arquitetural: ADR 0105

RN-426 — Listar/revogar PAT é escopado ao PRÓPRIO usuário, no WHERE da query — sem admin cross-user nesta onda

ListPersonalAccessTokensUseCase/RevokePersonalAccessTokenUseCase filtram por userId dentro da consulta SQL (WHERE user_id = $1 AND ...), nunca trazendo tudo e filtrando depois em memória. Cada usuário só enxerga e só revoga os PRÓPRIOS tokens — inclusive dentro de um projeto onde ele é maintainer.

revogar(id, userId, motivo) é IDEMPOTENTE: se o UPDATE (com o mesmo WHERE user_id = $1) não acha linha porque já estava revogado, uma segunda consulta de desempate devolve a linha (revogar de novo não é erro); se não acha porque o token não existe OU não é do usuário chamador, devolve null — a MESMA resposta (404 no controller) pros dois casos, pra não vazar a existência de um token alheio pelo código de status.

Fechado pela RN-427: um maintainer revogar o PAT de outro usuário — o caso de resposta a incidente (dev desligado com token vazando) — que esta seção declarava fora de escopo saiu do backlog e está implementado. Esta régua (autorevogação, escopo por userId) não mudou em nada.

• Onde: src/application/use-cases/auth/list-personal-access-tokens.use-case.ts (ListPersonalAccessTokensUseCase), src/application/use-cases/auth/revoke-personal-access-token.use-case.ts, src/infrastructure/persistence/drizzle/personal-access-token.repository.ts (listarDoUsuarioNoProjeto, revogar)
• Teste: test/application/use-cases/auth/list-personal-access-tokens.use-case.spec.ts, test/application/use-cases/auth/revoke-personal-access-token.use-case.spec.ts, test/infrastructure/persistence/personal-access-token.repository.spec.ts (revogar token de outro usuário → null)
• Decisão arquitetural: ADR 0105

RN-427 — maintainer revoga PAT de QUALQUER usuário do projeto, escopado por project_id — resposta a incidente

Extensão do modelo da RN-426, não uma decisão de arquitetura nova: mesmo padrão já usado para fechar a RN-407 (PO lendo métricas de produto) sobre um modelo já decidido, sem ADR próprio. Fecha o corte que o ADR 0105 declarava "fora desta onda" — resposta a incidente real (dev desligado com token vazando), onde esperar o próprio usuário revogar não é opção.

ListPersonalAccessTokensAsMaintainerUseCase/ RevokePersonalAccessTokenAsMaintainerUseCase são casos de uso NOVOS, em rotas SEPARADAS (GET .../personal-access-tokens/all, DELETE .../personal-access-tokens/:tokenId/admin, ambas @RequireRole('maintainer')) — nunca um if dentro dos handlers de self-service, mesmo princípio já usado no resto do produto para autorização por nível (OfferInfraHandoffUseCase). A rota de autorevogação (RN-426) não muda em nada.

listarDoProjeto traz TODOS os tokens do projeto — sem filtro de userId — com um innerJoin em users pro e-mail do dono, mesmo padrão que a listagem de membros do projeto já usa: sem o e-mail, um maintainer vendo "revogar token de quem?" só teria um UUID cru, e o próprio motivo do item (resposta a incidente) pede saber QUEM é o dono.

revogarComoMaintainer(id, projectId, motivo) é o mesmo desenho idempotente de revogar() — UPDATE condicional seguido de SELECT de desempate quando o UPDATE não acha linha —, mas o WHERE compara project_id, nunca user_id: um maintainer revoga qualquer dono DENTRO do projeto dele, nunca um token de outro projeto. Sem linha nenhuma (token não existe OU é de outro projeto), devolve null — a MESMA resposta (404) pros dois casos, mesma disciplina de não vazar existência que a RN-426 já aplicava.

• Onde: src/application/use-cases/auth/list-personal-access-tokens-as-maintainer.use-case.ts, src/application/use-cases/auth/revoke-personal-access-token-as-maintainer.use-case.ts, src/infrastructure/persistence/drizzle/personal-access-token.repository.ts (listarDoProjeto, revogarComoMaintainer), src/interfaces/http/runner/personal-access-tokens.controller.ts (listAllPats, revokePatAsMaintainer), apps/web/src/routes/settings/PersonalAccessTokensSection.tsx (sub-lista visível só para owner/maintainer)
• Teste: test/application/use-cases/auth/list-personal-access-tokens-as-maintainer.use-case.spec.ts, test/application/use-cases/auth/revoke-personal-access-token-as-maintainer.use-case.spec.ts, test/infrastructure/persistence/personal-access-token.repository.spec.ts (listarDoProjeto/revogarComoMaintainer), test/interfaces/http/runner/personal-access-tokens.controller.spec.ts, apps/web/src/routes/ProjectSettingsTab.test.tsx
• Decisão arquitetural: ADR 0105 (extensão do modelo existente, sem ADR novo)

RN-430 — PRs são project-wide; a decisão usa o sessionId da própria ação, nunca a mais recente

A aba prs resolve o defeito de ProjectApprovalsTab.tsx, que escopava a seção "PRs em revisão" a usePendingActions(projectId, latestSession?.id) — a revisão pendente de uma sessão anterior desaparecia assim que uma sessão nova nascia. A listagem vem direto do provider (GET /projects/:id/code/pull-requests, já project-wide por desenho); o cruzamento com a proposed_action correspondente (ex.: git_merge) usa ProposedActionRepository.findPendingByProject(projectId, actionType?), novo, ao lado do já existente escopado por sessão. A decisão (aprovar/negar/sempre permitir) usa o sessionId que a própria ProposedAction carrega, nunca latestSession — a ação pode ter nascido numa sessão diferente da atual.

A aba PRs é a primeira produtora real de git_merge pela UI (actor.kind: 'user'); a trava de branch protegida em decide.ts (RN-154) segue absoluta independente de quem propõe. git_merge ganhou corpo próprio no card de aprovação em vez do despejo de JSON cru (mesmo defeito que a RN-096 já corrigiu para outros tipos).

• Onde: src/application/ports/proposed-action-repository.port.ts, src/infrastructure/persistence/drizzle/proposed-action.repository.ts, src/application/use-cases/actions/list-project-pending-actions.use-case.ts, src/interfaces/http/actions/project-actions.controller.ts (GET /projects/:projectId/actions?status=pending&actionType=), apps/web/src/routes/ProjectPrsTab.tsx, apps/web/src/components/ApprovalCard.tsx
• Teste: list-project-pending-actions.use-case.spec.ts (ação pendente de sessão antiga encontrada project-wide; filtro por actionType; nunca devolve ação decidida); propose-action.use-case.spec.ts (git_merge com payload real da aba PRs segue pending mesmo com GitMerge() em allow, e com agent_autonomy curinga ligado); ProjectPrsTab.test.tsx (PRs de múltiplas sessões aparecem juntas; decisão usa o sessionId da ação, não o da sessão mais recente); ApprovalCard.test.tsx (corpo próprio de git_merge)
• ADR: nenhum — extensão de um caminho de leitura já existente, sem mudar o pipeline de decisão
• Origem: pedido do dono do produto — "não há maneiras de gerir PRs"

O explorador de pasta do Runner vira três colunas, e a criação de um projeto runner deixa de esperar o passo final (RN-436/436)

RN-439 — POST .../runner-ticket autentica E autoriza no MESMO guard; RolesGuard (global) se abstém em rota @RequirePatAuth()

POST /projects/:projectId/runner-ticket respondia 403 "Não autenticado" para TODO PAT, mesmo válido, recém-emitido, escopado ao projeto certo — achado numa verificação AO VIVO do brabo-runner conectando a um projeto real, nunca por teste automatizado. Causa raiz: JwtAuthGuard e RolesGuard são os dois APP_GUARD — GLOBAIS — e um guard global SEMPRE roda ANTES de um guard LOCAL de rota (@UseGuards), não importa a ordem dos decorators no controller. JwtAuthGuard já sabia se abster nesta rota (o desvio de IS_PAT_ROUTE_KEY já existia, sem popular request.user, contando com PatAuthGuard pra autenticar depois); RolesGuard não sabia, e recusava toda chamada com request.user ainda vazio — PatAuthGuard nunca chegava a rodar. O comentário do controller descrevia a ordem ao contrário ("RolesGuard roda DEPOIS do PatAuthGuard"), e nunca foi assim.

A correção seguiu o MESMO padrão que JwtAuthGuard já usava para este problema: RolesGuard ganhou o desvio gêmeo (IS_PAT_ROUTE_KEY → retorna true sem checar request.user), delegando a autorização inteira para quem passa a ser o ÚNICO guard rodando depois de request.user populado nesta rota — o próprio PatAuthGuard, que agora também lê @RequireRole (via Reflector) e resolve o papel efetivo (ResolveEffectiveRoleUseCase.forProject), recusando com a MESMA mensagem que RolesGuard usaria ("Papel insuficiente para esta ação"). A lógica é duplicada entre os dois guards de PROPÓSITO — RolesGuard mora em iam, PatAuthGuard mora em auth, e uma dependência cruzada só para reusar ~10 linhas não valeria a pena.

Um SEGUNDO defeito ficou escondido atrás do primeiro, e só apareceu quando o teste de integração passou a exercitar os dois guards JUNTOS: PatAuthGuard comparava o token BRUTO direto contra personal_access_tokens.token_hash em validarEUsar — que sempre espera o HASH (hashDeToken, HMAC-SHA256+ pepper, o mesmo que TokenFactory/IssuePersonalAccessTokenUseCase usam para gravar). Corrigido para this.tokens.validarEUsar(hashDeToken(token)). Enquanto RolesGuard recusava tudo antes, este segundo bug nunca chegava a se manifestar — corrigir só o primeiro teria trocado um 403 sempre por um 401 sempre, e o runner continuaria nunca conectando de verdade.

• Onde: src/interfaces/http/iam/roles.guard.ts (desvio IS_PAT_ROUTE_KEY); src/interfaces/http/auth/pat-auth.guard.ts (autorização por papel + hash do token); src/interfaces/http/runner/runner-http.module.ts (IamUseCasesModule importado, pelo ResolveEffectiveRoleUseCase que PatAuthGuard passou a precisar); comentário corrigido em src/interfaces/http/runner/runner-tickets.controller.ts
• Teste: test/interfaces/pat-auth.guard.spec.ts (autorização por papel isolada + hash do token); test/interfaces/roles.guard.spec.ts (desvio IS_PAT_ROUTE_KEY); test/interfaces/http/runner/runner-tickets.guards.integration.spec.ts (NOVO — sobe JwtAuthGuard+RolesGuard+PatAuthGuard num Nest real, com supertest, na MESMA ordem relativa do AppModule: é o teste que faltava, porque cada guard só era exercitado isolado antes disto). Verificado também AO VIVO: brabo-runner conectou de verdade a um projeto runner real com um PAT emitido depois da correção
• ADR: 0105 — correção de bug na implementação da decisão já tomada lá (PAT autentica esta rota), não uma decisão nova
• Origem: achado rodando o brabo-runner de verdade contra um projeto real e isolando com curl direto — nunca por teste automatizado, porque nenhuma suíte exercitava RolesGuard e PatAuthGuard na mesma requisição

RN-440 — addressableAgents() é o catálogo FECHADO do handoff manual, mais estrito que assertHandoffTargetAllowed

Handoff manual a agente à escolha (backlog, ADR 0109): assertHandoffTargetAllowed (ADR 0038) só recusa um SUBAGENTE de área — um agente citando "abc" como alvo passaria por ela sem erro, porque uma AGENTE só cita alvos que ele já conhece pela própria instrução. Isso deixa de ser verdade quando quem escolhe é um HUMANO, num <select> alimentado por um cliente que pode divergir do backend. addressableAgents() (src/domain/agents/agent-areas.ts) é o catálogo FECHADO — leads de área (AGENT_AREAS.map(a => a.lead)) ∪ SOLO_CONVERSATIONAL_AGENTS (criativo, po, arquiteto, ux-designer, staff) — e RequestManualHandoffUseCase recusa com 400 qualquer toAgent fora dele, ANTES de chamar CreateHandoffUseCase.

SOLO_CONVERSATIONAL_AGENTS é uma lista PRÓPRIA, não derivada do roster apps/web/src/lib/agents.ts (que também lista agentes de gate e o Psicólogo/Anamnese, nenhum endereçável por handoff). A direção da derivação é a da api para o web: desde a AT-046 a cópia do web deixou de ser mirror MANUAL e sai do MESMO gerador das áreas (pnpm --filter api gerar:areas, Fase 18), em apps/web/src/lib/agent-areas.generated.ts, que agents.ts só reexporta. agent-areas.spec.ts reprova quando o disco diverge do que o gerador produz, e a lista gerada sai as const satisfies readonly AgentKey[] — um nome que o roster do web não conhece quebra o build do web. O engine NÃO recebe a lista (não há consumidor lá). Mesmo com as duas cópias travadas, quem decide o que é aceito continua sendo o RequestManualHandoffUseCase.

• Onde: src/domain/agents/agent-areas.ts (addressableAgents, SOLO_CONVERSATIONAL_AGENTS); src/application/use-cases/agents/request-manual-handoff.use-case.ts; scripts/gerar-areas.ts (renderWeb, que escreve a lista no web); apps/web/src/lib/agent-areas.generated.ts (cópia GERADA, reexportada por apps/web/src/lib/agents.ts)
• Teste: test/domain/agents/agent-areas.spec.ts (describe('addressableAgents (ADR 0109)') e describe('a lista solo sai do gerador para o web (AT-046)'), mais o aferidor de frescor do arquivo do web); test/application/use-cases/agents/request-manual-handoff.use-case.spec.ts (recusa subagente E recusa agente desconhecido); apps/web/src/lib/agents.test.ts
• ADR: 0109
• Origem: backlog do modelo de time — item aberto desde a FASE 13c, fechado pelo caso real do Staff (ADR 0088) e do UX Designer (ADR 0087), os dois com plumbing de engine pronto e nenhum caminho humano até eles

RN-441 — POST .../sessions/:sessionId/handoffs exige developer; handoff manual nasce offered, sem estado novo

O único caminho para gravar toAgent continua sendo CreateHandoffUseCase (ADR 0038) — não um segundo mecanismo. RequestManualHandoffUseCase resolve fromAgent sozinho (o agent.activated mais RECENTE da sessão, via SessionEventRepository.listByTypeInSession — mesmo critério de activeAgent em SessionPage.tsx, achado 9-fix; sessão sem nenhum agente ativado ainda cai no sentinela "usuario", nunca um nome adivinhado) e chama CreateHandoffUseCase.execute passando actor: {kind: 'user', id: userId} — CreateHandoffInput ganhou o campo opcional actor?: Actor para isso, com default {kind:'agent', id: fromAgent} preservando o comportamento de sempre para o chamador interno (o engine). O handoff nasce offered, do MESMO jeito que um automático, e o card de aceite já existente (offeredHandoff/handleAcceptHandoff em SessionPage.tsx) o pega sozinho no próximo poll de useHandoffs — sem NENHUMA mudança no caminho de aceite. (Não pegava, e ninguém viu até a AT-253: o card casava a oferta pelo ATOR, e o ator do manual é a pessoa. Corrigido na RN-631, que casa pelo handoffId.)

A rota (POST projects/:projectId/sessions/:sessionId/handoffs) exige papel developer, o mesmo de handoffs/:handoffId/accept (RN-136: quem CONVERSA nesta tela). ux-designer e staff entraram em AGENTES_DE_CHAT (SessionPage.tsx) na mesma mudança — as duas cláusulas de message/2 já existiam em agent_command_controller.ex (ADR 0087/0088), verificado por leitura ANTES de escrever qualquer linha de web, e nenhuma delas tinha caminho humano até si.

• Onde: src/interfaces/http/agents/agents.controller.ts (requestManual); src/interfaces/http/agents/dto/request-manual-handoff.dto.ts; src/application/use-cases/agents/create-handoff.use-case.ts (actor?: Actor); apps/web/src/routes/SessionPage.tsx (AGENTES_DE_CHAT, .manualHandoffRow, handleRequestManualHandoff); apps/web/src/lib/api-client.ts (requestManualHandoff)
• Teste: test/interfaces/http/agents/agents.controller.spec.ts (papel exigido); test/application/use-cases/agents/request-manual-handoff.use-case.spec.ts (fromAgent derivado, sentinela "usuario", actor: user); docs/security-surface.md + test/interfaces/route-surface.spec.ts (classificação role:developer em runtime)
• ADR: 0109
• Origem: backlog do modelo de time (ver RN-440)

RN-443 — Budget de área é ADITIVO ao de projeto/sessão, nunca cascata; só maintainer muda o teto

Fecha o item "budget por área" do corte do ADR 0038, em aberto desde a FASE 8. agent_areas ganha budget_micros (nullable — null é SEM TETO, o default) e spent_micros (NOT NULL DEFAULT 0), espelhando exatamente max_parallel: mesma linha, mesmo dono da decisão, mesmo AgentAreaRepository. Não é a cascata de binding de modelo do ADR 0064 (sessão > agente > área > projeto > workspace, "o mais específico vence") — os dois mecanismos usam a palavra "área" e não têm mais nada em comum. Budget de área é um TERCEIRO teto independente ao lado dos de projeto e sessão que já existiam: CheckBudgetGateUseCase.execute agora resolve a área do agentId (via areaDo, função pura, sem tocar banco a menos que ache correspondência) e checa os três em paralelo — qualquer um bloqueado já recusa a chamada, sem hierarquia entre eles.

RecordLlmUsageUseCase incrementa spent_micros da área do ator SEMPRE que ele pertence a uma (lead ou membro — areaDo devolve área pros dois), com ou sem budget_micros configurado: o gasto real da área fica visível antes mesmo de alguém configurar um teto. Ator sem área (usuário no chat, agente fora de qualquer área) não grava nada — não é omissão silenciosa, é o comportamento correto quando não há o que incrementar.

SetAreaBudgetUseCase exige maintainer (mesma régua de SetAreaMaxParallelUseCase — mudar quanto o produto pode gastar sem perguntar), converte dólar→micro-USD no controller (mesma convenção de BudgetsController) e não emite evento de domínio (config de projeto, sem sessão pra gravar — mesmo raciocínio já registrado em SetAreaMaxParallelUseCase). null LIMPA o teto — campo obrigatório que aceita null como valor válido (ValidateIf, não IsOptional), mesmo padrão de RenameSessionDto.

• Onde: src/db/schema/agents.ts (agentAreas, colunas budgetMicros/spentMicros e os dois CHECK); src/domain/llm/area-budget.ts (isAreaBudgetExceeded); src/application/use-cases/llm/check-budget-gate.use-case.ts; src/application/use-cases/llm/record-llm-usage.use-case.ts; src/application/use-cases/execution/set-area-budget.use-case.ts; src/infrastructure/persistence/drizzle/agent-area.repository.ts (setBudget/incrementSpent); src/interfaces/http/execution/execution.controller.ts (PUT agent-areas/:key/budget); apps/web/src/routes/settings/BudgetSection.tsx
• Teste: test/application/use-cases/llm/check-budget-gate.use-case.spec.ts (describe budget de área — aditivo, não cascata: área excedida bloqueia com projeto/sessão OK e vice-versa, sem teto nunca bloqueia, agente sem área não é afetado); test/application/use-cases/llm/record-llm-usage.use-case.spec.ts (describe gasto por área: incrementa pro membro e pro lead, não faz nada nocivo sem área, soma sem teto configurado); test/application/use-cases/execution/set-area-budget.use-case.spec.ts (grava, limpa com null, recusa negativo/NaN/Infinity, zero é válido); test/infrastructure/persistence/drizzle/agent-area.repository.spec.ts (setBudget/incrementSpent, atomicidade sob concorrência)
• ADR: 0110
• Origem: item de backlog aprovado pelo dono do produto numa sessão de planejamento explícita — docs/explanation/backlog.md, tabela "Older backlog"

RN-447 — Converter execution_mode de projeto EXISTENTE recusa (409) enquanto qualquer dev agent do projeto não está idle

ConvertProjectExecutionModeUseCase (PUT .../execution-mode, papel maintainer) lê engine.dev_agent_states DIRETO (cross-schema, mesmo banco físico — mesmo caminho da RN-409) por project_id, em TODAS as sessões do projeto, não só a mais recente. Qualquer status diferente de idle (working/blocked/idle_tripped/awaiting_gate/ awaiting_approval) recusa a conversão: Engine.Dev.DevAgentServer NÃO re-resolve o worktree sozinho — workspace_root é capturado UMA vez, na criação do worktree, e trocar a coluna por baixo dele deixaria o agente escrevendo num escopo que o permissions.json e a política de terminal (ADR 0055) já abandonaram. A decisão é RECUSAR e explicar (mesmo padrão "recusa e ensina" da RN-088/RN-422) — nunca drenar ou forçar a migração de um agente vivo.

idle_tripped conta como ATIVO aqui, diferente da RN-409 (que o exclui de onlineAgentCount): as duas perguntas são diferentes — "alguém está olhando este agente trabalhar agora" (RN-409) contra "existe um ponteiro de escopo que ficaria obsoleto" (aqui). Um agente com o circuit breaker disparado ainda tem workspace_root capturado, esperando desbloqueio humano — não é "ocioso" para efeito de conversão, mesmo não sendo "online" para efeito de contagem.

Mesmo (modo, caminho) de hoje é NO-OP: a checagem de dev agent nem roda — reenviar o formulário sem mudar nada não deveria custar uma varredura de agentes ativos.

• Onde: src/application/use-cases/iam/convert-project-execution-mode.use-case.ts; src/application/ports/dev-agent-activity.port.ts; src/infrastructure/persistence/drizzle/dev-agent-activity.repository.ts
• Teste: test/application/use-cases/iam/convert-project-execution-mode.use-case.spec.ts (recusa com dev agent ativo, sem gravar nada; no-op não checa); test/infrastructure/persistence/drizzle/dev-agent-activity.repository.spec.ts (idle não conta, todo o resto conta, isolamento entre projetos)
• ADR: 0111
• Origem: correção registrada em docs/explanation/backlog.md durante a implementação da Onda 1 do runner (ADR 0104), fechada nesta Onda 2

RN-448 — permissions.json é RELOCALIZADO na conversão — o conteúdo nunca muda, só o caminho

PermissionsFileStore.move(from, to) lê o arquivo na localização ANTIGA (projectScopeRoot(localAntiga)), grava o MESMO conteúdo na localização NOVA e apaga o antigo (best-effort — se já não existir, não há o que apagar). O conteúdo (padrões allow/deny/ask) não carrega caminho nem modo dentro de si, então não há nada para REESCREVER, só para mover. from === to (nenhuma raiz efetiva mudou) é no-op.

Confirmado por leitura de projectScopeRoot (project-workspaces-root.ts): para mounted/runner a raiz É o workspacePath, tratado como caminho DENTRO DO CONTAINER DA API — em runner, isso já era verdade ANTES desta entrega (sem bind-mount, o arquivo mora numa pasta que só coincide em STRING com a pasta real do usuário, desconectada dela). A conversão não muda essa propriedade existente, só a relocaliza de forma consistente — sem caso especial para runner além de usar move() como qualquer outro par.

• Onde: src/application/ports/permissions-file-store.port.ts (move); src/infrastructure/filesystem/fs-permissions-file-store.ts
• Teste: test/infrastructure/filesystem/fs-permissions-file-store.spec.ts (conteúdo sobrevive e é apagado da origem; origem sem arquivo grava vazio sem lançar; from === to é no-op)
• ADR: 0111

RN-449 — Saindo de container, o ciclo de vida do container é encerrado (removed) ANTES da coluna mudar

ConvertProjectExecutionModeUseCase chama RegistrarTransicaoDeContainerUseCase (ADR 0081) para levar a linha de project_containers a removed — via stopped primeiro quando está running (container-lifecycle.ts não tem aresta direta running -> removed) — ANTES de gravar o novo execution_mode. A ordem é obrigatória: RegistrarTransicaoDeContainerUseCase recusa (400) qualquer transição num projeto que não esteja em execution_mode = 'container' NO MOMENTO da chamada, então chamá-lo depois de trocar a coluna sempre falharia. Sem linha de container (projeto que nunca provisionou), nenhuma transição é disparada.

Entrar em container a partir de mounted/runner NÃO auto-provisiona nada — o portão da imagem do Arquiteto (RN-105) e o ciclo de vida normal valem a partir daí, como para qualquer projeto container — nunca um atalho que pula o portão porque o projeto "já tinha código em algum lugar".

• Onde: src/application/use-cases/iam/convert-project-execution-mode.use-case.ts (removerContainerSeExistir)
• Teste: test/application/use-cases/iam/convert-project-execution-mode.use-case.spec.ts (running passa por stopped; provisioning vai direto; sem linha, nenhuma transição; entrar em container nunca dispara transição)
• ADR: 0111

RN-450 — workspaceVerifiedAt zera em TODA conversão real, mesmo voltando para runner com o "mesmo" caminho

Só faz sentido em execution_mode: 'runner' (RN-423): um timestamp provando que um runner CONECTADO confirmou o caminho no host real. Qualquer conversão que muda de fato o par (modo, caminho) — incluindo uma que pousa de novo em runner com um caminho de aparência igual — zera o campo, forçando confirmação NOVA: o timestamp antigo atesta uma verificação que aconteceu sob um par DIFERENTE, e carregá-lo adiante afirmaria uma confirmação que nunca aconteceu para o estado novo. O no-op (RN-447) é a única exceção — nada muda, então nada zera.

• Onde: src/application/use-cases/iam/convert-project-execution-mode.use-case.ts
• Teste: test/application/use-cases/iam/convert-project-execution-mode.use-case.spec.ts (runner -> container zera; no-op preserva)
• ADR: 0111

Pasta local anexada vira o quarto escopo do índice RAG, lido pelo NAVEGADOR (RN-455..457, ADR 0113)

Pedido do dono do produto: anexar uma pasta da PRÓPRIA máquina do usuário a um projeto como referência de leitura para os agentes — sem exigir o CLI brabo-runner (ADR 0103), diferente de execution_mode: runner (ADR 0104), que precisa de um caminho de HOST real porque roteia comando para lá. O navegador lê o CONTEÚDO dos arquivos (File.text()) e o caminho RELATIVO dentro da pasta escolhida (File.webkitRelativePath) — nunca um caminho absoluto de máquina, porque a API de File do navegador não expõe um, para nenhum site. O que atravessa a rede é texto que o navegador já tinha o direito de ler, o mesmo modelo de confiança de qualquer upload de arquivo comum.

RN-455 — chunks.scope ganha 'local', reusando o pipeline de RAG inteiro

ChunkScope passa de 'docs' | 'adr' | 'session' para incluir 'local' (migração 0052, ALTER TYPE ... ADD VALUE) — aditivo, sem migração de dado, sem CHECK novo: os dois CHECK de chunks (migração 0045) já são escritos como "é session ou não é", então local cai do mesmo lado de docs/adr (tem source_path, não tem session_id) sem mudança nenhuma além do valor do enum. origemDoChunk (domain/rag/rag-citation.ts) não precisou de nenhum ramo novo: um chunk local carrega sourcePath exatamente como docs/adr, então cai no kind: 'file' que a citação já sabia renderizar.

• Onde: src/db/schema/rag.ts (chunkScopeEnum), src/db/migrations/0052_chunks_local_scope.sql, src/application/ports/chunk-repository.port.ts (ChunkScope), src/application/use-cases/rag/index-local-folder.use-case.ts
• Teste: test/application/use-cases/rag/index-local-folder.use-case.spec.ts (caminho feliz e full rebuild), test/interfaces/http/rag/rag.controller.spec.ts
• ADR: 0113
• Origem: pedido do dono do produto

RN-457 — maintainer, e reanexar é o MECANISMO de resincronizar — nunca o "Reindexar agora" genérico

POST .../rag/local exige maintainer, mesma régua de POST .../rag/reindex (RN-238): as duas chamam o provider de embedding e substituem o que o projeto já tinha indexado. ReindexProjectUseCase NÃO foi estendido para cobrir local — ele reindexa lendo de uma fonte que o SERVIDOR consegue revisitar (o repositório do projeto, o event log), e local não tem fonte nenhuma para revisitar: o texto só existe no navegador de quem anexou, e o servidor nunca guardou caminho de host nenhum (não há um). Chamar deleteByScope(projectId, 'local') no botão genérico apagaria a referência anexada sem ter como recriá-la — reanexar a pasta (novo upload) É o mecanismo de resincronizar, e é um botão deliberadamente separado. Os dois casos de uso carregam comentário cruzado explicando o porquê, para uma "correção" futura não religar os dois e apagar silenciosamente o material do usuário.

• Onde: src/interfaces/http/rag/rag.controller.ts (anexarPastaLocal, @RequireRole('maintainer')), src/application/use-cases/rag/reindex-project.use-case.ts (comentário "Por que local NÃO entra aqui")
• Teste: test/interfaces/http/rag/rag.controller.spec.ts
• ADR: 0113
• Origem: pedido do dono do produto

RN-458 — Cobertura de local é forma PRÓPRIA, e lastAttachedAt é a ÚNICA exceção real ao "nunca Xmin" (RN-237)

RagCoverage.local não reusa RagFileCoverage (RN-237, ADR 0080): não há "total no repositório" pra comparar — uma pasta anexada não tem um total que o servidor possa recontar. RagLocalCoverage mostra o que está indexado AGORA (filesIndexed, folderName) e lastAttachedAt, um MAX(chunks.created_at) REAL sobre o escopo — a única exceção declarada à regra de nunca mostrar um "reindexado há Xmin" chutado, porque aqui o valor real EXISTE e é barato de calcular (mesmo todosOsChunks que GetRagCoverageUseCase já busca).

• Onde: src/application/use-cases/rag/get-rag-coverage.use-case.ts (RagLocalCoverage), apps/web/src/components/rag/RagCoveragePanel.tsx
• Teste: test/application/use-cases/rag/get-rag-coverage.use-case.spec.ts, apps/web/src/components/rag/RagCoveragePanel.test.tsx
• ADR: 0113
• Origem: pedido do dono do produto

Ollama nativo no bootstrap dev e pull de modelo Hugging Face (RN-461..463, ADR 0114/0115)

RN-462 — Pull de modelo Hugging Face exige confirmação explícita em duas etapas; nunca roda sozinho

POST .../huggingface/pull-requests só CRIA o pedido, em pending_confirmation — nenhum download começa. Somente uma chamada SEPARADA, POST .../pull-requests/:id/confirm, move o pedido para confirmed → pulling e de fato chama OllamaProvider.pullModel. ConfirmModelPullUseCase RECUSA (409) confirmar um pedido que já não esteja em pending_confirmation — a transição de estado É a segunda confirmação, não uma flag à parte, e por isso não é reexecutável. Falha do Ollama durante o pull marca o pedido failed com failedReason prefixado pela origem (infra/modelo/código, vocabulário do ADR 0020) — nunca falha silenciosa, e nada é ativado no catálogo quando falha.

• Onde: src/application/use-cases/llm/huggingface/request-model-pull.use-case.ts:23 (RequestModelPullUseCase), src/application/use-cases/llm/huggingface/confirm-model-pull.use-case.ts:45 (ConfirmModelPullUseCase), src/interfaces/http/llm/huggingface-models.controller.ts:109-165 (as duas rotas, role:maintainer)
• Teste: test/application/use-cases/llm/huggingface/request-model-pull.use-case.spec.ts (cria em pending_confirmation, nada além disso), test/application/use-cases/llm/huggingface/confirm-model-pull.use-case.spec.ts (caminho feliz ativa no catálogo; falha do Ollama marca failed com a origem certa — modelo/infra; recusa reconfirmar um pedido que já saiu de pending_confirmation; 404 para pedido inexistente no workspace)
• ADR: 0115
• Origem: pedido do dono do produto

RN-463 — Allowlist de publishers oficiais; comunidade exige opt-in explícito com aviso de segurança

Busca no Hugging Face Hub filtra para publishers OFICIAIS por padrão — HUGGINGFACE_OFFICIAL_PUBLISHERS, vocabulário FECHADO e curado à mão (meta-llama, google, mistralai, microsoft, Qwen, deepseek-ai, openai, nvidia), comparado por igualdade EXATA de caixa — um reupload minúsculo (qwen/...) não herda o selo da org oficial (Qwen/...). includeCommunity=true traz todo o resto, cada resultado marcado official: true|false, nunca ocultando a distinção. Na tela, o toggle de comunidade nasce DESLIGADO e, enquanto ligado, mostra um aviso de segurança (Alert tone="danger") — o opt-in e o aviso são o mesmo gesto, nunca uma preferência que o usuário liga uma vez e esquece que está ligada.

• Onde: src/domain/llm/huggingface-official-publishers.ts:17-41 (HUGGINGFACE_OFFICIAL_PUBLISHERS/isOfficialPublisher), src/application/use-cases/llm/huggingface/search-huggingface-models.use-case.ts:28-39 (filtro por padrão), apps/web/src/components/HuggingFaceModelBrowser.tsx:190-203 (toggle + Alert de aviso)
• Teste: test/domain/huggingface/huggingface-official-publishers.spec.ts (reconhece publisher do allowlist; recusa reupload de terceiro; sensível a caixa; repoId sem / nunca casa), test/application/use-cases/llm/huggingface/search-huggingface-models.use-case.spec.ts (só oficiais por padrão; includeCommunity traz todos marcados), apps/web/src/components/HuggingFaceModelBrowser.test.tsx (toggle nasce desligado e só mostra o aviso quando ligado; busca respeita includeCommunity)
• ADR: 0115
• Origem: pedido do dono do produto

Configuração do runner pelo navegador (RN-464..466, ADR 0118)

RN-464 — Chave de dispositivo do runner: registro/revogação self-service; SEM visão de maintainer nesta rodada (corte declarado)

Revisada pela RN-687 (ADR 0203, 01/10): o fluxo do navegador foi APOSENTADO, e o POST .../runner-device-keys saiu com ele — junto com RegisterRunnerDeviceKeyUseCase e o teste dele, citados abaixo como eram. Ficam GET/DELETE e a revogação self-service; a chave nova nasce no terminal (RN-551) e quem a registra é o instalador (RN-552). As chaves de projeto já registradas continuam valendo e revogáveis.

runner_device_keys guarda só a chave PÚBLICA Ed25519 de um dispositivo do runner — gerada no navegador, nunca a privada. POST/DELETE .../runner-device-keys exigem papel mínimo developer e são autenticadas pelo JWT DE SESSÃO normal (diferente de runner-ticket: quem chama aqui é o navegador já logado registrando o próprio dispositivo, não o runner rodando sem sessão). RegisterRunnerDeviceKeyUseCase valida só a FORMA mínima da JWK (kty:"OKP", crv:"Ed25519", x presente) — a validação profunda (é mesmo um ponto Ed25519 válido) fica pro jose.importJWK no momento de usar, na RN-465. RevokeRunnerDeviceKeyUseCase é IDEMPOTENTE e escopado ao userId chamador — mesmo desenho de revogar() da RN-426 — e devolve 404 tanto para chave inexistente quanto para chave de outro usuário, mesma disciplina de não vazar existência.

Assimetria declarada com o PAT: ao contrário da RN-427 (maintainer revoga o PAT de QUALQUER usuário do projeto, resposta a incidente), a chave de dispositivo NÃO tem hoje uma rota equivalente de maintainer — só autorevogação. O docblock de RunnerDeviceKeysController declara isto explicitamente como corte desta rodada, não esquecimento: estender o mesmo padrão da RN-427 para chaves de dispositivo é trabalho futuro direto, se vier a ser pedido.

• Onde: src/db/schema/auth.ts:338 (runnerDeviceKeys), src/application/use-cases/auth/register-runner-device-key.use-case.ts, src/application/use-cases/auth/revoke-runner-device-key.use-case.ts, src/interfaces/http/runner/runner-device-keys.controller.ts
• Teste: test/application/use-cases/auth/register-runner-device-key.use-case.spec.ts, test/application/use-cases/auth/revoke-runner-device-key.use-case.spec.ts
• ADR: 0118
• Origem: pedido do dono do produto

RN-465 — POST .../runner-ticket aceita PAT OU chave de dispositivo (Ed25519, TTL ≤60s) — segunda forma de credencial de DISPOSITIVO, nunca dual-auth com JWT de sessão (distinção da RN-439)

Revisada pela RN-687 (ADR 0203, 01/10): nada desta RN mudou no guard — o PatAuthGuard continua aceitando o JWT de uma chave de PROJETO, e é por isso que um runner configurado pelo navegador antes do ADR 0203 não quebra. O que deixou de existir é criar uma chave de projeto NOVA: o navegador não gera mais o par.

PatAuthGuard ganhou um segundo caminho, ao lado do PAT (brb_...) inalterado: um bearer no formato de JWT compacto (três segmentos) é tratado como chave de dispositivo. O guard lê o kid do header (sem verificar assinatura ainda), busca a chave pública ATIVA correspondente em runner_device_keys, e só então verifica a assinatura EdDSA com jose.importJWK/jwtVerify. TTL curto e OBRIGATÓRIO: exp - iat não pode passar de 60s — checado contra a vida ASSINADA do token, não contra "agora", fechando a janela de replay de um JWT vazado a partir do momento em que foi assinado. userId/projectId usados para autorizar vêm sempre do REGISTRO salvo no banco, nunca de claim do JWT — o token só precisa provar posse da privada, nunca afirmar quem é o dono. projectId é conferido DUAS vezes (claim do JWT contra a rota, e projeto registrado da chave contra a rota) — mesma disciplina 401 vs 403 que o caminho PAT já usa: token/chave válida para o projeto ERRADO é categoria diferente de token/chave inválida. O runner assina esse JWT em assinarTicketComChaveDeDispositivo (apps/runner/src/auth.ts), com a JWK privada já CARREGADA em memória — nunca lendo arquivo ali, preservando a garantia "sem I/O de arquivo" de auth.ts (quem lê o arquivo é o módulo separado da RN-466).

Isto NÃO reabre a RN-439: a RN-439 fechou a garantia de que runner-ticket nunca aceita o JWT de LOGIN como credencial — ela continua de pé. A chave de dispositivo é um JWT DIFERENTE, autoassinado pelo próprio runner com uma chave que a api nunca viu a privada, sem sub de usuário nenhum — só uma segunda forma de provar "sou o dispositivo de tal usuário neste projeto", tão escopada quanto o PAT que ela complementa. Aceitar o JWT de sessão aqui faria RolesGuard/@RequireRole autorizar esse usuário pra tudo que o papel dele permite no resto da api, estourando o escopo runner:project:<id> — exatamente o que a RN-439 impediu.

• Onde: src/interfaces/http/auth/pat-auth.guard.ts:104-216 (autenticarChaveDeDispositivo), apps/runner/src/auth.ts:143-188 (assinarTicketComChaveDeDispositivo, obterTicketDoRunnerComCredencial)
• Teste: test/interfaces/pat-auth.guard.spec.ts (describe "chave de dispositivo (JWT EdDSA autoassinado, ao lado do PAT)" — caminho feliz, assinatura inválida, chave revogada, projectId do claim não bate com a rota, chave registrada em outro projeto, TTL longo demais, kid sem chave correspondente), apps/runner/src/auth.spec.ts (describe "assinarTicketComChaveDeDispositivo"/"obterTicketDoRunnerComCredencial")
• ADR: 0118
• Origem: pedido do dono do produto

Os dois tetos de rebaixamento em project_members (RN-472)

RN-472 — Ninguém rebaixa o owner do workspace, e ninguém rebaixa a si mesmo

A RN-471 registrou que ResolveEffectiveRoleUseCase.forProject é projectRole ?? workspaceRole — a linha de projeto SOBREPÕE a de workspace, nos dois sentidos. O que ela não guardou é a consequência: AddProjectMemberUseCase era um passthrough de uma linha para o upsert, e nenhum dos dois caminhos de escrita olhava para QUEM é o alvo. Qualquer maintainer podia (a) rebaixar o owner do workspace a viewer num projeto, tirando o dono do próprio projeto, e (b) se rebaixar sem poder desfazer, porque desfazer é a mesma rota, que pede maintainer.

A sobreposição FICA nos dois sentidos. forProject não muda. Restringir alguém num projeto sensível (workspace developer → viewer no projeto X) é capacidade deliberada, e "o maior dos dois" a eliminaria — o resolve-effective-role.use-case.spec.ts fixa a metade de subir desde a Fase 1. O que entra são DOIS tetos, e só eles:

O owner é workspace_members.role, nunca workspaces.created_by. Os dois existem em db/schema/iam.ts e não são a mesma coisa: created_by é fato histórico, e é o role que a autorização usa em todo o resto do sistema (forWorkspace é workspaces.findMemberRole; created_by não aparece em caminho de autorização nenhum). Ler created_by blindaria o criador que já transferiu a propriedade e deixaria descoberto o owner corrente que não criou nada — o buraco que o teto existe para fechar.

O teto 2 é "a si mesmo", sem limiar — não "abaixo de maintainer". A versão com limiar copiaria um número do @RequireRole do controller para dentro do domínio e envelheceria calada se a rota mudasse de mínimo. O preço, declarado: o owner que quisesse se pôr como maintainer no próprio projeto (movimento reversível) também é recusado, e passa a precisar de outro maintainer. Subir o próprio papel não é rebaixamento e continua passando.

Os tetos moram no CASO DE USO, com a regra no domínio — não no RolesGuard. O guard autoriza o CHAMADOR contra o @RequireRole da rota e não vê corpo (dto.role) nem alvo (dto.userId); os dois tetos são sobre o ALVO e sobre a relação ator↔alvo. A FORMA é a de domain/actions/decide.ts (RN-154/RN-418): função pura, mensagem ao lado da condição, sem chave de configuração. O que não se transporta é o desfecho — lá o teto vira require_approval sobre uma proposed_action de agente, aqui a chamada já é humana e síncrona e não há fila para onde mandá-la.

403, não 409 nem 400: é recusa de autorização — o chamador tem o papel da rota e não tem autoridade para este movimento. Esperar não muda nada (não é conflito de estado) e o corpo é válido (o mesmo corpo com outro alvo passaria).

O que os tetos NÃO cobrem, e segue possível: rebaixar outro maintainer que não é owner de workspace; auto-rebaixamento pela REMOÇÃO — RemoveProjectMemberUseCase não ganhou teto, e remover a própria linha derruba o efetivo para o papel de workspace, que é benigno quando o workspace segura e irreversível quando não segura (maintainer só pela linha de projeto, viewer no workspace); auto-PROMOÇÃO, que já era possível antes; e rebaixar o owner NO WORKSPACE (POST workspaces/:workspaceId/members segue sem teto). Os dois casos da remoção estão FIXADOS em teste, inclusive o aberto.

A tela fica para depois, e a recusa aparece. MembersSection calcula o teto 2 sozinha, mas não o teto 1: listProjectMembers devolve o papel da LINHA DE PROJETO, e o papel de workspace do alvo não está ao alcance do cliente. Meio gate seria um Select honesto sobre uma recusa e calado sobre a outra — a segunda fonte de papel contra a qual a RN-471 escreve. Enquanto isso, handleRoleChange já mostra mensagemDaApi(erro, …) num toast (RN-471), e é a frase da api que diz qual teto bateu.

• Onde: src/domain/iam/tetos-de-rebaixamento.ts (rebaixaOwnerDoWorkspace, ehAutoRebaixamento e as duas mensagens), src/application/use-cases/iam/add-project-member.use-case.ts (onde os dois são aplicados, antes do upsert), src/interfaces/http/iam/projects.controller.ts (o @CurrentUser() que dá o ator, e as duas descrições corrigidas), src/interfaces/http/iam/dto/add-member.dto.ts (a terceira), src/application/use-cases/iam/resolve-effective-role.use-case.ts (INTOCADO — projectRole ?? workspaceRole segue como está), src/db/schema/iam.ts (workspaces.created_by × workspace_members.role)
• Teste: test/application/use-cases/iam/tetos-de-rebaixamento.use-case.spec.ts (os dois tetos recusando; owner de workspace recebendo owner de projeto passa; auto-rebaixamento também quando o papel do ator vem da linha de projeto; auto-promoção passa; as DUAS capacidades legítimas preservadas — rebaixar outra pessoa, e viewer de workspace virando maintainer no projeto; auto-remoção permitida; e a remoção que ainda rebaixa quem a chamou, fixada como lacuna declarada)
• Origem: ADR 0127, sobre o achado da revisão da #444 registrado na RN-471

O kid é o vínculo, e a recusa tem nome (RN-475)

RN-477 — Provisionamento que falha DIZ que falhou, e a espera por ele tem teto

O provisionamento de repositório roda inteiro dentro do POST — não há worker nem fila atrás dele (a descrição de OpenAPI que prometia "continues in the background" estava errada e foi corrigida). Uma falha, portanto, já aconteceu quando a resposta chega. Esta RN é sobre a tela nunca afirmar "provisionando" sobre um trabalho que já terminou mal.

Toda falha vira estado DURÁVEL, e há dois caminhos que não viravam. O primeiro é step.check(), que ficava fora de todo try/catch no BootstrapRunner e faz IO de rede: um 401 de token expirado, um 403 ou um timeout subiam sem tocar a linha, que continuava pending com lastError: NULL. O segundo é a recusa em createRepo, que acontece antes de a linha existir — repo_bootstraps só nasce depois de o provider confirmar o repositório, então o projeto ficava com ZERO linha. Agora o primeiro grava status: 'failed' + lastError num lugar só (o catch da etapa) e emite bootstrap.step_failed; e o segundo é lido pelo endpoint de status a partir da proposed_action de git_repo_create que falhou.

A falha de criação NÃO inventa um passo. failedStep fica null: o repositório não chegou a existir, então nenhum dos seis passos do Gitflow foi tentado, e nomear um para preencher a frase seria trocar um silêncio por uma informação errada. A tela tem um título próprio para esse caso, sem {{step}}.

A tela mostra o motivo e oferece saída. O .catch(() => {}) de corpo vazio da ProvisioningPage — cujo comentário afirmava que "a falha aparece via bootstrapQuery", o que era falso nos dois caminhos acima — passa a guardar a mensagem da api e exibi-la. O botão "Tentar novamente" deixa de depender de status === 'provision_failed': ele aparece também quando o POST recusou, que é justamente quando não há status de falha para depender.

A espera tem TETO e três estados que não colapsam, exatamente como a RN-474 e pelo mesmo motivo: o poll de 1s era infinito. Passados 3 minutos sem convergir, a tela diz que parou de acompanhar, declara que isso não prova fracasso (o provisionamento roda dentro da requisição, e um provider lento pode ainda estar trabalhando) e oferece "procurar de novo" — que rearma a espera sem disparar um segundo POST, porque um segundo POST criaria mais uma sessão de bootstrap.

O card do dashboard sabe. O read model consulta as ações git_repo_create falhadas junto com as linhas de bootstrap, então um projeto que falhou antes de existir cursor deixa de aparecer sem badge nenhum — e o clique volta a levar para a tela de provisionamento, que só desviava em provision_failed.

• Onde: src/application/use-cases/git/bootstrap-runner.ts:181 (o catch da etapa, único lugar que declara o fracasso), src/domain/git/repo-bootstrap-status.ts:29 (o segundo argumento), src/application/use-cases/git/get-repo-bootstrap-status.use-case.ts:59 (a falha de criação lida da proposed_action), src/infrastructure/persistence/drizzle/projects-summary.repository.ts (o badge do card), apps/web/src/routes/ProvisioningPage.tsx (motivo, retry e teto)
• Teste: test/application/use-cases/git/provision-repository.use-case.spec.ts (falha no CHECK vira failed com motivo e evento; falha ao CRIAR não deixa linha mas o status reporta, com failedStep nulo), test/domain/git/repo-bootstrap-status.spec.ts (sem linha com falha de criação; com linha a falha antiga é ignorada; pending puro), apps/web/src/routes/ProvisioningPage.test.tsx (o motivo aparece; o retry existe sem provision_failed; a espera para e diz o que não sabe; título sem passo não inventa um)
• Origem: uso real do dono do produto — o provisionamento ficou "Pendente" para sempre, e a causa (permissão negada: /data/git-repos/exp001.git, um volume Docker de desenvolvimento que nascia root) estava gravada só em proposed_actions.execution_result, que nenhuma tela lê

A busca do RAG deixa rastro, e o rastro congela os pesos (RN-479..481)

RN-478 — O permissions.json mora onde a api ALCANÇA, o escopo do terminal aponta para o HOST

A raiz do projeto tinha uma derivação (projectScopeRoot) e dois consumidores com necessidades opostas. Isso estava certo enquanto os dois modos com pasta de usuário eram bind-mount; deixou de estar quando o modo runner nasceu (RN-423, ADR 0104), porque ele é deliberadamente sem bind-mount.

São duas derivações, e as duas moram no mesmo arquivo — a fonte continua única, o que se separou foi a pergunta. projectScopeRoot fica inalterada; permissionsFilePath é nova e diverge dela em um único ponto: no modo runner o arquivo vai para <PROJECT_WORKSPACES_ROOT>/<workspace_dir_name>/permissions.json, a raiz gerenciada, chaveada pelo nome que a RN-109 congela na criação. container e mounted não mudam — em mounted a pasta é bind-mount, e mover o arquivo quebraria projetos que já o têm em disco sem ganhar nada.

Por que a raiz gerenciada e não o disco do usuário, já que o código está lá: permissions.json é política, não código do projeto. Quem a lê é a api; o runner nunca a lê (recebe comando já aprovado) e o engine não a toca em ponto nenhum — todas as menções a ela em apps/engine/lib são comentário. Guardá-la na máquina do usuário a tornaria editável por quem ela restringe, e ilegível justamente quando o runner está desconectado, que é quando a decisão precisa continuar valendo.

O que isso corrigiu. A ativação da execução é a primeira escrita do arquivo, e ela fazia mkdir -p de um caminho do host dentro do container da api: EACCES: permission denied, mkdir '/home/<usuario>' → 500. A leitura degradava calada (ENOENT → EMPTY_PERMISSIONS_FILE), e é por isso que o efeito maior atravessou sem ser visto: em projeto runner o permissions.json nunca existiu, e decide() sempre caiu em require_approval por um arquivo que não estava lá.

Custo declarado: para projeto runner, o arquivo de política deixa de morar ao lado do código — quem o procurar na pasta do projeto não vai achar.

Recusa tipada, e 400 em vez de 500. Os dois throw new Error(...) da derivação viram LocalizacaoDeProjetoInvalidaError, no molde de CaminhoLocalInvalidoError: motivo legível em pt-BR, e ActivateExecutionUseCase o mapeia para 400. Uma linha de projeto incoerente (o par (modo, caminho) só se torna inválido sendo gravado por fora da criação) passa a dizer o que corrigir em vez de virar 500 sem corpo. A tela da Visão geral passa a mostrar essa mensagem — ela imprimia a constante "Não foi possível ativar a execução" enquanto o botão gêmeo do chat da sessão já usava mensagemDaApi: mesmo botão, dois diagnósticos.

A lacuna que FICA, declarada: o engine tem o mesmo defeito e ele não foi corrigido aqui. Engine.Actions.Workspace.ensure!/4 faz File.mkdir_p!(workspace_dir(project_id)), que em projeto runner é o caminho do host — o working tree do dev agent não tem onde nascer. Não vira 500 (o rescue de ensure_remoto/2 devolve {:error, …}), vira dev agent que não trabalha. Corrigi-lo isolado seria materializar worktree no host por um caminho que a execução em container substitui; o que muda agora é só a mensagem, que nomeia a causa em vez de repassar "permissão negada" cru.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts:231 (projectScopeRoot, inalterada) e :319 (permissionsFilePath, a segunda derivação), com LocalizacaoDeProjetoInvalidaError em :219, src/infrastructure/filesystem/fs-permissions-file-store.ts:77 (o único chamador do caminho do arquivo), src/application/use-cases/execution/activate-execution.use-case.ts:176 (o 400), src/interfaces/http/execution/execution.controller.ts:74 (a anotação de OpenAPI, que prometia 409 para dois casos que nunca foram 409), apps/web/src/routes/ProjectOverviewTab.tsx:485 (mensagemDaApi), apps/engine/lib/engine/actions/workspace.ex:61 (a mensagem da lacuna que fica)
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (permissionsFilePath nos três modos; e a não-regressão de projectScopeRoot continuar devolvendo o caminho do host em runner/mounted — unificar as duas de volta quebraria o ADR 0055), test/application/use-cases/execution/activate-execution.use-case.spec.ts (com o FsPermissionsFileStore DE VERDADE: o arquivo cai na raiz gerenciada e a pasta do host fica intocada; linha incoerente vira 400 que ensina), apps/web/src/routes/ProjectOverviewTab.test.tsx (a mensagem da api na tela), apps/engine/test/engine/actions/workspace_runner_test.exs (a falha nomeia a causa em projeto runner, e passa intacta nos outros modos)
• Origem: uso real do dono do produto — "Ativar execução" respondendo 500 no projeto exp002

RN-479 — Toda busca híbrida grava uma linha em rag_searches, com os pesos CONGELADOS; e a telemetria nunca derruba a busca

src/domain/rag/rag-search-limits.ts declara, no próprio comentário, que nenhum dos quatro números da busca híbrida (os dois pesos, o limiar e o número de candidatos) vem de calibração com dado real. Não vinha porque não havia como: a busca não deixava rastro nenhum — nem linha de tabela, nem evento. Calibrar sem medir seria trocar um chute por outro.

HybridSearchUseCase passa a gravar, a cada busca, o que ela devolveu (hits, com o rank 1-based de cada trecho), sob que condições (degraded/vector_available), quanto demorou (latency_ms), quem buscou (actor_kind/actor_id) e em que sessão — ou em NENHUMA.

Por que TABELA e não só evento de sessão. session_events.session_id é NOT NULL, e uma busca vinda da aba de RAG é de PROJETO: não tem sessão. Registrar só como evento perderia exatamente as buscas em que um humano olhou os scores e julgou, que são as que carregam o sinal de verdade. É a mesma classe de problema que forçou o corte do metering de embedding (ADR 0075, token_usage.session_id NOT NULL), e a saída é a mesma: tabela própria, com session_id NULLABLE.

pesos congelado na linha é o ponto. pesosVigentes() copia os valores do momento para dentro do registro — mesma disciplina do preço congelado no metering (ADR 0042) e da image_version em project_containers. Sem a cópia, a primeira calibração que mexer em RAG_SEARCH_WEIGHT_VECTOR faria toda a medição anterior passar a significar outra coisa, calada — e "melhorou depois da mudança?", a única pergunta que a telemetria existe para responder, ficaria impossível de fazer.

Gravar telemetria NUNCA derruba a busca, e também não falha CALADA. Quem pergunta não deveria perder a resposta porque o instrumento de medição caiu; e o repositório é explícito sobre falha que vira silêncio (RN-059). Então o INSERT que falha vira log com a origem classificada (infra, RN-023) e searchId: null na resposta — que não é o mesmo que "não houve resultado": é "não há a que anexar voto", e a tela precisa dos dois separados para não oferecer um controle que a api recusaria (RN-088).

degraded e vector_available são duas colunas de propósito, e a redundância de hoje (degraded = !vector_available) está declarada no schema em vez de escondida: vector_available é um fato sobre o PROVIDER — é ele que faz medir:rag reprovar —, e degraded é a palavra do CONTRATO com o engine, cuja definição pode crescer.

• Onde: src/domain/rag/rag-telemetry.ts (pesosVigentes, RagSearchHitTelemetry), src/db/schema/rag.ts (ragSearches), src/application/use-cases/rag/hybrid-search.use-case.ts (registrarBusca), src/infrastructure/persistence/drizzle/rag-telemetry.repository.ts
• Teste: test/application/use-cases/rag/hybrid-search.use-case.spec.ts (a linha gravada com rank e pesos; os pesos serem CÓPIA e não o mesmo objeto; a busca da aba sem sessão; e o CASO DE FALHA — insert que falha não derruba a busca e devolve searchId: null)
• ADR: 0129 — por que é TABELA e não evento, e por que os pesos vão congelados; 0080, cujos números esta RN não revisa: ela dá o instrumento para revisá-los depois
• Origem: plano do dono do produto, Parte 2 / Etapa 1

RN-480 — O voto sobre um trecho é o único sinal de VERDADE da medição, e ele exige a referência que a busca devolveu

Latência e taxa de degradação dizem se a busca RODOU; só o voto diz se ela ACERTOU. rag_feedback guarda esse voto — dois valores (util/irrelevante) e não uma escala de 1 a 5, porque escala fina convida a diferenças de régua entre quem vota que nenhuma agregação recupera depois.

A referência é obrigatória, e as duas recusas são 400 que ENSINAM. searchId que não existe naquele projeto, e chunkId que não estava entre os hits daquela busca, são recusados antes de qualquer escrita. Não é rigor decorativo: o rank do trecho votado é o que separa dois diagnósticos que a precision@1 confunde — índice pobre não devolve o trecho certo em posição nenhuma, peso errado devolve o trecho certo em rank 7. Voto sem rank produz número sem significado, que é pior que número nenhum.

A recusa vale nos dois caminhos: pela aba vira 400 na tela; pelo agente vira tool-result de erro que o modelo pode corrigir na iteração seguinte (RN-061/RN-163), nunca crash.

Um voto por ator por trecho por busca (unique (search_id, chunk_id, actor_id), com onConflictDoUpdate): mudar de ideia sobrescreve o próprio voto. Sem a trava, quem clicasse duas vezes pesaria o dobro na precision@k e a métrica passaria a medir entusiasmo.

O papel é viewer, o MESMO de search — quem pode ler o resultado é quem pode julgá-lo (RN-102: o mínimo é do endpoint, e votar não gasta nem configura nada). A ferramenta do agente é :direct, nunca proposed_action: dar nota a um trecho não é efeito externo, e transformá-la em ação a aprovar encheria a fila de ruído.

• Onde: src/db/schema/rag.ts (ragFeedback, ragVerdictEnum), src/application/use-cases/rag/record-rag-feedback.use-case.ts, apps/engine/lib/engine/harness/tools/rag_feedback.ex, apps/web/src/components/rag/RagCitationCard.tsx (os dois controles, onde o score já está)
• Teste: test/application/use-cases/rag/record-rag-feedback.use-case.spec.ts (o rank devolvido; e os três CASOS DE FALHA — searchId desconhecido, chunkId fora dos hits, busca de outro projeto), apps/engine/test/engine/harness/tools/rag_feedback_test.exs (a recusa voltando como tool-result com a mensagem da api, nunca crash; :direct; e o registro nos seis agentes que já tinham rag_search), apps/web/src/components/rag/RagCitationCard.test.tsx (os três estados do controle, e a ausência dele sem searchId), test/scripts/medir-rag.spec.ts (precision@k sobre o julgado)
• ADR: 0129
• Origem: plano do dono do produto, Parte 2 / Etapa 1

RN-486 — Estado REGISTRADO e estado OBSERVADO nunca se fundem, e "não olhei" tem motivo próprio

project_containers guarda o que foi REGISTRADO. O daemon responde o que é OBSERVADO. Antes do broker a tabela não tinha como mentir (container_id era sempre NULL); agora tem, e a leitura diz isso em vez de escondê-lo.

A rota de ciclo de vida devolve os dois, separados. Container morto por fora aparece como registrado running e observado exited, e é assim que tem de aparecer. A reconciliação é NA LEITURA, não um daemon de fundo.

observado: null sozinho não é resposta. Ele significa duas coisas diferentes, e naoObservado é o que as separa: null ali quer dizer que a observação ACONTECEU e voltou vazia — a afirmação positiva "olhei e não há container" —, enquanto broker-nao-configurado, broker-sem-resposta e broker-recusou querem dizer que não deu para olhar, cada um com um conserto diferente. Herdar o estado registrado nesses três casos é exatamente o que a RN-468 proíbe: sinal de ambiente diz o que SABE, e proxy não vira garantia.

Nenhuma recusa do broker derruba a leitura. O ciclo de vida registrado é informação legítima por si só e existia antes do broker; perdê-lo porque o broker está fora trocaria um dado que temos por um que não temos.

Lacuna declarada: container órfão de projeto que nunca teve linha de ciclo de vida não aparece nessa rota — ela lê o registrado primeiro. Quem acha órfão é a varredura por brabo.managed=true, e a página que a consome ainda não existe.

• Onde: src/application/use-cases/containers/obter-estado-observado-do-container.use-case.ts (os três motivos e o null que não é motivo), src/interfaces/http/containers/containers.controller.ts (a rota que devolve os dois), src/application/ports/container-broker.port.ts (o null de inspect é ausência; a falha LANÇA)
• Teste: test/application/use-cases/containers/spec-e-observacao-de-container.use-case.spec.ts ("olhei e não há" e "não consegui olhar" não colapsam; sem BROKER_URL o broker nem é chamado; recusa vira motivo com detalhe, nunca exceção)
• ADR: 0130

RN-487 — O Arquiteto roteia módulo por módulo, mas só CANDIDATA — quem elege é a Infra

route_modules_to_infra produz UMA lista — um item {modulo, imagemCandidata, porque} por módulo do module_map vigente — e ela vira o evento artifact.module_routing, sem tabela: mesmo desenho de artifact.module_map/ artifact.project_image/artifact.c4_diagram, o evento É o artefato.

A imagem candidata passa pela MESMA regra de choose_project_image, aplicada por item. validarDecisaoDeImagem já recusa imagem sem tag/digest explícito, latest, e rationale com menos de 10 caracteres — reimplementar essa regra por módulo criaria uma segunda versão dela para divergir da primeira cedo ou tarde. validarRoteamento (domain/architecture/module-routing.ts) delega, e só acrescenta o que é PRÓPRIO da lista: vazia é recusada (não é uma decisão), e módulo repetido também (duas imagens para o mesmo módulo são ambíguas — qual vale?).

Módulo fora do module_map vigente é recusado nomeando os módulos VÁLIDOS, mesma régua de AssignStoryModulesUseCase (missingModules): listar só o que está errado obrigaria o modelo a adivinhar contra um mapa que ele não pode reler; listar os nomes certos encerra a busca na primeira recusa.

Sem module_map vigente, não há módulo — recusado com 400, nunca inventado. É a mesma recusa de create_c4_diagram quando falta module_map, e pelo mesmo motivo: não há módulo, não há infra para rotear. O build_kickoff/1 do ArquitetoServer — o ÚNICO lugar de onde o modelo aprende a ORDEM das ferramentas — lista route_modules_to_infra como o passo que segue create_module_map.

:direct, nunca proposed_action. Rotear não tem efeito externo — não sobe container, não muda nada fora do event log — e é decisão INTERNA de arquitetura, do mesmo calibre de choose_project_image/create_c4_diagram. Colocar isto na fila de aprovação misturaria um rascunho que a Infra ainda vai revisar com decisões que já têm efeito real.

Arquiteto candidata, Infra elege — e esta entrega é só a metade que candidata. A metade que ELEGE entre as candidaturas (ou recusa todas) é do Infra Lead, com proposed_action própria, num PR à parte. O que existe aqui é a lista auditável no event log, antes de a Infra ter ferramenta para agir sobre ela — mesmo sequenciamento que já valeu para o module_map existir antes de create_c4_diagram precisar dele.

• Onde: src/domain/architecture/module-routing.ts (validarRoteamento, EVENTO_MODULE_ROUTING), src/application/use-cases/architecture/route-modules-to-infra.use-case.ts, src/application/use-cases/architecture/get-module-routing.use-case.ts, src/interfaces/http/internal/internal-sessions.controller.ts (POST .../module-routing), apps/engine/lib/engine/harness/tools/route_modules_to_infra.ex, apps/engine/lib/engine/agents/arquiteto_server.ex (build_kickoff/1, passo 4)
• Teste: test/domain/architecture/module-routing.spec.ts (lista vazia, módulo repetido, e a delegação a validarDecisaoDeImagem — latest e rationale curto), test/application/use-cases/architecture/route-modules-to-infra.use-case.spec.ts (caminho feliz com dois módulos; sem module_map vigente; módulo fora do mapa; versionamento ao rotear de novo), apps/engine/test/engine/harness/tools/route_modules_to_infra_test.exs (:direct; normalização das chaves do tool call; recusa da api virando tool-result de erro, nunca crash — RN-061)
• ADR: 0131
• Origem: plano do dono do produto, Parte 1 / PR 1.4

RN-490 — O golden-set de acerto do RAG mede por CAMINHO DE ARQUIVO, no TOP-5, nunca por chunk exato ou rank 1

O gate rag-acertivo (config/gates.yml) mede se a busca híbrida devolve o arquivo certo para 17 perguntas compostas a partir de RNs/ADRs reais deste repositório (golden-set, molde do ADR 0123 aplicado ao RAG). O critério de "acertou" tem duas decisões deliberadas, e as duas evitam medir a pergunta errada:

• Caminho de arquivo, nunca chunk exato. O chunking (1200/150) é justamente um dos parâmetros que este programa existe para poder revisar (ADR 0080) — travar o golden-set no chunk faria QUALQUER ajuste de chunking quebrar os 17 casos, mesmo quando o arquivo certo continuasse sendo recuperado.
• TOP-5, nunca só a primeira posição. É assim que o produto usa o resultado: o Chat RAG cita VÁRIOS trechos por resposta (RagCitationCard, plural), não só o primeiro. Medir contra rank 1 mediria uma pergunta que a UI não faz. 5, e não o RAG_SEARCH_RESULT_LIMIT (10) da rota real, para não testar um k mais folgado que a maioria das buscas reais usa.

O critério é função PURA (acertouCaminhoEsperado/rankDoCaminhoEsperado), consumida pelo seed (seed-golden-set-rag.ts) e testada isolada — a mesma disciplina de gate-registry.ts: a decisão de "isto bateu" não depende de como o resultado chegou.

O golden-set roda manual (mix golden_set.rag), nunca em mix test comum — mesma decisão já registrada para o golden-set do QA (ADR 0123): sem segredo de LLM de API ou infra nova, não havia como rodar Ollama de verdade em CI. Excluído por tag PERMANENTE (:golden_set_rag) em test_helper.exs, nunca por detecção de "Ollama alcançável" — mesmo motivo do lado QA: esta máquina já tem Ollama de pé o tempo todo. O piso é RATCHET (>=, nunca >), contagem e não porcentagem, chaveado pelo modelo de EMBEDDING (nomic-embed-text, hoje o único que o produto suporta) e escrito só por humano.

Revisada pela RN-498: "não há como rodar Ollama de verdade em CI" era verdade na Etapa 2 e deixou de ser na Etapa 3 (ADR 0138) — um workflow dedicado, agendado, agora roda mix golden_set.rag de verdade contra um Ollama real em CI. A exclusão permanente em test_helper.exs acima CONTINUA valendo como está: ela protege o mix test comum (e a máquina de qualquer desenvolvedor com Ollama de pé), nunca o novo workflow, que invoca a tag explicitamente, do mesmo jeito que sempre foi preciso.

• Onde: src/domain/rag/golden-set-criterio.ts, scripts/seed-golden-set-rag.ts, apps/engine/test/engine/rag/rag_golden_test.exs, apps/engine/test/fixtures/golden_set_rag/floor.json
• Teste: test/domain/rag/golden-set-criterio.spec.ts
• ADR: 0132
• Origem: plano do dono do produto, Parte 2 / Etapa 2

RN-493 — Terminal dentro do container real ganha PISO de auto-aprovação, sem tocar nos tetos absolutos

Quando containerExecutionActive é verdadeiro (o mesmo running REGISTRADO da RN-492, consultado por ProposeActionUseCase só para actionType === 'terminal' em projeto execution_mode: container), o valor INICIAL de current dentro de decide() deixa de ser require_approval e passa a ser auto_approve — um PISO, não um teto novo: os estágios que seguem (agent_autonomy, permissions.json) continuam podendo REBAIXAR esse piso exatamente como já rebaixavam o require_approval default (um deny explícito ou um ask casando o comando vencem do mesmo jeito), e os CINCO tetos absolutos de decide.ts (escopo, git push/comando privilegiado, merge protegido, instruction_patch, paralelismo) continuam rodando por CIMA, byte a byte como estavam — inclusive quando o auto_approve veio do piso, e não de uma regra explícita.

A justificativa é uma SEGUNDA fronteira, não a ausência da primeira. O escopo léxico de terminal (terminalNoEscopo, ADR 0055) continua rodando sobre os MESMOS caminhos de HOST de sempre — o cwd/command que chegam em decide() NUNCA são traduzidos pra /work (essa tradução acontece só depois, no engine — RN-492). Dentro do container real, some uma fronteira MAIS forte por cima da léxica: o mount namespace do Docker, que o processo fisicamente não atravessa, somado à validação de /work que o broker já faz (DiretorioForaDoEscopoError). É defesa em profundidade — o escopo léxico não é substituído, é redundante.

• Onde: src/domain/actions/decide.ts (DecideContext.containerExecutionActive, o current inicial condicional), src/application/use-cases/actions/propose-action.use-case.ts
• Teste: test/domain/actions/decide.spec.ts (describe "decide — piso do container ativo do projeto": auto-aprova sem regra nenhuma; inalterado sem containerExecutionActive; não afeta ação não-terminal; agent_autonomy/permissions.json explícitos rebaixam o piso; IAM insuficiente nega antes do piso; escopo continua vencendo por cima; git push/sudo continuam require_approval), test/application/use-cases/actions/propose-action.use-case.spec.ts (describe "piso do container ativo": terminal auto-aprova e EXECUTA com container running; não afeta container_start; sem linha running, inalterado; deny embutido/git push/sudo continuam vencendo)
• ADR: 0134
• Origem: plano do dono do produto, Parte 1 / PR 1.6

RN-495 — container_stop/container_remove nascem como proposed_action, e só container_remove entra no teto absoluto

Fecha a lacuna que o comentário de ContainerBrokerPort (ADR 0130) e o CLAUDE.md declaravam desde o PR 1.5: stop/remove tinham CLIENTE HTTP pronto (HttpContainerBrokerClient.stop/.remove) e ZERO chamador — a página global de containers (/containers, RN-496) é o primeiro. Os dois NUNCA são ação de agente: só um humano clicando "Parar"/"Remover" numa linha da tela propõe.

container_stop segue o calibre EXATO de container_start (RN-491): maintainer, require_approval por padrão, PODE ser configurado auto_approve (nunca semeado) — ExecuteContainerStopUseCase pede ao broker para parar e, só quando o registrado ainda dizia running, registra a transição running -> stopped (container-lifecycle.ts). Registrado já stopped/provisioning/failed: o broker é chamado mesmo assim (é idempotente — parar o que já não está rodando é no-op do lado do Docker), mas NENHUMA transição é gravada — inventar uma que a máquina de estados não descreveu de verdade seria o mesmo defeito que a RN-486 já nomeou para o observado.

container_remove é o MAIS destrutivo dos três — descarta o container e exige reprovisionar do zero (container-lifecycle.ts: removed só sai provisionando de novo, nunca "voltando à vida") — e por isso entra no MESMO teto absoluto de decide.ts que git push/comando privilegiado (RN-418): nunca auto-aprovável, nem por agent_autonomy nem por permissions.json, mesmo com "modo automático" ligado. A fresta de "sempre permitir" é fechada NA FONTE, pelo mesmo mecanismo de RN-418: ApproveAlwaysActionUseCase recusa (400) gravar o padrão para container_remove — o clique inteiro é recusado, e quem quer remover aprova a instância pelo fluxo normal (POST .../approve). No web, ApprovalCard.podeSemprePermitir esconde o botão "sempre permitir" para container_remove, mesma régua que já vale para instruction_patch.

ContainerBrokerPort.remove é docker rm --force — remove mesmo um container running, numa chamada só. A máquina de estados NÃO tem running -> removed direto (só running -> stopped/failed, e só DAÍ para removed): ExecuteContainerRemoveUseCase registra os DOIS hops quando o registrado ainda dizia running (stopped, depois removed), refletindo o que aconteceu de verdade do lado do Docker sem alargar a máquina de estados por um atalho que só existiria aqui.

Nenhum dos dois decide imagem — ao contrário de container_start, que reusa DecidirImagemDoProjetoUseCase para emitir uma nova versão de artifact.project_image. stop/remove só pedem ao broker para agir sobre o container que já existe.

• Onde: src/domain/actions/decide.ts (ACTION_TYPES, MIN_ROLE_FOR_ACTION_TYPE, teto absoluto de container_remove), src/domain/actions/command-matcher.ts (ACTION_TYPE_LABELS), src/domain/containers/container-stop-remove-execution-result.ts, src/application/use-cases/actions/execute-container-stop.use-case.ts, src/application/use-cases/actions/execute-container-remove.use-case.ts, src/application/use-cases/actions/approve-action.use-case.ts, src/application/use-cases/actions/propose-action.use-case.ts, src/application/use-cases/actions/approve-always-action.use-case.ts, apps/web/src/lib/aprovacoes.ts, apps/web/src/components/ApprovalCard.tsx (podeSemprePermitir)
• Teste: test/domain/actions/decide.spec.ts ("container_stop, a página global de containers" — CONSEGUE auto_approve; "teto de container_remove" — NUNCA consegue), test/application/use-cases/actions/execute-container-stop.use-case.spec.ts, test/application/use-cases/actions/execute-container-remove.use-case.spec.ts (os dois hops a partir de running; um hop só a partir de stopped/ failed; idempotência; BrokerRecusouError/BrokerIndisponivelError nunca propagam), test/application/use-cases/actions/approve-always-action.use-case.spec.ts, apps/web/src/lib/aprovacoes.test.ts, apps/web/src/routes/ContainersPage.test.tsx
• Decisão arquitetural: ADR 0136
• Origem: plano do dono do produto, Parte 1 / PR 1.8

RN-496 — A página global de containers pergunta ao broker com TETO, e nunca funde registrado com observado

Mesma família da RN-486/RN-468, aplicada a uma tela NOVA: GET workspaces/:workspaceId/containers (/containers, cross-projeto) devolve uma linha por projeto do workspace que já tem project_containers (ContainersOverviewRepository, TRÊS consultas em lote, nunca uma por projeto — mesmo espírito de ProjectsSummaryRepository), mas perguntar ao broker o estado OBSERVADO é uma chamada de REDE por projeto, e não cabe numa consulta SQL.

O teto (ADR 0060) é por DUAS réguas, não uma. Primeiro, só linhas provisioning/running são ELEGÍVEIS — um container stopped/failed/ removed não precisa de confirmação do daemon para a tela fazer sentido (ninguém espera que ele esteja de pé). Segundo, entre as elegíveis, no máximo TETO_DE_VERIFICACOES_POR_CARGA (20, revisável) são perguntadas ao broker POR CARREGAMENTO — em paralelo, nunca em série. O que sobra de fora de qualquer uma das duas réguas carrega naoVerificado (fora_do_escopo_da_verificacao | teto_de_verificacoes_atingido), um campo PRÓPRIO da tela — nunca confundido com naoObservado (broker-nao-configurado/broker-sem-resposta/broker-recusou), que é sobre o broker TER SIDO perguntado e não ter respondido. Uma linha fora do teto tem observado/naoObservado/detalheDaObservacao todos null: a tela nunca inventa uma resposta que o broker não deu.

A leitura da imagem é a CONGELADA, não a vigente. imageVersion em project_containers aponta para a versão de artifact.project_image que estava vigente quando a linha nasceu — o Arquiteto pode ter revisado a decisão DEPOIS. A tela resolve a imagem-texto buscando o evento artifact.project_image cuja versão bate com imageVersion (decisaoNaVersao, domain/containers/project-container.ts), nunca a decisão mais recente — mostrar a mais recente mentiria sobre qual imagem o container que subiu de verdade usa. null quando o evento daquela versão não é encontrado (nunca inventada).

A proposed_action pendente de container (se houver) viaja na MESMA leitura em lote, batida por projectId IN (...) como as outras duas — é o que permite a tela trocar os três botões de ação pelo ApprovalCard inline sem uma quarta consulta por projeto.

• Onde: src/application/ports/containers-overview-repository.port.ts, src/infrastructure/persistence/drizzle/containers-overview.repository.ts, src/application/use-cases/containers/obter-visao-geral-de-containers.use-case.ts, src/domain/containers/project-container.ts (decisaoNaVersao, versaoDoPayload), src/interfaces/http/containers/containers-overview.controller.ts, apps/web/src/routes/ContainersPage.tsx, apps/web/src/lib/hooks.ts (useContainersOverview)
• Teste: test/infrastructure/persistence/drizzle/containers-overview.repository.spec.ts (só entra projeto com project_containers; imagem CONGELADA, não a vigente; acaoPendente cross-sessão; número de consultas não cresce com a quantidade de projetos), test/application/use-cases/containers/obter-visao-geral-de-containers.use-case.spec.ts (elegibilidade por status; teto por carga; naoObservado nunca confundido com naoVerificado), test/interfaces/http/containers/containers-overview.controller.spec.ts, apps/web/src/routes/ContainersPage.test.tsx
• Decisão arquitetural: ADR 0136
• Origem: plano do dono do produto, Parte 1 / PR 1.8

A base única dos projetos montados (RN-500)

RN-500 — Existe UMA base para os projetos montados, ela é montada por identidade, e ausente quer dizer "não ofereça o modo"

BRABO_PROJECTS_BASE é a única pasta do computador do operador que os containers do Brabo enxergam. Ela é montada por identidade ($X:$X) nos serviços api e engine, o que significa que o caminho é o MESMO no host e dentro dos dois containers.

A identidade não é preferência de estilo. A string de projects.workspace_path é digitada pelo usuário e mostrada de volta a ele; com host ≠ container o produto teria que escolher qual das duas guardar, e qualquer escolha faz a tela mentir para alguém. E é ela que faz projectScopeRoot (api) e Engine.Actions.Workspace.workspace_dir/2 (engine) continuarem corretos sem uma linha de código nova — o discriminador da barra inicial segue valendo, e o escopo de terminal do ADR 0055 continua autorizando exatamente a pasta que o usuário vê.

Ausente é estado NORMAL, não erro. baseDeProjetos() devolve null quando a variável não está definida ou está vazia, e NUNCA lança. null viaja até o cliente por GET /workspaces/:workspaceId/projects-base (maintainer, o mesmo mínimo de POST .../projects, porque é para decidir o que aquela rota oferece que o valor existe) e é assim que a criação de projeto aprende a não oferecer o modo Pasta montada. Oferecer um modo que a instalação não honra produz um projeto que trava depois, na primeira ferramenta do primeiro agente, longe da tela onde a decisão foi tomada — é a mesma lição da RN-170.

dentroDaBaseDeProjetos reusa dentroDoEscopo, a mesma função do escopo de terminal, e não uma comparação de prefixo escrita de novo: a armadilha é exatamente a que ela já resolve — /home/voce/brabo2 não está dentro de /home/voce/brabo, embora a string comece igual. A própria base conta como dentro; com base null, nada está dentro.

A base é variável PRÓPRIA, nunca PROJECT_WORKSPACES_HOST_DIR. Os três motivos estão no ADR, e o primeiro tem consequência de dados: workspace gerenciado é nomeado por workspace_dir_name (UNIQUE) e projeto montado é nomeado pelo usuário, então <base>/loja e um projeto container com workspace_dir_name = loja cairiam na MESMA pasta física, com init_from_bare! dando git init dentro do projeto do outro.

A guarda do checkout mora no preflight, e é o único lugar onde ela é possível. pnpm dev recusa subir quando a base se sobrepõe ao checkout do Brabo, nos dois sentidos. A api não consegue fazer essa checagem: ela compara contra process.cwd(), que dentro do container dela é /workspace, e nunca vê o caminho real no disco. Sem essa guarda, quem clona o Brabo em $HOME/brabo e aponta a base para lá passa por toda validação existente e faz os dev agents executarem dentro da árvore do próprio produto — a falha do ADR 0055 entrando por uma porta que ele não vigia.

O que esta RN NÃO faz: ela não exige que um projeto mounted esteja dentro da base. caminhoDeWorkspaceLocalValido e projectScopeRoot ficam intactos — aquele predicado roda em toda LEITURA, e projeto montado legado fora da base passaria a explodir ao ser lido. A base é regra de CRIAÇÃO e CONVERSÃO, e entra na RN seguinte.

• Onde: src/infrastructure/filesystem/project-workspaces-root.ts:67 (baseDeProjetos) e :92 (dentroDaBaseDeProjetos); src/interfaces/http/iam/workspaces.controller.ts:197 (GET :workspaceId/projects-base); scripts/dev/base-de-projetos.mjs e a chamada em scripts/dev/preflight.mjs; docker/docker-compose.yml e docker/docker-compose.prod.yml (serviços api, engine, broker)
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (describe('baseDeProjetos / dentroDaBaseDeProjetos')) e scripts/dev/base-de-projetos.spec.ts
• ADR: 0141
• Origem: plano do dono do produto, PR 1

A pasta montada nasce quando o container sobe (RN-501)

RN-501 — mounted valida só o LÉXICO e a base na criação; a pasta é MATERIALIZADA depois, por quem tem autoridade sobre o disco

A criação de um projeto mounted deixou de tocar disco. Ela exige duas coisas, e as duas são léxicas:

1. o mesmo predicado que runner já usava (caminhoDeWorkspaceLocalValido) — absoluto, sem .., fora da raiz e das pastas de sistema, sem se sobrepor ao checkout do Brabo (RN-422/RN-423);
2. estar dentro de BRABO_PROJECTS_BASE (RN-500), que é a única pasta do computador que os containers da api e do engine enxergam.

O projeto nasce com workspaceVerifiedAt: null, exatamente como um runner.

Por que adiar. O requisito é do dono do produto e é literal: "se for Pasta montada, o bind-mount deve ser criado APÓS a decisão do arquiteto". A validação de disco rodava na CRIAÇÃO, que é a primeira tela do fluxo, e a decisão do Arquiteto acontece muitas sessões depois — exigir a pasta pronta na criação é exigi-la antes de existir decisão nenhuma. E é o que impedia mounted de ser escolha de primeira classe: um caminho SUGERIDO pelo assistente (<base>/<slug>) é, por construção, um caminho que ainda não existe.

A diferença entre mounted e runner nunca foi o que conta como caminho válido — é quando e quem confirma o disco. No runner é o CLI conectando; no mounted é a materialização.

Sem base configurada, o MODO não está disponível. A recusa diz isso, com o nome da variável e o que o operador precisa fazer — nunca finge que o caminho é que estava errado. Fora da base, a recusa nomeia a base e sugere <base>/<nome que a pessoa pediu>, nunca a base pelada, que ensinaria a colocar o projeto na raiz de todos eles. As duas mensagens saem de UMA fonte (motivoDeForaDaBaseDeProjetos), porque as duas portas que aplicam a regra — criação/conversão e materialização — recusam pelo mesmo motivo.

A materialização (materializarWorkspaceMontado) é mkdir -p mais as três perguntas de disco de sempre (existe? é pasta? dá para escrever?), com a recusa por estar fora da base antes do mkdir — senão um caminho gravado por fora do produto faria a api criar pasta em qualquer lugar que ela alcança. Dois chamadores:

• ExecuteContainerStartUseCase — o normal. Quando a Infra sobe o container, a pasta é criada, provada gravável, e workspace_verified_at é carimbado pelo MESMO caminho que ConfirmProjectWorkspaceUseCase usa. Falhar é failed NOMEADO, nunca throw nem 500 — mesma disciplina de BrokerIndisponivelError/RunnerNaoConectadoError —, e o ciclo de vida não chega a ser marcado provisioning: marcá-lo e só então descobrir que não dá para escrever deixaria project_containers afirmando um estado que nunca existiu. A mensagem nomeia a variável, o caminho, a causa provável (dono da pasta no host; as imagens rodam non-root, ADR 0024) e o próximo passo ("aprove container_start de novo").
• ConvertProjectExecutionModeUseCase — a exceção, declarada. A conversão não tem passo de container onde pendurar o trabalho, e logo em seguida ela MOVE o permissions.json para permissionsFilePath(localNova), que em mounted é a pasta do usuário. Mover arquivo para dentro de pasta inexistente falha, então aqui mkdir-na-decisão é o certo — antes da transação, para que a recusa não deixe transação aberta, e virando 400.

O que esta RN NÃO faz, e é a regressão mais fácil de causar. A regra da base não entra em caminhoDeWorkspaceLocalValido. Esse predicado roda em TODA LEITURA, por projectScopeRoot (escopo de terminal, permissions.json, aba Code), e um projeto mounted LEGADO — criado quando o bind-mount era uma linha de compose por projeto, portanto fora da base — passaria a explodir com LocalizacaoDeProjetoInvalidaError ao ser simplesmente lido. A base é regra de criação e conversão; o léxico é para sempre.

Sem migration, e o CHECK do banco fica intacto. mounted continua gravando workspace_path NÃO-nulo, então (execution_mode <> 'container') = (workspace_path IS NOT NULL) segue satisfeito. Adiar a verificação nunca toca o invariante de pareamento.

Consequência declarada: entre criar o projeto e subir o container, workspace_path aponta para uma pasta que pode não existir. Nada quebra (projectScopeRoot é léxico; permissions.json degrada para EMPTY_PERMISSIONS_FILE, que é require_approval em tudo), mas a tela precisa DIZER — uma tela que mostra um caminho sem dizer que ele ainda não existe é uma tela afirmando o que não sabe.

• Onde: src/application/services/workspace-location.ts:93 (léxico) e :108 (base); src/infrastructure/filesystem/project-workspaces-root.ts:575 (motivoDeForaDaBaseDeProjetos), :624 (validarWorkspaceMontadoEmDisco, o antigo validarCaminhoDeWorkspaceLocal) e :705 (materializarWorkspaceMontado); src/application/use-cases/iam/convert-project-execution-mode.use-case.ts:139; src/application/use-cases/actions/execute-container-start.use-case.ts:133 e :334
• Teste: test/infrastructure/filesystem/project-workspaces-root.spec.ts (describe('materializarWorkspaceMontado') e a não-regressão "projeto mounted LEGADO, FORA da base, continua resolvendo sem lançar"); test/application/use-cases/iam/create-project-modo-de-workspace.spec.ts (describe('mounted valida só o léxico + a base na criação')); test/application/use-cases/iam/convert-project-execution-mode.use-case.spec.ts; test/application/use-cases/actions/execute-container-start.use-case.spec.ts (describe "ExecuteContainerStartUseCase — materialização do mounted")
• ADR: 0142, que referencia 0141
• Origem: plano do dono do produto, PR 2

Projeto montado sobe container pelo BROKER (RN-503)

RN-503 — Projeto mounted sobe container pelo BROKER, e o que atravessa a rede é um localizador discriminado — nunca um caminho absoluto

Um projeto no modo Pasta montada não conseguia container nenhum até aqui, e por dois bloqueios independentes: ExecuteContainerStartUseCase mandava todo modo diferente de container para o RUNNER (que exige um brabo-runner conectado), e o broker recusava na fonte qualquer modo que não fosse container, com ModoDeExecucaoNaoSuportadoError.

Os dois existiam pela mesma razão de GEOMETRIA, não pelo nome do modo: a pasta de um projeto montado ficava num lugar arbitrário do disco do operador, que o daemon Docker do servidor não tinha por que enxergar. O ADR 0141 (RN-500) mudou essa geometria — todo projeto montado passa a morar sob uma base montada por identidade —, e é isso, e só isso, que esta regra colhe.

A ramificação passa a ser por DESTINO, não por modo. container e mounted vão ao BROKER; só runner vai ao runner, porque a pasta dele continua numa máquina que este servidor não alcança (ADR 0137). Vale igual para as três ações de ciclo de vida — container_start, container_stop e container_remove: elas TÊM de mudar juntas, senão o container de um projeto montado sobe no servidor e o pedido de parar vai procurá-lo na máquina do usuário, deixando de pé, sem forma de parar, o que está de pé.

O invariante do ADR 0130 não se mexe: nenhum caminho absoluto atravessa a rede. O broker é root-equivalente no host e COMPÕE o -v a partir das raízes DELE; se a api mandasse /home/voce/brabo/loja, a contenção do bind-mount passaria a depender de a api estar correta, que é exatamente a dependência que o broker existe para não ter. O que muda é que agora existem DUAS raízes do lado de lá, então a spec precisa DIZER contra qual delas o pedaço relativo vale — e diz, num localizador discriminado:

Três estados e não dois, porque o terceiro existe de verdade e tem dois consertos diferentes: projeto runner (a pasta está noutra máquina — o conserto é o runner, do lado de lá) e projeto mounted LEGADO criado fora da base (o conserto é mover a pasta). Colapsá-los num null faria a mesma ausência mandar quem opera para o lugar errado. A pasta que É a própria base também cai aqui, e não vira segmento vazio: <raiz>/ montaria a base inteira — a pasta de TODOS os projetos montados — dentro do container de um só.

A falta de uma raiz nunca é suprida pela outra. Sem BRABO_PROJECTS_HOST_BASE, um start de projeto montado recusa nomeando a variável (BaseDeProjetosNaoConfiguradaError, origem infra, 503) e não toca container nenhum — mesmo molde de RaizDeWorkspacesNaoConfiguradaError. Cair na outra raiz por omissão seria o pior desfecho possível: a raiz gerenciada é nomeada por workspace_dir_name e a base é nomeada pelo usuário, então o mesmo nome aponta para pastas diferentes e o container subiria com a pasta de OUTRO projeto, sem nada indicando por quê. Pelo mesmo motivo, a lista de modos que o broker atende é de PERMITIDOS: um modo novo no enum nasce recusado, com mensagem, em vez de aceito por omissão.

A composição continua passando por três barreiras, não uma. A api recusa o que não está sob a base (segmentoSobABaseDeProjetos); o broker recusa o segmento que não é relativo (segmentoDeProjetoValidado — .., absoluto, vazio, barra dupla, NUL); e o resultado da concatenação ainda passa por raizDeProjetoValidada antes de virar -v. Validar o segmento e não validar a concatenação seria confiar na aritmética de strings.

mounted ELEGE a imagem, como container — não lê a vigente como o runner. Não é simetria estética: é o único desenho que funciona. O broker compõe a partir de artifact.project_image, indo BUSCÁ-LO na api. Uma eleição da Infra que não fosse gravada nesse artefato seria inerte — o container subiria com a imagem que o Arquiteto decidiu, o payload que o humano aprovou diria outra, e nada no registro denunciaria a diferença. O caminho do runner pode ler a vigente justamente porque ali a api MANDA os campos da spec pelo canal; lá o artefato não é a fonte que o outro lado consulta.

O que esta regra NÃO faz: não materializa pasta nenhuma — quem cria a pasta do projeto montado é a RN-501, no MESMO caso de uso e antes desta ramificação, justamente porque o daemon do servidor precisa da pasta existindo para montá-la. Também não toca o portão da imagem (RN-105 já vale para os três modos desde a RN-494) e não muda quem PROPÕE container_start — o Infra Lead segue podendo propor para um projeto sem runner conectado e sem imagem decidida, a lacuna declarada desde a RN-494.

• Onde: src/application/use-cases/containers/obter-spec-de-container.use-case.ts (LocalizacaoDoProjeto, localizacaoDoProjeto); src/infrastructure/filesystem/project-workspaces-root.ts (segmentoSobABaseDeProjetos); src/interfaces/http/internal/dto/container-spec-internal.response.dto.ts; src/application/use-cases/actions/execute-container-start.use-case.ts, …/execute-container-stop.use-case.ts, …/execute-container-remove.use-case.ts (a ramificação !== 'runner'); packages/docker-port/src/docker-port.ts (segmentoDeProjetoValidado); apps/broker/src/config.ts (baseDeProjetosNoHost) e apps/broker/src/operacoes.ts (raizDoProjetoNoHost, garantirModoSuportado, BaseDeProjetosNaoConfiguradaError, LocalizacaoIndisponivelError)
• Teste: test/application/use-cases/containers/spec-e-observacao-de-container.use-case.spec.ts (describe('… o localizador discriminado (RN-503)')); test/application/use-cases/actions/execute-container-{start,stop,remove}.use-case.spec.ts; packages/docker-port/src/docker-port.spec.ts (describe('segmentoDeProjetoValidado')); apps/broker/src/operacoes.spec.ts e apps/broker/src/config.spec.ts
• ADR: 0130, 0141
• Origem: plano do dono do produto, PR 3

O artefato de decisão dos conversacionais (RN-505)

RN-508 — container_start_via_runner: segundo tipo de ação para subir o container, exclusivo de runner, e o Infra Lead recusa às cegas ANTES de propor

container_start (ADR 0130/0133) exige imagem/network/resources/ rationale — a Infra ELEGE uma candidata do roteamento do Arquiteto. Até esta entrega, o mesmo tipo de ação também atendia execution_mode: runner (ExecuteContainerStartUseCase.executeViaRunner), mas o caminho do runner NUNCA lia nenhum desses quatro campos: a imagem que sobe é a que já estiver DECIDIDA (não há roteamento contra o qual eleger, porque o broker nunca alcança a pasta de um projeto runner). Pedir 4 campos que o dispatch sempre descartava é o defeito que motiva nascer uma AÇÃO separada em vez de uma container_start "inteligente" ramificando por modo.

container_start_via_runner só tem rationale (opcional). Mesmo calibre de container_start (maintainer, require_approval por padrão, nunca semeado em auto-aprovação, configurável em permissions.json como as demais três ações de container — não entra no teto absoluto de container_remove). ExecuteContainerStartUseCase perde o ramo runner inteiro (executeViaRunner, ApiToEngineClient/ObterSpecDeContainerUseCase saem do construtor) — fica exclusivo de container/mounted, os dois pelo BROKER (RN-503). O código extraído vira ExecuteContainerStartViaRunnerUseCase, mesmo arquivo-irmão. A dança de ciclo de vida (provisioning -> running) que os dois caminhos compartilhavam por cópia vira SubirCicloDeVidaDoContainerUseCase (.../containers/) — extraída para não duplicar o racional da máquina de estados nos dois arquivos.

O Infra Lead consulta LOCALMENTE, sem HTTP, antes de propor. A tool nova (Engine.Infra.Tools.ProposeContainerStartViaRunner) é interceptada por Engine.Infra.InfraLeadServer.dispatch_calls/2, que lê Project.get/1 (execution_mode) e Engine.Runners.Registry.connected?/1 (runner conectado) — as DUAS leituras já são locais, no mesmo processo BEAM — ANTES de chamar propose_action. Recusa com motivo NOMEADO (nunca propõe às cegas) quando o projeto está em container (usa propose_container_start), em mounted (idem, desde a RN-503) ou em runner sem runner conectado agora. Esta lacuna — "propor sem saber se dá certo" — é a MESMA que propose_container_start tem desde a RN-494, declarada e aceita para aquela tool (tocar o prompt/ instrução do Infra Lead ficaria fora do escopo de API/domínio); a tool NOVA nasce sem ela, porque nasce sabendo negar.

A especificação que a api compõe é a que o runner VALIDA, e isso passou a ser provado. EspecificacaoDeContainerParaRunner são os campos de EntradaDeEspecificacao (packages/docker-port) menos raizDoProjeto, que só o runner conhece — DEZ, não nove. Ela nasceu com nove, sem projectId, e a consequência foi que este caminho NUNCA subiu container nenhum desde que existe: o engine repassa o mapa opacamente, o runner o entrega a especificacaoValidada, que exige projectId como texto não vazio, e a ação terminava failed com "especificação de container recusada em projectId: esperava texto não vazio, recebi undefined" — e daí o bloqueio CORRETO da RN-507/RN-502 fazia o resto, sem nenhum dev agent reivindicando tarefa. O dado sempre existiu (SpecDeContainer.projectId, o mesmo que o BROKER recebe por GET .../container-spec, e é por isso que só o modo runner quebrou); só não era copiado. Três suítes verdes não pegaram porque cada uma montava o próprio fixture: o teste do caso de uso afirmava o que ele mesmo esperava, o do runner montava um fixture COM projectId, e o engine não olha o mapa. O que passa a ser garantido é a CORRENTE — o payload que ExecuteContainerStartViaRunnerUseCase compõe, atravessando o especificacaoValidada de verdade —, e o teste também trava o conjunto de campos: raizDoProjeto é o único que a api não manda, então campo novo de um lado sem o outro reprova.

• Onde: src/domain/actions/decide.ts (container_start_via_runner); src/application/use-cases/actions/ execute-container-start-via-runner.use-case.ts (novo); src/application/use-cases/containers/ subir-ciclo-de-vida-do-container.use-case.ts (novo); src/application/use-cases/actions/propose-action.use-case.ts; src/application/use-cases/actions/approve-action.use-case.ts; src/application/ports/api-to-engine-client.port.ts (EspecificacaoDeContainerParaRunner, os dez campos); apps/web/src/lib/aprovacoes.ts; apps/engine/lib/engine/infra/tools/propose_container_start_via_runner.ex (novo); apps/engine/lib/engine/infra/infra_lead_server.ex
• Teste: test/application/use-cases/actions/execute-container-start.use-case.spec.ts, test/application/use-cases/actions/ execute-container-start-via-runner.use-case.spec.ts (novo), test/contract/ especificacao-de-container-para-runner.contract.spec.ts (a CORRENTE — o payload composto pela api contra o especificacaoValidada de verdade), apps/web/src/lib/aprovacoes.test.ts, apps/engine/test/engine/infra/tools/ propose_container_start_via_runner_test.exs (novo), apps/engine/test/engine/infra/infra_lead_server_test.exs
• ADR: 0145
• Origem: decisão do dono do produto — Docker vira pré-requisito real do modo runner, sem fallback pro host

O navegador de pastas servido pela api (RN-504)

RN-509 — "Sempre permitir" de um Dev Agent de módulo escopa a agent_autonomy, POR AGENTE — não mais o permissions.json de projeto inteiro

ApproveAlwaysActionUseCase sempre gravou em permissions.json/allow — escopo de PROJETO INTEIRO, compartilhado por qualquer ator. Isso significava que "sempre permitir" um comando pro dev-checkout liberava o MESMO comando pro dev-auth, pro dev-lead, e pra qualquer agente futuro do projeto: a intenção de quem clicou ("confio NESTE agente com ISTO") não tinha como ser expressa — só existia "confio em qualquer um com isto".

A gravação passa a se ramificar pelo ATOR, dentro do MESMO use case (não um novo — duplicar as duas guardas de teto absoluto de terminal fora de escopo/git_push/sudo e de container_remove em dois lugares seria o mesmo defeito que RN-418/RN-495 já existem para evitar):

• Ator agent cujo id é dev-<modulo> (ADR 0053/FASE 14d — a área DINÂMICA de dev, um agente por módulo do module_map): grava em agent_autonomy(projectId, agentId, actionType) = auto_approve, pelo MESMO AgentAutonomyRepository.upsert que activate-execution.use-case.ts já chama pra semear as três ações git por módulo. permissions.json fica intocado.
• Qualquer outro ator — user, system, agente agent que não é dev-de-módulo, e o dev-lead — continua indo pro permissions.json/allow de sempre, escopo de projeto inteiro, exatamente como antes.

dev-lead é a exceção que precisa de nome próprio. ehDevDeModulo (agent-areas.ts) é agentId.startsWith('dev-') PURO, de propósito — e isso classifica dev-lead como true. Quem exclui o lead da própria área é ehMembroDe, não ehDevDeModulo sozinho ("o lead não é membro da própria área" vale pra qualquer área — duplicar a exclusão dentro do predicado deixava as duas cópias inalcançáveis por teste, achado registrado no comentário do próprio agent-areas.ts). Por isso o branch usa ehDevDeModulo(actor.id) && actor.id !== DEV_LEAD: sem o segundo termo, "sempre permitir" clicado numa ação do dev-lead gravaria autonomia de módulo sob o agentId do LEAD por acidente — um agente que não é membro de dev, que não tem módulo, e que a área nunca olha via agent_area_members.

Os dois tetos absolutos de decide.ts continuam rodando ANTES do branch, sem mudar de ordem. Terminal com efeito externo git (git push, gh pr create) ou privilegiado (sudo/doas) — RN-106/RN-418 — e container_remove — RN-495 — seguem recusando o clique INTEIRO (400, ação nem aprovada), pra QUALQUER ator, antes mesmo do projeto ser buscado. Escopar a gravação por agente não é uma segunda porta pro mesmo teto: os dois if de recusa ficam onde estavam, e o branch novo entra depois.

O evento permission.granted carrega um payload OU outro, nunca um fingindo ser o outro. { pattern } continua sendo o formato do caminho de permissions.json (o padrão de texto gravado no arquivo); o caminho novo emite { agentId, actionType } — não há "padrão" nenhum pra mostrar quando a gravação é uma linha de tabela chaveada por agente.

Sem migração de dados. Entradas antigas de "sempre permitir" gravadas para um dev-de-módulo em permissions.json, de antes desta regra existir, continuam lá exatamente como estavam — só não recebem MAIS entradas desse tipo dali pra frente. Decisão consciente do dono do produto, não lacuna esquecida.

• Onde: src/application/use-cases/actions/approve-always-action.use-case.ts (o branch ehAgenteDeModulo), src/domain/agents/agent-areas.ts (ehDevDeModulo, DEV_LEAD — consumidos, não alterados), src/application/ports/agent-autonomy-repository.port.ts (upsert, já existente, sem método novo)
• Teste: test/application/use-cases/actions/approve-always-action.use-case.spec.ts (descreve escopo por Dev Agent de módulo (RN-509): caminho feliz dev-checkout grava agent_autonomy e não vaza pra dev-auth; os DOIS tetos absolutos recusando o clique inteiro pra um ator dev-de-módulo; dev-lead e ator user — inclusive com id começando em dev- — continuam no caminho antigo)
• Origem: plano do dono do produto, Frente 2

O destino do espelho é por projeto (RN-515)

RN-515 — O destino do espelho é declarado POR PROJETO e nunca é global; null é o estado normal; e a api valida SÓ o léxico, dizendo que é só o léxico

A capacidade espelho (RN-514, ADR 0147) copia o trabalho dos agentes para uma pasta do usuário fora da base montada — que é a razão de ela existir, porque bind mount não atravessa rede nem alcança caminho fora do que foi montado. Esta regra decide onde esse destino mora e como o usuário o declara; ela não copia arquivo nenhum.

Por PROJETO, nunca global. O destino é a coluna projects.mirror_path e o campo mirrorPath do projeto, escrito por PUT /projects/:projectId/mirror-path (maintainer, o mesmo mínimo de execution-mode e de projects-base: a rota fala de um caminho do computador do operador). Nunca configuração global no runner, nunca variável de ambiente: um destino global faria o artefato do projeto B aterrissar na pasta do projeto A, e o usuário descobriria isso pelo conteúdo, não por um erro (ADR 0147, ponto 4).

null é o estado NORMAL, não uma pendência. A coluna é nullable e nasce nula; projeto sem espelho é a maioria, e o produto nunca escolhe um destino sozinho. Limpar é {"mirrorPath": null} — a chave é obrigatória, e omiti-la é 400: um corpo que omite o campo seria indistinguível de "limpe", e limpar em silêncio é justamente o defeito. Limpar funciona sempre, inclusive num projeto container, senão uma linha convertida ficaria presa no estado que a regra proíbe.

Só o LÉXICO, e a api DIZ que é só o léxico. A api não enxerga a máquina onde o destino vai existir — é a situação do modo runner (RN-423), não a do mounted, onde a pasta acaba dentro da base que a api alcança de verdade. Ela reusa caminhoDeWorkspaceLocalValido, o mesmo predicado da criação e da conversão (absoluto, sem ../., nunca a raiz nem pasta de sistema, nunca sobreposto ao checkout do Brabo), em vez de uma quarta cópia da mesma régua — e não exige BRABO_PROJECTS_BASE, porque o destino do espelho é por definição a pasta que a base não cobre. A mensagem de recusa declara que o disco não foi verificado e quem o verifica.

Os dois sentidos do mesmo laço. Destino dentro do workspacePath e destino que contém o workspacePath são a mesma recusa vista de dois lados (ADR 0147, ponto 2): escrever o espelho dentro da origem faz o espelho copiar o próprio espelho, e uma origem dentro do destino aninha a cópia a cada rodada. Recusar um e permitir o outro seria fechar a porta e deixar a janela. A comparação é por SEGMENTO (dentroDoEscopo), nunca startsWith cru: /base-outra não está dentro de /base, e recusá-lo taxaria uma pasta irmã perfeitamente legítima.

Esta é a metade LÉXICA da guarda, e só ela. A outra é realpath, e é do RUNNER (espelho-guard.ts, ADR 0147 ponto 2), na máquina onde os dois caminhos existem de verdade. Um symlink em qualquer segmento do destino apontando de volta para a origem passa por aqui sem ser visto — a api não tem disco onde resolvê-lo. A api não garantiu o laço; ela impediu o laço ESCRITO.

container é recusado, e a recusa é NOMEADA. A origem de um projeto container é um volume gerenciado no servidor, e quem copiaria é um processo na máquina do usuário, que não a enxerga. Aceitar e nunca copiar seria pior que recusar, porque pareceria configurado. mounted e runner podem. Pelo mesmo motivo, converter o modo ZERA o destino (RN-447..450): em container ele não poderia existir, e mesmo entre mounted e runner a conversão MOVE a origem contra a qual os dois sentidos do laço foram validados.

O valor volta em toda leitura de projeto (ProjectResponseDto.mirrorPath), para a implementação do espelho e a tela de estado não precisarem de rota nova. Não há endpoint de leitura dedicado.

E ele NÃO é proposed_action. A escrita do espelho é configuração que o usuário declarou, não um agente pedindo para agir — o ADR 0147 é explícito disso, e sincronizar por comando de terminal cairia no escopo do ADR 0055 e viraria fila de aprovações rotineiras.

• Onde: src/db/schema/iam.ts (coluna mirror_path, nullable, sem CHECK — a recusa de container mora no caso de uso porque o modo é CONVERSÍVEL); src/db/migrations/0056_lovely_firelord.sql; src/domain/iam/project.entity.ts (mirrorPath); src/application/services/workspace-location.ts (validarDestinoDeEspelho — o léxico reusado, a recusa de container e os dois sentidos do laço); src/application/use-cases/iam/set-project-mirror-path.use-case.ts; src/application/use-cases/iam/convert-project-execution-mode.use-case.ts (a conversão zerando o destino); src/interfaces/http/iam/dto/set-mirror-path.dto.ts (@IsDefined
  • @ValidateIf, nunca @IsOptional, que colapsaria null e undefined); src/interfaces/http/iam/projects.controller.ts (PUT :projectId/mirror-path, maintainer); src/interfaces/http/iam/dto/iam.response.dto.ts
• Teste: test/application/use-cases/iam/set-project-mirror-path.use-case.spec.ts (grava, normaliza, limpa, limpa mesmo em container, recusa não-absoluto/../raiz/pasta de sistema/checkout do Brabo, os dois sentidos do laço, /base-outra vs /base NÃO sendo dentro, container recusado, 404); test/interfaces/http/iam/projects-execution-mode.controller.spec.ts (describe "destino do espelho (RN-515)" — maintainer e o repasse de null); test/application/use-cases/iam/convert-project-execution-mode.use-case.spec.ts (a conversão zerando o destino); test/interfaces/route-surface.spec.ts (a rota classificada em docs/security-surface.md)
• ADR: 0147, ponto 4
• Origem: FASE 28, sessão 6 (metade A — onde o destino mora; a cópia, o mirror_sync e a segunda passada de realpath são a metade B, no engine e no runner)

O estado do espelho é visível, e os três estados não colapsam (RN-517)

RN-517 — O desfecho de cada rodada do espelho volta pelo canal e vira TELEMETRIA numa tabela própria; "nunca sincronizou", "sincronizou e não copiou nada" e "falhou" são TRÊS respostas, e sucesso e erro convivem

A sessão 8 da FASE 28 e o ponto 7 do ADR 0147. A RN-516 fez o espelho copiar de verdade e deixou o mirror_sync fire-and-forget — sem mirror_sync_result no protocolo, de propósito, porque o formato da telemetria era decisão desta entrega. É ela que fecha o laço.

O caminho é o de workspace_confirm, e nenhum outro. O runner empurra mirror_sync_result no canal terminal:<projectId> depois de a rodada terminar; o engine trata em handle_in/3 e REPASSA à api pelo HTTP interno (POST /internal/projects/:projectId/mirror-sync-result), que grava pelo caso de uso. O engine não escreve a tabela — um segundo caminho de escrita seria a segunda fonte da mesma verdade, e a primeira coisa a divergir. É o único precedente de o runner contar algo sobre si mesmo, e foi por isso que o ADR o nomeou.

Nunca um "ok" otimista. O desfecho reportado é o REAL: as três contagens que sincronizarEspelho devolveu (copiados, pulados, recusados — nunca recontadas) ou o erro nomeado. As TRÊS saídas de tratarMirrorSync reportam, e com mensagens diferentes: a recusa por destino não concedido, a falha da cópia e o sucesso. ok NUNCA é deduzido de haver contagem ou mensagem — nem no runner, nem na tradução do engine, nem no caso de uso da api: deduzir tornaria uma rodada que copiou 0 arquivos (perfeitamente normal) indistinguível de uma que nem chegou a rodar.

TABELA, e não event log. project_mirror_states, uma linha por projeto (project_id único, mesmo desenho de project_containers). O motivo é o mesmo que fez rag_searches virar tabela (RN-479): session_events.session_id é NOT NULL e uma rodada de espelho não tem sessão — o event log perderia a coisa inteira, não uma parte dela. E não é proposed_action em hipótese nenhuma: a escrita do espelho é configuração que o usuário declarou, não um agente pedindo para agir.

Os TRÊS estados da RN-088, e eles não colapsam. "Nunca sincronizou" é a linha ausente. "Sincronizou e não copiou nada" é linha presente com files_copied = 0 — um desfecho, não um vazio. "Falhou" é last_error_at mais recente que last_synced_at. São três respostas diferentes, a pessoa age diferente em cada uma, e um traço servindo às três seria a tela recusando nomear o que sabe (RN-470).

Sucesso e erro CONVIVEM na mesma linha. As duas escritas mencionam colunas disjuntas: a de sucesso não toca last_error/last_error_at, a de falha não toca nenhuma coluna de sucesso, e nenhuma das duas apaga a outra. Quem decide qual está VIGENTE é a comparação dos dois carimbos (deriveMirrorSyncStatus, função pura do domínio), e é isso que permite a tela dizer "a última rodada falhou — última cópia boa em ontem, com 412 arquivos". Uma escrita destrutiva de um lado sobre o outro jogaria fora justamente a informação mais útil que a tela tem enquanto o espelho está quebrado. Duas escolhas menores na mesma direção: falha SEM destino não apaga o destino da última cópia que funcionou, e empate exato de carimbo resolve para failed — entre afirmar que está tudo bem e afirmar que algo falhou, a afirmação segura é a que faz a pessoa olhar.

destination é CONGELADO, como image_version em project_containers e os pesos em rag_searches (RN-479): é o destino REAL daquela rodada, resolvido por realpath na máquina do usuário depois do mkdir -p. Ler projects.mirror_path na hora de mostrar diria o destino de AGORA sobre uma cópia de ontem — e os dois divergem de verdade, porque a concessão viaja no join e só muda quando o runner reconecta (RN-516). Quando divergem, a tela DIZ isso.

Gravar telemetria jamais derruba o que ela mede. A cópia já terminou quando o reporte sai; o handle_in do engine só LOGA a recusa da api e devolve {:noreply, socket} nos dois ramos, e o canal do runner segue vivo. Sem canal (a conexão caiu entre o pedido e o fim da cópia) o runner não reporta e não lança — a rodada que aconteceu não é desfeita por isso. E um projeto cujo destino foi LIMPO no meio ainda registra: a rodada aconteceu, e o erro dela é o que costuma explicar o que houve.

Na tela, a linha entra em AmbienteDoProjeto (a coluna lateral da Visão geral, ao lado das de modo de execução e runner) e só existe em projeto que tem mirrorPath — num projeto sem espelho, "nunca sincronizou" seria uma ausência inventada, o mesmo argumento que já valia para a linha do runner. Data ABSOLUTA com ressalva e nunca bolinha verde de "está de pé", pelo mesmo precedente de workspaceVerifiedAt: o carimbo diz que uma rodada aconteceu, não que a pasta esteja em dia com o que mudou depois (o gatilho é um momento nomeado, o commit — nunca um watcher). O status chega RESOLVIDO da api: a regra que decide qual carimbo vale tem uma fonte só, e é ela que decide qual das três frases a pessoa lê.

Papel viewer para LER, maintainer para escrever o destino — a régua da RN-102 aplicada: o mínimo é do ENDPOINT, e este só lê. O destino já viaja em toda leitura de projeto (GET /projects/:projectId, viewer), então exigir maintainer aqui trancaria informação para quem já a vê no mesmo projeto, que é o pior dos dois defeitos porque é invisível para quem perdeu a capacidade.

• Onde: src/db/schema/iam.ts (project_mirror_states, no agregado iam porque é lá que o destino mora — não há domain/runners); src/db/migrations/0057_brave_silver_centurion.sql; src/domain/iam/mirror-state.ts (deriveMirrorSyncStatus, a regra dos três estados, pura); src/application/ports/mirror-state-repository.port.ts (DOIS métodos de escrita, não um upsert com tudo opcional — é o que torna a disjunção um invariante do tipo, não uma convenção do chamador); src/infrastructure/persistence/drizzle/mirror-state.repository.ts; src/application/use-cases/iam/record-mirror-sync.use-case.ts e .../get-project-mirror-state.use-case.ts; src/interfaces/http/internal/internal-projects.controller.ts (POST .../mirror-sync-result); src/interfaces/http/iam/projects.controller.ts (GET .../mirror-state, viewer); apps/engine/lib/engine/sessions/engine_api_client.ex (report_mirror_sync/2); apps/engine/lib/engine_web/channels/terminal_channel.ex (handle_in("mirror_sync_result", …) e a tradução do vocabulário); apps/runner/src/channel.ts (MirrorSyncResultMessage, enviarMirrorSyncResult); apps/runner/src/index.ts (tratarMirrorSync reporta as três saídas); apps/web/src/components/AmbienteDoProjeto.tsx
• Teste: test/application/use-cases/iam/mirror-sync-telemetry.use-case.spec.ts (os três estados na função pura e na leitura; erro que não apaga o sucesso; destino trocado; contagem 0; mensagem sem texto e mensagem longa; projeto sem destino que ainda registra); test/infrastructure/persistence/drizzle/mirror-state.repository.spec.ts (o invariante das colunas disjuntas contra o banco de verdade — um fake provaria o fake); apps/engine/test/engine_web/channels/terminal_channel_test.exs (describe "mirror_sync_result" — o repasse com tradução, o filesCopied: 0 que não some, campo ausente que NÃO vira nil, sucesso faltando que vira ok: false, :web ignorado, e a api que recusa sem derrubar o canal); apps/runner/src/index-handlers.spec.ts (describe "o desfecho é reportado em mirror_sync_result" — contagem real, repositório vazio como sucesso, falha nomeada, recusa sem destino, e a conexão caída que não reporta nem lança); apps/web/src/components/AmbienteDoProjeto.test.tsx (describe "linha do espelho" — sem mirrorPath a linha some e nem consulta; os três estados com três frases; nenhum vocabulário de liveness; destino trocado dito)
• ADR: 0147, ponto 7
• Origem: FASE 28, sessão 8. Fica declarado e NÃO feito: nenhum alarme, nenhuma notificação e nenhuma retentativa automática de rodada que falhou — a próxima rodada acontece no próximo momento nomeado, como sempre, e a tela é o único lugar onde a falha aparece hoje

A revogação de chave de dispositivo deixa de ser cega, e alcança a conexão viva (RN-519..520)

RN-519 — Ninguém revoga o que não consegue ver: a chave de dispositivo ganha listagem do PRÓPRIO dono, e a visão de maintainer fica fora por DECISÃO

A sessão 7 da FASE 28 e o ponto 6 do ADR 0147. A revogação existia desde o ADR 0118 (DELETE /projects/:projectId/runner-device-keys/:deviceKeyId, developer, 204, idempotente) — e não havia como enxergar o que se revoga.

O corte real era maior do que o docblock dizia. Ele declarava a ausência como "sem a visão de maintainer (listar/revogar de qualquer usuário) que o PAT tem". Mas o PersonalAccessTokensController tem cinco rotas — @Post(), @Get() e @Delete(':tokenId') para o próprio usuário, mais @Get('all') e @Delete(':tokenId/admin') para maintainer (RN-427) — e o de chave de dispositivo tinha duas. Não faltava só a visão de maintainer: faltava a listagem do PRÓPRIO dono. Uma chave órfã (aba fechada no meio do fluxo da RN-473) era inerte, invisível e permanente, sem tela nenhuma onde revogá-la — a lacuna que o CLAUDE.md já declarava.

Entra @Get(), developer, no mesmo formato que o PAT já tem e escopado ao próprio usuário no WHERE do repositório, nunca num filtro do caso de uso.

A revogada CONTINUA na lista. Mesma escolha de listarDoUsuarioNoProjeto do PAT: quem revogou precisa ver que revogou, e sumir com a linha faria a tela afirmar que a chave nunca existiu. revokedAt é o que separa as duas, e lastUsedAt nulo é o sinal da ÓRFÃ — registrada e nunca usada por runner nenhum.

Nunca a JWK pública. Ela não é segredo, mas não serve a nada aqui: a lista existe para revogar, e para isso bastam id, nome e as três datas. A metade privada a api nunca viu.

A visão de maintainer continua FORA — agora por decisão, não por omissão. As duas rotas de admin do PAT nasceram de resposta a incidente (RN-427): dev desligado com um segredo COMPARTILHADO circulando. Chave de dispositivo não é esse bicho — a privada nunca sai do navegador que a gerou, então não há segredo na mão de outro a conter. O que a DELETE daqui ganhou em troca foi ALCANCE (RN-520), não amplitude.

• Onde: src/interfaces/http/runner/runner-device-keys.controller.ts:99 (@Get(), listDeviceKeys, developer); src/application/use-cases/auth/list-runner-device-keys.use-case.ts:24; src/application/ports/runner-device-key-repository.port.ts:90 (listarDoUsuarioNoProjeto); src/infrastructure/persistence/drizzle/runner-device-key.repository.ts:69; src/interfaces/http/runner/dto/runner-device-key-list.response.dto.ts:19 (as DUAS travas de tipo, Wire/MesmasChaves, ao contrário do DTO do registro)
• Teste: test/application/use-cases/auth/list-runner-device-keys.use-case.spec.ts (delegação com userId/projectId na ordem certa; a revogada que fica na lista; a órfã com lastUsedAt nulo; repositório que rejeita e propaga); test/interfaces/http/runner/runner-device-keys.controller.spec.ts (as TRÊS rotas em developer; a delegação; a rota que não devolve lista vazia por engano)
• ADR: 0147, ponto 6
• Origem: FASE 28, sessão 7. Fica declarado e NÃO feito: tela nenhuma. Esta entrega é a metade server-side; a lacuna do CLAUDE.md fecha pela metade — a api passa a poder listar e revogar, e apps/web ainda não tem onde fazê-lo
• A outra metade FECHOU na RN-561: a aba Configurações ganhou a seção que lista e revoga, marcando a ESPÉCIE de cada chave. O que segue aberto daqui é a visão de maintainer (acima, por decisão) e o alvo {projeto, usuário} da desconexão (RN-520)

RN-520 — Revogar deixa de só impedir ticket NOVO e passa a derrubar a conexão VIVA; o alvo é {projeto, usuário} e nunca {chave}, e derrubar nunca derruba a revogação

Revisada pela RN-685 (ADR 0201): o ticket do socket passou a guardar QUAL credencial o pediu, e a revogação de chave (e a de PAT) derruba só as conexões abertas COM ELA — outro runner do mesmo usuário, com outra chave ou com PAT, fica de pé. O "custo declarado" abaixo deixou de valer. O par {projeto, usuário} sobrevive como o alvo da remoção de membro (RN-615), como o da conexão LEGADA (ticket sem credencial) durante o rollout, e como o plano B quando o engine não conhece a rota por credencial.

A outra metade do ponto 6 do ADR 0147. Revogar uma chave de dispositivo impedia o ticket SEGUINTE e nada mais: um brabo-runner já conectado mantinha o canal terminal:<projectId> de pé — executando comando aprovado, atendendo PTY, subindo container — com a chave revogada, até cair sozinho.

Quem manda o comando é a api; quem alcança o pid é o engine. A api chama POST /internal/projects/:projectId/runner/disconnect (o mesmo HTTP interno com service token de sempre, nunca um segundo mecanismo), e o engine acha o canal por Engine.Runners.Registry.whereis/1 — o pid que ele já entregava. O engine não consulta a tabela de chaves e a api não fala com o canal; nenhum dos dois faz o trabalho do outro, a mesma divisão de EngineWeb.ContainerCommandController (RN-497).

A precisão que existe é {projeto, usuário}, e a que não existe é {chave} — por construção, não por gosto. Engine.Runners.SocketTicket guarda project_id, user_id e kind, e só; a api pede o ticket com {userId, kind}. A identidade da CREDENCIAL que originou o ticket (o PAT, ou o kid da chave de dispositivo — RN-475) morre no PatAuthGuard e nunca chega ao socket. Levá-la até lá exigiria coluna nova em runner_socket_tickets, campo novo no pedido interno e um assign novo no connect/3: mudança de contrato de auth, fora desta entrega.

Custo DECLARADO, e nomeado no código, não só aqui: um runner do MESMO usuário conectado com PAT, ou com outra chave do mesmo projeto, também cai. Ele reconecta sozinho — a rodada seguinte pede um ticket novo, e a credencial que ainda vale ganha um. Quem foi revogado não ganha, e é aí que a revogação morde. Runner de OUTRO usuário no mesmo projeto não cai: a comparação é socket.assigns.user_id, dentro do processo do canal, que é o único que pode lê-lo — e o desfecho de_outro_dono volta ao pedinte em vez de um :ok que não descreve o que aconteceu.

Derruba o TRANSPORTE, não só o processo do canal. Parar apenas o canal deixaria o socket vivo e o cliente Phoenix reentrando no tópico para sempre com um ticket já consumido — degradação silenciosa, exatamente o defeito que o ADR 0147 existe para não repetir. EngineWeb.RunnerSocket.id/1 deixa de ser nil e passa a nomear a conexão (runner_socket:<kind>:<projectId>:<userId>), e o canal usa o mecanismo documentado do Phoenix, Endpoint.broadcast(id, "disconnect", %{}). É por ele que o runner PERCEBE a queda: onDisconnected resolve a rodada, o laço pede ticket novo e a api recusa.

Efeito colateral NUNCA derruba o efeito principal. O DELETE continua 204 e idempotente: engine fora do ar, nenhum runner conectado ou timeout não podem fazer a revogação falhar nem virar 5xx. A chamada ao engine mora num try/catch que só LOGA, dentro do caso de uso — a MESMA régua de rag_searches (RN-479) e do mirror_sync_result (RN-517). E os quatro desfechos são informação, não erro: sem_runner é o caso normal de quem revoga uma chave órfã (RN-519), e desfecho DESCONHECIDO vindo do engine vira timeout e nunca derrubado — entre afirmar que a conexão caiu e afirmar que talvez não, a afirmação segura é a que não promete o que não se sabe.

Revoga PRIMEIRO, derruba depois, e o projeto sai da LINHA revogada, nunca da URL: o projectId da rota já era ignorado no DELETE, e lê-lo aqui faria um projectId divergente derrubar o runner de um projeto que não tem nada com esta chave.

• Onde: src/application/use-cases/auth/revoke-runner-device-key.use-case.ts:63 (a ordem, o projeto da linha e o try/catch que só loga); src/application/ports/api-to-engine-client.port.ts:433 (disconnectRunnerOfUser, DesfechoDeDesconexaoDeRunner); src/infrastructure/http-clients/api-to-engine-client.ts:477; apps/engine/lib/engine/runners/revogacao.ex:92 (derrubar/3); apps/engine/lib/engine_web/channels/terminal_channel.ex:697 (handle_info({:derrubar_por_revogacao, …})); apps/engine/lib/engine_web/channels/runner_socket.ex:79 (id/1, que deixou de ser nil); apps/engine/lib/engine_web/controllers/runner_connection_command_controller.ex:27; apps/engine/lib/engine_web/router.ex:86
• Teste: test/application/use-cases/auth/revoke-runner-device-key.use-case.spec.ts (describe "a revogação alcança a conexão viva" — o projeto da linha; a ordem revoga→derruba; engine fora do ar que não derruba a revogação; 404 que não derruba ninguém); test/infrastructure/http-clients/api-to-engine-client.spec.ts (a rota e o corpo; desfecho desconhecido virando timeout; 500 que LANÇA, para o caso de uso tratar); apps/engine/test/engine/runners/revogacao_test.exs (sem runner; o dono; o outro dono; o teto; argumento fora de forma que não levanta); apps/engine/test/engine_web/channels/terminal_channel_test.exs (describe "revogação alcança a conexão viva" — o canal REAL que para e libera a presença no Registry, o de outro dono que fica de pé, o :web que nunca é alvo); apps/engine/test/engine_web/controllers/runner_connection_command_controller_test.exs (os 200 com desfecho, e o 400 de pedido malformado)
• ADR: 0147, ponto 6
• Origem: FASE 28, sessão 7. Fica declarado e NÃO feito: a revogação não alcança um runner conectado em OUTRO projeto com a mesma chave — não existe esse caso, porque runner_device_keys.project_id amarra a chave a um projeto só; e nenhuma tela dispara isto ainda (a metade web da RN-519)

RN-521 — A página /containers lista TODO projeto do workspace e vira o caminho HUMANO de subir o container, ramificado por execution_mode

Estendida pela RN-574 (ADR 0161): um quarto motivo de recusa local, sem_broker_na_instalacao, para container/mounted numa instalação sem broker de container — depois de "já está de pé" e antes de "sem imagem decidida".

Estendida pela RN-590 (AT-105): a mesma leitura vale na conversão de modo, em parar/remover e na proposta do Infra Lead (recusa 409 da api ao propor).

Subir o container de um projeto tinha um caminho: o Infra Lead, dentro de uma sessão, chamando a ferramenta dele. Numa execução real do exp004 (modo runner) a container_start_via_runner falhou pelo defeito que a RN-508 fechou — e não havia como TENTAR DE NOVO. Cinco dev agents ficaram horas emitindo dev.blocked_by_container (RN-502), e a única saída era abrir sessão nova e conversar com um agente para reexecutar uma operação de máquina.

A página global de containers (ADR 0136, RN-495) já era o lugar onde um HUMANO decide ciclo de vida de container — mas ela nem mostrava o projeto: a régua era "uma linha por projeto que já tem project_containers", e uma subida que falha ANTES de registrar não deixa linha nenhuma. A tela escondia exatamente o projeto para o qual ela precisava existir.

O TERCEIRO estado tem nome próprio, e não é stopped. O read model passa a LEFT JOIN (era INNER) e registrado vira null para quem nunca provisionou — não é um valor novo de ContainerLifecycleStatus (stopped é um container que EXISTIU e parou), e não é "não observado" (que é sobre o daemon ter sido perguntado). A tela imprime "nunca provisionado" e a coluna Observado diz sem_container_registrado, o terceiro motivo de naoVerificado — os três não colapsam (RN-088/RN-486).

A lista alargou; o ORÇAMENTO não. Perguntar o observado ao broker é chamada de rede por projeto, com teto de 20 por carregamento (TETO_DE_VERIFICACOES_POR_CARGA). Projeto sem project_containers não tem o que observar, então nunca é elegível e nunca ocupa uma vaga: num workspace com centenas de projetos vazios, quem tem container de verdade continua verificado exatamente como antes. E continuam sendo TRÊS consultas em lote, quantos projetos forem — nenhuma dentro de laço.

A ação ramifica por execution_mode, com a mesma régua do backend (RN-497/RN-503): container e mounted propõem container_start (broker, no servidor) e runner propõe container_start_via_runner (agente local, na máquina do usuário). Os DOIS payloads são diferentes de propósito e não se copiam: container_start carrega a ELEIÇÃO de imagem (imagem, rede, recursos), lida da decisão vigente do projeto no clique; container_start_via_runner tem schema só com rationale (RN-508), porque ela sobe a imagem JÁ decidida e não elege nada.