deepdebug-local-agent 1.0.23 → 1.2.0

package/docs/graphify-validation-run-2026-10-28.md

@@ -0,0 +1,243 @@
+# Graphify: corrida do harness de validação, 2026-10-28
+
+Corrida real de `tools/graphify-validation/run.sh --pip-audit` (T4-06, D8) contra `vh-api-gateway@release/qa`, `visionhammer-agents@release/qa` e
+`deepdebug-local-agent@main` (SHAs na secção 0 do relatório). Máquina de desenvolvimento (macOS arm64, 10 CPUs, 16 GB), **não** um VPS de 2 vCPU / 4 GB.
+Graphify `graphifyy==0.9.93` do PyPI, instalado com `--require-hashes`. Sem LLM, sem rede para o Graphify, sem acesso ao pgvector de PROD nem de QA.
+
+**Conclusão curta: o Graphify continua "go com condições", e "Graphify validado" (D5) ainda não pode ser declarado.** Dos limiares propostos, nesta corrida
+falham G1 (só no repo do Local Agent), G3, G4 (memória no incremental), G5 e G8 (versionamento no agents); passam os testes de rede e determinismo; G6, G9 e G10 não foram medidos.
+
+## Leitura dos resultados (com as ressalvas que alteram a conclusão)
+
+- **G1, extração.** gateway 99,81 % (3 ficheiros sem símbolos), agents 100 %, Local Agent 93,33 % (8 de 120: 7 são testes `node:test` só com código de topo, mais `src/workspace/git-client.js`, **causa não investigada**). Falha o limiar de 95 % só no Local Agent, num repo pequeno onde um ficheiro pesa 0,8 %.
+- **G2, arestas.** INFERRED: gateway 12,22 %, agents 14,05 % (a 1 ponto do limiar de 15 %; a nota do piloto tinha 11,4 % e 13,6 % com a 0.9.86), Local Agent 1,68 %. A precisão da amostra vem de um **oráculo automático** (tipo declarado do recetor), não de revisão humana: gateway 94,6 % nas 56 decididas de 60, agents 100 % nas 53 decididas de 60, Local Agent 100 % em 7 (só 7 arestas INFERRED `calls` fora de testes). O oráculo reproduziu o falso positivo que o piloto cita (`webClientBuilder.build()` apontado para `RootAuditEvent.Builder`, 3 ocorrências na amostra do gateway), o que mostra que não aprova tudo. Fica `PARCIAL`: falta a revisão por 2 pessoas e as linhas `unknown` (construtores, chamadas encadeadas, `var`) estão por julgar nos CSV.
+- **G3, Spring/DI (fixture sintética, 19 verificações).** Falha: interface→implementação 62,5 % (5/8). O grafo liga `StripeGateway implements PaymentGateway` e as chamadas à interface, mas **não liga quem chama a interface às implementações** (3 verificações "chega à implementação" falham). Injeção por Lombok/construtor por tipo: 4/4. `@Bean`: 2/4 (o método `@Bean` aparece como método comum; quem consome o bean não chega ao método). `@Qualifier`: 0/3 (ignorado). Confirma a condição do piloto "sem nós de bean". Consequência para o loop: o contexto de "quem é afetado por mudar `PaymentGateway.charge`" tem de juntar `implements` a mão (ou o fallback `rg`).
+- **G4, desempenho.** A frio: gateway 19,5 s, agents 15,3 s, Local Agent 2,8 s, todos abaixo de 60 s; maior processo filho 440-445 MB (estimativa da soma da árvore: ~795 MB, que conta páginas partilhadas). **Incremental (1 ficheiro): 21,6 s e 18,7 s, maior filho 1,17 e 1,13 GB, acima do limiar de 1 GB** (o piloto tinha 1,06 GB). Confirma que o `update` incremental reconstrói tudo. Em 2 vCPU/4 GB **não medido**; o tempo deve subir, a memória do maior processo não deve descer.
+- **G5, recall.**
+  - "Quem é afetado" (`affected`, profundidade 1, só fontes main, `rg -w` como referência): recall agregado 54,8 % no gateway, 76,8 % no agents, 87,5 % no Local Agent; o limiar é 90 %. A precisão contra `rg` ficou em 100 % no gateway e no Local Agent e 79,6 % no agents. Os piores casos são classes cujo uso é por métodos (`PolicyGate`: 10 % a profundidade 1, 15 % a profundidade 2): o nó da classe não recebe as chamadas aos seus métodos. Ou seja, a primitiva certa é `affected` **por método**, não por classe, e isso não foi medido aqui.
+  - recall@8 com 22 perguntas escritas à mão (`config/questions.json`; 8 gateway, 8 agents, 6 Local Agent): o grafo fica em 43,8 % (gateway), 62,5 % (agents) e 66,7 % (Local Agent). O baseline lexical **justo** (palavras tiradas só do texto da pergunta, `rg` insensível a maiúsculas) dá 87,5 %, 75,0 % e 91,7 %. As perguntas conceptuais sem nome de símbolo são o ponto fraco do grafo (gateway 25 %, agents 57,1 %), exatamente a lacuna que o piloto não tinha testado e que o D14 (fallback ripgrep) cobre. As perguntas que nomeiam o símbolo: grafo 100 %.
+  - A coluna `lexical_curated` (100 % nos três) usa palavras escolhidas por quem já sabia a resposta; **não é comparável** e está no relatório só como teto.
+  - **pgvector não medido**: sem o dataset do `RagEvalController` e sem BD, a comparação "grafo ≥ pgvector − 5 pp" do G5 não pode ser feita. O harness aceita `--vector-results` para quando houver.
+  - O conjunto de 22 perguntas é pequeno e a verdade (ficheiros) foi verificada à mão por um só agente; serve para comparar backends, não para um número absoluto.
+- **G7, segurança.** Com a rede negada (`sandbox-exec`, verificado por uma sonda TCP que falhou), os 3 repos terminaram com exit 0, **0 eventos `socket.*`** no hook de auditoria e só 2 `subprocess.Popen` (`git rev-parse HEAD`). `pip-audit`: 0 vulnerabilidades conhecidas nos 32 pacotes do lock 3.12 (não foi corrido no lock 3.11). Licenças: 32 permissivas, `tree-sitter-groovy` sem ficheiro de licença no wheel. `PARCIAL`: a lista de comandos desativados é requisito do wrapper, não foi testada.
+- **G8, higiene.** Determinismo: duas corridas a frio dão a mesma impressão de nós/arestas nos 3 repos. `visionhammer-agents@release/qa` **tem 57 ficheiros `graphify-out/` versionados** (gateway e Local Agent: 0). O limiar exige 0, logo falha até haver o PR de remoção.
+- **Versão.** O piloto mediu o fork 0.9.86; esta corrida mede o PyPI 0.9.93. Números próximos (tempos, INFERRED, grafos de ~17 000 nós), sem sinal de que o fork acrescente valor, o que sustenta D8.
+
+## Não medido (e porquê)
+
+| Item | Motivo |
+|---|---|
+| recall@8 contra pgvector (G5) | sem BD de QA nem dataset do `RagEvalController` |
+| G6, incidentes ponta a ponta sem Voyage | exige agent2/LA com LLM |
+| G9, imagem `local-agent-full` | sem Docker local; plano em `docs/graphify-packaging-plan.md` |
+| G10, Python, SQL, Go, Terraform reais e repo do piloto | fora dos 3 repos pedidos; o piloto anterior só tinha fixtures sintéticas para Go e Terraform |
+| 2 vCPU / 4 GB e hardware do piloto | só há esta máquina |
+| Revisão manual de 2 pessoas das INFERRED | passo humano; CSV pronto |
+| `pip-audit` do lock Python 3.11, instalação do lock em Linux | só macOS arm64 e lock 3.12 auditados |
+
+---
+
+## Relatório gerado (REPORT.md, sem edição manual)
+
+Gerado por `tools/graphify-validation/run.sh`. Marcacao: PASSA/FALHA contra o limiar proposto; PARCIAL = medido mas falta um passo humano ou de ambiente; NAO MEDIDO = nao deu para medir aqui.
+
+## 0. Ambiente e versoes
+
+| Item | Valor |
+|---|---|
+| Data (UTC) | 2026-10-28T03:57:56Z |
+| Graphify | graphifyy==0.9.93 (fixado por hash) |
+| Python | Python 3.12.10 |
+| SO / CPU / RAM | Darwin 25.3.0 arm64 / 10 CPUs / 16.0 GB |
+| ripgrep | ripgrep 14.1.1 (rev 0ae49f8b6e) |
+| Bloqueio de rede | sandbox-exec (deny network*); eficaz: True |
+| Ambiente do processo | so HOME, LANG, NO_COLOR, PATH, PYTHONHASHSEED (sem chaves LLM nem credenciais) |
+
+| Repo | Ref | SHA | Ficheiros de codigo |
+|---|---|---|---|
+| deepdebug-local-agent | origin/main | 854fa34cb8 | 120 |
+| vh-api-gateway | origin/release/qa | ef42fba928 | 1552 |
+| visionhammer-agents | origin/release/qa | 33a705cc9a | 1056 |
+
+## 1. Resumo por criterio
+
+| ID | Veredito | Medido |
+|---|---|---|
+| G1 | FALHA | deepdebug-local-agent 93.33% (8 sem simbolos); vh-api-gateway 99.81% (3 sem simbolos); visionhammer-agents 100.0% (0 sem simbolos) |
+| G2 | PARCIAL | deepdebug-local-agent INFERRED 1.68%, precisao oraculo 100.0% (n=7, decididas 7); vh-api-gateway INFERRED 12.22%, precisao oraculo 94.6% (n=60, decididas 56); visionhammer-agents INFERRED 14.05%, precisao oraculo 100.0% (n=60, decididas 53); falta revisao manual por 2 pessoas |
+| G3 | FALHA | interface->impl 62.5% (limiar 90%) |
+| G4 | FALHA | deepdebug-local-agent frio 2.83s, arvore 635.4 MB, maior filho 94.6 MB; incremental 2.8s, arvore 635.7 MB, maior filho 121.0 MB; vh-api-gateway frio 19.47s, arvore 795.9 MB, maior filho 444.2 MB; incremental 21.64s, arvore 1093.5 MB, maior filho 1174.2 MB; visionhammer-agents frio 15.27s, arvore 793.7 MB, maior filho 439.7 MB; incremental 18.68s, arvore 1123.9 MB, maior filho 1134.7 MB; maquina de desenvolvimento (nao 2 vCPU/4 GB); soma de RSS da arvore acima de 1 GB em pelo menos uma corrida (pode contar paginas partilhadas) |
+| G5 | FALHA | deepdebug-local-agent affected recall vs rg 87.5% (precisao 100.0%); deepdebug-local-agent recall@8 grafo 66.7% vs lexical (palavras da pergunta) 91.7%; vh-api-gateway affected recall vs rg 54.8% (precisao 100.0%); vh-api-gateway recall@8 grafo 43.8% vs lexical (palavras da pergunta) 87.5%; visionhammer-agents affected recall vs rg 76.8% (precisao 79.6%); visionhammer-agents recall@8 grafo 62.5% vs lexical (palavras da pergunta) 75.0%; pgvector NAO medido (sem BD de QA) |
+| G6 | NAO MEDIDO | exige agent2/LA com LLM e incidentes reais; fora do harness |
+| G7 | PARCIAL | deepdebug-local-agent: 0 eventos socket, exit 0; vh-api-gateway: 0 eventos socket, exit 0; visionhammer-agents: 0 eventos socket, exit 0; pip-audit: 0 vulnerabilidades conhecidas em 32 pacotes (exit 0); comandos de rede desativados = requisito de empacotamento, nao testado aqui |
+| G8 | FALHA | determinismo igual em 3/3 repos; deepdebug-local-agent: 0 ficheiros graphify-out versionados; vh-api-gateway: 0 ficheiros graphify-out versionados; visionhammer-agents: 57 ficheiros graphify-out versionados |
+| G9 | NAO MEDIDO | sem Docker local; ver docs/graphify-packaging-plan.md |
+| G10 | NAO MEDIDO | Java e JS cobertos por repos VH; Python/SQL/Go/Terraform e repo do piloto fora deste conjunto |
+
+## 2. Detalhe por repo
+
+### deepdebug-local-agent
+
+- Corrida a frio: 2.83s, pico de RSS da arvore 635.4 MB (estimativa; maior filho 94.6 MB), nos 1642, arestas 3283, graphify-out 3.2 MB.
+- G1: 112/120 ficheiros de codigo com simbolos (93.33%); 8 sem simbolos, dos quais 7 em testes. Lista: src/workspace/git-client.js, test/bind-host.test.js, test/child-env.test.js, test/file-count.test.js, test/observability-detect.test.js, test/sandbox.test.js, test/search-outcome.test.js, test/adapters/registry.test.js
+- G2: INFERRED 1.68% (1.69% so em fontes main); INFERRED por relacao {'calls': 7, 'indirect_call': 38, 'references': 10}.
+- G8 determinismo: assinatura aab33c2415660429 vs aab33c2415660429, igual: True.
+- Incremental (1 ficheiro alterado: bin/install.js): 2.8s, 635.7 MB; simbolo novo no grafo: True; sem alteracoes: 2.38s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=7): oraculo ok/wrong/unknown {'ok': 7}; precisao nas decididas 100.0%; estrato ambiguo {'n': 0, 'ok': 0, 'precision_pct': None, 'unknown': 0, 'wrong': 0}; estrato outros {'n': 7, 'ok': 7, 'precision_pct': 100.0, 'unknown': 0, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| confineToRoot (ok) | 2 | 3 | 2 | 0 | 1 | 66.7% | 100.0% |
+| sanitizedChildEnv (ok) | 2 | 2 | 2 | 0 | 0 | 100.0% | 100.0% |
+| verifySignature (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+| evaluateCommand (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+| resolveBindHost (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| validateHeaderRoot (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| BurstSuppressor (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| isSecretEnvName (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+
+Agregado (profundidade 1): recall 87.5%, precisao 100.0% (5 simbolos); profundidade 2: recall 87.5%.
+
+recall@8 no conjunto de referencia (6 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 6 | 66.7% | 66.7% |
+| graph | conceptual | 6 | 66.7% | 66.7% |
+| graph_call_only | all | 6 | 66.7% | 66.7% |
+| graph_call_only | conceptual | 6 | 66.7% | 66.7% |
+| lexical_auto | all | 6 | 91.7% | 100.0% |
+| lexical_auto | conceptual | 6 | 91.7% | 100.0% |
+| lexical_curated | all | 6 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 6 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+### vh-api-gateway
+
+- Corrida a frio: 19.47s, pico de RSS da arvore 795.9 MB (estimativa; maior filho 444.2 MB), nos 17654, arestas 71062, graphify-out 133.0 MB.
+- G1: 1549/1552 ficheiros de codigo com simbolos (99.81%); 3 sem simbolos, dos quais 0 em testes. Lista: src/main/java/io/visionhammer/gateway/filter/RequestLoggingFilter.java, src/main/java/io/visionhammer/gateway/logs/api/LogsController.java, src/main/java/io/visionhammer/gateway/security/bo/package-info.java
+- G2: INFERRED 12.22% (8.86% so em fontes main); INFERRED por relacao {'calls': 8263, 'references': 423}.
+- G8 determinismo: assinatura 0bbbea2d3be0dc3d vs 0bbbea2d3be0dc3d, igual: True.
+- Incremental (1 ficheiro alterado: src/main/java/io/visionhammer/gateway/admin/api/AdminInsightsController.java): 21.64s, 1093.5 MB; simbolo novo no grafo: True; sem alteracoes: 12.98s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=60): oraculo ok/wrong/unknown {'ok': 53, 'unknown': 4, 'wrong': 3}; precisao nas decididas 94.6%; estrato ambiguo {'n': 20, 'ok': 16, 'precision_pct': 84.2, 'unknown': 1, 'wrong': 3}; estrato outros {'n': 40, 'ok': 37, 'precision_pct': 100.0, 'unknown': 3, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| TenantAccessGuard (ok) | 21 | 21 | 21 | 0 | 0 | 100.0% | 100.0% |
+| PolicyGate (ok) | 4 | 40 | 4 | 0 | 36 | 10.0% | 100.0% |
+| EgressUrlGuard (ok) | 11 | 13 | 11 | 0 | 2 | 84.6% | 100.0% |
+| SlackRequestVerifier (ok) | 2 | 6 | 2 | 0 | 4 | 33.3% | 100.0% |
+| JwtTokenProvider (ok) | 8 | 8 | 8 | 0 | 0 | 100.0% | 100.0% |
+| AuthRateLimiter (ok) | 4 | 5 | 4 | 0 | 1 | 80.0% | 100.0% |
+| DataErasureService (ok) | 0 | 2 | 0 | 0 | 2 | 0.0% | n/d |
+| EmailService (ok) | 7 | 9 | 7 | 0 | 2 | 77.8% | 100.0% |
+
+Agregado (profundidade 1): recall 54.8%, precisao 100.0% (8 simbolos); profundidade 2: recall 57.7%.
+
+recall@8 no conjunto de referencia (8 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 8 | 43.8% | 50.0% |
+| graph | conceptual | 6 | 25.0% | 33.3% |
+| graph | symbolic | 2 | 100.0% | 100.0% |
+| graph_call_only | all | 8 | 43.8% | 50.0% |
+| graph_call_only | conceptual | 6 | 25.0% | 33.3% |
+| graph_call_only | symbolic | 2 | 100.0% | 100.0% |
+| lexical_auto | all | 8 | 87.5% | 87.5% |
+| lexical_auto | conceptual | 6 | 100.0% | 100.0% |
+| lexical_auto | symbolic | 2 | 50.0% | 50.0% |
+| lexical_curated | all | 8 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 6 | 100.0% | 100.0% |
+| lexical_curated | symbolic | 2 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+### visionhammer-agents
+
+- Corrida a frio: 15.27s, pico de RSS da arvore 793.7 MB (estimativa; maior filho 439.7 MB), nos 16776, arestas 60583, graphify-out 121.6 MB.
+- G1: 1056/1056 ficheiros de codigo com simbolos (100.0%); 0 sem simbolos, dos quais 0 em testes. Lista: nenhum
+- G2: INFERRED 14.05% (12.87% so em fontes main); INFERRED por relacao {'calls': 5980, 'references': 2534}.
+- G8 determinismo: assinatura 703f4318fc6b20a3 vs 703f4318fc6b20a3, igual: True.
+- Incremental (1 ficheiro alterado: agents/cloud-engineer/src/main/java/io/visionhammer/agents/agent1/controller/Agent1Controller.java): 18.68s, 1123.9 MB; simbolo novo no grafo: True; sem alteracoes: 11.32s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=60): oraculo ok/wrong/unknown {'ok': 53, 'unknown': 7}; precisao nas decididas 100.0%; estrato ambiguo {'n': 20, 'ok': 18, 'precision_pct': 100.0, 'unknown': 2, 'wrong': 0}; estrato outros {'n': 40, 'ok': 35, 'precision_pct': 100.0, 'unknown': 5, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| ContextAssembler (ok) | 7 | 15 | 7 | 0 | 8 | 46.7% | 100.0% |
+| VoyageEmbeddingClient (ok) | 7 | 9 | 7 | 0 | 2 | 77.8% | 100.0% |
+| PiiEgressMasker (ok) | 21 | 21 | 21 | 0 | 0 | 100.0% | 100.0% |
+| SecretMasker (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| CorrelationIdDetector (ok) | 2 | 2 | 2 | 0 | 0 | 100.0% | 100.0% |
+| LiteLlmChatAdapter (ok) | 11 | 1 | 0 | 11 | 1 | 0.0% | 0.0% |
+| PolicyGateGuard (ok) | 4 | 4 | 4 | 0 | 0 | 100.0% | 100.0% |
+| ChunkRemaskService (ok) | 1 | 3 | 1 | 0 | 2 | 33.3% | 100.0% |
+
+Agregado (profundidade 1): recall 76.8%, precisao 79.6% (8 simbolos); profundidade 2: recall 76.8%.
+
+recall@8 no conjunto de referencia (8 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 8 | 62.5% | 62.5% |
+| graph | conceptual | 7 | 57.1% | 57.1% |
+| graph | symbolic | 1 | 100.0% | 100.0% |
+| graph_call_only | all | 8 | 62.5% | 62.5% |
+| graph_call_only | conceptual | 7 | 57.1% | 57.1% |
+| graph_call_only | symbolic | 1 | 100.0% | 100.0% |
+| lexical_auto | all | 8 | 75.0% | 75.0% |
+| lexical_auto | conceptual | 7 | 71.4% | 71.4% |
+| lexical_auto | symbolic | 1 | 100.0% | 100.0% |
+| lexical_curated | all | 8 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 7 | 100.0% | 100.0% |
+| lexical_curated | symbolic | 1 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+## 3. Spring/DI (fixture sintetica)
+
+| Grupo | Encontrado | Esperado | % |
+|---|---|---|---|
+| bean_methods | 2 | 4 | 50.0% |
+| interface_impl | 5 | 8 | 62.5% |
+| lombok_injection | 4 | 4 | 100.0% |
+| qualifier | 0 | 3 | 0.0% |
+
+Itens em falta:
+
+- bean_methods / bean-clock-consumed-by-audit-bean: not reachable within 2 hops
+- bean_methods / bean-consumer-checkout-audit: not reachable within 2 hops
+- interface_impl / checkout-reaches-stripe-impl: not reachable within 2 hops
+- interface_impl / refund-reaches-paypal-impl: not reachable within 2 hops
+- interface_impl / refund-reaches-stripe-impl: not reachable within 2 hops
+- qualifier / qualifier-stripe-selected: not reachable within 2 hops
+- qualifier / qualifier-stripe-not-paypal: vacuous: companion check qualifier-stripe-selected failed, so absence proves nothing
+- qualifier / qualifier-fastcache-bean: not reachable within 2 hops
+
+## 4. Licencas das dependencias instaladas
+
+32 distribuicoes; permissivas 32; a rever nenhuma; desconhecidas nenhuma; sem ficheiro de licenca ['tree-sitter-groovy'].
+
+## 5. pip-audit
+
+0 vulnerabilidades conhecidas em 32 pacotes (exit 0)
+
+## 6. O que este relatorio nao mediu
+
+- recall@8 contra pgvector: precisa do dataset do RagEvalController e da BD de QA (passar `--vector-results`).
+- G6 (incidentes ponta a ponta sem Voyage), G9 (imagem local-agent-full) e G10 (repo do piloto, Python/SQL/Go/Terraform reais).
+- Revisao manual por 2 pessoas das arestas INFERRED (o CSV em `review/` esta pronto para isso).
+- Desempenho em 2 vCPU/4 GB e no hardware do piloto.

package/docs/releasing.md

@@ -0,0 +1,37 @@
+# Releasing (npm)
+
+Every push to `main` publishes `deepdebug-local-agent` to npm through
+`.github/workflows/npm-publish.yml` (Trusted Publishing, OIDC; no token). The version
+is chosen automatically from the commit messages since the last release tag, following
+[Semantic Versioning](https://semver.org) and [Conventional Commits](https://www.conventionalcommits.org):
+
+| Level | Version step | Commit that triggers it |
+|---|---|---|
+| Patch | `0.0.X` bug fix | `fix:`, and any other type (`perf:`, `refactor:`, `docs:`, `chore:`, `ci:`, ...) or a message without a type |
+| Minor | `0.X.0` new functionality | `feat:` or `feat(scope):` |
+| Major | `X.0.0` big, breaking change | `type!:` (for example `feat!:`) or a `BREAKING CHANGE:` footer |
+
+The highest level among the commits since the last `vX.Y.Z` tag wins. Merge commits and the
+CI bump commits (`[skip ci]`) are ignored. The rules live in `scripts/next-version.mjs` and are
+unit tested in `test/next-version.test.js`.
+
+Examples:
+
+```
+fix: reject unsigned requests on /workspace/exec          -> 1.1.0 becomes 1.1.1
+feat(ws): metadata-only channel                           -> 1.1.1 becomes 1.2.0
+feat!: require node 22                                    -> 1.2.0 becomes 2.0.0
+```
+
+Tips
+
+- Write the PR title as a Conventional Commit and use "Squash and merge", so the version
+  follows the title. With a normal merge, the commits inside the PR decide.
+- To skip a release (for example a docs-only change), put `[skip ci]` in the merge commit
+  subject.
+- To force a version, run the workflow by hand with the `version` input:
+  `gh workflow run npm-publish.yml -f version=X.Y.Z` (must be greater than the highest tag).
+- The workflow tags and commits the bump only after a successful publish, so a failed
+  publish does not burn a version. npm reviews each new version automatically: it can stay
+  in "Validating" for a few minutes before it becomes installable.
+- Provenance is not published (`--provenance` is rejected by npm for private repositories).

package/docs/signed-commands.md

@@ -0,0 +1,163 @@
+# Signed and allow-listed commands — operator notes
+
+The platform (vh-api-gateway, visionhammer-agents) signs every command it sends
+to a local agent with an Ed25519 key, and the agent runs shell commands only
+from an allowlist. Both checks have three modes, `off | warn | enforce`. The
+default is `enforce` (signature: since 1.1.0; exec policy: since 1.0.35), and an
+unrecognised value also means `enforce`. `warn` verifies and logs without
+rejecting; use it only as an explicit, temporary opt-out
+(`LOCAL_AGENT_SIGNATURE_MODE=warn`) for an agent whose platform side does not
+sign yet. Without a listen address the agent also binds `127.0.0.1` unless a
+token (`LOCAL_AGENT_TOKEN` / `AGENT_SHARED_SECRET`) or Cloud Run is present.
+
+## Protocol v1
+
+HTTP headers on every platform → agent request:
+
+| Header | Value |
+|---|---|
+| `X-VH-Key-Id` | id of the signing key, for example `vh-2026-09` |
+| `X-VH-Timestamp` | unix epoch **seconds** |
+| `X-VH-Nonce` | 16–128 chars `[A-Za-z0-9_-]`, unique per request |
+| `X-VH-Tenant-Id` / `X-VH-Workspace-Id` | the tenant and workspace the platform acts for (`""` when unknown) |
+| `X-VH-Signature` | base64 Ed25519 signature over the canonical string |
+
+Canonical string (UTF-8, `\n`-joined, no trailing newline):
+
+```
+VH-AGENT-SIG-V1
+<METHOD upper-case>
+<raw path + "?" + raw query, as sent>
+<hex sha256 of the exact body bytes (sha256("") when empty)>
+<tenantId>
+<workspaceId>
+<timestamp>
+<nonce>
+```
+
+Golden vector (all three implementations test against it): method `post`, path
+`/workspace/exec?x=1`, body `{}`, tenant `t`, workspace `w`, timestamp
+`1790000000`, nonce `abcdefghijklmnop` →
+`VH-AGENT-SIG-V1\nPOST\n/workspace/exec?x=1\n44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\nt\nw\n1790000000\nabcdefghijklmnop`.
+
+WebSocket tunnel: the envelope gains `paramsRaw` (the exact JSON the platform
+signed) and `sig: {keyId, timestamp, nonce, tenantId, workspaceId, signature}`.
+Method is `WS`, path is the command name, body is `paramsRaw`. A verified
+envelope runs `JSON.parse(paramsRaw)`; the unsigned `params` copy is used only
+by older agents, or in `warn`/`off` mode when the envelope is not signed.
+
+The agent rejects (in `enforce`) with 401 when:
+
+* the request has no signature, or the key id is unknown;
+* the signature does not verify;
+* `|now − timestamp| > 60 s`;
+* the nonce was already used (in-memory LRU, TTL 120 s, 100k entries);
+* the tenant does not match the agent's identity (`LOCAL_AGENT_TENANT_ID` →
+  `TENANT_ID` → `~/.deepdebug/config.json`). If the signed workspace is
+  non-empty, it must match `LOCAL_AGENT_WORKSPACE_ID` / `WORKSPACE_ID` (set
+  `LOCAL_AGENT_REQUIRE_WORKSPACE=true` to require it on every call). A shared
+  operator agent with no identity accepts any signed tenant.
+
+`X-Agent-Token` (`LOCAL_AGENT_TOKEN`) is still checked first, as the second
+factor. `GET /health` and `/metrics` stay public.
+
+## Exec allowlist
+
+`/workspace/exec`, `/workspace/run`, `/mcp/execute-command` and
+`/setup/run-command` accept a command only when every segment (`&&`, `||`,
+`;`, `|`) belongs to one of these families: read-only git; package-manager
+install, test, build or lint for an ecosystem detected in the workspace (npm,
+yarn, pnpm, mvn/mvnw, gradle/gradlew, pip, poetry, uv, go, cargo, dotnet); test
+runners; linters; file read/write inside the workspace root; or `cd` inside
+the root. `$VAR`, `$(...)`, backticks, subshells, `&`, here-docs, process
+substitution and paths outside the root are refused.
+
+Hardening rules:
+
+* **Wrappers are validated recursively.** `env`, `time`, `nice`, `timeout`,
+  `c8`, `nyc`, `npx`, `npm/pnpm exec`, `poetry run` and `uv run` wrap another
+  command, and that command must pass the same policy. `xargs` is refused.
+  Interpreter eval (`node -e/-p`, `python -c`, `sh/bash -c`) is never
+  allowed. Test runners refuse inline JSON config.
+* **Paths are realpath-resolved.** Every non-flag token that is path-like or
+  exists on disk, every `--opt=value`, every redirect target and every
+  `cd`/`git -C` directory is resolved with symlinks followed and must stay
+  inside the root. An unquoted glob may use wildcards only in its last segment,
+  and none of the symlinks it can match may point outside.
+* **Protected files.** A redirect, `tee`, `cp`, `mv`, `rm`, `touch`, `chmod`
+  or `sort -o` is refused on these paths: `.git/**`, hook dirs (`.husky`,
+  `.githooks`), and build/test config that executes code. That includes
+  `package.json`, `.npmrc`, lockfiles, `Makefile`, `pom.xml`, `*.gradle*`,
+  `gradle/wrapper`, `setup.py`, `pyproject.toml`, `conftest.py`, and
+  `*.config.js` for jest, vitest, eslint and similar tools. Those files change
+  only through the signed apply-patch tool.
+* **No write-then-execute.** A command string that writes files may not run a
+  package-manager, test or lint tool in a later segment. The source of truth is
+`src/utils/exec-policy.js`; the reason is returned in the 403 body.
+
+Two exceptions:
+
+1. **Human approval (REQUIRE_HUMAN).** An `X-VH-Approval` header (or
+   `approvalToken` in the body) holding a PolicyGate token
+   `vhapr1.<keyId>.<b64url payload>.<b64url sig>`. It is signed with the same
+   platform key over `VH-HUMAN-APPROVAL-V1\n<keyId>\n<payload segment>`. The
+   token is bound to the SHA-256 of the exact command, the tenant and the
+   workspace. It lives at most 15 minutes and can be used once.
+2. **Platform-authored tools.** A body with `commandOrigin: "platform"` and a
+   known `tool` (`create_branch`, `git_commit`, `git_push`, `close_pr`,
+   `delete_branch`, `publish_scope`, `current_branch`). It is honoured only
+   when the request signature verified. The model's free-form `run_command`
+   never carries it.
+
+## Rollout
+
+1. **Generate the keypair** on a trusted workstation. Keep the private key
+   off disk after upload.
+   ```sh
+   openssl genpkey -algorithm ed25519 -out local-agent-signing-key.pem
+   openssl pkey -in local-agent-signing-key.pem -pubout -outform DER | base64   # SPKI, 60 chars
+   ```
+2. **Store the private key** in Secret Manager as `local-agent-signing-key`
+   (PKCS#8 PEM) in `visionhammer`, and grant `secretAccessor` to the gateway
+   and agent2 runtime service accounts.
+   ```sh
+   gcloud secrets create local-agent-signing-key --replication-policy=automatic --data-file=local-agent-signing-key.pem
+   ```
+3. **Mount it on the signers.** On gateway and software-engineer (agent2)
+   Cloud Run, set
+   `--set-secrets=LOCAL_AGENT_SIGNING_KEY=local-agent-signing-key:latest` and
+   `--update-env-vars=LOCAL_AGENT_SIGNING_KEY_ID=vh-2026-09`. Without the key
+   they log once and send unsigned requests, as before. Remember
+   `--vpc-egress=private-ranges-only` on `run services update`.
+4. **Give the agents the public key:**
+   * Image default: add `{"keyId":"vh-2026-09","publicKey":"<SPKI b64>"}` to
+     `src/config/trusted-signing-keys.json` and cut a new image.
+   * BYOC provisioning: set `LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=<SPKI b64>`
+     on the gateway. `CloudEngineerService` copies it, along with
+     `LOCAL_AGENT_SIGNATURE_MODE` and `LOCAL_AGENT_EXEC_POLICY_MODE`, into
+     every ACI/Cloud Run agent it provisions.
+   * Operator QA agent: set the same env on `deepdebug-local-agent-qa`.
+5. **Soak in `warn`.** Watch the logs for `[agent-sig] WARN` and
+   `[exec-policy] WARN`. The logs are rate-limited, one line per reason and
+   path per minute. Expect zero signature warnings from updated platform
+   callers. Every exec warning is a command that `enforce` would block.
+6. **Flip to enforce** per agent: `LOCAL_AGENT_SIGNATURE_MODE=enforce` once
+   the signature warnings are zero. Set the gateway env to `enforce` so new
+   BYOC agents start enforced. Roll back by setting `warn` again, with no
+   redeploy of the platform.
+
+   Since 1.0.35 (security review 2026-10-11) the **exec policy defaults to
+   `enforce`**: a command outside the allowlist is refused unless it carries a
+   PolicyGate approval token or is a signed platform tool command. Set
+   `LOCAL_AGENT_EXEC_POLICY_MODE=warn` explicitly on an agent that still needs
+   the soak. In the same release the HTTP perimeter stopped defaulting to
+   `compat`: `AGENT_SHARED_SECRET` is enforced as `X-Agent-Token`, and an agent
+   with no token outside Cloud Run only answers loopback callers (the reverse
+   WS tunnel). `LOCAL_AGENT_AUTH=compat` is the explicit, logged opt-out.
+
+### Key rotation
+
+Add the new public key next to the old one (`kid1=...,kid2=...` / two file
+entries) on every agent. Then switch `LOCAL_AGENT_SIGNING_KEY` and
+`LOCAL_AGENT_SIGNING_KEY_ID` on the signers to the new version. After a day,
+remove the old public key. Approval tokens use the same keys.

package/env.example

@@ -39,3 +39,37 @@ LOG_LEVEL=info
 
 # For on-premise DeepDebug server
 # DEEPDEBUG_API_URL=https://deepdebug.internal.company.com
+
+# ─── Security (audit 2026-09) ───
+# LOCAL_AGENT_TOKEN: when set, every route except GET /health and /metrics
+# requires the X-Agent-Token header. Set it only once every caller (gateway,
+# agents) sends the header. AGENT_SHARED_SECRET (injected by the gateway on
+# BYOC ACI agents) is enforced the same way when LOCAL_AGENT_TOKEN is not set.
+# With neither (and outside Cloud Run) the agent is loopback-only: it binds
+# 127.0.0.1 and refuses non-loopback callers. LOCAL_AGENT_BIND_HOST overrides.
+# LOCAL_AGENT_TOKEN=
+# Extra browser origins allowed by CORS (comma-separated, exact match).
+# LOCAL_AGENT_CORS_ORIGINS=
+# Re-enable /setup/run-command, /setup/install-tool, /setup/run-auth-command.
+# LOCAL_AGENT_ENABLE_SETUP_COMMANDS=false
+# LOCAL_AGENT_AUTH=loopback  -> accept loopback callers only (laptop + WS tunnel)
+# LOCAL_AGENT_AUTH=off       -> emergency opt-out (NOT recommended)
+
+# ─── Signed + allow-listed commands (docs/signed-commands.md) ───
+# Trusted platform public keys (Ed25519), keyId=base64 (raw 32-byte or SPKI DER).
+# Several entries = rotation window. The image default lives in
+# src/config/trusted-signing-keys.json.
+# LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=MCowBQYDK2VwAyEA...
+# off | warn | enforce (default) — verify X-VH-Signature on every command.
+# Set warn only as a loud, temporary opt-out for a platform that does not sign yet.
+# LOCAL_AGENT_SIGNATURE_MODE=enforce
+# off | warn | enforce (default) — shell allowlist on exec endpoints.
+# LOCAL_AGENT_EXEC_POLICY_MODE=enforce
+# Identity the signature must match (defaults: TENANT_ID / WORKSPACE_ID).
+# LOCAL_AGENT_TENANT_ID=
+# LOCAL_AGENT_WORKSPACE_ID=
+# LOCAL_AGENT_REQUIRE_WORKSPACE=false
+
+# DLP (T4-09): mask secrets/PII before content leaves the agent. Default off.
+# LOCAL_AGENT_DLP_MODE=off|warn|enforce   (warn = count only, enforce = redact)
+# LOCAL_AGENT_DLP_BLOCK_CLASSES=private-key,cloud-credential   (enforce: withhold whole text)

package/helm/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: deepdebug-agent
 description: DeepDebug Local Agent for enterprise code debugging and analysis
 type: application
-version: 1.0.0
-appVersion: "1.0.0"
+version: 1.1.0
+appVersion: "1.1.0"
 keywords:
   - debugging
   - ai

package/helm/templates/deployment.yaml

@@ -38,14 +38,24 @@ spec:
               value: "production"
             - name: PORT
               value: "5055"
-            - name: DEEPDEBUG_API_URL
+            # Names aligned to what src/server.js actually reads (server.js frozen):
+            # GATEWAY_URL (server.js:73), TENANT_ID (:7505), WORKSPACE_ROOT (:637).
+            - name: GATEWAY_URL
               value: {{ .Values.config.apiUrl | quote }}
-            - name: DEEPDEBUG_TENANT_ID
+            - name: TENANT_ID
               valueFrom:
                 secretKeyRef:
                   name: {{ include "deepdebug-agent.fullname" . }}-secret
                   key: tenant-id
-            - name: DEEPDEBUG_WORKSPACE_PATH
+            # Without a token the agent is loopback-only (bind 127.0.0.1) and the
+            # kubelet probes would fail; with it, every route but /health and
+            # /metrics needs X-Agent-Token.
+            - name: LOCAL_AGENT_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "deepdebug-agent.fullname" . }}-secret
+                  key: agent-token
+            - name: WORKSPACE_ROOT
               value: {{ .Values.config.workspacePath | quote }}
             - name: LOG_LEVEL
               value: {{ .Values.config.logLevel | quote }}

package/helm/templates/networkpolicy.yaml

@@ -0,0 +1,22 @@
+{{- if .Values.networkPolicy.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+spec:
+  podSelector:
+    matchLabels:
+      {{- include "deepdebug-agent.selectorLabels" . | nindent 6 }}
+  policyTypes:
+    - Ingress
+  {{- with .Values.networkPolicy.allowFrom }}
+  ingress:
+    - from:
+        {{- toYaml . | nindent 8 }}
+      ports:
+        - protocol: TCP
+          port: 5055
+  {{- end }}
+{{- end }}

package/helm/templates/secret.yaml

@@ -7,3 +7,4 @@ metadata:
 type: Opaque
 data:
   tenant-id: {{ .Values.config.tenantId | b64enc | quote }}
+  agent-token: {{ required "config.agentToken is required (LOCAL_AGENT_TOKEN: the agent refuses remote callers without it)" .Values.config.agentToken | b64enc | quote }}

package/helm/values.yaml

@@ -27,6 +27,9 @@ replicaCount: 1
 # ─────────────────────────────────────────
 config:
   tenantId: ""  # Required: Your tenant ID
+  # Required: shared secret for X-Agent-Token (LOCAL_AGENT_TOKEN). Pass it with
+  # --set config.agentToken=$(openssl rand -hex 32); never commit it.
+  agentToken: ""
   apiUrl: "https://api.deepdebug.ai"
   logLevel: "info"
   
@@ -117,20 +120,6 @@ readinessProbe:
   timeoutSeconds: 5
   failureThreshold: 3
 
-# ─────────────────────────────────────────
-# Network Policies (Enterprise)
-# ─────────────────────────────────────────
-networkPolicy:
-  enabled: true
-  # Allow egress only to DeepDebug API
-  egressRules:
-    - to:
-        - ipBlock:
-            cidr: 0.0.0.0/0
-      ports:
-        - protocol: TCP
-          port: 443
-
 # ─────────────────────────────────────────
 # Pod Disruption Budget
 # ─────────────────────────────────────────
@@ -160,3 +149,13 @@ podAnnotations:
   prometheus.io/scrape: "true"
   prometheus.io/port: "5055"
   prometheus.io/path: "/metrics"
+
+# ─────────────────────────────────────────
+# Network Policy (security review 2026-10-11, C1)
+# ─────────────────────────────────────────
+# The agent reaches the platform over an OUTBOUND tunnel, so it needs no
+# inbound traffic except kubelet probes. Default: deny all ingress except the
+# sources listed in allowFrom (NetworkPolicy peers, e.g. a podSelector).
+networkPolicy:
+  enabled: true
+  allowFrom: []

package/mcp-server.js

@@ -6,6 +6,7 @@ import {
     ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import path from "path";
+import { createAuthMiddleware } from "./src/utils/agent-auth.js";
 import { spawn } from "child_process";
 import { exists, listRecursive, readFile, writeFile, stat } from "./fs-utils.js";
 import { detectProject, readText } from "./detectors.js";
@@ -454,6 +455,8 @@ function errorResponse(message) {
 export async function startMCPHttpServer(wsManager, port = 5056) {
     const express = (await import("express")).default;
     const app = express();
+    // SECURITY: execute_command runs `sh -c`; same auth perimeter as the main API.
+    app.use(createAuthMiddleware());
 
     const server = createMCPServer(wsManager);
 
@@ -522,7 +525,7 @@ export async function startMCPHttpServer(wsManager, port = 5056) {
         }
     });
 
-    app.listen(port, () => {
+    app.listen(port, process.env.MCP_BIND_HOST || "127.0.0.1", () => {
         console.log(`🧠 DeepDebug MCP Server listening on http://localhost:${port}`);
         console.log(`   SSE: http://localhost:${port}/sse`);
         console.log(`   REST: http://localhost:${port}/tool/{toolName}`);