@pathbit/agentdevkit 0.0.7 → 0.0.8

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -63,6 +63,7 @@ export function renderClientIgnore(template, settings = {}) {
 
 const localStat = file => { try { return lstatSync(file); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; } };
 const localRead = file => localStat(file) ? readFileSync(file, 'utf8') : null;
+const localMode = file => { const item = localStat(file); return item ? item.mode & 0o777 : null; };
 const portable = path => path.split(sep).join('/');
 
 function canonicalExisting(path) {
@@ -144,6 +145,61 @@ function artifactProbes(root, patterns) {
   return [...probes];
 }
 
+const matchesComponent = (part, pattern) => posix.matchesGlob(`x${part}`, `x${pattern.replace(/[{}()]/g, '\\$&')}`);
+
+function matchesParts(parts, pattern) {
+  const cache = new Map();
+  function match(part, glob) {
+    const key = `${part}:${glob}`; if (cache.has(key)) return cache.get(key);
+    const expected = pattern[glob];
+    const result = glob === pattern.length ? part === parts.length
+      : expected === '**' ? match(part, glob + 1) || part < parts.length && match(part + 1, glob)
+        : part < parts.length && matchesComponent(parts[part], expected) && match(part + 1, glob + 1);
+    cache.set(key, result); return result;
+  }
+  return match(0, 0);
+}
+
+function artifactPath(path, patterns, directory = false) {
+  const parts = path.split('/');
+  return patterns.some(pattern => {
+    const rule = pattern.slice(3).replace(/\/$/, '');
+    return parts.some((part, index) => (index < parts.length - 1 || directory || !pattern.endsWith('/'))
+      && (rule.includes('/') ? matchesParts(parts.slice(0, index + 1), ['**', ...rule.split('/')])
+        : matchesComponent(part, rule)));
+  });
+}
+
+function visibleArtifactProbes(root, location, patterns) {
+  const listed = gitCommand(location.top, ['--literal-pathspecs', '-c', 'core.excludesFile=', 'ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', location.prefix ? `${location.prefix}/` : '.']);
+  if (listed.error || listed.status !== 0) throw new Error(listed.error?.message || listed.stderr || 'Falha ao conferir artefatos existentes.');
+  const paths = listed.stdout.split('\0').filter(Boolean), prefix = location.prefix ? `${location.prefix}/` : '';
+  const probes = new Set(paths.filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length)).filter(path => artifactPath(path, patterns)));
+  const ignores = new Set(paths.filter(path => path.startsWith(prefix) && (path === '.gitignore' || path.endsWith('/.gitignore'))));
+  let ancestor = root;
+  while (true) {
+    ignores.add(portable(relative(location.top, join(ancestor, '.gitignore'))));
+    if (ancestor === location.top) break;
+    ancestor = dirname(ancestor);
+  }
+  for (const path of ignores) {
+    const file = join(location.top, path), item = localStat(file);
+    if (!item?.isFile() || item.isSymbolicLink()) continue;
+    // Git resolves precedence; these literals only add witnesses for named exceptions.
+    for (const line of readFileSync(checkedLocalPath(file), 'utf8').split(/\r?\n/)) {
+      if (!line.startsWith('!') || line.length === 1) continue;
+      const rule = line.slice(1).replace(/(?<!\\) +$/, ''), directory = rule.endsWith('/') || rule.endsWith('/**');
+      const literal = rule.replace(/(?:\/\*\*)+\/?$/, '').replace(/\/$/, '').replace(/^\//, '');
+      if (/(^|[^\\])[*?\[]/.test(literal)) continue;
+      const ruleBase = !rule.startsWith('/') && !literal.includes('/') && relative(dirname(file), root).split(sep)[0] !== '..' ? root : dirname(file);
+      const candidate = portable(relative(root, resolve(ruleBase, literal.replace(/\\(.)/g, '$1'))));
+      if (!candidate || candidate === '..' || candidate.startsWith('../') || !artifactPath(candidate, patterns, directory)) continue;
+      probes.add(checkedOutput(directory ? `${candidate}/.agentdevkit-artifact-probe` : candidate));
+    }
+  }
+  return [...probes];
+}
+
 function localIgnoreSource(location, source) {
   const path = resolve(location.top, source);
   if (path === location.exclude) return true;
@@ -204,9 +260,9 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const body = fixed.split(/\r?\n/).map(line => location?.prefix && line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line).join('\n');
   const target = location?.exclude ?? checkedLocalPath(join(root, '.gitignore'));
   const before = localRead(target), after = localBlock(before, first, last, body);
-  const edits = before === after ? [] : [{ path: target, before, after }];
+  const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
-  const artifactPaths = artifactProbes(root, artifacts);
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
   const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first) && !localRead(join(root, '.gitignore'))?.includes(first)) {
     const ignored = ignoreMatches(location, [...probes, ...artifactPaths]);
@@ -215,10 +271,10 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   if (location) {
     const fallback = checkedLocalPath(join(root, '.gitignore'));
     const old = localRead(fallback), next = localBlock(old, first, last, null);
-    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next });
+    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next, beforeMode: localMode(fallback) });
   }
   const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => wanted.has(path)).map(path => location.prefix ? path.slice(location.prefix.length + 1) : path) : [];
-  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
@@ -235,7 +291,8 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     return { ...item, path };
   });
   if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
-    const probes = [...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || [])];
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []),
+      ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : [])])];
     const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
     for (let index = 0; index < relativePaths.length; index++) {
       const match = matches.get(relativePaths[index]);
@@ -252,10 +309,21 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
 export function assertLocalIgnoreUnchanged(plan) {
   for (const edit of plan.edits) {
     checkedLocalPath(edit.path);
-    if (localRead(edit.path) !== edit.before) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
+    if (localRead(edit.path) !== edit.before || Object.hasOwn(edit, 'beforeMode') && localMode(edit.path) !== edit.beforeMode) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
   }
 }
 
+function atomicLocalWrite(path, content, mode, published) {
+  const temporary = `${path}.agentdevkit-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx' });
+    if (mode !== null && mode !== undefined) chmodSync(temporary, mode);
+    const writtenMode = localMode(temporary);
+    renameSync(temporary, path);
+    published?.(writtenMode);
+  } finally { rmSync(temporary, { force: true }); }
+}
+
 export function applyLocalIgnore(plan) {
   assertLocalIgnoreUnchanged(plan);
   const before = checkLocalIgnore(plan);
@@ -264,18 +332,19 @@ export function applyLocalIgnore(plan) {
   try {
     for (const edit of plan.edits) {
       mkdirSync(dirname(edit.path), { recursive: true });
-      const temporary = `${edit.path}.agentdevkit-${randomUUID()}`;
-      try { writeFileSync(temporary, edit.after, { flag: 'wx' }); renameSync(temporary, edit.path); }
-      finally { rmSync(temporary, { force: true }); }
-      written.push(edit);
+      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }));
     }
     const verified = checkLocalIgnore({ ...plan, edits: [], trackedOutputs: [] });
     if (verified.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${verified.missing.join(', ')}`);
   } catch (error) {
-    for (const edit of written.reverse()) {
-      if (localRead(edit.path) !== edit.after) continue;
-      if (edit.before === null) rmSync(edit.path, { force: true }); else writeFileSync(edit.path, edit.before);
+    const rollbackErrors = [];
+    for (const { edit, mode } of written.reverse()) {
+      try {
+        if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) continue;
+        if (edit.before === null) rmSync(edit.path, { force: true }); else atomicLocalWrite(edit.path, edit.before, edit.beforeMode);
+      } catch (failure) { rollbackErrors.push(failure); }
     }
+    if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error });
     throw error;
   }
   return { status: plan.status, changed: plan.edits.length, trackedOutputs: plan.trackedOutputs };

package/.pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs

@@ -101,6 +101,14 @@ function sourcePath(root, name) {
   return file;
 }
 
+function storagePath(root, name, kind) {
+  const file = sourcePath(root, name);
+  let item;
+  try { item = lstatSync(file); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (item && !(kind === 'directory' ? item.isDirectory() : item.isFile())) fail(`Caminho local exige ${kind}: ${name}`);
+  return file;
+}
+
 export function loadCatalog(root = projectRoot) {
   root = realpathSync(root);
   const home = sourcePath(root, '.pbai4devs/tools'); const catalog = Object.create(null);
@@ -272,15 +280,21 @@ export class ToolManager {
     return { mode: 'setup', selection: selected, platform: this.target, node: process.version, nodePath: process.execPath, npm, results: entries, summary, status: summary.failed ? 'failed' : summary.passed ? 'passed' : 'not-applicable', exitCode: summary.failed ? 1 : 0 };
   }
   local(name) { this.entry(name); return join(this.home, name, '.local'); }
+  storage(name) {
+    const local = this.local(name), tool = join(this.home, name);
+    for (const path of [this.home, tool, local, join(local, 'versions'), join(tool, 'versions'), join(this.home, '.cache'), join(this.home, '.cache/npm'), join(this.home, 'npm-cache')]) storagePath(this.root, path, 'directory');
+    for (const path of [join(local, 'CURRENT.json'), join(tool, 'CURRENT.json')]) storagePath(this.root, path, 'file');
+    return { local, tool };
+  }
   current(name) {
-    this.entry(name);
-    const local = this.local(name); const legacy = join(this.home, name);
+    const { local, tool: legacy } = this.storage(name);
     const base = existsSync(join(local, 'CURRENT.json')) ? local : legacy;
     const file = join(base, 'CURRENT.json');
     if (!existsSync(file)) fail(`Ferramenta ausente: ${name}; execute install ${name}.`);
     const info = json(file);
     if (info.name !== name || info.platform !== this.target || !versionPattern.test(info.version || '')) fail(`Instalacao incompativel: ${name}`);
-    return { ...info, layout: base === local ? 'local' : 'legacy', prefix: join(base, 'versions', `${info.version}-${this.target}`) };
+    const prefix = storagePath(this.root, join(base, 'versions', `${info.version}-${this.target}`), 'directory');
+    return { ...info, layout: base === local ? 'local' : 'legacy', prefix };
   }
   check(name) {
     const entry = this.entry(name); const runtime = this.runtime(name); const info = this.current(name);
@@ -306,7 +320,7 @@ export class ToolManager {
     for (const legacy of [name, `${name}.cmd`, `${name}.ps1`, `${name}.sh`]) rmSync(join(bin, legacy), { force: true });
   }
   migrate(name) {
-    const local = this.local(name); const tool = join(this.home, name);
+    const { local, tool } = this.storage(name);
     const legacyState = join(tool, 'CURRENT.json'); const legacyVersions = join(tool, 'versions');
     if (existsSync(legacyState)) {
       if (existsSync(join(local, 'CURRENT.json')) || (existsSync(join(local, 'versions')) && readdirSync(join(local, 'versions')).length)) fail(`Layouts local e antigo coexistem: ${name}; revise antes de migrar.`);
@@ -318,15 +332,15 @@ export class ToolManager {
     }
     const oldCache = join(this.home, 'npm-cache');
     if (existsSync(oldCache)) {
-      const cache = join(this.home, '.cache'); mkdirSync(cache, { recursive: true });
-      try { renameSync(oldCache, join(cache, existsSync(join(cache, 'npm')) ? `npm-legacy-${process.pid}-${Date.now()}` : 'npm')); }
+      const cache = storagePath(this.root, join(this.home, '.cache'), 'directory'); mkdirSync(cache, { recursive: true });
+      const destination = storagePath(this.root, join(cache, existsSync(join(cache, 'npm')) ? `npm-legacy-${randomUUID()}` : 'npm'), 'directory');
+      try { renameSync(oldCache, destination); }
       catch (error) { if (error.code !== 'ENOENT' || existsSync(oldCache)) throw error; }
     }
   }
   async withLock(name, action) {
-    const local = this.local(name);
-    for (const directory of [this.home, join(this.home, name), local]) if (existsSync(directory) && lstatSync(directory).isSymbolicLink()) fail(`Diretorio local nao pode ser um link: ${directory}`);
-    mkdirSync(local, { recursive: true }); const lock = join(local, '.update-lock');
+    const { local } = this.storage(name);
+    mkdirSync(local, { recursive: true }); const lock = storagePath(this.root, join(local, '.update-lock'), 'directory');
     try { mkdirSync(lock); } catch (error) {
       if (error.code === 'EEXIST') {
         const status = this.lockStatus(name);
@@ -334,8 +348,8 @@ export class ToolManager {
       }
       throw error;
     }
-    try { writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString() })); return await action(); }
-    finally { rmSync(lock, { recursive: true, force: true }); }
+    try { writeFileSync(storagePath(this.root, join(lock, 'owner.json'), 'file'), JSON.stringify({ pid: process.pid, hostname: hostname(), startedAt: new Date().toISOString() }), { flag: 'wx' }); return await action(); }
+    finally { rmSync(storagePath(this.root, lock, 'directory'), { recursive: true, force: true }); }
   }
   lockStatus(name) {
     const lock = sourcePath(this.root, join(this.local(name), '.update-lock'));
@@ -380,29 +394,36 @@ export class ToolManager {
     return this.updateLocked(name);
   }); }
   async update(name) { this.preflight([name]); return this.withLock(name, async () => { this.migrate(name); return this.updateLocked(name); }); }
-  commitState(name, temporary) { renameSync(temporary, join(this.local(name), 'CURRENT.json')); }
+  commitState(name, temporary) {
+    const { local } = this.storage(name);
+    renameSync(storagePath(this.root, temporary, 'file'), storagePath(this.root, join(local, 'CURRENT.json'), 'file'));
+  }
   async updateLocked(name) {
     const entry = this.entry(name); const runtime = this.runtime(name); const release = validateRelease(name, entry, await this.fetchRelease(name, entry));
+    const { local } = this.storage(name);
+    const target = storagePath(this.root, join(local, 'versions', `${release.version}-${this.target}`), 'directory');
     let installed;
     try { installed = this.check(name); } catch { /* Ausente ou quebrado: reparar em staging. */ }
     if (installed?.version === release.version) { this.launchers(name); return { ...installed, changed: false }; }
-    const local = this.local(name); mkdirSync(join(local, 'versions'), { recursive: true });
-    const stage = mkdtempSync(join(local, '.stage-')); const target = join(local, 'versions', `${release.version}-${this.target}`);
-    const temporary = join(local, `CURRENT.${process.pid}.${Date.now()}.json`); let previous; let moved = false;
+    mkdirSync(storagePath(this.root, join(local, 'versions'), 'directory'), { recursive: true });
+    const stage = mkdtempSync(join(local, '.stage-'));
+    const temporary = storagePath(this.root, join(local, `CURRENT.${randomUUID()}.json`), 'file'); let previous; let moved = false;
     try {
       this.installPackage(stage, entry.download.package, release.version, entry, runtime);
+      this.storage(name); storagePath(this.root, stage, 'directory');
       const pkg = json(join(stage, 'node_modules', entry.download.package, 'package.json')); const lock = json(join(stage, 'package-lock.json'));
       if (pkg.name !== entry.download.package || pkg.version !== release.version || lock.packages?.[`node_modules/${entry.download.package}`]?.integrity !== release.dist.integrity) fail('Pacote instalado nao corresponde ao registro.');
       prepareExecutables(stage, entry, this.target);
       execute(stage, entry, entry.probe, true, entry.probeInput, toolEnvironment(entry, local, runtime), runtime);
+      this.storage(name); storagePath(this.root, target, 'directory');
       const info = { name, package: entry.download.package, version: release.version, platform: this.target, node: runtime.version, nodePath: runtime.file, source: entry.source, tarball: release.dist.tarball, integrity: release.dist.integrity, checkedAt: new Date().toISOString() };
-      writeFileSync(temporary, `${JSON.stringify(info, null, 2)}\n`);
+      writeFileSync(storagePath(this.root, temporary, 'file'), `${JSON.stringify(info, null, 2)}\n`, { flag: 'wx' });
       this.launchers(name);
-      if (existsSync(target)) { previous = `${target}.previous-${process.pid}-${Date.now()}`; renameSync(target, previous); }
-      try { renameSync(stage, target); moved = true; this.commitState(name, temporary); }
-      catch (error) { if (moved) rmSync(target, { recursive: true, force: true }); if (previous) renameSync(previous, target); throw error; }
+      if (existsSync(target)) { previous = storagePath(this.root, `${target}.previous-${randomUUID()}`, 'directory'); renameSync(storagePath(this.root, target, 'directory'), previous); }
+      try { renameSync(storagePath(this.root, stage, 'directory'), storagePath(this.root, target, 'directory')); moved = true; this.commitState(name, temporary); }
+      catch (error) { if (moved) rmSync(storagePath(this.root, target, 'directory'), { recursive: true, force: true }); if (previous) renameSync(storagePath(this.root, previous, 'directory'), storagePath(this.root, target, 'directory')); throw error; }
       return { ...info, layout: 'local', prefix: target, changed: true };
-    } finally { rmSync(stage, { recursive: true, force: true }); rmSync(temporary, { force: true }); }
+    } finally { rmSync(storagePath(this.root, stage, 'directory'), { recursive: true, force: true }); rmSync(storagePath(this.root, temporary, 'file'), { force: true }); }
   }
   run(name, args) { const entry = this.entry(name); const runtime = this.runtime(name); return execute(this.current(name).prefix, entry, args, false, undefined, toolEnvironment(entry, this.local(name), runtime), runtime); }
 }

package/.pbai4devs/scripts/preparar-ferramentas/tests/TEST.mjs

@@ -232,6 +232,87 @@ test('falha ao gravar CURRENT restaura o target anterior e o pacote em uso', asy
   assert.equal(manager.check('test-tool').version, '1.0.0'); assert.ok(!existsSync(join(local, '.update-lock')));
 });
 
+test('versions simbolico existente ou quebrado e recusado antes de baixar ou escrever', async t => {
+  for (const broken of [false, true]) await t.test(broken ? 'broken' : 'existing', async subtest => {
+    const { root, manager, state, local } = fixture(subtest);
+    const outside = join(root, 'outside'); mkdirSync(outside);
+    writeFileSync(join(outside, 'keep.txt'), 'preservado'); mkdirSync(local);
+    if (!createSymlink(subtest, broken ? join(outside, 'missing') : outside, join(local, 'versions'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    for (const action of ['install', 'update']) await assert.rejects(manager[action]('test-tool'), /nao pode ser um link/);
+    assert.equal(state.fetches, 0); assert.equal(state.installs, 0);
+    assert.deepEqual(readdirSync(outside), ['keep.txt']);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    assert.equal(existsSync(join(local, 'CURRENT.json')), false);
+    assert.equal(existsSync(join(local, '.update-lock')), false);
+  });
+});
+
+test('recibo CURRENT e destino de versao simbolicos nao sao seguidos nem substituidos', async t => {
+  for (const kind of ['current', 'target', 'broken-target']) await t.test(kind, async subtest => {
+    const { root, manager, state, local } = fixture(subtest); await manager.install('test-tool');
+    const receipt = readFileSync(join(local, 'CURRENT.json'));
+    const outside = join(root, 'outside'); mkdirSync(outside); writeFileSync(join(outside, 'keep.txt'), 'preservado');
+    if (kind === 'current') {
+      writeFileSync(join(outside, 'CURRENT.json'), receipt); rmSync(join(local, 'CURRENT.json'));
+      if (!createSymlink(subtest, join(outside, 'CURRENT.json'), join(local, 'CURRENT.json'))) return;
+      assert.throws(() => manager.check('test-tool'), /nao pode ser um link/);
+    } else {
+      state.version = '2.0.0';
+      if (!createSymlink(subtest, kind === 'target' ? outside : join(outside, 'missing'), join(local, 'versions', `2.0.0-${platformKey()}`), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    }
+    const before = readdirSync(outside), installs = state.installs;
+    await assert.rejects(manager.update('test-tool'), /nao pode ser um link/);
+    assert.equal(state.installs, installs); assert.deepEqual(readdirSync(outside), before);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    assert.deepEqual(readFileSync(kind === 'current' ? join(outside, 'CURRENT.json') : join(local, 'CURRENT.json')), receipt);
+  });
+});
+
+test('troca de versions durante fetch ou install nao escapa da arvore local', async t => {
+  for (const phase of ['fetch', 'install']) await t.test(phase, async subtest => {
+    const { root, manager, state, local } = fixture(subtest); await manager.install('test-tool');
+    const receipt = readFileSync(join(local, 'CURRENT.json')); state.version = '2.0.0';
+    const outside = join(root, 'outside'); mkdirSync(outside);
+    const probe = join(local, 'symlink-probe');
+    if (!createSymlink(subtest, outside, probe, process.platform === 'win32' ? 'junction' : 'dir')) return;
+    unlinkSync(probe);
+    const versions = join(local, 'versions'), kept = join(local, 'versions-kept'); let linked = false;
+    const replace = () => {
+      renameSync(versions, kept);
+      symlinkSync(outside, versions, process.platform === 'win32' ? 'junction' : 'dir'); linked = true;
+    };
+    if (phase === 'fetch') manager.fetchRelease = async () => { replace(); return release('2.0.0'); };
+    else manager.installPackage = (prefix, name, version) => { packageFiles(prefix, name, version); replace(); };
+    try {
+      await assert.rejects(manager.update('test-tool'), /nao pode ser um link/);
+      assert.deepEqual(readdirSync(outside), []); assert.deepEqual(readFileSync(join(local, 'CURRENT.json')), receipt);
+    } finally { if (linked) { unlinkSync(versions); renameSync(kept, versions); } }
+    assert.equal(manager.check('test-tool').version, '1.0.0');
+    assert.equal(existsSync(join(local, '.update-lock')), false);
+  });
+});
+
+test('migracao recusa links de versions antigo e cache compartilhado sem mover dados', async t => {
+  for (const kind of ['legacy-versions', 'cache']) await t.test(kind, async subtest => {
+    const { root, manager, state } = fixture(subtest);
+    const home = join(root, '.pbai4devs/tools'), legacy = join(home, 'test-tool');
+    const outside = join(root, 'outside'); mkdirSync(outside); writeFileSync(join(outside, 'keep.txt'), 'preservado');
+    if (kind === 'legacy-versions') {
+      writeFileSync(join(legacy, 'CURRENT.json'), JSON.stringify({ name: 'test-tool', version: '1.0.0', platform: platformKey() }));
+      if (!createSymlink(subtest, outside, join(legacy, 'versions'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    } else {
+      mkdirSync(join(home, 'npm-cache')); writeFileSync(join(home, 'npm-cache/keep.txt'), 'cache antigo');
+      if (!createSymlink(subtest, outside, join(home, '.cache'), process.platform === 'win32' ? 'junction' : 'dir')) return;
+    }
+    await assert.rejects(manager.install('test-tool'), /nao pode ser um link/);
+    assert.equal(state.fetches, 0); assert.equal(state.installs, 0);
+    assert.deepEqual(readdirSync(outside), ['keep.txt']);
+    assert.equal(readFileSync(join(outside, 'keep.txt'), 'utf8'), 'preservado');
+    if (kind === 'legacy-versions') assert.ok(existsSync(join(legacy, 'CURRENT.json')));
+    else assert.equal(readFileSync(join(home, 'npm-cache/keep.txt'), 'utf8'), 'cache antigo');
+  });
+});
+
 test('duas atualizacoes nao disputam a mesma ferramenta nem apagam lock alheio', async t => {
   const { manager, state, local } = fixture(t); let enter; let proceed;
   const entered = new Promise(resolve => { enter = resolve; });

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

@@ -1,13 +1,13 @@
 #!/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 { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
 const tomlMarker = '# gerado: sincronizar-agentes';
@@ -113,9 +113,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 && 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();
@@ -237,6 +241,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   function cleanScope(value) {
     if (!stat(safe(value))) return;
+    if (stat(safe(value)).isDirectory() && !scan(value).length) return;
     if (force && value.split('/')[1] === 'external-skills') planRemove(value, true);
     else if (onlyReferences(value)) planRemove(value);
     else if (force) planRemove(value, true);
@@ -410,16 +415,72 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   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 };
   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,21 +494,60 @@ 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));
+  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;
   }
-  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 } : {}) };
 }