dd-harness 0.31.0 → 0.32.0

package/README.md

@@ -1,64 +1,103 @@
-# dd-harness
-
-Materializa a **política**, o **briefing** e o **Brain** do
-[dd-harness](https://dd-harness.vercel.app) dentro do seu repositório, para que a sessão
-do agente de código abra já sabendo as regras e as decisões do projeto.
-
-Sem dependência: `fetch`, `crypto` e `fs` são do Node. Um CLI que vive pinado em
-repositório alheio precisa envelhecer bem, e cada dependência é uma chance de não
-envelhecer.
-
-## Instalação
-
-```sh
-npm install -g dd-harness
-```
-
-Ou sem instalar nada:
-
-```sh
-npx dd-harness sync
-```
-
-Requer Node 20 ou mais novo.
-
-## Uso
-
-```sh
-dd-harness init --tenant <espaço> --projeto <projeto>   # prepara o repositório
-dd-harness login --token <token>                        # credencial desta máquina
-dd-harness sync                                         # escreve os artefatos
-dd-harness check [--commit <sha>]                       # mede âncoras e reporta deriva
-dd-harness status                                       # só lê: o que espera julgamento
-```
-
-O token pessoal nasce na tela `/tokens` do serviço. Ele é guardado em
-`~/.dd-harness/credentials.json` (modo `0600`, por origem de API) — **fora** do
-repositório, para não viajar num commit.
-
-## O que aparece no seu repositório
-
-```
-.dd-harness.json      configuração (tenant, projeto, api) — escrita à mão
-CLAUDE.md             SEU arquivo; o sync nunca o reescreve
-dd-harness/           tudo o que é gerado
-  politica.md
-  BRIEFING.md
-  brain/
-  manifest.json
-```
-
-Na raiz fica apenas o **seu** `CLAUDE.md`, que importa a política com a linha
-`@dd-harness/politica.md`. Isso deixa conviverem a parte gerenciada e o que o
-repositório tem de próprio — adotar um projeto existente é acrescentar uma linha, não
-sobrescrever nada.
-
-O `sync` confere esse ponteiro a cada execução, inclusive quando o serviço não mudou:
-import quebrado ou linha ausente faz a sessão abrir **sem política e sem avisar**. Isso
-foi medido, não suposto.
-
-## Deriva
-
-`dd-harness check` mede as âncoras das memórias contra o estado real do repositório e
-reporta o que saiu do lugar. Com `--commit <sha>` ele também cruza as âncoras com o diff
-daquele commit — a memória volta ao code review. Nada bloqueia: avisa.
+# 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/api.d.ts

@@ -19,3 +19,5 @@ export declare function credencial(raiz: string): Promise<Credencial>;
 export declare function recusa(resposta: Response): Promise<never>;
 export declare function cabecalhos(token: string, comCorpo?: boolean): Record<string, string>;
 export declare function pede(url: string | URL, init?: RequestInit, tentativas?: number): Promise<Response>;
+/** A conexão também pode cair depois dos headers, enquanto o corpo é consumido. */
+export declare function jsonDaEscrita(resposta: Response): Promise<unknown>;

package/dist/api.js

@@ -20,44 +20,39 @@ export function cabecalhos(token, comCorpo = false) {
         ? { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }
         : { Authorization: `Bearer ${token}` };
 }
-/**
- * `fetch` com nova tentativa para falha transitoria.
- *
- * Medido em uso real: um `ECONNRESET` de conexao ociosa derrubou um `arquivar` que
- * funcionou na segunda tentativa manual. Sem retry, falha de rede de um segundo vira erro
- * final — e para um agente isso e a diferenca entre seguir sozinho e parar para pedir
- * ajuda. Com varios agentes concorrendo, transitorio deixa de ser raro.
- *
- * O que NAO e repetido, e o cuidado que importa:
- *
- * - Erro de aplicacao (4xx). Token invalido ou memoria fora dos filtros nao melhora na
- *   segunda tentativa; repetir so atrasa a mensagem que o agente precisa ler.
- * - 5xx em requisicao que ESCREVE. `POST /memorias` pode ter gravado antes de a resposta
- *   se perder, e repetir criaria duas. Perder a resposta de uma escrita que funcionou e
- *   ruim; gravar duas vezes e pior.
- *
- * Entao: repete falha de REDE (o `fetch` nem chegou a receber resposta) sempre, e 5xx
- * apenas quando o metodo e seguro de repetir.
- */
-const IDEMPOTENTES = new Set(["GET", "HEAD", "PUT", "DELETE"]);
+/** Retry limitado a leituras; erro de transporte em escrita deixa resultado incerto. */
+// Mesmo PUT/DELETE podem ter auditoria, triggers ou conflito após a primeira aplicação.
+// Só leituras são repetidas automaticamente; erro de transporte não prova ausência de commit.
+const LEITURAS = new Set(["GET", "HEAD"]);
 const espera = (ms) => new Promise((r) => setTimeout(r, ms));
 export async function pede(url, init = {}, tentativas = 3) {
     const metodo = (init.method ?? "GET").toUpperCase();
-    const podeRepetirErroDoServidor = IDEMPOTENTES.has(metodo);
+    const podeRepetirErroDoServidor = LEITURAS.has(metodo);
+    if (!Number.isInteger(tentativas) || tentativas < 1)
+        throw new Error("tentativas deve ser inteiro positivo");
     let ultimoErro;
     for (let tentativa = 1; tentativa <= tentativas; tentativa += 1) {
         try {
-            const resposta = await fetch(url, init);
+            const timeout = AbortSignal.timeout(10000);
+            const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+            const resposta = await fetch(url, { ...init, signal });
+            if (resposta.status >= 500 && !podeRepetirErroDoServidor) {
+                await resposta.body?.cancel();
+                throw new Error(`HTTP ${resposta.status}: o servidor pode ter aplicado a escrita antes de falhar`);
+            }
             if (resposta.status >= 500 && podeRepetirErroDoServidor && tentativa < tentativas) {
+                await resposta.body?.cancel();
                 await espera(tentativa * 400);
                 continue;
             }
             return resposta;
         }
         catch (erro) {
-            // Aqui o `fetch` falhou antes de qualquer resposta: DNS, conexao recusada,
-            // ECONNRESET. Nada foi processado do outro lado, entao repetir e seguro mesmo
-            // para POST.
+            if (!podeRepetirErroDoServidor) {
+                throw new Error(`resultado incerto de ${metodo}: não houve confirmação confiável e a escrita pode ter sido aplicada. Consulte o estado antes de tentar novamente.`, { cause: erro });
+            }
+            if (init.signal?.aborted)
+                throw erro;
             ultimoErro = erro;
             if (tentativa === tentativas)
                 break;
@@ -67,3 +62,12 @@ export async function pede(url, init = {}, tentativas = 3) {
     const detalhe = ultimoErro instanceof Error ? ultimoErro.message : String(ultimoErro);
     throw new Error(`não consegui falar com o serviço depois de ${tentativas} tentativas: ${detalhe}`);
 }
+/** A conexão também pode cair depois dos headers, enquanto o corpo é consumido. */
+export async function jsonDaEscrita(resposta) {
+    try {
+        return await resposta.json();
+    }
+    catch (cause) {
+        throw new Error("resultado incerto: a resposta da escrita ficou incompleta. Consulte o estado antes de tentar novamente.", { cause });
+    }
+}

package/dist/artefato.js

@@ -1,4 +1,5 @@
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
+import { invalidaContexto } from "./estado-local.js";
 /**
  * O `GET` devolve o payload inteiro (politica, briefing, pastas e memorias); aqui so o
  * artefato pedido interessa.
@@ -38,5 +39,8 @@ export async function escreveArtefato(raiz, tipo, conteudo) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaContexto(raiz).catch(() => {
+        throw new Error("Artefato aceito pela API, mas a sessão local não pôde ser invalidada. Reabra a sessão antes de trabalhar.");
+    });
+    return (await jsonDaEscrita(resposta));
 }

package/dist/cinto.d.ts

@@ -21,12 +21,14 @@ import type { Brain, Memoria } from "./brain.js";
  */
 /** Onde o cache vive. Fora do repositorio: nada do dd-harness volta a morar em disco versionado. */
 export declare function caminhoDoCache(raiz: string): string;
+export declare function invalidaCache(raiz: string): Promise<void>;
 /**
  * So o que o cruzamento precisa. O payload inteiro tem briefing, politica e o corpo de
  * toda memoria — carregar isso a cada `Edit` seria pagar leitura de disco grande para,
  * quase sempre, nao casar com nada.
  */
 export type CacheDeAncoras = {
+    projeto?: string;
     gravado_em: string;
     memorias: Pick<Memoria, "pasta" | "slug" | "titulo" | "resumo" | "status" | "ancoras" | "escopo">[];
 };

package/dist/cinto.js

@@ -1,4 +1,7 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { estadoDoRepo, escreveAtomico } from "./estado-local.js";
+import { leConfigDoRepo, leToken } from "./config.js";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { memoriasNoConteudo } from "./diff.js";
 /**
@@ -23,7 +26,16 @@ import { memoriasNoConteudo } from "./diff.js";
  */
 /** Onde o cache vive. Fora do repositorio: nada do dd-harness volta a morar em disco versionado. */
 export function caminhoDoCache(raiz) {
-    return join(raiz, ".claude", "dd-harness-ancoras.json");
+    return join(estadoDoRepo(raiz), "ancoras.json");
+}
+async function identidade(raiz) {
+    const config = await leConfigDoRepo(raiz).catch(() => null);
+    return createHash("sha256").update(JSON.stringify([config, config ? await leToken(config.api) : null])).digest("hex");
+}
+export async function invalidaCache(raiz) {
+    await rm(caminhoDoCache(raiz), { force: true }).catch(() => {
+        throw new Error("Gravação aceita pela API, mas o cache local não pôde ser invalidado. Reabra a sessão para reconstruí-lo.");
+    });
 }
 /**
  * Acrescenta UMA memoria ao cache, sem esperar a proxima sessao.
@@ -40,21 +52,23 @@ export function caminhoDoCache(raiz) {
  * Idempotente pelo endereco: regravar a mesma memoria substitui a entrada, nunca duplica.
  */
 export async function acrescentaAoCache(raiz, memoria) {
-    if (memoria.ancoras.length === 0)
+    const existente = await leCache(raiz);
+    if (!existente && memoria.ancoras.length === 0)
         return;
-    const atual = (await leCache(raiz)) ?? { gravado_em: "", memorias: [] };
+    const atual = existente ?? { gravado_em: "", memorias: [] };
     const endereco = `${memoria.pasta}/${memoria.slug}`;
     const cache = {
+        projeto: await identidade(raiz),
         gravado_em: new Date().toISOString(),
         memorias: [
             ...atual.memorias.filter((m) => `${m.pasta}/${m.slug}` !== endereco),
-            memoria,
+            ...(memoria.status === "ativa" && memoria.ancoras.length ? [memoria] : []),
         ],
     };
     try {
         const caminho = caminhoDoCache(raiz);
         await mkdir(dirname(caminho), { recursive: true });
-        await writeFile(caminho, `${JSON.stringify(cache)}\n`, "utf8");
+        await escreveAtomico(caminho, `${JSON.stringify(cache)}\n`);
     }
     catch {
         // Mesmo motivo do `guardaCache`: cache e otimizacao, nao contrato.
@@ -63,6 +77,7 @@ export async function acrescentaAoCache(raiz, memoria) {
 /** Guarda as ancoras do Brain para o hook consultar sem rede. Falha em silencio: cache e otimizacao, nao contrato. */
 export async function guardaCache(raiz, brain) {
     const cache = {
+        projeto: await identidade(raiz),
         gravado_em: new Date().toISOString(),
         memorias: brain.memorias
             .filter((m) => m.status === "ativa" && m.ancoras.length > 0)
@@ -79,7 +94,7 @@ export async function guardaCache(raiz, brain) {
     try {
         const caminho = caminhoDoCache(raiz);
         await mkdir(dirname(caminho), { recursive: true });
-        await writeFile(caminho, `${JSON.stringify(cache)}\n`, "utf8");
+        await escreveAtomico(caminho, `${JSON.stringify(cache)}\n`);
     }
     catch {
         // Sem cache o hook cala, e o PULL continua funcionando. Nao vale falhar a sessao.
@@ -87,7 +102,10 @@ export async function guardaCache(raiz, brain) {
 }
 export async function leCache(raiz) {
     try {
-        return JSON.parse(await readFile(caminhoDoCache(raiz), "utf8"));
+        const cache = JSON.parse(await readFile(caminhoDoCache(raiz), "utf8"));
+        if (cache.projeto !== await identidade(raiz) || !Array.isArray(cache.memorias))
+            return null;
+        return cache;
     }
     catch {
         return null;
@@ -106,7 +124,8 @@ export async function leCache(raiz) {
  * nao viu o aviso de hoje.
  */
 async function jaAvisou(raiz, sessao, enderecos) {
-    const caminho = join(raiz, ".claude", `dd-harness-avisos-${sessao.replace(/[^\w-]/g, "")}.json`);
+    const chave = createHash("sha256").update(sessao + await identidade(raiz)).digest("hex");
+    const caminho = join(estadoDoRepo(raiz), `avisos-${chave}.json`);
     let vistos = [];
     try {
         vistos = JSON.parse(await readFile(caminho, "utf8"));
@@ -134,7 +153,7 @@ async function jaAvisou(raiz, sessao, enderecos) {
  */
 export function caminhoRelativo(raiz, arquivo) {
     const rel = relative(resolve(raiz), resolve(arquivo));
-    if (!rel || rel.startsWith(".."))
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || /^[A-Za-z]:/.test(rel))
         return null;
     return rel.split(sep).join("/");
 }

package/dist/config.d.ts

@@ -17,6 +17,10 @@ export type ConfigDoRepo = {
 export declare const CAMINHO_CONFIG = ".dd-harness.json";
 export declare const CAMINHO_MANIFESTO = "dd-harness/manifest.json";
 export declare function leConfigDoRepo(raiz: string): Promise<ConfigDoRepo>;
+/** Sobe apenas até a raiz git; não herda outro projeto acima de um worktree. */
+export declare function achaRaiz(inicio?: string): Promise<string>;
+/** Uma configuração copiada de outro checkout nunca pode direcionar operações silenciosamente. */
+export declare function raizDoMcp(): Promise<string>;
 export type ConfigDaMaquina = {
     /**
      * Onde o monorepo `dd-harness_new` esta clonado nesta maquina. O worker de embeddings

package/dist/config.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { diretorioDoUsuario } from "./estado-local.js";
 /**
  * O servico publicado e o padrao: um repositorio que so declara `tenant` e `projeto` ja
  * fala com quem existe. Para desenvolver contra a maquina local, ponha `api` explicito no
@@ -30,8 +30,37 @@ export async function leConfigDoRepo(raiz) {
         pasta: lido.pasta ?? PADRAO.pasta,
     };
 }
-const arquivoDeCredenciais = () => join(homedir(), ".dd-harness", "credentials.json");
-const arquivoDeConfigDaMaquina = () => join(homedir(), ".dd-harness", "config.json");
+/** Sobe apenas até a raiz git; não herda outro projeto acima de um worktree. */
+export async function achaRaiz(inicio = process.env.DD_HARNESS_ROOT ?? process.cwd()) {
+    let atual = resolve(inicio);
+    const { access } = await import("node:fs/promises");
+    for (;;) {
+        if (await access(join(atual, CAMINHO_CONFIG)).then(() => true, () => false))
+            return atual;
+        if (await access(join(atual, ".git")).then(() => true, () => false))
+            break;
+        const pai = dirname(atual);
+        if (pai === atual)
+            break;
+        atual = pai;
+    }
+    throw new Error(`não encontrei ${CAMINHO_CONFIG} a partir de ${resolve(inicio)}. Configure este projeto com dd-harness start.`);
+}
+/** Uma configuração copiada de outro checkout nunca pode direcionar operações silenciosamente. */
+export async function raizDoMcp() {
+    const explicita = process.env.DD_HARNESS_ROOT;
+    const atual = await achaRaiz(process.cwd()).catch(() => null);
+    if (!explicita)
+        return atual ?? process.cwd();
+    const raiz = await achaRaiz(explicita);
+    const normaliza = (p) => process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p);
+    if (atual && normaliza(atual) !== normaliza(raiz)) {
+        throw new Error("DD_HARNESS_ROOT aponta para outro checkout/projeto. Corrija a raiz na configuração MCP deste host e reinicie-o.");
+    }
+    return raiz;
+}
+const arquivoDeCredenciais = () => join(diretorioDoUsuario(), "credentials.json");
+const arquivoDeConfigDaMaquina = () => join(diretorioDoUsuario(), "config.json");
 export async function leConfigDaMaquina() {
     try {
         const cru = await readFile(arquivoDeConfigDaMaquina(), "utf8");
@@ -43,7 +72,7 @@ export async function leConfigDaMaquina() {
 }
 export async function guardaConfigDaMaquina(parcial) {
     const caminho = arquivoDeConfigDaMaquina();
-    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    await mkdir(diretorioDoUsuario(), { recursive: true });
     const atual = await leConfigDaMaquina();
     const mesclado = { ...atual, ...parcial };
     await writeFile(caminho, `${JSON.stringify(mesclado, null, 2)}\n`, "utf8");
@@ -65,7 +94,7 @@ export async function leToken(api) {
 }
 export async function guardaToken(api, token) {
     const caminho = arquivoDeCredenciais();
-    await mkdir(join(homedir(), ".dd-harness"), { recursive: true });
+    await mkdir(diretorioDoUsuario(), { recursive: true });
     let mapa = {};
     try {
         mapa = JSON.parse(await readFile(caminho, "utf8"));

package/dist/curar.js

@@ -1,5 +1,6 @@
+import { invalidaCache } from "./cinto.js";
 import { readFile } from "node:fs/promises";
-import { cabecalhos, credencial, pede, recusa } from "./api.js";
+import { jsonDaEscrita, cabecalhos, credencial, pede, recusa } from "./api.js";
 import { interpreta } from "./gravar.js";
 /**
  * A memoria inteira, no markdown que `gravar` e `editar` consomem.
@@ -73,6 +74,7 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
+    await invalidaCache(raiz);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {
@@ -89,7 +91,8 @@ export async function arquiva(raiz, endereco, opcoes) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    const lido = (await resposta.json());
+    await invalidaCache(raiz);
+    const lido = (await jsonDaEscrita(resposta));
     return lido;
 }
 /**
@@ -108,7 +111,8 @@ export async function promove(raiz, endereco, global) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaCache(raiz);
+    return (await jsonDaEscrita(resposta));
 }
 /**
  * Apaga de verdade, em cascata — ancoras, deriva medida, vinculos, tudo.
@@ -140,5 +144,6 @@ export async function apaga(raiz, endereco, confirmacao) {
     }
     if (!resposta.ok)
         await recusa(resposta);
-    return (await resposta.json());
+    await invalidaCache(raiz);
+    return (await jsonDaEscrita(resposta));
 }

package/dist/diagnostico.d.ts

@@ -0,0 +1,5 @@
+export declare function handshakeMcp(raiz: string, comando?: string, args?: string[]): Promise<{
+    versao: string;
+    ferramentas: string[];
+}>;
+export declare function diagnostico(inicio: string, testarMcp?: boolean): Promise<string[]>;

package/dist/diagnostico.js

@@ -0,0 +1,92 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+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) => {
+        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 } });
+        let buffer = "", terminou = false, versao = "desconhecida";
+        const fim = (erro, resultado) => {
+            if (terminou)
+                return;
+            terminou = true;
+            clearTimeout(timer);
+            filho.stdin.end();
+            filho.kill();
+            if (erro)
+                reject(erro);
+            else
+                resolve(resultado);
+        };
+        const timer = setTimeout(() => fim(new Error("MCP não completou initialize/tools/list em 30 segundos")), 30000);
+        filho.once("error", () => fim(new Error("Não foi possível iniciar o executável MCP")));
+        filho.once("exit", () => { if (!terminou)
+            fim(new Error("MCP encerrou antes de listar ferramentas")); });
+        filho.stdin.on("error", () => fim(new Error("MCP fechou stdin antes do handshake")));
+        filho.stderr.resume(); // Saída do subprocesso pode conter ambiente; não a ecoar.
+        const envia = (v) => filho.stdin.write(JSON.stringify(v) + "\n");
+        filho.stdout.on("data", chunk => {
+            buffer += chunk;
+            if (buffer.length > 2000000)
+                return fim(new Error("Resposta MCP excedeu o limite do diagnóstico"));
+            for (;;) {
+                const pos = buffer.indexOf("\n");
+                if (pos < 0)
+                    break;
+                const linha = buffer.slice(0, pos);
+                buffer = buffer.slice(pos + 1);
+                let msg;
+                try {
+                    msg = JSON.parse(linha);
+                }
+                catch {
+                    return fim(new Error("MCP imprimiu texto fora do protocolo em stdout"));
+                }
+                if (msg.error)
+                    return fim(new Error("MCP recusou initialize/tools/list"));
+                if (msg.id === 1) {
+                    versao = msg.result?.serverInfo?.version ?? versao;
+                    envia({ jsonrpc: "2.0", method: "notifications/initialized" });
+                    envia({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+                }
+                else if (msg.id === 2) {
+                    const ferramentas = msg.result?.tools?.map((t) => t.name);
+                    if (!Array.isArray(ferramentas))
+                        return fim(new Error("tools/list não devolveu ferramentas"));
+                    fim(undefined, { versao, ferramentas });
+                }
+            }
+        });
+        envia({ jsonrpc: "2.0", id: 1, method: "initialize", params: {
+                protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "dd-harness-diagnostico", version: "1.0.0" },
+            } });
+    });
+}
+export async function diagnostico(inicio, testarMcp = false) {
+    const raiz = await achaRaiz(inicio);
+    const c = await leConfigDoRepo(raiz);
+    const linhas = [`Raiz: ${raiz}`, `Projeto: ${c.tenant}/${c.projeto}`, `Node: ${process.version}`,
+        `Credencial: ${await leToken(c.api) ? "presente (valor omitido)" : "ausente"}`];
+    for (const [host, config, hook] of [
+        ["Claude Code", ".mcp.json", ".claude/settings.json"],
+        ["Codex", ".codex/config.toml", ".codex/hooks.json"],
+        ["Antigravity", ".agents/mcp_config.json", ".agents/hooks.json"],
+    ]) {
+        const m = await readFile(join(raiz, config), "utf8").catch(() => "");
+        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.`);
+    }
+    const politica = await buscaPolitica(raiz);
+    linhas.push(`Contexto: ${politica.estado}${politica.estado === "inalcancavel" ? " — " + politica.motivo : ""}`);
+    if (testarMcp) {
+        const m = await handshakeMcp(raiz);
+        linhas.push(`MCP ${m.versao}: initialize/tools/list concluídos; ${m.ferramentas.length} ferramentas. Isto não comprova hooks ativos.`);
+    }
+    return linhas;
+}

package/dist/edicoes.d.ts

@@ -0,0 +1,15 @@
+export type Host = "claude" | "codex" | "antigravity";
+export type Chamada = {
+    raiz: string;
+    sessao: string;
+    ferramenta: string;
+    args: Record<string, unknown>;
+};
+export type Edicao = {
+    arquivo: string;
+    antes?: string;
+    depois?: string;
+    origem?: string;
+};
+export declare function normalizaEntrada(host: Host, entrada: Record<string, unknown>): Chamada;
+export declare function edicoesDaChamada(c: Chamada): Edicao[];