@pathbit/agentdevkit 0.0.10 → 0.0.12

package/.pbai4devs/scripts/preparar-ferramentas/tests/native-release.test.mjs

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { gzipSync, deflateRawSync } from 'node:zlib';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync, symlinkSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nativeHash, nativeRelease, validateNativeDownload, validateNativeRelease, downloadNative, extractNative, installNative, checkNative, assertNativeVersion } from '../../lib/native-release.mjs';
+import { ToolManager, platformKey, toolEnvironment } from '../SCRIPT.mjs';
+
+const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+function fixture(t) { const dir = join(project, '.agent-tests'); mkdirSync(dir, { recursive: true }); const root = mkdtempSync(join(dir, 'native tools ')); t.after(() => rmSync(root, { recursive: true, force: true })); return root; }
+function config(bytes = Buffer.from('#!/bin/sh\necho 1.2.3\n'), version = '1.2.3') {
+  return { name: 'native-test', description: 'Native fixture.', group: 'security', source: 'https://github.com/owner/repo',
+    platforms: [platformKey()], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'],
+    download: { provider: 'github-release', repository: 'owner/repo', channel: 'reviewed', version, tag: `v${version}`,
+      assets: { [platformKey()]: { file: 'tool.bin', format: 'raw', binary: 'tool', sha256: nativeHash(bytes) } } } };
+}
+function tar(entries) {
+  const chunks = [];
+  for (const { name, bytes = Buffer.from('binary'), type = '0' } of entries) {
+    const header = Buffer.alloc(512); header.write(name, 0, 100); header.write('0000755\0', 100); header.write('0000000\0', 108); header.write('0000000\0', 116);
+    header.write(bytes.length.toString(8).padStart(11, '0') + '\0', 124); header.write('00000000000\0', 136); header.fill(32, 148, 156); header.write(type, 156); header.write('ustar\0', 257);
+    header.write([...header].reduce((a, b) => a + b, 0).toString(8).padStart(6, '0') + '\0 ', 148);
+    chunks.push(header, bytes, Buffer.alloc((512 - bytes.length % 512) % 512));
+  }
+  return gzipSync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+}
+function crc32(bytes) { let crc = 0xffffffff; for (const b of bytes) { crc ^= b; for (let i = 0; i < 8; i++) crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1)); } return (crc ^ 0xffffffff) >>> 0; }
+function zip(entries) {
+  const locals = [], centrals = []; let cursor = 0;
+  for (const { name, bytes = Buffer.from('binary'), mode = 0o100755, method = 8 } of entries) {
+    const filename = Buffer.from(name), compressed = method === 8 ? deflateRawSync(bytes) : bytes, crc = crc32(bytes);
+    const local = Buffer.alloc(30); local.writeUInt32LE(0x04034b50); local.writeUInt16LE(20, 4); local.writeUInt16LE(method, 8); local.writeUInt32LE(crc, 14); local.writeUInt32LE(compressed.length, 18); local.writeUInt32LE(bytes.length, 22); local.writeUInt16LE(filename.length, 26);
+    const central = Buffer.alloc(46); central.writeUInt32LE(0x02014b50); central.writeUInt16LE(3 << 8 | 20, 4); central.writeUInt16LE(20, 6); central.writeUInt16LE(method, 10); central.writeUInt32LE(crc, 16); central.writeUInt32LE(compressed.length, 20); central.writeUInt32LE(bytes.length, 24); central.writeUInt16LE(filename.length, 28); central.writeUInt32LE((mode << 16) >>> 0, 38); central.writeUInt32LE(cursor, 42);
+    locals.push(local, filename, compressed); centrals.push(central, filename); cursor += local.length + filename.length + compressed.length;
+  }
+  const central = Buffer.concat(centrals), end = Buffer.alloc(22); end.writeUInt32LE(0x06054b50); end.writeUInt16LE(entries.length, 8); end.writeUInt16LE(entries.length, 10); end.writeUInt32LE(central.length, 12); end.writeUInt32LE(cursor, 16);
+  return Buffer.concat([...locals, central, end]);
+}
+const asset = (bytes, format, binary = 'tool') => ({ format, binary, sha256: nativeHash(bytes) });
+
+test('native release requires reviewed pins and exact platform assets', () => {
+  const entry = config(); assert.equal(validateNativeDownload(entry.download, entry.platforms), entry.download);
+  const release = nativeRelease(entry, platformKey()); assert.equal(validateNativeRelease(entry, release, platformKey()), release);
+  for (const change of [{ channel: 'latest' }, { tag: 'master' }, { version: '1.2.3-rc.1' }, { repository: '../evil' }, { assets: {} }]) assert.throws(() => validateNativeDownload({ ...entry.download, ...change }, entry.platforms));
+  assert.throws(() => validateNativeRelease(entry, { ...release, url: 'https://evil.example/tool' }, platformKey()));
+  const invalid = config(); invalid.download.assets[platformKey()].binary = '../escape'; assert.throws(() => validateNativeDownload(invalid.download, invalid.platforms));
+  assert.throws(() => assertNativeVersion('version 1.2.30', '1.2.3')); assert.throws(() => assertNativeVersion('version 1.2.3-rc.1', '1.2.3')); assertNativeVersion('Tool v1.2.3\n', '1.2.3');
+});
+
+test('native download follows only anonymous official asset hosts with limits', async () => {
+  const seen = [];
+  const fetcher = async (url, options) => { seen.push({ url, options }); return seen.length === 1 ? new Response(null, { status: 302, headers: { location: 'https://release-assets.githubusercontent.com/file?signature=x' } }) : new Response('data'); };
+  assert.equal((await downloadNative('https://github.com/owner/repo/releases/download/v1/tool', { fetcher })).toString(), 'data');
+  assert.ok(seen.every(({ options }) => !Object.keys(options.headers).some(key => /authorization|token/i.test(key))));
+  await assert.rejects(downloadNative('http://github.com/file', { fetcher }), /Host/);
+  await assert.rejects(downloadNative('https://evil.example/file', { fetcher }), /GitHub/);
+  await assert.rejects(downloadNative('https://github.com/file', { fetcher: async () => new Response(null, { status: 302, headers: { location: 'https://evil.example/file' } }) }), /Host/);
+  await assert.rejects(downloadNative('https://github.com/file', { maxBytes: 2, fetcher: async () => new Response('four') }), /limite/);
+  await assert.rejects(downloadNative('https://github.com/file', { fetcher: async () => new Response('missing', { status: 404 }) }), /404/);
+});
+
+test('native extraction accepts exact raw/tar/zip executable and rejects traversal and links', () => {
+  const raw = Buffer.from('raw binary'); assert.deepEqual(extractNative(raw, asset(raw, 'raw')), raw);
+  for (const format of ['tar.gz', 'zip']) {
+    const pack = format === 'tar.gz' ? tar : zip;
+    const archive = pack([{ name: 'LICENSE', bytes: Buffer.from('license') }, { name: 'tool', bytes: raw }]);
+    assert.deepEqual(extractNative(archive, asset(archive, format)), raw);
+    for (const name of ['../escape', '/absolute', 'C:/drive', 'folder\\escape']) {
+      const bad = pack([{ name }, { name: 'tool' }]); assert.throws(() => extractNative(bad, asset(bad, format)), /Caminho/);
+    }
+    const duplicate = pack([{ name: 'tool' }, { name: 'TOOL' }]); assert.throws(() => extractNative(duplicate, asset(duplicate, format)), /duplicada/);
+    const link = pack([{ name: 'link', type: '2', mode: 0o120777 }, { name: 'tool' }]); assert.throws(() => extractNative(link, asset(link, format)), /Links|Link/);
+    assert.throws(() => extractNative(archive, { ...asset(archive, format), sha256: '0'.repeat(64) }), /SHA-256/);
+    assert.throws(() => extractNative(archive, asset(archive, format, 'absent')), /ausente/);
+  }
+});
+
+test('native receipts reject tampering and symbolic files without following them', async t => {
+  const root = fixture(t), bytes = Buffer.from('binary'), entry = config(bytes); const prefix = join(root, 'stage'); mkdirSync(prefix);
+  const receipt = await installNative(prefix, entry, platformKey(), { download: async () => bytes }); assert.equal(checkNative(prefix, entry, platformKey()).binarySha256, receipt.binarySha256);
+  const executable = join(prefix, receipt.executable); writeFileSync(executable, 'tampered'); assert.throws(() => checkNative(prefix, entry, platformKey()), /alterado/);
+  writeFileSync(executable, bytes); const outside = join(root, 'outside'); writeFileSync(outside, 'preserve'); rmSync(executable);
+  try { symlinkSync(outside, executable); } catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) return; throw error; }
+  assert.throws(() => checkNative(prefix, entry, platformKey()), /simbolico/); assert.equal(readFileSync(outside, 'utf8'), 'preserve');
+});
+
+test('native manager installs, reuses without network, updates reviewed pins and rolls back', { skip: process.platform === 'win32' }, async t => {
+  const root = fixture(t); let bytes = Buffer.from('#!/bin/sh\nif [ "$1" = "exit" ]; then exit 37; fi\necho 1.2.3\n'), installs = 0, fail = false;
+  let entry = config(bytes); const manager = new ToolManager({ root, catalog: { 'native-test': entry }, install: async prefix => { installs++; if (fail) throw Error('download failed'); await installNative(prefix, entry, platformKey(), { download: async () => bytes }); } });
+  const installed = await manager.install(entry.name); assert.equal(installed.version, '1.2.3'); assert.equal(manager.check(entry.name).version, '1.2.3'); assert.equal(manager.run(entry.name, ['exit']), 37);
+  manager.fetchRelease = async () => { throw Error('unexpected network'); }; assert.equal((await manager.install(entry.name)).changed, false); assert.equal(installs, 1);
+  const old = readFileSync(join(manager.local(entry.name), 'CURRENT.json'));
+  bytes = Buffer.from('#!/bin/sh\necho 2.0.0\n'); entry = config(bytes, '2.0.0'); manager.catalog[entry.name] = entry; manager.fetchRelease = async () => nativeRelease(entry, platformKey()); fail = true;
+  await assert.rejects(manager.update(entry.name), /download failed/); assert.deepEqual(readFileSync(join(manager.local(entry.name), 'CURRENT.json')), old);
+  fail = false; assert.equal((await manager.update(entry.name)).version, '2.0.0'); assert.equal(manager.check(entry.name).version, '2.0.0');
+  assert.ok(!existsSync(join(manager.local(entry.name), '.update-lock')));
+});
+
+test('native environment removes unrelated credentials while preserving host settings', () => {
+  const saved = process.env.NATIVE_TEST_TOKEN; process.env.NATIVE_TEST_TOKEN = 'secret';
+  try { assert.equal(toolEnvironment(config(), '/tmp/local').NATIVE_TEST_TOKEN, undefined); } finally { if (saved === undefined) delete process.env.NATIVE_TEST_TOKEN; else process.env.NATIVE_TEST_TOKEN = saved; }
+});

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -12,9 +12,11 @@ node --test .pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs
 
 `--check` só confere; a execução normal atualiza os recursos. `--force` salva
 conflitos em `.agent-tests/` antes de reparar os caminhos gerenciados.
-Recursos nativos humanos e seus links permanecem intactos, inclusive com
-`--force`. O retorno inclui `preserved`; esses caminhos não contam como
-derivados pendentes nem passam a pertencer ao kit.
+Recursos nativos humanos recebem um bloco curto com a referência ao hub.
+Texto, frontmatter e nomes existentes são preservados. O estado guarda só o
+hash desse bloco; edições externas continuam permitidas. Um bloco alterado
+não é sobrescrito por `--force`. Links humanos continuam opacos.
+Comandos Gemini recebem o complemento dentro do `prompt` TOML.
 
 Metadados vêm da fonte ou do YAML nativo declarado no manifesto. Regras exigem
 `trigger` válido; `glob` exige `globs`. Origens nativas precisam pertencer ao
@@ -36,9 +38,9 @@ a seleção, use `agentdevkit agents <lista>`; não edite o manifesto gerado.
 Os derivados ficam locais: catálogos, manifesto, estado e apontamentos são
 excluídos pelo Git. O bloco em `.git/info/exclude` preserva regras próprias;
 sem Git, usa um bloco na raiz que migra ao executar depois de `git init`.
-Raízes dedicadas são locais por completo; `.github` e `.vscode` excluem somente
-os arquivos gerados. Conteúdo próprio permanece no disco e não é desindexado
-sem comprovação de propriedade do kit.
+Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
+conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
+presença de um bloco gerenciado.
 Entradas novas usam os templates; hashes em `estado/derived.json` permitem
-atualizar apenas arquivos integralmente gerados, preservando alterações humanas.
+atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
 `--check` também acusa derivados ainda rastreados; não altera o índice.

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

@@ -8,6 +8,8 @@ import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
 import { nativePathBoundary } from '../lib/native-paths.mjs';
+import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
+import { mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
 import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
@@ -72,7 +74,7 @@ function link(target, source) {
 
 export { resourcePath } from '../lib/resource-path.mjs';
 
-export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, output = console.log } = {}) {
+export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, recordDerivedState = true, output = console.log } = {}) {
   requireNode();
   root = realpathSync(resolve(root));
   const absolute = value => join(root, ...value.split('/'));
@@ -95,7 +97,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const path = safe(value);
     const item = stat(path);
     if (!item) return [];
-    if (item.isFile()) return !markdownOnly || value.endsWith('.md') ? [value] : [];
+    if (item.isFile()) return !markdownOnly || /\.md$/i.test(value) ? [value] : [];
     if (!item.isDirectory()) fail(`Tipo de arquivo nao suportado: ${value}`);
     const files = [];
     function visit(folder) {
@@ -107,22 +109,27 @@ export function synchronize({ root = projectRoot, check = false, force = false,
         if (info.isDirectory()) {
           files.push(...scan(child, { markdownOnly, prune }));
         } else if (info.isFile()) {
-          if (!markdownOnly || name.endsWith('.md')) files.push(child);
+          if (!markdownOnly || /\.md$/i.test(name)) files.push(child);
         } else fail(`Tipo de arquivo nao suportado: ${child}`);
       }
     }
     visit(value);
     return files;
   }
-  const referenceFile = value => {
+  const mergedInputs = new Map();
+  const captureInput = (path, bytes) => { if (!mergedInputs.has(path)) mergedInputs.set(path, bytes); };
+  const referenceFile = (value, supplied) => {
     const info = stat(safe(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 bytes = supplied ?? readFileSync(absolute(value)), text = normalize(bytes.toString('utf8'));
+    captureInput(value, bytes);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    const recordedHash = priorFiles[value];
+    if (recordedHash && recordedHash !== digest) return false;
+    const recorded = recordedHash === digest;
+    return isReference(text) && recorded;
   };
-  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 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)$/i.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();
@@ -132,21 +139,40 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const legacy = [];
   const config = '.pbai4devs/espelhos.conf';
   const configExists = stat(safe(config));
+  captureInput(config, configExists ? readFileSync(absolute(config)) : null);
   const stateFile = '.pbai4devs/estado/agentdevkit.json';
   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 registryBytes = stat(safe(entryRegistry)) ? readFileSync(absolute(entryRegistry)) : null;
+  captureInput(entryRegistry, registryBytes);
+  const previousEntries = registryBytes ? JSON.parse(registryBytes.toString('utf8')) : { schemaVersion: 1, entries: {} };
+  if (previousEntries?.schemaVersion !== 1 || !previousEntries.entries || typeof previousEntries.entries !== 'object' || Array.isArray(previousEntries.entries) || Object.entries(previousEntries.entries).some(([name, hash]) => !canonicalEntrypoint(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 validResourcePath = path => {
+    if (typeof path !== 'string' || !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/.+/.test(path)) return false;
+    const [root, scope] = path.split('/');
+    return !reserved.has(root.toLowerCase()) && ![...auxiliary, 'workflows'].includes(scope.toLowerCase())
+      && !['readme.md', 'instructions.md'].includes(posix.basename(path).toLowerCase())
+      && (/\.(md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'));
+  };
+  for (const [name, values] of [['files', previousEntries.files ?? {}], ['blocks', previousEntries.blocks ?? {}]]) {
+    if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && canonicalEntrypoint(path)) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
+    for (const path of Object.keys(values)) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
+  }
+  const removedBlocks = new Set(previousEntries.removedBlocks ?? []);
+  if (!Array.isArray(previousEntries.removedBlocks ?? []) || [...removedBlocks].some(path => typeof path !== 'string' || !(validResourcePath(path) || canonicalEntrypoint(path)))) fail('Registro de blocos removidos invalido.');
+  for (const path of removedBlocks) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
+  const priorFiles = { ...installed?.files, ...previousEntries.files };
+  const priorBlocks = { ...Object.fromEntries(Object.entries(installed?.blocks ?? {}).filter(([path]) => !removedBlocks.has(path))), ...previousEntries.blocks };
+  const ownedPaths = new Set([...Object.keys(priorFiles), ...Object.keys(priorBlocks), ...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;
+    if (!nativeRoots.has(value.split('/')[0]) && !canonicalEntrypoint(value) && value !== 'README.md') return false;
     const boundary = nativePathBoundary(root, value, ownedPaths, { preserveRootAliases: true });
     return boundary ? remember(boundary.path, boundary.reason) : false;
   }
@@ -160,6 +186,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   function preserveUnknown(value) {
     if (preserveBoundary(value)) return true;
     const info = stat(safe(value));
+    if (info?.isFile() && (/\.(md|mdc)$/i.test(value) || value.startsWith('.gemini/commands/') && value.endsWith('.toml'))) return false;
     return info && !referenceFile(value) && !claimed(value) ? remember(value) : false;
   }
   function preserveNativeType(value, info, type) {
@@ -267,6 +294,13 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const backup = new Set();
   const conflicts = new Set();
   const expected = new Map();
+  const managedBlocks = {};
+  const generatedFiles = {};
+  const rememberGenerated = (target, content) => {
+    const hash = createHash('sha256').update(content).digest('hex');
+    if (installed?.files?.[target] !== hash || Object.hasOwn(previousEntries.files ?? {}, target)) generatedFiles[target] = hash;
+  };
+  const retiredBlocks = new Set();
   const changed = [];
   function planRemove(value, custom = false) {
     safe(value);
@@ -278,8 +312,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (preserveBoundary(value)) return;
     if (!stat(safe(value))) return;
     if (stat(safe(value)).isDirectory() && !scan(value).length) return;
+    if (Object.keys(priorBlocks).some(path => path === value || path.startsWith(value + '/'))) return;
     if (onlyReferences(value)) planRemove(value);
-    else if (claimed(value)) { if (force) planRemove(value, true); else conflicts.add(value); }
+    else if (claimed(value)) remember(value, 'edited-generated-file');
     else remember(value);
   }
   const registries = new Map();
@@ -287,7 +322,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   for (const [target, content] of built.outputs) {
     const info = stat(safe(target));
     if (info && !info.isFile()) fail(`Registro nao e arquivo: ${target}`);
-    if (!info || readFileSync(absolute(target), 'utf8') !== content) {
+    const current = info ? readFileSync(absolute(target)) : null;
+    captureInput(target, current);
+    if (!current || current.toString('utf8') !== content) {
       registries.set(target, content);
       if (force && info) backup.add(target);
     }
@@ -304,10 +341,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       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;
+      captureInput(manifest, current);
       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);
+      if (!unchanged) { remember(manifest, 'edited-generated-file'); continue; }
       const nextHash = createHash('sha256').update(content).digest('hex');
       if (installed?.files?.[manifest] !== nextHash) discoveryOutputs[manifest] = nextHash;
       if (!info || readFileSync(absolute(manifest), 'utf8') !== content) {
@@ -332,6 +369,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (info && !info.isFile()) fail(`.gitignore nao e arquivo: ${target}`);
     let merged;
     const current = info ? readFileSync(absolute(target), 'utf8') : '';
+    captureInput(target, info ? Buffer.from(current) : null);
     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');
@@ -355,7 +393,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       ancestor = posix.dirname(ancestor);
     }
     const info = stat(safe(target));
-    if (info && (!info.isFile() || !referenceFile(target))) {
+    const targetBytes = info?.isFile() ? readFileSync(absolute(target)) : null;
+    captureInput(target, targetBytes);
+    const reference = targetBytes && referenceFile(target, targetBytes);
+    const mixed = info?.isFile() && /\.(md|mdc|toml)$/i.test(target) && (priorBlocks[target] || !reference);
+    if (info && !mixed && (!info.isFile() || !reference)) {
       scan(target);
       if (force) planRemove(target, true); else conflicts.add(target);
     }
@@ -364,7 +406,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       if (/[{}]/.test(source)) fail(`Caminho incompativel com inclusao Gemini: ${source}`);
       const command = built.catalog.commands.find(entry => entry.path === source);
       if (!command) fail(`Comando Gemini exige COMMAND.md: ${source}`);
-      const content = `${tomlMarker}\ndescription = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(`@{${source}}\n\n{{args}}`)}\n`;
+      const current = mixed ? targetBytes : null;
+      const merged = mixed ? mergeTomlContent(current, `@{${source}}`, { expectedHash: priorBlocks[target] }) : null;
+      const content = merged ? merged.text : `${tomlMarker}\ndescription = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(`@{${source}}\n\n{{args}}`)}\n`;
+      if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
+      else rememberGenerated(target, content);
       expected.set(target, content);
       if (!info?.isFile() || readFileSync(absolute(target), 'utf8') !== content) changed.push(target);
       continue;
@@ -380,7 +426,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (!title) fail(`Titulo ausente: ${source}`);
     const ruleInclusion = /^\.(?:agents|agent)\/rules\//.test(target);
     const inclusion = ruleInclusion ? `@[origem](${link(target, source)})` : `Leia e siga [origem](${link(target, source)}).`;
-    const content = `${frontmatter}\n${title}\n\n${marker}\n${inclusion}\n`;
+    const current = mixed ? targetBytes : null;
+    const merged = mixed ? mergeManagedContent(current, inclusion, { expectedHash: priorBlocks[target] }) : null;
+    const content = merged ? merged.text : `${frontmatter}\n${title}\n\n${marker}\n${inclusion}\n`;
+    if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
+    else rememberGenerated(target, content);
     expected.set(target, content);
     if (!info?.isFile() || readFileSync(absolute(target), 'utf8') !== content) changed.push(target);
   }
@@ -394,8 +444,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       const files = scan(scope);
       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 (priorBlocks[file]) continue;
         if (referenceFile(file)) planRemove(file);
-        else if (claimed(file)) { if (force) planRemove(file, true); else conflicts.add(file); }
+        else if (claimed(file)) remember(file, 'edited-generated-file');
         else remember(file);
       }
       function directories(value) {
@@ -410,40 +461,77 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       directories(scope);
     }
     for (const file of scan(agent, { markdownOnly: true, prune: true })) {
-      if (protectedPath(file) || expected.has(file) || !read(absolute(file)).includes(marker)) continue;
+      if (protectedPath(file) || expected.has(file) || priorBlocks[file] || !read(absolute(file)).includes(marker)) continue;
       if (referenceFile(file)) planRemove(file);
-      else if (force) planRemove(file, true);
-      else conflicts.add(file);
+      else remember(file, 'edited-generated-file');
     }
   }
   for (const { target } of missing) cleanScope(target);
   const rootEntries = new Map();
+  const nextEntries = generateEntrypoints ? {} : { ...previousEntries.entries };
   if (generateEntrypoints) {
     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}`;
+    for (const canonical of resolveAdapters(installed?.clients).entrypoints) {
+      const name = resolveEntrypoint(root, canonical);
+      const template = `.pbai4devs/templates/entrypoints/${canonical}`;
       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;
+      captureInput(name, current);
       const previousHash = previous.entries[name] ?? installed?.files?.[name];
-      if (info && (!current || createHash('sha256').update(current).digest('hex') !== previousHash)) { remember(name); continue; }
+      const previousBlockHash = priorBlocks[name] ?? Object.entries(priorBlocks).find(([path]) => canonicalEntrypoint(path) === canonical)?.[1];
+      if (current && (previousBlockHash || createHash('sha256').update(current).digest('hex') !== previousHash)) {
+        const merged = mergeManagedContent(current, entrypointReference(root, canonical), { expectedHash: previousBlockHash });
+        captureInput(name, current);
+        managedBlocks[name] = merged.sha256;
+        rootEntries.set(name, merged.text);
+        remember(name, 'existing-file-extended');
+        continue;
+      }
       if (current && createHash('sha256').update(current).digest('hex') === installed?.files?.[name]) {
-        rootEntries.set(name, current.toString('utf8'));
+        const content = renderEntrypointImports(root, current.toString('utf8'));
+        rootEntries.set(name, content);
+        const nextHash = createHash('sha256').update(content).digest('hex');
+        if (nextHash !== installed.files[name]) nextEntries[name] = nextHash;
         continue;
       }
-      const content = readFileSync(absolute(template), 'utf8');
+      const content = renderEntrypointImports(root, readFileSync(absolute(template), 'utf8'));
       const nextHash = createHash('sha256').update(content).digest('hex');
-      next.entries[name] = nextHash;
+      nextEntries[name] = nextHash;
       rootEntries.set(name, content);
     }
-    const content = JSON.stringify(next, null, 2) + '\n';
-    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] : []),
+  for (const [target, digest] of Object.entries(priorBlocks)) {
+    if (!(validResourcePath(target) || canonicalEntrypoint(target))) continue;
+    if (managedBlocks[target]) continue;
+    if (canonicalEntrypoint(target) && Object.keys(managedBlocks).some(path => canonicalEntrypoint(path) === canonicalEntrypoint(target))) { removedBlocks.add(target); continue; }
+    if (!generateEntrypoints && canonicalEntrypoint(target)) { managedBlocks[target] = digest; continue; }
+    if (generatedFiles[target] || nextEntries[target]) { removedBlocks.add(target); continue; }
+    if (expected.has(target) || rootEntries.has(target) || preserveBoundary(target)) continue;
+    const info = stat(safe(target));
+    if (!info) continue;
+    if (!info.isFile()) fail(`Tipo alterado em caminho gerenciado: ${target}`);
+    const current = readFileSync(absolute(target));
+    const content = target.endsWith('.toml') ? stripTomlContent(current, digest) : stripManagedContent(current, digest);
+    captureInput(target, current);
+    expected.set(target, content);
+    if (readFileSync(absolute(target), 'utf8') !== content) changed.push(target);
+    retiredBlocks.add(target);
+    removedBlocks.add(target);
+    remember(target, 'existing-file-extended');
+  }
+  const next = { schemaVersion: 1, entries: nextEntries };
+  if (Object.keys(discoveryOutputs).length) next.outputs = discoveryOutputs;
+  if (Object.keys(generatedFiles).length) next.files = generatedFiles;
+  const derivedBlocks = Object.fromEntries(Object.entries(managedBlocks).filter(([path, hash]) => installed?.blocks?.[path] !== hash || Object.hasOwn(previousEntries.blocks ?? {}, path)));
+  if (Object.keys(derivedBlocks).length) next.blocks = derivedBlocks;
+  for (const path of Object.keys(managedBlocks)) removedBlocks.delete(path);
+  if (removedBlocks.size) next.removedBlocks = sorted(removedBlocks);
+  const registryContent = JSON.stringify(next, null, 2) + '\n';
+  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
+  const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(recordDerivedState && (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;
@@ -452,7 +540,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       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}/`)));
+  ]).filter(path => !managedBlocks[path] && !retiredBlocks.has(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);
@@ -473,6 +561,13 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   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)]));
+  for (const [path, bytes] of mergedInputs) {
+    const boundary = transactionRoots.find(root => path === root || path.startsWith(root + '/'));
+    if (!boundary) continue;
+    let snapshot = originals.get(boundary);
+    for (const segment of path.slice(boundary.length).split('/').filter(Boolean)) snapshot = snapshot?.children?.[segment];
+    if (bytes === null ? snapshot != null : !snapshot?.data?.equals(bytes)) fail(`Arquivo mudou apos planejar: ${path}`);
+  }
   const currentHashes = new Map([...originals].map(([value, content]) => [value, fingerprint(content)]));
   const originalDirectories = new Set();
   for (const value of transactionRoots) {
@@ -486,7 +581,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   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.`);
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
-  if (check) return { ...summary, ownedOutputs, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
+  if (check) return { ...summary, ownedOutputs, managedBlocks, 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);
@@ -592,7 +687,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     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 } : {}) };
+  return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
 }
 
 export function main(args = process.argv.slice(2)) {

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

@@ -39,7 +39,7 @@ function snapshot(root) {
   visit(); return result;
 }
 
-test('coexiste com aliases nativos, configuração e colisão humana sem alterar os destinos', t => {
+test('coexiste com aliases nativos e complementa colisões sem perder conteúdo humano', t => {
   const root = fixture(t);
   put(root, '.claude/skills/existing/SKILL.md', '# Human skill\n');
   put(root, '.claude/agents/revisor.md', '# Human reviewer\n');
@@ -48,7 +48,12 @@ test('coexiste com aliases nativos, configuração e colisão humana sem alterar
   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, before] of Object.entries(original)) {
+    if (['AGENTS.md', '.claude/agents/revisor.md'].includes(path)) {
+      assert.ok(fs.readFileSync(join(root, path), 'utf8').startsWith(path === 'AGENTS.md' ? '# Human instructions\n' : '# Human reviewer\n'));
+      assert.match(fs.readFileSync(join(root, path), 'utf8'), /<!-- BEGIN AGENTDEVKIT -->/);
+    } else 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'));
@@ -98,25 +103,24 @@ test('link em caminho registrado continua sendo erro antes de qualquer escrita',
   }
 });
 
-test('manifesto standalone tem propriedade explícita e alterações humanas exigem reparo autorizado', t => {
+test('manifesto standalone editado pelo usuário passa a ser preservado', 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');
+  assert.equal(fs.readFileSync(join(root, path), 'utf8'), '{"entries":[{"path":".agents/skills/custom"}]}\n');
+  assert.ok(result.preserved.some(item => item.path === path));
+  assert.ok(!result.ownedOutputs.includes(path));
+  assert.equal(run(root, { check: true }).exitCode, 0);
 });
 
-test('manifesto nativo omite colisões preservadas e inclui somente apontamentos ativos', t => {
+test('manifesto nativo inclui recursos humanos complementados com apontamento', 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.deepEqual(JSON.parse(fs.readFileSync(join(root, '.agents/skills.json'))).entries, [{ path: '.agents/skills/demo' }]);
   assert.ok(result.preserved.some(item => item.path === collision));
   assert.ok(!result.ownedOutputs.includes(collision));
   assert.equal(run(root, { check: true }).exitCode, 0);
@@ -166,7 +170,12 @@ test('variantes humanas de entradas da raiz são preservadas sem criar duplicata
   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 [path, content] of Object.entries(before)) {
+    if (['agents.md', 'claude.md', 'gemini.md'].includes(path)) {
+      assert.ok(fs.readFileSync(join(root, path), 'utf8').startsWith(`# Human ${path}\n`));
+      assert.match(fs.readFileSync(join(root, path), 'utf8'), /<!-- BEGIN AGENTDEVKIT -->/);
+    } else 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));
@@ -178,13 +187,14 @@ test('variantes humanas de entradas da raiz são preservadas sem criar duplicata
   assert.deepEqual(snapshot(root), stable);
 });
 
-test('variante de caixa de entrada registrada não esconde drift de propriedade', t => {
+test('variante única de entrada registrada conserva conteúdo como arquivo misto', 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);
+    run(root, { force: true });
+    assert.ok(fs.readFileSync(join(root, 'agents.md'), 'utf8').startsWith('# Renamed human entry\n'));
+    assert.ok(!fs.readdirSync(root).includes('AGENTS.md'));
+    assert.equal(run(root, { check: true }).exitCode, 0);
   }
 });

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

@@ -47,8 +47,13 @@ test('texto humano com formato de referência nunca comprova propriedade', t =>
     const result = run(root);
     assert.ok(result.preserved.some(item => item.path === path));
     assert.ok(!result.ownedOutputs.includes(path));
-    assert.equal(fs.readFileSync(join(root, path), 'utf8'), human);
-    assert.equal(snapshot(root)[path], before[path]);
+    if (path === generated) {
+      assert.ok(fs.readFileSync(join(root, path), 'utf8').startsWith(human));
+      assert.match(fs.readFileSync(join(root, path), 'utf8'), /<!-- BEGIN AGENTDEVKIT -->/);
+    } else {
+      assert.equal(fs.readFileSync(join(root, path), 'utf8'), human);
+      assert.equal(snapshot(root)[path], before[path]);
+    }
     assert.equal(run(root, { check: true }).exitCode, 0);
     const stable = snapshot(root);
     run(root, { force: true });