dd-harness 0.36.0 → 0.38.0

package/README.md

@@ -1,103 +1,103 @@
-# dd-harness
-
-Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
-A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
-para skills e estado descartável fora do repositório.
-
-Requer Node >=20.3.0. CLI sem dependências de runtime.
-
-## Instalação e configuração
-
-```sh
-npm install -g dd-harness@latest
-npx -y dd-harness-mcp@latest --help
-dd-harness start --host todos
-```
-
-Para um projeto já criado no serviço:
-
-```sh
-dd-harness init --tenant meu-espaco --projeto meu-projeto
-dd-harness login --token <token>
-dd-harness integrar --host claude,codex,antigravity
-dd-harness diagnostico --mcp
-```
-
-`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
-`antigravity`, uma lista separada por vírgulas ou `todos`.
-`integrar` instala nos três por padrão e preserva configurações alheias.
-O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
-Para serviço local, use `init --api http://localhost:3000` antes do login.
-
-## Hosts
-
-| Host | MCP | Boot e guarda | Skills |
-|---|---|---|---|
-| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
-| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
-| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
-
-Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
-Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
-antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
-ela pode acrescentar confirmações. Não amplia permissões automaticamente.
-
-Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
-e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
-sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
-Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
-edições estruturadas, patches, remoções e renomeações.
-
-Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
-confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
-o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
-
-## Uso diário
-
-```sh
-dd-harness politica
-dd-harness buscar "contrato de integração"
-dd-harness ler regras/contrato
-dd-harness gravar memoria.md
-dd-harness editar memoria.md
-dd-harness arquivar regras/contrato --motivo obsoleta
-dd-harness status
-dd-harness skills
-dd-harness roadmap
-dd-harness changelog
-dd-harness --help
-```
-
-`check` mede e grava observações de deriva; `status` só consulta.
-O antigo comando `sync` não faz parte do CLI atual.
-`politica --hook` e `cinto` permanecem como compatibilidade legada;
-use `integrar` para instalar `sessao` e `guarda`.
-
-## Estado e conflitos
-
-- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
-  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
-- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
-- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
-  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
-  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
-- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
-- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
-  ou redirecionadas por links são preservadas e aparecem como conflitos.
-- Skills marcadas só por comando não são instaladas para descoberta automática em
-  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
-  Claude não são prometidos como portáveis.
-- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
-  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
-
-## Escritas e commits
-
-Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
-POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
-em escrita exige consultar o estado antes de tentar novamente.
-
-A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
-`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
-Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
-Git author nem concede autorização de commit/push. É regra de trabalho do agente,
-não inferência automática de identidade nem hook que renomeia commits humanos.
+# dd-harness
+
+Política e briefing carregados do serviço; memória consultada por MCP ou CLI.
+A fonte dos artefatos continua no serviço. O cliente mantém configuração, ponteiros
+para skills e estado descartável fora do repositório.
+
+Requer Node >=20.3.0. CLI sem dependências de runtime.
+
+## Instalação e configuração
+
+```sh
+npm install -g dd-harness@latest
+npx -y dd-harness-mcp@latest --help
+dd-harness start --host todos
+```
+
+Para um projeto já criado no serviço:
+
+```sh
+dd-harness init --tenant meu-espaco --projeto meu-projeto
+dd-harness login --token <token>
+dd-harness integrar --host claude,codex,antigravity
+dd-harness diagnostico --mcp
+```
+
+`start` usa Claude por padrão. `--host` aceita `claude`, `codex`,
+`antigravity`, uma lista separada por vírgulas ou `todos`.
+`integrar` instala nos três por padrão e preserva configurações alheias.
+O token nasce em /tokens e fica em ~/.dd-harness/credentials.json, por origem de API.
+Para serviço local, use `init --api http://localhost:3000` antes do login.
+
+## Hosts
+
+| Host | MCP | Boot e guarda | Skills |
+|---|---|---|---|
+| Claude Code | .mcp.json | .claude/settings.json | .claude/skills |
+| Codex | .codex/config.toml | .codex/hooks.json | .agents/skills |
+| Antigravity | .agents/mcp_config.json | .agents/hooks.json | .agents/skills |
+
+Codex exige revisão/confiança dos hooks em /hooks. Instalação não comprova ativação.
+Antigravity usa PreInvocation e mensagem efêmera: política e briefing são consultados
+antes de cada inferência. Sua guarda usa `ask` para respeitar concessões já existentes;
+ela pode acrescentar confirmações. Não amplia permissões automaticamente.
+
+Sem boot válido, a guarda recusa ferramentas cobertas, inclusive shell. Leitura conhecida
+e onboarding controlado continuam possíveis. Os hooks precisam estar ativos: não são
+sandbox nem controlam ferramentas que o aplicativo não encaminha a eles.
+Após boot válido, shell não tem análise de diff antecipada; avisos por âncora cobrem
+edições estruturadas, patches, remoções e renomeações.
+
+Configurações MCP novas levam DD_HARNESS_ROOT explícito. Ao copiar/mover um checkout,
+confira essa raiz com diagnostico. O MCP recusa divergência entre a raiz explícita e
+o projeto identificado no diretório de execução. Corrija a configuração e reinicie o host.
+
+## Uso diário
+
+```sh
+dd-harness politica
+dd-harness buscar "contrato de integração"
+dd-harness ler regras/contrato
+dd-harness gravar memoria.md
+dd-harness editar memoria.md
+dd-harness arquivar regras/contrato --motivo obsoleta
+dd-harness status
+dd-harness skills
+dd-harness roadmap
+dd-harness changelog
+dd-harness --help
+```
+
+`check` mede e grava observações de deriva; `status` só consulta.
+O antigo comando `sync` não faz parte do CLI atual.
+`politica --hook` e `cinto` permanecem como compatibilidade legada;
+use `integrar` para instalar `sessao` e `guarda`.
+
+## Estado e conflitos
+
+- Política/briefing não são materializados. Âncoras/resumos, sessão e manifestos ficam
+  em ~/.dd-harness/repos, isolados por caminho/projeto/credencial quando aplicável.
+- DD_HARNESS_HOME permite isolamento explícito em testes. Nunca aponte testes ao estado pessoal.
+- Uma sessão validada expira em quatro horas. Boot, retomada e compactação revalidam.
+  Alterações locais de política/briefing via MCP invalidam a sessão; reabra depois de editar.
+  Alterações remotas feitas por outro cliente são percebidas no próximo boot/revalidação.
+- Curadoria invalida as âncoras do checkout atual. A próxima edição as consulta novamente.
+- Só ponteiros registrados e intactos são atualizados/removidos. Skills manuais, editadas
+  ou redirecionadas por links são preservadas e aparecem como conflitos.
+- Skills marcadas só por comando não são instaladas para descoberta automática em
+  .agents; use listar_skills/ler_skill após pedido explícito. Metadados próprios do
+  Claude não são prometidos como portáveis.
+- Se há fila e worker local configurado, o boot solicita um lote. O log fica em
+  ~/.dd-harness/worker.log; solicitar não significa que a indexação concluiu.
+
+## Escritas e commits
+
+Só GET/HEAD têm retry automático (até três tentativas, timeout por tentativa).
+POST/PATCH/PUT/DELETE não são repetidos. Falha de conexão, 5xx ou resposta incompleta
+em escrita exige consultar o estado antes de tentar novamente.
+
+A política entregue exige `[IDENTIFICAÇÃO] - tipo: descrição` nos commits de agentes:
+`[CODEX] - feat: ...`, `[CLAUDE] - fix: ...`, `[GEMINI] - docs: ...`.
+Identifique quem realmente commitou, inclusive ao usar outro editor. A regra não altera
+Git author nem concede autorização de commit/push. É regra de trabalho do agente,
+não inferência automática de identidade nem hook que renomeia commits humanos.

package/dist/atualizar.d.ts

@@ -21,6 +21,18 @@ export type Item = {
  * maquina, nao por projeto).
  */
 export declare function diagnosticaAtualizacao(raiz: string, versaoInstalada: string, versaoPublicada: string | null): Promise<Item[]>;
+/**
+ * Incorpora ao projeto as skills iniciais escolhidas pelo usuario.
+ *
+ * Recebe os slugs em vez de criar tudo que falta, e essa e a diferenca que importa: skill
+ * pode ter sido apagada de proposito, e criar a lista inteira desfaria a decisao de quem
+ * apagou. Quem chama aqui e a skill `atualizar-harness`, depois do "sim" a cada uma.
+ */
+export declare function incorporaSkills(raiz: string, slugs: string[]): Promise<{
+    criadas: string[];
+    falharam: string[];
+    ponteiros: string;
+}>;
 /**
  * Aplica so os itens marcados `aplicar`. Os de `perguntar` ficam intactos de proposito —
  * quem decide sobre arquivo editado a mao e o dono dele.

package/dist/atualizar.js

@@ -74,66 +74,113 @@ export async function diagnosticaAtualizacao(raiz, versaoInstalada, versaoPublic
     // daquela epoca, e as que vieram depois so existiam em projeto criado do zero. Este item
     // e o caminho que faltava.
     //
-    // Skill inicial que falta e skill que NASCEU DEPOIS deste projeto — as padrao nao se
-    // apagam, entao ausencia aqui nao e decisao de ninguem, e recria-la nao desfaz nada.
-    // Por isso `aplicar`: e o mesmo caso do hook que faltava, e nao o do CLAUDE.md editado.
-    //
-    // A skill do projeto continua editavel: criar a que falta nao mexe em nenhuma existente,
-    // e o `criaSkill` erra de proposito se o slug ja existir.
+    // `perguntar`, nunca `aplicar`: skill PODE ser apagada, entao do lado de fora "nasceu
+    // depois deste projeto" e "eu apaguei porque nao quero" sao indistinguiveis — e recriar
+    // sozinho desfaria a segunda em silencio, toda vez que alguem rodasse o comando. Quem
+    // sabe qual dos dois e o dono; o diagnostico so mostra o que falta e para que serve.
+    let doServico = null;
     try {
-        const existentes = new Set((await leSkills(raiz)).map(s => s.slug));
-        const faltando = SKILLS_INICIAIS.filter(s => !existentes.has(s.slug)).map(s => s.slug);
+        doServico = await leSkills(raiz);
+    }
+    catch {
+        // So a REDE cai aqui. O que vem depois e disco, e misturar os dois no mesmo try faz um
+        // erro de leitura de arquivo ser reportado como "o serviço não respondeu" — mentira que
+        // manda procurar o problema no lugar errado.
+        itens.push({ o_que: "skills", situacao: "não consegui consultar o serviço", acao: "manual",
+            detalhe: "confira com `dd-harness skills` quando o serviço responder" });
+    }
+    if (doServico) {
+        const existentes = new Set(doServico.map(s => s.slug));
+        const faltando = SKILLS_INICIAIS.filter(s => !existentes.has(s.slug));
+        // Sem ponteiro em disco, a skill EXISTE no servico e nenhum host a descobre — o Claude
+        // Code le `.claude/skills/*/SKILL.md` na abertura da sessao. Some por apagar o .md ou
+        // por renomear a pasta, e some CALADA: `dd-harness skills` continua listando a skill,
+        // entao a unica pista e ela nunca ser invocada. Caso diferente do de baixo, e este se
+        // resolve sozinho: reescrever o ponteiro nao desfaz decisao nenhuma sobre a skill.
+        const destinos = [...new Set((await hostsInstalados(raiz))
+                .map(h => h === "claude" ? ".claude" : ".agents"))];
+        const semPonteiro = [];
+        for (const skill of doServico) {
+            for (const destino of destinos.length ? destinos : [".claude"]) {
+                // No `.agents` a skill so-por-comando nao ganha ponteiro de proposito: ausencia ali
+                // e desenho, nao perda.
+                if (destino === ".agents" && skill.so_por_comando)
+                    continue;
+                // So ENOENT conta como "sem ponteiro". Permissao negada ou disco com erro nao e
+                // ponteiro faltando, e tratar como se fosse mandaria reescrever por cima de um
+                // problema que e outro.
+                const existe = await readFile(join(raiz, destino, "skills", skill.slug, "SKILL.md"), "utf8")
+                    .then(() => true)
+                    .catch((e) => { if (e.code === "ENOENT")
+                    return false; throw e; });
+                if (!existe) {
+                    semPonteiro.push(`${destino}/skills/${skill.slug}`);
+                }
+            }
+        }
+        if (semPonteiro.length) {
+            itens.push({
+                o_que: "ponteiros de skill",
+                situacao: `${semPonteiro.length} skill(s) do serviço sem arquivo em disco`,
+                acao: "aplicar",
+                detalhe: `${semPonteiro.join(", ")} — o host não descobre a skill sem o ponteiro; será reescrito`,
+            });
+        }
         itens.push(faltando.length === 0
             ? { o_que: "skills", situacao: `${existentes.size} no projeto; nenhuma inicial faltando`, acao: "em-dia" }
             : {
                 o_que: "skills",
-                situacao: `${faltando.length} skill(s) inicial(is) nasceram depois deste projeto`,
-                acao: "aplicar",
-                detalhe: `${faltando.join(", ")} — serão criadas no serviço; as existentes não são tocadas`,
+                situacao: `${faltando.length} skill(s) inicial(is) não estão neste projeto`,
+                acao: "perguntar",
+                // A descricao inteira, nao so o slug: e o campo que diz QUANDO a skill serve, e
+                // sem ele a pergunta vira "quer `revisar-memoria`?" — que ninguem responde bem.
+                detalhe: faltando.map(s => `${s.slug}: ${s.descricao}`).join("\n"),
             });
     }
-    catch {
-        // Sem rede ou sem credencial: o resto do diagnostico continua valendo, e skill faltando
-        // nao e urgente o bastante para derrubar a checagem inteira.
-        itens.push({ o_que: "skills", situacao: "não consegui consultar o serviço", acao: "manual",
-            detalhe: "confira com `dd-harness skills` quando o serviço responder" });
-    }
     return itens;
 }
-/** Cria no serviço as skills iniciais que este projeto ainda não tem. */
-async function criaSkillsFaltantes(raiz) {
-    const existentes = new Set((await leSkills(raiz)).map(s => s.slug));
-    const faltando = SKILLS_INICIAIS.filter(s => !existentes.has(s.slug));
+/** Reescreve em disco os ponteiros das skills que o serviço tem. */
+async function reescrevePonteiros(raiz) {
+    const destinos = [...new Set((await hostsInstalados(raiz))
+            .map(h => h === "claude" ? ".claude" : ".agents"))];
+    const r = await escrevePonteirosDeSkills(raiz, await leSkills(raiz), destinos.length ? destinos : [".claude"]);
+    return `ponteiros de skill: ${r.escritos} reescrito(s)` +
+        (r.conflitos.length ? `; ${r.conflitos.length} preservado(s) por edição local` : "");
+}
+/**
+ * Incorpora ao projeto as skills iniciais escolhidas pelo usuario.
+ *
+ * Recebe os slugs em vez de criar tudo que falta, e essa e a diferenca que importa: skill
+ * pode ter sido apagada de proposito, e criar a lista inteira desfaria a decisao de quem
+ * apagou. Quem chama aqui e a skill `atualizar-harness`, depois do "sim" a cada uma.
+ */
+export async function incorporaSkills(raiz, slugs) {
     const criadas = [];
     const falharam = [];
-    for (const inicial of faltando) {
+    for (const slug of slugs) {
+        const inicial = SKILLS_INICIAIS.find(s => s.slug === slug);
+        if (!inicial) {
+            falharam.push(`${slug} (não é uma skill inicial)`);
+            continue;
+        }
         try {
             await criaSkill(raiz, inicial);
-            criadas.push(inicial.slug);
+            criadas.push(slug);
         }
-        catch {
-            // Uma que nao entrou nao impede as outras: metade criada e melhor que nenhuma, e a
-            // linha de retorno diz exatamente qual faltou.
-            falharam.push(inicial.slug);
+        catch (erro) {
+            // Uma que nao entrou nao impede as outras: metade incorporada e melhor que nenhuma,
+            // e o retorno diz qual faltou e por que.
+            falharam.push(`${slug} (${erro instanceof Error ? erro.message : String(erro)})`);
         }
     }
+    // Sem o ponteiro em disco a skill existe no servico e host nenhum a descobre; criar e
+    // parar aqui entregaria uma skill invisivel ate o boot seguinte.
     let ponteiros = "";
-    // A skill no servico nao e descoberta por host nenhum sem o ponteiro em disco: o Claude
-    // Code le `.claude/skills/*/SKILL.md` na abertura da sessao, e MCP nao fornece skill.
-    // Criar no servico e parar aqui entregaria uma skill que so aparece no boot seguinte.
     if (criadas.length) {
-        try {
-            const hosts = await hostsInstalados(raiz);
-            const destinos = [...new Set(hosts.map(h => h === "claude" ? ".claude" : ".agents"))];
-            const r = await escrevePonteirosDeSkills(raiz, await leSkills(raiz), destinos.length ? destinos : [".claude"]);
-            ponteiros = `; ${r.escritos} ponteiro(s) em disco`;
-        }
-        catch {
-            ponteiros = "; ponteiros NÃO escritos — rode `dd-harness integrar` ou reabra a sessão";
-        }
+        ponteiros = await reescrevePonteiros(raiz)
+            .catch(() => "ponteiros NÃO escritos — rode `dd-harness atualizar --aplicar` ou reabra a sessão");
     }
-    return `skills: ${criadas.length} criada(s)${criadas.length ? " — " + criadas.join(", ") : ""}` +
-        (falharam.length ? `; FALHARAM: ${falharam.join(", ")}` : "") + ponteiros;
+    return { criadas, falharam, ponteiros };
 }
 /**
  * Aplica so os itens marcados `aplicar`. Os de `perguntar` ficam intactos de proposito —
@@ -152,12 +199,14 @@ export async function aplicaAtualizacao(raiz, itens) {
             // um projeto que continua sem o cinto.
             feitos.push(r.ok ? `hooks: ${r.estado}` : `hooks: NÃO aplicado (${r.motivo})`);
         }
-        else if (item.o_que === "skills") {
+        else if (item.o_que === "ponteiros de skill") {
+            // Seguro no `--aplicar`: reescrever o ponteiro de uma skill que o servico tem nao
+            // decide nada sobre a skill — so devolve ao host a chance de descobri-la.
             try {
-                feitos.push(await criaSkillsFaltantes(raiz));
+                feitos.push(await reescrevePonteiros(raiz));
             }
             catch (erro) {
-                feitos.push(`skills: NÃO aplicado (${erro instanceof Error ? erro.message : String(erro)})`);
+                feitos.push(`ponteiros de skill: NÃO aplicado (${erro instanceof Error ? erro.message : String(erro)})`);
             }
         }
     }

package/dist/diagnostico.js

@@ -5,9 +5,14 @@ import { achaRaiz, leConfigDoRepo, leToken } from "./config.js";
 import { buscaPolitica } from "./politica.js";
 export async function handshakeMcp(raiz, comando = "npx", args = ["-y", "dd-harness-mcp@latest"]) {
     return new Promise((resolve, reject) => {
+        // `DD_HARNESS_ROOT` fica FORA: passa-la aqui testaria um cenario que o host nao
+        // reproduz, e esconderia justamente a falha procurada — com a raiz explicita correta o
+        // servidor sobe ate quando a declaracao versionada esta quebrada para outra maquina.
+        // O cwd e a raiz, que e como o host lanca.
+        const { DD_HARNESS_ROOT: _ignorado, ...ambiente } = process.env;
         const filho = spawn(comando, args, { cwd: raiz, windowsHide: true,
             shell: process.platform === "win32" && comando === "npx", stdio: ["pipe", "pipe", "pipe"],
-            env: { ...process.env, DD_HARNESS_ROOT: raiz } });
+            env: ambiente });
         let buffer = "", terminou = false, versao = "desconhecida";
         const fim = (erro, resultado) => {
             if (terminou)
@@ -79,8 +84,13 @@ export async function diagnostico(inicio, testarMcp = false) {
         const h = await readFile(join(raiz, hook), "utf8").catch(() => "");
         linhas.push(`${host}: MCP ${m.includes("dd-harness") ? "declarado" : "ausente"}; ` +
             `hooks ${h.includes("dd-harness guarda") && h.includes("dd-harness sessao") ? "declarados" : "ausentes/legados"}; ativação no host requer verificação.`);
-        if (m.includes("dd-harness") && !m.includes(JSON.stringify(raiz)))
-            linhas.push(`${host}: confira DD_HARNESS_ROOT; a raiz explícita atual não foi reconhecida.`);
+        // Invertido de proposito: a raiz explicita era exigida, e passou a ser o defeito. O
+        // arquivo vai para o git, entao um caminho absoluto so vale na maquina que gerou —
+        // noutro checkout o servidor lanca antes do handshake e o host so ve conexao fechada.
+        if (m.includes("dd-harness") && m.includes("DD_HARNESS_ROOT")) {
+            linhas.push(`${host}: DD_HARNESS_ROOT declarado em ${config} — remova. ` +
+                `Caminho absoluto em arquivo versionado quebra em outro checkout; sem ele a raiz sai do cwd.`);
+        }
     }
     const politica = await buscaPolitica(raiz);
     linhas.push(`Contexto: ${politica.estado}${politica.estado === "inalcancavel" ? " — " + politica.motivo : ""}`);

package/dist/escreve-config.js

@@ -140,28 +140,28 @@ export const escreveAgents = (raiz) => escrevePonteiro(raiz, "AGENTS.md");
  * em producao compara para saber se precisa de atualizacao.
  */
 export const VERSAO_DO_MOLDE = "v1.3.0";
-export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
-
-Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
-
-**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
-\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
-de ler código, responder ou planejar.
-
-- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
-  avise o usuário e **não modifique nada** até ele resolver.
-- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
-
-Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
-
-Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
-desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
-válido — não crie fase sem o usuário pedir.
-
-E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
-ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
-já saiu errado, e é tarde.
-
-Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
-frase que antecede pular o procedimento. A política diz quais são obrigatórias
+export const SUGESTAO_AGENTS = `## Protocolo do dd-harness
+
+Este projeto tem um protocolo de trabalho que **não está neste arquivo**.
+
+**ANTES de qualquer outra coisa**, chame a ferramenta MCP \`ler_artefato\` com
+\`tipo: "politica"\` e siga o que ela devolver. É a primeira ação da sessão, antes
+de ler código, responder ou planejar.
+
+- Se a ferramenta não existir, o servidor MCP do dd-harness não está declarado:
+  avise o usuário e **não modifique nada** até ele resolver.
+- Se ela devolver vazio, este projeto nunca foi briefado — diga isso ao usuário.
+
+Leia também o briefing com a mesma ferramenta (tipo briefing). Os dois são obrigatórios.
+
+Depois, \`ler_roadmap\`: se houver uma fase **Agora**, é dela que saem os passos
+desta sessão. Lista vazia significa que este projeto não usa roadmap, e isso é
+válido — não crie fase sem o usuário pedir.
+
+E \`listar_skills\`: são os procedimentos deste projeto. **Invoque a que couber
+ANTES de fazer o trabalho, não depois** — skill lida no fim vira revisão do que
+já saiu errado, e é tarde.
+
+Vale mesmo quando o pedido parece pequeno: "é só um ajuste" é exatamente a
+frase que antecede pular o procedimento. A política diz quais são obrigatórias
 e quando.`;

package/dist/hosts.js

@@ -1,4 +1,5 @@
-import { readFile, mkdir } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { access, readFile, mkdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { escreveAtomico, estadoDoRepo } from "./estado-local.js";
 import { escrevePonteiro, SUGESTAO_AGENTS } from "./escreve-config.js";
@@ -48,11 +49,84 @@ function grupo(doc, evento, command, antigos = []) {
     preservados.push({ hooks: [{ type: "command", command, timeout: 60 }] });
     doc[evento] = preservados;
 }
+/**
+ * Onde o `dd-harness-mcp` instalado guarda o arquivo de entrada, ou `null` se nao houver.
+ *
+ * O caminho sai do `bin` do proprio pacote, nao de um literal daqui: ele ja mudou uma vez
+ * (`dist/mcp/src/`, porque o build abrange dois diretorios) e um literal duplicado
+ * envelheceria em silencio — apontando para um arquivo que nao existe, o que o host
+ * reporta como CONNECTION_CLOSED sem dizer mais nada.
+ */
+async function entradaDoMcp() {
+    // `devolve` e nao `resolve`: o `resolve` de `node:path` esta no escopo deste modulo, e
+    // o parametro o sombrearia dentro do callback.
+    const raizGlobal = await new Promise(devolve => {
+        execFile("npm", ["root", "-g"], { shell: process.platform === "win32" }, (erro, saida) => devolve(erro ? "" : saida.trim()));
+    });
+    if (!raizGlobal)
+        return null;
+    const pasta = join(raizGlobal, "dd-harness-mcp");
+    try {
+        const { bin } = JSON.parse(await readFile(join(pasta, "package.json"), "utf8"));
+        const relativo = typeof bin === "string" ? bin : bin?.["dd-harness-mcp"];
+        if (!relativo)
+            return null;
+        const entrada = join(pasta, relativo);
+        await access(entrada);
+        return entrada;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Config de MCP e artefato de MAQUINA, nao de projeto: o bloco carrega o caminho do node
+ * e do pacote instalado ali. Versionar isso entrega a um clone o valor de quem gerou, e o
+ * sintoma no outro lado e sempre o mesmo CONNECTION_CLOSED — que nao diz nada sobre a
+ * causa. Quem clona roda `integrar` e recebe o seu.
+ *
+ * Acrescenta ao que ja existir, sem reescrever: `.gitignore` e arquivo do projeto.
+ */
+async function ignoraConfigDeMaquina(raiz, caminhos) {
+    const arquivo = join(raiz, ".gitignore");
+    const atual = await readFile(arquivo, "utf8").catch((e) => {
+        if (e.code === "ENOENT")
+            return "";
+        throw e;
+    });
+    const linhas = new Set(atual.split(/\r?\n/).map(l => l.trim()));
+    const faltam = caminhos.filter(c => !linhas.has(c));
+    if (!faltam.length)
+        return;
+    const bloco = "# dd-harness: config de MCP e por maquina — rode `dd-harness integrar`\n" + faltam.join("\n") + "\n";
+    await escreveAtomico(arquivo, atual && !atual.endsWith("\n") ? `${atual}\n${bloco}` : atual + bloco);
+}
 /** Cada host usa seu formato. Configuração alheia não é inferida como gerenciada. */
 export async function instalaHosts(raiz, hosts) {
     raiz = resolve(raiz);
     const avisos = [];
-    const mcp = { command: "npx", args: ["-y", "dd-harness-mcp@latest"], env: { DD_HARNESS_ROOT: raiz } };
+    // `npx` NAO serve no Windows, e nao ha variante que sirva: o host lanca o servidor com
+    // `spawn` sem shell, e ali `npx` da ENOENT (nao existe executavel com esse nome) e
+    // `npx.cmd` da EINVAL (o Node recusa .bat/.cmd sem shell desde a CVE-2024-27980). Os
+    // dois chegam ao cliente como CONNECTION_CLOSED, que parece servidor morrendo e nao
+    // comando inalcancavel. Apontar o proprio node para o arquivo e o que sobra — e e o que
+    // todo MCP que funciona nesta plataforma ja faz.
+    //
+    // Gravar caminho de maquina aqui so e legitimo porque estes arquivos sao de maquina: o
+    // `integrar` os poe no .gitignore, e quem clona roda `integrar` e recebe o seu. Num
+    // arquivo versionado seria o mesmo erro que DD_HARNESS_ROOT ja foi.
+    //
+    // Sem DD_HARNESS_ROOT: `raizDoMcp` resolve a raiz pelo cwd, que e onde o host lanca o
+    // servidor. Com a variavel, um caminho de outro checkout o faz lancar antes do
+    // handshake — mesmo CONNECTION_CLOSED, outra causa.
+    const entrada = await entradaDoMcp();
+    const mcp = entrada
+        ? { command: process.execPath, args: [entrada] }
+        : { command: "npx", args: ["-y", "dd-harness-mcp@latest"] };
+    if (!entrada && process.platform === "win32") {
+        avisos.push("MCP declarado via npx, que nao sobe no Windows: instale com " +
+            "`npm i -g dd-harness-mcp@latest` e rode `dd-harness integrar` de novo.");
+    }
     for (const host of hosts) {
         if (host === "codex") {
             const caminho = join(raiz, ".codex", "config.toml");
@@ -62,10 +136,11 @@ export async function instalaHosts(raiz, hosts) {
                 throw e;
             });
             if (atual.includes("dd-harness")) {
-                avisos.push("Codex: servidor já configurado; preservado. Confira command e DD_HARNESS_ROOT com diagnostico.");
+                avisos.push("Codex: servidor já configurado; preservado. Confira o command com diagnostico.");
             }
             else {
-                await escreveAtomico(caminho, atual + `\n[mcp_servers.dd-harness]\ncommand = "npx"\nargs = ["-y", "dd-harness-mcp@latest"]\nstartup_timeout_sec = 60\n[mcp_servers.dd-harness.env]\nDD_HARNESS_ROOT = ${JSON.stringify(raiz)}\n`);
+                const args = mcp.args.map(a => JSON.stringify(a)).join(", ");
+                await escreveAtomico(caminho, atual + `\n[mcp_servers.dd-harness]\ncommand = ${JSON.stringify(mcp.command)}\nargs = [${args}]\nstartup_timeout_sec = 60\n`);
             }
             await json(join(raiz, ".codex", "hooks.json"), doc => {
                 const h = objeto(doc.hooks);
@@ -120,6 +195,7 @@ export async function instalaHosts(raiz, hosts) {
             }
         }
     }
+    await ignoraConfigDeMaquina(raiz, hosts.map(h => h === "claude" ? ".mcp.json" : h === "codex" ? ".codex/config.toml" : ".agents/mcp_config.json"));
     await mkdir(dirname(join(raiz, "AGENTS.md")), { recursive: true });
     await escrevePonteiro(raiz, "AGENTS.md");
     if (hosts.includes("claude"))