@pathbit/agentdevkit 0.0.7 → 0.0.9

package/.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 // Planeja em memória; somente os caminhos gerenciados pelo manifesto são alterados.
-import { cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix, resolve } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { requireNode, projectRoot, isMain } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
-import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { nativePathBoundary } from '../lib/native-paths.mjs';
+import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
 const tomlMarker = '# gerado: sincronizar-agentes';
@@ -90,6 +91,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     return current;
   }
   function scan(value, { markdownOnly = false, prune = false } = {}) {
+    if (preserveBoundary(value)) return [];
     const path = safe(value);
     const item = stat(path);
     if (!item) return [];
@@ -99,6 +101,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     function visit(folder) {
       for (const name of readdirSync(safe(folder)).sort(compare)) {
         const child = `${folder}/${name}`;
+        if (preserveBoundary(child)) continue;
         const info = stat(safe(child));
         if (prune && isGeneratedOutput(child, info.isDirectory())) continue;
         if (info.isDirectory()) {
@@ -113,9 +116,13 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   const referenceFile = value => {
     const info = stat(safe(value));
-    return Boolean(info?.isFile() && info.size <= 1024 * 1024 && isReference(read(absolute(value))));
+    if (!info?.isFile() || info.size > 1024 * 1024) return false;
+    const bytes = readFileSync(absolute(value)), text = normalize(bytes.toString('utf8'));
+    const recorded = installed?.files?.[value] === createHash('sha256').update(bytes).digest('hex');
+    const marked = text.split('\n').includes(marker) || text.startsWith(tomlMarker + '\n');
+    return isReference(text) && (marked || recorded);
   };
-  const onlyReferences = value => scan(value).every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file));
+  const onlyReferences = value => { const files = scan(value); return files.length > 0 && ![...preserved.keys()].some(path => path === value || path.startsWith(`${value}/`)) && files.every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file)); };
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
@@ -129,10 +136,41 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const installed = stat(safe(stateFile)) ? JSON.parse(read(safe(stateFile))) : null;
   const configText = configExists ? read(safe(config)) : adapterManifest(root, { clients: installed?.clients });
   const rows = configText.split('\n');
+  const entryRegistry = '.pbai4devs/estado/derived.json';
+  const previousEntries = stat(safe(entryRegistry)) ? JSON.parse(read(safe(entryRegistry))) : { schemaVersion: 1, entries: {} };
+  if (previousEntries?.schemaVersion !== 1 || !previousEntries.entries || typeof previousEntries.entries !== 'object' || Array.isArray(previousEntries.entries) || Object.entries(previousEntries.entries).some(([name, hash]) => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
+  const previousOutputs = previousEntries.outputs ?? {};
+  if (!previousOutputs || typeof previousOutputs !== 'object' || Array.isArray(previousOutputs) || Object.entries(previousOutputs).some(([path, hash]) => !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/(skills|rules|agents)\.json$/.test(path) || reserved.has(path.split('/')[0].toLowerCase()) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de saidas derivadas invalido.');
+  const ownedPaths = new Set([...Object.keys(installed?.files || {}), ...Object.keys(installed?.blocks || {}), ...Object.keys(previousEntries.entries), ...Object.keys(previousOutputs)]);
+  const nativeRoots = new Set(rows.map(row => row.split('|')).filter(([type]) => ['agente', 'gitignore'].includes(type)).map(([, target]) => target));
+  const preserved = new Map();
+  const remember = (path, reason = 'user-owned') => { preserved.set(path, { path, reason }); return true; };
+  function preserveBoundary(value) {
+    if (!nativeRoots.has(value.split('/')[0]) && !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'README.md'].includes(value)) return false;
+    const boundary = nativePathBoundary(root, value, ownedPaths, { preserveRootAliases: true });
+    return boundary ? remember(boundary.path, boundary.reason) : false;
+  }
+  function claimed(value) {
+    if (ownedPaths.has(value)) return true;
+    const info = stat(safe(value));
+    if (!info?.isFile() || info.size > 1024 * 1024) return false;
+    const text = read(safe(value));
+    return text.split('\n').includes(marker) || text.startsWith(tomlMarker + '\n');
+  }
+  function preserveUnknown(value) {
+    if (preserveBoundary(value)) return true;
+    const info = stat(safe(value));
+    return info && !referenceFile(value) && !claimed(value) ? remember(value) : false;
+  }
+  function preserveNativeType(value, info, type) {
+    if (!info || info[type]()) return false;
+    if ([...ownedPaths].some(path => path === value || path.startsWith(`${value}/`))) fail(`Tipo alterado em caminho gerenciado: ${value}`);
+    return remember(value, info.isDirectory() ? 'existing-directory' : info.isFile() ? 'existing-file' : 'existing-other');
+  }
   function ignoreRoot(target) {
     if (!/^\.[^/]+$/.test(target) || reserved.has(target.toLowerCase())) fail(`Pasta de agente invalida: ${target}`);
-    const info = stat(absolute(target));
-    if (info && !info.isDirectory()) fail(`Pasta de agente nao e diretorio: ${target}`);
+    const info = preserveBoundary(target) ? null : stat(safe(target));
+    preserveNativeType(target, info, 'isDirectory');
     for (const known of ignoreRoots) if (known !== target && known.toLowerCase() === target.toLowerCase()) fail('Raizes de agentes diferem somente por maiusculas/minusculas.');
     ignoreRoots.add(target);
   }
@@ -141,7 +179,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const fields = row.split('|');
     if (fields.length < 2 || fields.length > 4) fail('Campos invalidos no manifesto.');
     const [type, target, source = '', metadata = ''] = fields;
-    safe(target);
+    if (!preserveBoundary(target)) safe(target);
     if (type === 'agente') {
       if (fields.length > 3) fail(`Pasta de agente invalida: ${target}`);
       ignoreRoot(target);
@@ -187,6 +225,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const entries = new Map();
   const folded = new Map();
   function add(target, source, metadata = '') {
+    if (preserveUnknown(target)) return;
     safe(target);
     const alias = folded.get(target.toLowerCase());
     if (alias && alias !== target) fail(`Destinos diferem somente por maiusculas/minusculas: ${target}`);
@@ -236,13 +275,15 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (custom) backup.add(value);
   }
   function cleanScope(value) {
+    if (preserveBoundary(value)) return;
     if (!stat(safe(value))) return;
-    if (force && value.split('/')[1] === 'external-skills') planRemove(value, true);
-    else if (onlyReferences(value)) planRemove(value);
-    else if (force) planRemove(value, true);
-    else conflicts.add(value);
+    if (stat(safe(value)).isDirectory() && !scan(value).length) return;
+    if (onlyReferences(value)) planRemove(value);
+    else if (claimed(value)) { if (force) planRemove(value, true); else conflicts.add(value); }
+    else remember(value);
   }
   const registries = new Map();
+  const discoveryOutputs = {};
   for (const [target, content] of built.outputs) {
     const info = stat(safe(target));
     if (info && !info.isFile()) fail(`Registro nao e arquivo: ${target}`);
@@ -254,22 +295,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   for (const agent of discoveries) {
     for (const kind of ['skills', 'rules', 'agents']) {
       const manifest = `${agent}/${kind}.json`;
+      if (preserveBoundary(manifest)) continue;
       const paths = [...entries].filter(([target, value]) => target.startsWith(`${agent}/`) && sources.get(value.source) === kind)
         .map(([target]) => kind === 'skills' ? posix.dirname(target) : target).sort(compare);
       const content = JSON.stringify({ entries: paths.map(path => ({ path })) }, null, 2) + '\n';
       const info = stat(safe(manifest));
+      if (preserveNativeType(manifest, info, 'isFile')) continue;
       if (info && !info.isFile()) fail(`Registro nao e arquivo: ${manifest}`);
+      if (info && !ownedPaths.has(manifest)) { remember(manifest); continue; }
+      const current = info ? readFileSync(absolute(manifest)) : null;
+      const priorHashes = [previousOutputs[manifest], installed?.files?.[manifest]];
+      const unchanged = current === null || priorHashes.includes(createHash('sha256').update(current).digest('hex'));
+      if (!unchanged && !force) conflicts.add(manifest);
+      if (!unchanged && force) backup.add(manifest);
+      const nextHash = createHash('sha256').update(content).digest('hex');
+      if (installed?.files?.[manifest] !== nextHash) discoveryOutputs[manifest] = nextHash;
       if (!info || readFileSync(absolute(manifest), 'utf8') !== content) {
-        let managedManifest = false;
-        if (info) {
-          try {
-            const previous = JSON.parse(read(absolute(manifest)));
-            managedManifest = Object.keys(previous).length === 1 && Array.isArray(previous.entries) && previous.entries.every(entry =>
-              entry && Object.keys(entry).length === 1 && typeof entry.path === 'string' && entry.path.startsWith(`${agent}/${kind}/`) && !entry.path.split('/').some(part => !part || part === '..' || part === '.')
-            );
-          } catch { /* Um manifesto customizado ou corrompido requer --force e backup. */ }
-        }
-        if (info && !managedManifest && !force) conflicts.add(manifest);
         if (info && force) backup.add(manifest);
         registries.set(manifest, content);
       }
@@ -284,11 +325,14 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     ...sorted(ignoreRoots).map(folder => [`${folder}/.gitignore`, '.pbai4devs/templates/gitignore/agents.ignore']),
   ]);
   for (const [target, template] of ignoreTemplates) {
+    if (preserveBoundary(target)) continue;
     if (!stat(safe(template))?.isFile()) fail(`Template .gitignore ausente ou invalido: ${template}`);
     const info = stat(safe(target));
+    if (target !== '.pbai4devs/.gitignore' && preserveNativeType(target, info, 'isFile')) continue;
     if (info && !info.isFile()) fail(`.gitignore nao e arquivo: ${target}`);
     let merged;
     const current = info ? readFileSync(absolute(target), 'utf8') : '';
+    if (target !== '.pbai4devs/.gitignore' && info && !ownedPaths.has(target) && !current.split(/\r?\n/).some(line => [ignoreBegin, ignoreEnd].includes(line))) { remember(target); continue; }
     try {
       let patterns = readFileSync(absolute(template), 'utf8');
       if (target !== '.pbai4devs/.gitignore') patterns = renderClientIgnore(patterns, ignoreClients[posix.dirname(target)]);
@@ -344,18 +388,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     for (const kind of [...auxiliary, 'README.md', 'INSTRUCTIONS.md']) cleanScope(`${agent}/${kind}`);
     for (const kind of Object.keys(principals)) {
       const scope = `${agent}/${kind}`;
+      if (preserveBoundary(scope)) continue;
       const info = stat(safe(scope));
       if (!info) continue;
       const files = scan(scope);
-      if (!info.isDirectory()) { if (force) planRemove(scope, true); else conflicts.add(scope); continue; }
+      if (!info.isDirectory()) { if (claimed(scope)) { if (force) planRemove(scope, true); else conflicts.add(scope); } else remember(scope); continue; }
       for (const file of files) if (!expected.has(file)) {
         if (referenceFile(file)) planRemove(file);
-        else if (force) planRemove(file, true);
-        else conflicts.add(file);
+        else if (claimed(file)) { if (force) planRemove(file, true); else conflicts.add(file); }
+        else remember(file);
       }
       function directories(value) {
         for (const name of readdirSync(safe(value))) {
           const child = `${value}/${name}`;
+          if (preserveBoundary(child)) continue;
           if (!stat(safe(child))?.isDirectory()) continue;
           if (![...expected.keys()].some(target => target.startsWith(child + '/'))) cleanScope(child);
           directories(child);
@@ -372,18 +418,19 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   for (const { target } of missing) cleanScope(target);
   const rootEntries = new Map();
-  const entryRegistry = '.pbai4devs/estado/derived.json';
   if (generateEntrypoints) {
-    const previous = stat(safe(entryRegistry)) ? JSON.parse(read(safe(entryRegistry))) : { schemaVersion: 1, entries: {} };
-    if (previous?.schemaVersion !== 1 || !previous.entries || typeof previous.entries !== 'object' || Array.isArray(previous.entries) || Object.entries(previous.entries).some(([name, hash]) => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
+    const previous = previousEntries;
     const next = { schemaVersion: 1, entries: {} };
+    if (Object.keys(discoveryOutputs).length) next.outputs = discoveryOutputs;
     for (const name of resolveAdapters(installed?.clients).entrypoints) {
       const template = `.pbai4devs/templates/entrypoints/${name}`;
       if (!stat(safe(template))?.isFile()) continue;
+      if (preserveBoundary(name)) continue;
       const info = stat(safe(name));
+      if (preserveNativeType(name, info, 'isFile')) continue;
       const current = info?.isFile() ? readFileSync(absolute(name)) : null;
       const previousHash = previous.entries[name] ?? installed?.files?.[name];
-      if (info && (!current || createHash('sha256').update(current).digest('hex') !== previousHash)) continue;
+      if (info && (!current || createHash('sha256').update(current).digest('hex') !== previousHash)) { remember(name); continue; }
       if (current && createHash('sha256').update(current).digest('hex') === installed?.files?.[name]) {
         rootEntries.set(name, current.toString('utf8'));
         continue;
@@ -394,32 +441,90 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       rootEntries.set(name, content);
     }
     const content = JSON.stringify(next, null, 2) + '\n';
-    if ((Object.keys(next.entries).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== content)) registries.set(entryRegistry, content);
+    if ((Object.keys(next.entries).length || Object.keys(discoveryOutputs).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== content)) registries.set(entryRegistry, content);
   }
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(generateEntrypoints && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
       if (target === '.pbai4devs/.gitignore') return false;
+      if (preserved.has(target) || preserveBoundary(target)) return false;
       const content = ignoreFiles.get(target) ?? readFileSync(absolute(target), 'utf8');
       const start = content.indexOf(ignoreBegin), finish = content.indexOf(ignoreEnd);
       return start >= 0 && finish > start && !(content.slice(0, start) + content.slice(finish + ignoreEnd.length)).trim();
     }),
-  ]);
+  ]).filter(path => ![...preserved.keys()].some(value => path === value || path.startsWith(`${value}/`)));
   const localPlan = localIgnores ? planLocalIgnore(root, { outputs: ownedOutputs }) : null;
   const localStatus = localPlan ? checkLocalIgnore(localPlan) : { changed: 0, missing: [], trackedOutputs: [] };
   const removals = topPaths(remove);
   const backups = topPaths(backup);
   const rootEntryChanges = [...rootEntries].filter(([name, content]) => !stat(absolute(name)) || readFileSync(absolute(name), 'utf8') !== content);
+  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
+  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
+  const configChanged = !configExists || configText !== finalConfig;
+  function capture(value) {
+    const file = safe(value), info = stat(file);
+    if (!info) return null;
+    if (info.isFile()) return { mode: info.mode & 0o777, data: readFileSync(file) };
+    if (!info.isDirectory()) fail(`Tipo de arquivo nao suportado: ${value}`);
+    return { mode: info.mode & 0o777, children: Object.fromEntries(readdirSync(file).sort(compare).map(name => [name, capture(`${value}/${name}`)])) };
+  }
+  function fingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+  }
+  const transactionRoots = topPaths([...removals, ...changed, ...registries.keys(), ...ignoreFiles.keys(), ...rootEntryChanges.map(([name]) => name), ...(configChanged ? [config] : [])]);
+  const originals = new Map(transactionRoots.map(value => [value, capture(value)]));
+  const currentHashes = new Map([...originals].map(([value, content]) => [value, fingerprint(content)]));
+  const originalDirectories = new Set();
+  for (const value of transactionRoots) {
+    let parent = posix.dirname(value);
+    while (parent !== '.') { if (stat(safe(parent))?.isDirectory()) originalDirectories.add(parent); parent = posix.dirname(parent); }
+  }
+  const touched = new Set(), createdDirectories = new Set(), restoredDirectories = new Set();
+  const prunedDirectories = new Map();
+  let restoring = false;
   const summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
-  if (check) return { ...summary, ownedOutputs, exitCode: dirty ? 1 : 0 };
+  const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
+  if (check) return { ...summary, ownedOutputs, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);
+  if (localStatus.missing.length) fail(`Regras humanas reabrem derivados locais: ${localStatus.missing.join(', ')}`);
+  if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+  function ensureDirectory(value) {
+    let parent = posix.dirname(value);
+    const missing = [];
+    while (parent !== '.' && !stat(safe(parent))) { missing.push(parent); parent = posix.dirname(parent); }
+    for (const directory of missing.reverse()) {
+      mkdirSync(safe(directory)); createdDirectories.add(directory);
+      if (restoring) restoredDirectories.add(directory);
+    }
+  }
+  function mutate(value, action, text) {
+    const boundary = transactionRoots.find(root => value === root || value.startsWith(root + '/'));
+    if (!boundary || fingerprint(capture(boundary)) !== currentHashes.get(boundary)) fail(`Arquivo mudou apos planejar: ${value}`);
+    const beforeHash = currentHashes.get(boundary);
+    touched.add(boundary);
+    let failure;
+    try { action(); } catch (error) { failure = error; }
+    let afterHash;
+    try { afterHash = fingerprint(capture(boundary)); }
+    catch (error) { currentHashes.set(boundary, 'conteudo-concorrente'); throw failure || error; }
+    const matches = text === undefined || (text === null ? !stat(safe(value)) : stat(safe(value))?.isFile() && readFileSync(absolute(value)).equals(Buffer.from(text)));
+    if (!matches && afterHash !== beforeHash) {
+      currentHashes.set(boundary, 'conteudo-concorrente');
+      if (failure) throw failure;
+      fail(`Mudanca concorrente preservada: ${value}`);
+    }
+    currentHashes.set(boundary, afterHash);
+    if (failure) throw failure;
+    if (!matches) fail(`Arquivo nao corresponde a gravacao planejada: ${value}`);
+  }
   function atomic(value, text) {
     const target = safe(value);
-    mkdirSync(dirname(target), { recursive: true });
+    const mode = stat(target)?.isFile() ? stat(target).mode & 0o777 : undefined;
+    ensureDirectory(value);
     const temporary = `${target}.sync.${randomUUID()}`;
-    try { writeFileSync(temporary, text, { flag: 'wx' }); renameSync(temporary, target); }
+    try { writeFileSync(temporary, text, { flag: 'wx' }); if (mode !== undefined) chmodSync(temporary, mode); renameSync(temporary, target); }
     finally { rmSync(temporary, { force: true }); }
   }
   let backupRoot;
@@ -433,22 +538,61 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     }
     output(`Backup local: ${posix.join('.agent-tests', backupRoot.slice(backupRoot.lastIndexOf('/') + 1).split('\\').at(-1))}`);
   }
-  for (const value of removals) rmSync(safe(value), { recursive: true, force: true });
-  for (const value of changed) atomic(value, expected.get(value));
-  for (const [value, text] of registries) atomic(value, text);
-  for (const [value, text] of ignoreFiles) atomic(value, text);
-  for (const [value, text] of rootEntryChanges) atomic(value, text);
-  if (localPlan) applyLocalIgnore(localPlan);
-  function pruneEmpty(value) {
-    if (!stat(safe(value))?.isDirectory()) return;
-    for (const name of readdirSync(absolute(value))) if (stat(safe(`${value}/${name}`))?.isDirectory()) pruneEmpty(`${value}/${name}`);
-    if (!readdirSync(absolute(value)).length) rmdirSync(absolute(value));
-  }
-  for (const agent of agents.keys()) for (const kind of [...Object.keys(principals), 'instructions', 'prompts']) pruneEmpty(`${agent}/${kind}`);
-  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
-  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
-  if (!configExists || configText !== finalConfig) atomic(config, finalConfig);
-  return { ...summary, ownedOutputs, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
+  function restore(value, content) {
+    rmSync(safe(value), { recursive: true, force: true });
+    if (!content) return;
+    ensureDirectory(value);
+    if (content.data) writeFileSync(safe(value), content.data);
+    else {
+      mkdirSync(safe(value));
+      for (const [name, child] of Object.entries(content.children)) restore(`${value}/${name}`, child);
+    }
+    chmodSync(safe(value), content.mode);
+  }
+  try {
+    if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+    for (const value of removals) mutate(value, () => rmSync(safe(value), { recursive: true, force: true }), null);
+    for (const value of changed) mutate(value, () => atomic(value, expected.get(value)), expected.get(value));
+    for (const [value, text] of registries) mutate(value, () => atomic(value, text), text);
+    for (const [value, text] of ignoreFiles) mutate(value, () => atomic(value, text), text);
+    for (const [value, text] of rootEntryChanges) mutate(value, () => atomic(value, text), text);
+    if (configChanged) mutate(config, () => atomic(config, finalConfig), finalConfig);
+    // Só os ancestrais de remoções conhecidas são candidatos à limpeza.
+    for (const value of removals) {
+      let parent = posix.dirname(value);
+      const boundary = value.split('/').slice(0, 2).join('/');
+      while (parent.startsWith(boundary + '/') || parent === boundary) {
+        const info = stat(safe(parent));
+        if (!info?.isDirectory() || readdirSync(absolute(parent)).length) break;
+        rmdirSync(safe(parent)); prunedDirectories.set(parent, info.mode & 0o777); parent = posix.dirname(parent);
+      }
+    }
+    if (localPlan) applyLocalIgnore(localPlan);
+  } catch (error) {
+    const failures = [];
+    restoring = true;
+    for (const value of [...touched].reverse()) {
+      try {
+        if (fingerprint(capture(value)) !== currentHashes.get(value)) fail(`Mudanca concorrente preservada: ${value}`);
+        restore(value, originals.get(value));
+      } catch (failure) { failures.push(failure); }
+    }
+    for (const [directory, mode] of [...prunedDirectories].sort(([left], [right]) => right.length - left.length)) {
+      try {
+        if (!stat(safe(directory))) ensureDirectory(`${directory}/.restore-probe`);
+        const info = stat(safe(directory));
+        if (!info?.isDirectory() || !restoredDirectories.has(directory) && (info.mode & 0o777) !== mode) fail(`Diretorio concorrente preservado: ${directory}`);
+        chmodSync(safe(directory), mode);
+      } catch (failure) { failures.push(failure); }
+    }
+    for (const directory of sorted(createdDirectories).sort((a, b) => b.length - a.length)) {
+      try { if (!originalDirectories.has(directory) && stat(safe(directory))?.isDirectory() && !readdirSync(absolute(directory)).length) rmdirSync(safe(directory)); }
+      catch (failure) { failures.push(failure); }
+    }
+    if (failures.length) throw new AggregateError([error, ...failures], `${error.message}; rollback incompleto: ${failures.map(failure => failure.message).join('; ')}`);
+    throw error;
+  }
+  return { ...summary, ownedOutputs, preserved: preservedPaths, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
 }
 
 export function main(args = process.argv.slice(2)) {

package/.pbai4devs/scripts/sincronizar-agentes/tests/COEXISTENCE.mjs

@@ -0,0 +1,190 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { nativePathBoundary } from '../../lib/native-paths.mjs';
+import { synchronize } from '../SCRIPT.mjs';
+
+const hash = content => createHash('sha256').update(content).digest('hex');
+const put = (root, path, text) => { fs.mkdirSync(dirname(join(root, path)), { recursive: true }); fs.writeFileSync(join(root, path), text); };
+const run = (root, options = {}) => synchronize({ root, localIgnores: false, output() {}, ...options });
+function fixture(t) {
+  const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'agentdevkit-coexist-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\nagente|.codex|plano\nagente|.agents|plano\ndescoberta|.agents|antigravity\n');
+  put(root, '.pbai4devs/skills/demo/SKILL.md', '---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n');
+  put(root, '.pbai4devs/agents/revisor/AGENT.md', '---\nname: revisor\ndescription: Revisor.\n---\n\n# Revisor\n');
+  for (const name of ['agents.ignore', 'shared.ignore', 'local.ignore', 'clients.json']) put(root, `.pbai4devs/templates/gitignore/${name}`, fs.readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore', name)));
+  for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) put(root, `.pbai4devs/templates/entrypoints/${name}`, `---\ndescription: Entry.\n---\n\n# ${name}\n\nLeia AGENTS.md.\n`);
+  return root;
+}
+function link(t, root, target, path, type = 'file') {
+  fs.mkdirSync(dirname(join(root, path)), { recursive: true });
+  try { fs.symlinkSync(target, join(root, path), type); return true; }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Sistema não permite criar este link simbólico.'); return false; } throw error; }
+}
+function snapshot(root) {
+  const result = {};
+  function visit(prefix = '') {
+    for (const name of fs.readdirSync(join(root, prefix)).sort()) {
+      const path = prefix ? `${prefix}/${name}` : name, info = fs.lstatSync(join(root, path));
+      result[path] = info.isSymbolicLink() ? ['link', fs.readlinkSync(join(root, path))] : info.isDirectory() ? ['directory', info.mode & 0o777] : ['file', info.mode & 0o777, hash(fs.readFileSync(join(root, path)))];
+      if (info.isDirectory()) visit(path);
+    }
+  }
+  visit(); return result;
+}
+
+test('coexiste com aliases nativos, configuração e colisão humana sem alterar os destinos', t => {
+  const root = fixture(t);
+  put(root, '.claude/skills/existing/SKILL.md', '# Human skill\n');
+  put(root, '.claude/agents/revisor.md', '# Human reviewer\n');
+  put(root, '.claude/.gitignore', '# Human ignore\n*.private\n');
+  put(root, 'AGENTS.md', '# Human instructions\n');
+  put(root, 'external/config.json', '{"human":true}\n');
+  if (!link(t, root, '../.claude/skills', '.codex/skills', 'dir') || !link(t, root, 'AGENTS.md', 'CLAUDE.md') || !link(t, root, '../external/config.json', '.claude/settings.local.json')) return;
+  const original = snapshot(root), result = run(root, { force: true });
+  for (const [path, before] of Object.entries(original)) assert.deepEqual(snapshot(root)[path], before, path);
+  for (const path of ['.codex/skills', 'CLAUDE.md', '.claude/agents/revisor.md', '.claude/.gitignore', '.claude/settings.local.json']) assert.ok(result.preserved.some(item => item.path === path), path);
+  assert.ok(result.ownedOutputs.includes('.agents/skills/demo/SKILL.md'));
+  assert.ok(result.ownedOutputs.every(path => !path.startsWith('.codex/skills/') && path !== '.claude/agents/revisor.md' && path !== 'CLAUDE.md'));
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true });
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('preserva raiz simbólica externa, link pendente e loop sem abri-los', t => {
+  for (const targetKind of ['external', 'dangling', 'loop']) {
+    const root = fixture(t), outside = fixture(t);
+    put(outside, 'sentinel.txt', 'outside\n');
+    const beforeOutside = snapshot(outside);
+    const target = targetKind === 'external' ? outside : targetKind === 'loop' ? '.codex' : join(outside, 'missing');
+    if (!link(t, root, target, '.codex', targetKind === 'external' && process.platform === 'win32' ? 'junction' : 'dir')) return;
+    const result = run(root, { force: true });
+    assert.equal(fs.readlinkSync(join(root, '.codex')), target);
+    assert.deepEqual(snapshot(outside), beforeOutside);
+    assert.ok(result.preserved.some(item => item.path === '.codex' && item.reason === 'symbolic-link'));
+    assert.equal(run(root, { check: true }).exitCode, 0);
+  }
+});
+
+test('ignore nativo simbólico permanece opaco na política local do Git', t => {
+  const root = fixture(t), outside = fixture(t);
+  const git = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+  assert.equal(git.status, 0, git.stderr);
+  put(outside, 'ignore', '# External human ignore\n!*.private\n');
+  if (!link(t, root, join(outside, 'ignore'), '.claude/.gitignore')) return;
+  const before = snapshot(outside);
+  const result = run(root, { localIgnores: true });
+  assert.ok(result.preserved.some(item => item.path === '.claude/.gitignore'));
+  assert.deepEqual(snapshot(outside), before);
+  assert.equal(run(root, { localIgnores: true, check: true }).exitCode, 0);
+});
+
+test('link em caminho registrado continua sendo erro antes de qualquer escrita', t => {
+  for (const source of ['files', 'blocks', 'derived', 'outputs']) {
+    const root = fixture(t), path = source === 'derived' ? 'CLAUDE.md' : source === 'outputs' ? '.agents/skills.json' : '.claude/skills/demo/SKILL.md';
+    if (!link(t, root, 'missing', path)) return;
+    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
+    else put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /Link simbolico em caminho gerenciado/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});
+
+test('manifesto standalone tem propriedade explícita e alterações humanas exigem reparo autorizado', t => {
+  const root = fixture(t); run(root);
+  const path = '.agents/skills.json', original = fs.readFileSync(join(root, path), 'utf8');
+  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/estado/derived.json')));
+  assert.equal(derived.outputs[path], hash(original));
+  put(root, path, '{"entries":[{"path":".agents/skills/custom"}]}\n');
+  const before = snapshot(root);
+  assert.throws(() => run(root), /--force/);
+  assert.deepEqual(snapshot(root), before);
+  const result = run(root, { force: true });
+  assert.equal(fs.readFileSync(join(root, path), 'utf8'), original);
+  assert.equal(fs.readFileSync(join(result.backupRoot, path), 'utf8'), '{"entries":[{"path":".agents/skills/custom"}]}\n');
+});
+
+test('manifesto nativo omite colisões preservadas e inclui somente apontamentos ativos', t => {
+  const root = fixture(t), collision = '.agents/skills/demo/SKILL.md';
+  put(root, collision, '# Human demo\n');
+  const result = run(root);
+  assert.deepEqual(JSON.parse(fs.readFileSync(join(root, '.agents/skills.json'))).entries, []);
+  assert.ok(result.preserved.some(item => item.path === collision));
+  assert.ok(!result.ownedOutputs.includes(collision));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('preserva diretórios humanos no lugar de índices, ignores e entradas, e arquivo no lugar de raiz', t => {
+  const root = fixture(t);
+  for (const path of ['.agents/skills.json', '.claude/.gitignore', 'CLAUDE.md']) put(root, `${path}/keep.txt`, 'Human data\n');
+  put(root, '.codex', 'Human native configuration\n');
+  const before = snapshot(root), result = run(root, { force: true });
+  for (const [path, value] of Object.entries(before)) assert.deepEqual(snapshot(root)[path], value, path);
+  for (const path of ['.agents/skills.json', '.claude/.gitignore', 'CLAUDE.md', '.codex']) {
+    assert.ok(result.preserved.some(item => item.path === path), path);
+    assert.ok(result.ownedOutputs.every(output => output !== path && !output.startsWith(`${path}/`)), path);
+  }
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true });
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('tipo alterado em caminho nativo registrado continua recusado antes de gravar', t => {
+  for (const [path, owned] of [
+    ['.agents/skills.json', '.agents/skills.json'],
+    ['.claude/.gitignore', '.claude/.gitignore'],
+    ['CLAUDE.md', 'CLAUDE.md'],
+    ['.codex', '.codex/skills/demo/SKILL.md'],
+  ]) {
+    const root = fixture(t);
+    if (path === '.codex') put(root, path, 'Human root\n'); else put(root, `${path}/keep.txt`, 'Human directory\n');
+    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /caminho gerenciado/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});
+
+test('classificação preservável não encobre aliases por caixa nem caminhos fora do escopo', t => {
+  const root = fixture(t);
+  put(root, '.Claude/notes.txt', 'human\n');
+  assert.throws(() => nativePathBoundary(root, '.claude/skills'), /maiusculas\/minusculas/);
+  assert.throws(() => nativePathBoundary(root, '.claude/skills', [], { preserveRootAliases: true }), /maiusculas\/minusculas/);
+  for (const path of ['../outside', '/outside', '.claude//skills', '.claude/./skills', '.claude/skills\n']) assert.throws(() => nativePathBoundary(root, path), /Caminho invalido/);
+});
+
+test('variantes humanas de entradas da raiz são preservadas sem criar duplicatas', t => {
+  const root = fixture(t);
+  for (const path of ['Readme.md', 'agents.md', 'claude.md', 'gemini.md']) put(root, path, `# Human ${path}\n`);
+  const before = snapshot(root), result = run(root, { force: true });
+  for (const [path, content] of Object.entries(before)) assert.deepEqual(snapshot(root)[path], content, path);
+  for (const [canonical, alias] of [['README.md', 'Readme.md'], ['AGENTS.md', 'agents.md'], ['CLAUDE.md', 'claude.md'], ['GEMINI.md', 'gemini.md']]) {
+    assert.deepEqual(nativePathBoundary(root, canonical, [], { preserveRootAliases: true }), { path: alias, reason: 'case-variant' });
+    if (canonical !== 'README.md') assert.ok(result.preserved.some(item => item.path === alias));
+    assert.ok(!result.ownedOutputs.includes(canonical));
+    assert.ok(!fs.readdirSync(root).includes(canonical), canonical);
+  }
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('variante de caixa de entrada registrada não esconde drift de propriedade', t => {
+  for (const owned of ['AGENTS.md', 'agents.md']) {
+    const root = fixture(t); put(root, 'agents.md', '# Renamed human entry\n');
+    assert.throws(() => nativePathBoundary(root, 'AGENTS.md', [owned], { preserveRootAliases: true }), /maiusculas\/minusculas/);
+    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /maiusculas\/minusculas/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});