@pathbit/agentdevkit 0.0.6 → 0.0.8

package/README.es.md

@@ -35,7 +35,7 @@ Después, abre el proyecto en tu agente y pide:
 La [guía de instalación](docs/guides/installation.md) incluye Windows, Node ausente,
 simulación y actualización. Instala y actualiza mediante el
 [paquete npm público][packages];
-la [release v0.0.6][release] conserva artefactos y checksums para verificarlos.
+la [release v0.0.8][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -80,7 +80,7 @@ formularios. Consulta [cómo participar](docs/maintainers/community.md).
 al agente que lea `AGENTS.md`.
 
 [clients]: .pbai4devs/COMPATIBILIDADE.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.6
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.8
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue

package/README.md

@@ -32,7 +32,7 @@ Depois, abra o projeto no seu agente e peça:
 
 Windows, instalação sem Node, simulação e atualização estão no
 [guia de instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md). A distribuição usa a
-versão publicada no [npm público][packages] e na [release v0.0.6][release],
+versão publicada no [npm público][packages] e na [release v0.0.8][release],
 sem instalação global. Instalação e atualização usam o pacote do registro;
 os arquivos da release servem para conferir os artefatos publicados.
 O idioma da CLI pode ser `pt`, `en` ou `es`.
@@ -89,7 +89,7 @@ ao seu agente para ler `AGENTS.md`.
 [help]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/troubleshooting.md
 [issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
 [packages]: https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/packages.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.6
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.8
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue

package/docs/guides/cli.md

@@ -63,6 +63,15 @@ e `unlock`. Consultar ou executar não instala silenciosamente.
 `setup` prepara as ferramentas compatíveis; outros comandos podem receber
 um nome ou grupo. Consulte [ferramentas e testes](tools-and-testing.md).
 
+Em `tools`, use `--` antes dos argumentos que pertencem à ferramenta:
+
+```console
+npx @pathbit/agentdevkit tools run agent-browser -- --json --help
+```
+
+Nesse exemplo, `--json` pertence ao agent-browser. Opções do kit ficam antes
+do separador. `--help` e `--version` do kit não exigem um projeto instalado.
+
 ## JSON e retorno
 
 As respostas incluem `ok`, `command`, `version`, `language`, `target` e

package/docs/guides/installation.md

@@ -60,6 +60,13 @@ workflows, formulários de issues ou configurações humanas em `.github`.
 Sem Git, uma proteção no `.gitignore` da raiz evita incluir os derivados
 quando o repositório for iniciado.
 
+O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
+e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
+O `.gitignore` existente e seus arquivos rastreados são preservados;
+uma exceção humana que conflite com essa proteção é informada como conflito.
+Nomes próprios de artefatos e arquivos existentes também são conferidos;
+a validação fica restrita ao projeto e aos ignores de seus ancestrais.
+
 Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
 do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
 Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
@@ -77,10 +84,18 @@ gerenciados alterados geram conflito; use `--force` somente após revisar o
 backup e o conteúdo que será substituído. Preserve os dados locais, as
 configurações próprias e os commits do projeto.
 
+Links simbólicos em caminhos usados pela instalação podem bloquear a operação.
+O kit informa o caminho e não converte nem remove o link automaticamente.
+Use a simulação para identificar esse caso antes de aplicar.
+
+Arquivos humanos não se tornam gerenciados apenas por conterem um link.
+As alterações de arquivos existentes preservam permissões, inclusive em backup
+e restauração após falha.
+
 O [fluxo de trabalho](workflow.md) orienta a próxima etapa do projeto.
 Se houver erro, consulte [solução de problemas](troubleshooting.md).
 
-[Wiki](../README.md) · [Spec v0.0.6][spec]
+[Wiki](../README.md) · [Spec v0.0.8][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.6/SPEC.md
+[spec]: ../specs/v0.0.8/SPEC.md

package/docs/guides/tools-and-testing.md

@@ -32,6 +32,8 @@ node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup
 `setup` reutiliza instalações saudáveis e verifica as compatíveis. Um nome
 ou grupo limita a seleção. `check`, `info` e `run` não trocam uma consulta
 por instalação. Downloads, caches e recibos permanecem locais e ignorados.
+O gerenciador recusa links simbólicos nos caminhos que escreve ou usa como
+estado local; a atualização não segue esses links para fora da instalação.
 
 ## Escolher a prova
 

package/docs/maintainers/packages.md

@@ -64,7 +64,7 @@ existir; a primeira publicação pode usar o secret `NPMJS_TOKEN`.
 Para publicar somente o pacote de uma tag que já tem artefato aprovado:
 
 ```console
-gh workflow run release.yml --ref master -f tag=v0.0.6 -F package_only=true
+gh workflow run release.yml --ref master -f tag=v0.0.8 -F package_only=true
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

package/docs/product/roadmap.md

@@ -17,6 +17,8 @@ status: vigente
 | Estrutura e exemplos v0.0.4 | CLI, distribuição e gerador | [Spec][layout]. |
 | Instalação pelo registro v0.0.5 | Pacote publicado | [Spec][registry]. |
 | Apresentação e licença v0.0.6 | Distribuição e atualização | [Spec][public]. |
+| Compatibilidade real v0.0.7 | Testes em clones existentes | [Spec][oss]. |
+| Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -36,3 +38,5 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [layout]: ../specs/v0.0.4/SPEC.md
 [registry]: ../specs/v0.0.5/SPEC.md
 [public]: ../specs/v0.0.6/SPEC.md
+[oss]: ../specs/v0.0.7/SPEC.md
+[robustness]: ../specs/v0.0.8/SPEC.md

package/docs/specs/README.md

@@ -11,6 +11,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.4](v0.0.4/SPEC.md): estrutura padrão e exemplos na raiz.
 - [v0.0.5](v0.0.5/SPEC.md): instalação pelo registro em todos os fluxos.
 - [v0.0.6](v0.0.6/SPEC.md): apresentação pública, licença e atualização segura.
+- [v0.0.7](v0.0.7/SPEC.md): projetos reais e proteção local de artefatos.
+- [v0.0.8](v0.0.8/SPEC.md): preservação, transações e validação aprofundada.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/v0.0.7/README.md

@@ -0,0 +1,10 @@
+---
+description: Compatibilidade do pacote com projetos open source existentes.
+---
+
+# Versão 0.0.7
+
+A [spec](SPEC.md) define testes em clones reais e a correção das exclusões
+locais de artefatos, preservando os arquivos e as decisões dos projetos.
+
+[Specs](../README.md)

package/docs/specs/v0.0.7/SPEC.md

@@ -0,0 +1,59 @@
+---
+description: Testes em projetos reais e proteção de artefatos locais.
+status: aprovado
+version: 0.0.7
+---
+
+# Compatibilidade com projetos existentes
+
+## Objetivo e autorização
+
+Atender ao pedido de testar o pacote publicado em projetos open source com
+conteúdo real, usando clones em `tmp/` ignorado. Corrigir a falta de proteção
+de artefatos revelada em projetos que não tinham as regras do AgentDevKit.
+
+O trabalho usa o [PRD](../../product/prd.md),
+o [design](../../product/design.md) e a
+[distribuição pública](../v0.0.6/SPEC.md). Não altera as aplicações clonadas.
+
+## Contrato
+
+- Clonar commits fixos de Express, Zod e Chi; preservar os projetos originais.
+- Comparar bytes, tipos, permissões, links, HEAD e alterações staged.
+- Verificar instalação, atualização, repetição, skill própria e conflitos.
+- Proteger artefatos no ignore local sem reescrever o `.gitignore` do usuário
+  nem desindexar arquivos humanos. Respeitar projetos irmãos e exceções.
+- Manter as recusas de links simbólicos. Um bloqueio seguro não comprova
+  instalação bem-sucedida; relatá-lo e verificar ausência de alterações.
+- Versionar o teste; guardar clones, logs e resultados somente em `tmp/`.
+- Publicar correções como nova versão estável; repetir a prova pública.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Matriz real registra resultado e preservação por projeto. |
+| AC-002 | Artefatos são ignorados sem alterar fontes ou projetos irmãos. |
+| AC-003 | Regressões e revisão independente aprovam a correção. |
+| AC-004 | Pacote estável publicado repete os resultados e atualiza o router. |
+
+## Verificação
+
+- **AC-001:** executar o runner contra o npm, incluindo caso staged e bloqueios;
+  registrar commits, versão e hashes. Não confundir com testes das aplicações.
+- **AC-002:** testar Git, instalação sem Git, projeto aninhado, caixa mista,
+  exceções humanas e artefatos já rastreados. Não forçar sobrescritas.
+- **AC-003:** executar testes do pacote, infraestrutura, lint e distribuição.
+  Comparar testes nativos do Express antes e depois, sem modificar suas fontes.
+- **AC-004:** conferir release, `latest`, checksum e instalação anônima; repetir
+  matriz com o pacote publicado e atualizar o router com backup e diagnóstico.
+
+Evidências dos clones ficam em `tmp/oss-compatibility/`; o relatório de revisão
+em `.agent-tests/oss-compatibility/` referencia cópias dessas provas.
+Zod e Chi não terão testes nativos sem os runtimes/gerenciadores exigidos.
+Não concluir compatibilidade universal a partir desta matriz.
+
+## Documentação afetada
+
+Atualizar instalação, testes, changelog, índices e roadmap. Documentar a
+proteção de artefatos locais e os limites de configurações preexistentes.

package/docs/specs/v0.0.8/README.md

@@ -0,0 +1,10 @@
+---
+description: Validação aprofundada e preservação de dados do AgentDevKit.
+---
+
+# Versão 0.0.8
+
+A [spec](SPEC.md) reúne correções da auditoria do instalador, sincronizador,
+gerenciador de ferramentas, CLI e regras de ignore.
+
+[Specs](../README.md)

package/docs/specs/v0.0.8/SPEC.md

@@ -0,0 +1,62 @@
+---
+description: Correções verificadas de preservação, transações e interface CLI.
+status: aprovado
+version: 0.0.8
+---
+
+# Preservação e validação aprofundada
+
+## Objetivo e autorização
+
+Atender ao pedido de revisão profunda, corrigindo falhas comprovadas e
+publicando uma nova versão estável após validação. Esta etapa continua o
+[PRD](../../product/prd.md), o [design](../../product/design.md) e os
+[testes em projetos reais](../v0.0.7/SPEC.md).
+
+## Contrato
+
+- Não apagar ou sobrescrever arquivos humanos pela aparência de seu Markdown.
+  Exigir propriedade comprovada para limpeza automática de apontamentos.
+- Recusar conflitos conhecidos antes de escrever. Em falhas posteriores,
+  restaurar as alterações próprias sem substituir edições humanas concorrentes.
+- Preservar permissões em atualização, backup e rollback, inclusive em
+  arquivos somente para leitura quando a operação for permitida pelo sistema.
+- Recusar componentes simbólicos nos caminhos locais de ferramentas, inclusive
+  após operações externas, antes de escrever ou confirmar uma instalação.
+- Preservar integralmente argumentos após `tools ... --`; ajuda e versão
+  não exigem diretório de projeto válido.
+- Conferir artefatos existentes e exceções literais além dos nomes de amostra,
+  sem ler ignores de projetos irmãos ou desindexar arquivos humanos.
+- Manter a recusa de links simbólicos incompatíveis do Zod; não converter
+  esse bloqueio documentado em uma instalação bem-sucedida.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Markdown humano é preservado; limpeza usa propriedade comprovada. |
+| AC-002 | Falhas não deixam gravações próprias parciais nem mudam permissões. |
+| AC-003 | Gerenciador não escreve fora da instalação por links simbólicos. |
+| AC-004 | CLI repassa argumentos; ajuda funciona sem projeto. |
+| AC-005 | Ignore protege artefatos sem invadir projetos irmãos. |
+| AC-006 | Regressões, pacote público e atualização do router são verificados. |
+
+## Verificação
+
+Para AC-001 a AC-005, conservar reproduções anteriores e testes de regressão
+que falham antes da correção, com assertivas de conteúdo, modo, estado e Git.
+Executar os testes relevantes em Node 24/26 e revisar os diffs de forma
+independente. Limitações de plataforma devem ficar explícitas.
+
+Para AC-006, executar pipeline completo, cenários de maturidade e matriz OSS
+do pacote gerado. Confirmar no CI Linux, macOS e Windows; publicar o mesmo TGZ,
+comparar checksum e repetir o consumo público. Atualizar o router com preview,
+backup, diagnóstico e comparação da baseline, preservando o índice existente.
+
+Testes e fixtures são versionados. Clones e provas ficam em `tmp/` e o registro
+de revisão em `.agent-tests/`. Não prometer ausência universal de bugs.
+
+## Documentação afetada
+
+Atualizar referência da CLI, instalação, ferramentas, changelog, README,
+roadmap e índices. Não criar documentos de produto nos projetos consumidores.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,8 @@
     "pack:release": "node scripts/release/assets.mjs",
     "ci:full": "node scripts/release/pipeline.mjs full",
     "ci:portable": "node scripts/release/pipeline.mjs portable",
-    "ci:smoke": "node scripts/release/pipeline.mjs smoke"
+    "ci:smoke": "node scripts/release/pipeline.mjs smoke",
+    "test:oss": "node tests/oss-compatibility.mjs"
   },
   "author": {
     "name": "PathBit",

package/src/cli.mjs

@@ -18,7 +18,10 @@ export function parseArgs(argv) {
   const options = { command: null, positionals: [], toolArgs: [], target: null, language: null, clients: undefined, yes: false, json: false, dryRun: false, force: false, check: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
-    if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
+    if (arg === '--' && options.command === 'tools') {
+      options.toolArgs.push(...argv.slice(index));
+      break;
+    } else if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
       const value = argv[++index]; if (!value || value.startsWith('-')) usage(`Missing value: ${arg}`);
       if (arg === '--target') options.target = value;
       else if (arg === '--lang') { options.language = normalizeLanguage(value); if (!options.language) usage('Use --lang pt, en or es.'); }
@@ -86,11 +89,14 @@ function print(result, options, output) {
 
 export async function main(argv = process.argv.slice(2), context = {}) {
   const output = context.stdout || process.stdout, input = context.stdin || process.stdin, errorOutput = context.stderr || process.stderr;
-  let options = { json: argv.includes('--json') }, language = normalizeLanguage(argv[argv.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
+  const separator = argv.indexOf('--'), globalArgs = separator < 0 ? argv : argv.slice(0, separator);
+  let options = { json: globalArgs.includes('--json') }, language = normalizeLanguage(globalArgs[globalArgs.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
   try {
     options = parseArgs(argv);
-    target = resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
-    const previous = ['help', 'version'].includes(options.command) ? null : loadState(target);
+    const informational = ['help', 'version'].includes(options.command);
+    target = informational ? resolve(context.cwd || process.cwd(), options.target || '.')
+      : resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
+    const previous = informational ? null : loadState(target);
     language = options.language || previous?.language || 'pt';
     clients = options.clients ?? previous?.clients ?? ['all'];
     if (options.command === 'init' && !previous && !options.yes && !options.json && !options.dryRun && input.isTTY && output.isTTY && (!options.language || options.clients === undefined)) {

package/src/install.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
@@ -77,8 +77,24 @@ function walk(root, path = '', filter = () => true) {
   return files;
 }
 
-function write(root, path, content) {
-  const target = safePath(root, path); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, content);
+function write(root, path, content, mode) {
+  const target = safePath(root, path); mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content, mode === undefined ? undefined : { mode });
+  if (mode !== undefined) chmodSync(target, mode);
+}
+
+function atomicWrite(root, path, content, mode, onPublished) {
+  const file = safePath(root, path);
+  mkdirSync(dirname(file), { recursive: true });
+  const temporary = `${file}.agentdevkit-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx', ...(mode === undefined ? {} : { mode }) });
+    if (mode !== undefined) chmodSync(temporary, mode);
+    const writtenMode = stat(temporary).mode & 0o777;
+    renameSync(temporary, file);
+    onPublished?.(writtenMode);
+    return writtenMode;
+  } finally { rmSync(temporary, { force: true }); }
 }
 
 function read(root, path) {
@@ -294,42 +310,63 @@ export function applyPlan(plan) {
   safePath(target, backup);
   for (const change of plan.changes) safePath(target, change.path);
   const before = new Map(plan.changes.map(change => [change.path, read(target, change.path)]));
+  const beforeModes = new Map(plan.changes.map(change => {
+    const info = stat(safePath(target, change.path));
+    return [change.path, info ? info.mode & 0o777 : undefined];
+  }));
   for (const change of plan.changes) if ((before.get(change.path) ? hash(before.get(change.path)) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
-  for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content);
-  const applied = [];
+  for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content, beforeModes.get(path));
+  const applied = [], removedDirectories = [];
   let untracked = false;
   try {
     if (plan.untrack?.paths.length) { applyUntrack(plan.untrack); untracked = true; }
     for (const change of plan.changes) {
       const file = safePath(target, change.path);
-      if (change.content === null) rmSync(file, { force: true });
-      else {
-        mkdirSync(dirname(file), { recursive: true });
-        const temporary = `${file}.agentdevkit-${randomUUID()}`;
-        try { writeFileSync(temporary, change.content, { flag: 'wx' }); renameSync(temporary, file); }
-        finally { rmSync(temporary, { force: true }); }
-      }
-      applied.push(change.path);
+      const content = change.content;
+      const signature = { path: change.path, hash: content === null ? null : hash(content) };
+      if (content === null) { rmSync(file, { force: true }); applied.push(signature); }
+      else atomicWrite(target, change.path, content, beforeModes.get(change.path), mode => {
+        signature.mode = mode; applied.push(signature);
+      });
     }
-    pruneRemovedDirectories(plan);
+    pruneRemovedDirectories(plan, directory => removedDirectories.push(directory));
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
     const ignored = applyLocalIgnore(changesFallback ? planLocalIgnore(target, { outputs: plan.ownedOutputs }) : plan.localIgnore);
     return { changed: Boolean(plan.changes.length || ignored.changed || untracked), backup: [...before.values()].some(Boolean) ? backup : null };
   } catch (error) {
-    const rollbackErrors = [];
-    for (const path of applied.reverse()) {
+    const rollbackErrors = [], preserved = [];
+    for (const removed of [...removedDirectories].sort((a, b) => a.path.length - b.path.length)) {
+      let directory, current;
+      try { directory = safePath(target, removed.path); current = stat(directory); }
+      catch { preserved.push(removed.path); continue; }
+      if (current) continue;
+      try { mkdirSync(directory, { mode: removed.mode }); chmodSync(directory, removed.mode); }
+      catch (failure) { rollbackErrors.push(failure); }
+    }
+    for (const appliedFile of applied.reverse()) {
+      const { path } = appliedFile;
+      let unchanged = false;
+      try {
+        const file = safePath(target, path), info = stat(file);
+        unchanged = appliedFile.hash === null ? !info : Boolean(info?.isFile()
+          && (info.mode & 0o777) === appliedFile.mode && hash(readFileSync(file)) === appliedFile.hash);
+      } catch { /* Não restaurar quando não é possível comprovar a própria gravação. */ }
+      if (!unchanged) { preserved.push(path); continue; }
       const content = before.get(path);
-      try { if (content) write(target, path, content); else rmSync(safePath(target, path), { force: true }); }
+      try { if (content) atomicWrite(target, path, content, beforeModes.get(path)); else rmSync(safePath(target, path), { force: true }); }
       catch (failure) { rollbackErrors.push(failure); }
     }
+    if (preserved.length) {
+      try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
+    }
     if (untracked) try { restoreUntrack(plan.untrack); } catch (failure) { rollbackErrors.push(failure); }
     if (rollbackErrors.length) throw Object.assign(new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error }), { code: error.code || 'E_OPERATION' });
     throw error;
   }
 }
 
-function pruneRemovedDirectories(plan) {
+function pruneRemovedDirectories(plan, onRemoved) {
   const { target } = plan;
   const legacy = '.pbai4devs/adapters/README.md';
   const removed = plan.changes.filter(change => change.action === 'remove' && (allowedManaged(change.path) || change.path === legacy));
@@ -342,8 +379,9 @@ function pruneRemovedDirectories(plan) {
     const boundary = parent.startsWith('.pbai4devs/') ? '.pbai4devs' : adapterRoots.find(root => parent.startsWith(`${root}/`));
     while (boundary && parent.startsWith(`${boundary}/`)) {
       const directory = safePath(target, parent);
-      if (!stat(directory)?.isDirectory() || readdirSync(directory).length) break;
-      try { rmdirSync(directory); }
+      const info = stat(directory);
+      if (!info?.isDirectory() || readdirSync(directory).length) break;
+      try { rmdirSync(directory); onRemoved?.({ path: parent, mode: info.mode & 0o777 }); }
       catch (error) { if (['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) break; throw error; }
       parent = portable(dirname(parent));
     }
@@ -351,8 +389,9 @@ function pruneRemovedDirectories(plan) {
   for (const root of plan.retiredRoots || []) {
     if (!adapterRoots.includes(root)) continue;
     const directory = safePath(target, root);
-    if (!stat(directory)?.isDirectory()) continue;
-    try { if (readdirSync(directory).length === 0) rmdirSync(directory); }
+    const info = stat(directory);
+    if (!info?.isDirectory()) continue;
+    try { if (readdirSync(directory).length === 0) { rmdirSync(directory); onRemoved?.({ path: root, mode: info.mode & 0o777 }); } }
     catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
   }
 }